绑定 .JARBinding a .JAR

本演练提供了从 Android 创建 Xamarin.Android Java 绑定库的分步说明。JAR 文件。This walkthrough provides step-by-step instructions for creating a Xamarin.Android Java Bindings Library from an Android .JAR file.

概述Overview

Android 社区还提供了许多可能想要使用应用程序中的 Java 库。The Android community offers many Java libraries that you may want to use in your app. 采用通常封装这些 Java 库。JAR (Java 存档文件) 格式,但您可以将打包。它在 JAR Java 绑定库,以便其功能是适用于 Xamarin.Android 应用。These Java libraries are often packaged in .JAR (Java Archive) format, but you can package a .JAR it in a Java Bindings Library so that its functionality is available to Xamarin.Android apps. Java 绑定库的目的是使中的 Api。JAR 文件提供给C#代码中通过自动生成的代码包装器。The purpose of the Java Bindings library is to make the APIs in the .JAR file available to C# code through automatically-generated code wrappers.

Xamarin 工具可以生成绑定库从一个或多个输入。JAR 文件。Xamarin tooling can generate a Bindings Library from one or more input .JAR files. 绑定库 (。DLL 程序集) 包含以下元素:The Bindings Library (.DLL assembly) contains the following:

  • 原始内容。JAR 文件。The contents of the original .JAR file(s).

  • 托管可调用包装 (MCW),这是C#类型对应的 Java 类型中的自动换行。JAR 文件。Managed Callable Wrappers (MCW), which are C# types that wrap corresponding Java types within the .JAR file(s).

生成的 MCW 代码使用 JNI (Java 本机接口) 将 API 调用转发到基础。JAR 文件。The generated MCW code uses JNI (Java Native Interface) to forward your API calls to the underlying .JAR file. 可以为任何创建绑定库。最初针对与 Android (请注意 Xamarin 工具中当前不支持非 Android Java 库的绑定) 一起使用的 JAR 文件。You can create bindings libraries for any .JAR file that was originally targeted to be used with Android (note that Xamarin tooling does not currently support the binding of non-Android Java libraries). 您还可以选择用于生成绑定库而不包括的内容。JAR 文件,以便在 DLL 具有依赖项。JAR 在运行时。You can also elect to build the Bindings Library without including the contents of the .JAR file so that the DLL has a dependency on the .JAR at runtime.

在本指南中,我们将逐步完成创建一个绑定库的基础知识。JAR 文件。In this guide, we'll step through the basics of creating a Bindings Library for a single .JAR file. 我们将所有内容会直接的示例演示了–,即没有自定义或绑定的调试需要的。We'll illustrate with an example where everything goes right – that is, where no customization or debugging of bindings is required. 创建绑定使用元数据提供了绑定进程不是完全自动和一定量的手动干预是必需的更高级方案的示例。Creating Bindings Using Metadata offers an example of a more advanced scenario where the binding process is not entirely automatic and some amount of manual intervention is required. Java 库绑定,一般情况下 (其中一个基本代码示例) 的概述,请参阅绑定 Java 库For an overview of Java library binding in general (with a basic code example), see Binding a Java Library.

演练Walkthrough

在下面的演练中,我们将创建一个绑定库,用于看毕加索会如何,流行的 Android。提供了映像加载和缓存功能的 JAR。In the following walkthrough, we'll create a Bindings Library for Picasso, a popular Android .JAR that provides image loading and caching functionality. 我们将使用以下步骤来绑定看毕加索会如何 2.x.x.jar Xamarin.Android 项目中创建新的.NET 程序集,我们可以使用:We will use the following steps to bind picasso-2.x.x.jar to create a new .NET assembly that we can use in a Xamarin.Android project:

  1. 创建新的 Java 绑定库项目。Create a new Java Bindings Library project.

  2. 添加。JAR 文件复制到项目。Add the .JAR file to the project.

  3. 设置为相应的生成操作。JAR 文件。Set the appropriate build action for the .JAR file.

  4. 选择目标框架。支持 JAR。Choose a target framework that the .JAR supports.

  5. 生成绑定库。Build the Bindings Library.

一旦我们创建绑定库,我们将开发一个小型的 Android 应用程序演示我们调用绑定库中的 Api 的能力。Once we've created the Bindings Library, we'll develop a small Android app that demonstrates our ability to call APIs in the Bindings Library. 在此示例中,我们想要访问的方法看毕加索会如何 2.x.x.jar:In this example, we want to access methods of picasso-2.x.x.jar:

package com.squareup.picasso

