Delen via

Aan de slag met Native Library Interop

  • Artikel

In dit artikel wordt beschreven hoe u aan de slag gaat met Native Library Interop met behulp van Maui.NativeLibraryInterop om de installatie te vereenvoudigen.

Deze instructies geven een overzicht van de basisstappen, belangrijke beslissingspunten en leidende voorbeelden voor het maken van bindingen via interactie met inheemse bibliotheken. Raadpleeg de documentatie voor de systeemeigen SDK's en bibliotheken die van belang zijn voor meer informatie over specifieke API's en implementatiedetails.

Voorwaarden

Installatievereisten:

Notitie

Het is mogelijk om de Android SDK en/of de Xcode-opdrachtregelprogramma's op een zelfstandige manier te installeren. De installatie van de Xcode opdrachtregelprogramma's wordt meestal afgehandeld via Xcode. Op dezelfde manier wordt Android SDK installatie doorgaans afgehandeld via Android Studio en/of de .NET MAUI VS Code Extension volgens de .NET MAUI Getting Started documentatie.

Een nieuwe binding maken

De eenvoudigste manier om aan de slag te gaan met het maken van een nieuwe binding is door de sjabloon te klonen in de Tenant.NativeLibraryInterop opslagplaats en daar wijzigingen aan te brengen. Lees meer in de overzichtsdocumentatievoor een beter inzicht in de volledige omvang van de configuratie van Maui.NativeLibraryInterop.

De .NET-bindingsbibliotheken instellen

De -sjabloon bevat starter .NET voor Android- en .NET-bindingsbibliotheken voor iOS.

Werk de bindingsbibliotheken bij zodat deze overeenkomen met de doelplatforms en de .NET-versie, indien nodig in uw .NET-app.

Notitie

Als u bijvoorbeeld alleen een iOS-binding wilt maken met .NET 9, kunt u het volgende doen:

  1. Verwijder de Android-bindingsbibliotheek op template/android/NewBinding.Android.Bindingen
  2. Werk het doelframework in template/macios/NewBinding.MaciOS.Binding/NewBinding.MaciOS.Binding.csproj bij zodat het is ingesteld op net9.0-ios.

De systeemeigen wrapperprojecten en -bibliotheken instellen

De sjabloon bevat ook starter Android Studio-projecten en Xcode-projecten.

Werk de systeemeigen projecten zo nodig bij om de doelplatforms en versies in uw .NET-app weer te geven en neem de systeemeigen bibliotheken op die interessant zijn voor de volgende stappen.

Installatie: iOS & Mac Catalyst

Het Xcode-project bevindt zich op sjabloon/macios/native/NewBinding.

Werk het Xcode-project bij om de doelplatforms en versies weer te geven zoals ondersteund in uw .NET-app. Klik in het Xcode-project op het framework op het hoogste niveau en klik in Doelen > Algemeen:

  1. Voeg indien nodig ondersteuningsbestemmingen toe of verwijder ze.
  2. Pas de iOS-versie indien nodig aan.

Breng de systeemeigen bibliotheek voor iOS en/of MacCatalyst in uw Xcode-project, door de methode die het beste werkt voor uw bibliotheek en uw behoeften (bijvoorbeeld CocoaPods, Swift Package Manager).

Installatie: Android

Het Android Studio-project bevindt zich op sjabloon/android/native.

Werk het Android Studio-project bij om de doelversies weer te geven die worden ondersteund in uw .NET-app.

  1. Navigeer naar het bestand build.gradle.kts (:app)
  2. De compileSdk-versie indien nodig bijwerken

Breng de systeemeigen Android-bibliotheek via gradle in

  1. Voeg de pakketafhankelijkheid toe aan het afhankelijkhedenblok van het bestand build.gradle.kts (:app).
  2. Voeg de opslagplaats toe aan het dependencyResolutionManagementrepositories blok in het bestand settings.gradle.kts.
  3. Synchroniseer het project met gradle-bestanden (via de knop in de rechterbovenhoek van Android Studio).

De API-interface maken

Maak de API-interface tussen uw systeemeigen projecten en uw .NET-bindingsprojecten met de volgende stappen.

API-definitie: iOS & Mac Catalyst

Breng aan de native zijde updates aan in template/macios/native/NewBinding/NewBinding/DotnetNewBinding.swift:

  1. Voeg een importinstructie toe om de systeemeigen bibliotheek te importeren die u zojuist hebt toegevoegd.
  2. Schrijf de API-definities voor de systeemeigen bibliotheek-API's die van belang zijn.
  3. Zorg ervoor dat het Xcode-project correct wordt gebouwd en dat u tevreden bent met de API's.

