使用舊版 .NET 升級小幫手

發行項
02/25/2024

在本文中，您將了解如何安裝和執行舊版的 .NET 升級小幫手命令列介面 (CLI) 工具。從 0.5.2 版開始，.NET 升級小幫手 CLI 工具的程式碼基底是基於 Visual Studio 延伸模組重訂基底。這意味著實際上有兩種不同的 CLI 工具：0.5.2 之前的版本 (稱為舊版本) 與 0.5.2+ 版本 (稱為目前版本)。

舊版本具有新版本中尚未提供的一些功能 (例如分析命令或解決方案層級升級)，但也缺少新版本 (0.5.2+) 中可用的新改進功能。因此，您可能想要在目前版本的功能和範圍增加之前繼續使用它。

提示

該工具的舊版本可以升級方案檔。

安裝舊版本

該工具的舊版本的安裝方式與目前版本相同，不同的只是您指定版本 0.4.421302：

dotnet tool install upgrade-assistant -g --version 0.4.421302

重要

若您已設定其他 NuGet 摘要來源，安裝此工具則可能會失敗。使用 --ignore-failed-sources 參數將這些失敗視為警告，而不是錯誤：

dotnet tool install upgrade-assistant -g --ignore-failed-sources --version 0.4.421302

分析您的程式碼

該工具的舊版本包含一個分析模式，可以執行升級應用程式的簡化試執行。其可能會提供見解，讓您能夠了解開始升級之前可能需要哪些變更。開啟終端，然後瀏覽至目標專案或解決方案所在的資料夾。執行 upgrade-assistant analyze 命令，傳入您要升級的專案或解決方案名稱。

例如，以下是對 .NET Framework WPF 應用程式執行分析模式之後的輸出：

> upgrade-assistant analyze .\WebSiteRatings.sln