public class Picasso
{ 
    ...
    public static Picasso with (Context context) { ... };
    ...
    public RequestCreator load (String path) { ... };
    ...
}

我们生成一个绑定库,用于以后看毕加索会如何 2.x.x.jar,我们可以调用这些方法从C#。After we generate a Bindings Library for picasso-2.x.x.jar, we can call these methods from C#. 例如:For example:

using Com.Squareup.Picasso;
...
Picasso.With (this)
    .Load ("http://mydomain.myimage.jpg")
    .Into (imageView);

创建绑定库Creating the Bindings Library

在开始执行以下步骤之前, 请下载看毕加索会如何 2.x.x.jarBefore commencing with the steps below, please download picasso-2.x.x.jar.

首先,创建一个新的绑定库项目。First, create a new Bindings Library project. 在 Visual Studio for Mac 或 Visual Studio 中,创建一个新的解决方案并选择Android 绑定库模板。In Visual Studio for Mac or Visual Studio, create a new Solution and select the Android Bindings Library template. (在本演练中的屏幕截图使用 Visual Studio 中,但 Visual Studio for Mac 是非常相似。)将解决方案命名JarBinding:(The screenshots in this walkthrough use Visual Studio, but Visual Studio for Mac is very similar.) Name the Solution JarBinding:

创建 JarBinding 库项目Create JarBinding library project

该模板包含Jar文件夹在其中添加你。JAR(s) 到绑定库项目。The template includes a Jars folder where you add your .JAR(s) to the Bindings Library project. 右键单击Jar文件夹,然后选择添加 > 现有项:Right-click the Jars folder and select Add > Existing Item:

添加现有项Add existing item

导航到看毕加索会如何 2.x.x.jar前面下载的文件,选择它并单击添加:Navigate to the picasso-2.x.x.jar file downloaded earlier, select it and click Add:

选择 jar 文件,然后单击添加Select jar file and click Add

确认看毕加索会如何 2.x.x.jar文件已成功添加到项目:Verify that the picasso-2.x.x.jar file was successfully added to the project:

Jar 添加到项目Jar added to project

创建 Java 绑定库项目时,必须指定是否。JAR 是嵌入到绑定库中或单独打包。When you create a Java Bindings library project, you must specify whether the .JAR is to be embedded in the Bindings Library or packaged separately. 若要执行此操作,您指定以下值之一生成操作:To do that, you specify one of the following build actions:

  • EmbeddedJar – 。绑定库中,将嵌入 JAR。EmbeddedJar – the .JAR will be embedded in the Bindings Library.

  • InputJar – 。将独立于绑定库保留 JAR。InputJar – the .JAR will be kept separate from the Bindings Library.

通常情况下,使用EmbeddedJar生成操作,以便。JAR 自动打包到绑定库中。Typically, you use the EmbeddedJar build action so that the .JAR is automatically packaged into the bindings library. 这是最简单的选项–中的 Java 字节码。JAR 转换为 Dex 字节码,以及 (以及托管的可调用包装) 嵌入到 APK。This is the simplest option – Java bytecode in the .JAR is converted into Dex bytecode and is embedded (along with the Managed Callable Wrappers) into your APK. 如果你想要保留。JAR 独立于绑定库,则可以使用InputJar选项; 但是,您必须确保。JAR 文件位于运行您的应用程序的设备上。If you want to keep the .JAR separate from the bindings library, you can use the InputJar option; however, you must ensure that the .JAR file is available on the device that runs your app.

生成操作设置为EmbeddedJar:Set the build action to EmbeddedJar:

选择 EmbeddedJar 生成操作Select EmbeddedJar build action

接下来,打开项目属性来配置目标框架Next, open the project Properties to configure the Target Framework. 如果。JAR 使用任何 Android Api,将目标框架设置为 API 级别。需要 JAR。If the .JAR uses any Android APIs, set the Target Framework to the API level that the .JAR expects. 通常情况下,开发人员的。JAR 文件将指示哪个 API 级别 (或级别) 的。与兼容 JAR。Typically, the developer of the .JAR file will indicate which API level (or levels) that the .JAR is compatible with. (有关目标框架设置和在常规的 Android API 级别的详细信息,请参阅了解 Android API 级别。)(For more information about the Target Framework setting and Android API levels in general, see Understanding Android API Levels.)

设置目标 API 级别绑定库 (在此示例中,我们将使用 API 级别 19):Set the target API level for your Bindings Library (in this example, we are using API level 19):

目标 API 级别设置为 API 19Target API level set to API 19

