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

Translation Quality


0/250

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.

Disable Debugging

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.

The 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 sample snippet:

[assembly: Application(Icon = "@drawable/icon")]

In Visual Studio 2013 and later, the application icon can be set through the Android Manifest section of project Properties, as shown in the following screenshot:

Application Icon setting

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 android:versionCode.

  • 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 android:versionName.

In Visual Studio, these values can be set in the Android Manifest section of project Properties, as shown in the following screenshot:

Version number and name

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:

Linker properties

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:

Packaging properties

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 Compilation

ℹ️

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

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:

ProguardConfiguration build action

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.

Multi-Dex

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.

Compile

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.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.