[Blazor] Replace DevServer with BlazorGateway for standalone WASM apps by javiercn · Pull Request #65982 · dotnet/aspnetcore

javiercn · 2026-03-25T23:01:47Z

Summary

Introduces Microsoft.AspNetCore.Components.Gateway — a lightweight ASP.NET Core host that replaces the DevServer for serving standalone Blazor WebAssembly applications during development and production.

Changes

New: Gateway project (`src/Components/Gateway/src/`)

BlazorGateway.cs — Static BuildWebHost(string[] args) method configurable in two modes:
- Standalone mode: Derives static web asset manifest paths from --applicationpath CLI arg (used by dotnet run and E2E tests)
- Aspire mode: Reads ClientApps config section for multiple client apps, YARP reverse proxy, config endpoints
Program.cs — Entry point that calls BlazorGateway.BuildWebHost(args).Run()
MSBuild targets (build/Microsoft.AspNetCore.Components.Gateway.targets) — Imported by WASM projects to override dotnet run behavior: sets _WebAssemblyUserRunParameters=true, resolves manifest paths via ComputeRunArguments
SpaFallback.targets — Temporary target that adds {**path:nonfile} catch-all endpoint to the static web assets endpoints manifest (clones identity index.html endpoint)

Updated: E2E test infrastructure

BlazorWasmTestAppFixture now calls BlazorGateway.BuildWebHost() instead of DevServer
Components.TestServer includes BlazorGateway.cs as shared source and uses it for the "Dev server client-side blazor" scenario
YARP packages added via the repo's <Reference> pattern (eng/Versions.props + eng/Dependencies.props)
SpaFallback.targets imported into BasicTestApp, ThreadingApp, and Wasm.Performance.TestApp

Key design decisions

YARP baked in — No conditional compilation; the Gateway always supports reverse proxy for future Aspire integration
Shared source via <Compile Include> — BlazorGateway.cs is included in test projects as source rather than referenced as a project, avoiding assembly conflicts with the test host's Program class
_RemoveTransitiveAspNetCoreFrameworkReference target — In TestServer, removes YARP's transitive FrameworkReference to Microsoft.AspNetCore.App after AddTransitiveFrameworkReferences but before ResolveTargetingPackAssets

Testing

E2E test validation in progress across 5 waves:

Wave 1 (smoke): StandaloneAppTest.HasTitle, HasHeading, BasicTestAppCanBeServed ✅
Wave 2 (BlazorWasmTestAppFixture): All 20 tests ✅
Wave 3-5: Core rendering, events, forms, remaining — in progress

javiercn · 2026-03-26T10:21:32Z

This is temporary until an SDK with the functionality flows here

javiercn · 2026-03-26T10:22:01Z

Temporary until the SDK update flows to asp.net core

Copilot

Pull request overview

This PR replaces the Blazor WebAssembly DevServer with a new Microsoft.AspNetCore.Components.Gateway host for serving standalone WASM apps in development/testing, and updates test/benchmark assets to use the new Gateway (including SPA fallback routing via static web assets endpoints).

Changes:

