Xamarin Bindings Libraries, an Android part (1/3)

Xamarin Bindings Libraries, an Android part (1/3)
December 21, 2021
This article covers the topic of creating and using the so-called Bindings Library for Xamarin or .NET mobile apps in general. The Bindings Library offers .NET developers the possibility to use native libraries written in Objective-C / Swift for iOS or in Java / Kotlin for Android apps. At the end of this article, you’ll find a living example which we’ve created in SABO Mobile IT.

1.    Introduction

Xamarin technology offers great ability for .NET developers to create awesome and fast native applications for smart mobile phones and tablets. Using Xamarin, .NET developers can write code in C# and use BCL (Base Class Library) and other .NET APIs. Xamarin internally binds the mentioned .NET API to Android/Java classes on the Android operating system or iOS APIs on the iOS operating system.

Structure of Xamarin native (Xamarin.Android, Xamarin.iOS) architecture

This way, .NET developers can create their own native apps using all functionality offered by Android/Java libraries or iOS libraries respectively.

In real life however, there is a lot of functionality already coded  by Android/iOS developers. Such functionalities are grouped in so-called third-party libraries. These libraries could be drivers, picture manipulators, device specific APIs, third-party service APIs, etc.

The native third-party libraries can be written in Java or Kotlin for Android and Objective-C or Swift for iOS. This means, unfortunately, that such libraries are incompatible with the C#/.NET environment.

Luckily, the Xamarin team provides a great feature which makes consuming these third-party libraries possible – the so-called Bindings Libraries.

Let's take a look at how to create and use the Bindings Library for Xamarin.Android and Xamarin.iOS.


2.    Android bindings library

When creating a bindings library for Android, just open Visual Studio – Create new project dialog and choose the type “Android Bindings Library”.

Visual studio new project dialog with Android Bindings Library template

After creation, the empty Android Bindings Library project looks like those in picture 3. There are three folders: Additions, Jars, and Transforms.

Under the Additions folder, extra functionality written in C# can be added as common .cs classes.  This is done most often in the form of partial classes extending generated classes by MSBUILD, so the project can be compiled.  The general task is to add here missing methods - implementation of interfaces generated from Java /Kotlin source.

Empty Android Bindings Library

Into the Jars folder, all compiled .jar or files or .aar archives should be placed –the native Java libraries themselves. The library for which you are creating bindings  must have set Build Action in the Properties panel to “LibraryProjectZip”, while additional reference .jarfiles needed by the binded library must have set Build Action to “EmbededReferenceJar” in Visual Studio. This means that the .jar reference is included in the resultant.dll file. More detailed information about Build Actions for the Android Bindings Library project can be found here [4].

The Transformsfolder contains three .xml files used while translating Java code into C#. These transformations are necessary especially when the Android Bindings Library projects fails to build due to C# compilation errors. Depending on the C# andJava versions used to write the original library,  translating may result in compile errors.  If this happens, add transformation customization into the Metadata.xml file.

Transformations are written using the XPATH syntax. XPath uses path expressions to select nodes or node-sets in an XML document. For example:

{% c-block language="xml" %}
<attr path="/api/package[@name='com.namespace.sdk']/class[@name='StackProps']/method[@name='copy' and count(parameter)=2 and parameter[1][@type='boolean'] and parameter[2][@type='com.namespace.sdk.services.TCFStack']]/parameter[@name='checked']" name="name">isChecked</attr>
{% c-block-end %}

Great help with writing custom transformation  can be found directly in generated source code  above every class member:

Sourcecode of Android Bindings Library class transformed from Kotlin to C# using msbuild (while building the project, for all jar/aar packages with build action LibraryProjectZip, mirror c# classes are generated under obj folder)

This row finds the method with two parameters in Java code com.namespace.sdk.StackProps.copy(paramater1,checked) and renames the name of the second parameter from “checked” to “isChecked”. Such transformation is necessary because “checked” is a C# reserved word and cannot be used as the parameter’s name.

When all necessary transformations are written and  the Android Bindings Libraries project has been built, we’ll get a resultant .dllfile of the binded library, which can be referenced in our Xamarin project.


2.1.     Troubleshooting

In real life, problems may arise during design or runtime. Solving problems with transformation and using the library is easier when you can look at decompiled Java source code. I recommend using Java Decompiler utility, which is free for download (see Reference links under this article).

Screenshot of Java Decompiler in action

2.1.1.      Coding problems

When using the binded library, you may encounter  the problem that requested methods or members are missing in the translated library. This is usually caused by missing native references. In picture above, for example, no types from kotlin.* are known for the Java compiler. The library is written in Kotlin instead of Java. To solve the problem with missing types, include Xamarin.Kotlin.StdLib NuGet package into the Android Bindings Library project.

2.1.2.      Runtime problems

When using the library and running the Xamarin app, you may encounter problems in runtime and the app crashes. This is usually caused by missing .jar references which the original .aar package is  using internally and  which are not included in the original .aar file. Then we have to find the missing .jar reference and add it into the Jars folder with Build Action set to EmbededReferenceJar.

Read next: Xamarin Bindings Libraries, an iOS part (2/3)

Luboš is an experienced .NET developer (web and mobile apps) very familiar with SQL and DevOps. He developed a lot of web applications used worldwide by industry and the academical world. He holds a bachelor’s degree in applied physics and astrophysics. Likes bowling, rides e-mountainbike, skis and plays the violin.

Article collaborators

SABO Newsletter icon


Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

About SABO Mobile IT

We focus on developing specialized software for our customers in the automotive, supplier, medical and high-tech industries in Germany and other European countries. We connect systems, data and users and generate added value for our customers with products that are intuitive to use.
Learn more about sabo