Set up Blazor hosting in the AppHost

Ce contenu n’est pas encore disponible dans votre langue.

This article is the reference for the Aspire Blazor hosting integration. It lists the AppHost APIs — with examples for both AppHost.cs and apphost.mts — that you use to model Blazor WebAssembly projects and a Blazor Gateway in your AppHost project.

If you’re new to this integration, start with Get started with Blazor hosting. For how apps connect through the gateway and service discovery properties, see Connect Blazor apps and APIs.

Installation

To start building an Aspire app that uses Blazor hosting, install the 📦 Aspire.Hosting.Blazor NuGet package:

TypeScript
C#

aspire add Aspire.Hosting.Blazor

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the Blazor hosting package:

{
  "packages": {
    "Aspire.Hosting.Blazor": "13.6.0"
  }
}

aspire add Aspire.Hosting.Blazor

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

#:package Aspire.Hosting.Blazor@*

<PackageReference Include="Aspire.Hosting.Blazor" Version="*" />

Add Blazor WebAssembly project

Use AddBlazorWasmProjectaddBlazorWasmProject to add a Blazor WebAssembly project to the AppHost model.

TypeScript
C#

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const api = await builder.addProject('api', '../MyApi/MyApi.csproj');

const blazorApp = await builder
  .addBlazorWasmProject('app', '../MyBlazorApp/MyBlazorApp.csproj')
  .withReference(await api.getEndpoint('http'));

await builder.build().run();

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.MyApi>("api");

var blazorApp = builder.AddBlazorWasmProject("app", "../MyBlazorApp/MyBlazorApp.csproj");
blazorApp.WithReference(api);

builder.Build().Run();

Add Blazor Gateway

Use AddBlazorGatewayaddBlazorGateway to add the Blazor Gateway resource. The gateway is the browser-facing endpoint for your hosted Blazor app.

TypeScript
C#

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const gateway = await builder
  .addBlazorGateway('gateway')
  .withExternalHttpEndpoints();

await builder.build().run();

var builder = DistributedApplication.CreateBuilder(args);

var gateway = builder.AddBlazorGateway("gateway")
    .WithExternalHttpEndpoints();

builder.Build().Run();

Associate a client app with the gateway

Use WithBlazorClientApp(IResourceBuilder<BlazorWasmAppResource> wasmApp, string apiPrefix, string otlpPrefix, bool proxyTelemetry)withBlazorClientApp(wasmApp: BlazorWasmAppResource, apiPrefix?: string, otlpPrefix?: string, proxyTelemetry?: boolean) to bind the WebAssembly project resource to the Blazor Gateway:

TypeScript
C#

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const weatherApi = await builder.addProject(
  'weatherapi',
  '../WeatherApi/WeatherApi.csproj'
);

const blazorApp = await builder
  .addBlazorWasmProject('app', '../MyBlazorApp/MyBlazorApp.csproj')
  .withReference(await weatherApi.getEndpoint('http'));

await builder
  .addBlazorGateway('gateway')
  .withExternalHttpEndpoints()
  .withBlazorClientApp(blazorApp);

await builder.build().run();

var builder = DistributedApplication.CreateBuilder(args);

var weatherApi = builder.AddProject<Projects.WeatherApi>("weatherapi");

var blazorApp = builder.AddBlazorWasmProject("app", "../MyBlazorApp/MyBlazorApp.csproj");
blazorApp.WithReference(weatherApi);

var gateway = builder.AddBlazorGateway("gateway")
    .WithExternalHttpEndpoints();

gateway.WithBlazorClientApp(blazorApp);

builder.Build().Run();

Add a Blazor Gateway for a C# project resource

AddDotnetProjectBlazorGateway adds a Blazor Gateway that hosts a DotnetProjectResource (a C# project or file-based app added with AddDotnetProjectaddDotnetProject) instead of the standard ProjectResource-based gateway. Use the distinct WithBlazorClientApp overload on this resource to attach a Blazor WebAssembly client app:

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const client: BlazorWasmAppResource
client = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addBlazorWasmProject(name: string, projectPath: string): BlazorWasmAppResource
Registers a Blazor WebAssembly project as a resource without launching it as a process. Prefer AddBlazorWasmProject which uses IProjectMetadata for path discovery.
addBlazorWasmProject(
  'client',
  '../Client/Client.csproj'
);
const 
const gateway: DotnetProjectResource
gateway = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addDotnetProjectBlazorGateway(name: string): DotnetProjectResource
Adds the built-in Blazor gateway as a .NET program resource.
addDotnetProjectBlazorGateway('gateway');

await 
const gateway: DotnetProjectResource
gateway.
ExecutableResource.withExternalHttpEndpoints(): DotnetProjectResource
Marks existing http or https endpoints on a resource as external.
withExternalHttpEndpoints();
await 
const gateway: DotnetProjectResource
gateway.
DotnetProjectResource.withBlazorClientApp(wasmApp: BlazorWasmAppResource, options?: {
    apiPrefix?: string;
    otlpPrefix?: string;
    proxyTelemetry?: boolean;
} | undefined): DotnetProjectResource (+1 overload)
Attaches a Blazor WebAssembly app to the gateway. The app's resource name becomes its URL path prefix, and its service references are forwarded to the gateway for proxying.
withBlazorClientApp(
const client: BlazorWasmAppResource
client);

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

var builder = DistributedApplication.CreateBuilder(args);

#pragma warning disable ASPIREBLAZOR001

var client = builder.AddBlazorWasmProject<Projects.Client>("client");

builder.AddDotnetProjectBlazorGateway("gateway")
    .WithExternalHttpEndpoints()
    .WithBlazorClientApp(client);

builder.Build().Run();

The gateway forwards the client’s service references and supports publishing through the shared Blazor client attachment and publish-companion pipeline. Browser-debugger resources are created only for local runs.