Aan de .NET-kant zijn we nu klaar om te interageren met de systeemeigen bibliotheek.

  1. Voer dotnet build uit van het sjabloon /macios/NewBinding.MaciOS.Binding om te testen of alles correct is verbonden en klaar voor gebruik.
  2. Gebruik objective sharpie om de C#-bindingen te genereren voor uw Swift API-updates:
    1. Navigeer naar template/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework in de uitvoermap MaciOS-bindingsprojecten.
    2. Voer sharpie xcode -sdks uit om een lijst met geldige doel-SDK-waarden op te halen voor de bindingsopdracht. Selecteer de waarde die overeenkomt met het platform en de versie die u wilt gebruiken met de volgende opdracht, bijvoorbeeld iphoneos18.0.
    3. Voer sharpie bind uit op de headerbestanden in het xcframework dat door het bindingsproject is gemaakt: 
      sharpie bind --output=sharpie-out --namespace=NewBindingMaciOS --sdk=iphoneos18.0 --scope=Headers Headers/NewBinding-Swift.h
    4. Werk de inhoud van template/macios/NewBinding.MaciOS.Binding/ApiDefinition.cs bij door deze te vervangen door de inhoud van template/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework/sharpie-out/ApiDefinitions.cs en naar wens aanpassen (bijvoorbeeld naamgeving).
    5. Voer dotnet build opnieuw uit vanuit template/macios/NewBinding.MaciOS.Binding.

Zie ook de documentatie objective-sharpie voor meer informatie over dit hulpprogramma.

API-definitie: Android

Breng aan de systeemeigen kant updates aan in template/android/native/newbinding/src/main/java/com/example/newbinding/DotnetNewBinding.java:

  1. Voeg een importinstructie toe om de systeemeigen bibliotheek te importeren die u zojuist hebt toegevoegd.
  2. Schrijf de API-definities voor de systeemeigen bibliotheken die van belang zijn.
  3. Zorg ervoor dat het Android Studio-project correct wordt gebouwd en dat u tevreden bent met de API's.

Aan de .NET-kant zijn we nu klaar om te interoperen met de systeemeigen bibliotheek.

  1. Voer dotnet build uit vanaf template/android/NewBinding.Android.Binding om te testen of alles correct is aangesloten en goed is om te gaan. (Opmerking: voor deze stap moet JDK 17 zijn geïnstalleerd)
  2. Verwijs naar eventuele Android-bindingsafhankelijkheden door een @(AndroidMavenLibrary) item toe te voegen aan template/sample/MauiSample.csproj voor elke Maven-afhankelijkheid die is gebonden aan uw systeemeigen Android-project. Dit zal verificatie van Java-afhankelijkheden voor uw project inschakelen en ervoor zorgen dat volgende builds waarschuwingen of fouten veroorzaken voor ontbrekende afhankelijkheden. U kunt deze waarschuwingen/fouten oplossen door @(AndroidMavenLibrary) of @(PackageReference) elementen toe te voegen zoals wordt voorgesteld om te voldoen aan de java-afhankelijkheidsketen voor de systeemeigen bibliotheek die u bindt. (Opmerking: de gradle-/maven-afhankelijkheden moeten vaak expliciet worden verwezen, omdat ze niet automatisch worden gebundeld in uw bibliotheek.)
<ItemGroup Condition="$(TargetFramework.Contains('android'))">
    <AndroidMavenLibrary Include="{DependencyGroupId}:{DependencyName}" Version="{DependencyVersion}" Bind="false" />
</ItemGroup>

Zie ook de AndroidMavenLibrary-verwijzing en Java-afhankelijkheidsverificatie documentatie voor meer informatie over dit proces.

Notitie

U kunt de naam van de tijdelijke aanduiding DotnetNewBinding klasse wijzigen zodat deze beter overeenkomt met de systeemeigen bibliotheek die wordt verpakt. Lees meer in de onderstaande sectie voor meer voorbeelden en tips voor het schrijven van de API-definities: Een bestaande binding wijzigen.

De API's gebruiken in uw .NET-app

De sjabloon bevat een .NET MAUI-voorbeeld-app op template/sample/MauiSample-, die verwijst naar de .NET-bindingsprojecten en de systeemeigen bibliotheken onmiddellijk klaar maakt voor gebruik!

Als u geïnteresseerd bent in het gebruik van uw eigen .NET ADVISOR-, .NET voor Android-, .NET voor iOS- en/of .NET voor Mac Catalyst-apps, kunt u dit echter doen door uw .NET-app-projectbestanden te wijzigen om te verwijzen naar de bindingsbibliotheken:

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

