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

从.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>
upgrade <MySolution.sln>
<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​​ 。