Adds a new Gateway project (Microsoft.AspNetCore.Components.Gateway) with a BlazorGateway.BuildWebHost(args) entrypoint and dotnet run integration via MSBuild targets.
Updates Components test infrastructure (E2E + Components.TestServer) to start the Gateway instead of DevServer and passes static web assets manifests explicitly.
Introduces a temporary SpaFallback.targets imported by multiple WASM test apps to add a {**path:nonfile} SPA fallback endpoint.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/WebAssembly/testassets/SpaFallback.targets	New MSBuild targets to inject SPA fallback static web asset endpoint.
src/Components/test/testassets/GlobalizationWasmApp/GlobalizationWasmApp.csproj	Imports SPA fallback targets for this test asset.
src/Components/test/testassets/Components.TestServer/Program.cs	Switches dev-host scenario to use `BlazorGateway` and passes manifests via args.
src/Components/test/testassets/Components.TestServer/Components.TestServer.csproj	Uses shared-source `BlazorGateway.cs`, adds YARP refs, and removes transitive framework ref.
src/Components/test/testassets/BasicTestApp/BasicTestApp.csproj	Imports SPA fallback targets.
src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj	Normalizes project file header/encoding.
src/Components/test/E2ETest/Infrastructure/ServerFixtures/BlazorWasmTestAppFixture.cs	Uses `BlazorGateway` and passes static web assets manifests to host.
src/Components/benchmarkapps/Wasm.Performance/TestApp/Wasm.Performance.TestApp.csproj	Imports SPA fallback targets for benchmark app.
src/Components/WebAssembly/testassets/ThreadingApp/ThreadingApp.csproj	Imports SPA fallback targets.
src/Components/WebAssembly/testassets/StandaloneApp/StandaloneApp.csproj	Imports Gateway run targets and SPA fallback; sets Gateway DLL location override.
src/Components/WebAssembly/testassets/SpaFallback.targets	New MSBuild targets to inject SPA fallback static web asset endpoint (Components copy).
src/Components/Gateway/src/build/Microsoft.AspNetCore.Components.Gateway.targets	Overrides `dotnet run` args for WASM projects to launch Gateway with manifest paths.
src/Components/Gateway/src/blazor-gateway.runtimeconfig.json.in	Adds runtimeconfig template for the packaged Gateway tool.
src/Components/Gateway/src/Program.cs	Gateway entrypoint calling `BlazorGateway.BuildWebHost(args).Run()`.
src/Components/Gateway/src/Microsoft.AspNetCore.Components.Gateway.nuspec	Packages Gateway tool + build targets into the shipping NuGet package.
src/Components/Gateway/src/Microsoft.AspNetCore.Components.Gateway.csproj	New shipping project (Web SDK) with YARP/service-discovery references and pack settings.
src/Components/Gateway/src/BlazorGateway.cs	Implements Gateway host setup: static web assets, optional YARP proxy, app config endpoints, and static assets mapping per client app.
eng/Versions.props	Adds version properties for YARP + service discovery packages.
eng/Dependencies.props	Adds YARP + service discovery packages to dependency tracking.

javiercn · 2026-03-29T14:28:38Z

+        // SPA fallback: serve index.html for any non-file URL path, similar to
+        // the old DevServer's MapFallbackToFile("index.html"). This is registered
+        // after MapStaticAssets so that specific static file routes take precedence.
+        app.MapFallbackToFile("index.html");


This is until we get fallbacks on the SDK

ScarletKuro · 2026-04-04T19:01:23Z

Does this replaces the old wasm standalone + co-host with ASP.NET core scenario?
If yes, I hope the OverrideHtmlAssetPlaceholders will work out of the box, because with the old one it doesn't dotnet/runtime#121993 (comment) unless you copy client's wwwroot to server's wwwroot upd: answers were given on Blazor Community Standup

ilonatommy

initial pass

ilonatommy

Ready for shipping after merge conflicts resolving and one more nit.