[15:39:00 INF] Loaded 9 extensions
[15:39:02 INF] Using MSBuild from C:\Program Files\dotnet\sdk\7.0.201\
[15:39:02 INF] Using Visual Studio install from C:\Program Files\Microsoft Visual Studio\2022\Preview [v17]
[15:39:05 INF] Writing output to C:\code\migration\AnalysisReport.sarif
[15:39:06 INF] Recommending Windows TFM net7.0-windows for project WebSiteRatings.csproj because the project either has Windows-specific dependencies or builds to a WinExe
[15:39:06 INF] Marking assembly reference System.Configuration for removal based on package mapping configuration System.Configuration
[15:39:06 INF] Adding package System.Configuration.ConfigurationManager based on package mapping configuration System.Configuration
[15:39:08 INF] Package EntityFramework, Version=6.2.0 does not support the target(s) net7.0-windows but a newer version (6.4.4) does.
[15:39:09 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added
[15:39:10 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs
[15:39:13 INF] Recommending Windows TFM net7.0-windows for project StarVoteControl.csproj because the project either has Windows-specific dependencies or builds to a WinExe
[15:39:13 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added
[15:39:13 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs
[15:39:13 INF] Running analyzers on WebSiteRatings
[15:39:14 INF] Identified 0 diagnostics in project WebSiteRatings
[15:39:14 INF] Running analyzers on StarVoteControl
[15:39:15 INF] Identified 0 diagnostics in project StarVoteControl
[15:39:15 INF] Analysis Complete, the report is available at C:\code\migration\AnalysisReport.sarif

輸出中有相當多的內部診斷資訊，但有些資訊很實用。請注意，該分析模式指示在升級期間，專案的目標 Framework Moniker (TFM) 將設定為 net7.0-windows，而不是 net7.0。提出此建議是因為解決方案所參考的專案是 WPF 專案，這是僅限 Windows 的技術。主控台應用程式可能會直接升級到 TFM net7.0 (除非它使用某個 Windows 特定的程式庫或程式碼)。

執行升級小幫手

開啟終端，然後瀏覽至目標專案或解決方案所在的資料夾。執行 upgrade-assistant upgrade 命令，傳入您要升級的專案或解決方案名稱。

當該工具執行時，它會顯示其執行以升級專案的步驟清單。完成每個步驟後，該工具會提供一組編號的命令，讓使用者套用或跳過下一個步驟。它可能會提供其他選項，例如：

取得有關此步驟的詳細資訊。
變更專案。
調整記錄設定。
停止升級並結束。

按 Enter 而不選擇數字會選取清單中的第一個項目。

當每個步驟初始化後，該工具可能會提供您套用該步驟後它認為會發生之狀況的相關資訊。

升級解決方案

當您升級包含多個專案的解決方案時，您必須選取解決方案中的哪一個專案是進入點。根據進入點專案，建立相依性關係圖來判斷要升級的專案，以及依何種順序進行升級。如果解決方案包含不屬於相依性關係圖的一部分的專案，則會忽略它們，而您必須個別升級這些專案。相依性會先升級，然後再升級進入點專案。

下一個步驟是選擇要升級的專案。您應該會看到類似下列程式碼片段的輸出：

Upgrade Steps

1. [Next step] Select an entrypoint
2. Select project to upgrade

Choose a command:
   1. Apply next step (Select an entrypoint)
   2. Skip next step (Select an entrypoint)
   3. See more step details
   4. Configure logging
   5. Exit

提示

請注意每個步驟的輸出，因為它可能包含工具無法升級之內容的相關資訊。根據應用程式的複雜度而定，您可能要在工具完成之後執行更多升級工作。

升級專案

選取專案後，即會顯示升級步驟的清單。選取第一個步驟，此步驟是備份專案。步驟清單看起來類似下列程式碼片段：

[15:50:50 INF] Initializing upgrade step Back up project

Upgrade Steps

Entrypoint: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj
Current Project: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj

1. [Next step] Back up project
2. Convert project file to SDK style
3. Clean up NuGet package references
    a. Duplicate reference analyzer
    b. Package map reference analyzer
    c. Target compatibility reference analyzer
    d. Upgrade assistant reference analyzer
    e. Windows Compatibility Pack Analyzer
    f. MyDotAnalyzer reference analyzer
    g. Newtonsoft.Json reference analyzer
    h. Windows App SDK package analysis
    i. Transitive reference analyzer
4. Update TFM
5. Update NuGet Packages
    a. Duplicate reference analyzer
    b. Package map reference analyzer
    c. Target compatibility reference analyzer
    d. Upgrade assistant reference analyzer
    e. Windows Compatibility Pack Analyzer
    f. MyDotAnalyzer reference analyzer
    g. Newtonsoft.Json reference analyzer
    h. Windows App SDK package analysis
    i. Transitive reference analyzer
6. Add template files
7. Update WCF service to CoreWCF (Preview)
8. Upgrade app config files
    a. Convert Application Settings
    b. Convert Connection Strings
    c. Disable unsupported configuration sections
9. Update source code
    a. Apply fix for UA0002: Types should be upgraded
    b. Apply fix for UA0012: 'UnsafeDeserialize()' does not exist
10. Move to next project

Choose a command:
   1. Apply next step (Back up project)
   2. Skip next step (Back up project)
   3. See more step details
   4. Select different project
   5. Configure logging
   6. Exit

每個步驟都會先詳細說明它將執行的動作，然後提示您執行該動作。當該工具到達該步驟時，會跳過任何不適用的步驟。例如，若此工具要處理 7. 將 WCF 服務更新為 CoreWCF (預覽)，但您的應用程式未定義 WCF 服務，則會略過此步驟，然後處理步驟 8。接著，若步驟 8 不適用，也會略過。當此工具嘗試尋找下一個適用的步驟時，您可能會看到已略過許多步驟。

最後步驟

當您升級專案之後，必須編譯並測試它們。很可能還需要執行更多的工作才能完成升級。您的應用程式的 .NET Framework 版本可能包含您的專案實際未使用的程式庫參考，而它們被繼續保留。分析每個參考，並判斷是否需要參考。此工具可能也已將 NuGet 套件參考新增或升級至錯誤的版本。

最後，尋找讓您的應用程式現代化的方式。如需範例，請參閱從 .NET Framework 升級至 .NET 之後的現代化

共用方式為