aspire-apphost-setup

name	aspire-apphost-setup
description	Pattern for adding .NET Aspire AppHost and ServiceDefaults to an existing .NET solution
domain	infrastructure
confidence	low
source	earned

Context

When adding .NET Aspire orchestration to an existing .NET solution, there are version-specific SDK patterns and common pitfalls around package compatibility.

Patterns

Aspire 9.x — Explicit Two-SDK Pattern

For Aspire SDK 9.x (targeting .NET 9), use Microsoft.NET.Sdk as the top-level SDK with a child <Sdk> element:

<Project Sdk="Microsoft.NET.Sdk">
  <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\MyApp\MyApp.csproj" />
  </ItemGroup>
</Project>

The Aspire.AppHost.Sdk 9.x does NOT auto-import Microsoft.NET.Sdk (it only does so for file-based apps where FileBasedProgram=true).

Aspire 13.x+ — Simplified Top-Level SDK

From SDK 13.0.0+, the top-level Sdk="Aspire.AppHost.Sdk/13.x.x" works because it unconditionally imports Microsoft.NET.Sdk.

Version Alignment

Keep all Aspire-related packages within the same minor version:

• AppHost SDK, Aspire.Hosting.AppHost, and Microsoft.Extensions.ServiceDiscovery should all be 9.5.x (for .NET 9) or 13.x (for .NET 10).
• OpenTelemetry packages are runtime-agnostic; use 1.11.x for .NET 9 era, 1.13+ for .NET 10.

ServiceDefaults Project

The ServiceDefaults project is a shared library (IsAspireSharedProject=true) that configures OTel, resilience, and service discovery. It references Microsoft.AspNetCore.App as a FrameworkReference.

Anti-Patterns

• Using Aspire.AppHost.Sdk as sole top-level Sdk on 9.x — causes NU1503 restore failures and missing build targets.
• Mixing .NET 9 and .NET 10 Aspire packages — version 10.x/13.x packages target net10.0 and won't restore for net9.0.
• Applying TreatWarningsAsErrors globally with Directory.Build.props — existing test projects may have analyzer warnings that become errors; scope it to src/ projects.