- Single Program.cs with top-level statements, pure config-driven - Supports standalone (MSBuild targets) and Aspire (env vars/YARP) - Gateway targets: _WebAssemblyUserRunParameters to skip WasmAppHost, AfterTargets ComputeRunArguments with ResolveStaticWebAssetsConfiguration to resolve manifest paths via Path.Combine(MSBuildProjectDirectory) - Temporary SpaFallback.targets in testassets: pure MSBuild target that clones identity index.html endpoint as {**path:nonfile} catch-all (replaces inline C# task, will be removed when SDK ships StaticWebAssetSpaFallbackEnabled) - Update StandaloneApp.csproj to import Gateway + SpaFallback targets

- Extract BlazorGateway.BuildWebHost() into BlazorGateway.cs (shared source) - Update Components.TestServer and BlazorWasmTestAppFixture to use BlazorGateway - Add YARP packages (Yarp.ReverseProxy, ServiceDiscovery) via repo's <Reference> pattern - Add SpaFallback.targets to BasicTestApp, ThreadingApp, and Wasm.Performance.TestApp - Remove Program.BuildWebHost.cs Compile Include from E2ETests (gets it via TestServer ref)

Pass explicit --staticWebAssets, --ClientApps:app:EndpointsManifest, and --ClientApps:app:PathPrefix arguments from call sites instead of deriving manifest paths inside BlazorGateway. Add SpaFallback.targets to GlobalizationWasmApp.

SpaFallback.targets added a {**path:nonfile} catch-all to BasicTestApp's endpoint manifest, which propagated to Components.TestServer. MapStaticAssets hardcodes Order=-100 on all endpoints, giving the catch-all higher priority than Razor component routes (Order=0), causing all non-file URLs to serve index.html instead of server-rendered pages. - Remove SpaFallback.targets import from BasicTestApp.csproj - Replace the .Add() Order-override in BlazorGateway with MapFallbackToFile, matching the old DevServer approach

…Fallback.targets

- Add Microsoft.Extensions.ServiceDiscovery and Microsoft.Extensions.ServiceDiscovery.Yarp to Version.Details.xml so Maestro auto-updates them from dotnet/extensions. - Add version property mappings in Version.Details.props. - Remove duplicate manual version entries from Versions.props. - Update ServiceDiscovery packages from 9.2.0 to 10.4.1. - Yarp.ReverseProxy remains as a manual external dependency. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ails.props The Maestro-managed PackageVersion definitions were missing from the auto-generated section, causing NU1015 (no version specified) errors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…gets comment - Fix tfm in blazor-gateway.runtimeconfig.json.in from net10.0 to net11.0 - Add _CreateRuntimeConfig target to Gateway csproj (port from DevServer) so the .in template is processed via GenerateFileFromTemplate - Add GenerateRuntimeConfigurationFiles=false to use our custom template - Add XML comment explaining _WebAssemblyUserRunParameters in Gateway.targets Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…view Demonstrates hosting a standalone Blazor WASM app behind the new Blazor Gateway (PR dotnet/aspnetcore#65982) instead of the legacy Blazor Dev Server: - ClientApps:app:EndpointsManifest serves WASM static assets - ReverseProxy section uses YARP to proxy /api/* to the Backend project - ClientApps:app:ConfigEndpointPath returns inline JSON config to the client - Service discovery via AddServiceDiscovery + AddServiceDiscoveryDestinationResolver The local Gateway project mirrors the upstream BlazorGateway.BuildWebHost. When Microsoft.AspNetCore.Components.Gateway ships, replace it with a single PackageReference in Client.csproj (in place of the DevServer reference). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Documents how to opt in to the new Blazor Gateway (PR dotnet/aspnetcore#65982) in a standalone Blazor WebAssembly app: swapping the DevServer reference for Microsoft.AspNetCore.Components.Gateway, configuring YARP proxying to backend APIs, and exposing a runtime config endpoint to the client. Links to the GatewayDemo sample in danroth27/AspNetCore11Samples for an end-to-end setup. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Drop Microsoft.AspNetCore.Components.WebAssembly.DevServer reference. - Add a top-level Gateway/ project (local stand-in for the upcoming Microsoft.AspNetCore.Components.Gateway package, dotnet/aspnetcore#65982). - Add a top-level BackendApi/ project (minimal /weather endpoint) so the Blazor app can demonstrate the Gateway's YARP proxying support. - Wire up Weather.razor to call /api/weather (proxied through the Gateway to BackendApi) instead of the static sample-data/weather.json. - Add Pages/AppConfig.razor demonstrating the Gateway's config endpoint: the Gateway returns inline JSON from /_app/config (banner text + feature flags + environment) and the page renders it. - Drop the GatewayDemo/ subdirectory it replaces. - Drop AddServiceDiscovery / AddServiceDiscoveryDestinationResolver from the Gateway: these are an Aspire-style integration and aren't needed when YARP destinations use plain absolute URLs. - Replace MapFallbackToFile (requires WebRoot, which the Gateway has none of) with a MapFallback that resolves /index.html from the static-asset endpoint manifest, so SPA routes return 200. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions Bot added the area-blazor Includes: Blazor, Razor Components label Mar 25, 2026

javiercn marked this pull request as ready for review March 26, 2026 10:19

javiercn requested review from a team and wtgodbe as code owners March 26, 2026 10:19

Copilot AI review requested due to automatic review settings March 26, 2026 10:19

Copilot started reviewing on behalf of javiercn March 26, 2026 10:20 View session

javiercn commented Mar 26, 2026

View reviewed changes

Copilot AI reviewed Mar 26, 2026

View reviewed changes

javiercn force-pushed the javiercn/blazor-gateway branch from 3576550 to 11863e3 Compare March 28, 2026 15:11

build-analysis Bot mentioned this pull request Mar 28, 2026

Sometimes the helix SDK uses GetWorkItemsAsync when workitems aren't done processing. dotnet/dnceng#6011

Open

3 tasks

javiercn force-pushed the javiercn/blazor-gateway branch from 11863e3 to faab532 Compare March 29, 2026 13:06

javiercn commented Mar 29, 2026

View reviewed changes

javiercn force-pushed the javiercn/blazor-gateway branch 2 times, most recently from 4fe2b05 to b9e014d Compare April 12, 2026 09:07

ilonatommy reviewed Apr 14, 2026

View reviewed changes

Comment thread src/Components/Gateway/src/build/Microsoft.AspNetCore.Components.Gateway.targets

Comment thread src/Components/Gateway/src/build/Microsoft.AspNetCore.Components.Gateway.targets

ilonatommy reviewed Apr 14, 2026

View reviewed changes

Comment thread src/Components/Gateway/src/blazor-gateway.runtimeconfig.json.in Outdated

Comment thread src/Components/Gateway/src/build/Microsoft.AspNetCore.Components.Gateway.targets

Comment thread src/Components/Gateway/src/blazor-gateway.runtimeconfig.json.in

ilonatommy approved these changes Apr 16, 2026

View reviewed changes

Comment thread src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj Outdated

ilonatommy assigned javiercn Apr 16, 2026

javiercn and others added 6 commits April 16, 2026 10:58

Remove --applicationpath parsing from BlazorGateway

645e6ad

Pass explicit --staticWebAssets, --ClientApps:app:EndpointsManifest, and --ClientApps:app:PathPrefix arguments from call sites instead of deriving manifest paths inside BlazorGateway. Add SpaFallback.targets to GlobalizationWasmApp.

Address PR review feedback: add namespace, fix paths, consolidate Spa…

2e4a184

…Fallback.targets

javiercn and others added 3 commits April 16, 2026 11:04

Revert whitespace-only change to E2ETests.csproj

b4aad61

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

javiercn force-pushed the javiercn/blazor-gateway branch from a3c3df4 to b4aad61 Compare April 16, 2026 09:05

javiercn merged commit 2fd33a4 into main Apr 20, 2026
25 checks passed

javiercn deleted the javiercn/blazor-gateway branch April 20, 2026 13:47

dotnet-policy-service Bot added this to the 11.0-preview4 milestone Apr 20, 2026

dotnet-maestro Bot mentioned this pull request Apr 21, 2026

[main] Source code updates from dotnet/aspnetcore dotnet/dotnet#6097

Merged

javiercn linked an issue Apr 22, 2026 that may be closed by this pull request

[Blazor] Gateway package for standalone Blazor WebAssembly applications #64573

Closed

danroth27 mentioned this pull request May 5, 2026

Set IsPackable=true on Microsoft.AspNetCore.Components.Gateway so Pack produces the shipping nupkg #66579

Merged

This was referenced May 6, 2026

Blazor .NET 11 Tracking Issue dotnet/AspNetCore.Docs#36448

Open

[11.0 P4] Replace DevServer with BlazorGateway for standalone WASM apps dotnet/AspNetCore.Docs#37111

Closed

jinzhao1127 mentioned this pull request May 26, 2026

An error dialog The server process is no longer running pop ups when running the 11.0 Blazor WebAssembly Standalone App #66836

Closed

3 tasks

This was referenced May 26, 2026

Fix BlazorGateway VS F5 launch (#66836) and E2E manifest task path (#66617) #66849

Merged

[release/11.0-preview5] Fix BlazorGateway VS F5 launch (#66836) and E2E manifest task path (#66617) #66855

Merged

Conversation

javiercn commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

New: Gateway project (src/Components/Gateway/src/)

Updated: E2E test infrastructure

Key design decisions

Testing

Uh oh!

javiercn Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

javiercn Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

javiercn Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

ScarletKuro commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ilonatommy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ilonatommy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

javiercn commented Mar 25, 2026 •

edited

Loading

New: Gateway project (`src/Components/Gateway/src/`)

ScarletKuro commented Apr 4, 2026 •

edited

Loading