Building a Xamarin.Android Application with Visual Studio and Nant

Introduction

This article shows you how to write a Nant script that builds a Xamarin.Android application that has been developed with Visual Studio. There are several key differences that need to be considered when building a Xamarin.Android application using Nant.

Background

This article assumes that you are already familiar with Nant and building applications using MSBUILD. For an example of a simple Nant build script, see the one I have posted on GitHub. I used Nant version 0.92. 

The article focuses on the differences you will need to make to your Nant script when building a Xamarin.Android application. It is therefore assumed that the reader is familiar with writing build scripts using Nant and wants to learn how to write a build script for a Xamarin.Android application that has been developed using Visual Studio.

The Android system requires that all installed applications are digitally signed with a certificate whose private key is held by the application's developer.

There are two build modes: debug mode and release mode. You would use debug mode when you are developing and testing your application. You would use release mode when you want to build a release version of your application such as when distributing it or publishing it on Google Play

It is assumed that the reader has already obtained a suitable private key.

Using the Script

The build script can be run from either the command line, a batch file or CruiseControl.NET (or other integration server). It may be beneficial to add the path to Nant to your PATH environment variable so you don't need to type the full path when you refer to the Nant executable.

Android applications do not get compiled into EXE or DLL files. Instead they get compiled into APK (Android Package) files. The key difference between compiling an application that targets the Windows platform and one that targets the Android platorm is that you will need to additionally sign and align your APK file.

You can perform the tasks of signing and aligning your application using the command-line tools that come with your Java Development Kit (JDK) These tools are jarsigner and zipalign respectively. However, if you are already using MSBUILD, then there is no need to call any external tools as MSBUILD can call them for you.

The Script

There are two MSBUILD targets that are key to building a Xamarin.Android application for Visual Studio.

These are:

• PackageAndroid
• SignAlignAndroid

N.B. The keyword ‘target’ is used by both Nant and MSBUIILD to mean different things and it is important not to get them confused. A target in Nant is a named block of script similar to a module or function. In MSBUILD, a target is a task(s) that is executed sequentially.

The skeleton script below shows three Nant targets. The Release target performs a standard rebuild of your application (having already performed any other build related tasks such as a Debug and / or Clean build. The PackageAndroid and SignAlignAndroid perform the Android specific tasks of creating, signing and aligning your APK file

The Release Nant target builds the application using MSBUILD specifying RELEASE as the MSBUUILD target:

<target name="Release" depends="Build"></target>

The PackageAndroid Nant target builds the application using MSBUUILD specifying PackageAndroid as the MSBUUILD target.

<target name="PackageAndroid" depends="Release"></target>

The SignAlignAndroid Nant target builds the application using MSBUUILD specifying SignAlignAndroid as the MSBUILD target.

<target name="SignAlignAndroid" depends="PackageAndroid"></target>

Let's take a closer look at these Nant targets. Hopefully the properties build.dir, project.dir and project.name are all self explanatory.

PackageAndroid

This creates your APK file but importantly does NOT sign it. This is useful when you simply want to compile your application for non distribution.

  <target name="PackageAndroid" depends="Release">
  <!-- Package the Android APK file -->
  <echo message="Task execution started at : ${script::format-to-string(datetime::now())}" />

  <!-- Actually package the APK file -->
  <property name="build.item" value="${build.dir}\${project.dir}\${project.name}" />
  <property name="config.type"        value="Release" />
  <property name="target"               value="PackageForAndroid" />
  <msbuild project="${build.item}" target="${target}"  verbose="${verbose}" failonerror="true">
    <property name="Configuration" value="${config.type}" verbose="${verbose}" />
  </msbuild>
  <echo message="Task execution finished at : ${script::format-to-string(datetime::now())}" />
</target>

SignAlignAndroid

This creates your APK file and additionally signs it.

<target name="SignAlignAndroid" depends="PackageAndroid">
  <!-- Sign the Android APK file -->
  <echo message="Task execution started at : ${script::format-to-string(datetime::now())}" />

  <!-- Actually sign the APK file -->
  <property name="build.item" value="${build.dir}\${project.dir}\${project.name}" />
  <property name="config.type"        value="Release" />
  <property name="target"               value="SignAndroidPackage" />
  <msbuild project="${build.item}" target="${target}" verbose="${verbose}" failonerror="true">
    <property name="Configuration" value="${config.type}" verbose="${verbose}" />
  </msbuild>

  <echo message="Task execution finished at : ${script::format-to-string(datetime::now())}" />
</target>

When building your Xamarin.Android application, by default the build process will use a temporary private key located in your user profile. This is fine if you are testing your application locally on your development machine. If you want to distribute your application to your testing team or for production use, you will need to sign your application with your actual private key. You can specifiy these by adding them to your .CSPROJ file. See the example below. Add these elements for each target platform.

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <AndroidKeyStore>True</AndroidKeyStore>
    <AndroidSigningKeyStore>\\mykeystorefolder\keystore.file</AndroidSigningKeyStore>
    <AndroidSigningStorePass>password</AndroidSigningStorePass>
    <AndroidSigningKeyAlias>alias</AndroidSigningKeyAlias>
    <AndroidSigningKeyPass>password</AndroidSigningKeyPass>
</PropertyGroup>

I have posted the entire build script on GitHub so feel free to have a look.