Share via

Xamarin.Android 10.2 release notes

  • Article

| GitHub | Developer Community | System requirements | Blogs |

Important

The names for generated Java types are different in this release. Any project that explicitly uses one of the old names that starts with md5 will need to be updated by hand to account for this change. See Breaking change for generated Java type names below for more details.

Important

The default multidex tool is now R8 instead of DX. R8 performs additional Java dependency checks that can result in new build warnings and errors like:

R8 : error : Compilation can't be completed because some library classes are missing.

See D8 enabled by default for all projects below for more details.

Installing

What's new in Xamarin.Android 10.2

Xamarin.Android 10.2 releases

Corresponding Visual Studio 2019 release notes

March 16 and 23, 2020 — Xamarin.Android 10.2.0.100

This version is included in the Visual Studio 2019 version 16.5 release and in the Stable updater channel of Visual Studio 2019 for Mac version 8.5.

Summary of what's new in Xamarin.Android 10.2.0.100

Breaking change for generated Java type names

Important

The fallback option in Xamarin.Android 10.1 that allowed using the old style of generated Java type names that started with md5 has now been removed.

Authors of projects that include literal uses of generated Java type names that start with md5 will now need to transition to alternatives like the [Register] attribute and the [Activity] attribute.

Projects that have the LowercaseMD5 fallback option set in the $(AndroidPackageNamingPolicy) MSBuild property will now fail to build with the following error:

error XAGJS7015: System.NotSupportedException: PackageNamingPolicy.LowercaseHash is no longer supported.

To resolve the error, remove the section for the $(AndroidPackageNamingPolicy) property from the .csproj file:

<PropertyGroup>
  <AndroidPackageNamingPolicy>LowercaseMD5</AndroidPackageNamingPolicy>
</PropertyGroup>

See the Xamarin.Android 10.1 release notes for additional background information about this change and examples of how to update existing projects.

D8 enabled by default for all projects

Important

Because the default DEX compiler is now D8, the default multidex tool is now R8 instead of DX. R8 performs additional Java dependency checks that can result in new build warnings and errors like:

R8 : error : Compilation can't be completed because some library classes are missing.

If needed, these errors can be suppressed temporarily by configuring R8 to be less strict:

  1. Add a new text file to the project, named for example proguard-rules.pro.

  2. Set the contents of the file to:

    -ignorewarnings

  3. Edit the .csproj file in a text editor and add --pg-conf proguard-rules.pro to the $(AndroidR8ExtraArguments) MSBuild property, for example by adding the following lines:

    <PropertyGroup>
  <AndroidR8ExtraArguments>--pg-conf proguard-rules.pro</AndroidR8ExtraArguments>
</PropertyGroup>

Xamarin.Android has included an option to use the D8 DEX compiler since Xamarin.Android 9.2, but is has so far been disabled by default to provide a gradual path for finding and addressing compatibility issues. Starting in Xamarin.Android 10.2, the D8 DEX compiler option is now enabled by default for both existing and new projects.

To switch back from D8 to the earlier DX compiler for a particular project, set the Dex compiler option in the Visual Studio project property pages first to d8 and then to dx and save the changes, or set the $(AndroidDexTool) MSBuild property to dx by hand in the .csproj file:

<PropertyGroup>
  <AndroidDexTool>dx</AndroidDexTool>
</PropertyGroup>

AndroidEnableDesugar now requires D8

Xamarin.Android now always use the D8 DEX compiler for projects that have the $(AndroidEnableDesugar) MSBuild property set to true:

<PropertyGroup>
  <AndroidEnableDesugar>true</AndroidEnableDesugar>
</PropertyGroup>

Similarly, Xamarin.Android now always uses the R8 code shrinker for projects that have $(AndroidEnableDesugar) set to true and that have the Code shrinker ($(AndroidLinkTool)) set to ProGuard or r8.

Note

$(AndroidEnableDesugar) does not correspond to any setting in the project properties pages in Visual Studio, so this change only affects project authors who have added the property to .csproj files by hand.

Background information

This change allows Xamarin.Android to remove support for the old desugar_deploy.jar mechanism from the Android Jack toolchain that was deprecated in 2017.

Mono Framework version update to 6.8

