.NET 升級小幫手的概觀

  • 發行項

新版的 .NET 會全年發行，主要版本每年發行一次。 .NET 升級助理可協助您將舊版 .NET、.NET Core 和 .NET Framework 的應用程式升級至最新版本。

.NET 升級助理是 Visual Studio 擴充功能和命令列工具，其設計目的是協助將應用程式升級至最新版的 .NET。

您可以選取說明>傳送意見反應>報告問題，在 Visual Studio 中提出 .NET 升級助理的相關問題。

安裝升級助理

.NET 升級小幫手可以安裝為 Visual Studio 延伸模組或 .NET 命令列工具。 如需詳細資訊，請參閱安裝 .NET 升級助理。

支援的語言

支援下列程式碼語言：

  • C#
  • Visual Basic

支援的專案

支援下列專案類型：

  • ASP.NET
  • Azure Functions
  • Windows Presentation Foundation
  • Windows Forms
  • 類別庫
  • 主控台應用程式
  • .NET Native UWP
  • Xamarin Forms
  • .NET MAUI

升級路徑

下列是支援的升級路徑：

  • .NET Framework 至 .NET
  • .NET Core 至 .NET
  • UWP 至 WinUI 3
  • 舊版 .NET 至最新版 .NET
  • Azure Functions v1-v3 至 v4 已隔離
  • Xamarin Forms 至 .NET MAUI
    • XAML 檔案轉換僅支援升級命名空間。 如需更全面的轉換，請使用 Visual Studio 2022 17.6 版或更新版本。

使用 Visual Studio 擴充功能升級

安裝 .NET 升級助理擴充功能之後，以滑鼠右鍵按一下 [方案總管] 視窗中的專案，然後選取 [升級]。

警告

如果您未使用原始檔控制，請務必先備份專案再升級。

The .NET Upgrade Assistant's Upgrade menu item in Visual Studio.

隨即開啟索引標籤，根據專案類型提供不同的升級樣式：

  • 就地專案升級

    此選項會升級專案，而不進行複製。

  • 並存專案升級

    複製專案並升級複本，只留下原始專案。

  • 並存累加

    對於複雜的 Web 應用程式而言，是不錯的選擇。 從 ASP.NET 升級至 ASP.NET Core 需要相當多的工作，有時需要手動重構。 此模式會將 .NET 專案放在您現有的 .NET Framework 專案旁邊，並路由傳送在 .NET 專案中實作的端點，而所有其他呼叫都會傳送至 .NET Framework 應用程式。

    此模式可讓您逐一升級 ASP.NET 或程式庫應用程式。

升級應用程式之後，會顯示狀態畫面，其中會顯示與升級相關聯之專案相關的所有成品。 您可以展開每個升級成品，以閱讀狀態的詳細資訊。 下列清單描述狀態圖示：

  • 填滿的綠色核取記號：成品已升級並順利完成。
  • 未填滿的綠色核取記號：此工具找不到任何與要升級之成品相關的資訊。
  • 黃色警告符號：成品已升級，但有您應該考慮的重要資訊。
  • 紅色 X：成品本應升級，但升級失敗。

The .NET Upgrade Assistant's Upgrade results tab in Visual Studio.

此外，如下圖所示，升級助理執行的動作會記錄到升級助理來源下的 [輸出] 視窗：

The output window in Visual Studio showing the results from the .NET Upgrade Assistant.

升級專案之後，您必須徹底測試專案。

使用 CLI 工具升級

安裝 .NET 升級助理 CLI 工具之後，請開啟終端視窗，並瀏覽至內含您要升級之專案的目錄。 您可以使用 upgrade-assistant --help 命令，來檢視 CLI 所提供的可用選項。

警告

如果您未使用原始檔控制，請務必先備份專案再升級。

使用 upgrade-assistant upgrade 命令執行此工具，其中會列出目前資料夾和下方的所有專案。 CLI 工具提供互動式方式，讓您選擇要升級的專案。 使用方向鍵來選取項目，然後按 Enter 鍵來執行項目。 選取您要升級的專案。 在本文提供的範例中，目前資料夾下有四個專案：

 Selected options
───────────────────────────────────────────────────────────
 No options specified, follow steps below to continue

 Steps
─────────────────
 Source project
─────────────────

Which project do you want to upgrade (found 9)?

> MatchingGame (winforms\MatchingGame\MatchingGame.csproj)
  MatchingGame.Logic (winforms\MatchingGame.Logic\MatchingGame.Logic.csproj)
  StarVoteControl (csharp\StarVoteControl\StarVoteControl.csproj)
  WebSiteRatings (csharp\WebSiteRatings\WebSiteRatings.csproj)

  Navigation
    Exit

視您升級的專案而定，您可能會看到一個選項，可指定升級應該如何繼續：

  • 就地專案升級

    此選項會升級專案，而不進行複製。

  • 並存專案升級

    此選項僅適用於 .NET Framework 專案。 複製專案並升級複本，只留下原始專案。

 Selected options
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Source project     C:\Code\winforms\MatchingGame\MatchingGame.csproj

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

How do you want to upgrade project MatchingGame?

> In-place project upgrade
  Side-by-side project upgrade

  Navigation
    Back
    Exit

在此步驟之後，如果有一個以上的可升級目標架構，您將選擇目標：

 Selected options
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Source project     C:\Code\Work\dotnet\dotnet-docs\docs\core\porting\snippets\upgrade-assistant-wpf-framework\winforms\MatchingGame\MatchingGame.csproj
 Ugrade type        Inplace

 Steps
──────────────────────────────────────────────────
 Source project / Ugrade type / Target framework
──────────────────────────────────────────────────

What is your preferred target framework?

> .NET 6.0 (Supported until November, 2024)
  .NET 7.0 (Supported until May, 2024)
  .NET 8.0 (Try latest preview features)

  Navigation
    Back
    Exit

升級專案之後，您必須徹底測試專案。