Preparing an Application for Release (Visual Studio with Xamarin Android 6.1 and earlier)
- PDF for offline use
- Related Articles:
- Related Links:
Let us know how you feel about this
last updated: 2017-03
This guide explains how to sign an Android application package using Visual Studio with Xamarin Android 6.1 and earlier. If you are using Visual Studio with Xamarin Android 7.0 or later, see Part 1 - Preparing and Application for Release.
After an application has been coded and tested, it is necessary to prepare a package for distribution. The first task in preparing this package is to build the application for release, which mainly entails setting some application attributes.
Use the following steps to build the app for release:
Disable Debugging – This prevents users from trying to debug the application on a device by using adb or other tools.
Specify the Application Icon – Each Xamarin.Android application should have an application icon specified. It is not technically required; however, some markets, such as Google Play, require it.
Version the Application – This step involves initializing or updating the versioning information. This is important for future application updates and to ensure that the users are aware of which version of the application they have installed.
Configure the Linker – Linking is a step that is specific to Xamarin.Android and can substantially reduce the size of the final APK by removing unused code.
Set Packaging Properties – Packaging properties control the creation of the Android application package (APK). This step optimizes the APK, protects its assets, and modularizes the packaging as needed.
Compile – This step compiles the code and assets to verify that it builds in Release mode.
Each of these steps is described below in more detail.
During development of an Android application, debugging is performed with the use of the Java Debug Wire Protocol (JDWP). This is a technology that allows tools such as adb to communicate with a JVM for the purposes of debugging. JDWP is turned on by default for Debug builds of a Xamarin.Android application. While JDWP is important during development, it can pose a security issue for released applications.
Always disable the debug state in a released application as it is possible (via JDWP) to gain full access to the Java process and execute arbitrary code in the context of the application if this debug state is not disabled.
The Android Manifest contains the
android:debuggable attribute, which
controls whether or not the application may be debugged. It is
considered a good practice to set the
android:debuggable attribute to
false. The simplest way to do this is by adding a conditional compile
statement in AssemblyInfo.cs:
#if DEBUG [assembly: Application(Debuggable=true)] #else [assembly: Application(Debuggable=false)] #endif
Note that Debug builds automatically set some permissions to make debug easier (such as Internet and ReadExternalStorage). Release builds, however, use only the permissions that you explicitly configure. If you find that switching to the Release build causes your app to lose a permission that was available in the Debug build, verify that you have explicitly enabled this permission in the Required permissions list as described in Permissions.
Specify the Application Icon
It is strongly recommended that each Xamarin.Android application specify an application icon. Some application marketplaces will not allow an Android application to be published without one.
Icon property of the
Application attribute is used to specify
the application icon for a Xamarin.Android project. This attribute can
be declared in the file Properties\AssemblyInfo.cs, as shown in this
[assembly: Application(Icon = "@drawable/icon")]
In Visual Studio 2015 and later, the application icon can be set through the Android Manifest section of project Properties, as shown in the following screenshot:
Version the Application
Versioning is important for Android application maintenance and distribution. Without some sort of versioning in place, it is difficult to determine if or how an application should be updated. To assist with versioning, Android recognizes two different types of information:
Version Number – An integer value (used internally by Android and the application) that represents the version of the application. Most applications start out with this value set to 1, and then it is incremented with each build. This value has no relationship or affinity with the version name attribute (see below). Applications and publishing services should not display this value to users. This value is stored in the AndroidManifest.xml file as
Version Name – A string that is used only for communicating information to the user about the version of the application (as installed on a specific device). The version name is intended to be displayed to users or in Google Play. This string is not used internally by Android. The version name can be any string value that would help a user identify the build that is installed on their device. This value is stored in the AndroidManifest.xml file as
In Visual Studio, these values can be set in the Android Manifest section of project Properties, as shown in the following screenshot:
Configure the Linker
Release mode turns off the shared runtime and turns on linking so that the application only ships the pieces of Xamarin.Android required at runtime. The linker in Xamarin.Android uses static analysis to determine which assemblies, types, and type members are used or referenced by a Xamarin.Android application. The linker then discards all the unused assemblies, types, and members that are not used (or referenced). This can result in a significant reduction in the package size. For example, consider the HelloWorld sample, which experiences an 83% reduction in the final size of its APK:
- Configuration: None – Xamarin.Android 4.2.5 Size = 17.4 MB.
- Configuration: SDK Assemblies Only – Xamarin.Android 4.2.5 Size = 3.0 MB.
Configure the linker in the Android Options section of project Properties. To access the linker options, click the Linker tab as shown in the following screen shot:
The Linking pull-down menu provides the following options for controlling the linker:
None – This turns off the linker; no linking will be performed.
Sdk Assemblies Only – This will link only the assemblies that are required by Xamarin.Android. Other assemblies will not be linked.
Sdk and User Assemblies – This will link all assemblies that are required by the application, and not just the ones required by Xamarin.Android.
Linking can produce some unintended side effects, so it is important that an application be re-tested in Release mode and on a physical device.
Set Packaging Properties
Packaging properties can be set in the Android Options section of project Properties, as shown in the following screenshot:
Many of these properties, such as Use Shared Runtime, and Use Fast Deployment are intended for Debug mode. However, when the application is configured for Release mode, there are other settings that determine how the app is optimized for size and execution speed, how it is protected from tampering, and how it can be packaged to support different architectures and size restrictions.
Specify Supported Architectures
When preparing a Xamarin.Android app for release, it is necessary to specify the CPU architectures that are supported. A single APK can contain machine code to support multiple, different architectures. See CPU Architectures for details about supporting multiple CPU architectures.
Bundle Assemblies into Native Code
When this option is enabled, assemblies are bundled into a native shared library. This option keeps the code safe; it protects managed assemblies by embedding them in native binaries.
This option requires an Enterprise license and is only available when Use Fast Deployment is disabled. Bundle assemblies into native code is disabled by default.
Note that the Bundle into Native Code option does not mean that the assemblies are compiled into native code. It is not possible to use AOT Compilation to compile assemblies into native code (currently only an experimental feature, and not for production use).
Generate One Package (.APK) per Selected ABI
When this option is enabled, one APK will be created for each of the supported ABI's (selected on the Advanced tab, as described in CPU Architectures) rather than a single, large APK for all supported ABI's. This option is available only when the project is configured for Release mode, and it is disabled by default.
AOT is currently an experimental feature. It is not recommended for production use. AOT and LLVM was available in Xamarin.Android 5.1, but it is no longer available in later Xamarin.Android versions. For more information, please see the Xamarin.Android 6.1 release notes
The AOT Compilation option (on the Packaging Properties page) enables Ahead-of-Time (AOT) compilation of assemblies. When this option is enabled, Just In Time (JIT) startup overhead is minimized by precompiling assemblies before runtime. The resulting native code is included in the APK along with the uncompiled assemblies. This results in shorter application startup time, but at the expense of slightly larger APK sizes.
The AOT Compilation option requires an Enterprise license or higher. AOT compilation is available only when the project is configured for Release mode, and it is disabled by default. For more information about AOT Compilation, see AOT.
LLVM Optimizing Compiler
The LLVM Optimizing Compiler will create smaller and faster compiled code and convert AOT-compiled assemblies into native code, but at the expense of slower build times. The LLVM compiler is disabled by default. In order to use the LLVM compiler, the AOT Compilation option must first be enabled (on the Packaging Properties page).
The LLVM Optimizing Compiler option requires a Business license.
ProGuard is an Android SDK tool that links and obfuscates Java code. ProGuard is normally used to create smaller applications by reducing the footprint of large included libraries (such as Google Play Services) in your APK. ProGuard removes unused Java bytecode, which makes the resulting app smaller. For example, using ProGuard on small Xamarin.Android apps usually achieves about a 24% reduction in size – using ProGuard on larger apps with multiple library dependencies typically achieves an even greater size reduction.
ProGuard is not an alternative to the Xamarin.Android linker. The Xamarin.Android linker links managed code, while ProGuard links Java bytecode. The build process first uses the Xamarin.Android linker to optimize the managed (C#) code in the app, and then it later uses ProGuard (if enabled) to optimize the APK at the Java bytecode level.
When Enable ProGuard is checked, Xamarin.Android runs the ProGuard tool on the resulting APK. A ProGuard configuration file is generated and used by ProGuard at build time. Xamarin.Android also supports custom ProguardConfiguration build actions. You can add a custom ProGuard configuration file to your project, right-click it, and select it as a build action as shown in this example:
ProGuard is disabled by default. The Enable ProGuard option is available only when the project is set to Release mode. All ProGuard build actions are ignored unless Enable ProGuard is checked. The Xamarin.Android ProGuard configuration does not obfuscate the APK, and it is not possible to enable obfuscation, even with custom configuration files. If you wish to use obfuscation, please see Application Protection with Dotfuscator.
For more detailed information about using the ProGuard tool, see ProGuard.
When the Enable Multi-Dex option is enabled, Android SDK tools are used to bypass the 65K method limit of the .dex file format. The 65K method limitation is based on the number of Java methods that an app references (including those in any libraries that the app depends on) – it is not based on the number of methods that are written in the source code. If an application only defines a few methods but uses many (or large libraries), it is possible that the 65K limit will be exceeded.
It is possible that an app is not using every method in every library that is referenced; therefore, it is possible that a tool such as ProGuard (see above) can remove the unused methods from code. The best practice is to enable Enable Multi-Dex only if absolutely necessary, i.e.the app still references more than 65K Java methods even after using ProGuard.
For more information about Multi-Dex, see Configure Apps with Over 64K Methods.
After all of the above steps are completed, you are ready to compile the application (select Build > Rebuild Solution) to verify that it builds successfully in Release mode. Note that this step does not yet produce an APK.
In Part 2, we'll create an APK and sign the application.