Set up .NET / C# apps in the AppHost
Use the Aspire.Hosting.Dotnet integration to add SDK-style .NET projects and C# file-based apps by path in your AppHost. The examples cover TypeScript, C#, and Go AppHosts.
If you’re new to the Dotnet integration, start with the Get started with the .NET / C# app integration guide.
Installation
Section titled “Installation”To add a .NET project or C# file-based app by path, install the 📦 Aspire.Hosting.Dotnet NuGet package:
aspire add Aspire.Hosting.DotnetLearn more about aspire add in the
command reference.
This updates your aspire.config.json with the Dotnet hosting integration package:
{ "packages": { "Aspire.Hosting.Dotnet": "17.0.0" }}aspire add Aspire.Hosting.DotnetLearn 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.DotnetLearn more about aspire add in the
command reference.
This updates your aspire.config.json with the Dotnet hosting integration package:
{ "packages": { "Aspire.Hosting.Dotnet": "17.0.0" }}Add a .NET project or file-based app by path
Section titled “Add a .NET project or file-based app by path”Use AddDotnetProjectaddDotnetProjectAddDotnetProject / addDotnetProject to add a resource by path. Supported inputs are SDK-style C#, F#, and Visual Basic project files (.csproj, .fsproj, and .vbproj), a directory containing exactly one supported project, or a C# file-based app (.cs). If the path isn’t absolute, it’s computed relative to the AppHost directory. Specify a project filename if a directory contains multiple supported projects. F# scripts and non-SDK project systems aren’t supported.
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();var builder = DistributedApplication.CreateBuilder(args);
var api = builder.AddDotnetProject("api", "../api/api.csproj") .WithHttpEndpoint(port: 8080) .WithExternalHttpEndpoints();
builder.Build().Run();builder, err := aspire.CreateBuilder()if err != nil { log.Fatal(aspire.FormatError(err))}
api := builder.AddDotnetProject("api", "../api/api.csproj")api.WithHttpEndpoint(aspire.HttpEndpointPort(8080))api.WithExternalHttpEndpoints()
app, err := builder.Build()if err != nil { log.Fatal(aspire.FormatError(err))}if err := app.Run(); err != nil { log.Fatal(aspire.FormatError(err))}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.
Because the resource is registered by path, the AppHost doesn’t need a ProjectReference to the app. Before the resource starts, Aspire validates the path and, for file-based apps, that the active .NET SDK version is 10 or later.
To refer to the resource type in a C# AppHost, for example in a helper method signature, add using Aspire.Hosting.Dotnet; and use IResourceBuilder<DotnetProjectResource>.
Add a file-based C# app
Section titled “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.
See C# file-based apps for app directives, file-based AppHost examples, and debugging considerations.
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
await builder.addDotnetProject('inventoryservice', '../InventoryService.cs');
await builder.build().run();var builder = DistributedApplication.CreateBuilder(args);
builder.AddDotnetProject("inventoryservice", @"..\InventoryService.cs");
builder.Build().Run();builder.AddDotnetProject("inventoryservice", "../InventoryService.cs")Configure options
Section titled “Configure options”Pass options to choose a launch profile or control how Aspire derives endpoints from the project:
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
await builder.addDotnetProject('inventoryservice', '../InventoryService.cs', { launchProfileName: 'https', excludeLaunchProfile: false, excludeKestrelEndpoints: false,});
await builder.build().run();var builder = DistributedApplication.CreateBuilder(args);
builder.AddDotnetProject("inventoryservice", @"..\InventoryService.cs", options =>{ options.LaunchProfileName = "https"; options.ExcludeLaunchProfile = false; options.ExcludeKestrelEndpoints = false;});
builder.Build().Run();builder.AddDotnetProject("inventoryservice", "../InventoryService.cs", aspire.AddDotnetProjectOptionsValue(&aspire.DotnetProjectOptions{ LaunchProfileName: aspire.StringPtr("https"), ExcludeLaunchProfile: aspire.BoolPtr(false), ExcludeKestrelEndpoints: aspire.BoolPtr(false),}))- Omitting the options object, or leaving
launchProfileNameunset or null, selects the default launch profile. excludeLaunchProfile: truedisables launch profiles entirely and takes precedence over a suppliedlaunchProfileName.excludeKestrelEndpoints: truestops Aspire from deriving model endpoints from the project’s Kestrel configuration. It doesn’t rewrite or disable the service’s own Kestrel configuration.
For profile selection order and how applicationUrl values become endpoints, see Launch profiles.
Filter endpoints in environment variables
Section titled “Filter endpoints in environment variables”By default, Aspire passes a project’s endpoints to the process through environment variables such as ASPNETCORE_URLS and HTTP_PORTS/HTTPS_PORTS. Call WithEndpointsInEnvironment / withEndpointsInEnvironment to control which endpoints are included:
await builder.addDotnetProject('apiservice', '../ApiService/ApiService.csproj') .withHttpsEndpoint() .withHttpsEndpoint({ port: 19227, name: 'admin' }) .withEndpointsInEnvironment(['https']); // include only "https"builder.AddDotnetProject("apiservice", "../ApiService/ApiService.csproj") .WithHttpsEndpoint() .WithHttpsEndpoint(port: 19227, name: "admin") .WithEndpointsInEnvironment( filter: static endpoint => endpoint.Name is not "admin");builder.AddDotnetProject("apiservice", "../ApiService/ApiService.csproj"). WithHttpsEndpoint(). WithHttpsEndpoint(aspire.HttpsEndpointPort(19227), aspire.HttpsEndpointName("admin")). WithEndpointsInEnvironment([]string{"https"}) // include only "https"The admin endpoint stays in the application model but isn’t exposed to the process through environment variables. The C# overload takes a filter callback; TypeScript and Go take the names of the endpoints to include.
For ports, proxies, and replicas, see Inner-loop networking.
Launch from an IDE
Section titled “Launch from an IDE”Aspire builds SDK-style project resources before launching them and surfaces any compiler diagnostics. A compile failure stops the resource from launching. You don’t need to build each service yourself, whether you start the app with aspire run or from an IDE.
IDEs with external build support, such as Visual Studio Code, coordinate the build with Aspire. Aspire builds each resource once, and the IDE launches the resulting output without building it again. You can customize the build of SDK-style projects by calling WithBuildEnvironmentwithBuildEnvironmentWithBuildEnvironment in the AppHost, and file-based apps are fully supported: their builds are coordinated and serialized just like when you use aspire run.
IDEs without external build support, such as Visual Studio, still launch project resources after Aspire builds them, but with these limitations:
- The IDE might build projects again before launching them, because Aspire can’t suppress the IDE build.
- This build customization isn’t supported. Aspire fails to start the application and reports an error instead of launching output that the IDE can’t reliably locate. Run the application with
aspire run, use an IDE with external build support, or remove the build customization. - File-based apps build themselves when they launch. They wait for Aspire to finish building project resources, but they aren’t serialized with each other, so separate file-based apps can race when they share
#:projectoutputs.WaitForStartonly waits for the file-based app process to start, not for its build to finish. To avoid races, run withaspire run, use an IDE with external build support, or add a health check to the preceding app that passes only after it finishes building and callWaitForon the next app.
Coordinated builds and restore
Section titled “Coordinated builds and restore”Before resources start, Aspire groups SDK-style projects that share a compatible SDK and build environment into generated MSBuild traversal projects under the AppHost’s intermediate output. Build groups run one after another. Projects within a group build in parallel and share one NuGet graph restore, which avoids restoring overlapping dependency graphs repeatedly. Projects that call WithBuildEnvironment build separately from these groups.
Because the group restore doesn’t invoke each project’s Restore target separately, custom targets attached to it, such as BeforeTargets="Restore" or AfterTargets="Restore", don’t run for each project. If a project relies on those hooks, set Aspire:Dotnet:RestoreProjectsIndividually to true in the AppHost’s configuration:
{ "Aspire": { "Dotnet": { "RestoreProjectsIndividually": true } }}The environment-variable equivalent is Aspire__Dotnet__RestoreProjectsIndividually=true. The setting defaults to false and applies to every generated traversal in the AppHost; it isn’t a runtime environment variable for your resources. With individual restore, each project restores one at a time while builds remain parallel.
A traversal also restores projects individually when its MSBuild context enables RestoreUseStaticGraphEvaluation, because NuGet’s static restore requires a restore-capable entry project. The build resource’s logs report why individual restore was selected. Restore failures aren’t retried with the other strategy.
File-based apps, projects with a custom build environment, individual Rebuild commands, and publishing use their own build and restore paths.
Multithreaded builds
Section titled “Multithreaded builds”When the dotnet SDK selected for a build (honoring global.json) supports the MSBuild -mt switch, Aspire passes it to coordinated traversal builds, file-based app builds, and rebuild commands. Multithreaded task execution can reduce the time it takes for resources to become ready. No configuration is required.
Publishing
Section titled “Publishing”Resources created with AddDotnetProject are automatically configured for the .NET SDK container-publishing pipeline. Use them with your deployment target.
Use WithContainerBuildOptionswithContainerBuildOptionsWithContainerBuildOptions / withContainerBuildOptions to configure supported image settings. See Container registries for image naming, tags, and registries.
Constructing a DotnetProjectResource directly doesn’t configure metadata, coordinated builds, or publishing. Prefer the builder API.
For other publishing models:
- Call
PublishAsDockerFilepublishAsDockerFilePublishAsDockerFile/publishAsDockerFileto use an explicit Dockerfile instead of .NET SDK container publishing. - Call
ExcludeFromManifestexcludeFromManifestExcludeFromManifestfor a resource that’s intentionally available only during local orchestration.