使用 .NET Upgrade Assistant（升级助手）升级 .NET 老旧版本项目
使用 .NET Upgrade Assistant 升级 .NET 老旧版本项目
- .NET Upgrade Assistant 概述
- .NET Upgrade Assistant 功能
-
- 1、支持以下代码语言：
- 2、支持的 `.NET` 升级路径：
- 3、支持的项目类型：
- .NET Upgrade Assistant 安装
-
- 1、使用 Visual Studio 扩展安装
- 2、手动下载 Visual Studio 插件安装
- .NET 升级助手项目升级
-
- 1、使用 Visual Studio 扩展升级
- 2、使用 CLI 工具升级
.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到.NETUWP到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.NETAzure FunctionsWPFWinFormsClass librariesConsoleXamarin.Forms.NET MAUIUWP
即将推出支持的项目类型（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-overviewGithub项目地址，https://github.com/dotnet/upgrade-assistant
通过对 .NET Upgrade Assistant（升级助手） 的介绍，希望该文章能够对您有所帮助，欢迎更多小伙伴尝试使用该工具升级项目，分享更多的项目升级实战经验。