Začínáme s interoperabilitou nativní knihovny

Tento článek popisuje, jak začít pracovat s nativní knihovnou interop pomocí Maui.NativeLibraryInterop, aby se zjednodušilo nastavení.

Tyto pokyny popisují základní kroky, klíčové rozhodovací body a příklady pro vytváření vazeb prostřednictvím zprostředkovatele komunikace nativní knihovny. Další pokyny ke konkrétním rozhraním API a podrobnostem implementace najdete v dokumentaci k nativním sadám SDK a knihovnám, které zajímají.

Požadavky

Požadavky na instalaci:

• .NET 9 SDK
• Úloha .NET MAUI (přes Visual Studio nebo CLI dotnet workload install maui)
• Android SDK
• Android Studio
• Objective-Sharpie (používá se k ručnímu vygenerování rozhraní API jazyka C#)
  • Xamarin.iOS (vyžaduje se pro práci Objective-Sharpie)
• Visual Studio nebo Visual Studio Code
• Xcode
• Nástroje příkazového řádku Xcode (xcode-select --install)

Poznámka:

Sadu Android SDK nebo nástroje příkazového řádku Xcode je možné nainstalovat samostatně. Instalace nástrojů příkazového řádku Xcode se ale obvykle zpracovává prostřednictvím Xcode. Podobně se instalace sady Android SDK také obvykle zpracovává prostřednictvím Android Studia nebo rozšíření .NET MAUI VS Code podle dokumentace Začínáme s .NET MAUI.

Vytvoření nové vazby

Nejjednodušší způsob, jak začít s vytvořením nové vazby, je naklonováním šablony v úložišti Maui.NativeLibraryInterop a provedením změn odsud. Pokud chcete lépe porozumět celému rozsahu nastavení Maui.NativeLibraryInterop, přečtěte si další informace v přehledové dokumentaci.

Nastavení knihoven vazeb .NET

Šablona obsahuje úvodní .NET pro Android a .NET pro knihovny vazeb pro iOS.

Aktualizujte knihovny vazeb tak, aby odrážely cílové platformy a verzi .NET podle potřeby v aplikaci .NET.

Poznámka:

Například: Pokud chcete vytvořit pouze vazbu pro iOS pomocí .NET 9, můžete:

1. Odstraňte knihovnu vazeb pro Android na adrese template/android/NewBinding.Android.Binding a
2. Aktualizujte cílovou architekturu v šabloně/macios/NewBinding.MaciOS.Binding/NewBinding.MaciOS.Binding.csproj tak, aby byla nastavena na net9.0-ios.

Nastavení nativních projektů a knihoven obálky

Šablona obsahuje také počáteční projekty Android Studio a projekty Xcode.

Aktualizujte nativní projekty tak, aby odrážely cílové platformy a verze podle potřeby v aplikaci .NET a pomocí následujících kroků zahrňte nativní knihovny, které vás zajímají.

Nastavení: iOS & Mac Catalyst

Projekt Xcode se nachází na adrese template/macios/native/NewBinding.

Aktualizujte projekt Xcode tak, aby odrážel cílové platformy a verze podporované v aplikaci .NET. V projektu Xcode klikněte na architekturu nejvyšší úrovně a v části Cíle > Obecné:

1. Podle potřeby přidejte nebo odeberte všechny cíle podpory.
2. Podle potřeby upravte verzi iOSu.

Přineste do projektu Xcode nativní knihovnu pro iOS nebo MacCatalyst, a to prostřednictvím libovolné metody, která je pro vaši knihovnu nejvhodnější (např. CocoaPods, Swift Správce balíčků).

Nastavení: Android

Projekt Android Studio se nachází v šabloně, androidu nebo nativním prostředí.

Aktualizujte projekt android Studia tak, aby odrážel cílové verze podporované v aplikaci .NET.

1. Přejděte do souboru build.gradle.kts (:app).
2. Podle potřeby aktualizujte compileSdk verzi.

Přenesení nativní knihovny pro Android prostřednictvím gradle

1. Přidejte závislost balíčku do bloku závislostí souboru build.gradle.kts (:app).
2. Přidejte úložiště do dependencyResolutionManagementrepositories bloku v souboru settings.gradle.kts .
3. Synchronizujte projekt se soubory gradle (pomocí tlačítka v pravém horním rohu Android Studia).

Vytvoření rozhraní API

Pomocí následujícího postupu vytvořte rozhraní API mezi nativními projekty a projekty vazeb .NET.

Definice rozhraní API: iOS &Mac Catalyst

Na nativní straně proveďte aktualizace v šabloně/macios/native/NewBinding/NewBinding/DotnetNewBinding.swift:

1. Přidejte příkaz importu pro import nativní knihovny, kterou jste právě přidali.
2. Napište definice rozhraní API pro rozhraní API nativní knihovny, která jsou zajímavá.
3. Ujistěte se, že se projekt Xcode úspěšně sestaví a že jste spokojení s rozhraními API.

Zpátky na straně .NET jsme připraveni spolupracovat s nativní knihovnou:

1. Spusťte dotnet build ze šablony/macios/NewBinding.MaciOS.Binding a otestujte, že všechno je správně připojené a je dobré začít.
2. Pomocí objective sharpie vygenerujte vazby jazyka C# pro aktualizace rozhraní Swift API:
   1. Přejděte na template/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework ve výstupní složce projektů MaciOS.
   2. Spuštěním sharpie xcode -sdks získejte seznam platných hodnot cílové sady SDK pro příkaz bind. Vyberte hodnotu, která odpovídá platformě a verzi, kterou chcete použít s dalším příkazem, například iphoneos18.0.
   3. Spusťte sharpie bind na soubory hlaviček v xcframeworku vytvořeném v rámci projektu propojení:

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

   4. Aktualizujte obsah šablony /macios/NewBinding.MaciOS.Binding/ApiDefinition.cs nahrazením obsahem šablony /macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework/sharpie-out/ApiDefinitions.cs a upravte podle potřeby (např., pojmenování).
   5. Znovu spusťte dotnet build příkaz template/macios/NewBinding.MaciOS.Binding .

Další informace o tomto nástroji najdete také v dokumentaci objective-sharpie.

Definice rozhraní API: Android

Na nativní straně proveďte aktualizace v šabloně /android/native/newbinding/src/main/java/com/example/newbinding/DotnetNewBinding.java označené jako.

1. Přidejte příkaz importu pro import nativní knihovny, kterou jste právě přidali.
2. Napište definice rozhraní API pro rozhraní API nativní knihovny, která jsou zajímavá.
3. Ujistěte se, že se projekt Android Studio úspěšně sestaví a že jste spokojení s rozhraními API.

Zpátky na straně .NET jsme připraveni spolupracovat s nativní knihovnou:

1. Spusťte dotnet build ze šablony,android/NewBinding.Android.Binding a otestujte, že všechno je správně připojené a je dobré začít. (Poznámka: Tento krok bude vyžadovat, abyste měli nainstalovanou sadu JDK 17.
2. Odkazujte na všechny závislosti vazby Androidu tak, že přidáte položku @(AndroidMavenLibrary) do template/sample/MauiSample.csproj pro každou závislost mavenu, která je svázaná v nativním projektu Androidu. To umožní ověření závislostí v Javě pro váš projekt a následné sestavení způsobí, že v případě chybějících závislostí dojde k upozorněním nebo chybám sestavení. Tato upozornění nebo chyby můžete vyřešit přidáním prvků @(AndroidMavenLibrary) nebo @(PackageReference) podle návrhu pro splnění řetězce závislostí Java pro nativní knihovnu, na kterou vytváříte vazby. (Poznámka: Závislosti v Gradle/Maven je často třeba explicitně uvést, protože nejsou automaticky zahrnuty do vaší knihovny.)

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

Další informace o tomto procesu najdete také v referenčních informací k AndroidMavenLibrary a dokumentaci k ověřování závislostí v Javě.

Poznámka:

Zástupnou DotnetNewBinding třídu můžete přejmenovat, aby lépe odrážela zabalenou nativní knihovnu. Další příklady a tipy pro zápis definic rozhraní API najdete v následující části: Úprava existující vazby.

Využívání rozhraní API v aplikaci .NET

Šablona obsahuje ukázkovou aplikaci .NET MAUI na šabloně/sample/MauiSample, která odkazuje na projekty vazeb .NET a zpřístupňuje nativní knihovny okamžitě k použití.

Pokud vás zajímají vlastní aplikace .NET MAUI, .NET pro Android, .NET pro iOS a/nebo .NET for Mac Catalyst, můžete to ale udělat tak, že upravíte soubory projektu aplikace .NET tak, aby odkazy na knihovny vazeb odkazují:

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

Úprava existující vazby

Pokud stávající plocha rozhraní API nezpřístupňuje funkce, které potřebujete ve vlastním projektu, je čas provést vlastní úpravy.

iOS a Mac Catalyst

V projektu Xcode najdete jeden nebo více souborů Swiftu, které definují plochu veřejného rozhraní API pro vazbu. Například register metoda služby Firebase Messaging je definována takto:

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

Poznámka:

Nativní typy rozhraní API obálky, které budou používány vazbou .NET, musí být deklarovány jako public a musí být opatřeny poznámkami @objc(NameOfType) a také metody musí být publica mohou také těžit z podobných poznámek, @objc(methodName:parameter1:) kde jsou zadány názvy a parametry, které pomáhají ovlivnit vazbu, kterou cíl ostrostí vygeneruje.

V této metodě můžete vidět, že veřejná plocha rozhraní API používá pouze typy, o kterých už rozhraní .NET pro iOS ví: NSData, StringNSError a zpětné volání.

Firebase.MaciOS.Binding V projektu soubor ApiDefinitions.cs obsahuje definici vazby pro toto nativní obálkové rozhraní 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);
        // ...
    }

