Upgrade to Aspire 13.0

In this article, you learn the steps involved in updating your existing Aspire projects to the latest version: Aspire 13.0. The easiest way to upgrade to Aspire 13.0 is using the Aspire CLI with the aspire update command.

Prerequisites

Before you upgrade your projects to Aspire 13.0, ensure that you have the following prerequisites:

• Install the latest tooling.
• Use the Aspire SDK.
• If you have a version of Aspire older than 9.0, remove the legacy workload.

Upgrade using the Aspire CLI

The recommended way to upgrade to Aspire 13.0 is using the Aspire CLI. This method handles all the necessary updates automatically.

Update the Aspire CLI

First, update the Aspire CLI to the latest version:

curl -sSL http://aspire.dev/install.sh | bash

Invoke-RestMethod -Uri "http://aspire.dev/install.ps1" | Invoke-Expression

Update your Aspire project

Update your Aspire project using the aspire update command:

aspire update

This command will:

• Update the Aspire.AppHost.Sdk version in your AppHost project.
• Update all Aspire NuGet packages to version 13.0.
• Handle dependency resolution automatically.
• Support both regular projects and Central Package Management (CPM).

Update your Aspire templates

Install the latest Aspire project templates by running this command:

dotnet new install Aspire.ProjectTemplates

AppHost template updates

Aspire 13.0 introduces a simplified AppHost project template structure. The SDK now encapsulates the Aspire.Hosting.AppHost package, resulting in cleaner project files.

Before (9.x)

<Project Sdk="Microsoft.NET.Sdk">

  <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UserSecretsId>1bf2ca25-7be4-4963-8782-c53a74e10ad9</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\MyApp.ApiService\MyApp.ApiService.csproj" />
    <ProjectReference Include="..\MyApp.Web\MyApp.Web.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />
    <PackageReference Include="Aspire.Hosting.Redis" Version="9.5.2" />
  </ItemGroup>

</Project>

After (13.0)

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UserSecretsId>1bf2ca25-7be4-4963-8782-c53a74e10ad9</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\MyApp.ApiService\MyApp.ApiService.csproj" />
    <ProjectReference Include="..\MyApp.Web\MyApp.Web.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.Redis" Version="13.0.0" />
  </ItemGroup>

</Project>

Key changes

• Simplified SDK declaration: The SDK is now specified directly in the <Project> tag with its version: Sdk="Aspire.AppHost.Sdk/13.0.0".
• No explicit Aspire.Hosting.AppHost reference: The SDK now automatically includes this package, reducing boilerplate.
• Cleaner structure: Removed the separate <Sdk Name="..." /> element and the Microsoft.NET.Sdk base SDK.
• Target framework: Updated from net9.0 to net10.0.

The aspire update command automatically handles this migration when upgrading from 9.x to 13.0.

Single-file AppHosts

The same project as a file-based AppHost:

apphost.cs

#:sdk Aspire.AppHost.Sdk@13.0.0
#:package Aspire.Hosting.Redis@13.0.0

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");
var api = builder.AddProject("apiservice", "../MyApi")
                 .WithReference(cache);

builder.Build().Run();

No project file needed - just a single .cs file with package references declared using #:package directives.

Manually upgrade a solution to Aspire 13.0

If you prefer to manually upgrade your projects, you can update your project files directly. The following steps guide you through the process:

• Edit your AppHost project file to use the new Aspire 13.0 SDK (Aspire.AppHost.Sdk).
• Update the NuGet packages in your project files to the latest versions.
• Adjust your code to address any breaking changes.

Edit your AppHost project file

To upgrade your AppHost project to Aspire 13.0, update your project file to use the new SDK declaration and remove the explicit Aspire.Hosting.AppHost package reference:

- <Project Sdk="Microsoft.NET.Sdk">
+ <Project Sdk="Aspire.AppHost.Sdk/13.0.0">

-  <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
-   <TargetFramework>net9.0</TargetFramework>
+   <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
-   <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
-   <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />
+   <!-- Aspire.Hosting.AppHost is now included automatically by the SDK -->
  </ItemGroup>

</Project>

Update the NuGet packages

To take advantage of the latest updates in your Aspire solution, update all NuGet packages to version 13.0.0.

dotnet add package Aspire.Hosting.Redis --version 13.0.0

Breaking changes

With the introduction of Aspire 13.0, there are some breaking changes. You need to adjust your code to address these changes.

For the complete list of breaking changes in Aspire 13.0, see Breaking changes in Aspire 13.0.

Use the Upgrade Assistant

The Upgrade Assistant is a tool that helps upgrade targeted projects to the latest version. If you're new to the Upgrade Assistant, there are two modalities to choose from:

• The Visual Studio extension version.
• The .NET CLI global tool version.

Regardless of how you install the Upgrade Assistant, you can use it to upgrade your Aspire projects to Aspire 13.0.

upgrade-assistant upgrade

 Selected options
────────────────────────────────────────────────────────────────────────────────────
 Source project     ..\AspireSample\AspireSample.AppHost\AspireSample.AppHost.csproj

 Steps
────────────────────────────────
 Source project / Upgrade type
────────────────────────────────

How do you want to upgrade project AspireSample.AppHost?

> Aspire upgrades
    Upgrade to latest Aspire version (aspire.latest)

  Upgrade project to a newer .NET version
    In-place project upgrade (framework.inplace)

  NuGet upgrades
    NuGet central package management (CPM) (nuget.cpm)

  Navigation
    Back
    Exit

 Selected options
────────────────────────────────────────────────────────────────────────────────────
 Source project     ..\AspireSample\AspireSample.AppHost\AspireSample.AppHost.csproj
 Upgrade type       aspire.latest

 Steps
──────────────────────────────────────────
 Source project / Upgrade type / Upgrade
──────────────────────────────────────────

We have gathered all required options and are ready to do the upgrade. Do you want to continue? [y/n] (y):

Finalizing operation...
Complete: 3 succeeded, 0 failed, 7 skipped.

Remove the Aspire workload (first-time upgrades from version 8 only)

If you're upgrading from Aspire 8 to Aspire 9 or later for the first time, you need to remove the legacy workload. This step is not needed for upgrades between Aspire 9 versions or from Aspire 9 to 13.

Previously the aspire workload was required to create and run Aspire projects. But, with Aspire 9 and later the workload is no longer required and should be removed from your .NET environment.

1. Find the installation source by opening a terminal and running the dotnet workload list command.

   The preceding command lists the workloads installed in the .NET environment. The method used to install Aspire is listed under the Installation Source column of the output, and is either VS for Visual Studio or SDK for the .NET SDK. For example, the following snippet indicates that Visual Studio was used to install Aspire:

   Installed Workload Id      Manifest Version      Installation Source
   --------------------------------------------------------------------
   aspire                     8.2.2/8.0.100         VS 17.14.36109.1
   

2. Remove Aspire 8.

   • If the Installation Source starts with VS:

     1. Open the Visual Studio Installer app.
     2. Modify the installation instance of Visual Studio.
     3. Select Individual Components.
     4. Search for aspire.
     5. Unselect Aspire SDK.
     6. Select the Modify button to apply the changes.

   • If the Installation Source starts with SDK, run dotnet workload uninstall aspire to remove Aspire.

Verify the upgrade

As with any upgrade, ensure that the app runs as expected and that all tests pass. Build the solution and look for suggestions, warnings, or errors in the output window—address anything that wasn't an issue before. If you encounter any issues, let us know by filing a GitHub issue.