Aspire SDK

The Aspire SDK is intended for AppHost projects, which serve as the orchestrator for Aspire applications. These projects are designated by their usage of the Aspire.AppHost.Sdk in the project file. The SDK provides features that simplify the development of Aspire apps.

The 📦 Aspire.AppHost.Sdk is used for building Aspire apps.

Project file

The Aspire.AppHost.Sdk is defined in the top-level Project node’s Sdk attribute:

XML — *.csproj file

<Project Sdk="Aspire.AppHost.Sdk/13.1">

    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net10.0</TargetFramework>
        <!-- Omitted for brevity -->
    </PropertyGroup>

    <!-- Omitted for brevity -->
</Project>

File-based app

The Aspire.AppHost.Sdk is defined in a file-based app’s source file using the #:sdk directive:

C# — file-based app

#:sdk Aspire.AppHost.Sdk@13.1.0

var builder = DistributedApplication.CreateBuilder(args);

// Omitted for brevity

The preceding example defines the top-level SDK as Aspire.AppHost.Sdk. The project also references the 📦 Aspire.Hosting.AppHost package which brings in a number of Aspire-related dependencies.

SDK Features

The Aspire SDK provides several key features.

Project references

Each ProjectReference in the AppHost project isn’t treated as standard project references. Instead, they enable the AppHost to execute these projects as part of its orchestration. Each project reference triggers a generator to create a class that represents the project as an IProjectMetadata. This metadata is used to populate the named projects in the generated Projects namespace. When you call the AddProject API, the Projects namespace is used to reference the project—passing the generated class as a generic-type parameter.

Tip

To prevent a project from being treated as an Aspire resource in the AppHost, set the IsAspireProjectResource attribute on the ProjectReference element to false, as shown in the following example:

<ProjectReference Include="..\MyProject\MyProject.csproj" IsAspireProjectResource="false" />

Otherwise, by default, the ProjectReference is treated as Aspire project resource.

Orchestrator dependencies

The Aspire SDK dynamically adds references to the Aspire dashboard and other AppHost dependencies, such as the developer control plane (DCP) packages. These dependencies are specific to the platform that the AppHost is built on.

When the AppHost project runs, the orchestrator relies on these dependencies to provide the necessary functionality to the AppHost. For more information, see Aspire orchestration overview.