Xamarin.Android now uses the Mono 6.8 runtime and class libraries at Commit c0c5c78e, bringing in about 800 new commits.

Build and deployment performance

  • GitHub PR 3692: For the specific scenario of Debug builds that have Use Fast Deployment enabled, undo part of the change from GitHub PR 2718 so that type mappings are parsed at run time instead of being compiled into unmanaged native shared libraries. This reduced the time for the GenerateJavaStubs task from about 540 milliseconds to about 320 milliseconds for an incremental build of a test app where the MainActivity type was modified between builds. As expected, this did increase the app startup time from about 1.30 seconds to about 1.35 seconds, but that still left an overall savings of approximately 170 milliseconds.
  • GitHub PR 3856: Add a fallback naming scheme for the files that mark whether the outputs of the _CompileAndroidLibraryResources target are up-to-date with the input files. This allows projects that use a google-services.json item and that are configured to use AAPT2 to skip the _CompileAndroidLibraryResources target correctly during incremental builds.
  • GitHub PR 3907: Adjust GenerateResourceDesigner to use System.Reflection.Metadata rather than Cecil, use loops instead of LINQ expressions, and skip over .NET Standard libraries. This reduced the time for the GenerateResourceDesigner task during an incremental build from about 470 milliseconds to about 370 milliseconds for a small app on a test system.
  • GitHub PR 4020: Skip a managed linker step for assemblies that have no references to Java.Lang.Object, such as .NET Standard libraries. This reduced the time for the _LinkAssembliesNoShrink target on a test system from about 160 milliseconds to about 50 milliseconds for an incremental build after a one-line change to the MainActivity class.
  • Mono GitHub PR 17898: Skip over unnecessary DNS lookups for the IP address of the target Android device or emulator when starting the debugger.

App startup performance

  • GitHub PR 3729: Initialize application logging and uncaught exception handling lazily. This reduced the time to display the first screen of a small test Xamarin.Forms app from about 780 milliseconds to about 750 milliseconds for a Release configuration build on a Google Pixel 3 XL device.
  • GitHub PR 3780: Simplify how Android system properties are looked up for internal uses within the Xamarin.Android runtime. This subtracted about 1 millisecond from the total app startup time.
  • GitHub PR 3951: Avoid searching for unmanaged compiled assemblies generated by Enable Startup Tracing or AOT Compilation unless the app was built with one of those options enabled. This reduced the Runtime.init() phase of application startup for a small test app from about 172 milliseconds to about 168 milliseconds.

Android resource editing performance

  • GitHub PR 3889: Update the _GeneratePackageManagerJavaForDesigner target to check the timestamp of the MonoPackageManager_Resources.java output file instead of the old obsolete MonoPackageManager.java file that was used in Xamarin.Android 9.3 and earlier. This reduced the total time for the SetupDependenciesForDesigner target by about 500 milliseconds for a small app on a test system. The SetupDependenciesForDesigner target runs in the background for interactive scenarios in Visual Studio after an Android resource has changed.
  • GitHub PR 3891: Avoid unnecessary changes to the build.props intermediate file during design-time builds so that the UpdateGeneratedFiles and SetupDependenciesForDesigner targets can skip the _ResolveLibraryProjectImports target. This reduced the time for the UpdateGeneratedFiles target by about 300 milliseconds for a small app on a test system. The UpdateGeneratedFiles target runs in the foreground each time an Android resource is saved, so this makes Visual Studio more responsive when working on Android resources.
  • GitHub PR 3907: Adjust GenerateResourceDesigner to use System.Reflection.Metadata rather than Cecil, use loops instead of LINQ expressions, and skip over .NET Standard libraries. This reduced the time for the GenerateResourceDesigner task during an incremental build from about 470 milliseconds to about 370 milliseconds for a small app on a test system. The GenerateResourceDesigner task also runs in the foreground each time an Android resource is saved, so this makes Visual Studio more responsive when working on Android resources.
  • GitHub PR 3913: Skip the _GenerateJavaStubs target for builds where only Android resources have changed. This makes Visual Studio more responsive when working with Android resources. For example, it reduced the design-time build by about 400 milliseconds for a scenario where an Android resource was edited and saved in a moderately large app on a test system.

