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:

• Sada .NET 8.0 SDK
• Úloha .NET MAUI (přes Visual Studio nebo CLI dotnet workload install maui)
• Android SDK
• Android Studio
• Objective-Sharpie (vyžaduje se pro automatické generová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 dependencyResolutionManagement repositories 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. V případě úspěchu byste měli vidět vygenerované vazby jazyka C# na adrese template/macios/native/NewBinding/bin/Release/net8.0-ios/sharpie/NewBinding/ApiDefinitions.cs.
2. Aktualizujte obsah šablony/macios/NewBinding.MaciOS.Binding/ApiDefinition.cs nahrazením obsahu šablony/macios/native/NewBinding/bin/Release/net8.0-ios/sharpie/NewBinding/ApiDefinitions.cs.
3. Znovu spusťte dotnet build příkaz template/macios/NewBinding.MaciOS.Binding .

Definice rozhraní API: Android

Na nativní straně proveďte aktualizace v šabloně/android/native/app/src/main/java/com/example/newbinding/DotnetNewBinding.java:

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. Odkazovat na všechny závislosti vazby Androidu přidáním následujícího kódu do šablony/sample/MauiSample.csproj pro každou závislost. Nahraďte {yourDependencyLibrary.aar} požadovaným souborem .aar pro závislost, kterou vytváříte vazbu. (Poznámka: Závislosti gradle/maven se často musí explicitně odkazovat, protože nejsou automaticky spojeny do vaší knihovny. Soubor build.gradle.kts je nakonfigurovaný tak, aby zkopíroval závislosti do složky bin/outputs/deps, na kterou můžete ve své aplikaci odkazovat).

<ItemGroup Condition="$(TargetFramework.Contains('android'))">
    <AndroidLibrary Include="..\android\native\newbinding\bin\Release\net8.0-android\outputs\deps\{yourDependencyLibrary.aar}">
        <Bind>false</Bind>
        <Visible>false</Visible>
    </AndroidLibrary>
</ItemGroup>

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. Když se projekt vazby sestaví, spustí se objective sharpie a vygeneruje se soubor ApiDefinitions.cs uvnitř nativní složky/macios/bin/sharpie (tato cesta se bude lišit v závislosti na projektu, na který samozřejmě pracujete). 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.