Migrieren von Xamarin.Essentials-Code in .NET for Android- und .NET for iOS-Apps

Xamarin.Essentials ist eine grundlegende Bibliothek für fast jede Xamarin-App, und ihre Funktionalität ist jetzt Teil der .NET Multi-Platform App UI (.NET MAUI).

Die folgenden Schritte skizzieren den Prozess zur Verwendung der nativen Gerätefunktionalität von .NET MAUI, früher bekannt als Xamarin.Essentials, in einer .NET for Android- oder .NET for iOS-App:

1. Entfernen Sie das NuGet-Paket Xamarin.Essentials aus Ihrer .NET for Android- oder .NET for iOS-App.
2. Setzen Sie die $(UseMauiEssentials)-Build-Eigenschaft in Ihrer Projektdatei auf true. Weitere Informationen finden Sie unter Ändern Ihrer Projektdatei.
3. Initialisieren Sie die Funktionalität „Essentials“, indem Sie die Platform.Init-Methode aufrufen. Für weitere Informationen siehe Initialisierung der Plattform.
4. Führen Sie bei Bedarf zusätzliche Einrichtung aus. Weitere Informationen finden Sie unter Durchführen zusätzlicher Einstellungen.
5. Fügen Sie using-Anweisungen für die gewünschte Funktionalität hinzu. Weitere Informationen finden Sie unter Hinzufügen einer using-Anweisung.

Wichtig

Es ist keine Aktion erforderlich, um Xamarin.Essentials in einer .NET MAUI-App zu verwenden, außer Verweise auf den Xamarin.Essentials-Namespace zu entfernen, da in .NET MAUI die Funktionalität Xamarin.Essentials bereits enthalten ist.

Ändern Ihrer Projektdatei

Um die systemeigene Gerätefunktionen von .NET MAUI in einer .NET for Android- oder .NET for iOS-App zu verwenden, ändern Sie Ihre Projektdatei, und legen Sie die Buildeigenschaft $(UseMauiEssentials) auf true fest.

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>

Initialisierung der Plattform

Android

Bei jeder gestarteten Activity müssen Sie die Platform.Init -Methode aufrufen, die sich im Microsoft.Maui.ApplicationModel-Namespace aus der OnCreate-Methode befindet:

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

Die Platform.Init-Methode erfordert ein Application-Argument oder ein Activity-Argument und ein Bundle-Argument.

iOS

In Ihrer AppDelegate-Klasse müssen Sie die Platform.Init-Methode aufrufen, die sich im Microsoft.Maui.ApplicationModel-Namespace aus der FinishedLaunching-Methode befindet:

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

Für die Platform.Init-Methode ist ein Func<UIKit.UIViewController-Argument erforderlich.

Hinweis

Bei Bedarf können Sie das aktuelle UIViewController-Objekt durch Aufruf der Methode Platform.GetCurrentUIViewController abrufen.

Ausführen zusätzlicher Setups

Die statische Klasse Platform enthält plattformspezifische Hilfsprogramme.

Android

Member	Zweck
ActivityStateChanged	Ein Ereignis, das ausgelöst wird, wenn sich der Status einer Aktivität ändert.
AppContext	Eine Eigenschaft, die das Context-Objekt abruft, das den aktuellen App-Kontext darstellt.
CurrentActivity	Eine Eigenschaft, die das aktuelle Activity-Objekt abruft, das die aktuelle Aktivität darstellt.
Intent	Eine statische Klasse, die die ActionAppAction-Zeichenfolge enthält, welche als Bezeichner für die von App-Aktionen verwendeten Intent dient.
OnNewIntent	Übergeben Sie ein Intent von einer überschriebenen Methode einer Aktivität beim Aufruf einer Aktion der App.
OnResume	Übergeben Sie ein Activity aus der überschriebenen Methode einer Aktivität, wenn ein Activity als Teil des Aufrufs einer App-Aktion wieder aufgenommen wird.
OnRequestPermissionsResult	Übergeben Sie die Ergebnisse der Genehmigungsanfragen aus der überschriebenen Methode einer Aktivität, um interne Genehmigungsanfragen zu bearbeiten.
WaitForActivityAsync	Warten Sie, bis ein Activity erstellt wird oder aktiv wird.

Um auf die aktuelle Context oder Activity für die laufende App zuzugreifen:

var context = Platform.AppContext;

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

Falls Activity erforderlich ist, aber die App noch nicht vollständig gestartet ist, rufen Sie die WaitForActivityAsync-Methode auf:

var activity = await Platform.WaitForActivityAsync();

Um Laufzeitberechtigungsanfragen zu verarbeiten, überschreiben Sie die OnRequestPermissionsResult-Methode in jedem Activity und rufen die Platform.OnRequestPermissionsResult-Methode von ihr aus auf:

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

Sie können nicht nur den aktuellen Activity abrufen, sondern sich sich auch für Lebenszyklusereignisse registrieren:

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

Aktivitätszustände sind:

• Erstellt
• Resumed
• Paused
• Wird zerstört
• SaveInstanceState
• Started
• Beendet

iOS

Methode	Zweck
ContinueUserActivity	Informiert die App, dass es Daten gibt, die mit der Fortsetzung einer als NSUserActivity-Objekt spezifizierten Aufgabe verbunden sind, und gibt dann zurück, ob die App die Aktivität fortgesetzt hat.
GetCurrentUIViewController	Ruft den aktuellen View Controller ab. Diese Methode gibt null zurück, wenn kein UIViewController erkannt werden kann.
OpenUrl	Öffnet die angegebene URI, um einen Authentifizierungsflow zu starten.
PerformActionForShortcutItem	Ruft die Aktion auf, die dem ausgewählten AppAction entspricht.

Um beispielsweise App-Aktionen zu verarbeiten, überschreiben Sie die PerformActionForShortcutItem-Methode in Ihrer AppDelegate-Klasse, und rufen Sie die Platform.PerformActionForShortcutItem-Methode von ihr aus auf:

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

Hinzufügen von using-Anweisungen

Die impliziten global using-Direktiven für .NET for iOS und .NET for Android enthalten nicht die Namespaces für die systemeigene Gerätefunktionalität von .NET MAUI. Daher sollten using-Anweisungen für den Xamarin.Essentials-Namespace durch using-Anweisungen für den Namespace ersetzt werden, der die erforderliche Funktionalität enthält:

Namespace	Zweck
Microsoft.Maui.ApplicationModel	Anwendungsmodellfunktionen, einschließlich App-Aktionen, Berechtigungen und Versionsnachverfolgung.
Microsoft.Maui.ApplicationModel.Communication	Kommunikationsfunktionen, einschließlich Kontakte, E-Mail und Netzwerk.
Microsoft.Maui.Devices	Gerätefunktionen, einschließlich Akku, Sensoren, Taschenlampe und haptisches Feedback.
Microsoft.Maui.Media	Medienfunktionen, einschließlich Medienauswahl und Text-zu-Sprache.
Microsoft.Maui.ApplicationModel.DataTransfer	Freigabefunktionen, einschließlich Zwischenablage und Dateifreigabe.
Microsoft.Maui.Storage	Speicherfunktionalität, einschließlich Dateiauswahl und sicherer Speicher.

Weitere Informationen zur Funktionalität in den einzelnen Namespaces finden Sie unter Plattformintegration.