繫結 Java 程式庫

  • 發行項

Android 社群有許多您可能想要在應用程式中使用的 Java 連結庫;本指南說明如何藉由建立系結連結庫，將 Java 連結庫併入 Xamarin.Android 應用程式。

概觀

Android 的第三方連結庫生態系統非常龐大。 因此，使用現有的 Android 連結庫通常比建立新的連結庫有意義。 Xamarin.Android 提供兩種方式來使用這些連結庫：

  • 建立系 結連結庫 ，以 C# 包裝函式自動包裝連結庫，讓您可以透過 C# 呼叫叫用 Java 程式代碼。

  • 使用 Java 原生介面 （JNI） 直接叫用 Java 連結庫程式碼中的呼叫。 JNI 是一種程式設計架構，可讓 Java 程式代碼呼叫原生應用程式或連結庫並加以呼叫。

本指南說明第一個選項：如何建立 系結連結庫，將一或多個現有的 Java 連結庫 包裝至您可以在應用程式中連結的元件。 如需使用 JNI 的詳細資訊，請參閱 使用 JNI。

Xamarin.Android 使用 Managed 可呼叫包裝函 式 （MCW） 實作系結。 MCW 是 JNI 網橋，用於 Managed 程式代碼需要叫用 Java 程式代碼時。 Managed 可呼叫包裝函式也支援子類別化 Java 類型，以及在 Java 類型上覆寫虛擬方法。 同樣地，每當 Android 執行時間 （ART） 程式代碼想要叫用 Managed 程式代碼時，它就會透過另一個稱為 Android 可呼叫包裝函式的 JNI 網橋來叫用 Managed 程式代碼。 下圖說明此 架構 ：

Android JNI bridge architecture

系結連結庫是包含 Java 類型的 Managed 可呼叫包裝函式的元件。 例如，以下是我們想要包裝在系結庫中的 Java 類型 MyClass：

package com.xamarin.mycode;

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

針對包含MyClass的.jar產生系結庫之後，我們可以從 C# 將它具現化並呼叫方法：

var instance = new MyClass ();

string result = instance.MyMethod (42);

若要建立此系結連結庫，您可以使用 Xamarin.Android Java 系結連結庫 範本。 產生的系結專案會建立 .NET 元件，其中包含 MCW 類別、 .jar 檔案，以及內嵌在其中之 Android Library 專案的資源。 您也可以建立 Android 封存的系結連結庫（。AAR） 檔案和 Eclipse Android 連結庫專案。 藉由參考產生的系結連結庫 DLL 元件，您可以在 Xamarin.Android 專案中重複使用現有的 Java 連結庫。

當您在系結連結庫中參考類型時，必須使用系結連結庫的命名空間。 一般而言，您會在 C# 原始程式檔頂端新增 using 指示詞，這是 Java 套件名稱的 .NET 命名空間版本。 例如，如果系結 .jar 的 Java 套件名稱如下：

com.company.package

然後，您會將下列 using 語句放在 C# 來源檔案頂端，以存取系結 .jar 檔案中的類型：

using Com.Company.Package;

系結現有的 Android 連結庫時，必須記住下列幾點：

  • 連結庫是否有任何外部相依性？ – Android 連結庫所需的任何 Java 相依性都必須包含在 Xamarin.Android 專案中，做為 ReferenceJar 或 EmbeddedReferenceJar。 任何原生元件都必須新增至系結專案做為 EmbeddedNativeLibrary。

  • Android 連結庫的目標 Android API 版本為何？ – 無法「降級」Android API 層級;請確定 Xamarin.Android 系結專案是以與 Android 連結庫相同的 API 層級（或更高層級）為目標。

  • 使用哪個版本的 JDK 來編譯連結庫？ – 如果 Android 連結庫建置的 JDK 版本與 Xamarin.Android 所使用的 JDK 版本不同，就可能發生系結錯誤。 可能的話，請使用安裝 Xamarin.Android 所使用的相同 JDK 版本重新編譯 Android 連結庫。

建置動作

