Xamarin android binding library

Creating a Xamarin Android binding library — Writing the binding

Creating a Xamarin Android binding library is not an easy task and is different for every native library. This article is the second of a series of 4 articles and shows the actual binding process.

John Thiriet

Enthusiast developer, former Microsoft MVP and Xamarin MVP, language nerd.

Introduction

This article is the second of a series of 4 articles:

1. Preparation
2. Writing the binding
3. Testing the binding
4. Publishing the binding as a NuGet package

In the previous article, we have seen what we need to prepare ourselves to bind a library.

Now, I will explain some key concepts and then showcase the common errors you might encounter.

For this article, I also suppose you have some basic knowledge of the binding process as written in the official documentation.

The purpose of this article is not replacing any online documentation (links at the end) but more how to deal with common errors.

Structure

A Xamarin Android binding project is structured in the following way:

• Additions
  • Additions.cs
• Jars
  • Your Jar or Aar file
• Properties
• Transforms
  • EnumFields.xml
  • EnumMethods.xml
  • Metadata.xml

Beside the actual library you are trying to bind, the most important file is the Metadata.xml file.

This is were most of the magic happens. Most of the time, you will not touch the other files. That is why it is going to be my focus here.

Dependencies

I suppose that you know about the dependencies needed for your library, if not, please read the preparation part of this series.

You have basically three ways to handle native dependencies in a binding project:

• Include them
• Reference them
• Reference a NuGet package containing a binding on them

For the first two, I invite you to read the official documentation about binding a jar and binding an aar.

The last one is more useful for big libraries like the AndroidX libraries, the Huawei Mobile Services or any library with a dependency on an existing one.

For example, if the library you need to bind has a reference to OkHttp, it’s not useful to create the binding for OkHttp as it already exists. Just reference the NuGet in your binding project and you are covered.

Compilation

We now have an empty project and have added the jar or aar file we need to bind.

We compile the project then we can have compilation errors and warnings.

The little game of binding creation will be to loop between 1 and 6 until we finally reach step 7 🙂

Fixing compilation errors

Errors are usually a good sign. This is what I expect when I do the first compilation. They mostly indicate that the compiler needs some help to generate the binding.

What you will read next is the process I apply to solve those binding errors. As stated in the previous article, this series does not aim to provide a solution to every problem but show you how I deal with them.

The most usual one is naming conflicts. They often occur because some member methods or classes have the same name as their parent class. Fixing those errors are pretty straightforward as you need to either rename the class or the method.

Here are a few exemples of naming conflicts:

Fun fact: Most of the errors come from the fact that C# does not allow some of the things Java is fine with 🙂

Looking for the culprit

Double-clicking on the error in Visual Studio will redirect you to the generated code where you can see some comments:

As you can see, the comment gives you a java type name. That might prove to be useful.

Scrolling up you might notice comments starting with Metadata.xml :

Those comments give the correct syntax to add into the Metadata.xml file to reference classes or methods. You can be as precise as referencing a specific parameter as well.

In the Metadata.xml file, I want to reference the OnError method of the ISomeListener interface.

I will therefore copy the path defined in the comment into an attr attribute:

Basically, we are using an XPath syntax to query our native library and apply some modifications on them.

If there is only one overload of a method, specifying the parameters arguments is not necessary:

Renaming

If I want to rename the interface I can use the managedName operator:

This operator works on every element so you can apply it on namespaces, classes, interfaces or methods.

Event args

Sometimes, event args conversion fails because of naming conflicts too.

In that case, I use the argsType operator to change the parameter’s type.

There are many operators available which you can have a list in the famous Gist from Jon Douglas referenced links.

Most of the time, fixing those naming issues will make your binding compilation pass. But it does not mean it is over yet!

I now need to look at the generated binding. If it compiles, it is testable!

The testing phase will be described in details in the next article of this series.

At that step of the process, I go to the C# sample project to check for any missing methods or types. I look at my Java sample and try to find the types and methods I need with Intellisense in my C# project. I find the process much faster that way.

If no classes or methods are missing then perfect, I go straight to the cleanup phase. But if I have some missing elements, I need to find why.

To help me with the investigation here are the questions I try to find answers for:

1. If a class is missing, does this type inherits from or implements another type that is also missing?
2. If a method is missing, does it have a parameter whose type is also missing?
3. Does the Java code reference some Java generic types?
4. Is the type obfuscated?

Repeat those questions for every type helps to have a clear view of what needs fixing.

Now that I know what is missing for my sample, I can work on fixing the binding.

Managing warnings

Warnings in Xamarin Android projects are important as they indicate something went wrong but not wrong enough to prevent the compilation.

Usually, I try to fix most of them starting with the infamous:

Invalidating means that a big bunch of classes and method have been removed. Therefore I always treat those warnings as errors to fix my issues.

Chances are, that if we fix those errors, we will get back some of the missing members needed.

So how can we fix them?

That depends on the error hence we need to understand very well the native library.

Obfuscation

