Liaison d’une bibliothèque Java

Article
11/10/2024

La communauté Android propose de nombreuses bibliothèques Java que vous pouvez utiliser dans votre application. Ces bibliothèques Java sont souvent empaquetées dans . JAR (Archive Java) ou . Format AAR (Android Archive), mais vous pouvez empaqueter un . JARRE/. AAR dans une bibliothèque de liaisons Java afin que ses fonctionnalités soient disponibles pour les applications .NET pour Android. L’objectif de la bibliothèque Liaisons Java est de rendre les API dans le . JARRE/. Fichier AAR disponible pour le code C# via des wrappers de code générés automatiquement.

Conseil

.NET 9 introduit la prise en charge du téléchargement et de la liaison automatique d’une bibliothèque Java à partir d’un référentiel Maven. Consultez la documentation Liaison d’une bibliothèque Java à partir de Maven pour simplifier ce scénario.

Procédure pas à pas

Dans cette procédure pas à pas, nous allons lier la version 3.1.0 de CircleImageView, une bibliothèque qui affiche une image dans un canevas circulaire.

À partir du référentiel Maven, téléchargez circleimageview-3.1.0.aar localement pour être lié.

Création de la bibliothèque de liaisons

Tout d’abord, créez un projet de bibliothèque de liaisons. Pour ce faire, vous pouvez utiliser le modèle de projet « Bibliothèque de liaisons Java Android » disponible dans Visual Studio ou via la dotnet ligne de commande avec :

dotnet new android-bindinglib

Copiez le circleimageview-3.1.0.aar fichier dans le répertoire du projet.

Comme les projets de style sdk .NET, les projets de liaison .NET pour Android incluent automatiquement n’importe quel projet . JARRE/. Les fichiers AAR dans le répertoire du projet en tant que AndroidLibrary fichier de type, aucune configuration supplémentaire n’est donc nécessaire.

Maintenant, générez le projet à l’aide de la commande Build de Visual Studio ou à partir de la ligne de commande :

dotnet build

Cette bibliothèque Java a maintenant été liée et prête à être référencée par un projet d’application .NET pour Android ou publiée sur NuGet pour une consommation publique.

Options supplémentaires

Ignorer les liaisons managées

Par défaut, les liaisons C# sont créées pour n’importe quel . JARRE/. AAR placé dans le projet. Toutefois, les liaisons C# peuvent être difficiles à créer et ne sont pas nécessaires si vous n’avez pas l’intention d’appeler l’API Java à partir de C#.

Cela est particulièrement le cas lorsque la bibliothèque Java est simplement une dépendance d’une autre bibliothèque Java et n’a pas besoin d’être appelée directement à partir de C#. Dans ce cas, l’attribut Bind="false" peut être utilisé pour inclure uniquement la dépendance Java, mais pas la lier.

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

Notez que si vous utilisez des importations automatiques, vous devez utiliser Update pour modifier le fichier importé automatiquement au lieu d’ajouter une copie supplémentaire avec Include.

Dépendances Java

Une bibliothèque Java peut dépendre d’autres bibliothèques Java qui seront requises pour être empaquetées avec votre application afin que votre application fonctionne. Ces informations sont généralement fournies dans un . Fichier POM, et il est de votre responsabilité de s’assurer que toutes les dépendances nécessaires sont correctement référencées, généralement via un package NuGet ou en regroupant les dépendances nécessaires. JARRE/. Fichiers AAR dans votre projet.

Dans .NET 9, la fonctionnalité vérification des dépendances Java a été ajoutée. En fournissant le . Fichier POM, les outils de liaison peuvent vous aider à vérifier que vous avez rempli toutes les dépendances Java requises.

Pour activer la vérification des dépendances Java pour notre procédure pas à pas, vérifiez que vous utilisez .NET 9+ et que votre projet cible net9.0-android ou version ultérieure.

À partir du référentiel Maven, téléchargez-le circleimageview-3.1.0.pom localement et placez-le dans votre dossier de projet. Notez que . Les fichiers POM ne sont pas détectés automatiquement, car ils doivent être associés au fichier correct. JARRE/. AAR.

Mettez à jour l’importation AndroidLibrary automatique pour spécifier l’emplacement du . Fichier POM avec Manifest attribut. En outre, spécifiez la JavaArtifact bibliothèque Java et JavaVersion les éléments suivants :

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

Cette bibliothèque est triviale et n’a pas de dépendances Java, mais si elle n’a pas été satisfaite, une erreur semblable à celle-ci serait émise :

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.

Des informations supplémentaires sur la configuration de la vérification des dépendances Java et sur la façon de satisfaire les dépendances sont disponibles dans la documentation.

Étapes suivantes

Personnalisation des liaisons avec des métadonnées : la bibliothèque Java liée à la procédure pas à pas est triviale et l’outil de liaison a été en mesure de le convertir entièrement en API C#. Malheureusement, ce n’est souvent pas le cas et il y aura souvent des erreurs de compilation. Ces erreurs doivent être corrigées avec des « métadonnées » pour indiquer manuellement à l’outil de liaison comment résoudre les différences entre les langages Java et C#.
Modification des espaces de noms : les types de la procédure pas à pas se terminent dans l’espace de noms DE.Hdodenhof.Circleimageview.NET. Les noms de package Java ont tendance à être plus détaillés que les espaces de noms .NET et il peut être plus souhaitable de le modifier, par exemple pour CircleImageViewLibrary utiliser un AndroidNamespaceReplacement:

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

Partager via