最后,生成绑定库。Finally, build the Bindings Library. 尽管可能会显示某些警告消息,但绑定库项目应能成功生成,并生成输出。在以下位置的 DLL:JarBinding/bin/Debug/JarBinding.dllAlthough some warning messages may be displayed, the Bindings Library project should build successfully and produce an output .DLL at the following location: JarBinding/bin/Debug/JarBinding.dll

使用绑定库Using the Bindings Library

若要使用这个。DLL 在 Xamarin.Android 应用中,执行以下步骤:To consume this .DLL in your Xamarin.Android app, do the following:

  1. 添加到绑定库的引用。Add a reference to the Bindings Library.

  2. 对进行调用。JAR 通过托管的可调用包装器。Make calls into the .JAR through the Managed Callable Wrappers.

在以下步骤中,我们将创建一个使用绑定库下载并显示的图像的最小应用ImageView;"繁重的工作",可以驻留在的代码。JAR 文件。In the following steps, we'll create a minimal app that uses the Bindings Library to download and display an image in an ImageView; the "heavy lifting" is done by the code that resides in the .JAR file.

首先,创建使用绑定库的新 Xamarin.Android 应用程序。First, create a new Xamarin.Android app that consumes the Bindings Library. 右键单击解决方案并选择添加新项目; 将新项目命名BindingTestRight-click the Solution and select Add New Project; name the new project BindingTest. 我们要在与绑定库相同的解决方案中创建此应用程序,为了简化本演练中;但是,使用绑定库应用程序,而是驻留在另一种解决方案:We're creating this app in the same Solution as the Bindings Library in order to simplify this walkthrough; however, the app that consumes the Bindings Library could, instead, reside in a different Solution:

添加新 BindingTest 项目Add new BindingTest project

右键单击引用的节点BindingTest项目,然后选择添加引用...:Right-click the References node of the BindingTest project and select Add Reference...:

直接添加引用Right Add Reference

检查JarBinding前面创建的项目并单击确定:Check the JarBinding project created earlier and click OK:

选择 JarBinding 项目Select JarBinding project

打开引用的节点BindingTest项目,然后确认JarBinding引用不存在:Open the References node of the BindingTest project and verify that the JarBinding reference is present:

在引用下显示 JarBindingJarBinding appears under References

修改BindingTest布局 (Main.axml),以便它具有单个ImageView:Modify the BindingTest layout (Main.axml) so that it has a single ImageView:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:minWidth="25px"
    android:minHeight="25px">
    <ImageView
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:id="@+id/imageView" />
</LinearLayout>

添加以下using语句MainActivity.cs –这样就可以轻松地访问的方法的基于 Java 的Picasso驻留在绑定库中的类:Add the following using statement to MainActivity.cs – this makes it possible to easily access the methods of the Java-based Picasso class that resides in the Bindings Library:

using Com.Squareup.Picasso;

修改OnCreate方法,以便使用Picasso类来从 URL 加载图像并将其显示在ImageView:Modify the OnCreate method so that it uses the Picasso class to load an image from a URL and display it in the ImageView:

public class MainActivity : Activity
{
    protected override void OnCreate(Bundle bundle)
    {
        base.OnCreate(bundle);
        SetContentView(Resource.Layout.Main);
        ImageView imageView = FindViewById<ImageView>(Resource.Id.imageView);

        // Use the Picasso jar library to load and display this image:
        Picasso.With (this)
            .Load ("http://i.imgur.com/DvpvklR.jpg")
            .Into (imageView);
    }
}

编译并运行BindingTest项目。Compile and run the BindingTest project. 应用程序将启动,并后一个短暂的延迟 (具体取决于网络条件),它应下载并显示类似于以下屏幕截图的映像:The app will startup, and after a short delay (depending on network conditions), it should download and display an image similar to the following screenshot:

屏幕截图的 BindingTest 运行Screenshot of BindingTest running

祝贺你!Congratulations! 您已成功绑定 Java 库。JAR 并将 Xamarin.Android 应用中使用。You've successfully bound a Java library .JAR and used it in your Xamarin.Android app.

总结Summary

在本演练中,我们将创建第三方绑定库。JAR 文件,添加到最小化测试应用,绑定库,然后运行应用程序以验证我们C#代码可以调用 Java 代码驻留在中。JAR 文件。In this walkthrough, we created a Bindings Library for a third-party .JAR file, added the Bindings Library to a minimal test app, and then ran the app to verify that our C# code can call Java code residing in the .JAR file.