Build Process

03/06/2020
35 minutes to read
- +5

Overview

The Xamarin.Android build process is responsible for gluing everything together: generating Resource.designer.cs, supporting the AndroidAsset, AndroidResource, and other build actions, generating Android-callable wrappers, and generating a .apk for execution on Android devices.

Application Packages

In broad terms, there are two types of Android application packages (.apk files) which the Xamarin.Android build system can generate:

Release builds, which are fully self-contained and don't require additional packages to execute. These are the packages which would be provided to an App store.
Debug builds, which are not.

Not coincidentally, these match the MSBuild Configuration which produces the package.

Shared Runtime

The shared runtime is a pair of additional Android packages which provide the Base Class Library (mscorlib.dll, etc.) and the Android binding library (Mono.Android.dll, etc.). Debug builds rely upon the shared runtime in lieu of including the Base Class Library and Binding assemblies within the Android application package, allowing the Debug package to be smaller.

The shared runtime may be disabled in Debug builds by setting the $(AndroidUseSharedRuntime) property to False.

Fast Deployment

Fast deployment works in concert with the shared runtime to further shrink the Android application package size. This is done by not bundling the app's assemblies within the package. Instead, they are copied onto the target via adb push. This process speeds up the build/deploy/debug cycle because if only assemblies are changed, the package is not reinstalled. Instead, only the updated assemblies are re-synchronized to the target device.

Fast deployment is known to fail on devices which block adb from synchronizing to the directory /data/data/@PACKAGE_NAME@/files/.__override__.

Fast deployment is enabled by default, and may be disabled in Debug builds by setting the $(EmbedAssembliesIntoApk) property to True.

MSBuild Projects

The Xamarin.Android build process is based on MSBuild, which is also the project file format used by Visual Studio for Mac and Visual Studio. Ordinarily, users will not need to edit the MSBuild files by hand – the IDE creates fully functional projects and updates them with any changes made, and automatically invoke build targets as needed.

Advanced users may wish to do things not supported by the IDE's GUI, so the build process is customizable by editing the project file directly. This page documents only the Xamarin.Android-specific features and customizations – many more things are possible with the normal MSBuild items, properties and targets.

Build Targets

The following build targets are defined for Xamarin.Android projects:

Build – Builds the package.
BuildAndStartAotProfiling – Builds the app with an embedded AOT profiler, sets the profiler TCP port to $(AndroidAotProfilerPort), and starts the default activity.

The default TCP port is 9999.

Added in Xamarin.Android 10.2.
Clean – Removes all files generated by the build process.
FinishAotProfiling – Collects the AOT profiler data from the device or emulator through the TCP port $(AndroidAotProfilerPort) and writes them to $(AndroidAotCustomProfilePath).

The default values for port and custom profile are 9999 and custom.aprof.

To pass additional options to aprofutil, set them in the $(AProfUtilExtraOptions) property.

This is equivalent to:
```
aprofutil $(AProfUtilExtraOptions) -s -v -f -p $(AndroidAotProfilerPort) -o "$(AndroidAotCustomProfilePath)"
```
Added in Xamarin.Android 10.2.
Install – Installs the package onto the default device or virtual device.
SignAndroidPackage – Creates and signs the package (.apk). Use with /p:Configuration=Release to generate self-contained "Release" packages.
StartAndroidActivity – Starts the default activity on the device or the running emulator. To start a different activity, set the $(AndroidLaunchActivity) property to the activity name.

This is equivalent to adb shell am start @PACKAGE_NAME@/$(AndroidLaunchActivity).

Added in Xamarin.Android 10.2.
StopAndroidPackage – Completely stops the application package on the device or the running emulator.

This is equivalent to adb shell am force-stop @PACKAGE_NAME@.

Added in Xamarin.Android 10.2.
Uninstall – Uninstalls the package from the default device or virtual device.
UpdateAndroidResources – Updates the Resource.designer.cs file. This target is usually called by the IDE when new resources are added to the project.

Build Extension Points

The Xamarin.Android build system exposes a few public extension points for users wanting to hook into our build process. To use one of these extension points you will need to add your custom target to the appropriate MSBuild property in a PropertyGroup. For example:

<PropertyGroup>
   <AfterGenerateAndroidManifest>
      $(AfterGenerateAndroidManifest);
      YourTarget;
   </AfterGenerateAndroidManifest>
</PropertyGroup>

A word of caution about extending the build process: If not written correctly, build extensions can affect your build performance, especially if they run on every build. It is highly recommended that you read the MSBuild documentation before implementing such extensions.

AfterGenerateAndroidManifest – Targets listed in this property will run directly after the internal _GenerateJavaStubs target. This is where the AndroidManifest.xml file is generated in the $(IntermediateOutputPath). So if you want to make any modifications to the generated AndroidManifest.xml file, you can do that using this extension point.

Added in Xamarin.Android 9.4.
BeforeGenerateAndroidManifest – Targets listed in this property will run directly before _GenerateJavaStubs.

Added in Xamarin.Android 9.4.

Build Properties

MSBuild properties control the behavior of the targets. They are specified within the project file, e.g. MyApp.csproj, within an MSBuild PropertyGroup element.

Configuration – Specifies the build configuration to use, such as "Debug" or "Release". The Configuration property is used to determine default values for other properties which determine target behavior. Additional configurations may be created within your IDE.

By default, the Debug configuration will result in the Install and SignAndroidPackage targets creating a smaller Android package which requires the presence of other files and packages to operate.

The default Release configuration will result in the Install and SignAndroidPackage targets creating an Android package which is stand-alone, and may be used without installing any other packages or files.
DebugSymbols – A boolean value which determines whether the Android package is debuggable, in combination with the $(DebugType) property. A debuggable package contains debug symbols, sets the //application/@android:debuggable attribute to true, and automatically adds the INTERNET permission so that a debugger can attach to the process. An application is debuggable if DebugSymbols is True and DebugType is either the empty string or Full.
DebugType – Specifies the type of debug symbols to generate as part of the build, which also impacts whether the Application is debuggable. Possible values include:
- Full: Full symbols are generated. If the DebugSymbols MSBuild property is also True, then the Application package is debuggable.
- PdbOnly: "PDB" symbols are generated. The Application package will not be debuggable.
If DebugType is not set or is the empty string, then the DebugSymbols property controls whether or not the Application is debuggable.
- AndroidGenerateLayoutBindings – Enables generation of layout code-behind if set to true or disables it completely if set to false. The default value is false.