Improved Android manifest merging

Xamarin.Android now includes an option to use the same Android manifest merger tool that Android Studio uses to merge AndroidManifest.xml files. This provides new capabilities and improves compatibility with Android Studio. See the documentation for details about the available merge rules.

To enable the new behavior for a project, set the $(AndroidManifestMerger) MSBuild property to manifestmerger.jar in the .csproj file:

<PropertyGroup>
  <AndroidManifestMerger>manifestmerger.jar</AndroidManifestMerger>
</PropertyGroup>

Any project authors who were previously using the Xamarin.Android.ManifestMerger NuGet package can remove that package after adding this setting.

Custom profiles for Enable Startup Tracing

The Enable Startup Tracing feature compiles a set of managed methods to unmanaged code to improve startup times. By default, only the common methods used during the startup of a basic Xamarin.Android app are compiled. For some apps, this default might not provide the optimum trade-offs between app size and startup times.

Xamarin.Android 10.2 includes new MSBuild targets to help create custom startup tracing profiles based on the actual methods that a particular app calls during startup.

Visual Studio integration for this feature is planned for a future release. Project authors who would like to try the feature before then can use command line steps similar to the following:

  1. Ensure only one Android device is attached.

  2. Under the app's Android Manifest > Required permissions in the Visual Studio project property pages, ensure the INTERNET permission is enabled.

  3. Open a Tools > Command Line > Developer Command Prompt.

  4. Run the following command from the app's solution directory:

    msbuild -restore -p:Configuration=Release -t:BuildAndStartAotProfiling

  5. Wait for the app's first screen to appear.

  6. Run the following two commands:

    set PATH=%PATH%;"C:\Program Files (x86)\Android\android-sdk\platform-tools"

    msbuild -t:FinishAotProfiling

  7. Add the following lines to the Android app project .csproj file:

    <ItemGroup>
  <AndroidAotProfile Include="custom.aprof" />
</ItemGroup>
<PropertyGroup>
  <AndroidUseDefaultAotProfile>false</AndroidUseDefaultAotProfile>
</PropertyGroup>

Known issues

  • GitHub 4152: Unable to read profile ... The system cannot find the file specified prevents FinishAotProfiling from completing successfully if the location of adb is not in the current PATH environment variable.
  • GitHub 4402: The first screen of the app never appears and Unable to read profile ... System.IO.IOException: Input file is too small prevents FinishAotProfiling from completing successfully if the INTERNET permission is not enabled for the app.

Bindings projects support for Kotlin libraries

This release adds better support for creating bindings for Kotlin libraries, including:

  • Hiding Kotlin internal types and members
  • Using Kotlin provided metadata to properly name method parameters
  • Hiding Kotlin generated methods like foo-impl that aren't intended for public use
  • Restoring Kotlin-mangled method names to their original names, such as changing foo-V5j3Lk8 back to foo
  • Adding support for Kotlin's native unsigned types (UInt, ULong, UShort, UByte)

Although it was technically possible to bind a Kotlin library previously, these changes greatly reduce the number of custom rules needed in the Transforms\Metadata.xml file to produce expected bindings.

No additional steps are needed to enable this. The binding process will detect if a .jar file was produced from Kotlin and will apply the needed fixes.

Important

Some of these changes required adding new APIs to Java.Interop.dll. This means that like the binding projects themselves, Xamarin.Android application projects that consume one of these new Kotlin library bindings must also be built using Xamarin.Android 10.2 or higher.

Android App Bundle publishing format workflow improvements

Xamarin.Android 10.2 adds two improvements to the support for Android App Bundle publishing format to align it more closely with the support for the APK publishing format.

The first change is that the Xamarin.Android MSBuild targets now copy the unsigned .aab file to the output directory. Previously, only the signed .aab file was copied to the output directory. The unsigned file can be useful in continuous integration environments where project authors might want to create an unsigned .aab file via the PackageForAndroid MSBuild target that can then be signed in a separate step.

This change resolve the following issue:

  • GitHub 3804: Building the PackageForAndroid target, for example by running msbuild -restore -p:Configuration=Release -t:PackageForAndroid, does not output an unsigned .aab file to the output path in projects configured to use the Android App Bundle publishing format.

