Migrating Xamarin.Android Applications to .NET 6

Introduction

With .NET 6, Xamarin.Android has transitioned to being part of the official .NET 6 distribution. This allows for greater code sharing and greater compatibility with .NET libraries. It also includes many other enhancements like SDK-style project files and performance improvements.

However, .NET 6 is also different than classic Xamarin.Android, and will require some work to port your application. The good news is we have prioritized compatibility, and we do not anticipate many (if any) code changes. The bulk of the work will be transitioning to the new SDK style project file format used by the rest of the modern .NET ecosystem.

Compatibility

The most important point is that the new .NET Android framework net6.0-android is backward compatible with the existing class frameworks (MonoAndroid9.0, MonoAndroid12.0, etc.). This means that .NET 6 Android applications can continue to use the vast ecosystem of existing NuGet packages and binding libraries.

This also dictates the best path for upgrading your application: you should begin by porting the application project to net6.0-android while your libraries and dependencies can remain as MonoAndroidXX.0 until you choose to migrate them later.

Note there are a few rarely used features that are not supported in .NET 6, like AppDomains. We have been trying to add build warnings to existing apps over the past year to inform users if they are using something that will not be supported.

Prerequisites

SDK style project files are expected to use <PackageReference> instead of packages.config to manage NuGet dependencies. If your application still uses packages.config, you will probably find it easier to do that migration first and confirm your application still works before migrating to .NET 6.

Getting Started

The main effort of migrating .NET 6 Android will be updating your application's .csproj to the SDK style project format. There are several possible strategies for doing this.

• try-convert - There is an unsupported tool to automatically convert .NET Framework .csproj files to SDK style. This may or may not produce useful results: https://github.com/dotnet/try-convert.

• upgrade-assistant - Work is being done to add Xamarin migration support to dotnet's upgrade-assistant, however it is not expected to be available until MAUI RTM launches.

• From new template - The simplest way may be to create a new application project using the project templates built into Visual Studio 2022 or dotnet new. After creating the new project, copy all of the aspects of the existing project to the new one: source code, resources, NuGet dependencies, project references, etc.

• Overwrite .csproj - If you're comfortable with editing your .csproj directly, you can simply edit it until it is a valid SDK style project. It will probably be helpful to look at the .csproj created by the Android template in order to know what must be specified.

Additional Resources

• OneDotNet.md - Provides some of the more technical details of changes made in .NET 6.
• OneDotNetBindingProjects.md - Provides some of the more technical details of changes made in .NET 6 specifically for Java binding libraries.
• OneDotNetEmbeddedResources.md - Provides some of the more technical details of changes made in .NET 6 specifically for Android class libraries and resources.