Upgrade to Aspire 9.5.2

In this article, you learn the steps involved in updating your existing Aspire projects to the latest version: Aspire 9.5.2. There are a few ways in which you can update your projects to Aspire 9.5.2:

• Manually upgrade your projects to Aspire 9.5.2.
• Use the Upgrade Assistant to upgrade your projects to Aspire 9.5.2.

Prerequisites

Before you upgrade your projects to Aspire 9.5.2, 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 it.

Upgrade the Aspire project templates

Install the latest Aspire project templates by running this command:

dotnet new install Aspire.ProjectTemplates

Manually upgrade a solution to Aspire 9.5.2

To upgrade your projects to Aspire 9.5.2, you need to update your project files. The following steps guide you through the process:

• Edit your AppHost project file to use the new Aspire 9.5.2 SDK (Aspire.AppHost.Sdk).
• Update the NuGet packages in your project files to the latest versions.
• Adjust your Program.cs file to use the new APIs and remove any obsolete APIs.

Edit your AppHost project file

To upgrade your AppHost project to Aspire 9.5.2, you need to update your project file to use the new 📦 Aspire.AppHost.Sdk:

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.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" />
  </ItemGroup>

</Project>

Optionally upgrade the target framework moniker (TFM)

Aspire 9.5.2 runs on .NET 9.0, but you can also run it on .NET 8.0. In other words, just because you're using the Aspire SDK, and pointing to version 9.5.2 packages, you can still target .NET 8.0. If you want to run your Aspire 9.5.2 project on .NET 9.0, you need to update the TargetFramework property in your project file:

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
-   <TargetFramework>net8.0</TargetFramework>
+   <TargetFramework>net9.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" />
  </ItemGroup>

</Project>

For more information on TFMs, see Target frameworks in SDK-style projects: Latest versions.

Overall AppHost project differences

If you followed all of the preceding steps, your AppHost project file should look like this:

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
-   <TargetFramework>net8.0</TargetFramework>
+   <TargetFramework>net9.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="8.0.0" />
+   <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />
  </ItemGroup>

</Project>

The changes include the addition of the Aspire.AppHost.Sdk, the update of the TargetFramework property to net9.0, and the update of the Aspire.Hosting.AppHost package to version 9.5.2.

Adjust your Program.cs file

With the introduction of Aspire 9.5, there are some breaking changes. Some APIs were originally marked as experimental (with the ExperimentalAttribute) and are now removed, while other APIs are now attributed as ObsoleteAttribute with details on new replacement APIs. You need to adjust your Program.cs file (and potentially other affected APIs) to use the new APIs. If you're using the Upgrade Assistant to upgrade your projects, it automatically adjusts your Program.cs file in most cases.

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

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 9.5.2.

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.

Update the NuGet packages

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

dotnet add package Aspire.Hosting.AppHost --version 9.5.2

With the AppHost project updated, your project file should look like this:

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.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="8.0.0" />
+   <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />
  </ItemGroup>

</Project>

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

If you're upgrading from Aspire 8 to Aspire 9 for the first time, you need to remove the legacy workload. This step is not needed for upgrades between Aspire 9 versions (such as from 9.4.0 to 9.5.2).

Previously the aspire workload was required to create and run Aspire projects. But, with Aspire 9 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.