The second change is that the directory name for the mono-symbolicate .pdb symbol file archive now ends with the expected .aab.mSYM extension instead of .apk.mSYM.

Managed TLS 1.0 setting now uses Native TLS 1.2+

The Managed TLS 1.0 setting for SSL/TLS implementation in the Visual Studio property pages now uses the same TLS implementation as the Native TLS 1.2+ setting. The legacy managed TLS implementation is no longer available.

New build errors and warnings XA0121, XA2000, XA2001

XA0121 error for old Xamarin.Android.Support library versions

The XA0121 warning from Xamarin.Android 10.1 is now an error because compatibility with the old GetAdditionalResourcesFromAssemblies MSBuild task has been removed.

Any project that uses one of the affected Xamarin.Android.Support libraries from version 26 or earlier will now see errors like:

error XA0121: Assembly 'Xamarin.Android.Support.Animated.Vector.Drawable' is using '[assembly: Java.Interop.JavaLibraryReferenceAttribute]', which is no longer supported. Use a newer version of this NuGet package or notify the library author.

To resolve these errors, update the project to use version 27 or higher of the Xamarin.Android.Support libraries.

XA2000 warning for use of AppDomain.CreateDomain()

The new XA2000 build warning identifies cases where projects are using the AppDomain.CreateDomain() API:

warning XA2000: Use of AppDomain.CreateDomain() detected in assembly: AndroidApp1. .NET 5 will only support a single AppDomain, so this API will no longer be available in Xamarin.Android once .NET 5 is released.

Because AppDomain in .NET 5 will follow the .NET Core semantics, where there is only exactly one AppDomain and AppDomain.CreateDomain() throws PlatformNotSupportedException, any projects currently using AppDomain.CreateDomain() will need to switch to a different API like AssemblyLoadContext. Project authors are encouraged to begin this transition as soon as they can to prepare for the behavior change.

XA2001 error for nonexistent Android resources

Xamarin.Android 10.2 adds a new XA2001 build error to identify cases where projects might unintentionally include references to Android resource file paths that do not exist. Example:

error XA2001: Source file 'Resources\layout\missing.xml' could not be found.

Before this change, projects that included references to nonexistent Android resources would rebuild the _CompileResources and _UpdateAndroidResgen targets on every build. The new error protects against this by ensuring that project authors remove references to nonexistent resources.

AAPT2 version update to 3.5.0-5435860

The version of the Android Asset Packaging Tool AAPT2 included in Xamarin.Android has been updated from 3.4.1-5326820 to 3.5.0-5435860.

Mono debugger and compiler option passthroughs

Mono debugger loglevel passthrough

The Mono soft debugger agent has an option to change the level of diagnostic information it logs. In the past, this log level was always 0 for Xamarin.Android apps. In Xamarin.Android 10.2, the log level can now be adjusted by setting the debugger-log-level option in the debug.mono.log Android system property. For example, the following command sets the log level to 10:

adb shell setprop debug.mono.log debugger-log-level=10

Mono compiler option passthrough

The new $(AndroidExtraAotOptions) MSBuild property allows passing options to the Mono compiler in projects that have either Enable Startup Tracing or AOT Compilation enabled.

In general, this property should be left blank, but in certain special scenarios it might provide useful flexibility.

Note that this property is different from the related $(AndroidAotAdditionalArguments) property. That property places comma-separated arguments into the --aot option of the Mono compiler. $(AndroidExtraAotOptions) instead passes full standalone space-separated options like --verbose or --debug to the compiler.

An example use would be to set the --verbose option to get additional diagnostic information during a command line build:

msbuild -p:AndroidExtraAotOptions=verbose

Issues fixed in Xamarin.Android 10.2.0.100