當您建立系結連結庫時，會在 .jar 或上設定建置動作。您納入系結連結庫專案的 AAR 檔案 – 每個建置動作都會決定.jar或 。AAR 檔案會內嵌至您的系結連結庫（或參考）。 下列清單摘要說明這些建置動作：

  • EmbeddedJar – 將 .jar 內嵌至產生的系結連結庫 DLL 作為內嵌資源。 這是最簡單的且最常使用的建置動作。 當您想要 將.jar 自動編譯成位元組程序代碼，並封裝至系結連結庫時，請使用此選項。

  • InputJar – 不會將 .jar 內嵌至產生的系結連結庫.DLL。 您的系結連結庫.DLL會在運行時間相依於此 .jar 。 當您不想在系結連結庫中包含 .jar 時，請使用此選項（例如，基於授權原因）。 如果您使用此選項，您必須確定執行應用程式的裝置上可以使用輸入 .jar 。

  • LibraryProjectZip – 內嵌 。將 AAR 檔案放入產生的系結連結庫.DLL。 這類似於 EmbeddedJar，不同之處在於您可以在系結 中存取資源（以及程式代碼）。AAR 檔案。 當您想要內嵌 時，請使用此選項。將 AAR 放入系結連結庫。

  • ReferenceJar– 指定參考.jar：參考.jar是系結.jar或 其中一個.jar。AAR 檔案相依於。 此參考 .jar 僅用於滿足編譯時間相依性。 當您使用此建置動作時，不會為參考 .jar 建立 C# 系結，也不會內嵌在產生的系結連結庫中.DLL。 當您將進行參考 的系結連結庫.jar 但尚未這麼做時，請使用此選項。 此建置動作適用於封裝多個 .jars （和/或 。AR） 轉換成多個相互相依的系結連結庫。

  • EmbeddedReferenceJar – 將參考 .jar 內嵌至產生的系結連結庫.DLL。 當您想要為輸入 .jar （或 ） 建立 C# 系結時，請使用此建置動作。AAR） 及其系結連結庫中的所有參考 .jar（s）。

  • EmbeddedNativeLibrary – 將原生 .so 內嵌至系結。 此建置動作用於所系結.jar檔案所需的 .so 檔案。 您可能需要先手動載入 .so 連結庫，再從 Java 連結庫執行程式代碼。 如下所述。

下列指南會更詳細地說明這些建置動作。

此外，下列建置動作可用來協助匯入 Java API 檔，並將其轉換成 C# XML 檔：

  • JavaDocJar 用來指向 Javadoc 封存 Jar，以取得符合 Maven 套件樣式的 Java 連結庫（通常是 FOOBAR-javadoc**.jar**）。
  • JavaDocIndex 用來指向 index.html API 參考檔 HTML 內的檔案。
  • JavaSourceJar 用來補充 JavaDocJar，以先從來源產生 JavaDoc，然後將結果 JavaDocIndex視為 ，作為符合 Maven 套件樣式的 Java 連結庫（通常是 FOOBAR-sources**.jar**）。

API 檔應該是 Java8、Java7 或 Java6 SDK 的預設 doclet（它們都是不同的格式），或 DroidDoc 樣式。

在系結中包含原生連結庫

在系結 Java 連結庫時，可能需要在 Xamarin.Android 系結專案中加入 .so 連結庫。 當包裝的 Java 程式代碼執行時，Xamarin.Android 將無法進行 JNI 呼叫，而且錯誤訊息 java.lang.UnsatisfiedLinkError：找不到原生方法： 會出現在應用程式的註銷中。

修正此問題的作業是手動載入 .so 連結庫，並呼叫 Java.Lang.JavaSystem.LoadLibrary。 例如，假設 Xamarin.Android 專案已使用 EmbeddedNativeLibrary 的建置動作包含在系結專案中的共用連結庫libpocketsphinx_jni.so，下列代碼段（在使用共用連結庫之前執行）會載入 .so 連結庫：

Java.Lang.JavaSystem.LoadLibrary("pocketsphinx_jni");

將 Java API 調整為 C⧣

Xamarin.Android 系結產生器將會變更一些 Java 慣用語和模式，以對應至 .NET 模式。 下列清單描述 Java 如何對應至 C#/.NET：

  • Java 中的 Setter/Getter 方法是 .NET 中的 Properties。

  • Java 中的欄位 是 .NET 中的屬性 。

  • Java 中的接聽程式/接聽程式介面 是 .NET 中的事件 。 回呼介面中方法的參數將由子類別表示 EventArgs 。

  • Java 中的靜態巢狀類別是 .NET 中的巢狀類別。

  • Java 中的 Inner 類別是巢狀類別，具有 C# 中的實例建構函式。

系結案例

下列系結案例指南可協助您系結 Java 連結庫（或連結庫），以納入您的應用程式：

  • 系結 。JAR 是建立.jar檔案系結連結庫的逐步解說。

  • 系結 。AAR 是針對 建立系結連結庫的逐步解說。AAR 檔案。 閱讀本逐步解說，以瞭解如何系結 Android Studio 連結庫。

  • 系結 Eclipse 連結庫專案 是從 Android Library Projects 建立系結連結庫的逐步解說。 閱讀本逐步解說，以瞭解如何系結 Eclipse Android Library Projects。

  • 自定義系 結說明如何對系結進行手動修改，以解決建置錯誤並塑造產生的 API，使其更類似 C#。

  • 疑難解答系 結列出常見的系結錯誤案例、說明可能的原因，並提供解決這些錯誤的建議。