aspire-apphost-setup - SKILL.md Agent Skill

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.