Install Properties

Install properties control the behavior of the Install and Uninstall targets.

AdbTarget – Specifies the Android target device the Android package may be installed to or removed from. The value of this property is the same as the adb Target Device option:
```
# Install package onto emulator via -e
# Use `/Library/Frameworks/Mono.framework/Commands/msbuild` on OS X
MSBuild /t:Install ProjectName.csproj /p:AdbTarget=-e
```

Packaging Properties

Packaging properties control the creation of the Android package, and are used by the Install and SignAndroidPackage targets. The Signing Properties are also relevant when packaging Release applications.

AndroidAotProfiles – A string property that allows the developer to add AOT profiles from the command line. It is a semicolon or comma separated list of absolute paths.

Added in Xamarin.Android 10.1.
AndroidApkDigestAlgorithm – A string value which specifies the digest algorithm to use with jarsigner -digestalg.

The default value is SHA-256. In Xamarin.Android 10.0 and earlier, the default value was SHA1.

Added in Xamarin.Android 9.4.
AndroidApkSignerAdditionalArguments – A string property which allows the developer to provide additional arguments to the apksigner tool.

Added in Xamarin.Android 8.2.
AndroidApkSigningAlgorithm – A string value which specifies the signing algorithm to use with jarsigner -sigalg.

The default value is SHA256withRSA. In Xamarin.Android 10.0 and earlier, the default value was md5withRSA.

Added in Xamarin.Android 8.2.
AndroidApplication – A boolean value that indicates whether the project is for an Android Application (True) or for an Android Library Project (False or not present).

Only one project with <AndroidApplication>True</AndroidApplication> may be present within an Android package. (Unfortunately this is not yet verified, which can result in subtle and bizarre errors regarding Android resources.)
AndroidApplicationJavaClass – The full Java class name to use in place of android.app.Application when a class inherits from Android.App.Application.

This property is generally set by other properties, such as the $(AndroidEnableMultiDex) MSBuild property.

Added in Xamarin.Android 6.1.
AndroidBinUtilsPath – A path to a directory containing the Android binutils such as ld, the native linker, and as, the native assembler. These tools are part of the Android NDK and are also included in the Xamarin.Android installation.

The default value is $(MonoAndroidBinDirectory)\ndk\.

Added in Xamarin.Android 10.0.
AndroidBoundExceptionType – A string value that specifies how exceptions should be propagated when a Xamarin.Android-provided type implements a .NET type or interface in terms of Java types, for example Android.Runtime.InputStreamInvoker and System.IO.Stream, or Android.Runtime.JavaDictionary and System.Collections.IDictionary.
- Java: The original Java exception type is propagated as-is.
  
  This means that, for example, InputStreamInvoker does not properly implement the System.IO.Stream API because Java.IO.IOException may be thrown from Stream.Read() instead of System.IO.IOException.
  
  This is the exception propagation behavior in all releases of Xamarin.Android prior to 10.2.
  
  This is the default value in Xamarin.Android 10.2.
- System: The original Java exception type is caught and wrapped in an appropriate .NET exception type.
  
  This means that, for example, InputStreamInvoker properly implements System.IO.Stream, and Stream.Read() will not throw Java.IO.IOException instances. (It may instead throw a System.IO.IOException which has a Java.IO.IOException as the Exception.InnerException value.)
  
  This will become the default value in Xamarin.Android 11.0.
Added in Xamarin.Android 10.2.
AndroidBuildApplicationPackage – A boolean value that indicates whether to create and sign the package (.apk). Setting this value to True is equivalent to using the SignAndroidPackage build target.

Support for this property was added after Xamarin.Android 7.1.

This property is False by default.
AndroidBundleConfigurationFile – Specifies a filename to use as a configuration file for bundletool when building an Android App Bundle. This file controls some aspects of how APKs are generated from the bundle, such as on what dimensions the bundle is split to produce APKs. Note that Xamarin.Android configures some of these settings automatically, including the list of file extensions to leave uncompressed.

This property is only relevant if $(AndroidPackageFormat) is set to aab.

Added in Xamarin.Android 10.3.
AndroidDexTool – An enum-style property with valid values of dx or d8. Indicates which Android dex compiler is used during the Xamarin.Android build process. Currently defaults to dx. For further information see our documentation on D8 and R8.
AndroidEnableDesugar – A boolean property that determines if desugar is enabled. Android does not currently support all Java 8 features, and the default toolchain implements the new language features by performing bytecode transformations, called desugar, on the output of the javac compiler. Defaults to False if using AndroidDexTool=dx and defaults to True if using AndroidDexTool=d8.
AndroidEnableGooglePlayStoreChecks – A bool property which allows developers to disable the following Google Play Store checks: XA1004, XA1005 and XA1006. This is useful for developers who are not targeting the Google Play Store and do not wish to run those checks.

Added in Xamarin.Android 9.4.
AndroidEnableMultiDex – A boolean property that determines whether or not multi-dex support will be used in the final .apk.

Support for this property was added in Xamarin.Android 5.1.

This property is False by default.
AndroidEnablePreloadAssemblies – A boolean property which controls whether or not all managed assemblies bundled within the application package are loaded during process startup or not.

When set to True, all assemblies bundled within the application package will be loaded during process startup, before any application code is invoked. This is consistent with what Xamarin.Android did in releases prior to Xamarin.Android 9.2.

When set to False, assemblies will only be loaded on an as-needed basis. This allows applications to startup faster, and is also more consistent with desktop .NET semantics. To see the time savings, set the debug.mono.log System Property to include timing, and look for the Finished loading assemblies: preloaded message within adb logcat.

