Bien démarrer avec Native Library Interop

Cet article explique comment démarrer avec Native Library Interop en utilisant Maui.NativeLibraryInterop pour simplifier la configuration.

Ces instructions fournissent les étapes de base, les points de décision clés et des exemples directeurs pour créer des liaisons via Native Library Interop. Pour obtenir de l’aide supplémentaire sur les API spécifiques et les détails d’implémentation, reportez-vous à la documentation relative aux bibliothèques et aux kits SDK natifs qui vous intéressent.

Prérequis

Installez les prérequis :

• .NET 9 SDK
• Charge de travail .NET MAUI (via Visual Studio ou CLI dotnet workload install maui)
• Android SDK
• Android Studio
• Objective-Sharpie (utilisé pour générer manuellement les API C#)
  • Xamarin.iOS (obligatoire pour qu’Objective Sharpie fonctionne)
• Visual Studio ou Visual Studio Code
• Xcode
• Xcode Command Line Tools (xcode-select --install)

Créer une liaison

Le moyen le plus simple de créer une liaison consiste à cloner le modèle dans le référentiel Maui.NativeLibraryInterop et à y apporter des modifications. Pour mieux comprendre l’étendue complète de la configuration actuelle de Maui.NativeLibraryInterop, consultez la documentation de présentation.

Configurer les bibliothèques de liaison .NET

Le modèle inclut des bibliothèques de liaison de démarrage .NET pour Android et .NET pour iOS.

Mettez à jour les bibliothèques de liaison pour refléter les plateformes cibles et la version de .NET nécessaires dans votre application .NET.

Configurer les bibliothèques et les projets wrapper natifs

Le modèle comprend également des projets Android Studio et des projets Xcode de démarrage.

Mettez à jour les projets natifs pour refléter les plateformes et versions cibles nécessaires dans votre application .NET, puis effectuez les étapes suivantes pour inclure les bibliothèques natives qui vous intéressent.

Configuration : iOS et Mac Catalyst

Le projet Xcode se trouve dans template/macios/native/NewBinding.

Mettez à jour le projet Xcode pour refléter les plateformes et versions cibles prises en charge dans votre application .NET. Dans le projet Xcode, cliquez sur l’infrastructure de niveau supérieur, puis, dans Targets > General :

1. Ajoutez/supprimez des destinations de support (Support Destinations) si nécessaire.
2. Ajustez la version d’iOS si nécessaire.

Intégrez la bibliothèque native pour iOS et/ou MacCatalyst à votre projet Xcode en utilisant la méthode la mieux adaptée à votre bibliothèque et à vos besoins (par exemple, CocoaPods, Swift Package Manager).

Configuration : Android

Le projet Android Studio se trouve dans template/android/native.

Mettez à jour le projet Android Studio pour refléter les versions cibles prises en charge dans votre application .NET.

1. Accédez au fichier build.gradle.kts (:app).
2. Mettez à jour la version de compileSdk si nécessaire.

Intégrer la bibliothèque native Android via Gradle

1. Ajoutez la dépendance de package dans le bloc de dépendances du fichier build.gradle.kts (:app).
2. Ajoutez le référentiel au bloc dependencyResolutionManagementrepositories dans le fichier settings.gradle.kts.
3. Synchronisez le projet avec les fichiers Gradle (à l’aide du bouton situé dans le coin supérieur droit d’Android Studio).

Créer l’interface d’API

Effectuez les étapes suivantes pour créer l’interface d’API entre vos projets natifs et vos projets de liaison .NET.

Définition d’API : iOS et Mac Catalyst

Côté natif, effectuez les mises à jour dans template/macios/native/NewBinding/NewBinding/DotnetNewBinding.swift :

1. Ajoutez une instruction import pour importer la bibliothèque native que vous venez d’ajouter.
2. Écrivez les définitions d’API pour les API de bibliothèque native qui vous intéressent.
3. Vérifiez que le projet Xcode est généré correctement et que les API vous conviennent.

De retour côté .NET, nous sommes maintenant prêts à interopérer avec la bibliothèque native :

1. Exécutez dotnet build à partir de template/macios/NewBinding.MaciOS.Binding pour vérifier que tout est correctement configuré et prêt à l’emploi.
2. Utilisez Objective-Sharpie pour générer les liaisons C# pour vos mises à jour d’API Swift :
   1. Naviguez vers template/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework dans le dossier de sortie de vos projets de liaison MaciOS.
   2. Exécutez sharpie xcode -sdks pour obtenir une liste des valeurs valides de SDK cible pour la commande bind. Sélectionnez la valeur correspondant à la plateforme et à la version que vous ciblez pour l’utiliser avec la commande suivante, par exemple iphoneos18.0.
   3. Exécutez sharpie bind contre les fichiers d'en-tête dans le xcframework créé par le projet de liaison :

      sharpie bind --output=sharpie-out --namespace=NewBindingMaciOS --sdk=iphoneos18.0 --scope=Headers Headers/NewBinding-Swift.h
      

   4. Mettre à jour le contenu de template/macios/NewBinding.MaciOS.Binding/ApiDefinition.cs en le remplaçant par le contenu de template/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework/sharpie-out/ApiDefinitions.cs et en apportant les modifications souhaitées (par exemple, le nommage).
   5. Exécutez à nouveau dotnet build à partir de template/macios/NewBinding.MaciOS.Binding.

Voir aussi la documentation objective-sharpie pour en savoir plus sur cet outil.

Définition d’API : Android

Du côté natif, effectuez des mises à jour dans template/android/native/newbinding/src/main/java/com/example/newbinding/DotnetNewBinding.java :

1. Ajoutez une instruction import pour importer la bibliothèque native que vous venez d’ajouter.
2. Écrivez les définitions d’API pour les API de bibliothèque native qui vous intéressent.
3. Vérifiez que le projet Android Studio est généré correctement et que les API vous conviennent.

De retour côté .NET, nous sommes maintenant prêts à interopérer avec la bibliothèque native :

1. Exécutez dotnet build à partir de template/android/NewBinding.Android.Binding pour vérifier que tout est correctement configuré et prêt à l’emploi. (Remarque : cette étape nécessite l’installation de JDK 17.)
2. Référencez toutes les dépendances Android en ajoutant un élément @(AndroidMavenLibrary) à template/sample/MauiSample.csproj pour chaque dépendance maven liée à votre projet Android natif. Cela activera la vérification des dépendances Java pour votre projet et fera en sorte que les builds suivants affichent des avertissements ou des erreurs en cas de dépendances manquantes. Vous pouvez corriger ces avertissements/erreurs en ajoutant les éléments @(AndroidMavenLibrary) ou @(PackageReference) comme suggéré afin de satisfaire la chaîne de dépendances Java pour la bibliothèque native que vous liez. (Remarque : les dépendances gradle/maven doivent souvent être référencées explicitement, car elles ne sont pas automatiquement incluses dans votre bibliothèque.)

<ItemGroup Condition="$(TargetFramework.Contains('android'))">
    <AndroidMavenLibrary Include="{DependencyGroupId}:{DependencyName}" Version="{DependencyVersion}" Bind="false" />
</ItemGroup>

Consultez également la documentation référence AndroidMavenLibrary et vérification des dépendances Java pour obtenir plus d’informations sur ce processus.

Consommer les API dans votre application .NET

Le modèle inclut un exemple d’application .NET MAUI dans template/sample/MauiSample qui fait référence aux projets de liaison .NET et rend les bibliothèques natives immédiatement prêtes à l’emploi.

Toutefois, si vous souhaitez utiliser vos propres applications .NET MAUI, .NET pour Android, .NET pour iOS et/ou .NET pour Mac Catalyst, vous devez modifier les fichiers de votre projet d’application .NET pour référencer les bibliothèques de liaison :

<!-- Reference to MaciOS Binding project -->
<ItemGroup Condition="$(TargetFramework.Contains('ios')) Or $(TargetFramework.Contains('maccatalyst'))">
    <ProjectReference Include="..\..\macios\NewBinding.MaciOS.Binding\NewBinding.MaciOS.Binding.csproj" />
</ItemGroup>

<!-- Reference to Android Binding project -->
<ItemGroup Condition="$(TargetFramework.Contains('android'))">
    <ProjectReference Include="..\..\android\NewBinding.Android.Binding\NewBinding.Android.Binding.csproj" />
</ItemGroup>

Modifier une liaison existante

Si la surface de l’API existante n’expose pas les fonctionnalités dont vous avez besoin dans votre projet, il est temps d’apporter vos propres modifications.

iOS et Mac Catalyst

Dans le projet Xcode, vous trouverez un ou plusieurs fichiers Swift qui définissent la surface d’API publique pour la liaison. Par exemple, la méthode register pour Firebase Messaging est définie comme suit :

@objc(MauiFIRMessaging)
public class MauiFIRMessaging : NSObject {

    @objc(register:completion:)
    public static func register(apnsToken: NSData, completion: @escaping (String?, NSError?) -> Void) {
        let data = Data(referencing: apnsToken);
        Messaging.messaging().apnsToken = data
        Messaging.messaging().token(completion: { fid, error in
            completion(fid, error as NSError?)
        })
    }
    // ...
}

Vous pouvez voir dans cette méthode que la surface d’API publique utilise uniquement les types que .NET pour iOS connaît déjà : NSData, String, NSError et un rappel.

Dans le projet Firebase.MaciOS.Binding, le fichier ApiDefinitions.cs contient la définition de la liaison pour cette API wrapper native :

using System;
using Foundation;

namespace Firebase
{
    // @interface MauiFIRMessaging : NSObject
    [BaseType (typeof(NSObject))]
    interface MauiFIRMessaging
    {
        [Static]
        [Export ("register:completion:")]
        [Async]
        void Register (NSData apnsToken, Action<string?, NSError?> completion);
        // ...
    }

Supposons que vous souhaitiez ajouter une méthode pour annuler l’inscription. Le code Swift ressemblerait à ceci :

@objc(unregister:)
public static func unregister(completion: @escaping (NSError?) -> Void) {
    // need delegate to watch for fcmToken updates
    Messaging.messaging().deleteToken(completion: { error in
        completion(error as NSError?)
    })
}

L’autre moitié consisterait à mettre à jour le fichier ApiDefinitions.cs dans le projet de liaison pour exposer cette nouvelle méthode. Il existe deux façons de procéder :

1. Vous pouvez ajouter manuellement le code requis.
2. Après avoir construit le projet de liaison, vous pouvez lancer l'outil objective sharpie pour générer un fichier ApiDefinitions.cs. Vous pouvez soit essayer de trouver les modifications pertinentes dans ce fichier et les copier manuellement, soit essayer de copier l’intégralité du fichier et d’examiner les différences pour trouver la partie dont vous avez besoin.

Dans ce cas, les modifications apportées à ApiDefinitions.cs sont les suivantes :

[Static]
[Export("unregister:")]
[Async]
void UnRegister(Action completion);

Après avoir apporté ces modifications, vous pouvez régénérer le projet de liaison. La nouvelle API est alors prête à être utilisée à partir de votre projet .NET MAUI.

Android

Dans le projet Android Studio, vous trouverez un répertoire de module contenant un fichier Java qui définit la surface d’API publique pour la liaison. Par exemple, la méthode initialize pour Facebook est définie comme suit :

package com.microsoft.mauifacebook;

import android.app.Activity;
import android.app.Application;
import android.os.Bundle;
import android.util.Log;

import com.facebook.LoggingBehavior;
import com.facebook.appevents.AppEventsLogger;

public class FacebookSdk {

    static AppEventsLogger _logger;

    public static void initialize(Activity activity, Boolean isDebug) {
        Application application = activity.getApplication();

        if (isDebug) {
            com.facebook.FacebookSdk.setIsDebugEnabled(true);
        }

        com.facebook.FacebookSdk.addLoggingBehavior(LoggingBehavior.APP_EVENTS);

        AppEventsLogger.activateApp(application);

        _logger = AppEventsLogger.newLogger(activity);
    }

    // ...
}

Vous pouvez voir dans cette méthode que la surface d’API publique utilise uniquement les types que .NET pour Android connaît déjà : Activity et Boolean.

Dans le projet Facebook.Android.Binding, le fichier Transforms/Metadata.xml contient uniquement du code XML pour décrire comment mapper le nom du package Java (com.microsoft.mauifacebook) à un espace de noms plus convivial en C# (Facebook). En règle générale, les liaisons Android sont plus « automatiques » que les liaisons Mac/iOS à ce stade et nécessitent rarement la modification des fichiers de transformation.

<metadata>
    <attr path="/api/package[@name='com.microsoft.mauifacebook']" name="managedName">Facebook</attr>
</metadata>

Supposons que vous souhaitiez ajouter une méthode pour journaliser un événement. Le code Java ressemblerait à ceci :

public static void logEvent(String eventName) {
    _logger.logEvent(eventName);
}

À partir de cette modification simple, le projet de liaison ne nécessite aucune mise à jour du fichier Transforms/Metadata.xml ou d’autres fichiers. Vous pouvez simplement régénérer le projet de liaison. La nouvelle API est alors prête à être utilisée à partir de votre projet .NET MAUI.