@ 目录
1、支持以下代码语言
2、支持的 .NET 升级路径
3、支持的项目类型
1、使用 Visual Studio 扩展安装
2、手动下载 Visual Studio 插件安装
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
到.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-overviewGithub
项目地址,https://github.com/dotnet/upgrade-assistant

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