Application and library build and deployment

  • Developer Community 797093, GitHub PR 3945: Starting in Xamarin.Android 10.1, warning XA5302: Two processes may be building this project at once. Lock file exists at path: ... obj\Debug\100\.__lock often appeared unnecessarily when deploying to an emulator or device from within Visual Studio.
  • Developer Community 854863: More than one device connected, please provide --device-id could prevent deploying successfully in projects configured to use the Android App Bundle publishing format when more than one device or emulator was attached.
  • Developer Community 869165: error CS0234: The type or namespace name 'CodeDom' does not exist in the namespace prevented building successfully in projects that used the word System as a dotted part of the default namespace for the project.
  • GitHub 1335: Xamarin.Android did not yet have a standardized way to override AndroidManifest.xml permissions brought in by referenced libraries.
  • GitHub 2687, GitHub 3428: Xamarin.Android did not yet provide an option to use the AndroidManifest.xml merge tool that Android Studio uses.
  • GitHub PR 3410: Messages similar to resources.arsc in APK 'android.jar' is compressed were incorrectly surfaced as build errors rather than warnings.
  • GitHub 3423: A misleading The "FilterAssemblies" task failed unexpectedly build error was shown instead of the expected Metadata file ... could not be found error when an app project referenced a .NET Standard library that did not build successfully.
  • GitHub 3622: Warnings similar to R8 : warning : Resource 'META-INF/MANIFEST.MF' already exists. could appear in the Error List window when building apps in the Release configuration with Code shrinker set to r8. These warnings from the upstream R8 tool are not currently relevant for Xamarin.Android users, so Xamarin.Android 10.2 now logs them as plain messages instead of warnings.
  • GitHub 3727: Device could not find component named: ... MainActivity ... The application could not be started. prevented launching an app successfully if the app had been uninstalled by hand between two Debug deployments.
  • GitHub 3804: Building the PackageForAndroid target, for example by running msbuild -restore -p:Configuration=Release -t:PackageForAndroid, did not output an unsigned .aab file to the output path in projects configured to use the Android App Bundle publishing format.
  • GitHub 3808: The type or namespace name ... could not be found in the global namespace prevented using %(Aliases) MSBuild item metadata on Xamarin.Android library project references.
  • GitHub 3849: warning XA0107: Ignoring as it is a Reference Assembly could appear without any mention of the name of the problematic assembly.
  • GitHub 3852: The LinkAssemblies task could get stuck in an infinite loop in projects referencing certain libraries when the $(Nullable) MSBuild property was set to enable.
  • GitHub 3898, GitHub 3920: If a NuGet package included a library without a [assembly: ReferenceAssemblyAttribute] attribute under a ref directory, then Xamarin.Android apps could unexpectedly use that ref version of the library instead of the expected version from the appropriate lib directory.
  • GitHub 3911: The managed linker did not yet remove the custom attribute metadata that C# 8.0 nullable reference types use. That metadata is only needed at build time.
  • GitHub PR 3937: message ANDKT0000: Warning: The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format could appear in the diagnostic Xamarin.Android build output from Java's keytool.exe because Xamarin.Android did not yet specify a -storetype argument to keytool.exe when generating the debug.keystore file that is used by default for deployment to local Android devices and emulators.
  • GitHub PR 3968: File extensions set in the $(AndroidStoreUncompressedFileExtensions) MSBuild property or in the corresponding Leave the following resource extensions uncompressed setting in the Visual Studio project property pages had to start with a . dot character to behave as expected. Now the . dot character is optional.
  • GitHub 3996: error XA5300: The Android SDK Directory could not be found. Please set via /p:AndroidSdkDirectory. could occur even after running the InstallAndroidDependencies MSBuild target on a newly configured build environment.
  • GitHub PR 4016: Unclear warning XA0110: Disabling true as it is not supported by `aapt2`. If you wish to use true please set true to false. appeared if the $(AndroidExplicitCrunch) MSBuild property was set to true in a project that was also configured to use AAPT2.
  • GitHub 4046: Adds a new build action to allow configuring message severity levels in the Xamarin Android Designer diagnostics tool. To use this in your project, add an XML configuration file that follows the format described in the Android Resource Analysis documentation and set the build action to AndroidResourceAnalysisConfig.
  • GitHub 4068: error MSB4044: The "CopyGeneratedJavaResourceClasses" task was not given a value for the required parameter "SourceTopDirectory". prevented incremental builds from completing successfully for projects using the Xamarin.AndroidX.Migration NuGet package.
  • GitHub 4074, GitHub 4182: Errors similar to error XA2002: Can not resolve reference: `System.Diagnostics.EventLog`, referenced by `Microsoft.Extensions.Logging.EventLog`. could prevent building if the NuGet package path was set to a custom location, for example via the NUGET_PACKAGES environment variable.
  • GitHub PR 4106: Any unhandled exceptions in the Xamarin.Android MSBuild tasks would result in two MSBuild errors instead of one.
  • GitHub PR 4131: error ADB1000 was shown in addition to error ADB0030 if the ADB0030 error condition occurred.
  • GitHub PR 4205: Some of the Xamarin.Android MSBuild tasks were using foreground logging methods from background threads. That usage pattern could in theory lead to lock ups in the Visual Studio user interface.

