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.

‍

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”.

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.

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:

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).

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)

‍