AndroidX migration in Xamarin.Forms

AndroidX replaces the Android Support Library. This article explains why AndroidX exists, how it impacts Xamarin.Forms, and how to migrate your application to use the AndroidX libraries.

History of AndroidX

The Android Support Library was created to provide newer features on older versions of Android. It is a compatibility layer that allows developers to use functionality that may not exist on all versions of the Android operating system and have graceful fallbacks for older versions. The Support Library also includes convenience and helper classes, debugging and utility tools, and sophisticated classes that depend on other Support Library classes to function.

While the Support Library was originally a single binary, it has grown and evolved into a suite of libraries, which are almost essential for modern app development. These are some commonly used features from the Support Library:

  • The Fragment support class.
  • The RecyclerView, used for managing long lists.
  • Multidex support for apps with over 65,536 methods.
  • The ActivityCompat class.

AndroidX is a replacement for the Support Library, which is no longer maintained - all new library development will occur in the AndroidX library. AndroidX is a redesigned library that uses semantic versioning, clearer package names, and better support for common application architecture patterns. AndroidX version 1.0.0 is the binary equivalent to Support Library version 28.0.0. For a complete list of class mappings from Support Library to AndroidX, see Support Library class mappings on developer.android.com.

Google created a migration process called the Jetifier with AndroidX. The Jetifier inspects the jar bytecode during the build process and remaps Support Library references, both in app code and in dependencies, to their AndroidX equivalent.

In a Xamarin.Forms app, just as in an Android Java app, the jar dependencies must be migrated to AndroidX. However, the Xamarin bindings must also be migrated to point to the correct, underlying jar files. Xamarin.Forms added support for automatic AndroidX migration in version 4.5.

For more information about AndroidX, see AndroidX overview on developer.android.com.

Automatic migration in Xamarin.Forms

To automatically migrate to AndroidX, a Xamarin.Forms project must:

  • Target Android API version 29 or greater.
  • Use Xamarin.Forms version 4.5 or greater.

Once you have confirmed these settings in your project, build the Android app in Visual Studio 2019. During the build process, the Intermediate Language (IL) is inspected and Support Library dependencies and bindings are swapped with AndroidX dependencies. If your application has all of the AndroidX dependencies required to build, you will notice no differences in the build process.

Note

You must keep the references to the Support Library in your project. These are used to compile the application before the migration process inspects the resulting IL and transforms the dependencies.

If AndroidX dependencies are detected that are not part of the project, a build error is reported that indicates which AndroidX packages are missing. An example build error is shown below:

Could not find 37 AndroidX assemblies, make sure to install the following NuGet packages:
- Xamarin.AndroidX.Lifecycle.LiveData
- Xamarin.AndroidX.Browser
- Xamarin.Google.Android.Material
- Xamarin.AndroidX.Legacy.Supportv4
You can also copy and paste the following snippit into your .csproj file:
 <PackageReference Include="Xamarin.AndroidX.Lifecycle.LiveData" Version="2.1.0-rc1" />
 <PackageReference Include="Xamarin.AndroidX.Browser" Version="1.0.0-rc1" />
 <PackageReference Include="Xamarin.Google.Android.Material" Version="1.0.0-rc1" />
 <PackageReference Include="Xamarin.AndroidX.Legacy.Support.V4" Version="1.0.0-rc1" />

The missing NuGet packages can either be installed via the NuGet Package Manager in Visual Studio, or installed by editing your Android .csproj file to include the PackageReference XML items listed in the error.

Once the missing packages are resolved, rebuilding the project loads the missing packages and your project is compiled using AndroidX dependencies instead of Support Library dependencies.

Note

If your project, and project dependencies, do not reference Android Support Libraries, the migration process does nothing and is not executed.