Řekněme, že chcete přidat metodu zrušení registrace. Kód Swiftu by vypadal přibližně takto:

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

Druhá polovina bude aktualizovat soubor ApiDefinitions.cs v projektu vazby tak, aby tuto novou metodu zpřístupnil. Existují dva způsoby, jak se k tomu můžete pustit:

1. Požadovaný kód můžete přidat ručně.
2. Po sestavení vazbového projektu můžete spustit nástroj objective sharpie a vygenerovat ApiDefinitions.cs soubor. Můžete se pokusit najít relevantní změny z tohoto souboru a zkopírovat je ručně, nebo zkopírovat celý soubor a podívat se na rozdíl, abyste našli požadovanou část.

V tomto případě by změny ApiDefinitions.cs byly:

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

Po provedení těchto změn můžete projekt Vazby znovu sestavit a nové rozhraní API bude připravené k použití z projektu .NET MAUI.

Poznámka:

Vazbové projekty pro Mac/iOS nepoužívají zdrojové generátory, takže systém projektů a intellisense nemusí vědět o novém rozhraní API, dokud projekt vazby znovu nevystavíte, a znovu načtěte řešení tak, aby odkaz na projekt shromažďoval novější sestavení. Projekt aplikace by se měl stále kompilovat bez ohledu na chyby intellisense.

