Set up .NET / C# apps in the AppHost

Esta página aún no está disponible en tu idioma.

This article is the reference for the Aspire Dotnet hosting integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.mts — that you use to add C# projects and file-based C# apps by path in your AppHost project.

If you’re new to the Dotnet integration, start with the Get started with the .NET / C# app integration guide.

If your C# AppHost needs to reference the resource type directly — for example, to declare a strongly typed variable or a method parameter — import it from the Aspire.Hosting.Dotnet namespace, matching the pattern used by the Go, Python, and JavaScript hosting integrations:

using Aspire.Hosting.Dotnet;

var builder = DistributedApplication.CreateBuilder(args);

IResourceBuilder<DotnetProjectResource> api =
    builder.AddDotnetProject("api", "../api/api.csproj");

Installation

To start building an Aspire app that adds a C# project or file-based app by path, install the 📦 Aspire.Hosting.Dotnet NuGet package:

C#
TypeScript

aspire add Aspire.Hosting.Dotnet

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

#:package Aspire.Hosting.Dotnet@*

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

aspire add Aspire.Hosting.Dotnet

Learn more about aspire add in the command reference.

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

{
  "packages": {
    "Aspire.Hosting.Dotnet": "13.5.0"
  }
}

Add a C# project or file-based app by path

Use AddDotnetProject / addDotnetProject to add a C# project or file-based app resource by path. The path argument can point at a project file (.csproj), a directory containing a single .csproj, or a file-based app (.cs). If the path isn’t absolute, it’s computed relative to the AppHost directory.

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddDotnetProject("api", "../api/api.csproj")
    .WithHttpEndpoint(port: 8080)
    .WithExternalHttpEndpoints();

builder.Build().Run();

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

const builder = await createBuilder();

const api = await builder.addDotnetProject('api', '../api/api.csproj');
await api.withHttpEndpoint({ port: 8080 });
await api.withExternalHttpEndpoints();

await builder.build().run();

The resource launches with dotnet run --project <path> for a project file, or dotnet run --file <path> for a file-based app. Endpoints, environment variables, and service discovery are configured from the project’s launchSettings.json and Kestrel configuration, matching AddProject<T>.

Add a file-based C# app

A file-based app is a single .cs file run directly with dotnet run --file, without a .csproj. File-based apps require .NET 10 or later.

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

builder.AddDotnetProject("inventoryservice", @"..\InventoryService.cs");

builder.Build().Run();

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

const builder = await createBuilder();

await builder.addDotnetProject('inventoryservice', '../InventoryService.cs');

await builder.build().run();

Configure options

Pass a configuration action to set additional options such as the launch profile:

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

builder.AddDotnetProject("inventoryservice", @"..\InventoryService.cs", o => o.LaunchProfileName = "https");

builder.Build().Run();

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

const builder = await createBuilder();

await builder.addDotnetProject('inventoryservice', '../InventoryService.cs', {
  launchProfileName: 'https',
});

await builder.build().run();

The resource is added as an ExecutableResource rather than a ProjectResource, so it doesn’t need to be referenced from the AppHost’s own solution. Before the resource starts, Aspire validates that the path resolves to a .csproj or .cs file (or a directory containing a single .csproj) and, for file-based apps, that the active .NET SDK version is 10 or later.

Publishing

Automatic project publishing for DotnetProjectResource isn’t currently supported. A plain DotnetProjectResource causes aspire publish and aspire deploy to fail with an actionable error instead of emitting an executable.v0 manifest containing machine-local paths.

Use one of these alternatives:

Use AddProject<TProject>(...) for a project referenced by a C# AppHost.
Use AddCSharpApp(...) / addCSharpApp(...) for a path-based project or file-based app that should use standard .NET project publishing.
Call PublishAsDockerFile(...) / publishAsDockerFile(...) to configure container publishing explicitly.
Call ExcludeFromManifest() / excludeFromManifest() when the resource is intentionally available only during local orchestration.