[Blazor] Gateway package for standalone Blazor WebAssembly applications

[javiercn]

Summary

Create a Gateway package for standalone Blazor WebAssembly applications that enables seamless Aspire integration without requiring a hosted server project.

Background

When integrating standalone Blazor WebAssembly applications with Aspire, we currently need to:

1. Remove the DevServer dependency
2. Create a custom Gateway project that serves static files
3. Expose a configuration endpoint (/_blazor/_configuration) for OTEL and service discovery settings
4. Add Aspire service defaults integration
5. Set up MSBuild targets to override ComputeRunArguments to launch Gateway instead of the WASM project

This is demonstrated in the AspireWithBlazorStandalone playground sample in https://github.com/dotnet/aspire.

Proposed Solution

Create a Microsoft.AspNetCore.Components.WebAssembly.Gateway package that:

1. Replaces DevServer for production scenarios

• Uses MapStaticAssets to serve blazor files.
• Serves static files from wwwroot
• Provides fallback to index.html

2. Exposes configuration endpoint

• Maps /_blazor/_configuration endpoint
• Returns OTEL settings (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS)
• Returns service discovery configuration (services:*)

3. Integrates with Aspire

• Adds service defaults (OpenTelemetry, health checks, service discovery)
• Maps default endpoints (/health, /alive)

4. MSBuild integration

• Provides .props and .targets files
• Overrides ComputeRunArguments to launch Gateway with static asset paths
• Passes --contentroot, --staticwebassets, --staticwebassetsendpoints arguments

Example Gateway Program.cs

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();

var contentRoot = builder.Configuration["contentroot"];
if (!string.IsNullOrEmpty(contentRoot))
{
    builder.Environment.ContentRootPath = contentRoot;
    builder.Environment.WebRootPath = Path.Combine(contentRoot, "wwwroot");
}

var app = builder.Build();
app.MapDefaultEndpoints();
app.MapStaticAssets();
app.MapFallbackToFile("index.html");
app.MapConfigurationEndpoint("/_blazor/_configuration");
app.Run();

[javiercn]

This is the shape of the gateway at runtime.

using Microsoft.AspNetCore.Hosting;

var builder = WebApplication.CreateBuilder(args);
builder.WebHost.UseStaticWebAssets();
builder.AddServiceDefaults();

var appConfigs = builder.Configuration.GetSection("ClientApps").Get<Dictionary<string, ClientAppConfiguration>>() ?? [];

var proxySection = builder.Configuration.GetSection("ReverseProxy");
var hasProxy = proxySection.Exists();

if (hasProxy)
{
    builder.Services.AddReverseProxy()
        .LoadFromConfig(proxySection)
        .AddServiceDiscoveryDestinationResolver();
}

var app = builder.Build();

app.MapDefaultEndpoints();
if (hasProxy)
{
    app.MapReverseProxy();
}

foreach (var appConfig in appConfigs.Values)
{
    if (!string.IsNullOrEmpty(appConfig.ConfigEndpointPath))
    {
        app.MapConfigurationEndpoint(appConfig.ConfigEndpointPath, appConfig.ConfigResponse);
    }

    if (!string.IsNullOrEmpty(appConfig.EndpointsManifest))
    {
        app.MapGroup(appConfig.PathPrefix!).MapStaticAssets(appConfig.EndpointsManifest)
    }
}

app.Run();

class ClientAppConfiguration
{
    public string? PathPrefix { get; set; }
    public string? EndpointsManifest { get; set; }
    public string? ConfigEndpointPath { get; set; }
    public string? ConfigResponse { get; set; }
}

For non-aspire scenarios, things are driven via MSBuild (for local dev)

For aspire based scenarios, the aspire orchestration layer takes care of setting everything up.