绑定 .JAR

项目
04/11/2018

重要

我们当前正在调查 Xamarin 平台上的自定义绑定使用情况。请参与此调查，告诉我们将来应该进行哪些开发工作。

本演练将提供从 Android .JAR 文件创建 Xamarin.Android Java 绑定库的分步说明。

概述

Android 社区提供很多你可能需要在应用中使用的 Java 库。这些 Java 库通常以 .JAR（Java 存档）格式打包，但你可以将 .JAR 打包到 Java 绑定库，使 Xamarin.Android 应用可以使用其功能。 Java 绑定库用于通过自动生成的代码包装器为 C# 代码提供 .JAR 文件中的 API。

Xamarin 工具可以从一个或多个输入 .JAR 文件生成绑定库。绑定库（.DLL 程序集）包含以下内容：

初始 .JAR 文件的内容。
托管的可调用包装器 (MCW)，该包装器为 C# 类型，可采用 .JAR 文件包装相应的 Java 类型。

生成的 MCW 代码使用 JNI（Java 本机接口）将 API 调用转发到基础 .JAR 文件。可以为最初用于 Android 的任何 .JAR 文件创建绑定库（请注意，Xamarin 工具当前不支持非 Android Java 库的绑定）。你还可以选择生成绑定库，且不包含 .JAR 文件的内容，使 DLL 在运行时对 .JAR 具有依赖项。

本指南将逐步介绍为单个 .JAR 文件创建绑定库的基础知识。我们将通过一个现成可用（即不需要自定义或调试绑定）的示例进行说明。使用元数据创建绑定举例说明了一种更高级的场景：绑定流程并不完全自动，需要一定的手动干预。有关 Java 库绑定的常规概述（包含基本代码示例），请参阅绑定 Java 库。

演练

在以下演练中，我们将为 Picasso（一种提供图像加载和缓存功能的常用 Android .JAR）创建绑定库。我们将按以下步骤绑定 picasso-2.x.x.jar，新建可在 Xamarin Android 项目中使用的 .NET 程序集：

创建一个新的 Java 绑定库项目。
向项目添加 .JAR 文件。
为 .JAR 文件设置适当的生成操作。
选择 .JAR 支持的目标框架。
生成绑定库。

创建绑定库后，我们将开发一个小型 Android 应用，用于展示在绑定库中调用 API 的能力。在此示例中，我们想要访问 picasso-2.x.x.jar 的方法：

package com.squareup.picasso

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

生成 picasso-2.x.x.jar 的绑定库后，可以从 C# 调用这些方法。例如：

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

创建绑定库

开始执行以下步骤之前，请下载 picasso-2.x.x.jar。

首先，新建绑定库项目。在 Visual Studio for Mac 或 Visual Studio 中，新建解决方案并选择 Android 绑定库模板。（本演练中的屏幕截图使用的是 Visual Studio，但 Visual Studio for Mac 非常类似。）将该解决方案命名为 JarBinding：

该模板包括一个 Jars 文件夹，可以在其中将 .JAR 添加到绑定库项目中。右键单击 Jars 文件夹，并选择“添加”>“现有项”：

导航到之前下载的 picasso-2.x.x.jar 文件，选中它，然后单击“添加”：

验证 picasso-2.x.x.jar 文件是否已成功添加到项目中：

创建 Java 绑定库项目时，必须指定是将 JAR 嵌入绑定库中还是单独打包。为此，请指定以下生成操作之一：

EmbeddedJar - .JAR 将嵌入绑定库中。
InputJar - .JAR 将与绑定库分离。

通常使用的是 EmbeddedJar 生成操作，使 .JAR 自动打包到绑定库。这是最简单的方法 - .JAR 中的 Java 字节码转换为 Dex 字节码，然后（与托管的可调用包装器一起）嵌入 APK。如果要将 .JAR 与绑定库分离，可以使用 InputJar 选项；但必须确保 .JAR 文件在运行应用的设备上可用。

将生成操作设置为 EmbeddedJar：

接下来，打开项目属性，配置“目标框架”。如果 .JAR 使用任何 Android API，请将目标框架设置为 .JAR 预计的 API 级别。通常，.JAR 文件的开发人员将指示 .JAR 所兼容的 API 级别。（有关目标框架设置和 Android API 级别的更多概要信息，请参阅了解 Android API 级别。）

设置绑定库的目标 API 级别（在本示例中，使用的是 API 级别 19）：

最后，生成绑定库。尽管可能会显示一些警告消息，但绑定库项目应成功构建并在以下位置生成输出 .DLL：JarBinding/bin/Debug/JarBinding.dll

使用绑定库

若要在 Xamarin.Android 应用中使用此 .DLL，请执行以下操作：

添加对绑定库的引用。
通过托管的可调用包装器对 .JAR 进行调用。

在以下步骤中，我们将创建一个最小的应用，用于使用绑定库下载并显示 ImageView 中的图像；“繁重工作”由 .JAR 文件中驻留的代码完成。

首先，新建使用绑定库的 Xamarin.Android 应用。右键单击“解决方案”并选择“添加新项目”；将新项目命名为 BindingTest。我们将在与绑定库相同的解决方案中创建此应用，以简化此演练；但使用绑定库的应用可以驻留在其他解决方案中：

右键单击 BindingTest 项目的“引用”节点并选择“添加引用...”：

勾选之前创建的 JarBinding 项目，然后单击“确定”：

打开 BindingTest 项目的“引用”节点，验证是否存在 JarBinding 引用：

修改 BindingTest 布局 (Main.axml)，使其具有单个 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 类（驻留在绑定库中）的方法：

using Com.Squareup.Picasso;

修改 OnCreate 方法，以便其使用 Picasso 类从 URL 加载图像并在 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 ("https://i.imgur.com/DvpvklR.jpg")
            .Into (imageView);
    }
}

编译并运行 BindingTest 项目。应用将启动，并在短暂延迟后（取决于网络条件），应下载并显示与以下屏幕截图类似的图像：

祝贺你！你成功绑定了 Java 库 .JAR 并在 Xamarin Android 应用中使用了它。

总结

在本演练中，我们为第三方 .JAR 文件创建了一个绑定库，将绑定库添加到最小的测试应用中，然后运行该应用以验证我们的 C# 代码是否可以调用驻留在 .JAR 文件中的 Java 代码。

通过

绑定 .JAR

概述

演练

创建绑定库

使用绑定库

总结

相关链接

其他资源