Binding a Java Library

Consuming Java libraries from C#

PDF for offline use:
Related Articles:

Let us know how you feel about this.

Thanks for the feedback!

The Android community has many Java libraries that you may want to use in your app; this guide explains how to incorporate Java libraries into your Xamarin.Android application by creating a Bindings Library.


The third-party library ecosystem for Android is massive. Because of this, it frequently makes more sense to use an existing library than to create a new one. Xamarin.Android offers two ways to use these libraries:

  • Create a Bindings Library that automatically wraps the library with C# wrappers so you can invoke Java code via C# calls.

  • Use the Java Native Interface (JNI) to invoke calls in Java library code directly.

This guide explains the first option: how to create a Bindings Library that wraps one or more existing Java libraries into an assembly that you can link to in your application. For more information about using JNI, see Working with JNI.

Xamarin.Android implements bindings by using Managed Callable Wrappers (MCW). MCW is a JNI bridge that is used when managed code needs to invoke Java code. Managed callable wrappers also provide support for subclassing Java types and for overriding virtual methods on Java types. Likewise, whenever Android runtime (ART) code wishes to invoke managed code, it does so via another JNI bridge known as Android Callable Wrappers (ACW). This architecture is illustrated in the following diagram:

A Bindings Library is an assembly containing Managed Callable Wrappers for Java types. For example, here is a Java type, MyClass, that we want to wrap in a Bindings Library:

package com.xamarin.mycode;

public class MyClass
    public String myMethod (int i) { ... }

After we generate a Bindings Library for the .JAR that contains MyClass, we can instantiate it and call methods on it from C#:

var instance = new MyClass ();

string result = instance.MyMethod (42);

To create this Bindings Library, you use the Xamarin.Android Java Bindings Library template. The resulting binding project creates a .NET assembly with the MCW classes, .JAR file(s), and resources for Android Library projects embedded in it. You can also create Bindings Libraries for Android Archive (.AAR) files and Eclipse Android Library projects. By referencing the resulting Bindings Library DLL assembly, you can reuse an existing Java library in your Xamarin.Android project.

When you reference types in your Binding Library, you must use the namespace of your binding library. Typically, you add a using directive at the top of your C# source files that is the .NET namespace version of the Java package name. For example, if the Java package name for your bound .JAR is the following:

Then you would put the following using statement at the top of your C# source files in order to access types in the bound .JAR file:

using Com.Company.Package;

Build Actions

When you create a Bindings Library, you set build actions on the .JAR or .AAR files that you incorporate into your Bindings Library project – each build action determines how the .JAR or .AAR file will be embedded into (or referenced by) your Bindings Library. The following table summarizes these build actions:

Build Action Description Recommended Use
EmbeddedJar Embeds the .JAR into the resulting Bindings Library DLL as an embedded resource. This is the simplest and most commonly-used build action. Use this option when you want the .JAR automatically compiled into byte code and packaged into the Bindings Library.
InputJar Does not embed the .JAR into the resulting Bindings Library .DLL. Your Bindings Library .DLL will have a dependency on this .JAR at runtime. Use this option when you do not want to include the .JAR in your Bindings Library (for example, for licensing reasons). If you use this option, you must ensure that the input .JAR is available on the device that runs your app.
LibraryProjectZip Embeds an .AAR file into the resulting Bindings Library .DLL. This is similar to EmbeddedJar, except that you can access resources (as well as code) in the bound .AAR file. Use this option when you want to embed an .AAR into your Bindings Library.
ReferenceJar Specifies a reference .JAR: a reference .JAR is a .JAR that one of your bound .JAR or .AAR files depends on. This reference .JAR is used only to satisfy compile-time dependencies. When you use this build action, C# bindings are not created for the reference .JAR and it is not embedded in the resulting Bindings Library .DLL. Use this option when you will make a Bindings Library for the reference .JAR but have not done so yet. This build action is useful for packaging multiple .JARs (and/or .AARs) into multiple interdependent Bindings Libraries.
EmbeddedReferenceJar Embeds a reference .JAR into the resulting Bindings Library .DLL. Use this build action when you want to create C# bindings for both the input .JAR (or .AAR) and all of its reference .JAR(s) in your Bindings Library.

These build actions are explained in more detail in the following guides.

Binding Scenarios

The following binding scenario guides can help you bind a Java library (or libraries) for incorporation into your app:

Xamarin.Android automates much of the binding process; however, in some cases manual modification is required to handle situations where Xamarin.Android maps the Android API to different types in C#. For example, Java int constants are sometimes mapped to C# enums. The following sections provide guidance on these manual steps:

  • Java Bindings Metadata provides an overview of the metadata that goes into a Java binding. It describes the various manual steps that are sometimes required to complete a Java binding library, and it explains how to shape an API exposed by a binding to more closely follow .NET design guidelines.

  • Creating Bindings Using Metadata explains how to bind a Java library and modify bindings metadata to create the final binding. This approach is often necessary when the automatic binding process cannot resolve build errors or if you want to customize the binding to tailor how data types are mapped.

  • Naming Parameters with Javadoc explains how to recover parameter names in a Java Binding Project by using Javadoc produced from the bound Java project.

  • Troubleshooting Bindings lists common binding error scenarios, explains possible causes, and offers suggestions for resolving these errors.