升级到 .NET.NET Aspire 9.0

项目
12/16/2024

.NET .NET Aspire 9.0 现已正式发布。在本文中，你将了解将现有 .NET Aspire 8.x 项目更新到 .NET Aspire 9.0 所涉及的步骤。可通过几种方法将项目更新为 .NET.NET Aspire 9.0：

手动将项目升级到 .NET.NET Aspire 9.0。
使用 升级助手 将项目升级到 .NET.NET Aspire 9.0。

提示

如果你刚接触 .NET.NET Aspire，则没有理由升级任何东西。有关详细信息，请参阅 .NET.NET Aspire 设置和工具。

先决条件

在将项目升级到 .NET.NET Aspire 9.0 之前，请确保满足以下先决条件：

注意

可以随意卸载 .NET.NET Aspire 工作负载，因为不再需要它。

dotnet workload uninstall aspire

有关详细信息，请参阅 dotnet 工作负荷卸载。

如果未卸载 .NET.NET Aspire 工作负载，并且使用的是新的 .NET.NET Aspire SDK 和模板，则会看到 .NET Aspire 8.0 和 .NET Aspire 9.0 模板。

手动升级到 .NET.NET Aspire 9.0

若要将项目升级到 .NET.NET Aspire 9.0，需要更新项目文件。以下步骤将指导你完成该过程：

编辑应用主机项目文件以使用新的 .NET.NET Aspire 9.0 SDK（Aspire.AppHost.Sdk）。
将项目文件中的 NuGet 包更新到最新版本。
调整 Program.cs 文件以使用新 API 并删除任何过时的 API。

编辑应用主机项目文件

若要将应用主机项目升级到 .NET.NET Aspire 9.0，需要更新项目文件以使用新的 📦Aspire。AppHost.Sdk：

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

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

  <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" />
  </ItemGroup>

</Project>

可选升级目标框架标识符 (TFM)

.NET Aspire 9.0 在 .NET 9.0 上运行，但也可以在 .NET 8.0 上运行它。换句话说，仅仅因为你使用的是 .NET Aspire SDK，并且指向版本 9.0 包，你仍然可以将 .NET 8.0 为目标。如果要在 .NET Aspire 9.0 上运行 .NET 9.0 项目，则需要更新项目文件中的 TargetFramework 属性：

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

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

  <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.0.0" />
  </ItemGroup>

</Project>

有关 TFM 的详细信息，请参阅 SDK 样式项目中目标框架：最新版本。

应用程序托管项目的总体差异

如果已执行上述所有步骤，则应用主机项目文件应如下所示：

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

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

  <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.0.0" />
  </ItemGroup>

</Project>

这些更改包括添加 Aspire.AppHost.Sdk、将 TargetFramework 属性更新为 net9.0，以及将 Aspire.Hosting.AppHost 包更新到版本 9.0.0。

调整 Program.cs 文件

随着 .NET.NET Aspire 9.0 的引入，出现了一些 重大更改。某些 API 最初标记为实验性（带有 ExperimentalAttribute），现已删除，而其他 API 现在被归为 ObsoleteAttribute，其中包含有关新替换 API 的详细信息。需要调整 Program.cs 文件（以及可能受影响的其他 API）才能使用新 API。如果使用升级助手升级项目，则在大多数情况下，它会自动调整 Program.cs 文件。

有关 9.0 中重大更改的完整列表，请参阅 9.0中的重大更改。

使用升级助手

升级助手是一种工具，可帮助将目标项目升级到最新版本。如果你是第一次使用升级助手程序，有两种模式可供选择：

无论如何安装升级助手，都可以使用它将 .NET Aspire 8.x 项目升级到 .NET Aspire 9.0。

若要使用将应用主机项目升级到 9.0，请在解决方案资源管理器中右键单击该项目，然后选择升级。

重要

如果尚未安装 升级助手，系统会提示你安装它。

升级助手显示欢迎礼包。选择 Aspire 升级 选项：

选中 Aspire 升级 选项后，升级助手将显示可选择的升级目标组件。请保持所有选项已选中并选择 升级选择：

最后，选择要升级的组件后，升级助手会显示升级过程的结果。如果一切成功，则会看到每个组件旁边的绿色复选标记：

若要升级 .NET.NET Aspire 应用主机项目，请确保已安装升级助手 CLI。在 .NET.NET Aspire 应用主机项目文件的根目录中打开终端会话，并运行以下命令：

upgrade-assistant upgrade

输出是交互式的，希望你选择升级类型。选择 Aspire 升级 选项：

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

使用键盘向上导航或向下导航，然后选择 Aspire 升级选项。升级助手会提示进行最终确认。输入 Y 继续升级：

 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.

更新 NuGet 包

若要利用 .NET.NET Aspire 解决方案中的最新更新，请将所有 NuGet 包更新为版本 9.0.0。

若要更新应用主机项目，请使用以下 .NET CLI 命令将 Aspire.Hosting.AppHost 包更新为版本 9.0.0：

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

当包引用已存在时，dotnet add package 命令将更新对指定版本的引用。有关详细信息，请参阅 dotnet add package。

更新应用主机项目后，项目文件应如下所示：

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

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

  <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.0.0" />
  </ItemGroup>

</Project>

提示

还需要将其他项目中的 NuGet 包更新到最新版本。

验证升级

与任何升级一样，请确保应用按预期运行，并且所有测试都通过。生成解决方案，并在输出窗口中查找建议、警告或错误- 解决以前未出现问题的任何内容。如果遇到任何问题，请通过提交 GitHub 问题告知我们。

通过