Skip to content

Update README for Components directory #27650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
4 commits merged into from
Nov 13, 2020
Merged

Update README for Components directory #27650

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ec885b4
Update README for Components directory
captainsafia Nov 9, 2020
a49fc19
Update src/Components/README.md
captainsafia Nov 11, 2020
391d5ca
Address feedback from peer review
captainsafia Nov 11, 2020
c8da724
Use new top-level references for build
captainsafia Nov 11, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 43 additions & 8 deletions src/Components/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,52 @@
# Blazor

**Build modern, interactive web-based UIs with C# and Razor.**
Blazor is a framework for building modern, interactive web-based UIs with C# and Razor. For more information on using Blazor to build apps, check out [the official docs](https://blazor.net).

This folder contains the underlying *components* programming model that powers both server-side and client-side [Blazor](#blazor) applications.
## Description

Blazor is a component based web UI framework. Blazor apps can run client-side in browser on WebAssembly or server-side as part of an ASP.NET Core app. Blazor is a full single-page application (SPA) framework inspired by the latest JavaScript SPA frameworks, featuring support for offline/PWA applications, app size trimming, and browser-based debugging.
This folder contains the component model shared between the WebAssembly and Server hosting models for Blazor.

Blazor uses only the latest web standards. No plugins or transpilation needed. It runs in the browser on a real .NET runtime implemented in [WebAssembly](http://webassembly.org) that executes normal .NET assemblies.
The following contains a description of each sub-directory in the `Components` directory.

[![Gitter](https://badges.gitter.im/aspnet/blazor.svg)](https://gitter.im/aspnet/blazor?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
- `Analyzers`: Contains a collection of Rosyln analyzers for Blazor components
- `Authorization`: Contains source files associated with auth-related components and services in Blazor
- `Components`: Contains the implementation for the Blazor component model
- `Forms`: Contains source files for Form components in Blazor
- `Ignitor`: A library for testing Blazor Server apps
- `Samples`: Contains a collection of sample apps in Blazor
- `Server`: Contains the implementation for Blazor Server-specific components
- `Shared`: Contains a collection of shared constants and helper methods/classes
- `Web`: Contains source files for handling DOM events, forms, and other components
- `Web.JS`: Contains the source files for Blazor's client-side JavaScript
- `WebAssembly`: Contains the implementation for WebAssembly-specific components

You can learn more about Blazor at https://blazor.net.
## Development Setup

## Getting Started
### Build

To get started with Blazor and build your first web app check out our [getting started guide](https://go.microsoft.com/fwlink/?linkid=870449).
This project takes a dependency on MVC and SignalR packages. In order to build this project and its dependencies, run the following command inside this directory.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about adding a general section to BuildFromSources.md that talks about how to build "sub-folders" and linking from here?

Each directory under src represents a feature area of ASP.NET Core. We provide convenience scripts build.sh or build.cmd inside these directories that let you build and test only this feature. For instance, if you were interested in contributing to Blazor, navigate to the src/Components directory, and run build.[cmd|sh] there to build all the projects and it's dependencies.

Then we link to these instructions from each of these docs. so we're not repeating ourselves?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This project takes a dependency on MVC and SignalR packages.

Ehh, these things are easy to go out of sync and don't really help the user much. Could we not list this here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then we link to these instructions from each of these docs. so we're not repeating ourselves?

Good insight. I think we can probably address this for all the projects in one go as part of #27631.

Ehh, these things are easy to go out of sync and don't really help the user much. Could we not list this here?

I've removed it.


```powershell
> ./build.cmd
```

Or on MacOS or Linux:

```bash
$ ./build.sh
```

### Test

This project contains a collection of unit tests implemented with XUnit and E2E tests implemented using Selenium. In order to run the E2E tests, you will need to have Selenium installed on your machine.

The E2E tests are located in the top-level `tests` folder in this directory. The E2E tests consists of a top-level `TestServer` which instantiates different app servers for specific scenarios:

- Standalone Blazor WASM
- Hosted Blazor WASM
- Blazor Server
- Blazor Server with pre-rendering

Each app server mounts the same `BasicTestApp` application under each scenario.

Project-specific tests are located in each project under the `tests` directory and can be run with `dotnet test`.