My experience shows that most of the time when dependencies are referenced correctly, obfuscation is a probable culprit.

Writing this kind of code is no fun. Hopefully, we only need to fix the types causing the issues.

Also, if the library is obfuscated in a somewhat predictable way, it is possible to write scripts to generate those obfuscation elements.

For those interested here is a dummy PowerShell sample I made. Please note that it requires the jd-cli command-line tool.

Missing members

Sometimes, even if we have all the references needed, some methods or classes might fail to be generated.

The first thing I do is check the api.xml file to verify that the class or method I need is there.

You can find the api.xml in your project build folder: obj/debug/api.xml . It basically shows what the binding process will expose.

In case it is not, I manually add what is missing to the Metadata.xml :

Of course, we need to know what to write there. To help, I usually look at similar methods or classes in the api.xml and write the same thing in Metadata.xml . As for the path attribute you can copy it from JD-GUI .

Removing members

Sometimes, some members are generated but not useful to C# and even might create issues.

In those cases I remove them:

Property fixing

In the Huawei binding, I encounter some properties that were generated because a method was called getSomething but was not a getter.

To fix that, I instructed the binding to not generate a property and keep the method by setting its name to empty:

Polishing

We now have all the necessary types and methods. That does not mean the work is over yet.

Usually, I try to clean up a bit the bindings at this step.

Of course, the cleanup process is important when I do a public binding. For private ones, I can accept some rough edges to save time.

I like renaming namespaces that do not feel like .NET at all:

This is what I used in the Huawei binding since I would rather not have Com.Something in C#.

I can also rename some parameters if I find them necessary yet usually I stop there with renaming.

Finally, for types that are Java tasks or callbacks, I like to add some code in the Additions.cs .

Adding code in this file will make it available to every consumer of the library easing code sharing.

Wrapping up

By following all these steps, I have working binding.

Of course, the process is not linear so I go back and forth from fixing errors to warnings and so on.

I find this important to apply those steps and it helped me a lot in writing those bindings.

So hopefully that will help you too!

If you want a good example of what I highly I recommend that you go and check my Huawei mobile services binding and the associated article.

In the next article, I will describe how I do to test the bindings I work on.

Keep posted and as always, feel free to read my previous posts and to comment below, I will be more than happy to answer.

References

1. The official documentation on bindings metadata.
2. The official documentation on binding a jar
3. The official documentation on binding an aar
4. The official documentation on troubleshooting bindings.
5. The excellent Jon Douglas gist.

Comments

You May Also Enjoy

Creating a Xamarin Android binding library — Preparation

Creating a Xamarin Android binding library is not an easy task and is different for every native library. This article is the first of a series of 4 articles.

Using Huawei Mobile Services with Xamarin

Huawei provides a set of tools to work on Android phones that do not use Google Play Services. In this post we will see how we can use them in a Xamarin Andr.

Crashes and errors analytics with App Center and Application Insights

Exporting analytics with App Center to Application Insights is pretty straightforward. Errors and crashes are not exposed directly though. Fortunately, there.

Supercharging your mobile analytics with App Center and Application Insights

I have always found App Center to be quite limited in terms of analytics. Little did I know that it is just the entry point for a powerful mobile analytics p.

Источник

Binding an .AAR

We’re currently investigating custom binding usage on the Xamarin platform. Please take this survey to inform future development efforts.

This walkthrough provides step-by-step instructions for creating a Xamarin.Android Java Bindings Library from an Android .AAR file.

Overview

The Android Archive (.AAR) file is the file format for Android libraries. An .AAR file is a .ZIP archive that contains the following:

• Compiled Java code
• Resource IDs
• Resources
• Meta-data (for example, Activity declarations, permissions)

In this guide, we’ll step through the basics of creating a Bindings Library for a single .AAR file. For an overview of Java library binding in general (with a basic code example), see Binding a Java Library.

A binding project can only include one .AAR file. If the .AAR depends on other .AAR, then those dependencies should be contained in their own binding project and then referenced. See Bug 44573.

Walkthrough

We’ll create a Bindings Library for an example Android archive file that was created in Android Studio, textanalyzer.aar. This .AAR contains a TextCounter class with static methods that count the number of vowels and consonants in a string. In addition, textanalyzer.aar contains an image resource to help display the counting results.

We’ll use the following steps to create a Bindings Library from the .AAR file:

Create a new Java Bindings Library project.

Add a single .AAR file to the project. A binding project may only contain a single .AAR.

Set the appropriate build action for the .AAR file.

Choose a target framework that the .AAR supports.

Build the Bindings Library.

Once we’ve created the Bindings Library, we’ll develop a small Android app that prompts the user for a text string, calls .AAR methods to analyze the text, retrieves the image from the .AAR, and displays the results along with the image.

The sample app will access the TextCounter class of textanalyzer.aar:

In addition, this sample app will retrieve and display an image resource that is packaged in textanalyzer.aar:

This image resource resides at res/drawable/monkey.png in textanalyzer.aar.

