Binden einer Java-Bibliothek

Die Android-Community hat viele Java-Bibliotheken veröffentlicht, die Sie für Ihre App verwenden können. Diese Java-Bibliotheken werden häufig im .JAR- (Java Archive) oder .AAR-Format (Android Archive) gepackt, aber Sie können ein .JAR/.AAR in einer Java Bindings Library verpacken, sodass deren Funktionalität für .NET-Anwendungen auf Android verfügbar ist. Der Zweck der Java-Bindings-Bibliothek besteht darin, die APIs in der .JAR/.AAR-Datei über automatisch generierte Codewrapper für C#-Code verfügbar zu machen.

Schritt-für-Schritt-Anleitung

In dieser Anleitung binden wir Version 3.1.0 von CircleImageView, einer Bibliothek, die ein Bild in einem kreisförmigen Bereich anzeigt.

Laden Sie circleimageview-3.1.0.aar aus dem Maven-Repository herunter, um lokal gebunden zu werden.

Erstellen der Bindungenbibliothek

Erstellen Sie zunächst ein neues Bindings-Library-Projekt. Dies kann mit der Projektvorlage "Android Java Binding Library" erfolgen, die in Visual Studio oder über die dotnet Befehlszeile verfügbar ist:

dotnet new android-bindinglib

Kopieren Sie die circleimageview-3.1.0.aar Datei in das Projektverzeichnis.

Wie .NET SDK-Stilprojekte enthalten .NET für Android-Binding-Projekte automatisch alle .JAR/.AAR-Dateien im Projektverzeichnis als AndroidLibrary Dateityp, sodass keine zusätzliche Konfiguration erforderlich ist.

Erstellen Sie nun das Projekt mit dem Befehl "Erstellen" von Visual Studio oder über die Befehlszeile:

dotnet build

Diese Java-Bibliothek wurde jetzt gebunden und kann von einem .NET für Android-Anwendungsprojekt referenziert oder für öffentliche Nutzung in NuGet veröffentlicht werden.

Zusätzliche Optionen

Verwaltete Bindungen überspringen

Standardmäßig werden C#-Bindungen für alle im Projekt platzierten .JAR-/.AAR-Dateien erstellt. C#-Bindungen können jedoch schwierig zu erstellen sein und sind nicht erforderlich, wenn Sie nicht beabsichtigen, die Java-API aus C# aufzurufen.

Dies ist insbesondere der Fall, wenn die Java-Bibliothek einfach eine Abhängigkeit von einer anderen Java-Bibliothek ist und nicht direkt von C# aufgerufen werden muss. In diesem Fall kann das Bind="false" Attribut nur verwendet werden, um die Java-Abhängigkeit einzuschließen, aber nicht zu binden.

<ItemGroup>
  <AndroidLibrary Update="circleimageview-3.1.0.aar" Bind="false" />
</ItemGroup>

Hinweis: Wenn Sie automatische Importe verwenden, müssen Sie Update nutzen, um die automatisch importierte Datei zu ändern, anstatt eine zusätzliche Kopie mit Include hinzuzufügen.

Java-Abhängigkeiten

Eine Java-Bibliothek hängt möglicherweise von anderen Java-Bibliotheken ab, die für die gepackte Anwendung erforderlich sind, damit Ihre Anwendung funktioniert. Diese Informationen werden traditionell in einer .POM-Datei bereitgestellt, und es liegt in Ihrer Verantwortung sicherzustellen, dass alle erforderlichen Abhängigkeiten ordnungsgemäß referenziert werden, in der Regel über ein NuGet-Paket oder durch Bündeln der benötigten .JAR/.AAR-Dateien in Ihrem Projekt.

In .NET 9 wurde das Feature "Java Dependency Verification" hinzugefügt. Durch die Bereitstellung der .POM-Datei können die Bindungstools sicherstellen, dass Sie alle notwendigen Java-Abhängigkeiten erfüllt sind.

Um die Java-Abhängigkeitsüberprüfung für unsere exemplarische Vorgehensweise zu aktivieren, stellen Sie sicher, dass Sie .NET 9+ und Ihre Projektziele net9.0-android oder höher verwenden.

Laden Sie aus dem Maven-Repository lokal herunter circleimageview-3.1.0.pom , und platzieren Sie es in Ihrem Projektordner. Beachten Sie, dass .POM-Dateien nicht automatisch erkannt werden, weil sie dem richtigen .JAR/.AAR zugeordnet werden müssen.

Aktualisieren Sie das automatisch importierte AndroidLibrary, um den Speicherort der .POM-Datei mit dem Attribut Manifest anzugeben. Geben Sie außerdem die JavaArtifact und JavaVersion der Java-Bibliothek an.

<!-- JavaArtifact format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidLibrary
    Update="circleimageview-3.1.0.aar"
    Manifest="circleimageview-3.1.0.pom"
    JavaArtifact="de.hdodenhof:circleimageview"
    JavaVersion="3.1.0" />
</ItemGroup>

Diese Bibliothek ist trivial und hat keine Java-Abhängigkeiten, aber wenn dies der Fall war und sie nicht zu erreichen waren, würde ein Fehler wie folgt ausgegeben:

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.

Weitere Informationen zum Konfigurieren der Java-Abhängigkeitsüberprüfung und zur Erfüllung von Abhängigkeiten finden Sie in der Dokumentation.

Nächste Schritte

• Anpassen von Bindungen mit Metadaten – Die in der exemplarischen Vorgehensweise gebundene Java-Bibliothek ist trivial, und die Bindungstools konnten sie vollständig automatisch in eine C#-API konvertieren. Leider ist dies oft nicht der Fall, und es werden häufig Kompilierungsfehler auftreten. Diese Fehler müssen mit "Metadaten" behoben werden, um die Bindungstools manuell anzuweisen, wie Unterschiede zwischen den Java- und C#-Sprachen behoben werden.

• Ändern von Namespaces – Die Typen in der Schritt-für-Schritt-Anleitung befinden sich im .NET-Namespace DE.Hdodenhof.Circleimageview. Java-Paketnamen sind in der Regel ausführlicher als .NET-Namespaces, und es kann sinnvoller sein, diese zu ändern, zum Beispiel durch die Verwendung von CircleImageViewLibrary einer AndroidNamespaceReplacement.

<ItemGroup>
  <AndroidNamespaceReplacement Include='DE.Hdodenhof.Circleimageview' Replacement='CircleImageViewLibrary' />
</ItemGroup>