使用 .NET 升级助手将.NET Framework应用迁移到.NET 5

Posted 2021-06-19 dotNET跨平台

从.NET Framework 迁移到.NET 5 犹如搬家，我们都知道搬家是很痛苦的，我们请求搬家公司来减轻我们的压力，.NET 升级助手 的作用就类似我们聘请的搬家公司，帮助我们处理繁重乏味的迁移工作。.NET 升级助手是一个全局命令行工具，可以指导你将.NET Framework应用程序迁移到.NET  5, 在这个迁移过程中自动执行几个步骤。.NET升级助手的代码： https://github.com/dotnet/upgrade-assistant/

如果我们的.NET Framework应用程序本身年龄够大，是一座屎山难以修复，.NET 5确是一种采用当今最先进材料构建的现代绿色住宅，.NET 升级助手 能让我们的迁移工作轻松一些，它也不是万能的，没办法帮助我们把系统搞的更好，在我们迁移的过程中还是需要进行一些手动工作的。

.NET 升级助手是一款可以在不同类型的 .NET Framework 应用上运行的命令行工具。它旨在帮助将 .NET Framework 应用升级到 .NET 5。在运行此工具后，大多数情况下，应用将需要更多操作才能完成迁移。此工具会安装可以帮助完成迁移的分析器。

它执行下列任务：

• 添加有助于升级的分析器

• 确定要升级的项目以及升级顺序

• 将你的项目文件更新为 SDK 格式

• 将你的项目重新定位到 .NET 5

• 将 NuGet 包依赖项更新为与 .NET 5 兼容的版本，并删除存在于 .NET 5 中的传递依赖项 packages.config

• 进行 C# 更新以使用其 .NET 5 等效项替换 .NET Framework 模式

• 在适当的地方，添加通用模板文件

该工具目前支持下列 .NET Framework 应用类型：

• .NET Framework Windows 窗体应用

• .NET Framework WPF 应用

• .NET Framework ASP.NET MVC 应用

• .NET Framework 控制台应用

• .NET Framework 类库

我们将通过迁移运行 .NET Framework 4.7.2的版本的 ASP.NET MVC 应用eShopLegacyMVCSolution来评估 .NET 升级助手.

我们使用从电子书“使用 Azure 云和 Windows 容器现代化现有 .NET 应用程序” 的代码  https://github.com/dotnet-architecture/eShopModernizing。

准备工作

在开始使用升级助手之前，请确保您熟悉 Microsoft 的移植文档并了解迁移限制，尤其是在迁移 ASP.NET 应用程序时。此外，您首先使用.NET Portability Analyzer 工具来了解哪些依赖项支持 .NET 5。这就像在搬家之前打电话给搬家公司了解他们是否可以搬家和不搬家以及可能需要多长时间。

在安装 .NET 升级助手之前，您必须确保安装好下列工具：

• Visual Studio 2019 16.8 或更高版本（需要 Visual Studio，因为该工具使用 MSBuild 来处理项目文件）

• .NET 5 SDK

该工具还依赖于try-convert将项目文件转换为 SDK 格式的工具。您必须有版本0.7.212201或更高版本才能使用升级助手。

在命令行下运行以下命令以安装 .NET 升级助手。（它是一个全局工具，因此您可以在任何地方运行该命令。）

dotnet tool install -g try-convert

如果已经安装try-convert但需要升级到较新版本，请执行以下命令：

dotnet tool update -g try-convert

安装 .NET 升级助手

我们现在已准备好安装 .NET 升级助手。为此，请从终端执行以下命令：

dotnet tool install -g upgrade-assistant

安装 .NET 升级助手后，切换到解决方案所在的文件夹并输入以下命令来运行它。

upgrade-assistant upgrade <MySolution.sln>

使用升级助手迁移到 .NET 5

首先，我将从我的终端运行以下命令。（默认命令就可以工作，但是，如果需要，您可以传递其他参数，例如--verbose.）

upgrade-assistant upgrade eShopDotNet5MVC.sln

