Liaison d’un fichier .AARBinding an .AAR

Important

Nous étudions actuellement l’utilisation de la liaison personnalisée sur la plateforme Xamarin.We're currently investigating custom binding usage on the Xamarin platform. Veuillez suivre ce questionnaire pour informer les futurs efforts de développement.Please take this survey to inform future development efforts.

Cette procédure pas à pas fournit des instructions détaillées sur la création d’une bibliothèque de liaisons Java Xamarin. Android à partir d’un Android. Fichier AAR.This walkthrough provides step-by-step instructions for creating a Xamarin.Android Java Bindings Library from an Android .AAR file.

Vue d’ensembleOverview

L' Archive Android (. AAR) est le format de fichier pour les bibliothèques Android.The Android Archive (.AAR) file is the file format for Android libraries. Pièce. Le fichier AAR est un. Archive ZIP qui contient les éléments suivants :An .AAR file is a .ZIP archive that contains the following:

  • Code Java compiléCompiled Java code
  • ID de ressourceResource IDs
  • RessourcesResources
  • Métadonnées (par exemple, déclarations d’activité, autorisations)Meta-data (for example, Activity declarations, permissions)

Dans ce guide, nous allons parcourir les bases de la création d’une bibliothèque de liaisons pour une seule. Fichier AAR.In this guide, we'll step through the basics of creating a Bindings Library for a single .AAR file. Pour obtenir une vue d’ensemble de la liaison de bibliothèque Java en général (à l’aide d’un exemple de code de base), consultez liaison d’une bibliothèque Java.For an overview of Java library binding in general (with a basic code example), see Binding a Java Library.

Important

Un projet de liaison ne peut inclure qu’un seul. Fichier AAR.A binding project can only include one .AAR file. Si. AAR dépend d’autres. AAR, ces dépendances doivent être contenues dans leur propre projet de liaison, puis référencées.If the .AAR depends on other .AAR, then those dependencies should be contained in their own binding project and then referenced. Consultez le bogue 44573.See Bug 44573.

Procédure pas à pasWalkthrough

Nous allons créer une bibliothèque de liaisons pour un exemple de fichier d’archive Android créé dans Android Studio, textanalyzer. AAR.We'll create a Bindings Library for an example Android archive file that was created in Android Studio, textanalyzer.aar. Voici. AAR contient une TextCounter classe avec des méthodes statiques qui comptent le nombre de voyelles et de consonnes dans une chaîne.This .AAR contains a TextCounter class with static methods that count the number of vowels and consonants in a string. En outre, textanalyzer. AAR contient une ressource image permettant d’afficher les résultats du comptage.In addition, textanalyzer.aar contains an image resource to help display the counting results.

Nous allons utiliser les étapes suivantes pour créer une bibliothèque de liaisons à partir du. Fichier AAR :We'll use the following steps to create a Bindings Library from the .AAR file:

  1. Créez un projet de bibliothèque de liaisons Java.Create a new Java Bindings Library project.

  2. Ajoutez un seul. Fichier AAR dans le projet.Add a single .AAR file to the project. Un projet de liaison ne peut contenir qu’un seul. AAR.A binding project may only contain a single .AAR.

  3. Définissez l’action de génération appropriée pour le. Fichier AAR.Set the appropriate build action for the .AAR file.

  4. Choisissez une version cible de .NET Framework que le. AAR prend en charge.Choose a target framework that the .AAR supports.

  5. Générez la bibliothèque de liaisons.Build the Bindings Library.

Une fois la bibliothèque de liaisons créée, nous allons développer une petite application Android qui invite l’utilisateur à entrer une chaîne de texte, appelle. Méthodes AAR pour analyser le texte, récupère l’image à partir de. AAR et affiche les résultats avec l’image.Once we've created the Bindings Library, we'll develop a small Android app that prompts the user for a text string, calls .AAR methods to analyze the text, retrieves the image from the .AAR, and displays the results along with the image.

L’exemple d’application accède à la TextCounter classe de textanalyzer. AAR:The sample app will access the TextCounter class of textanalyzer.aar:

package com.xamarin.textcounter;

public class TextCounter
{
    ...
    public static int numVowels (String text) { ... };
    ...
    public static int numConsonants (String text) { ... };
    ...
}

