Перенос Xamarin.Essentials кода в .NET для Android и .NET для приложений iOS

Xamarin.Essentials является основной библиотекой почти для каждого приложения Xamarin, и ее функциональные возможности теперь являются частью пользовательского интерфейса мультиплатформенных приложений .NET (.NET MAUI).

Ниже описан процесс использования .NET MAUIсобственных функций устройства, ранее известных как Xamarin.Essentials.NET для Android или .NET для приложения iOS:

1. Xamarin.Essentials Удалите пакет NuGet из приложения .NET для Android или .NET для iOS.
2. Задайте для свойства true сборки $(UseMauiEssentials) значение в файле проекта. Дополнительные сведения см. в разделе "Изменение файла проекта".
3. Инициализировать функциональные возможности "essentials" путем вызова Platform.Init метода. Дополнительные сведения см. в разделе "Инициализация платформы".
4. При необходимости выполните дополнительную настройку. Дополнительные сведения см. в разделе "Выполнение дополнительной настройки".
5. Добавьте директивы using для необходимых функций. Дополнительные сведения см. в разделе "Добавление директив using".

Внимание

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

Изменение файла проекта

Чтобы использовать .NET MAUIсобственные функции устройств в приложении .NET для Android или .NET для iOS, измените файл проекта и задайте $(UseMauiEssentials) для свойства сборки значение true.

Android

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>
    ...
    <UseMauiEssentials>true</UseMauiEssentials>
  </PropertyGroup>
</Project>

iOS

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-ios</TargetFramework>
    ...
    <UseMauiEssentials>true</UseMauiEssentials>
  </PropertyGroup>
</Project>

Инициализация платформы

Android

В любом Activity запущенном методе необходимо вызвать Platform.Init метод, который находится в Microsoft.Maui.ApplicationModel пространстве имен из OnCreate метода:

using Android.Content.PM;
using Android.Runtime;
using Microsoft.Maui.ApplicationModel;

namespace MyAndroidApp;

[Activity(Label = "@string/app_name", MainLauncher = true)]
public class MainActivity : Activity
{
    protected override async void OnCreate(Bundle? savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
        Platform.Init(this, savedInstanceState);
        // ...
    }
}

Метод Platform.Init требует аргумента Application или Activity аргумента и аргумента Bundle .

iOS

AppDelegate В классе необходимо вызвать Platform.Init метод, который находится в Microsoft.Maui.ApplicationModel пространстве имен из FinishedLaunching метода:

using Microsoft.Maui.ApplicationModel;

namespace MyiOSApp;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override UIWindow? Window
    {
        get;
        set;
    }

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
    {
        // create a new window instance based on the screen size
        Window = new UIWindow(UIScreen.MainScreen.Bounds);

        // create a UIViewController with a single UILabel
        var vc = new UIViewController();
        // ...
        Window.RootViewController = vc;

        Platform.Init(() => vc);

        // make the window visible
        Window.MakeKeyAndVisible();

        return true;
    }
}

Для Platform.Init метода требуется Func<UIKit.UIViewController аргумент.

Примечание.

При необходимости можно получить текущий UIViewController объект, вызвав Platform.GetCurrentUIViewController метод.

Выполнение дополнительной настройки

Статический Platform класс содержит вспомогательные средства для конкретной платформы.

Android

Элемент	Характер использования
ActivityStateChanged	Событие, возникающее при изменении состояния действия.
AppContext	Свойство, которое получает Context объект, представляющий текущий контекст приложения.
CurrentActivity	Свойство, которое получает текущий Activity объект, представляющий текущее действие.
Intent	Статический класс, содержащий ActionAppAction строку, которая является идентификатором, Intent используемым действиями приложения.
OnNewIntent	Intent Передайте из переопределенного метода действия при вызове действия приложения.
OnResume	Activity Передайте из переопределенного метода действия, когда Activity возобновляется в рамках вызова действия приложения.
OnRequestPermissionsResult	Передача результатов запроса разрешений из переопределенного метода действия для обработки внутренних запросов разрешений.
WaitForActivityAsync	Activity Дождитесь создания или станут активными.

Чтобы получить доступ к текущему Context или Activity работающему приложению, выполните следующие действия.

var context = Platform.AppContext;

// Current Activity or null if not initialized or not started.
var activity = Platform.CurrentActivity;

Если есть ситуация, когда Activity требуется, но приложение не полностью запущено, вызовите WaitForActivityAsync метод:

var activity = await Platform.WaitForActivityAsync();

Чтобы обрабатывать запросы разрешений среды выполнения, переопределите OnRequestPermissionsResult метод в каждом Activity и вызовите Platform.OnRequestPermissionsResult метод из него:

public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Permission[] grantResults)
{
    Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);
    base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
}

Помимо получения текущего Activity, можно также зарегистрировать для событий жизненного цикла:

protected override void OnCreate(Bundle bundle)
{
    base.OnCreate(bundle);
    Platform.Init(this, bundle);
    Platform.ActivityStateChanged += Platform_ActivityStateChanged;
}

protected override void OnDestroy()
{
    base.OnDestroy();
    Platform.ActivityStateChanged -= Platform_ActivityStateChanged;
}

void Platform_ActivityStateChanged(object sender, ActivityStateChangedEventArgs e) =>
    Toast.MakeText(this, e.State.ToString(), ToastLength.Short).Show();

Состояния действия:

• Создание
• Возобновлено
• Приостановлен
• Уничтожаются
• SaveInstanceState
• Запуск
• Остановлено

iOS

Способ	Характер использования
ContinueUserActivity	Сообщает приложению, что есть данные, связанные с продолжением задачи, указанной NSUserActivity в качестве объекта, а затем возвращает, продолжает ли приложение действие.
GetCurrentUIViewController	Возвращает текущий контроллер представления. Этот метод возвращается null , если не удается обнаружить UIViewControllerобъект.
OpenUrl	Открывает указанный URI для запуска потока проверки подлинности.
PerformActionForShortcutItem	Вызывает действие, соответствующее выбранному AppAction пользователем.

Например, чтобы обработать действия приложения, переопределите PerformActionForShortcutItem метод в AppDelegate классе и вызовите Platform.PerformActionForShortcutItem из него метод:

public override void PerformActionForShortcutItem(UIApplication application, UIApplicationShortcutItem shortcutItem, UIOperationHandler completionHandler)
{
    Platform.PerformActionForShortcutItem(application, shortcutItem, completionHandler);
}

Добавьте директивы using.

Неявные global using директивы для .NET для iOS и .NET для Android не включают пространства имен для .NET MAUIсобственных функций устройств. using Поэтому директивы пространства имен должны быть заменены using директивами для Xamarin.Essentials пространства имен, содержащего необходимые функциональные возможности:

Пространство имен	Характер использования
Microsoft.Maui.ApplicationModel	Функции модели приложений, включая действия приложения, разрешения и отслеживание версий.
Microsoft.Maui.ApplicationModel.Communication	Функции коммуникации, включая контакты, электронную почту и сеть.
Microsoft.Maui.Devices	Функциональные возможности устройств, включая батарею, датчики, фонарик и хаптичную обратную связь.
Microsoft.Maui.Media	Функции мультимедиа, включая выбор мультимедиа и текст в речь.
Microsoft.Maui.ApplicationModel.DataTransfer	Совместное использование функций, включая буфер обмена и общий доступ к файлам.
Microsoft.Maui.Storage	служба хранилища функциональные возможности, включая выбор файлов и безопасное хранилище.

Дополнительные сведения о функциональных возможностях в каждом пространстве имен см. в разделе "Интеграция платформы".