Android

V projektu Android Studio najdete adresář modulu, který obsahuje soubor Java, který definuje plochu veřejného rozhraní API pro vazbu. initialize Například metoda pro Facebook je definována takto:

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

    // ...
}

V této metodě vidíte, že veřejná plocha rozhraní API používá pouze typy, o kterých rozhraní .NET pro Android již umí: Activity a Boolean.

V projektu Facebook.Android.Binding soubor Transforms/Metadata.xml obsahuje pouze kód XML, který popisuje, jak mapovat název balíčku Java (com.microsoft.mauifacebook) na popisnější obor názvů jazyka C#.Facebook Obecně platí, že vazby androidu jsou v tuto chvíli "automatické" než Mac/iOS a vy byste v těchto transformovaných souborech měli provádět změny jen zřídka.

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

Řekněme, že chcete přidat metodu protokolování události. Kód Java by vypadal přibližně takto:

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

Z této jednoduché změny projekt vazby nevyžaduje žádné aktualizace transformací/Metadata.xml ani jiných souborů. Projekt vazby můžete jednoduše znovu sestavit a nové rozhraní API bude připravené k použití z projektu .NET MAUI.

Poznámka:

Vazbové projekty pro Android nepoužívají zdrojové generátory, takže systém projektů a intellisense nemusí vědět o novém rozhraní API, dokud projekt vazby znovu nevystavíte, a znovu nenačte řešení tak, aby odkaz na projekt shromažďoval novější sestavení. Projekt aplikace by se měl stále kompilovat bez ohledu na chyby intellisense.