En outre, cet exemple d’application va récupérer et afficher une ressource d’image empaquetée dans textanalyzer. AAR:In addition, this sample app will retrieve and display an image resource that is packaged in textanalyzer.aar:

Image de singe XamarinXamarin monkey image

Cette ressource image se trouve dans textanalyzer. AAR, à l’adresse res/drawable/monkey.png .This image resource resides at res/drawable/monkey.png in textanalyzer.aar.

Création de la bibliothèque de liaisonsCreating the Bindings Library

Avant de commencer à suivre les étapes ci-dessous, téléchargez l’exemple de fichier d’archive textanalyzer. AAR Android :Before commencing with the steps below, please download the example textanalyzer.aar Android archive file:

  1. Créez un projet de bibliothèque de liaisons en commençant par le modèle Bibliothèque de liaisons Android.Create a new Bindings Library project starting with the Android Bindings Library template. Vous pouvez utiliser Visual Studio pour Mac ou Visual Studio (les captures d’écran ci-dessous illustrent Visual Studio, mais Visual Studio pour Mac sont très similaires).You can use either Visual Studio for Mac or Visual Studio (the screenshots below show Visual Studio, but Visual Studio for Mac is very similar). Nommez la solution AarBinding:Name the solution AarBinding:

    Créer un projet AarBindingsCreate AarBindings project

  2. Le modèle comprend un dossier jar dans lequel vous ajoutez votre. AAR (s) au projet de bibliothèque de liaisons.The template includes a Jars folder where you add your .AAR(s) to the Bindings Library project. Cliquez avec le bouton droit sur le dossier jar et sélectionnez Ajouter > élément existant:Right-click the Jars folder and select Add > Existing Item:

    Ajouter un élément existantAdd existing item

  3. Accédez au fichier textanalyzer. AAR téléchargé précédemment, sélectionnez-le, puis cliquez sur Ajouter:Navigate to the textanalyzer.aar file downloaded earlier, select it, and click Add:

    Ajouter textanalayzer. AARAdd textanalayzer.aar

  4. Vérifiez que le fichier textanalyzer. AAR a été correctement ajouté au projet :Verify that the textanalyzer.aar file was successfully added to the project:

    Le fichier textanalyzer. AAR a été ajoutéThe textanalyzer.aar file was added

  5. Définissez l’action de génération pour textanalyzer. AAR sur LibraryProjectZip .Set the Build Action for textanalyzer.aar to LibraryProjectZip. Dans Visual Studio pour Mac, cliquez avec le bouton droit sur textanalyzer. AAR pour définir l’action de génération.In Visual Studio for Mac, right-click textanalyzer.aar to set the Build Action. Dans Visual Studio, l’action de génération peut être définie dans le volet Propriétés .) :In Visual Studio, the Build Action can be set in the Properties pane):

    Définition de l’action de génération textanalyzer. AAR sur LibraryProjectZipSetting the textanalyzer.aar build action to LibraryProjectZip

  6. Ouvrez les propriétés du projet pour configurer la version cible de .NET Framework.Open the project Properties to configure the Target Framework. Si. AAR utilise des API Android, définit le Framework cible au niveau de l’API que le. AAR attend.If the .AAR uses any Android APIs, set the Target Framework to the API level that the .AAR expects. (Pour plus d’informations sur le paramètre Framework cible et les niveaux d’API Android en général, consultez Présentation des niveaux d’API Android.)(For more information about the Target Framework setting and Android API levels in general, see Understanding Android API Levels.)

    Définissez le niveau d’API cible pour votre bibliothèque de liaisons.Set the target API level for your Bindings Library. Dans cet exemple, nous sommes libres d’utiliser le niveau d’API de plateforme le plus récent (niveau d’API 23), car notre textanalyzer n’a pas de dépendance sur les API Android :In this example, we are free to use the latest platform API level (API level 23) because our textanalyzer does not have a dependency on Android APIs:

    Définition du niveau cible sur l’API 23Setting the target level to API 23

  7. Générez la bibliothèque de liaisons.Build the Bindings Library. Le projet de bibliothèque de liaisons doit être généré correctement et produire une sortie. DLL à l’emplacement suivant : AarBinding/bin/debug/AarBinding.dllThe Bindings Library project should build successfully and produce an output .DLL at the following location: AarBinding/bin/Debug/AarBinding.dll

Utilisation de la bibliothèque de liaisonsUsing the Bindings Library

