使用 .NET Upgrade Assistant（升级助手）升级 .NET 老旧版本项目

.NET Upgrade Assistant 概述

.NET 升级助手是一种工具，旨在帮助用户实现 .NET 应用程序的现代化。

新版本 .NET 全年发布，主要版本每年发布一次。 .NET Upgrade Assistant 升级助手有助于将 .NET、.NET Core 或 .NET Framework 早期版本中的应用升级到最新版本。

.NET 升级助手 是一个 Visual Studio 扩展和命令行工具，旨在帮助将应用升级到最新版本的 .NET。

可以通过选择 “帮助”>“发送反馈”>“报告问题”，在 Visual Studio 中提交与 .NET 升级助手 相关的问题。

关于 .NET 版本发布策略，请查看官方文档

• .NET 支持策略，https://dotnet.microsoft.com/zh-cn/platform/support/policy

.NET Upgrade Assistant 功能

1、支持以下代码语言：

• C#（CSharp）
• Visual Basic

2、支持的 .NET 升级路径：

• .NET Framework 到 .NET
• .NET Core 到 .NET
• UWP 到 WinUI 3
• 任何以前的 .NET 版本到最新 .NET 版本
• Azure Functions v1，v2，v3 到 v4（独立）
• Xamarin Forms 到 .NET MAUI

注意：对于 Xamarin -> MAUI .xaml 文件（XAML 文件）转换仅支持升级基本的命名空间。若要进行更全面的转换，请使用 Visual Studio 2022 版本 17.6 或更高版本。

3、支持的项目类型：

• ASP.NET
• Azure Functions
• WPF
• WinForms
• Class libraries
• Console
• Xamarin.Forms
• .NET MAUI
• UWP

即将推出支持的项目类型（Coming soon）：

• WCF 到 WCF Core 升级

如果遇到任何问题或有改进建议，请在 Visual Studio 中报告反馈（请参阅 报告问题）。

Report a Problem（报告问题）：

• https://learn.microsoft.com/en-us/visualstudio/ide/how-to-report-a-problem-with-visual-studio?view=vs-2022

.NET Upgrade Assistant 安装

1、使用 Visual Studio 扩展安装

选择 VS 菜单栏目，选择 扩展(X) -> 管理扩展(M)... 单机，弹出窗口选择【联机】右上角搜索框输入 .NET Upgrade Assistant 点击回车（Enter）键，显示信息如下：

直接点击下载，等待安装完成即可。

2、手动下载 Visual Studio 插件安装

除了上面使用 Visual Studio 扩展安装的方式，还可以手动下载 Visual Studio 的 .NET Upgrade Assistant 插件，手动安装。

• 扩展插件下载地址，https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.upgradeassistant

手动安装 VSIX 插件显示信息如下：

.NET 升级助手项目升级

注意：下面两种升级方式，如果不使用源代码管理，请确保在升级之前备份项目。

1、使用 Visual Studio 扩展升级

安装 .NET Upgrade Assistant（升级助手）扩展后，右键单击 “解决方案资源管理器” 窗口中的 项目/.csproj，然后选择 “升级/Upgrade”。

将打开一个选项卡，该选项卡根据项目类型提供不同的升级样式：

• 就地项目升级

此选项无需复制即可升级项目。

• 并行项目升级

复制项目并升级副本，从而保留原始项目。

• 并行增量

对于复杂的 Web 应用，这是一个不错的选择。 从 ASP.NET 升级到 ASP.NET Core 需要进行大量的工作，有时还需要手动重构。 此模式将 .NET 项目放在现有 .NET Framework 项目旁，并路由在 .NET 项目中实现的终结点，而所有其他调用将发送到 .NET Framework 应用程序。

此模式允许你逐个缓慢升级 ASP.NET 或库应用。

升级应用后，将显示状态屏幕，其中显示与升级关联的项目相关的所有项目。可以展开每个升级项目，以阅读有关状态的详细信息。

以下列表介绍了状态图标：

• 已填充绿色复选标记：项目已升级并成功完成。
• 未填充绿色复选标记：工具找不到有关要升级的项目的任何内容。
• 黄色警告标志：项目已升级，但应考虑重要信息。
• 红色 X：项目要升级，但升级失败了。

此外，升级助手执行的操作将记录到 “升级助手” 源下的 “输出” 窗口，如下图所示：

注意：升级项目后，需要对其进行全面测试。

2、使用 CLI 工具升级

安装 .NET 升级助手 CLI 工具，执行如下命令：

dotnet tool install -g upgrade-assistant

同样地，由于 .NET 升级助 手是作为 .NET 工具安装的，因此运行以下命令可以轻松地更新它：

dotnet tool update -g upgrade-assistant

注意：如果已配置其他 NuGet 源，则安装此工具可能会失败。

使用 --ignore-failed-sources 参数将这些失败处理为警告而不是错误：

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

若要使用 WCF 组件升级项目，请使用旧版 CLI 工具。 有关详细信息，请参阅安装（旧版本）。

安装旧版本 CLI：

• https://learn.microsoft.com/zh-cn/dotnet/core/porting/upgrade-assistant-install-legacy

安装 .NET 升级助手 CLI 工具后，打开 终端 窗口并导航到包含要升级的项目的目录。 可以使用 upgrade-assistant --help 命令查看 CLI 提供的可用选项。

查看升级助手帮助信息：

PS C:\Users\Jeffrey.Chai> upgrade-assistant --help
USAGE:
    upgrade-assistant [OPTIONS] <COMMAND>

EXAMPLES:
    upgrade-assistant upgrade <PROJECT_PATH>
    upgrade-assistant upgrade <PROJECT_PATH> --operation Inplace --targetFramework net6.0
    upgrade-assistant upgrade <PROJECT_PATH> --operation SideBySide --targetFramework LTS
--destination <NEW_PROJECT_NAME_OR_PATH>

OPTIONS:
    -h, --help       Prints help information
    -v, --version    Prints version information

COMMANDS:
    upgrade    Upgrade project or its features. This command lets you pick upgrade options and
               guides through upgrade process

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

注意！注意！注意！ 升级项目后，需要对其进行全面测试。

关于 .NET Upgrade Assistant 更多信息，请查看相关文档：

• .NET 升级助手概述，https://learn.microsoft.com/zh-cn/dotnet/core/porting/upgrade-assistant-overview
• Github 项目地址，https://github.com/dotnet/upgrade-assistant

通过对 .NET Upgrade Assistant（升级助手） 的介绍，希望该文章能够对您有所帮助，欢迎更多小伙伴尝试使用该工具升级项目，分享更多的项目升级实战经验。