升級至 .NET.NET Aspire 9.0

發行項
12/13/2024

.NET .NET Aspire 9.0 現已正式推出。在本文中，您將瞭解將現有 .NET Aspire 8.x 專案更新至 .NET Aspire 9.0 時所涉及的步驟。有幾種方式可將專案更新為 .NET.NET Aspire 9.0：

手動將項目升級至 .NET.NET Aspire 9.0。
使用 Upgrade Assistant 將您的項目升級至 .NET.NET Aspire 9.0。

提示

如果您不熟悉 .NET.NET Aspire，則沒有理由升級任何東西。如需詳細資訊，請參閱 .NET.NET Aspire 安裝和工具。

先決條件

將項目升級至 .NET.NET Aspire 9.0 之前，請確定您具備下列必要條件：

注意

您可以隨意卸載 .NET.NET Aspire 工作負載，因為您不再需要它。

dotnet workload uninstall aspire

如需詳細資訊，請參閱 dotnet workload uninstall。

如果您未卸載 .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中的重大變更。

使用升級小幫手

Upgrade Assistant 是一種工具，可協助將目標項目升級至最新版本。如果您是升級助理的新手，有兩種模式可供選擇：

不論您安裝升級小幫手的方式為何，您都可以用它來將 .NET Aspire 8.x 項目升級為 .NET Aspire 9.0。

若要使用將應用程式主項目升級至 9.0，請在 [方案總管] 中以滑鼠右鍵按兩下專案，然後選取 [升級]。

重要

如果尚未安裝 升級小幫手，系統會提示您安裝它。

升級小幫手會顯示歡迎套件。選取 Aspire 升級 選項

選取 [Aspire 升級] 選項后，[升級小幫手] 會顯示可選取的升級目標元件。保留所有選項的核取狀態，然後選取 升級選項。

最後，選取要升級的元件之後，升級小幫手會顯示升級程序的結果。如果一切成功完成，您會看到每個元件旁的綠色打勾符號。

若要升級 .NET.NET Aspire 應用程式主機專案，請確定您已安裝Upgrade Assistant 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 問題，讓我們知道。

共用方式為