Pour utiliser ce. DLL dans votre application Xamarin. Android, vous devez d’abord ajouter une référence à la bibliothèque de liaisons.To consume this .DLL in your Xamarin.Android app, you must first add a reference to the Bindings Library. Effectuez les étapes suivantes :Use the following steps:

  1. Nous créons cette application dans la même solution que la bibliothèque de liaisons pour simplifier cette procédure pas à pas.We're creating this app in the same Solution as the Bindings Library to simplify this walkthrough. (L’application qui utilise la bibliothèque de liaisons peut également résider dans une autre solution.) Créer une application Xamarin. Android : cliquez avec le bouton droit sur la solution et sélectionnez Ajouter nouveau projet.(The app that consumes the Bindings Library could also reside in a different Solution.) Create a new Xamarin.Android app: right-click the Solution and select Add New Project. Nommez le nouveau projet BindingTest:Name the new project BindingTest:

    Créer un projet BindingTestCreate new BindingTest project

  2. Cliquez avec le bouton droit sur le nœud références du projet BindingTest et sélectionnez Ajouter une référence...:Right-click the References node of the BindingTest project and select Add Reference...:

    Cliquez sur Ajouter une référence.Click Add Reference

  3. Sélectionnez le projet AarBinding créé précédemment, puis cliquez sur OK:Select the AarBinding project created earlier and click OK:

    Vérifier le projet de liaison AARCheck the AAR binding project

  4. Ouvrez le nœud références du projet BindingTest pour vérifier que la référence AarBinding est présente :Open the References node of the BindingTest project to verify that the AarBinding reference is present:

    AarBinding est listé sous RéférencesAarBinding is listed under References

Si vous souhaitez afficher le contenu du projet de bibliothèque de liaisons, vous pouvez double-cliquer sur la référence pour l’ouvrir dans l' Explorateur d’objets.If you would like to view the contents of the Binding Library project, you can double-click the reference to open it in the Object Browser. Vous pouvez voir le contenu mappé de l' Com.Xamarin.Textcounter espace de noms (mappé à partir du com.xamarin.textanalyzezr package Java) et vous pouvez afficher les membres de la TextCounter classe :You can see the mapped contents of the Com.Xamarin.Textcounter namespace (mapped from the Java com.xamarin.textanalyzezr package) and you can view the members of the TextCounter class:

Affichage de l’Explorateur d’objetsViewing the Object Browser

La capture d’écran ci-dessus met en évidence les deux TextAnalyzer méthodes que l’exemple d’application appellera : NumConsonants (qui encapsule la méthode Java sous-jacente numConsonants ) et NumVowels (qui encapsule la méthode Java sous-jacente numVowels ).The above screenshot highlights the two TextAnalyzer methods that the example app will call: NumConsonants (which wraps the underlying Java numConsonants method), and NumVowels (which wraps the underlying Java numVowels method).

L’accès à. Types AARAccessing .AAR Types

Une fois que vous avez ajouté une référence à votre application qui pointe vers la bibliothèque de liaisons, vous pouvez accéder aux types Java dans le. AAR comme pour accéder aux types C# (grâce aux wrappers C#).After you add a reference to your app that points to the Binding Library, you can access Java types in the .AAR as you would access C# types (thanks to the C# wrappers). Le code d’application C# peut appeler TextAnalyzer des méthodes, comme illustré dans cet exemple :C# app code can call TextAnalyzer methods as illustrated in this example:

using Com.Xamarin.Textcounter;
...
int numVowels = TextCounter.NumVowels (myText);
int numConsonants = TextCounter.NumConsonants (myText);

Dans l’exemple ci-dessus, nous appelons des méthodes statiques dans la TextCounter classe.In the above example, we're calling static methods in the TextCounter class. Toutefois, vous pouvez également instancier des classes et appeler des méthodes d’instance.However, you can also instantiate classes and call instance methods. Par exemple, si votre. AAR encapsule une classe appelée Employee qui a la méthode d’instance buildFullName , vous pouvez l’instancier MyClass et l’utiliser comme indiqué ici :For example, if your .AAR wraps a class called Employee that has the instance method buildFullName, you can instantiate MyClass and use it as seen here:

var employee = new Com.MyCompany.MyProject.Employee();
var name = employee.BuildFullName ();

Les étapes suivantes ajoutent du code à l’application afin qu’il invite l’utilisateur à entrer du texte, utilise TextCounter pour analyser le texte, puis affiche les résultats.The following steps add code to the app so that it prompts the user for text, uses TextCounter to analyze the text, and then displays the results.

Remplacez la disposition BindingTest (main. AXML) par le code XML suivant.Replace the BindingTest layout (Main.axml) with the following XML. Cette disposition a un EditText pour l’entrée de texte et deux boutons pour initier des nombres de voyelles et de consonnes :This layout has an EditText for text input and two buttons for initiating vowel and consonant counts:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation             ="vertical"
    android:layout_width            ="fill_parent"
    android:layout_height           ="fill_parent" >
    <TextView
        android:text                ="Text to analyze:"
        android:textSize            ="24dp"
        android:layout_marginTop    ="30dp"
        android:layout_gravity      ="center"
        android:layout_width        ="wrap_content"
        android:layout_height       ="wrap_content" />
    <EditText
        android:id                  ="@+id/input"
        android:text                ="I can use my .AAR file from C#!"
        android:layout_marginTop    ="10dp"
        android:layout_gravity      ="center"
        android:layout_width        ="300dp"
        android:layout_height       ="wrap_content"/>
    <Button
        android:id                  ="@+id/vowels"
        android:layout_marginTop    ="30dp"
        android:layout_width        ="240dp"
        android:layout_height       ="wrap_content"
        android:layout_gravity      ="center"
        android:text                ="Count Vowels" />
    <Button
        android:id                  ="@+id/consonants"
        android:layout_width        ="240dp"
        android:layout_height       ="wrap_content"
        android:layout_gravity      ="center"
        android:text                ="Count Consonants" />
</LinearLayout>

Remplacez le contenu de MainActivity.cs par le code suivant.Replace the contents of MainActivity.cs with the following code. Comme illustré dans cet exemple, les gestionnaires d’événements de bouton appellent des méthodes encapsulées TextCounter qui résident dans le. AAR et utilisent des toasts pour afficher les résultats.As seen in this example, the button event handlers call wrapped TextCounter methods that reside in the .AAR and use toasts to display the results. Notez l' using instruction pour l’espace de noms de la bibliothèque liée (dans ce cas, Com.Xamarin.Textcounter ) :Notice the using statement for the namespace of the bound library (in this case, Com.Xamarin.Textcounter):

using System;
using Android.App;
using Android.Content;
using Android.Runtime;
using Android.Views;
using Android.Widget;
using Android.OS;
using Android.Views.InputMethods;
using Com.Xamarin.Textcounter;

namespace BindingTest
{
    [Activity(Label = "BindingTest", MainLauncher = true, Icon = "@drawable/icon")]
    public class MainActivity : Activity
    {
        InputMethodManager imm;

        protected override void OnCreate(Bundle bundle)
        {
            base.OnCreate(bundle);

            SetContentView(Resource.Layout.Main);

            imm = (InputMethodManager)GetSystemService(Context.InputMethodService);

            var vowelsBtn = FindViewById<Button>(Resource.Id.vowels);
            var consonBtn = FindViewById<Button>(Resource.Id.consonants);
            var edittext = FindViewById<EditText>(Resource.Id.input);
            edittext.InputType = Android.Text.InputTypes.TextVariationPassword;

            edittext.KeyPress += (sender, e) =>
            {
                imm.HideSoftInputFromWindow(edittext.WindowToken, HideSoftInputFlags.NotAlways);
                e.Handled = true;
            };

            vowelsBtn.Click += (sender, e) =>
            {
                int count = TextCounter.NumVowels(edittext.Text);
                string msg = count + " vowels found.";
                Toast.MakeText (this, msg, ToastLength.Short).Show ();
            };

            consonBtn.Click += (sender, e) =>
            {
                int count = TextCounter.NumConsonants(edittext.Text);
                string msg = count + " consonants found.";
                Toast.MakeText (this, msg, ToastLength.Short).Show ();
            };

        }
    }
}

Compilez et exécutez le projet BindingTest .Compile and run the BindingTest project. L’application démarre et présente la capture d’écran à gauche (le EditText est initialisé avec du texte, mais vous pouvez cliquer dessus pour le modifier).The app will start and present the screenshot on the left (the EditText is initialized with some text, but you can tap it to change it). Quand vous appuyez sur Count voyelles, un toast affiche le nombre de voyelles comme indiqué à droite :When you tap COUNT VOWELS, a toast displays the number of vowels as shown on the right:

Captures d’écran de l’exécution de BindingTestScreenshots from running BindingTest

Essayez de cliquer sur le bouton CONsonnes de nombre .Try tapping the COUNT CONSONANTS button. En outre, vous pouvez modifier la ligne de texte et appuyer à nouveau sur ces boutons pour tester différents nombres de voyelles et de consonnes.Also, you can modify the line of text and tap these buttons again to test for different vowel and consonant counts.

L’accès à. Ressources AARAccessing .AAR Resources

L’outil Xamarin fusionne les données R à partir du. AAR dans la classe de ressources de votre application.The Xamarin tooling merges the R data from the .AAR into your app's Resource class. Par conséquent, vous pouvez accéder à. AAR des ressources de votre disposition (et du code-behind) de la même façon que vous accédez aux ressources qui se trouvent dans le chemin d’accès aux ressources de votre projet.As a result, you can access .AAR resources from your layout (and from code-behind) in the same way as you would access resources that are in the Resources path of your project.

Pour accéder à une ressource d’image, vous utilisez le nom de la ressource. dessinable pour l’image compressée dans le. AAR.To access an image resource, you use the Resource.Drawable name for the image packed inside the .AAR. Par exemple, vous pouvez référencer image.png dans le. Fichier AAR à l’aide de @drawable/image :For example, you can reference image.png in the .AAR file by using @drawable/image:

<ImageView android:src="@drawable/image" ... />

Vous pouvez également accéder aux mises en page des ressources qui résident dans le. AAR.You can also access resource layouts that reside in the .AAR. Pour ce faire, vous utilisez le nom Resource. Layout pour la disposition compressée à l’intérieur du. AAR.To do this, you use the Resource.Layout name for the layout packaged inside the .AAR. Par exemple :For example:

var a = new ArrayAdapter<string>(this, Resource.Layout.row_layout, ...);

L’exemple textanalyzer. AAR contient un fichier image qui réside dans res/drawable/monkey.png.The textanalyzer.aar example contains an image file that resides at res/drawable/monkey.png. Nous allons accéder à cette ressource d’image et l’utiliser dans notre exemple d’application :Let's access this image resource and use it in our example app:

Modifiez la disposition de BindingTest (main. AXML) et ajoutez un ImageView à la fin du LinearLayout conteneur.Edit the BindingTest layout (Main.axml) and add an ImageView to the end of the LinearLayout container. Cela ImageView permet d’afficher l’image trouvée au niveau de la zone de ** @ dessin/singe**. cette image sera chargée à partir de la section des ressources de textanalyzer. AAR:This ImageView displays the image found at @drawable/monkey; this image will be loaded from the resource section of textanalyzer.aar:

    ...
    <ImageView
        android:src                 ="@drawable/monkey"
        android:layout_marginTop    ="40dp"
        android:layout_width        ="200dp"
        android:layout_height       ="200dp"
        android:layout_gravity      ="center" />

</LinearLayout>

Compilez et exécutez le projet BindingTest .Compile and run the BindingTest project. L’application démarre et présente la capture d’écran sur la gauche – lorsque vous appuyez sur compter les consonnes, les résultats s’affichent comme indiqué à droite :The app will start and present the screenshot on the left – when you tap COUNT CONSONANTS, the results are displayed as shown on the right:

BindingTest affichant le nombre de consonnesBindingTest displaying consonant count

Félicitations !Congratulations! Vous avez correctement lié une bibliothèque Java. AAR!You've successfully bound a Java library .AAR!

RésuméSummary

Dans cette procédure pas à pas, nous avons créé une bibliothèque de liaisons pour un. Fichier AAR, ajout de la bibliothèque de liaisons à une application de test minimale et exécution de l’application pour vérifier que notre code C# peut appeler du code Java résidant dans le. Fichier AAR.In this walkthrough, we created a Bindings Library for an .AAR file, added the Bindings Library to a minimal test app, and ran the app to verify that our C# code can call Java code residing in the .AAR file. En outre, nous avons étendu l’application pour accéder et afficher une ressource d’image qui réside dans le. Fichier AAR.In addition, we extended the app to access and display an image resource that resides in the .AAR file.