Application behavior on device and emulator

  • Developer Community 788217: Exceptions similar to Android.Content.Res.Resources+NotFoundException: Resource ID #0x7f09001cv could cause apps to abort when trying to use Android resources if the [Activity(MainLauncher = true)] activity was in a library project.
  • Developer Community 878335, GitHub 4177: Starting in Xamarin.Android 10.1, Java.Lang.ClassNotFoundException: md545536373befe5ba5b0be978b998d36b6.TestSuiteActivity_TestData prevented running Xamarin.Android unit test app projects.
  • GitHub PR 3862: If an app referenced multiple libraries that each provided a different version of an Android resource, then the final selected version of the resource in the app was different when the app was built using AAPT2 instead of AAPT.
  • GitHub PR 3927: Starting in Xamarin.Android 10.1, native libraries did not load as expected for apps deployed in the Debug configuration using the Assemblies:Dexes fast deployment mode.
  • GitHub PR 3940: Starting in Xamarin.Android 9.4, Unknown Mono AOT mode could appear incorrectly in the app log output depending on the AOT mode.

Application Mono Framework behavior on device and emulator

  • Developer Community 716868, Mono GitHub 18106: Starting in Xamarin.Android 9.2, No compatible code running appeared in the Visual Studio debugger after the debugger paused on breakpoints in callback methods from Android Java APIs, such as WebViewClient.ShouldInterceptRequest() or Android.OS.AsyncTask.RunInBackground().

  • Developer Community 756697: Starting in Xamarin.Android 10.0, NTLM authentication in Xamarin.Android apps no longer worked, resulting in server-side System.ComponentModel.Win32Exception exceptions.

    The initial fix for this issue in Xamarin.Android 10.1 was incomplete. Xamarin.Android 10.2 now includes additional changes that allow switching back to the Xamarin.Android 9.4 HttpClient behavior.

    To switch back to the Xamarin.Android 9.4 behavior, set the $(AndroidHttpClientHandlerType) MSBuild property to System.Net.Http.MonoWebRequestHandler, System.Net.Http in the .csproj file:

    <PropertyGroup>
  <AndroidHttpClientHandlerType>System.Net.Http.MonoWebRequestHandler, System.Net.Http</AndroidHttpClientHandlerType>
</PropertyGroup>

  • Developer Community 720606, Mono GitHub 16742: System.ArgumentOutOfRangeException was thrown unexpectedly when calling DateTime.TryParseExact() with certain dates from the year 1948.

  • Mono GitHub 17878: In certain scenarios involving callbacks from native threads, apps could become unresponsive while running mono_gc_wait_for_bridge_processing().

  • Mono GitHub 18030: System.Net.Http.HttpRequestException: mono-io-layer-error (-1) caused HttpClient requests to abort if the first IP address returned by the associated DNS query was not accessible.

Design-time build process

  • GitHub PR 4199: Using ReSharper's class creation dialog in a Xamarin.Android project could lock up the Visual Studio interface.

Android API bindings

  • GitHub 3712: The [Service] attribute did not yet include a property to set the new foregroundServiceType attribute that was added in Android 10 (API level 29).

Thank you

A big Thank You! to community members who contributed improvements in this release:

Feedback welcome

Your feedback is important to us. If there are any problems with this release, check our GitHub Issues, Xamarin.Android Community Forums and Visual Studio Developer Community for existing issues. For new issues within the Xamarin.Android SDK, please report a GitHub Issue. For general Xamarin.Android experience issues, let us know via the Report a Problem option found in your favorite IDE under Help > Report a Problem.

Open source

Xamarin.Android 10.2 is based on the open-source Xamarin.Android repositories: