Migrowanie Xamarin.Essentials kodu na platformie .NET dla systemów Android i .NET dla aplikacji systemu iOS

Xamarin.Essentials jest podstawową biblioteką prawie każdej aplikacji platformy Xamarin, a jej funkcjonalność jest teraz częścią interfejsu użytkownika aplikacji wieloplatformowej platformy .NET (.NET MAUI).

W poniższych krokach opisano proces używania .NET MAUIfunkcji urządzenia natywnego, dawniej znanej jako Xamarin.Essentials, w aplikacji .NET dla systemu Android lub .NET dla systemu iOS:

1. Xamarin.Essentials Usuń pakiet NuGet z platformy .NET dla systemu Android lub .NET dla aplikacji systemu iOS.
2. $(UseMauiEssentials) Ustaw właściwość build na true wartość w pliku projektu. Aby uzyskać więcej informacji, zobacz Modyfikowanie pliku projektu.
3. Zainicjuj funkcję "essentials", wywołując metodę Platform.Init . Aby uzyskać więcej informacji, zobacz Inicjowanie platformy.
4. W razie potrzeby wykonaj dodatkową konfigurację. Aby uzyskać więcej informacji, zobacz Wykonywanie dodatkowej konfiguracji.
5. Dodaj dyrektywy using dla wymaganej funkcjonalności. Aby uzyskać więcej informacji, zobacz Dodawanie dyrektyw using.

Ważne

Nie jest wymagana żadna akcja do użycia Xamarin.Essentials w .NET MAUI aplikacji, inna niż usuwanie odwołań do Xamarin.Essentials przestrzeni nazw, ponieważ .NET MAUI zawiera już funkcje z Xamarin.Essentialsprogramu .

Modyfikowanie pliku projektu

Aby użyć .NET MAUIfunkcji urządzenia natywnego na platformie .NET dla systemu Android lub .NET dla systemu iOS, zmodyfikuj plik projektu i ustaw $(UseMauiEssentials) właściwość kompilacji na 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>

Inicjowanie platformy

Android

W każdym Activity uruchomionym pliku należy wywołać metodę Platform.Init , która znajduje się w Microsoft.Maui.ApplicationModel przestrzeni nazw, z OnCreate metody :

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

Metoda Platform.Init wymaga argumentu Application lub argumentu Activity i argumentu Bundle .

iOS

AppDelegate W klasie należy wywołać metodę Platform.Init , która znajduje się w Microsoft.Maui.ApplicationModel przestrzeni nazw, z FinishedLaunching metody :

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

Metoda Platform.Init wymaga argumentu Func<UIKit.UIViewController .

Uwaga

Jeśli jest to wymagane, możesz pobrać bieżący UIViewController obiekt, wywołując metodę Platform.GetCurrentUIViewController .

Wykonywanie dodatkowej konfiguracji

Klasa statyczna Platform zawiera pomocników specyficznych dla platformy.

Android

Element członkowski	Purpose
ActivityStateChanged	Zdarzenie, które jest zgłaszane, gdy zmienia się stan działania.
AppContext	Właściwość, która pobiera Context obiekt reprezentujący bieżący kontekst aplikacji.
CurrentActivity	Właściwość, która pobiera bieżący Activity obiekt reprezentujący bieżące działanie.
Intent	Klasa statyczna zawierająca ActionAppAction ciąg, który jest identyfikatorem używanym Intent przez akcje aplikacji.
OnNewIntent	Przekaż metodę Intent przesłoniętą przez działanie podczas wywoływania akcji aplikacji.
OnResume	Przekaż metodę Activity przesłoniętą działania, gdy Activity element zostanie wznowiony w ramach wywoływania akcji aplikacji.
OnRequestPermissionsResult	Przekaż wyniki żądania uprawnień z metody zastąpienia działania w celu obsługi wewnętrznych żądań uprawnień.
WaitForActivityAsync	Poczekaj na Activity utworzenie lub stanie się aktywny.

Aby uzyskać dostęp do bieżącej Context aplikacji lub Activity dla uruchomionej aplikacji:

var context = Platform.AppContext;

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

Jeśli jest taka sytuacja, w której Activity jest wymagana, ale aplikacja nie została w pełni uruchomiona, wywołaj metodę WaitForActivityAsync :

var activity = await Platform.WaitForActivityAsync();

Aby obsłużyć żądania uprawnień środowiska uruchomieniowego, zastąpij metodę OnRequestPermissionsResult w każdej Activity metodzie i wywołaj Platform.OnRequestPermissionsResult ją z niej:

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

Oprócz pobrania bieżącego Activityelementu można również zarejestrować się w celu uzyskania zdarzeń cyklu życia:

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

Stany aktywności to:

• Utworzone
• Wznowione
• Wstrzymana
• Zniszczone
• SaveInstanceState
• Rozpoczęto
• Zatrzymana

iOS

Metoda	Purpose
ContinueUserActivity	Informuje aplikację, że istnieją dane skojarzone z kontynuowaniem zadania określonego NSUserActivity jako obiekt, a następnie zwraca, czy aplikacja kontynuowała działanie.
GetCurrentUIViewController	Pobiera bieżący kontroler widoku. Ta metoda zwraca wartość null , jeśli nie można wykryć klasy UIViewController.
OpenUrl	Otwiera określony identyfikator URI, aby rozpocząć przepływ uwierzytelniania.
PerformActionForShortcutItem	Wywołuje akcję odpowiadającą wybranemu AppAction przez użytkownika.

Aby na przykład obsługiwać akcje aplikacji, przesłoń metodę PerformActionForShortcutItem w AppDelegate klasie i wywołaj z niej metodę Platform.PerformActionForShortcutItem :

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

Dodawanie dyrektyw using

Niejawne global using dyrektywy dla platformy .NET dla systemów iOS i .NET dla systemu Android nie zawierają przestrzeni nazw dla .NET MAUIfunkcji urządzeń natywnych. using W związku z tym dyrektywy dla Xamarin.Essentials przestrzeni nazw powinny zostać zastąpione dyrektywami using dla przestrzeni nazw, która zawiera wymagane funkcje:

Przestrzeń nazw	Purpose
Microsoft.Maui.ApplicationModel	Funkcje modelu aplikacji, w tym akcje aplikacji, uprawnienia i śledzenie wersji.
Microsoft.Maui.ApplicationModel.Communication	Funkcje komunikacji, w tym kontakty, poczta e-mail i sieć.
Microsoft.Maui.Devices	Funkcjonalność urządzenia, w tym baterii, czujników, latarki i haptycznych opinii.
Microsoft.Maui.Media	Funkcje multimediów, w tym wybieranie multimediów i zamiana tekstu na mowę.
Microsoft.Maui.ApplicationModel.DataTransfer	Udostępnianie funkcji, w tym schowka i udostępniania plików.
Microsoft.Maui.Storage	Funkcje magazynu, w tym pobieranie plików i bezpieczny magazyn.

Aby uzyskać więcej informacji na temat funkcji w każdej przestrzeni nazw, zobacz Integracja platformy.