Applications or libraries which use dependency injection may require that this property be True if they in turn require that AppDomain.CurrentDomain.GetAssemblies() return all assemblies within the application bundle, even if the assembly wouldn't otherwise have been needed.

By default this value will be set to True.

Added in Xamarin.Android 9.2.
AndroidEnableProfiledAot – A boolean property that determines whether or not the AOT profiles are used during Ahead-of-Time compilation.

The profiles are listed in AndroidAotProfile item group. This ItemGroup contains default profile(s). It can be overriden by removing the existing one(s) and adding your own AOT profiles.

Support for this property was added in Xamarin.Android 9.4.

This property is False by default.
AndroidEnableSGenConcurrent – A boolean property that determines whether or not Mono's concurrent GC collector will be used.

Support for this property was added in Xamarin.Android 7.2.

This property is False by default.
AndroidErrorOnCustomJavaObject – A boolean property that determines whether types may implement Android.Runtime.IJavaObject without also inheriting from Java.Lang.Object or Java.Lang.Throwable:
```
class BadType : IJavaObject {
    public IntPtr Handle {
        get {return IntPtr.Zero;}
    }

    public void Dispose()
    {
    }
}
```
When True, such types will generate an XA4212 error, otherwise a XA4212 warning will be generated.

Support for this property was added in Xamarin.Android 8.1.

This property is True by default.
AndroidExtraAotOptions – A string property that allows passing additional options to the Mono compiler during the Aot task for projects that have either $(AndroidEnableProfiledAot) or $(AotAssemblies) set to true. The string value of the property is added to the response file when calling the Mono cross-compiler.

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.

Added in Xamarin.Android 10.2.
AndroidFastDeploymentType – A : (colon)-separated list of values to control what types can be deployed to the Fast Deployment directory on the target device when the $(EmbedAssembliesIntoApk) MSBuild property is False. If a resource is fast deployed, it is not embedded into the generated .apk, which can speed up deployment times. (The more that is fast deployed, then the less frequently the .apk needs to be rebuilt, and the install process can be faster.) Valid values include:
- Assemblies: Deploy application assemblies.
- Dexes: Deploy .dex files, Android Resources, and Android Assets. This value can only be used on devices running Android 4.4 or later (API-19).
The default value is Assemblies.

Experimental. Added in Xamarin.Android 6.1.
AndroidGenerateJniMarshalMethods – A bool property which enables generating of JNI marshal methods as part of the build process. This greatly reduces the System.Reflection usage in the binding helper code.

By default this will be set to False. If the developers wish to use the new JNI marshal methods feature, they can set
```
<AndroidGenerateJniMarshalMethods>True</AndroidGenerateJniMarshalMethods>
```
in their .csproj. Alternatively provide the property on the command line via
```
/p:AndroidGenerateJniMarshalMethods=True
```
Experimental. Added in Xamarin.Android 9.2. The default value is False.
AndroidGenerateJniMarshalMethodsAdditionalArguments – A string property which can be used to add additional parameters to the jnimarshalmethod-gen.exe invocation. This is useful for debugging, so that options such as -v, -d, or --keeptemp can be used.

Default value is empty string. It can be set in the .csproj file or on the command line. For example:
```
<AndroidGenerateJniMarshalMethodsAdditionalArguments>-v -d --keeptemp</AndroidGenerateJniMarshalMethodsAdditionalArguments>
```
or:
```
/p:AndroidGenerateJniMarshalMethodsAdditionalArguments="-v -d --keeptemp"
```
Added in Xamarin.Android 9.2.
AndroidHttpClientHandlerType – Controls the default System.Net.Http.HttpMessageHandler implementation which will be used by the System.Net.Http.HttpClient default constructor. The value is an assembly-qualified type name of an HttpMessageHandler subclass, suitable for use with System.Type.GetType(string). The most common values for this property are:
- Xamarin.Android.Net.AndroidClientHandler: Use the Android Java APIs to perform network requests. This allows accessing TLS 1.2 URLs when the underlying Android version supports TLS 1.2. Only Android 5.0 and later reliably provide TLS 1.2 support through Java.
  
  This corresponds to the Android option in the Visual Studio property pages and the AndroidClientHandler option in the Visual Studio for Mac property pages.
  
  The new project wizard selects this option for new projects when the Minimum Android Version is configured to Android 5.0 (Lollipop) or higher in Visual Studio or when Target Platforms is set to Latest and Greatest in Visual Studio for Mac.
- Unset/the empty string: This is equivalent to System.Net.Http.HttpClientHandler, System.Net.Http
  
  This corresponds to the Default option in the Visual Studio property pages.
  
  The new project wizard selects this option for new projects when the Minimum Android Version is configured to Android 4.4.87 or lower in Visual Studio or when Target Platforms is set to Modern Development or Maximum Compatibility in Visual Studio for Mac.
- System.Net.Http.HttpClientHandler, System.Net.Http: Use the managed HttpMessageHandler.
  
  This corresponds to the Managed option in the Visual Studio property pages.
Note

If TLS 1.2 support is required on Android versions prior to 5.0, or if TLS 1.2 support is required with the System.Net.WebClient and related APIs, then $(AndroidTlsProvider) should be used.

Note

Support for this property works by setting the XA_HTTP_CLIENT_HANDLER_TYPE environment variable. A $XA_HTTP_CLIENT_HANDLER_TYPE value found in a file with a Build action of @(AndroidEnvironment) will take precedence.

Added in Xamarin.Android 6.1.
AndroidLinkMode – Specifies which type of linking should be performed on assemblies contained within the Android package. Only used in Android Application projects. The default value is SdkOnly. Valid values are:
- None: No linking will be attempted.
- SdkOnly: Linking will be performed on the base class libraries only, not user's assemblies.
- Full: Linking will be performed on base class libraries and user assemblies.
  
  Note
  
  Using an AndroidLinkMode value of Full often results in broken apps, particularly when Reflection is used. Avoid unless you really know what you're doing.