Creating the Bindings Library

Before commencing with the steps below, please download the example textanalyzer.aar Android archive file:

Create a new Bindings Library project starting with the Android Bindings Library template. You can use either Visual Studio for Mac or Visual Studio (the screenshots below show Visual Studio, but Visual Studio for Mac is very similar). Name the solution AarBinding:

The template includes a Jars folder where you add your .AAR(s) to the Bindings Library project. Right-click the Jars folder and select Add > Existing Item:

Navigate to the textanalyzer.aar file downloaded earlier, select it, and click Add:

Verify that the textanalyzer.aar file was successfully added to the project:

Set the Build Action for textanalyzer.aar to LibraryProjectZip . In Visual Studio for Mac, right-click textanalyzer.aar to set the Build Action. In Visual Studio, the Build Action can be set in the Properties pane):

Open the project Properties to configure the Target Framework. If the .AAR uses any Android APIs, set the Target Framework to the API level that the .AAR expects. (For more information about the Target Framework setting and Android API levels in general, see Understanding Android API Levels.)

Set the target API level for your Bindings Library. In this example, we are free to use the latest platform API level (API level 23) because our textanalyzer does not have a dependency on Android APIs:

Build the Bindings Library. The Bindings Library project should build successfully and produce an output .DLL at the following location: AarBinding/bin/Debug/AarBinding.dll

Using the Bindings Library

To consume this .DLL in your Xamarin.Android app, you must first add a reference to the Bindings Library. Use the following steps:

We’re creating this app in the same Solution as the Bindings Library to simplify this walkthrough. (The app that consumes the Bindings Library could also reside in a different Solution.) Create a new Xamarin.Android app: right-click the Solution and select Add New Project. Name the new project BindingTest:

Right-click the References node of the BindingTest project and select Add Reference. :

Select the AarBinding project created earlier and click OK:

Open the References node of the BindingTest project to verify that the AarBinding reference is present:

If you would like to view the contents of the Binding Library project, you can double-click the reference to open it in the Object Browser. You can see the mapped contents of the Com.Xamarin.Textcounter namespace (mapped from the Java com.xamarin.textanalyzezr package) and you can view the members of the TextCounter class:

The above screenshot highlights the two TextAnalyzer methods that the example app will call: NumConsonants (which wraps the underlying Java numConsonants method), and NumVowels (which wraps the underlying Java numVowels method).

Accessing .AAR Types

After you add a reference to your app that points to the Binding Library, you can access Java types in the .AAR as you would access C# types (thanks to the C# wrappers). C# app code can call TextAnalyzer methods as illustrated in this example:

In the above example, we’re calling static methods in the TextCounter class. However, you can also instantiate classes and call instance methods. For example, if your .AAR wraps a class called Employee that has the instance method buildFullName , you can instantiate MyClass and use it as seen here:

The following steps add code to the app so that it prompts the user for text, uses TextCounter to analyze the text, and then displays the results.

Replace the BindingTest layout (Main.axml) with the following XML. This layout has an EditText for text input and two buttons for initiating vowel and consonant counts:

Replace the contents of MainActivity.cs with the following code. As seen in this example, the button event handlers call wrapped TextCounter methods that reside in the .AAR and use toasts to display the results. Notice the using statement for the namespace of the bound library (in this case, Com.Xamarin.Textcounter ):

Compile and run the BindingTest project. The app will start and present the screenshot on the left (the EditText is initialized with some text, but you can tap it to change it). When you tap COUNT VOWELS, a toast displays the number of vowels as shown on the right:

Try tapping the COUNT CONSONANTS button. Also, you can modify the line of text and tap these buttons again to test for different vowel and consonant counts.

Accessing .AAR Resources

The Xamarin tooling merges the R data from the .AAR into your app’s Resource class. As a result, you can access .AAR resources from your layout (and from code-behind) in the same way as you would access resources that are in the Resources path of your project.

To access an image resource, you use the Resource.Drawable name for the image packed inside the .AAR. For example, you can reference image.png in the .AAR file by using @drawable/image :

You can also access resource layouts that reside in the .AAR. To do this, you use the Resource.Layout name for the layout packaged inside the .AAR. For example:

The textanalyzer.aar example contains an image file that resides at res/drawable/monkey.png. Let’s access this image resource and use it in our example app:

Edit the BindingTest layout (Main.axml) and add an ImageView to the end of the LinearLayout container. This ImageView displays the image found at @drawable/monkey; this image will be loaded from the resource section of textanalyzer.aar:

Compile and run the BindingTest project. The app will start and present the screenshot on the left – when you tap COUNT CONSONANTS, the results are displayed as shown on the right:

Congratulations! You’ve successfully bound a Java library .AAR!

Summary

In this walkthrough, we created a Bindings Library for an .AAR file, added the Bindings Library to a minimal test app, and ran the app to verify that our C# code can call Java code residing in the .AAR file. In addition, we extended the app to access and display an image resource that resides in the .AAR file.

Источник