From a4b282607c0a6cf46f206316aa5e1c7a1db0a23c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 11 Nov 2025 20:10:43 +0000 Subject: [PATCH 1/5] Initial plan From 631262c64e3d7d713df6505614364ff86b84a9b6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 11 Nov 2025 20:15:44 +0000 Subject: [PATCH 2/5] Add Aspire 13.0 upgrade documentation Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com> --- docs/get-started/upgrade-to-aspire-13.md | 332 +++++++++++++++++++++++ docs/toc.yml | 2 + 2 files changed, 334 insertions(+) create mode 100644 docs/get-started/upgrade-to-aspire-13.md diff --git a/docs/get-started/upgrade-to-aspire-13.md b/docs/get-started/upgrade-to-aspire-13.md new file mode 100644 index 0000000000..fc9888f17c --- /dev/null +++ b/docs/get-started/upgrade-to-aspire-13.md @@ -0,0 +1,332 @@ +--- +title: Upgrade to Aspire 13.0 +description: Learn how to upgrade all your Aspire projects to Aspire 13.0. +ms.date: 11/11/2025 +zone_pivot_groups: dev-environment +--- + +# Upgrade to Aspire 13.0 + +> [!CAUTION] +> Aspire 13.0 is a major version release with breaking changes. Please review the [Breaking changes section](#breaking-changes) before upgrading. + +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. + +> [!TIP] +> If you're new to Aspire, there's no reason to upgrade anything. For more information, see [Aspire setup and tooling](../fundamentals/setup-tooling.md). + +> [!NOTE] +> If you're upgrading from Aspire 8.x, follow the [upgrade guide to 9.x](upgrade-to-aspire-9.md) first, then upgrade to 13.0. + +## Prerequisites + +Before you upgrade your projects to Aspire 13.0, ensure that you have the following prerequisites: + +- [Install the latest tooling](../fundamentals/setup-tooling.md). +- [Use the Aspire SDK](../fundamentals/dotnet-aspire-sdk.md). +- If you have a version of Aspire older than 9.0, [remove it](upgrade-to-aspire-9.md#remove-the-aspire-workload-first-time-upgrades-from-version-8-only). + +## 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: + +:::zone pivot="visual-studio,dotnet-cli" + +# [Bash](#tab/bash) + +```bash +curl -sSL https://aspire.dev/install.sh | bash +``` + +# [PowerShell](#tab/powershell) + +```powershell +Invoke-RestMethod -Uri "https://aspire.dev/install.ps1" | Invoke-Expression +``` + +--- + +:::zone-end + +### Update your Aspire project + +Update your Aspire project using the `aspire update` command: + +```Aspire +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: + +```dotnetcli +dotnet new install Aspire.ProjectTemplates +``` + +> [!TIP] +> If you have the legacy Aspire workload installed, you need to pass the `--force` flag to overwrite the existing templates. For instructions on uninstalling the legacy workload, see [Remove the Aspire workload](upgrade-to-aspire-9.md#remove-the-aspire-workload-first-time-upgrades-from-version-8-only). + +## 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) + +```xml + + + + + + Exe + net9.0 + enable + enable + 1bf2ca25-7be4-4963-8782-c53a74e10ad9 + + + + + + + + + + + + + +``` + +### After (13.0) + +```xml + + + + Exe + net10.0 + enable + enable + 1bf2ca25-7be4-4963-8782-c53a74e10ad9 + + + + + + + + + + + + +``` + +### Key changes + +- **Simplified SDK declaration**: The SDK is now specified directly in the `` 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 `` 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 + +> [!TIP] +> For an even simpler setup, Aspire 13.0 also supports single-file AppHosts that don't require a project file at all. Single-file AppHosts are perfect for quick prototypes and learning scenarios. + +The same project as a file-based AppHost: + +**apphost.cs** + +```csharp +#: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](xref:dotnet/aspire/app-host) 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: + +```diff +- ++ + +- + + + Exe +- net9.0 ++ net10.0 + enable + enable +- true + 0afc20a6-cd99-4bf7-aae1-1359b0d45189 + + + +- ++ + + + +``` + +### Update the NuGet packages + +To take advantage of the latest updates in your Aspire solution, update all NuGet packages to version `13.0.0`. + +:::zone pivot="visual-studio" + +:::image type="content" source="media/visual-studio-update-nuget.png" lightbox="media/visual-studio-update-nuget.png" alt-text="Visual Studio: Update all NuGet packages for the Aspire solution."::: + +:::zone-end +:::zone pivot="vscode,dotnet-cli" + +To update your project packages, use the following .NET CLI command to update Aspire packages to version `13.0.0`: + +```dotnetcli +dotnet add package Aspire.Hosting.Redis --version 13.0.0 +``` + +When a package reference already exists, the `dotnet add package` command updates the reference to the specified version. For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package). + +:::zone-end + +> [!TIP] +> You'll want to also update the NuGet packages in your other projects to the latest versions. + +## 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](../compatibility/13.0/index.md). + +> [!IMPORTANT] +> Be sure to review breaking changes for all versions of Aspire after the one you're upgrading from. For example, if you're upgrading from Aspire 9.0, you must address breaking changes for all versions between 9.0 and 13.0. + +## Use the Upgrade Assistant + +The [Upgrade Assistant](/dotnet/core/porting/upgrade-assistant-overview) 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](/dotnet/core/porting/upgrade-assistant-install#visual-studio-extension). +- [The .NET CLI global tool version](/dotnet/core/porting/upgrade-assistant-install#net-global-tool). + +Regardless of how you install the Upgrade Assistant, you can use it to upgrade your Aspire projects to Aspire 13.0. + +:::zone pivot="visual-studio" + +To upgrade the Aspire AppHost project to Aspire 13.0 with Visual Studio, right-click the project in **Solution Explorer** and select **Upgrade**. + +> [!IMPORTANT] +> If the **Upgrade Assistant** isn't already installed, you'll be prompted to install it. + +The Upgrade Assistant displays a welcome package. Select the **Aspire upgrades** option: + +:::image type="content" source="media/upgrade-assistant-welcome-aspire.png" lightbox="media/upgrade-assistant-welcome-aspire.png" alt-text="Visual Studio: Upgrade Assistant welcome page with Aspire AppHost project."::: + +With the **Aspire upgrades** option selected, the Upgrade Assistant displays the selectable upgrade target components. Leave all the options checked and select **Upgrade selection**: + +:::image type="content" source="media/upgrade-assistant-aspire-app-host-comps.png" lightbox="media/upgrade-assistant-aspire-app-host-comps.png" alt-text="Visual Studio: Upgrade Assistant Aspire selectable components to upgrade."::: + +Finally, after selecting the components to upgrade, the Upgrade Assistant displays the results of the upgrade process. If everything was successful, you see green check marks next to each component: + +:::image type="content" source="media/upgrade-assistant-aspire-upgraded.png" lightbox="media/upgrade-assistant-aspire-upgraded.png" alt-text="Visual Studio: Upgrade Assistant Aspire AppHost project upgraded successfully."::: + +:::zone-end +:::zone pivot="vscode,dotnet-cli" + +To upgrade the Aspire AppHost project, ensure that you installed the Upgrade Assistant CLI. Open a terminal session at the root directory of the Aspire AppHost project file, and run the following command: + +```dotnetcli +upgrade-assistant upgrade +``` + +The output is interactive, expecting you to select the upgrade type. Choose the **Aspire upgrades** option: + +```dotnetcli + 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 +``` + +Use your keyboard to navigate up ↑ or down ↓, and select the **Aspire upgrades** option. The Upgrade Assistant prompts for final confirmation. Enter Y to continue with the upgrade: + +```dotnetcli + 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): +``` + +Finally, after the upgrade process is complete, the Upgrade Assistant displays the results of the upgrade process: + +```dotnetcli +Finalizing operation... +Complete: 3 succeeded, 0 failed, 7 skipped. +``` + +:::zone-end + +## 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](https://github.com/dotnet/aspire/issues/new/choose). diff --git a/docs/toc.yml b/docs/toc.yml index 01f3fd0cad..c38c858f5f 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -36,6 +36,8 @@ items: href: get-started/dev-containers.md - name: What's new in Aspire 13 href: https://aspire.dev/whats-new/aspire-13/ + - name: Upgrade to Aspire 13.0 + href: get-started/upgrade-to-aspire-13.md - name: Upgrade to Aspire 9.5.2 href: get-started/upgrade-to-aspire-9.md From 3da8c142186e8bc15f2907d60441faaec6216bbb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 11 Nov 2025 20:18:32 +0000 Subject: [PATCH 3/5] Remove unnecessary zone pivot from CLI update section Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com> --- docs/get-started/upgrade-to-aspire-13.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/get-started/upgrade-to-aspire-13.md b/docs/get-started/upgrade-to-aspire-13.md index fc9888f17c..f2ac8f452d 100644 --- a/docs/get-started/upgrade-to-aspire-13.md +++ b/docs/get-started/upgrade-to-aspire-13.md @@ -34,8 +34,6 @@ The recommended way to upgrade to Aspire 13.0 is using the Aspire CLI. This meth First, update the Aspire CLI to the latest version: -:::zone pivot="visual-studio,dotnet-cli" - # [Bash](#tab/bash) ```bash @@ -50,8 +48,6 @@ Invoke-RestMethod -Uri "https://aspire.dev/install.ps1" | Invoke-Expression --- -:::zone-end - ### Update your Aspire project Update your Aspire project using the `aspire update` command: From 10af2cde3d2b8ff5a3ac15f87d6f134bee046332 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 11 Nov 2025 20:35:44 +0000 Subject: [PATCH 4/5] Remove upgrade-to-aspire-9.md and consolidate into aspire-13 doc Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com> --- .openpublishing.redirection.json | 4 + docs/get-started/upgrade-to-aspire-13.md | 38 ++- docs/get-started/upgrade-to-aspire-9.md | 311 ----------------------- docs/toc.yml | 2 - 4 files changed, 39 insertions(+), 316 deletions(-) delete mode 100644 docs/get-started/upgrade-to-aspire-9.md diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 31ea8958ed..dcf2e015df 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -339,6 +339,10 @@ { "source_path_from_root": "/docs/deployment/aspire-deploy/local-deployment-state.md", "redirect_url": "/dotnet/aspire/deployment/deployment-state-caching" + }, + { + "source_path_from_root": "/docs/get-started/upgrade-to-aspire-9.md", + "redirect_url": "/dotnet/aspire/get-started/upgrade-to-aspire-13" } ] } diff --git a/docs/get-started/upgrade-to-aspire-13.md b/docs/get-started/upgrade-to-aspire-13.md index f2ac8f452d..9058693bdd 100644 --- a/docs/get-started/upgrade-to-aspire-13.md +++ b/docs/get-started/upgrade-to-aspire-13.md @@ -16,7 +16,7 @@ In this article, you learn the steps involved in updating your existing Aspire p > If you're new to Aspire, there's no reason to upgrade anything. For more information, see [Aspire setup and tooling](../fundamentals/setup-tooling.md). > [!NOTE] -> If you're upgrading from Aspire 8.x, follow the [upgrade guide to 9.x](upgrade-to-aspire-9.md) first, then upgrade to 13.0. +> If you're upgrading from Aspire 8.x, you should first upgrade to Aspire 9.x using the Upgrade Assistant or manually, then upgrade to 13.0. Be sure to [remove the legacy Aspire workload](#remove-the-aspire-workload-first-time-upgrades-from-version-8-only) if upgrading from version 8. ## Prerequisites @@ -24,7 +24,7 @@ Before you upgrade your projects to Aspire 13.0, ensure that you have the follow - [Install the latest tooling](../fundamentals/setup-tooling.md). - [Use the Aspire SDK](../fundamentals/dotnet-aspire-sdk.md). -- If you have a version of Aspire older than 9.0, [remove it](upgrade-to-aspire-9.md#remove-the-aspire-workload-first-time-upgrades-from-version-8-only). +- If you have a version of Aspire older than 9.0, [remove the legacy workload](#remove-the-aspire-workload-first-time-upgrades-from-version-8-only). ## Upgrade using the Aspire CLI @@ -72,7 +72,7 @@ dotnet new install Aspire.ProjectTemplates ``` > [!TIP] -> If you have the legacy Aspire workload installed, you need to pass the `--force` flag to overwrite the existing templates. For instructions on uninstalling the legacy workload, see [Remove the Aspire workload](upgrade-to-aspire-9.md#remove-the-aspire-workload-first-time-upgrades-from-version-8-only). +> If you have the legacy Aspire workload installed, you need to pass the `--force` flag to overwrite the existing templates. For instructions on uninstalling the legacy workload, see [Remove the Aspire workload](#remove-the-aspire-workload-first-time-upgrades-from-version-8-only). ## AppHost template updates @@ -323,6 +323,38 @@ Complete: 3 succeeded, 0 failed, 7 skipped. :::zone-end +## 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. + +> [!IMPORTANT] +> You must remove Aspire 8 (the **aspire workload**) to enable the Aspire 9+ templates. + +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 + ``` + +1. Remove Aspire 8. + + - If the **Installation Source** starts with _VS_: + + 1. Open the **Visual Studio Installer** app. + 1. **Modify** the installation instance of Visual Studio. + 1. Select **Individual Components**. + 1. Search for `aspire`. + 1. Unselect **Aspire SDK**. + 1. 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](https://github.com/dotnet/aspire/issues/new/choose). diff --git a/docs/get-started/upgrade-to-aspire-9.md b/docs/get-started/upgrade-to-aspire-9.md deleted file mode 100644 index 0ccbd3be19..0000000000 --- a/docs/get-started/upgrade-to-aspire-9.md +++ /dev/null @@ -1,311 +0,0 @@ ---- -title: Upgrade to Aspire 9.5.2 -description: Learn how to upgrade all your Aspire projects to Aspire 9.5.2. -ms.date: 10/01/2025 -zone_pivot_groups: dev-environment ---- - -# 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. - -> [!TIP] -> If you're new to Aspire, there's no reason to upgrade anything. For more information, see [Aspire setup and tooling](../fundamentals/setup-tooling.md). - -## Prerequisites - -Before you upgrade your projects to Aspire 9.5.2, ensure that you have the following prerequisites: - -- [Install the latest tooling](../fundamentals/setup-tooling.md). -- [Use the Aspire SDK](../fundamentals/dotnet-aspire-sdk.md). -- If you have a version of Aspire older than 9.0, [remove it](#remove-the-aspire-workload-first-time-upgrades-from-version-8-only). - -## Upgrade the Aspire project templates - -Install the latest Aspire project templates by running this command: - -```dotnetcli -dotnet new install Aspire.ProjectTemplates -``` - -> [!TIP] -> If you have the legacy Aspire workload installed, you need to pass the `--force` flag to overwrite the existing templates. For instructions on uninstalling the legacy workload, see [Remove the Aspire workload (first-time upgrades from version 8 only)](#remove-the-aspire-workload-first-time-upgrades-from-version-8-only). - -## 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](xref:dotnet/aspire/app-host) 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](https://www.nuget.org/packages/Aspire.AppHost.Sdk): - -```diff - - -+ - - - Exe - net8.0 - enable - enable - true - 0afc20a6-cd99-4bf7-aae1-1359b0d45189 - - - - - - - -``` - -### 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: - -```diff - - - - - - Exe -- net8.0 -+ net9.0 - enable - enable - true - 0afc20a6-cd99-4bf7-aae1-1359b0d45189 - - - - - - - -``` - -For more information on TFMs, see [Target frameworks in SDK-style projects: Latest versions](/dotnet/standard/frameworks#latest-versions). - -### Overall AppHost project differences - -If you followed all of the preceding steps, your AppHost project file should look like this: - -```diff - - -+ - - - Exe -- net8.0 -+ net9.0 - enable - enable - true - 0afc20a6-cd99-4bf7-aae1-1359b0d45189 - - - -- -+ - - - -``` - -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 - -> [!IMPORTANT] -> If you're still seeing a _Program.cs_, you could change the name of this file to match the templates. Moving forward, an AppHost project contains an _AppHost.cs_ file that acts as the entry point. - -With the introduction of Aspire 9.5, there are some _breaking changes_. Some APIs were originally marked as experimental (with the ) and are now removed, while other APIs are now attributed as 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](../compatibility/9.5/index.md). - -> [!IMPORTANT] -> Be sure to review breaking changes for all versions of Aspire after the one you're upgrading from. For example, if you're upgrading from Aspire 9.0, you must address breaking changes for versions [9.1](../compatibility/9.1/index.md), [9.2](../compatibility/9.2/index.md), [9.3](../compatibility/9.3/index.md), [9.4](../compatibility/9.4/index.md), and [9.5](../compatibility/9.5/index.md). - -## Use the Upgrade Assistant - -The [Upgrade Assistant](/dotnet/core/porting/upgrade-assistant-overview) 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](/dotnet/core/porting/upgrade-assistant-install#visual-studio-extension). -- [The .NET CLI global tool version](/dotnet/core/porting/upgrade-assistant-install#net-global-tool). - -Regardless of how you install the Upgrade Assistant, you can use it to upgrade your Aspire projects to Aspire 9.5.2. - -:::zone pivot="visual-studio" - -To upgrade the Aspire AppHost project to Aspire 9.5.2 with Visual Studio, right-click the project in **Solution Explorer** and select **Upgrade**. - -> [!IMPORTANT] -> If the **Upgrade Assistant** isn't already installed, you'll be prompted to install it. - -The Upgrade Assistant displays a welcome package. Select the **Aspire upgrades** option: - -:::image type="content" source="media/upgrade-assistant-welcome-aspire.png" lightbox="media/upgrade-assistant-welcome-aspire.png" alt-text="Visual Studio: Upgrade Assistant welcome page with Aspire AppHost project."::: - -With the **Aspire upgrades** option selected, the Upgrade Assistant displays the selectable upgrade target components. Leave all the options checked and select **Upgrade selection**: - -:::image type="content" source="media/upgrade-assistant-aspire-app-host-comps.png" lightbox="media/upgrade-assistant-aspire-app-host-comps.png" alt-text="Visual Studio: Upgrade Assistant Aspire selectable components to upgrade."::: - -Finally, after selecting the components to upgrade, the Upgrade Assistant displays the results of the upgrade process. If everything was successful, you see green check marks next to each component: - -:::image type="content" source="media/upgrade-assistant-aspire-upgraded.png" lightbox="media/upgrade-assistant-aspire-upgraded.png" alt-text="Visual Studio: Upgrade Assistant Aspire AppHost project upgraded successfully."::: - -:::zone-end -:::zone pivot="vscode,dotnet-cli" - -To upgrade the Aspire AppHost project, ensure that you installed the Upgrade Assistant CLI. Open a terminal session at the root directory of the Aspire AppHost project file, and run the following command: - -```dotnetcli -upgrade-assistant upgrade -``` - -The output is interactive, expecting you to select the upgrade type. Choose the **Aspire upgrades** option: - -```dotnetcli - 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 -``` - -Use your keyboard to navigate up ↑ or down ↓, and select the **Aspire upgrades** option. The Upgrade Assistant prompts for final confirmation. Enter Y to continue with the upgrade: - -```dotnetcli - 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): -``` - -Finally, after the upgrade process is complete, the Upgrade Assistant displays the results of the upgrade process: - -```dotnetcli -Finalizing operation... -Complete: 3 succeeded, 0 failed, 7 skipped. -``` - -:::zone-end - -### Update the NuGet packages - -To take advantage of the latest updates in your Aspire solution, update all NuGet packages to version `9.5.2`. - -:::zone pivot="visual-studio" - -:::image type="content" source="media/visual-studio-update-nuget.png" lightbox="media/visual-studio-update-nuget.png" alt-text="Visual Studio: Update all NuGet packages for the Aspire solution."::: - -:::zone-end -:::zone pivot="vscode,dotnet-cli" - -To update your AppHost project, use the following .NET CLI command to update the `Aspire.Hosting.AppHost` package to version `9.5.2`: - -```dotnetcli -dotnet add package Aspire.Hosting.AppHost --version 9.5.2 -``` - -When a package reference already exists, the `dotnet add package` command updates the reference to the specified version. For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package). - -:::zone-end - -With the AppHost project updated, your project file should look like this: - -```diff - - - - - - Exe - net8.0 - enable - enable - true - 0afc20a6-cd99-4bf7-aae1-1359b0d45189 - - - -- -+ - - - -``` - -> [!TIP] -> You'll want to also update the NuGet packages in your other projects to the latest versions. - -## 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. - -> [!IMPORTANT] -> You must remove Aspire 8 (the **aspire workload**) to enable the Aspire 9 templates. - -01. 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 - ``` - -01. Remove Aspire 8. - - - If the **Installation Source** starts with _VS_: - - 01. Open the **Visual Studio Installer** app. - 01. **Modify** the installation instance of Visual Studio. - 01. Select **Individual Components**. - 01. Search for `aspire`. - 01. Unselect **Aspire SDK**. - 01. 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](https://github.com/dotnet/aspire/issues/new/choose). diff --git a/docs/toc.yml b/docs/toc.yml index c38c858f5f..b96f047811 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -38,8 +38,6 @@ items: href: https://aspire.dev/whats-new/aspire-13/ - name: Upgrade to Aspire 13.0 href: get-started/upgrade-to-aspire-13.md - - name: Upgrade to Aspire 9.5.2 - href: get-started/upgrade-to-aspire-9.md - name: AppHost items: From c7ff7fb11e0e99d0c9878827888858fec97bfda3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 12 Nov 2025 04:42:27 +0000 Subject: [PATCH 5/5] Add note about Visual Studio support for single-file AppHosts Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com> --- docs/get-started/upgrade-to-aspire-13.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/get-started/upgrade-to-aspire-13.md b/docs/get-started/upgrade-to-aspire-13.md index 9058693bdd..37bd8b0728 100644 --- a/docs/get-started/upgrade-to-aspire-13.md +++ b/docs/get-started/upgrade-to-aspire-13.md @@ -164,6 +164,9 @@ builder.Build().Run(); No project file needed - just a single _.cs_ file with package references declared using `#:package` directives. +> [!NOTE] +> Single-file AppHosts are not currently supported in Visual Studio. Use Visual Studio Code or the command line to work with single-file AppHosts. + ## 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: