Прочитать на английском

Поделиться через

Начало работы с машинной библиотекой взаимодействия

  • Статья

В этой статье описывается, как приступить к работе с машинной библиотекой с помощью Maui.NativeLibraryInterop, чтобы упростить настройку.

Эти инструкции описывают основные шаги, ключевые точки принятия решений и примеры создания привязок с помощью взаимодействия с машинной библиотекой. Дополнительные рекомендации по конкретным API и реализации см. в документации по собственным пакетам SDK и библиотекам.

Необходимые компоненты

Установка необходимых компонентов:

Примечание

Можно установить пакет SDK для Android и (или) средства командной строки Xcode в автономном режиме. Однако установка средств командной строки Xcode обычно обрабатывается с помощью Xcode. Аналогичным образом установка пакета SDK для Android обычно обрабатывается с помощью Android Studio и (или) расширения VS Code ДЛЯ .NET MAUI в документации по началу работы с .NET MAUI.

Создание новой привязки

Самый простой способ приступить к созданию новой привязки — клонирование шаблона в репозитории Maui.NativeLibraryInterop и внесение изменений. Чтобы лучше понять, как в настоящее время настроен Maui.NativeLibraryInterop, см. дополнительные сведения в документации по обзору.

Настройка библиотек привязки .NET

Шаблон включает начальный .NET для Android и .NET для библиотек привязки iOS.

Обновите библиотеки привязки, чтобы отразить целевые платформы и версию .NET при необходимости в приложении .NET.

Примечание

Например, если вы стремитесь создать только привязку iOS с помощью .NET 9, можно:

  1. Удаление библиотеки привязки Android в шаблоне/android/NewBinding.Android.Binding и
  2. Обновите целевую платформу в шаблоне/macios/NewBinding.MaciOS.Binding/NewBinding.MaciOS.Binding.csproj , чтобы иметь значение net9.0-ios.

Настройка собственных проектов и библиотек оболочки

Шаблон также включает начальные проекты Android Studio и проекты Xcode.

Обновите собственные проекты, чтобы отразить целевые платформы и версии, необходимые в приложении .NET, и включите собственные библиотеки, интересующие вас, выполните следующие действия.

Настройка: iOS и Mac Catalyst

Проект Xcode находится в шаблоне/macios/native/NewBinding.

Обновите проект Xcode, чтобы отразить целевые платформы и версии, поддерживаемые в приложении .NET. В проекте Xcode щелкните платформу верхнего уровня и в > цели":

  1. При необходимости добавьте или удалите все назначения поддержки .
  2. При необходимости настройте версию iOS.

Введите собственную библиотеку для iOS и (или) MacCatalyst в проект Xcode, используя любой метод, лучший для вашей библиотеки и ваших потребностей (например, CocoaPods, Swift диспетчер пакетов).

Настройка: Android

Проект Android Studio находится в шаблоне или android/native.

Обновите проект Android Studio, чтобы отразить целевые версии, поддерживаемые в приложении .NET.

  1. Перейдите к файлу build.gradle.kts (:app)
  2. compileSdk Обновление версии по мере необходимости

Перенос собственной библиотеки Android с помощью gradle

  1. Добавьте зависимость пакета в блок зависимостей файла build.gradle.kts (:app ).
  2. Добавьте репозиторий dependencyResolutionManagementrepositories в блок в файле settings.gradle.kts .
  3. Синхронизация проекта с файлами gradle (с помощью кнопки в правом верхнем углу Android Studio).

Создание интерфейса API

Создайте интерфейс API между собственными проектами и проектами привязки .NET, выполнив следующие действия.

Определение API: iOS и Mac Catalyst

На собственной стороне сделайте обновления в шаблоне/macios/native/NewBinding/NewBinding/DotnetNewBinding.swift:

  1. Добавьте инструкцию импорта для импорта только что добавленной собственной библиотеки.
  2. Напишите определения API для api-интерфейсов собственной библиотеки, интересующих вас.
  3. Убедитесь, что проект Xcode успешно выполняет сборку, и вы удовлетворены API.

Вернитесь на сторону .NET, теперь мы готовы взаимодействовать с собственной библиотекой:

  1. Запустите dotnet build из шаблона/macios/NewBinding.MaciOS.Binding , чтобы проверить, что все подключено правильно и хорошо.
  2. Используйте программу Objective Sharpie для создания привязок C# для обновлений Swift API.
    1. Перейдите к разделу template/macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework в папке вывода проектов привязки MaciOS.
    2. Запустите sharpie xcode -sdks, чтобы получить список допустимых значений целевого пакета SDK для команды bind. Выберите значение, которое соответствует платформе и версии, которую вы используете для следующей команды, например iphoneos18.0.
    3. Запустите sharpie bind против файлов заголовков в xcframework, который был создан проектом привязки. 
      sharpie bind --output=sharpie-out --namespace=NewBindingMaciOS --sdk=iphoneos18.0 --scope=Headers Headers/NewBinding-Swift.h
    4. Обновите содержимое шаблона /macios/NewBinding.MaciOS.Binding/ApiDefinition.cs, заменив его содержимым шаблона /macios/NewBinding.MaciOS.Binding/bin/Debug/net9.0-ios/NewBinding.MaciOS.Binding.resources/NewBindingiOS.xcframework/ios-arm64/NewBinding.framework/sharpie-out/ApiDefinitions.cs и внесите корректировки по мере необходимости (например, именование).
    5. Запустите dotnet build из шаблона/macios/NewBinding.MaciOS.Binding еще раз.

Также см. документацию по objective-sharpie, чтобы узнать больше об этом инструменте.

Определение API: Android

На стороне нативного кода внесите обновления в шаблон /android/native/newbinding/src/main/java/com/example/newbinding/DotnetNewBinding.java:

  1. Добавьте инструкцию импорта для импорта только что добавленной собственной библиотеки.
  2. Напишите определения API для api-интерфейсов собственной библиотеки, интересующих вас.
  3. Убедитесь, что проект Android Studio успешно выполняет сборку, и вы удовлетворены API.

Вернитесь на сторону .NET, теперь мы готовы взаимодействовать с собственной библиотекой:

  1. Запустите dotnet build из шаблона/android/NewBinding.Android.Binding , чтобы проверить, что все подключено правильно и хорошо. (Примечание. Для этого шага потребуется установить JDK 17)
  2. Ссылайтесь на все зависимости привязки Android, добавив элемент @(AndroidMavenLibrary) для шаблона/sample/MauiSample.csproj для каждой зависимости maven, привязанной к собственному проекту Android. Это позволит включить проверку зависимостей Java в вашем проекте и приведет к тому, что последующие сборки будут выдавать предупреждения или ошибки при отсутствующих зависимостях. Эти предупреждения и ошибки можно устранить, добавив элементы @(AndroidMavenLibrary) или @(PackageReference), как предложено, чтобы удовлетворить цепочку зависимостей Java для собственной библиотеки, которую вы привязываете. Примечание. Зависимости gradle/maven часто должны быть явно указаны, так как они не включаются в вашу библиотеку автоматически.
XML 
<ItemGroup Condition="$(TargetFramework.Contains('android'))">
    <AndroidMavenLibrary Include="{DependencyGroupId}:{DependencyName}" Version="{DependencyVersion}" Bind="false" />
</ItemGroup>

Дополнительные сведения об этом процессе см. в документации AndroidMavenLibrary и проверке зависимостей Java.

Примечание

Класс заполнителя DotnetNewBinding можно переименовать, чтобы лучше отразить оболочку собственной библиотеки. Дополнительные примеры и советы по написанию определений API см. в разделе ниже: Изменение существующей привязки.

Использование API в приложении .NET

Шаблон включает пример приложения .NET MAUI в шаблоне/образце/MauiSample, который ссылается на проекты привязки .NET и делает собственные библиотеки немедленно готовыми к использованию!

Если вы заинтересованы в использовании собственных приложений .NET MAUI, .NET для Android, .NET для iOS и /или .NET для приложений Mac Catalyst, вы можете сделать это, изменив файлы проекта приложения .NET, чтобы ссылаться на библиотеки привязки:

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

Изменение существующей привязки

Если существующая область API не предоставляет функциональные возможности, необходимые в собственном проекте, пришло время внести собственные изменения!

IOS и Mac Catalyst

В проекте Xcode вы найдете один или несколько файлов Swift, определяющих область общедоступного API для привязки. Например, register метод для обмена сообщениями Firebase определяется следующим образом:

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

Примечание

Собственные типы API-оболочки, которые будут использоваться привязкой .NET, должны быть объявлены как public и должны быть помечены и @objc(NameOfType) методы также должны publicбыть помечены, а также может воспользоваться аналогичными заметками @objc(methodName:parameter1:) , в которых указано имя и параметры, которые помогают повлиять на привязку, с которой будет генерироваться цель sharpie.

В этом методе видно, что область общедоступного API использует только типы, о которых уже известно .NET для iOS: NSData, StringNSError и обратном вызове.

Firebase.MaciOS.Binding В проекте файл ApiDefinitions.cs содержит определение привязки для этого СОБСТВЕННОго API-оболочки:

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

Предположим, что вы хотите добавить метод для отмены регистрации. Код Swift будет выглядеть примерно так:

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

Вторая половина будет обновлять файл ApiDefinitions.cs в проекте привязки, чтобы предоставить этот новый метод. Это можно сделать двумя способами:

  1. Можно вручную добавить обязательный код.
  2. После создания проекта привязки вы можете запустить инструмент objective sharpie для создания файла ApiDefinitions.cs. Вы можете попытаться найти соответствующие изменения из этого файла и скопировать их вручную или попытаться скопировать по всему файлу и посмотреть на дифф, чтобы найти нужную часть.

В этом случае изменения в ApiDefinitions.cs будут следующими:

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

После внесения этих изменений можно перестроить проект привязки, а новый API будет готов к использованию из проекта .NET MAUI.

Примечание

Проекты привязки для Mac/iOS не используют исходные генераторы, поэтому система проектов и intellisense могут не знать о новом API, пока не перестроили проект привязки, и перезагрузили решение, чтобы ссылка на проект взяла новую сборку. Проект приложения по-прежнему должен компилироваться независимо от ошибок intellisense.

Android

В проекте Android Studio вы найдете каталог модуля, содержащий java-файл, определяющий область общедоступного API для привязки. Например, initialize метод для Facebook определяется следующим образом:

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

    // ...
}

В этом методе видно, что область общедоступного API использует только типы, о которых уже известно .NET для Android: Activity и Boolean.

В проекте Facebook.Android.Binding файл Transforms/Metadata.xml содержит только некоторые xml, чтобы описать сопоставление имени пакета Java (com.microsoft.mauifacebook) с более понятным пространствомFacebook имен C#. Как правило, привязки android являются более "автоматическими", чем Mac/iOS на данный момент, и вам редко нужно вносить изменения в эти файлы преобразования.

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

Предположим, вы хотите добавить метод для ведения журнала события. Код java будет выглядеть примерно так:

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

Из этого простого изменения проект привязки не требует обновлений для преобразования или Metadata.xml или других файлов. Вы можете просто перестроить проект привязки, и новый API будет готов к использованию из проекта .NET MAUI.

Примечание

Проекты привязки для Android не используют генераторы источников, поэтому система проектов и intellisense могут не знать о новом API, пока не перестроили проект привязки и перезагрузили решение, чтобы ссылка на проект взяла новую сборку. Проект приложения по-прежнему должен компилироваться независимо от ошибок intellisense.