Een bestaande binding wijzigen

Als de bestaande API-surface de functionaliteit die u nodig hebt niet beschikbaar maakt in uw eigen project, is het tijd om uw eigen wijzigingen aan te brengen.

iOS & Mac Catalyst

In het Xcode-project vindt u een of meer Swift-bestanden die het openbare API-oppervlak voor de binding definiëren. De register-methode voor Firebase Messaging wordt bijvoorbeeld gedefinieerd als:

@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?)
        })
    }
    // ...
}

Notitie

Systeemeigen wrapper-API-typen die door de .NET-binding worden gebruikt, moeten worden gedeclareerd als public en moeten worden geannoteerd met @objc(NameOfType); methoden moeten ook publiczijn en kunnen ook profiteren van vergelijkbare annotaties @objc(methodName:parameter1:) waarin de naam en parameters worden opgegeven die de binding helpen beïnvloeden die Objective Sharpie zal genereren.

In deze methode ziet u dat het openbare API-oppervlak alleen gebruikmaakt van typen waarvan .NET voor iOS al op de hoogte is: NSData, String, NSError en een callback.

In het Firebase.MaciOS.Binding-project bevat het ApiDefinitions.cs-bestand de bindingsdefinitie voor deze systeemeigen wrapper-API:

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);
        // ...
    }

Stel dat u een methode wilt toevoegen om de registratie ongedaan te maken. De Swift-code ziet er ongeveer als volgt uit:

@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?)
    })
}

De andere helft is het bijwerken van het ApiDefinitions.cs bestand in het bindingsproject om deze nieuwe methode beschikbaar te maken. U kunt dit op twee manieren doen:

  1. U kunt de vereiste code handmatig toevoegen
  2. Nadat u het bindingsproject hebt gebouwd, kunt u het hulpprogramma objective sharpie uitvoeren om een ApiDefinitions.cs-bestand te genereren. U kunt proberen de relevante wijzigingen uit dit bestand te vinden en ze handmatig te kopiëren, of proberen het hele bestand te kopiëren en naar de diff te kijken om het gewenste deel te vinden.

In dit geval zijn de wijzigingen in ApiDefinitions.cs:

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

Zodra u deze wijzigingen hebt aangebracht, kunt u het bindingsproject opnieuw bouwen en kunt u de nieuwe API gebruiken vanuit uw .NET MAUI-project.

Notitie

Bindingsprojecten voor Mac/iOS maken geen gebruik van brongeneratoren, dus het projectsysteem en intellisense weten pas over de nieuwe API's als u het bindingsproject opnieuw hebt opgebouwd en de oplossing opnieuw hebt geladen, zodat de projectverwijzing de nieuwere assembly ophaalt. Uw app-project moet nog steeds worden gecompileerd, ongeacht intellisense-fouten.

Android

In het Android Studio-project vindt u een modulemap die een Java-bestand bevat dat het openbare API-oppervlak voor de binding definieert. De methode initialize voor Facebook wordt bijvoorbeeld gedefinieerd als hieronder:

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);
    }

    // ...
}

U kunt in deze methode zien dat het openbare API-oppervlak alleen gebruikmaakt van typen waarvan .NET voor Android al op de hoogte is: Activity en Boolean.

In het project Facebook.Android.Binding bevat het bestand Transforms/Metadata.xml slechts een xml om te beschrijven hoe de java-pakketnaam (com.microsoft.mauifacebook) wordt toegewezen aan een meer C#-beschrijvende naamruimte (Facebook). Over het algemeen zijn Android-bindingen op dit moment meer 'automatisch' dan Mac/iOS, en u moet zelden wijzigingen aanbrengen in deze transformatiebestanden.

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

Stel dat u een methode wilt toevoegen voor het registreren van een gebeurtenis. De Java-code ziet er ongeveer als volgt uit:

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

Bij deze eenvoudige wijziging vereist het bindingsproject geen updates voor de Transformaties/Metadata.xml of andere bestanden. U kunt gewoon het bindingsproject herbouwen en de nieuwe API kan worden gebruikt vanuit uw .NET MAUI-project.

Notitie

Bindingsprojecten voor Android maken geen gebruik van brongeneratoren, dus het projectsysteem en intellisense weten mogelijk pas over de nieuwe API's als u het bindingsproject opnieuw hebt opgebouwd en de oplossing opnieuw hebt geladen, zodat de projectverwijzing de nieuwere assembly ophaalt. Uw app-project moet nog steeds worden gecompileerd, ongeacht intellisense-fouten.