Two files, one repository
dotnet/aspnetcore ships 2 formats across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 14 | 0% |
| Commands | 0 | 0 | 13 | 0% |
| Section tags | 0 | 0 | 7 | 0% |
What each file covers
Sections
0 shared · 1 only in A · 14 only in B- − `eng/common`
- + Working on Issues in the Components Area
- + Working on issues
- + Overview
- + Sample Projects
- + Build Tips
- + Efficient Build Strategy
- + Fix a compilation error in Components.Endpoints
- + E2E Testing Structure
- + Running E2E Tests Manually
- + Understanding Logging Configuration
- + Creating E2E Tests
- + Running E2E Tests
- + Build the E2E test project (this includes all test assets as dependencies)
- + Run a specific test
Commands
0 shared · 0 only in A · 13 only in B- + dotnet build --no-restore -v:q
- + dotnet build <path-to-project.csproj> --no-restore --no-dependencies -v:q
- + dotnet build src\Components\Endpoints\src\Microsoft.AspNetCore.Components.Endpoints.csproj --no-restore --no-dependencies -v:q
- + dotnet run --project Components.TestServer.csproj
- + dotnet build src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-restore -v:q
- + dotnet test src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-build --filter "FullyQualifiedName~TestName"
- + git checkout
- + git clean -fd
- + dotnet new blazor
- + git checkout -- src/Components/Samples
- + git clean -df -- src/Components/Samples
- + npm run build
- + dotnet build <project.csproj> --no-restore --no-dependencies -v:q
Section tags
0 shared · 0 only in A · 7 only in B- + build
- + test
- + code-style
- + architecture
- + testing-strategy
- + dependencies
- + do-not
Line diff
dotnet/aspnetcore · eng/common/AGENTS.md
@@ −1 @@
1# `eng/common`
2
3Files under `eng/common` come from [Arcade](https://github.com/dotnet/arcade).
4Edits in `eng/common` will be overwritten by automation unless the changes are made directly in the Arcade repository.
5For more information, see the [Arcade documentation](https://github.com/dotnet/arcade/tree/main/Documentation).
6
dotnet/aspnetcore · src/Components/AGENTS.md
@@ +1 @@
1# Working on Issues in the Components Area
2
3This guide provides step-by-step instructions for working on issues in the ASP.NET Core Components area.
4
5## Working on issues
6
7You MUST follow this workflow when implementing new features or fixing bugs in the Components area.
8* Add the workflow to your `todos` and follow it strictly.
9- Create a sample scenario.
10- If working on a bug, use playwright to reproduce the behavior/problem first.
11- You MUST have reproduced the problem before attempting to fix it.
12- Research the problem area using the microsoft docs, existing code, git history, and logging on the sample project.
13- Implement the fix or feature in the sample project first.
14- Test the fix or feature interactively using Playwright.
15- Once the fix or feature is validated in the sample, implement E2E tests for it.
16 - When you create an E2E test. First execute it interactively with Playwright.
17 - If an E2E test is failing, debug it by running the test server manually and navigating to the scenario in a browser.
18- Only after the E2E tests are passing, remove the sample code you added in the Samples projects.
19 - Use `git checkout` and `git clean -fd` to remove the sample code.
20
21### Overview
22
23The workflow for implementing new features in the Components area follows these steps:
24
251. **Create a sample scenario first** - This is the most important first step. Update code in one of the projects in the `src/Components/Samples` folder to include the scenarios for the feature you want to build. This allows you to develop and test the feature interactively before writing formal tests.
26
272. **Build and test interactively** - Build the feature and use Playwright to test it in the browser, ensuring it works end-to-end at a basic level.
28
29### Sample Projects
30
31The `src/Components/Samples` folder contains canonical Blazor Web App samples, and `src/Components/WebAssembly/Samples` contains a standalone WebAssembly sample, that you can use for developing and testing features. All are generated from the `dotnet new blazor`/`blazorwasm` templates with `Auto` interactivity and adapted to reference the in-tree framework:
32
33- **BlazorWebAppGlobal** (+ **.Client**) - A Blazor Web App with **global** interactivity (`@rendermode="InteractiveAuto"` on `Routes`/`HeadOutlet` in `App.razor`). Change that one value to `InteractiveServer`/`InteractiveWebAssembly` to test the whole app on a single platform.
34- **BlazorWebAppPerPage** (+ **.Client**) - A Blazor Web App with **per-page** interactivity. Apply `@rendermode` per page/component (`InteractiveServer`/`InteractiveWebAssembly`/`InteractiveAuto`), mix modes, or omit it for static SSR.
35- **BlazorWebAssemblyStandalone** - A standalone Blazor WebAssembly app (no server host), under `src/Components/WebAssembly/Samples`.
36
37Together these cover every interactivity platform (Server/WebAssembly/Auto/None) and location (Global/Per-page) by editing a single `@rendermode` rather than restructuring.
38
39**Always start by adding your feature scenario to whichever sample matches the render mode you need.** This allows you to:
40- Quickly iterate on the implementation
41- Test the feature interactively in a real browser
42- Verify the feature works before writing formal E2E tests
43- Debug issues more easily with full logging capabilities
44
453. **Debug when needed**:
46 - If something isn't working as expected, increase the logging level in the sample for `Microsoft.AspNetCore.Components` to `Debug` to see detailed logs.
47 - Check browser console logs using Playwright's `browser_console_messages`.
48 - Use Microsoft documentation to learn more about troubleshooting Blazor applications.
49 - You can also increase the log level for JavaScript console output.
50
514. **Validate the sample works** - You must have a validated, working sample in the Samples folder before proceeding. Use Playwright to confirm the feature works end-to-end in the browser.
52
535. **Implement E2E tests** - Only after the sample is validated, implement E2E tests for it.
54
556. **Clean up sample code** - After your E2E tests are passing, remove the sample code you added to the Samples projects. The sample was only for development and interactive testing; the E2E tests now provide the permanent test coverage. Use `git checkout -- src/Components/Samples` and `git clean -df -- src/Components/Samples` to remove the sample code.
56
57## Build Tips
58
59### Efficient Build Strategy
60
61To avoid unnecessary full repository builds, follow this optimized approach:
62
63#### 1. Initial Setup - Check for First Build
64Before running any commands, check if a full build has already been completed:
65- Look for `artifacts\agent-sentinel.txt` in the repository root
66- If this file exists, skip to step 2
67- If not present, run the initial build and create the sentinel file:
68
69```bash
70.\eng\build.cmd
71echo "We ran eng\build.cmd successfully" > artifacts\agent-sentinel.txt
72```
73
74#### 2. Check for JavaScript Assets
75Before running tests or samples, verify that JavaScript assets are built:
76- Check for `src\Components\Web.JS\dist\Debug\blazor.web.js`
77- If not present, run from the repository root: `npm run build`
78
79#### 3. Iterating on C# Changes
80
81**Most of the time (no dependency changes):**
82```bash
83dotnet build --no-restore -v:q
84```
85
86Or with `eng\build.cmd`:
87```bash
88.\eng\build.cmd -NoRestore -NoBuildDeps -NoBuildNative -NoBuildNodeJS -NoBuildJava -NoBuildInstallers -verbosity:quiet
89```
90
91**When you've added/changed project references or package dependencies:**
92
93First restore:
94```bash
95.\restore.cmd
96```
97
98Then build:
99```bash
100dotnet build --no-restore -v:q
101```
102
103**Note:** The `-v:q` (or `-verbosity:quiet`) flag minimizes build output to only show success/failure and error details. Remove this flag if you need to see detailed build output for debugging.
104
105#### 4. Building Individual Projects (Fixing Build Errors)
106
107When fixing build errors in a specific project, you can build just that project without its dependencies for even faster iteration:
108
109```bash
110dotnet build <path-to-project.csproj> --no-restore --no-dependencies -v:q
111```
112
113**When to use `--no-dependencies`:**
114- Fixing compilation errors in a single project (syntax errors, type errors, etc.)
115- Making isolated changes that don't affect project references
116- Rapid iteration on a specific library
117
118**When NOT to use `--no-dependencies`:**
119- You've changed public APIs that other projects depend on
120- You need to verify that dependent projects still compile correctly
121- You're unsure if your changes affect other projects (safer to build without this flag)
122
123**Example:**
124```bash
125# Fix a compilation error in Components.Endpoints
126dotnet build src\Components\Endpoints\src\Microsoft.AspNetCore.Components.Endpoints.csproj --no-restore --no-dependencies -v:q
127```
128
129#### Quick Reference
130
1311. **First time only**: `.\eng\build.cmd` → create `artifacts\agent-sentinel.txt`
1322. **Check JS assets**: Verify `src\Components\Web.JS\dist\Debug\blazor.web.js` exists, run `npm run build` if missing
1333. **Most C# changes**: `dotnet build --no-restore -v:q`
1344. **Fixing build errors in one project**: `dotnet build <project.csproj> --no-restore --no-dependencies -v:q`
1355. **Added/changed dependencies**: Run `.\restore.cmd` first, then use step 3
136
137### E2E Testing Structure
138
139Tests live in `src/Components/test`. The structure includes:
140
141- **testassets folder** - Contains test assets and scenarios
142- **Components.TestServer project** - A web application that launches multiple web servers with different scenarios (different project startups). Avoid adding new startup files unless strictly necessary.
143
144### Running E2E Tests Manually
145
1461. **Build the tests**: Follow the build instructions to build the E2E test project and its dependencies.
1472. **Start Components.TestServer**:
148 ```bash
149 cd src\Components\test\testassets\Components.TestServer
150 dotnet run --project Components.TestServer.csproj
151 ```
1523. **Navigate to the test server** - The main server runs on `http://127.0.0.1:5019/subdir`
1534. **Select a test scenario** - The main page shows a dropdown with all available test components
1545. **Reproduce the scenario** to verify it works the same way as in the sample
155
156Note: There are also other server instances launched for different test configurations (authentication, CORS, prerendering, etc.). These are listed in the "scenarios" table on the main page.
157
158### Understanding Logging Configuration
159
160#### Server-side (.NET) Logging
161
162The server uses `Microsoft.Extensions.Logging.Testing.TestSink` for capturing logs. Log configuration is in `Program.cs`:
163
164```csharp
165.ConfigureLogging((ctx, lb) =>
166{
167 TestSink sink = new TestSink();
168 lb.AddProvider(new TestLoggerProvider(sink));
169 lb.Services.Add(ServiceDescriptor.Singleton(sink));
170})
171```
172
173#### Client-side (Blazor WebAssembly) Logging
174
175Logs appear in the browser console. Log levels:
176- Logs with `warn:` prefix are Warning level
177- Logs with `info:` prefix are Information level
178- Logs with `fail:` prefix are Error level
179
180The Blazor WebAssembly log level can be configured at startup:
181
182```javascript
183Blazor.start({
184 logLevel: 1 // LogLevel.Debug
185});
186```
187
188LogLevel values: Trace=0, Debug=1, Information=2, Warning=3, Error=4, Critical=5
189
190For Server-side Blazor (SignalR):
191```javascript
192Blazor.start({
193 circuit: {
194 configureSignalR: builder => {
195 builder.configureLogging("debug") // LogLevel.Debug
196 }
197 }
198});
199```
200
201#### Viewing Logs in Playwright
202
203Use `browser_console_messages` to see JavaScript console output including .NET logs routed to the console.
204
205### Creating E2E Tests
206
207E2E tests are located in `src/Components/test/E2ETest`.
208
2091. First, check if there are already E2E tests for the component/feature area you're working on
2102. Try to add an additional test to existing test files when possible
2113. When adding test coverage, prefer extending existing test components and assets over creating a set of new ones if it doesn't complicate the existing ones excessively. This reduces test infrastructure complexity and keeps related scenarios together.
212
213### Running E2E Tests
214
215The E2E tests use Selenium. To build and run tests:
216
217```bash
218# Build the E2E test project (this includes all test assets as dependencies)
219dotnet build src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-restore -v:q
220
221# Run a specific test
222dotnet test src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-build --filter "FullyQualifiedName~TestName"
223```
224
225**Important**: Never run all E2E tests locally as that is extremely costly. Full test runs should only happen on CI machines.
226
227If a test is failing, it's best to run the server manually and navigate to the test to investigate. The test output won't be very useful for debugging.
228
229
@@ −1 +1 @@
1−# `eng/common`
1+# Working on Issues in the Components Area
22
3−Files under `eng/common` come from [Arcade](https://github.com/dotnet/arcade).
4−Edits in `eng/common` will be overwritten by automation unless the changes are made directly in the Arcade repository.
5−For more information, see the [Arcade documentation](https://github.com/dotnet/arcade/tree/main/Documentation).
3+This guide provides step-by-step instructions for working on issues in the ASP.NET Core Components area.
4+
5+## Working on issues
6+
7+You MUST follow this workflow when implementing new features or fixing bugs in the Components area.
8+* Add the workflow to your `todos` and follow it strictly.
9+- Create a sample scenario.
10+- If working on a bug, use playwright to reproduce the behavior/problem first.
11+- You MUST have reproduced the problem before attempting to fix it.
12+- Research the problem area using the microsoft docs, existing code, git history, and logging on the sample project.
13+- Implement the fix or feature in the sample project first.
14+- Test the fix or feature interactively using Playwright.
15+- Once the fix or feature is validated in the sample, implement E2E tests for it.
16+ - When you create an E2E test. First execute it interactively with Playwright.
17+ - If an E2E test is failing, debug it by running the test server manually and navigating to the scenario in a browser.
18+- Only after the E2E tests are passing, remove the sample code you added in the Samples projects.
19+ - Use `git checkout` and `git clean -fd` to remove the sample code.
20+
21+### Overview
22+
23+The workflow for implementing new features in the Components area follows these steps:
24+
25+1. **Create a sample scenario first** - This is the most important first step. Update code in one of the projects in the `src/Components/Samples` folder to include the scenarios for the feature you want to build. This allows you to develop and test the feature interactively before writing formal tests.
26+
27+2. **Build and test interactively** - Build the feature and use Playwright to test it in the browser, ensuring it works end-to-end at a basic level.
28+
29+### Sample Projects
30+
31+The `src/Components/Samples` folder contains canonical Blazor Web App samples, and `src/Components/WebAssembly/Samples` contains a standalone WebAssembly sample, that you can use for developing and testing features. All are generated from the `dotnet new blazor`/`blazorwasm` templates with `Auto` interactivity and adapted to reference the in-tree framework:
32+
33+- **BlazorWebAppGlobal** (+ **.Client**) - A Blazor Web App with **global** interactivity (`@rendermode="InteractiveAuto"` on `Routes`/`HeadOutlet` in `App.razor`). Change that one value to `InteractiveServer`/`InteractiveWebAssembly` to test the whole app on a single platform.
34+- **BlazorWebAppPerPage** (+ **.Client**) - A Blazor Web App with **per-page** interactivity. Apply `@rendermode` per page/component (`InteractiveServer`/`InteractiveWebAssembly`/`InteractiveAuto`), mix modes, or omit it for static SSR.
35+- **BlazorWebAssemblyStandalone** - A standalone Blazor WebAssembly app (no server host), under `src/Components/WebAssembly/Samples`.
36+
37+Together these cover every interactivity platform (Server/WebAssembly/Auto/None) and location (Global/Per-page) by editing a single `@rendermode` rather than restructuring.
38+
39+**Always start by adding your feature scenario to whichever sample matches the render mode you need.** This allows you to:
40+- Quickly iterate on the implementation
41+- Test the feature interactively in a real browser
42+- Verify the feature works before writing formal E2E tests
43+- Debug issues more easily with full logging capabilities
44+
45+3. **Debug when needed**:
46+ - If something isn't working as expected, increase the logging level in the sample for `Microsoft.AspNetCore.Components` to `Debug` to see detailed logs.
47+ - Check browser console logs using Playwright's `browser_console_messages`.
48+ - Use Microsoft documentation to learn more about troubleshooting Blazor applications.
49+ - You can also increase the log level for JavaScript console output.
50+
51+4. **Validate the sample works** - You must have a validated, working sample in the Samples folder before proceeding. Use Playwright to confirm the feature works end-to-end in the browser.
52+
53+5. **Implement E2E tests** - Only after the sample is validated, implement E2E tests for it.
54+
55+6. **Clean up sample code** - After your E2E tests are passing, remove the sample code you added to the Samples projects. The sample was only for development and interactive testing; the E2E tests now provide the permanent test coverage. Use `git checkout -- src/Components/Samples` and `git clean -df -- src/Components/Samples` to remove the sample code.
56+
57+## Build Tips
58+
59+### Efficient Build Strategy
60+
61+To avoid unnecessary full repository builds, follow this optimized approach:
62+
63+#### 1. Initial Setup - Check for First Build
64+Before running any commands, check if a full build has already been completed:
65+- Look for `artifacts\agent-sentinel.txt` in the repository root
66+- If this file exists, skip to step 2
67+- If not present, run the initial build and create the sentinel file:
68+
69+```bash
70+.\eng\build.cmd
71+echo "We ran eng\build.cmd successfully" > artifacts\agent-sentinel.txt
72+```
73+
74+#### 2. Check for JavaScript Assets
75+Before running tests or samples, verify that JavaScript assets are built:
76+- Check for `src\Components\Web.JS\dist\Debug\blazor.web.js`
77+- If not present, run from the repository root: `npm run build`
78+
79+#### 3. Iterating on C# Changes
80+
81+**Most of the time (no dependency changes):**
82+```bash
83+dotnet build --no-restore -v:q
84+```
85+
86+Or with `eng\build.cmd`:
87+```bash
88+.\eng\build.cmd -NoRestore -NoBuildDeps -NoBuildNative -NoBuildNodeJS -NoBuildJava -NoBuildInstallers -verbosity:quiet
89+```
90+
91+**When you've added/changed project references or package dependencies:**
92+
93+First restore:
94+```bash
95+.\restore.cmd
96+```
97+
98+Then build:
99+```bash
100+dotnet build --no-restore -v:q
101+```
102+
103+**Note:** The `-v:q` (or `-verbosity:quiet`) flag minimizes build output to only show success/failure and error details. Remove this flag if you need to see detailed build output for debugging.
104+
105+#### 4. Building Individual Projects (Fixing Build Errors)
106+
107+When fixing build errors in a specific project, you can build just that project without its dependencies for even faster iteration:
108+
109+```bash
110+dotnet build <path-to-project.csproj> --no-restore --no-dependencies -v:q
111+```
112+
113+**When to use `--no-dependencies`:**
114+- Fixing compilation errors in a single project (syntax errors, type errors, etc.)
115+- Making isolated changes that don't affect project references
116+- Rapid iteration on a specific library
117+
118+**When NOT to use `--no-dependencies`:**
119+- You've changed public APIs that other projects depend on
120+- You need to verify that dependent projects still compile correctly
121+- You're unsure if your changes affect other projects (safer to build without this flag)
122+
123+**Example:**
124+```bash
125+# Fix a compilation error in Components.Endpoints
126+dotnet build src\Components\Endpoints\src\Microsoft.AspNetCore.Components.Endpoints.csproj --no-restore --no-dependencies -v:q
127+```
128+
129+#### Quick Reference
130+
131+1. **First time only**: `.\eng\build.cmd` → create `artifacts\agent-sentinel.txt`
132+2. **Check JS assets**: Verify `src\Components\Web.JS\dist\Debug\blazor.web.js` exists, run `npm run build` if missing
133+3. **Most C# changes**: `dotnet build --no-restore -v:q`
134+4. **Fixing build errors in one project**: `dotnet build <project.csproj> --no-restore --no-dependencies -v:q`
135+5. **Added/changed dependencies**: Run `.\restore.cmd` first, then use step 3
136+
137+### E2E Testing Structure
138+
139+Tests live in `src/Components/test`. The structure includes:
140+
141+- **testassets folder** - Contains test assets and scenarios
142+- **Components.TestServer project** - A web application that launches multiple web servers with different scenarios (different project startups). Avoid adding new startup files unless strictly necessary.
143+
144+### Running E2E Tests Manually
145+
146+1. **Build the tests**: Follow the build instructions to build the E2E test project and its dependencies.
147+2. **Start Components.TestServer**:
148+ ```bash
149+ cd src\Components\test\testassets\Components.TestServer
150+ dotnet run --project Components.TestServer.csproj
151+ ```
152+3. **Navigate to the test server** - The main server runs on `http://127.0.0.1:5019/subdir`
153+4. **Select a test scenario** - The main page shows a dropdown with all available test components
154+5. **Reproduce the scenario** to verify it works the same way as in the sample
155+
156+Note: There are also other server instances launched for different test configurations (authentication, CORS, prerendering, etc.). These are listed in the "scenarios" table on the main page.
157+
158+### Understanding Logging Configuration
159+
160+#### Server-side (.NET) Logging
161+
162+The server uses `Microsoft.Extensions.Logging.Testing.TestSink` for capturing logs. Log configuration is in `Program.cs`:
163+
164+```csharp
165+.ConfigureLogging((ctx, lb) =>
166+{
167+ TestSink sink = new TestSink();
168+ lb.AddProvider(new TestLoggerProvider(sink));
169+ lb.Services.Add(ServiceDescriptor.Singleton(sink));
170+})
171+```
172+
173+#### Client-side (Blazor WebAssembly) Logging
174+
175+Logs appear in the browser console. Log levels:
176+- Logs with `warn:` prefix are Warning level
177+- Logs with `info:` prefix are Information level
178+- Logs with `fail:` prefix are Error level
179+
180+The Blazor WebAssembly log level can be configured at startup:
181+
182+```javascript
183+Blazor.start({
184+ logLevel: 1 // LogLevel.Debug
185+});
186+```
187+
188+LogLevel values: Trace=0, Debug=1, Information=2, Warning=3, Error=4, Critical=5
189+
190+For Server-side Blazor (SignalR):
191+```javascript
192+Blazor.start({
193+ circuit: {
194+ configureSignalR: builder => {
195+ builder.configureLogging("debug") // LogLevel.Debug
196+ }
197+ }
198+});
199+```
200+
201+#### Viewing Logs in Playwright
202+
203+Use `browser_console_messages` to see JavaScript console output including .NET logs routed to the console.
204+
205+### Creating E2E Tests
206+
207+E2E tests are located in `src/Components/test/E2ETest`.
208+
209+1. First, check if there are already E2E tests for the component/feature area you're working on
210+2. Try to add an additional test to existing test files when possible
211+3. When adding test coverage, prefer extending existing test components and assets over creating a set of new ones if it doesn't complicate the existing ones excessively. This reduces test infrastructure complexity and keeps related scenarios together.
212+
213+### Running E2E Tests
214+
215+The E2E tests use Selenium. To build and run tests:
216+
217+```bash
218+# Build the E2E test project (this includes all test assets as dependencies)
219+dotnet build src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-restore -v:q
220+
221+# Run a specific test
222+dotnet test src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-build --filter "FullyQualifiedName~TestName"
223+```
224+
225+**Important**: Never run all E2E tests locally as that is extremely costly. Full test runs should only happen on CI machines.
226+
227+If a test is failing, it's best to run the server manually and navigate to the test to investigate. The test output won't be very useful for debugging.
228+
6229
