Associazione di una libreria Java

La community Android offre molte librerie Java che possono essere usate nell'app. Queste librerie Java vengono spesso incluse nel formato .JAR (Java Archive) o .AAR (Android Archive), ma è possibile includere un .JAR/.AAR in una Java Bindings Library affinché la relativa funzionalità sia disponibile per le applicazioni .NET per Android. Lo scopo della libreria Java Bindings è quello di rendere disponibili le API nei file .JAR/.AAR per il codice C# tramite wrapper di codice generati automaticamente.

guida dettagliata

In questa guida verrà collegata la versione 3.1.0 di CircleImageView, una libreria che visualizza un'immagine in un'area di disegno circolare.

Dal repository Maven, scaricare circleimageview-3.1.0.aar sul computer locale per essere vincolato.

Creazione della libreria dei binding

Creare prima di tutto un nuovo progetto libreria binding. Questa operazione può essere eseguita con il modello di progetto "Libreria di binding Java Android" disponibile in Visual Studio o tramite la dotnet riga di comando con:

dotnet new android-bindinglib

Copiare il circleimageview-3.1.0.aar file nella directory del progetto.

Come i progetti stile .NET SDK, i progetti di associazione .NET per Android includono automaticamente qualsiasi file .JAR/.AAR nella directory del progetto come un tipo di file AndroidLibrary, quindi non è necessaria alcuna configurazione aggiuntiva.

Compilare ora il progetto usando il comando Compila di Visual Studio o dalla riga di comando:

dotnet build

Questa libreria Java è stata associata ed è pronta per essere referenziata da un progetto di applicazione .NET per Android o pubblicata su NuGet per l'utilizzo pubblico.

Opzioni aggiuntive

Saltare le associazioni gestite

Per impostazione predefinita, le associazioni C# verranno create per qualsiasi .JAR/.AAR inserito nel progetto. Tuttavia, le associazioni C# possono essere difficili da creare e non sono necessarie se non si intende chiamare l'API Java da C#.

Questo è soprattutto il caso in cui la libreria Java è semplicemente una dipendenza di un'altra libreria Java e non deve essere chiamata direttamente da C#. In questo caso, l'attributo Bind="false" può essere usato solo per includere la dipendenza Java, ma non per associarla.

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

Si noti che se si usano importazioni automatiche è necessario usare Update per modificare il file importato automaticamente anziché aggiungere una copia aggiuntiva con Include.

Dipendenze Java

Una libreria Java può dipendere da altre librerie Java che dovranno essere incluse in un pacchetto con l'applicazione per consentire il funzionamento dell'applicazione. Queste informazioni vengono tradizionalmente fornite in un file .POM ed è responsabilità dell'utente assicurarsi che le dipendenze necessarie vengano referenziate correttamente, solitamente tramite un pacchetto NuGet o incorporando i file .JAR/.AAR necessari nel progetto.

In .NET 9 è stata aggiunta la funzionalità Di verifica delle dipendenze Java. Fornendo il file .POM, gli strumenti di binding possono aiutare a garantire che siano soddisfatte tutte le dipendenze Java necessarie.

Per abilitare la Verifica delle Dipendenze Java nel nostro walkthrough, assicurati di usare .NET 9+ e che il tuo progetto abbia come destinazione una versione pari o superiore a net9.0-android.

Scarica circleimageview-3.1.0.pom dal repository Maven localmente e inseriscilo nella cartella del progetto. Si noti che i file .POM non vengono rilevati automaticamente perché devono essere associati al corretto .JAR/.AAR.

Aggiornare l'oggetto importato automaticamente AndroidLibrary per specificare il percorso del file .POM con l'attributo Manifest. Specificare anche il JavaArtifact e il JavaVersion della libreria Java:

<!-- 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>

Questa libreria è semplice e non ha dipendenze Java, ma se le avesse e non fossero soddisfatte, verrebbe emesso un errore come il seguente:

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.

Altre informazioni sulla configurazione della verifica delle dipendenze Java e su come soddisfare le dipendenze sono disponibili nella documentazione.

Passaggi successivi

• Personalizzazione di binding con metadati: la libreria Java legata nella guida passo-passo è semplice e gli strumenti di binding sono stati in grado di convertirla completamente in un'API C#. Sfortunatamente questo non è spesso il caso e spesso si verificano errori di compilazione. Questi errori devono essere corretti con "metadati" per indicare manualmente agli strumenti di associazione come risolvere le differenze tra i linguaggi Java e C#.

• Modifica degli spazi dei nomi: i tipi nella procedura dettagliata finiscono nello spazio dei nomi .NETDE.Hdodenhof.Circleimageview. I nomi dei pacchetti Java tendono ad essere più verbosi dei namespace .NET e potrebbe essere preferibile modificarli, ad esempio usando CircleImageViewLibraryAndroidNamespaceReplacement.

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