```
<AndroidLinkMode>SdkOnly</AndroidLinkMode>
```
AndroidLinkSkip – Specifies a semicolon-delimited (;) list of assembly names, without file extensions, of assemblies that should not be linked. Only used within Android Application projects.
```
<AndroidLinkSkip>Assembly1;Assembly2</AndroidLinkSkip>
```
AndroidLinkTool – An enum-style property with valid values of proguard or r8. Indicates which code shrinker is used for Java code. Currently defaults to an empty string, or proguard if $(AndroidEnableProguard) is True. For further information see our documentation on D8 and R8.
AndroidLintEnabled – A bool property which allows the developer to run the android lint tool as part of the packaging process.
- AndroidLintEnabledIssues – A comma separated list of lint issues to enable.
- AndroidLintDisabledIssues – A comma separated list of lint issues to disable.
- AndroidLintCheckIssues – A comma separated list of lint issues to check. Note: only these issues will be checked.
- AndroidLintConfig – This is a Build action for a lint style config file. This can be used to enabled/disable issues to check. Multiple files can use this build action as their contents will be merged.
See Lint Help for more details on the android lint tooling.
AndroidManagedSymbols – A boolean property that controls whether sequence points are generated so that file name and line number information can be extracted from Release stack traces.

Added in Xamarin.Android 6.1.
AndroidManifest – Specifies a filename to use as the template for the app's AndroidManifest.xml. During the build, any other necessary values will be merged into to produce the actual AndroidManifest.xml. The $(AndroidManifest) must contain the package name in the /manifest/@package attribute.
AndroidManifestMerger – Specifies the implementation for merging AndroidManifest.xml files. This is an enum-style property where legacy selects the original C# implementation and manifestmerger.jar selects Google's Java implementation.

The default value is currently legacy. This will change to manifestmerger.jar in a future release to align behavior with Android Studio.

Google's merger enables support for xmlns:tools="http://schemas.android.com/tools" as described in the Android documentation.

Introduced in Xamarin.Android 10.2
AndroidMultiDexClassListExtraArgs – A string property which allows developers to pass additional arguments to the com.android.multidex.MainDexListBuilder when generating the multidex.keep file.

One specific case is if you are getting the following error during the dx compilation.
```
com.android.dex.DexException: Too many classes in --main-dex-list, main dex capacity exceeded
```
If you are getting this error you can add the following to the .csproj.
```
<DxExtraArguments>--force-jumbo </DxExtraArguments>
<AndroidMultiDexClassListExtraArgs>--disable-annotation-resolution-workaround</AndroidMultiDexClassListExtraArgs>
```
this should allow the dx step to succeed.

Added in Xamarin.Android 8.3.
AndroidPackageFormat – An enum-style property with valid values of apk or aab. This indicates if you want to package the Android application as an APK file or Android App Bundle. App Bundles are a new format for Release builds that are intended for submission on Google Play. This value currently defaults to apk.

When $(AndroidPackageFormat) is set to aab, other MSBuild properties are set, which are required for Android App Bundles:
- $(AndroidUseAapt2) is True.
- $(AndroidUseApkSigner) is False.
- $(AndroidCreatePackagePerAbi) is False.
AndroidPackageNamingPolicy – An enum-style property for specifying the Java package names of generated Java source code.

In Xamarin.Android 10.2 and later, the only supported value is LowercaseCrc64.

In Xamarin.Android 10.1, a transitional LowercaseMD5 value was also available that allowed switching back to the original Java package name style as used in Xamarin.Android 10.0 and earlier. That option was removed in Xamarin.Android 10.2 to improve compatibility with build environments that have FIPS compliance enforced.

Added in Xamarin.Android 10.1.
AndroidR8JarPath – The path to r8.jar for use with the r8 dex-compiler and shrinker. Defaults to a path in the Xamarin.Android installation. For further information see our documentation on D8 and R8.
AndroidSdkBuildToolsVersion – The Android SDK build-tools package provides the aapt and zipalign tools, among others. Multiple different versions of the build-tools package may be installed simultaneously. The build-tools package chosen for packaging is done by checking for and using a "preferred" build-tools version if it is present; if the "preferred" version is not present, then the highest versioned installed build-tools package is used.

The $(AndroidSdkBuildToolsVersion) MSBuild property contains the preferred build-tools version. The Xamarin.Android build system provides a default value in Xamarin.Android.Common.targets, and the default value may be overridden within your project file to choose an alternate build-tools version, if (for example) the latest aapt is crashing out while a previous aapt version is known to work.
AndroidSupportedAbis – A string property that contains a semicolon (;)-delimited list of ABIs which should be included into the .apk.

Supported values include:
- armeabi-v7a
- x86
- arm64-v8a: Requires Xamarin.Android 5.1 and later.
- x86_64: Requires Xamarin.Android 5.1 and later.
AndroidTlsProvider – A string value which specifies which TLS provider should be used in an application. Possible values are:
- Unset/the empty string: In Xamarin.Android 7.3 and higher, this is equivalent to btls.
  
  In Xamarin.Android 7.1, this is equivalent to legacy.
  
  This corresponds to the Default setting in the Visual Studio property pages.
- btls: Use Boring SSL for TLS communication with HttpWebRequest.
  
  This allows use of TLS 1.2 on all Android versions.
  
  This corresponds to the Native TLS 1.2+ setting in the Visual Studio property pages.
- legacy: In Xamarin.Android 10.1 and earlier, use the historical managed SSL implementation for network interaction. This does not support TLS 1.2.
  
  This corresponds to the Managed TLS 1.0 setting in the Visual Studio property pages.
  
  In Xamarin.Android 10.2 and later, this value is ignored and the btls setting is used.
- default: This value is unlikely to be used in Xamarin.Android projects. The recommended value to use instead is the empty string, which corresponds to the Default setting in the Visual Studio property pages.
  
  The default value is not offered in the Visual Studio property pages.
  
  This is currently equivalent to legacy.
Added in Xamarin.Android 7.1.
AndroidUseApkSigner – A bool property which allows the developer to use the to the apksigner tool rather than the jarsigner.

Added in Xamarin.Android 8.2.
AndroidUseDefaultAotProfile – A bool property that allows the developer to suppress usage of the default AOT profiles.

