作者：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 包
如何測試 API 和包映射
若要使用為 .NET 升級助手創建的映射測試 NuGet 包，您需要執行以下步驟：
-
確保您擁有來自 Visual Studio Marketplace 的最新版本的 .NET 升級助手擴展
-
創建/打開一個使用您新映射中指定的 API 和包的測試項目，以進行升級
-
設置本地源文件夾，例如 C:\LocalFeed
-
將之前創建的 Microsoft.UpgradeAssistant.Mappings 包添加到本地源，通過在輸出文件夾中運行以下命令：
nuget add Microsoft.UpgradeAssistant.Mappings.1.0.0.nupkg -source C:\LocalFeed
- 在第二步的測試項目的解決方案文件夾中創建一個 Nuget.config 文件，內容如下：
<?xml version="1.0" encoding="utf-8"?>
<configuration><packageSources><add key="Local Feed" value="C:\LocalFeed" /></packageSources>
</configuration>
- 運行升級助手來升級測試項目
API 和包將根據您創建的映射進行升級。
接下來發生什么？
一旦您驗證了新映射按預期工作后，我們鼓勵您在 upgrade-assistant github repo 中創建拉取請求。我們將審核您的更改，合并后，CI/CD 管道將創建一個新的 Microsoft.UpgradeAssistant.Mappings 包并將其發布在 nuget.org 上。發布后，現有的 .NET Upgrade Assistant 安裝將在升級期間包含新映射。
您正在手動升級到 .NET MAUI 嗎？
如果是這樣，您是否知道 .NET 升級助手擴展包含用于 Xamarin.Forms -> .NET MAUI 升級的 C# 分析器和代碼修復程序？它可以幫助您手動升級從 Xamarin.Forms 項目復制到 .NET MAUI 項目的代碼。分析器會查找 Xamarin.Forms 命名空間，輕量級代碼修復工具會根據內置映射以及新的第三方 API 映射應用代碼更改。您可以試一試。
總結
第三方 API 和包映射支持是一項新功能，它擴展了 .NET 升級助手的功能，以幫助升級具有第三方庫依賴項的項目。您可以通過創建和共享庫的升級映射來為 .NET 開發者社區做出貢獻。
我們希望此功能對您有用，我們歡迎您通過評論此博客文章或在升級助手 github 存儲庫中提供反饋和建議。
