Xamarin Forms 5 was recently released and is the last major version until the migration to .NET MAUI (Multi-platform App UI). In this release there are a few breaking changes with controls being moved out and pages renamed, but there is another important change, namely the requirement to migrate to AndroidX.
What is AndroidX?
To understand AndroidX, let's first go back in time to understand its predecessor, the Android Support Libraries. Originally, the support libraries were a means to provide backwards compatibility to the fragmented Android ecosystem and were versioned according to their target Android API Version (EG. V20). These libraries were required as most Android phones rarely got updates, so in order for you application to work on older versions of the OS, as well as taking advantage of the latest and greatest features, you needed to include these support libraries into your application.
However, over time, actual features, such as the CardView, were included as part of these libraries which meant that even if you targeted a relatively high minimum SDK version, you still needed to include the support libraries for those features. In short, things started to get messy and so AndroidX was born.
AndroidX stands for Android eXtension library and is essentially a redesign of the Android Support Libraries to provide better organisation and consistency across devices as well as being able to be maintained and updated independently. In addition, AndroidX will now follow the Semantic versioning scheme. It is worth pointing out that the Android Support Libraries are no longer maintained, with the last version being V28, so there is a definite need to migrate over to AndroidX.
Migrating to AndroidX
Now that we know what AndroidX is and why we need to migrate to it, lets take a look at how to do it in Xamarin Forms. First, we need to make sure that we have the following in place:
- The Minimum Target Framework needs to be set to V10+
- The Minimum Target SDK Version needs to be set to 29+
In Visual Studio 2019, Microsoft created an experimental feature to migrate our project over to AndroidX, however it is worth noting that this will only apply namespace changes, so there will be other steps that will need to be manually done. Regardless, it provides us a first step in the migration process. As this feature is experimental, you will need to enable it by going to Tools > Options > Xamarin > Android Settings and enabling the Enable AndroidX Migrator (Experimental) feature.
Now when you Right-Click on your Android project you will see the Migrate to AndroidX option.
Like I mentioned before, this will migrate the namespaces that it picks up in your project. After it has completed, you will then need to install the corresponding AndroidX NuGet Packages for the namespace change. In order to help understand which packages contain which assemblies, Microsoft have provided a CSV file with all the various mappings for us, which really comes in handy.
The next step in the process is to remove any .axml files that haven't been customized. If they have been customized, you will need to update them to use their corresponding AndroidX type. After that is done, you need to remove the following two lines from your MainActivity.cs file
TabLayoutResource = Resource.Layout.Tabbar;
ToolbarResource = Resource.Layout.Toolbar;
What About My Dependencies?
If you have any dependencies in your project that haven't been migrated to AndroidX, you will need to install the Xamarin.AndroidX.Migration NuGet Package. You would also still need to keep your existing references to the Android Support Libraries as those are going to be required to build your project. However, these packages will not be included in your final package as during the build the Xamarin.AndroidX.Migration package will redirect the calls from the Android Support Libraries to the corresponding AndroidX package. One word of caution, if the redirecting of calls does occur you will notice that your build times take longer than normal as all a full build will have to happen every time, so try ensure that all your dependencies are updated and support AndroidX. All of the Microsoft packages, such as Xamarin Forms, Xamarin Essentials etc have been migrated over to already.
During the build process the Xamarin.AndroidX.Migration package will generate errors if you have any of the required AndroidX NuGet Packages are missing. If that is the case, just add the packages that it mentions via NuGet.
You may be wondering if you will ever be able to remove the Xamarin.AndroidX.Migration NuGet Package, and the answer is yes, if all of the following conditions are met:
- All your source code is migrated over to AndroidX, including
- Layout files
- ProGuard configuration
- Manifest files
- All your dependencies have migrated to AndroidX
If all of the above have been migrated, you can safely remove the Xamarin.AndroidX.Migration package and all the associated Support Libraries.
Summary
AndroidX is the successor to the Android Support Libraries and provides us with better organised and consistent packages. With the release of Xamarin 5, your projects are now required to target AndroidX, but with the tooling and steps mentioned above, you should be able to get it migrated in a short amount of time. Lastly, if you have any dependencies that are still using the Android Support Libraries, then be sure to include the Xamarin.AndroidX.Migration NuGet package to redirect your calls to AndroidX.