.NET Upgrade Assistant tool received an update last month introducing Third-Party API and Package Map Support to simplify the upgrade process by identifying and replacing outdated third-party APIs and packages with their updated versions. Microsoft states that the new feature aims to ease transitions between platforms, such as from UWP to WinUI or from Xamarin Forms to .NET MAUI.
Furthermore, Microsoft aims to help developers upgrade older applications to the latest version of .NET, which often presents the challenge of locating equivalent APIs and NuGet packages from third-party libraries, noting that the task becomes even more complex when migrating to a new platform.
To address these complexities, the .NET Upgrade Assistant now includes a set of mappings for Microsoft-owned libraries. Notably, this tool now also supports third-party API and package maps, enabling third-party developers to specify mappings for their libraries. These mappings detail the old and new APIs and packages, allowing the Upgrade Assistant to apply necessary code and project changes during an upgrade for developers.
As stated in the original announcement post, to create third-party API maps for the .NET Upgrade Assistant, developers should start by reading the README.md in the upgrade-assistant GitHub repository. They should then clone the repository and open UpgradeAssistant.Extensions.sln in Visual Studio.
Next, they need to create a new folder for their company with a subfolder for their library under mappings in the UpgradeAssistant.Mappings project. Following this, developers should add *.apimap.json and *.packagemap.json files for their library, using the samples or any existing maps as a starting point. Finally, the NuGet package for the maps can be created by running the Pack command in Visual Studio.
(Usage of Pack command in Visual Studio, Source: Microsoft Official DevBlog)
The original announcement post documents the steps to test API and Package Maps, so interested readers can explore more about it.
Furthermore, developers are encouraged to submit a pull request to the upgrade-assistant GitHub repository, Marco Goertz, states the following:
Once you have validated that your new mappings work as expected we encourage you to create a pull request in the upgrade-assistant github repo. We will review your changes, and once they are merged the CI/CD pipeline will create a new Microsoft.UpgradeAssistant.Mappings package and publish it on nuget.org. As soon as it’s published, existing .NET Upgrade Assistant installation will include the new mappings during upgrades.
Additionally, the .NET Upgrade Assistant extension includes a C# analyzer and code fixer specifically for Xamarin.Forms to .NET MAUI upgrades. This tool assists users in manually upgrading code by identifying Xamarin.Forms namespaces and apply necessary code changes based on both built-in and new third-party API mappings.
(Map code fixes, Source: Microsoft Official DevBlog)
Interested readers can find more info and details about .NET Upgrade Assistant on the official Microsoft dotnet website.