.NET 升级助手概述

  • 项目

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

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

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

安装升级助手

.NET 升级助手可以作为 Visual Studio 扩展或 .NET 命令行工具安装。 有关详细信息，请参阅安装 .NET 升级助手。

支持的语言

支持以下代码语言：

  • C#
  • Visual Basic

支持的项目

支持以下项目类型：

  • ASP.NET
  • Azure Functions
  • Windows Presentation Foundation
  • Windows 窗体
  • 类库
  • Console 应用程序
  • .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 升级助手扩展后，右键单击“解决方案资源管理器”窗口中的项目，然后选择“升级”。

注意

如果不使用源代码管理，请确保在升级之前备份项目。

The .NET Upgrade Assistant's Upgrade menu item in Visual Studio.

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

  • 就地项目升级

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

  • 并行项目升级

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

  • 并行增量

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

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

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

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

The .NET Upgrade Assistant's Upgrade results tab in Visual Studio.

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

The output window in Visual Studio showing the results from the .NET Upgrade Assistant.

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

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

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