.NET 升級小幫手的概觀

  • 發行項

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

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

選取 [說明>傳送意見> 反應報告問題]，即可在 Visual Studio 中提出與 .NET 升級小幫手相關的問題。

安裝升級小幫手

.NET 升級小幫手可以安裝為 Visual Studio 擴充功能或 .NET 命令列工具。 如需詳細資訊，請參閱 安裝 .NET Upgrade Assistant。

支援的語言

支援下列程式碼語言：

  • 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 Upgrade Assistant 擴充功能之後，請在[方案總管] 視窗中以滑鼠右鍵按一下專案，然後選取 [升級]。

警告

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

Visual Studio 中的 .NET 升級小幫手 [升級] 功能表項目。

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

  • 就地專案升級

    此選項會升級您的專案，而不進行複本。

  • 並存專案升級

    複製專案並升級複本，讓原始專案保持獨立。

  • 並存累加

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

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

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

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

Visual Studio 中的 .NET 升級小幫手 [升級結果] 索引標籤。

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

Visual Studio 中的輸出視窗，顯示 .NET 升級小幫手的結果。

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

使用 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

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