To suppress the default AOT profiles, set the property to false.

Added in Xamarin.Android 10.1.
AndroidUseLegacyVersionCode – A boolean property will allows the developer to revert the versionCode calculation back to its old pre Xamarin.Android 8.2 behavior. This should ONLY be used for developers with existing applications in the Google Play Store. It is highly recommended that the new $(AndroidVersionCodePattern) property is used.

Added in Xamarin.Android 8.2.
AndroidUseManagedDesignTimeResourceGenerator – A boolean property which will switch over the design time builds to use the managed resource parser rather than aapt.

Added in Xamarin.Android 8.1.
AndroidUseSharedRuntime – A boolean property that is determines whether the shared runtime packages are required in order to run the Application on the target device. Relying on the shared runtime packages allows the Application package to be smaller, speeding up the package creation and deployment process, resulting in a faster build/deploy/debug turnaround cycle.

This property should be True for Debug builds, and False for Release projects.
AndroidVersionCodePattern – A string property which allows the developer to customize the versionCode in the manifest. See Creating the Version Code for the APK for information on deciding a versionCode.

Some examples, if abi is armeabi and versionCode in the manifest is 123, {abi}{versionCode} will produce a versionCode of 1123 when $(AndroidCreatePackagePerAbi) is True, otherwise will produce a value of 123. If abi is x86_64 and versionCode in the manifest is 44. This will produce 544 when $(AndroidCreatePackagePerAbi) is True, otherwise will produce a value of 44.

If we include a left padding format string {abi}{versionCode:0000}, it would produce 50044 because we are left padding the versionCode with 0. Alternatively, you can use the decimal padding such as {abi}{versionCode:D4} which does the same as the previous example.

Only '0' and 'Dx' padding format strings are supported since the value MUST be an integer.

Pre-defined key items
- abi – Inserts the targeted abi for the app
  - 2 – armeabi-v7a
  - 3 – x86
  - 4 – arm64-v8a
  - 5 – x86_64
- minSDK – Inserts the minimum supported Sdk value from the AndroidManifest.xml or 11 if none is defined.
- versionCode – Uses the version code directly from Properties\AndroidManifest.xml.
You can define custom items using the $(AndroidVersionCodeProperties) property (defined next).

By default the value will be set to {abi}{versionCode:D6}. If a developer wants to keep the old behavior you can override the default by setting the $(AndroidUseLegacyVersionCode) property to true

Added in Xamarin.Android 7.2.
AndroidVersionCodeProperties – A string property which allows the developer to define custom items to use with the AndroidVersionCodePattern. They are in the form of a key=value pair. All items in the value should be integer values. For example: screen=23;target=$(_AndroidApiLevel). As you can see you can make use of existing or custom MSBuild properties in the string.

Added in Xamarin.Android 7.2.
AotAssemblies – A boolean property that determines whether or not assemblies will be Ahead-of-Time compiled into native code and included in the .apk.

Support for this property was added in Xamarin.Android 5.1.

This property is False by default.
EmbedAssembliesIntoApk – A boolean property that determines whether or not the app's assemblies should be embedded into the Application package.

This property should be True for Release builds and False for Debug builds. It may need to be True in Debug builds if Fast Deployment doesn't support the target device.

When this property is False, then the $(AndroidFastDeploymentType) MSBuild property also controls what will be embedded into the .apk, which can impact deployment and rebuild times.
EnableLLVM – A boolean property that determines whether or not LLVM will be used when Ahead-of-Time compiling assemblies into native code.

The Android NDK must be installed to build a project that has this property enabled.

Support for this property was added in Xamarin.Android 5.1.

This property is False by default.

This property is ignored unless the $(AotAssemblies) MSBuild property is True.
EnableProguard – A boolean property that determines whether or not proguard is run as part of the packaging process to link Java code.

Support for this property was added in Xamarin.Android 5.1.

This property is False by default.

When True, ProguardConfiguration files will be used to control proguard execution.
JavaMaximumHeapSize – Specifies the value of the java -Xmx parameter value to use when building the .dex file as part of the packaging process. If not specified, then the -Xmx option supplies java with a value of 1G. This was found to be commonly required on Windows in comparison to other platforms.

Specifying this property is necessary if the _CompileDex target throws a java.lang.OutOfMemoryError.

Customize the value by changing:
```
<JavaMaximumHeapSize>1G</JavaMaximumHeapSize>
```
JavaOptions – Specifies additional command-line options to pass to java when building the .dex file.
LinkerDumpDependencies – A bool property which enables generating of linker dependencies file. This file can be used as input for illinkanalyzer tool.

