Introducing third-party APIs and package maps in the .NET Upgrade Assistant

The .NET Upgrade Assistant is a powerful tool that functions as a Visual Studio extension and command-line tool. It helps developers update applications from older .NET versions to the latest versions. The tool offers comprehensive support for updating Microsoft libraries and frameworks. Microsoft has introduced a new feature: support for third-party APIs and package maps. This innovation allows outdated third-party APIs and packages to be replaced with their newer counterparts during the upgrade process, simplifying the transition to new platforms such as UWP to WinUI or Xamarin Forms to .NET MAUI.

What is the support for third-party APIs and package maps?

When updating older applications to the latest .NET version, one of the biggest challenges is finding the corresponding APIs and NuGet packages from third-party libraries. This task becomes even more complex when a platform change is involved, such as from UWP to WinUI or from Xamarin Forms to .NET MAUI. For example, the Xamarin.Forms namespace must be replaced with Microsoft.Maui and/or Microsoft.Maui.Controls. In addition to the namespaces, types and methods often need to be adapted as well.
The .NET Upgrade Assistant already offers extensive mappings for Microsoft-managed libraries. Now, the .NET Upgrade Assistant also supports third-party API and package maps. This feature allows anyone to create mappings for their own libraries, containing information about old and new APIs and packages. The Upgrade Assistant uses these mappings, in addition to the built-in mappings, to implement code and project changes during an upgrade.

Creating API and package maps

To create third-party API maps for the .NET Upgrade Assistant, the following steps are necessary:

  1. Read the README.md file in the Upgrade Assistant GitHub repo.
  2. Clone the repository and open UpgradeAssistantExtensions.sln in Visual Studio.
  3. Create a new folder for your company with a subfolder for your library under Mappings in the UpgradeAssistant.Mappings project.
  4. Add *.apimap.json and *.packagemap.json files to your library (use the examples or existing mappings as a starting point).
  5. Create the NuGet package for the mappings by running the Pack command.

This creates a Microsoft.UpgradeAssistant.Mappings NuGet package in the project's output folder.

Testing the API and package maps

To test the NuGet package with the created mappings, proceed as follows:

  1. Make sure you have the latest version of the .NET Upgrade Assistant extension from the Visual Studio Marketplace.
  2. Create/open a test project that uses the APIs and packages specified in your new mappings.
  3. Set up a local feed folder, e.g. C:\LocalFeed.
  4. Add the previously created Microsoft.UpgradeAssistant.Mappings package to the local feed by running the following command in the output folder: `nuget add Microsoft.UpgradeAssistant.Mappings.1.0.0.nupkg -source C:\LocalFeed`
  5. Create a Nuget.config file with the following content in the solution folder of the test project:

“`





“` `

  1. Run the Upgrade Assistant to update the test project.

The APIs and packages should be updated according to the created mappings.

What happens next?

Once you've confirmed that your new mappings are working as expected, we recommend creating a pull request in the Upgrade Assistant GitHub repository. Your changes will be reviewed, and once merged, the CI/CD pipeline will create a new Microsoft.UpgradeAssistant.Mappings package and publish it to nuget.org. Once published, existing .NET Upgrade Assistant installations will include the new mappings during upgrades.

Manual upgrade to .NET MAUI?

If you are manually upgrading to .NET MAUI, you should know that the .NET Upgrade Assistant extension includes a C# analyzer and code fixer for Xamarin.Forms to .NET MAUI upgrades. This can help you update manually copied code from Xamarin.Forms projects to .NET MAUI projects. The analyzer searches for Xamarin.Forms namespaces, and the Lightbulb code fixer applies code changes based on the built-in mappings as well as the new third-party API mappings.

Summary: Key takeaways about intuitive eating

Support for third-party APIs and package maps significantly expands the capabilities of the .NET Upgrade Assistant by making it easier to update projects with dependencies on third-party libraries.