從 Maven 綁定 Java 函式庫

常見的綁定情境是將 Java 函式庫綁定至寄存於 Maven 存放庫中的資源庫，例如 Maven Central。

.NET 9 引進了從 Maven 存放庫自動下載 Java 連結庫的支援，並驗證其相依性，以協助讓此案例更容易且更準確。

提示

如果在 .NET 9 之前使用 .NET 版本，或系結不是來自 Maven 的 Java 連結庫，請參閱 系結 Java 連結庫 檔。

操作指南

在本操作指南中，我們將綁定 CircleImageView 版本 3.1.0，這個函式庫會在圓形框架中顯示影像。

從Maven 存放庫中，我們可以看到此程式庫的下列識別碼，稍後將需要：

<dependency>
    <groupId>de.hdodenhof</groupId>
    <artifactId>circleimageview</artifactId>
    <version>3.1.0</version>
</dependency>

建立綁定程式庫

首先，建立新的 Bindings Library 專案。 這可以使用 Visual Studio 中提供的「Android Java 系結連結庫」專案範本或透過 dotnet 命令行來完成：

dotnet new android-bindinglib

開啟範本所建立的項目檔 （.csproj）。 我們會在ItemGroup內新增AndroidMavenLibrary元素，以指定我們想要系結的Java程式庫。

<!-- Include format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidMavenLibrary Include="de.hdodenhof:circleimageview" Version="3.1.0" />
</ItemGroup>

現在，使用 Visual Studio 的 Build 命令，或從命令行建置專案：

dotnet build

此 Java 連結庫現已系結，且已準備好由適用於 Android 的 .NET 應用程式項目參考，或發佈至 NuGet 以供公用取用。

其他選項

略過 Managed 綁定

根據預設，專案中放置的任何 .JAR/.AAR 檔案都會建立 C# 系結。 如果您不打算從 C# 呼叫 Java API，那麼 C# 系結的創建可能會很具挑戰性，也沒有必要這麼做。

當 Java 連結庫只是另一個 Java 連結庫的相依性，而且不需要直接從 C# 呼叫時，尤其如此。 在此情況下， Bind="false" 屬性只能包含 Java 相依性，但不能系結它。

<ItemGroup>
  <AndroidMavenLibrary Include="de.hdodenhof:circleimageview" Version="3.1.0" Bind="false" />
</ItemGroup>

下一步

  • AndroidMavenLibrary 選項 - 教學庫會自動從預設存放庫 Maven Central 下載。 您可以指定其他 Maven 存放庫和選項。

  • Java 相依性驗證 - 逐步解說中系結的 Java 連結庫是微不足道的，並不相依於任何其他 Java 套件。 大部分的函式庫會依賴其他 Java 套件，並且會顯示錯誤，以確保可以解決這些依賴性。

必須先修正這些錯誤，繫結才能進行建置，如下所示：

error XA4241: Java dependency 'androidx.collection:collection:1.0.0' is not satisfied.
error XA4242: Java dependency 'org.jetbrains.kotlin:kotlin-stdlib:1.9.0' is not satisfied. Microsoft maintains the NuGet package 'Xamarin.Kotlin.StdLib' that could fulfill this dependency.

  • 元數據自定義綁定 - 教學中涉及的 Java 庫十分簡單，綁定工具能夠全自動地將其轉換為 C# API。 不幸的是，這通常不是這種情況，而且通常會發生編譯錯誤。 您必須使用「元數據」來修正這些錯誤，以手動指示系結工具如何解決 Java 和 C# 語言之間的差異。

  • 變更命名空間 - 逐步解說中的類型最終會位於 .NET 命名空間 DE.Hdodenhof.Circleimageview中。 Java 套件名稱通常比 .NET 命名空間更冗長，因此可能更適合變更，例如 CircleImageViewLibrary 使用 AndroidNamespaceReplacement：

<ItemGroup>
  <AndroidNamespaceReplacement Include='DE.Hdodenhof.Circleimageview' Replacement='CircleImageViewLibrary' />
</ItemGroup>
  • Last updated on