This document will provide an overview of the Xamarin.Android build process.
The Xamarin.Android build process is responsible for gluing everything
and other build actions,
and generating a
.apk for execution on Android devices.
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 extra packages to execute. These are the packages that are provided to an App store.
Debug builds, which are not.
These package types match the MSBuild
produces the package.
Prior to Xamarin.Android 11.2, the shared runtime was a pair
of extra 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 could be disabled in Debug builds by setting the
Support for the Shared Runtime was removed in Xamarin.Android 11.2.
Fast deployment works by further shrinking Android application
package size. This is done by excluding the app's assemblies from the
package, and instead deploying the app's assemblies directly to the
files directory, usually located
/data/data/com.some.package. The internal
files directory is
not a globally writable folder, so the
run-as tool is used to execute
all the commands to copy the files into that directory.
This process speeds up the build/deploy/debug cycle because the package is not reinstalled when only assemblies are changed. Only the updated assemblies are resynchronized to the target device.
[!WARNING] Fast deployment is known to fail on devices which block
run-as, which often includes devices older than Android 5.0.
Fast deployment is enabled by default, and may be disabled in Debug builds
by setting the
$(EmbedAssembliesIntoApk) property to
The Enhanced Fast Deployment mode can
be used in conjunction with this feature to speed up deployments even further.
This will deploy both assemblies, native libraries, typemaps and dexes to the
directory. But you should only really need to enable this if you are changing
native libraries, bindings or Java code.
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.
The following MSBuild properties are used with Binding projects:
The Following MSBuild properties are used to control generation of the
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
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 are used:
keytool Option Mapping
Consider the following
$ 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 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>
Extension points include:
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.
The Xamarin.Android-specific parts of the build process are defined in
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.