The default value is False.
MandroidI18n – Specifies the internationalization support included with the Application, such as collation and sorting tables. The value is a comma- or semicolon-separated list of one or more of the following case-insensitive values:
- None: Include no additional encodings.
- All: Include all available encodings.
- CJK: Include Chinese, Japanese, and Korean encodings such as Japanese (EUC) [enc-jp, CP51932], Japanese (Shift-JIS) [iso-2022-jp, shift_jis, CP932], Japanese (JIS) [CP50220], Chinese Simplified (GB2312) [gb2312, CP936], Korean (UHC) [ks_c_5601-1987, CP949], Korean (EUC) [euc-kr, CP51949], Chinese Traditional (Big5) [big5, CP950], and Chinese Simplified (GB18030) [GB18030, CP54936].
- MidEast: Include Middle-Eastern encodings such as Turkish (Windows) [iso-8859-9, CP1254], Hebrew (Windows) [windows-1255, CP1255], Arabic (Windows) [windows-1256, CP1256], Arabic (ISO) [iso-8859-6, CP28596], Hebrew (ISO) [iso-8859-8, CP28598], Latin 5 (ISO) [iso-8859-9, CP28599], and Hebrew (Iso Alternative) [iso-8859-8, CP38598].
- Other: Include Other encodings such as Cyrillic (Windows) [CP1251], Baltic (Windows) [iso-8859-4, CP1257], Vietnamese (Windows) [CP1258], Cyrillic (KOI8-R) [koi8-r, CP1251], Ukrainian (KOI8-U) [koi8-u, CP1251], Baltic (ISO) [iso-8859-4, CP1257], Cyrillic (ISO) [iso-8859-5, CP1251], ISCII Davenagari [x-iscii-de, CP57002], ISCII Bengali [x-iscii-be, CP57003], ISCII Tamil [x-iscii-ta, CP57004], ISCII Telugu [x-iscii-te, CP57005], ISCII Assamese [x-iscii-as, CP57006], ISCII Oriya [x-iscii-or, CP57007], ISCII Kannada [x-iscii-ka, CP57008], ISCII Malayalam [x-iscii-ma, CP57009], ISCII Gujarati [x-iscii-gu, CP57010], ISCII Punjabi [x-iscii-pa, CP57011], and Thai (Windows) [CP874].
- Rare: Include Rare encodings such as IBM EBCDIC (Turkish) [CP1026], IBM EBCDIC (Open Systems Latin 1) [CP1047], IBM EBCDIC (US-Canada with Euro) [CP1140], IBM EBCDIC (Germany with Euro) [CP1141], IBM EBCDIC (Denmark/Norway with Euro) [CP1142], IBM EBCDIC (Finland/Sweden with Euro) [CP1143], IBM EBCDIC (Italy with Euro) [CP1144], IBM EBCDIC (Latin America/Spain with Euro) [CP1145], IBM EBCDIC (United Kingdom with Euro) [CP1146], IBM EBCDIC (France with Euro) [CP1147], IBM EBCDIC (International with Euro) [CP1148], IBM EBCDIC (Icelandic with Euro) [CP1149], IBM EBCDIC (Germany) [CP20273], IBM EBCDIC (Denmark/Norway) [CP20277], IBM EBCDIC (Finland/Sweden) [CP20278], IBM EBCDIC (Italy) [CP20280], IBM EBCDIC (Latin America/Spain) [CP20284], IBM EBCDIC (United Kingdom) [CP20285], IBM EBCDIC (Japanese Katakana Extended) [CP20290], IBM EBCDIC (France) [CP20297], IBM EBCDIC (Arabic) [CP20420], IBM EBCDIC (Hebrew) [CP20424], IBM EBCDIC (Icelandic) [CP20871], IBM EBCDIC (Cyrillic - Serbian, Bulgarian) [CP21025], IBM EBCDIC (US-Canada) [CP37], IBM EBCDIC (International) [CP500], Arabic (ASMO 708) [CP708], Central European (DOS) [CP852], Cyrillic (DOS) [CP855], Turkish (DOS) [CP857], Western European (DOS with Euro) [CP858], Hebrew (DOS) [CP862], Arabic (DOS) [CP864], Russian (DOS) [CP866], Greek (DOS) [CP869], IBM EBCDIC (Latin 2) [CP870], and IBM EBCDIC (Greek) [CP875].
- West: Include Western encodings such as Western European (Mac) [macintosh, CP10000], Icelandic (Mac) [x-mac-icelandic, CP10079], Central European (Windows) [iso-8859-2, CP1250], Western European (Windows) [iso-8859-1, CP1252], Greek (Windows) [iso-8859-7, CP1253], Central European (ISO) [iso-8859-2, CP28592], Latin 3 (ISO) [iso-8859-3, CP28593], Greek (ISO) [iso-8859-7, CP28597], Latin 9 (ISO) [iso-8859-15, CP28605], OEM United States [CP437], Western European (DOS) [CP850], Portuguese (DOS) [CP860], Icelandic (DOS) [CP861], French Canadian (DOS) [CP863], and Nordic (DOS) [CP865].
```
<MandroidI18n>West</MandroidI18n>
```
MonoSymbolArchive – A boolean property which controls whether .mSYM artifacts are created for later use with mono-symbolicate, to extract “real” filename and line number information from Release stack traces.

This is True by default for “Release” apps which have debugging symbols enabled: $(EmbedAssembliesIntoApk) is True, $(DebugSymbols) is True, and $(Optimize) is True.

Added in Xamarin.Android 7.1.

Binding Project Build Properties

The following MSBuild properties are used with Binding projects:

AndroidClassParser – A string property which controls how .jar files are parsed. Possible values include:
- class-parse: Uses class-parse.exe to parse Java bytecode directly, without assistance of a JVM. This value is experimental.
- jar2xml: Use jar2xml.jar to use Java reflection to extract types and members from a .jar file.
The advantages of class-parse over jar2xml are:
- class-parse is able to extract parameter names from Java bytecode which contains debug symbols (e.g. bytecode compiled with javac -g).
- class-parse doesn't "skip" classes which inherit from or contain members of unresolvable types.
Experimental. Added in Xamarin.Android 6.0.

The default value is jar2xml.

The default value will change in a future release.
AndroidCodegenTarget – A string property which controls the code generation target ABI. Possible values include:
- XamarinAndroid: Uses the JNI binding API present since Mono for Android 1.0. Binding assemblies built with Xamarin.Android 5.0 or later can only run on Xamarin.Android 5.0 or later (API/ABI additions), but the source is compatible with prior product versions.
- XAJavaInterop1: Use Java.Interop for JNI invocations. Binding assemblies using XAJavaInterop1 can only build and execute with Xamarin.Android 6.1 or later. Xamarin.Android 6.1 and later bind Mono.Android.dll with this value.
  
  The benefits of XAJavaInterop1 include:
  - Smaller assemblies.
  - jmethodID caching for base method invocations, so long as all other binding types in the inheritance hierarchy are built with XAJavaInterop1 or later.
  - jmethodID caching of Java Callable Wrapper constructors for managed subclasses.
  The default value is XAJavaInterop1.

Resource Properties

Resource properties control the generation of the Resource.designer.cs file, which provides access to Android resources.

AndroidAapt2CompileExtraArgs – Specifies additional command-line options to pass to the aapt2 compile command when processing Android assets and resources.

Added in Xamarin.Android 9.1.
AndroidAapt2LinkExtraArgs – Specifies additional command-line options to pass to the aapt2 link command when processing Android assets and resources.

