microsoft/aspire · critical · NotSupportedException

Publishing a DotnetProjectResource-backed Blazor gateway is…

Error message

Publishing a DotnetProjectResource-backed Blazor gateway is not supported yet. Use AddBlazorGateway for publish scenarios.

What it means

AddDotnetProjectBlazorGateway creates the Blazor gateway from a DotnetProjectResource, but publishing that shape is unsupported: the publish path's WASM static-asset merge needs IContainerFilesDestinationResource, so the resulting gateway image would silently miss client apps. The extension fails fast instead of emitting a broken deployment.

Solutions

Replace AddDotnetProjectBlazorGateway with AddBlazorGateway (container-based) for publish scenarios.
Keep the dotnet-project gateway only for local run mode and gate it with ExecutionContext checks.
Restructure so the gateway is always container-backed when publish targets are used.
Check Aspire release notes for when DotnetProjectResource container execution/publish support lands.

Example fix

// before
var gateway = builder.AddDotnetProjectBlazorGateway("gateway", ...);
// after
var gateway = builder.AddBlazorGateway("gateway", ...);

Defensive patterns

Strategy: validation

Validate before calling

if (builder.ExecutionContext.IsPublishMode && usingDotnetProjectGateway)
{
    throw new InvalidOperationException("Use AddBlazorGateway (container-based) for publish scenarios.");
}

Try / catch

try { AddGateway(builder); } catch (NotSupportedException ex) when (ex.Message.Contains("not supported yet")) { logger.LogError(ex, "Switch to AddBlazorGateway for publish"); throw; }

Prevention

Use AddBlazorGateway whenever publish/deploy targets exist.
Gate dotnet-project-only wiring behind ExecutionContext.IsRunMode checks.
Track Aspire updates for DotnetProjectResource container/publish support.

When it happens

Trigger: Calling AddDotnetProjectBlazorGateway(...) inside an app model that is evaluated in publish mode (builder.ExecutionContext.IsPublishMode), e.g. running `aspire publish` against a gateway backed by AddDotnetProject.

Common situations: An app that runs fine locally (run mode) breaks when publishing; using the dotnet-project gateway overload for a deploy scenario where only the container-based AddBlazorGateway supports publish.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/c255d1efb2a2c144. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs:112

    /// This gateway can be used only when running the AppHost. Publishing it is not supported; use the standard
    /// Blazor gateway for publish scenarios.
    /// </ats-remarks>
    /// <ats-param name="builder">The distributed application builder.</ats-param>
    /// <ats-param name="name">The name of the gateway resource.</ats-param>
    /// <ats-returns>The gateway resource builder.</ats-returns>
    [Experimental("ASPIREDOTNETPROJECT001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    [AspireExport]
    public static IResourceBuilder<DotnetProjectResource> AddDotnetProjectBlazorGateway(
        this IDistributedApplicationBuilder builder,
        [ResourceName] string name)
    {
        if (builder.ExecutionContext.IsPublishMode)
        {
            // A DotnetProjectResource is an ExecutableResource and is not an IContainerFilesDestinationResource,
            // so the WASM static-asset merge that the publish path performs (via ContainerFilesDestinationAnnotation)
            // would silently produce a gateway image missing the client apps. Fail fast instead of emitting a
            // broken deployment until container execution is implemented for DotnetProjectResource.
            throw new NotSupportedException(
                $"Publishing a {nameof(DotnetProjectResource)}-backed Blazor gateway is not supported yet. Use {nameof(AddBlazorGateway)} for publish scenarios.");
        }

        var gatewayPath = GetScriptPath("Gateway.cs");
        return builder.AddDotnetProject(name, gatewayPath)
            .WithHttpEndpoint()
            .WithHttpsEndpoint();
    }

    /// <summary>
    /// Registers a Blazor WebAssembly project as a resource using the Aspire-generated
    /// IProjectMetadata type to discover the project path. The resource name becomes the
    /// URL path prefix (e.g., "store" → served at /store/).
    /// Use WithReference() to declare service dependencies.
    /// </summary>
    [AspireExportIgnore(Reason = "Open generic type parameter TProject is not ATS-compatible.")]
    public static IResourceBuilder<BlazorWasmAppResource> AddBlazorWasmProject<TProject>(
        this IDistributedApplicationBuilder builder,

View on GitHub (pinned to 25830f84bd)