.NET 升级助手新增了第三方 API 和包映射支持

作者：Marco Goertz

排版：Alan Wang

.NET 升级助手是一个 Visual Studio 扩展和命令行工具，可帮助您将应用从之前的 .NET 和 .NET Framework 升级到最新版本的 .NET。正如我们在之前的文章中所描述的那样，它为升级 Microsoft 库和框架提供了强大的支持。我们很高兴地宣布增加了第三方 API 和包映射支持，这将允许您能够在升级过程中轻松找到过时的第三方 API 和包并将其替换为较新的版本。此新功能简化了向新平台（如从 UWP 到 WinUI 或从 Xamarin Forms 到 .NET MAUI）的过渡，确保了更顺畅、更高效的升级体验。

什么是第三方 API 和包映射支持？

将旧应用程序升级到最新版本的 .NET 的挑战之一是从第三方库中找到等效的 API 和 NuGet 包。当您还要升级到一个新平台时，这尤其具有挑战性，例如从 UWP 升级到 WinUI 或从 Xamarin Forms 升级到 .NET MAUI。对于后者，您需要将 Xamarin.Forms 命名空间替换为 Microsoft.Maui 和/或 Microsoft.Maui.Controls。

但这仅仅是个开始。除了命名空间之外，类型和方法通常也不同，因此您可能需要对代码进行一些更改才能使用新的 API。让我们以 Xamarin.Forms.Color 为例。您不仅需要将命名空间从 Xamarin.Forms 更新为 Microsoft.Maui.Graphics，还需要将 R、G 或 B 等属性更改为 Red、Green 或 Blue，而且静态 Color 属性（例如 AliceBlue）现在属于一个新类型 Colors。为了帮助您完成此任务，.NET 升级助手包含了一套全面的 Microsoft 拥有库的已知映射。但是您可能使用的所有流行的第三方库怎么办？第三方可以为自己的库提供映射吗？

是的，可以！.NET 升级助手现在支持第三方 API 和包映射。此功能允许任何人为其自己的库指定映射，其中包含有关旧 API 和包以及新 API 和包的信息。升级助手将在升级期间使用这些映射以及内置映射来进行代码和项目更改。

如何创建 API 和包映射

若要为 .NET 升级助手创建第三方 API 映射，您需要执行以下操作：

• 首先阅读 upgrade-assistant github repo 中的 README.md 文件

• 克隆 repo 并在 Visual Studio 中打开 UpgradeAssistant.Extensions.sln

• 在 UpgradeAssistant.Mappings 项目的 mappings 下为您的公司创建一个新文件夹，并在其中为您的库创建一个子文件夹

• 为您的库添加 *.apimap.json 和 *.packagemap.json 文件（使用示例或任何现有映射作为起点）

• 通过运行 Pack 命令为映射创建 NuGet 包

这会在项目的输出文件夹中创建一个 Microsoft.UpgradeAssistant.Mappings NuGet 包。

README.md

https://github.com/dotnet/upgrade-assistant

如何测试 API 和包映射

若要使用为 .NET 升级助手创建的映射测试 NuGet 包，您需要执行以下步骤：

1. 确保您拥有来自 Visual Studio Marketplace 的最新版本的 .NET 升级助手扩展

2. 创建/打开一个使用您新映射中指定的 API 和包的测试项目，以进行升级

3. 设置本地源文件夹，例如 C:\LocalFeed

4. 将之前创建的 Microsoft.UpgradeAssistant.Mappings 包添加到本地源，通过在输出文件夹中运行以下命令：

nuget add Microsoft.UpgradeAssistant.Mappings.1.0.0.nupkg -source C:\LocalFeed

5. 在第二步的测试项目的解决方案文件夹中创建一个 Nuget.config 文件，内容如下：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="Local Feed" value="C:\LocalFeed" />
  </packageSources>
</configuration>

6. 运行升级助手来升级测试项目

API 和包将根据您创建的映射进行升级。

.NET 升级助手扩展

https://devblogs.microsoft.com/dotnet/announcing-api-map-support-for-ua/

接下来发生什么？

一旦您验证了新映射按预期工作后，我们鼓励您在 upgrade-assistant github repo 中创建拉取请求。我们将审核您的更改，合并后，CI/CD 管道将创建一个新的 Microsoft.UpgradeAssistant.Mappings 包并将其发布在 nuget.org 上。发布后，现有的 .NET Upgrade Assistant 安装将在升级期间包含新映射。

upgrade-assistant

https://github.com/dotnet/upgrade-assistant

nuget.org

https://www.nuget.org/

您正在手动升级到 .NET MAUI 吗？

如果是这样，您是否知道 .NET 升级助手扩展包含用于 Xamarin.Forms -> .NET MAUI 升级的 C# 分析器和代码修复程序？它可以帮助您手动升级从 Xamarin.Forms 项目复制到 .NET MAUI 项目的代码。分析器会查找 Xamarin.Forms 命名空间，轻量级代码修复工具会根据内置映射以及新的第三方 API 映射应用代码更改。您可以试一试。

总结

第三方 API 和包映射支持是一项新功能，它扩展了 .NET 升级助手的功能，以帮助升级具有第三方库依赖项的项目。您可以通过创建和共享库的升级映射来为 .NET 开发者社区做出贡献。

我们希望此功能对您有用，我们欢迎您通过评论此博客文章或在升级助手 github 存储库中提供反馈和建议。

升级助手

https://github.com/dotnet/upgrade-assistant