Added in Xamarin.Android 9.1.
AndroidExplicitCrunch – If you are building an app with a very large number of local drawables, an initial build (or rebuild) can take minutes to complete. To speed up the build process, try including this property and setting it to True. When this property is set, the build process pre-crunches the .png files.

Note: This option is not compatible with the $(AndroidUseAapt2) option. If $(AndroidUseAapt2) is enabled, this functionality will be disabled. If you wish to continue to use this feature please set $(AndroidUseAapt2) to False.

Experimental. Added in Xamarin.Android 7.0.
AndroidResgenExtraArgs – Specifies additional command-line options to pass to the aapt command when processing Android assets and resources.
AndroidResgenFile – Specifies the name of the Resource file to generate. The default template sets this to Resource.designer.cs.
AndroidUseAapt2 – A bool property which allows the developer to control the use of the aapt2 tool for packaging. By default this will be set to false and we will use aapt. If the developer wishes to use the new aapt2 functionality they can set
```
<AndroidUseAapt2>True</AndroidUseAapt2>
```
in their .csproj. Alternatively provide the property on the command line via
```
/p:AndroidUseAapt2=True
```
Added in Xamarin.Android 8.3.
MonoAndroidResourcePrefix – Specifies a path prefix that is removed from the start of filenames with a Build action of AndroidResource. This is to allow changing where resources are located.

The default value is Resources. Change this to res for the Java project structure.

Signing Properties

Signing properties control how the Application package is signed so that it may be installed onto an Android device. To allow quicker build iteration, the Xamarin.Android tasks do not sign packages during the build process, because signing is quite slow. Instead, they are signed (if necessary) before installation or during export, by the IDE or the Install build target. Invoking the SignAndroidPackage target will produce a package with the -Signed.apk suffix in the output directory.

By default, the signing target generates a new debug-signing key if necessary. If you wish to use a specific key, for example on a build server, the following MSBuild properties can be used:

AndroidDebugKeyAlgorithm – Specifies the default algorithm to use for the debug.keystore. It defaults to RSA.
AndroidDebugKeyValidity – Specifies the default validity to use for the debug.keystore. It defaults to 10950 or 30 * 365 or 30 years.
AndroidDebugStoreType – Specifies the key store file format to use for the debug.keystore. It defaults to pkcs12.

Added in Xamarin.Android 10.2.
AndroidKeyStore – A boolean value which indicates whether custom signing information should be used. The default value is False, meaning that the default debug-signing key will be used to sign packages.
AndroidSigningKeyAlias – Specifies the alias for the key in the keystore. This is the keytool -alias value used when creating the keystore.
AndroidSigningKeyPass – Specifies the password of the key within the keystore file. This is the value entered when keytool asks Enter key password for $(AndroidSigningKeyAlias).

In Xamarin.Android 10.0 and earlier, this property only supports plain text passwords.

In Xamarin.Android 10.1 and later, this property also supports env: and file: prefixes that can be used to specify an environment variable or file that contains the password. These options provide a way to prevent the password from appearing in build logs.

For example, to use an environment variable named AndroidSigningPassword:
```
<PropertyGroup>
    <AndroidSigningKeyPass>env:AndroidSigningPassword</AndroidSigningKeyPass>
</PropertyGroup>
```
To use a file located at C:\Users\user1\AndroidSigningPassword.txt:
```
<PropertyGroup>
    <AndroidSigningKeyPass>file:C:\Users\user1\AndroidSigningPassword.txt</AndroidSigningKeyPass>
</PropertyGroup>
```
Note

The env: prefix is not supported when $(AndroidPackageFormat) is set to aab.
AndroidSigningKeyStore – Specifies the filename of the keystore file created by keytool. This corresponds to the value provided to the keytool -keystore option.
AndroidSigningStorePass – Specifies the password to $(AndroidSigningKeyStore). This is the value provided to keytool when creating the keystore file and asked Enter keystore password:.

In Xamarin.Android 10.0 and earlier, this property only supports plain text passwords.

In Xamarin.Android 10.1 and later, this property also supports env: and file: prefixes that can be used to specify an environment variable or file that contains the password. These options provide a way to prevent the password from appearing in build logs.

For example, to use an environment variable named AndroidSigningPassword:
```
<PropertyGroup>
    <AndroidSigningStorePass>env:AndroidSigningPassword</AndroidSigningStorePass>
</PropertyGroup>
```
To use a file located at C:\Users\user1\AndroidSigningPassword.txt:
```
<PropertyGroup>
    <AndroidSigningStorePass>file:C:\Users\user1\AndroidSigningPassword.txt</AndroidSigningStorePass>
</PropertyGroup>
```
Note

The env: prefix is not supported when $(AndroidPackageFormat) is set to aab.
JarsignerTimestampAuthorityCertificateAlias – This property allows you to specify an alias in the keystore for a timestamp authority. See the Java Signature Timestamp Support documentation for more details.
```
<PropertyGroup>
    <JarsignerTimestampAuthorityCertificateAlias>Alias</JarsignerTimestampAuthorityCertificateAlias>
</PropertyGroup>
```
JarsignerTimestampAuthorityUrl – This property allows you to specify a URL to a timestamp authority service. This can be used to make sure your .apk signature includes a timestamp. See the Java Signature Timestamp Support documentation for more details.
```
<PropertyGroup>
    <JarsignerTimestampAuthorityUrl>http://example.tsa.url</JarsignerTimestampAuthorityUrl>
</PropertyGroup>
```

For example, consider the following keytool invocation:

$ keytool -genkey -v -keystore filename.keystore -alias keystore.alias -keyalg RSA -keysize 2048 -validity 10000
Enter keystore password: keystore.filename password
Re-enter new password: keystore.filename password
...
Is CN=... correct?
  [no]:  yes

Generating 2,048 bit RSA key pair and self-signed certificate (SHA1withRSA) with a validity of 10,000 days
        for: ...
Enter key password for keystore.alias
        (RETURN if same as keystore password): keystore.alias password
[Storing filename.keystore]

To use the keystore generated above, use the property group:

<PropertyGroup>
    <AndroidKeyStore>True</AndroidKeyStore>
    <AndroidSigningKeyStore>filename.keystore</AndroidSigningKeyStore>
    <AndroidSigningStorePass>keystore.filename password</AndroidSigningStorePass>
    <AndroidSigningKeyAlias>keystore.alias</AndroidSigningKeyAlias>
    <AndroidSigningKeyPass>keystore.alias password</AndroidSigningKeyPass>
</PropertyGroup>

Build Actions

Build actions are applied to files within the project and control how the file is processed.

AndroidAarLibrary

The Build action of AndroidAarLibrary should be used to directly reference .aar files. This build action will be most commonly used by Xamarin Components. Namely to include references to .aar files which are required to get Google Play and other services working.

Files with this Build action will be treated in a similar fashion too the embedded resources found in Library projects. The .aar will be extracted into the intermediate directory. Then any assets, resource and .jar files will be included in the appropriate item groups.

AndroidBoundLayout

Indicates that the layout file is to have code-behind generated for it in case when the AndroidGenerateLayoutBindings property is set to false. In all other aspects it is identical to AndroidResource described above. This action can be used only with layout files:

<AndroidBoundLayout Include="Resources\layout\Main.axml" />

AndroidEnvironment

Files with a Build action of AndroidEnvironment are used to initialize environment variables and system properties during process startup. The AndroidEnvironment Build action may be applied to multiple files, and they will be evaluated in no particular order (so don't specify the same environment variable or system property in multiple files).

AndroidFragmentType

Specifies the default fully qualified type to be used for all <fragment> layout elements when generating the layout bindings code. The property defaults to the standard Android Android.App.Fragment type.

AndroidJavaLibrary

Files with a Build action of AndroidJavaLibrary are Java Archives ( .jar files) which will be included in the final Android package.

AndroidJavaSource

Files with a Build action of AndroidJavaSource are Java source code which will be included in the final Android package.

AndroidLintConfig

The Build action 'AndroidLintConfig' should be used in conjunction with the AndroidLintEnabled build property. Files with this build action will be merged together and passed to the android lint tooling. They should be XML files which contain information on which tests to enable and disable.

See the lint documentation for more details.

AndroidNativeLibrary

Native libraries are added to the build by setting their Build action to AndroidNativeLibrary.

Note that since Android supports multiple Application Binary Interfaces (ABIs), the build system must know which ABI the native library is built for. There are two ways this can be done:

Path "sniffing".
Using the Abi item attribute.

With path sniffing, the parent directory name of the native library is used to specify the ABI that the library targets. Thus, if you add lib/armeabi-v7a/libfoo.so to the build, then the ABI will be "sniffed" as armeabi-v7a.

Item Attribute Name

Abi – Specifies the ABI of the native library.

<ItemGroup>
  <AndroidNativeLibrary Include="path/to/libfoo.so">
    <Abi>armeabi-v7a</Abi>
  </AndroidNativeLibrary>
</ItemGroup>

AndroidResource

All files with an AndroidResource build action are compiled into Android resources during the build process and made accessible via $(AndroidResgenFile).

<ItemGroup>
  <AndroidResource Include="Resources\values\strings.xml" />
</ItemGroup>

More advanced users might perhaps wish to have different resources used in different configurations but with the same effective path. This can be achieved by having multiple resource directories and having files with the same relative paths within these different directories, and using MSBuild conditions to conditionally include different files in different configurations. For example:

<ItemGroup Condition="'$(Configuration)'!='Debug'">
  <AndroidResource Include="Resources\values\strings.xml" />
</ItemGroup>
<ItemGroup  Condition="'$(Configuration)'=='Debug'">
  <AndroidResource Include="Resources-Debug\values\strings.xml"/>
</ItemGroup>
<PropertyGroup>
  <MonoAndroidResourcePrefix>Resources;Resources-Debug<MonoAndroidResourcePrefix>
</PropertyGroup>

LogicalName – Specifies the resource path explicitly. Allows “aliasing” files so that they will be available as multiple distinct resource names.

<ItemGroup Condition="'$(Configuration)'!='Debug'">
  <AndroidResource Include="Resources/values/strings.xml"/>
</ItemGroup>
<ItemGroup Condition="'$(Configuration)'=='Debug'">
  <AndroidResource Include="Resources-Debug/values/strings.xml">
    <LogicalName>values/strings.xml</LogicalName>
  </AndroidResource>
</ItemGroup>

AndroidResourceAnalysisConfig

The Build action AndroidResourceAnalysisConfig marks a file as a severity level configuration file for the Xamarin Android Designer layout diagnostics tool. This is currently only used in the layout editor and not for build messages.

See the Android Resource Analysis documentation for more details.

Added in Xamarin.Android 10.2.

Content

The normal Content Build action is not supported (as we haven't figured out how to support it without a possibly costly first-run step).

Starting in Xamarin.Android 5.1, attempting to use the @(Content) Build action will result in a XA0101 warning.

LinkDescription

Files with a LinkDescription build action are used to control linker behavior.

ProguardConfiguration

Files with a ProguardConfiguration build action contain options which are used to control proguard behavior. For more information about this build action, see ProGuard.

These files are ignored unless the $(EnableProguard) MSBuild property is True.

Target Definitions

The Xamarin.Android-specific parts of the build process are defined in $(MSBuildExtensionsPath)\Xamarin\Android\Xamarin.Android.CSharp.targets, but normal language-specific targets such as Microsoft.CSharp.targets are also required to build the assembly.

The following build properties must be set before importing any language targets:

<PropertyGroup>
  <TargetFrameworkIdentifier>MonoDroid</TargetFrameworkIdentifier>
  <MonoDroidVersion>v1.0</MonoDroidVersion>
  <TargetFrameworkVersion>v2.2</TargetFrameworkVersion>
</PropertyGroup>

All of these targets and properties can be included for C# by importing Xamarin.Android.CSharp.targets:

<Import Project="$(MSBuildExtensionsPath)\Xamarin\Android\Xamarin.Android.CSharp.targets" />

This file can easily be adapted for other languages.