该工具执行并向我们显示它将执行的步骤。对于流程中的每个步骤，我们可以应用流程中的下一步、跳过它、查看详细信息或配置日志记录。大多数情况下，您需要选择Apply next step。为了节省一些时间，您可以按回车来执行此操作。

当该工具启动时，它会在项目的根目录中放置一个日志文件log.txt

第一步是备份项目。.NET 升级助手会询问您是要为备份使用自定义路径还是默认位置。完成后，我们就可以转换项目文件了。

第二步是将项目文件转换为 SDK 样式，.NET 5 项目使用的是 SDK 格式。在此步骤中，升级助手使用该ry-convert工具将你的项目文件转换为该 SDK 格式。在此过程中，我们看到该工具警告我们一些导入，如System.Web迁移后可能需要手动干预。

第三步是清理Nuget包的引用关系

第四步是更新TFM，.NET 升级助手会将目标框架名称 (TFM) 更新为 .NET 5.0。在我的情况下，值从net472更改为net5.0。

第五步是更新 NuGet 包，升级助手更新 TFM 后，它会尝试更新项目的 NuGet 包。该工具使用分析器来检测要删除的引用以及要使用.NET 5版本升级的软件包。然后，该工具更新包。

第六步是添加模板文件，该工具更新任何 NuGet 包后，它会添加任何相关模板文件。ASP.NET Core 使用模板文件进行配置和启动。这通常包括Program.cs，Startup.cs，appsettings.json和appsettings.development.json。

第七步是迁移应用程序配置文件，现在升级助手已准备好迁移我们的应用程序配置文件。该工具确定支持哪些设置，然后将任何可配置的设置迁移到我的appSettings.json文件中。完成后，该工具system.web.webPages.razor/pages/namespaces通过_ViewImports.cshtml使用对 的@addTagHelper引用进行更新来迁移Microsoft.AspNetCore.Mvc.TagHelpers。

第八步是更新Razor 文件，修复Razor 文件里面的代码

第九步是更新 C# 源代码，.NET升级助手将C＃代码引用升级到其.NET Core 版本。您会在终端中看到列出的几个步骤 - 并非所有步骤都适用。在这些情况下，它们将被跳过并标记为[Complete].

就这个例子来说，该步骤首先删除任何using引用 .NET Framework 命名空间的语句，例如System.Web. 然后，它确保我的ActionResult调用来自Microsoft.AspNetCore.Mvc命名空间。最后，升级助手确保我不使用ASP.NET Core 不支持的HttpContext.Current 。

最后一步是评估下一个项目。由于我们的解决方案只有一个项目，因此该工具退出。

现在工具已经帮我们完成大部分的迁移工作了，最后一步就是要我们手动修复剩余的问题了。仍然需要整理一些东西。大多数这些问题涉及 ASP.NET Core 如何处理启动、配置和捆绑。

• 在ASP.NET Core不再需要Global.asax和Global.asax.cs文件， ASP.NET Core的Startup.cs 依赖注入模式替换了全球应用程序事件模型。

• 您不需要的App_Start文件夹或其中的任何文件（BundleConfig.cs，FilterConfig.cs和RouteConfig.cs），继续把它删除了。

• 执行此操作后，您剩下的大部分错误都与静态资源的捆绑有关。ASP.NET Core 可与多种捆绑解决方案配合使用。阅读捆绑文档并选择最适合您的项目的方法。

• 最后，解决任何仍然存在的问题。这个示例的变化很小。例如，在我的_Layout.cshtml文件中，我们必须注入一个IHttpContextAccessor来访问HttpContext.Session并且我还需要清理一些ActionResult响应。

虽然升级助手可以满足您的大部分用例，但它有一个可选的辅助功能模型，允许您自定义升级步骤，而无需自己修改工具。例如，您可以将NuGet软件包显式映射到其替换版本，添加自定义模板文件并添加自定义升级步骤。

首先，您将包含一个ExtensionManifest.json文件，该文件定义工具在何处找到不同的扩展项。您需要一个清单，但以下所有元素都是可选的，因此您可以仅定义您需要的内容，具体请参考文档 https://github.com/dotnet/upgrade-assistant/blob/main/docs/extensibility.md 。