[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

- 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.

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

src/WebAssembly/testassets/SpaFallback.targets

This is temporary until an SDK with the functionality flows here

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

src/Components/WebAssembly/testassets/SpaFallback.targets

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.

Copilot · 2026-03-26T10:26:48Z

src/Components/WebAssembly/testassets/StandaloneApp/StandaloneApp.csproj

  <PropertyGroup>
    <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
+    <!-- Point to the locally-built Gateway DLL -->
+    <_BlazorGatewayDll>$(RepoRoot)artifacts\bin\Microsoft.AspNetCore.Components.Gateway\Debug\$(DefaultNetCoreTargetFramework)\blazor-gateway.dll</_BlazorGatewayDll>


_BlazorGatewayDll is hard-coded to the Debug artifacts path. This will break if the test asset is built/run under a non-Debug configuration (e.g., Release/CI). Consider using $(Configuration) (and/or $(ArtifactsBinDir)) instead of the literal "Debug" so the path matches the current build.

Suggested change

<_BlazorGatewayDll>$(RepoRoot)artifacts\bin\Microsoft.AspNetCore.Components.Gateway\Debug\$(DefaultNetCoreTargetFramework)\blazor-gateway.dll</_BlazorGatewayDll>

<_BlazorGatewayDll>$(RepoRoot)artifacts\bin\Microsoft.AspNetCore.Components.Gateway\$(Configuration)\$(DefaultNetCoreTargetFramework)\blazor-gateway.dll</_BlazorGatewayDll>

Copilot · 2026-03-26T10:26:49Z

src/Components/Gateway/src/BlazorGateway.cs

+/// <summary>
+/// Intended for framework test use only.
+/// </summary>
+public static class BlazorGateway
+{


BlazorGateway is declared in the global namespace. For consistency with the rest of the repo (which uses file-scoped namespaces, including the previous DevServer entrypoint) and to avoid potential type name collisions when this file is included as shared source, consider moving it under an appropriate namespace (e.g., Microsoft.AspNetCore.Components.Gateway) and updating call sites accordingly.

Copilot · 2026-03-26T10:26:49Z

src/Components/WebAssembly/testassets/SpaFallback.targets

+-->
+<Project>
+  <PropertyGroup>
+    <GenerateStaticWebAssetsManifestDependsOn>$(GenerateStaticWebAssetsManifestDependsOn);_AddSpaFallbackEndpoint</GenerateStaticWebAssetsManifestDependsOn>
+  </PropertyGroup>
+
+  <Target Name="_AddSpaFallbackEndpoint">
+    <ItemGroup>
+      <!-- Find the identity (uncompressed) index.html endpoint: Route == index.html, AssetFile not .gz/.br -->
+      <_SpaFallbackCandidate Include="@(StaticWebAssetEndpoint)"
+        Condition="'%(Identity)' == 'index.html' and !$([System.String]::Copy('%(AssetFile)').EndsWith('.gz')) and !$([System.String]::Copy('%(AssetFile)').EndsWith('.br'))" />
+    </ItemGroup>
+
+    <ItemGroup Condition="'@(_SpaFallbackCandidate)' != ''">
+      <!-- Add a clone with route changed to the SPA catch-all pattern -->
+      <StaticWebAssetEndpoint Include="{**path:nonfile}"
+        AssetFile="%(_SpaFallbackCandidate.AssetFile)"
+        Selectors="%(_SpaFallbackCandidate.Selectors)"
+        EndpointProperties="%(_SpaFallbackCandidate.EndpointProperties)"
+        ResponseHeaders="%(_SpaFallbackCandidate.ResponseHeaders)"
+        Order="2147483647" />
+    </ItemGroup>
+  </Target>


The SpaFallback.targets file is duplicated (there’s an identical copy under src/WebAssembly/testassets/SpaFallback.targets). Maintaining two copies risks them drifting and makes imports inconsistent. Consider keeping a single copy in one location and updating imports to reference that one file.

Suggested change

-->

<Project>

<PropertyGroup>

<GenerateStaticWebAssetsManifestDependsOn>$(GenerateStaticWebAssetsManifestDependsOn);_AddSpaFallbackEndpoint</GenerateStaticWebAssetsManifestDependsOn>

</PropertyGroup>

<Target Name="_AddSpaFallbackEndpoint">

<ItemGroup>



<_SpaFallbackCandidate Include="@(StaticWebAssetEndpoint)"

Condition="'%(Identity)' == 'index.html' and !$([System.String]::Copy('%(AssetFile)').EndsWith('.gz')) and !$([System.String]::Copy('%(AssetFile)').EndsWith('.br'))" />

</ItemGroup>

<ItemGroup Condition="'@(_SpaFallbackCandidate)' != ''">



<StaticWebAssetEndpoint Include="{**path:nonfile}"

AssetFile="%(_SpaFallbackCandidate.AssetFile)"

Selectors="%(_SpaFallbackCandidate.Selectors)"

EndpointProperties="%(_SpaFallbackCandidate.EndpointProperties)"

ResponseHeaders="%(_SpaFallbackCandidate.ResponseHeaders)"

Order="2147483647" />

</ItemGroup>

</Target>

This file now delegates to the shared SpaFallback.targets to avoid duplication.

-->

<Project>

<Import Project="../../../WebAssembly/testassets/SpaFallback.targets" />

Copilot · 2026-03-26T10:26:49Z

src/Components/WebAssembly/testassets/SpaFallback.targets

+        Selectors="%(_SpaFallbackCandidate.Selectors)"
+        EndpointProperties="%(_SpaFallbackCandidate.EndpointProperties)"
+        ResponseHeaders="%(_SpaFallbackCandidate.ResponseHeaders)"
+        Order="2147483647" />


This uses a hard-coded magic number for endpoint order. To make intent clearer (and avoid accidental typos), consider using an expression like $([System.Int32]::MaxValue) instead of 2147483647.

Suggested change

Order="2147483647" />

Order="$([System.Int32]::MaxValue)" />

Copilot · 2026-03-26T10:26:50Z

src/WebAssembly/testassets/SpaFallback.targets

+  endpoints manifest. This will be removed once the SDK ships StaticWebAssetSpaFallbackEnabled.
+-->
+<Project>
+  <PropertyGroup>
+    <GenerateStaticWebAssetsManifestDependsOn>$(GenerateStaticWebAssetsManifestDependsOn);_AddSpaFallbackEndpoint</GenerateStaticWebAssetsManifestDependsOn>
+  </PropertyGroup>
+
+  <Target Name="_AddSpaFallbackEndpoint">
+    <ItemGroup>
+      <!-- Find the identity (uncompressed) index.html endpoint: Route == index.html, AssetFile not .gz/.br -->
+      <_SpaFallbackCandidate Include="@(StaticWebAssetEndpoint)"
+        Condition="'%(Identity)' == 'index.html' and !$([System.String]::Copy('%(AssetFile)').EndsWith('.gz')) and !$([System.String]::Copy('%(AssetFile)').EndsWith('.br'))" />
+    </ItemGroup>
+
+    <ItemGroup Condition="'@(_SpaFallbackCandidate)' != ''">
+      <!-- Add a clone with route changed to the SPA catch-all pattern -->
+      <StaticWebAssetEndpoint Include="{**path:nonfile}"
+        AssetFile="%(_SpaFallbackCandidate.AssetFile)"
+        Selectors="%(_SpaFallbackCandidate.Selectors)"
+        EndpointProperties="%(_SpaFallbackCandidate.EndpointProperties)"
+        ResponseHeaders="%(_SpaFallbackCandidate.ResponseHeaders)"
+        Order="2147483647" />
+    </ItemGroup>
+  </Target>


The SpaFallback.targets file is duplicated (there’s an identical copy under src/Components/WebAssembly/testassets/SpaFallback.targets). Having two identical targets files increases the chance of them diverging over time; consider consolidating to a single shared file and updating imports accordingly.

Suggested change

endpoints manifest. This will be removed once the SDK ships StaticWebAssetSpaFallbackEnabled.

-->

<Project>

<PropertyGroup>

<GenerateStaticWebAssetsManifestDependsOn>$(GenerateStaticWebAssetsManifestDependsOn);_AddSpaFallbackEndpoint</GenerateStaticWebAssetsManifestDependsOn>

</PropertyGroup>

<Target Name="_AddSpaFallbackEndpoint">

<ItemGroup>



<_SpaFallbackCandidate Include="@(StaticWebAssetEndpoint)"

Condition="'%(Identity)' == 'index.html' and !$([System.String]::Copy('%(AssetFile)').EndsWith('.gz')) and !$([System.String]::Copy('%(AssetFile)').EndsWith('.br'))" />

</ItemGroup>

<ItemGroup Condition="'@(_SpaFallbackCandidate)' != ''">



<StaticWebAssetEndpoint Include="{**path:nonfile}"

AssetFile="%(_SpaFallbackCandidate.AssetFile)"

Selectors="%(_SpaFallbackCandidate.Selectors)"

EndpointProperties="%(_SpaFallbackCandidate.EndpointProperties)"

ResponseHeaders="%(_SpaFallbackCandidate.ResponseHeaders)"

Order="2147483647" />

</ItemGroup>

</Target>

endpoints manifest. This file now forwards to the shared implementation under

src/Components/WebAssembly/testassets/SpaFallback.targets to avoid duplication.

-->

<Project>

<Import Project="..\Components\WebAssembly\testassets\SpaFallback.targets" />

Copilot · 2026-03-26T10:26:50Z

src/Components/test/testassets/GlobalizationWasmApp/GlobalizationWasmApp.csproj

    <Reference Include="Microsoft.Extensions.Localization" />
  </ItemGroup>

+  <Import Project="..\..\..\..\WebAssembly\testassets\SpaFallback.targets" />


This import points at the SpaFallback.targets copy under src/WebAssembly/testassets, while other WASM test assets in Components import src/Components/WebAssembly/testassets/SpaFallback.targets. Using a different copy makes it easy for the two files to drift; consider switching to the same shared path (e.g., via $(RepoRoot)) once the duplication is resolved.

Suggested change

<Import Project="..\..\..\..\WebAssembly\testassets\SpaFallback.targets" />

<Import Project="$(RepoRoot)src\Components\WebAssembly\testassets\SpaFallback.targets" />

javiercn added 2 commits March 25, 2026 21:41

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

Remove --applicationpath parsing from BlazorGateway

3576550

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.

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

src/WebAssembly/testassets/SpaFallback.targets

Copy link

Member Author

javiercn Mar 26, 2026

Choose a reason for hiding this comment

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

This is temporary until an SDK with the functionality flows here

javiercn commented Mar 26, 2026

View reviewed changes

src/Components/WebAssembly/testassets/SpaFallback.targets

Copy link

Member Author

javiercn Mar 26, 2026

Choose a reason for hiding this comment

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

Temporary until the SDK update flows to asp.net core

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Blazor] Replace DevServer with BlazorGateway for standalone WASM apps#65982

[Blazor] Replace DevServer with BlazorGateway for standalone WASM apps#65982
javiercn wants to merge 3 commits intomainfrom
javiercn/blazor-gateway

javiercn commented Mar 25, 2026 •

edited

Loading

Uh oh!

javiercn Mar 26, 2026

Uh oh!

javiercn Mar 26, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	<_BlazorGatewayDll>$(RepoRoot)artifacts\bin\Microsoft.AspNetCore.Components.Gateway\Debug\$(DefaultNetCoreTargetFramework)\blazor-gateway.dll</_BlazorGatewayDll>
	<_BlazorGatewayDll>$(RepoRoot)artifacts\bin\Microsoft.AspNetCore.Components.Gateway\$(Configuration)\$(DefaultNetCoreTargetFramework)\blazor-gateway.dll</_BlazorGatewayDll>

	<Import Project="..\..\..\..\WebAssembly\testassets\SpaFallback.targets" />
	<Import Project="$(RepoRoot)src\Components\WebAssembly\testassets\SpaFallback.targets" />

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!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

javiercn commented Mar 25, 2026 •

edited

Loading

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