Berechtigungen

Durchsuchen Sie das Beispiel

In diesem Artikel wird beschrieben, wie Sie die .NET Multi-Platform App UI (.NET MAUI) Permissions Klasse verwenden können. Mit dieser Klasse können Sie Berechtigungen zur Laufzeit überprüfen und anfordern. Der typ Permissions ist im Namespace Microsoft.Maui.ApplicationModel verfügbar.

Verfügbare Berechtigungen

.NET MAUI versucht, so viele Berechtigungen wie möglich abstrahieren zu können. Jedes Betriebssystem hat jedoch einen anderen Satz von Berechtigungen. Auch wenn die API den Zugriff auf eine gemeinsame Berechtigung ermöglicht, kann es in Bezug auf diese Berechtigung Unterschiede zwischen den Betriebssystemen geben. In der folgenden Tabelle werden die verfügbaren Berechtigungen beschrieben:

In der folgenden Tabelle wird ✔️ verwendet, um anzuzeigen, dass das Recht unterstützt wird, und ❌, um anzuzeigen, dass das Recht nicht unterstützt wird oder nicht erforderlich ist:

Wenn eine Berechtigung als ❌ markiert ist, wird bei einer Anforderung oder Überprüfung immer Granted zurückgegeben.

Überprüfung der Berechtigungen

Um den aktuellen Status einer Berechtigung zu prüfen, verwenden Sie die Permissions.CheckStatusAsync-Methode zusammen mit der jeweiligen Berechtigung, um den Status abzurufen. Das folgende Beispiel überprüft den Status der Berechtigung LocationWhenInUse:

PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>();

Ein PermissionException wird ausgelöst, wenn die erforderliche Erlaubnis nicht deklariert ist.

Es ist am besten, den Status der Genehmigung zu prüfen, bevor Sie sie anfordern. Jedes Betriebssystem gibt einen anderen Standardstatus zurück, wenn der/die Benutzer*in noch nie dazu aufgefordert wurde. iOS gibt Unknown zurück, während andere Denied zurückgeben. Wenn der Status Granted ist, müssen keine weiteren Anrufe getätigt werden. Unter iOS, wenn der Status Denied ist, sollten Sie den Benutzer auffordern, die Berechtigung in den Einstellungen zu ändern. Unter Android können Sie ShouldShowRationale aufrufen, um festzustellen, ob der Benutzer die Erlaubnis bereits in der Vergangenheit verweigert hat.

Berechtigungsstatus

Bei Verwendung von CheckStatusAsync oder RequestAsync wird ein PermissionStatus zurückgegeben, der zur Bestimmung der nächsten Schritte verwendet werden kann:

• Unknown
  Die Berechtigung ist in einem unbekannten Zustand, oder unter iOS wurde der Benutzer nie dazu aufgefordert.

• Denied
  Der/Die Benutzer*in hat die Genehmigungsanfrage abgelehnt.

• Disabled
  Die Funktion ist auf dem Gerät deaktiviert.

• Granted
  Der/Die Benutzer*in hat die Erlaubnis erteilt oder sie wird automatisch erteilt.

• Restricted
  In einem eingeschränkten Zustand.

• Limited
  Im eingeschränkten Zustand. Nur iOS gibt diesen Status zurück.

Anfordern von Berechtigungen

Um eine Berechtigung von den Benutzer*innen anzufordern, verwenden Sie die RequestAsync-Methode zusammen mit der spezifischen anzufordernden Berechtigung. Wenn der/die Benutzer*in die Erlaubnis zuvor erteilt und nicht widerrufen hat, gibt diese Methode Granted zurück, ohne dem/der Benutzer*in ein Dialogfeld anzuzeigen. Berechtigungen sollten nicht von Ihrer MauiProgram- oder App-Klasse angefordert werden, sondern erst, wenn die erste Seite der App erschienen ist.

Das folgende Beispiel fordert die Erlaubnis LocationWhenInUse an:

PermissionStatus status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();

Ein PermissionException wird ausgelöst, wenn die erforderliche Erlaubnis nicht deklariert ist.

var status = await Permissions.RequestAsync<Permissions.PostNotifications>();

Erklären Sie, warum eine Erlaubnis erforderlich ist

Es empfiehlt sich, dem/der Benutzer*in zu erklären, warum seine App eine bestimmte Berechtigung benötigt. Unter iOS müssen Sie eine Zeichenfolge angeben, die dem/der Benutzer*in angezeigt wird. Android verfügt nicht über diese Möglichkeit und setzt den Berechtigungsstatus standardmäßig auf Disabled. Dies schränkt die Möglichkeit ein, festzustellen, ob der/die Benutzer*in die Erlaubnis verweigert hat oder ob die Erlaubnis zum ersten Mal angefordert wird. Die Methode ShouldShowRationale kann verwendet werden, um zu bestimmen, ob eine informative Benutzeroberfläche angezeigt werden soll. Wenn die Methode true zurückgibt, liegt das daran, dass der/die Benutzer*in die Berechtigung in der Vergangenheit verweigert oder deaktiviert hat. Andere Plattformen geben beim Aufruf dieser Methode immer false zurück.

Beispiel

Der folgende Code zeigt das allgemeine Verwendungsmuster, um festzustellen, ob eine Erlaubnis erteilt wurde, und sie dann anzufordern, wenn dies nicht der Fall ist.

public async Task<PermissionStatus> CheckAndRequestLocationPermission()
{
    PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>();

    if (status == PermissionStatus.Granted)
        return status;

    if (status == PermissionStatus.Denied && DeviceInfo.Platform == DevicePlatform.iOS)
    {
        // Prompt the user to turn on in settings
        // On iOS once a permission has been denied it may not be requested again from the application
        return status;
    }

    if (Permissions.ShouldShowRationale<Permissions.LocationWhenInUse>())
    {
        // Prompt the user with additional information as to why the permission is needed
    }

    status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();

    return status;
}

Erweitern von Berechtigungen

Die Berechtigungs-API wurde erstellt, um flexibel und erweiterbar für Anwendungen zu sein, die mehr Validierung oder Berechtigungen erfordern, die nicht in .NET MAUI enthalten sind. Erstellen Sie eine Klasse, die von Permissions.BasePermission erbt, und implementieren Sie die erforderlichen abstrakten Methoden. Der folgende Beispielcode veranschaulicht die grundlegenden abstrakten Mitglieder, jedoch ohne Implementierung:

public class MyPermission : Permissions.BasePermission
{
    // This method checks if current status of the permission.
    public override Task<PermissionStatus> CheckStatusAsync()
    {
        throw new System.NotImplementedException();
    }

    // This method is optional and a PermissionException is often thrown if a permission is not declared.
    public override void EnsureDeclared()
    {
        throw new System.NotImplementedException();
    }

    // Requests the user to accept or deny a permission.
    public override Task<PermissionStatus> RequestAsync()
    {
        throw new System.NotImplementedException();
    }

    // Indicates that the requestor should prompt the user as to why the app requires the permission, because the
    // user has previously denied this permission.
    public override bool ShouldShowRationale()
    {
        throw new NotImplementedException();
    }
}

Bei der Implementierung einer Berechtigung auf einer bestimmten Plattform kann die Permissions.BasePlatformPermission-Klasse davon abgeleitet werden. Diese Klasse bietet zusätzliche Hilfsmethoden für die Plattform, um die Berechtigungsdeklarationen automatisch zu überprüfen. Dies hilft bei der Erstellung von benutzerdefinierten Berechtigungen, die Gruppierungen vornehmen, wie etwa der Zugriff auf den Speicher unter Android, indem sowohl Lesen als auch Schreiben angefordert werden. Das folgende Codebeispiel demonstriert das Anfordern von Lese- und Schreibzugriffen auf den Speicher:

public class ReadWriteStoragePerms : Permissions.BasePlatformPermission
{
    public override (string androidPermission, bool isRuntime)[] RequiredPermissions =>
        new List<(string androidPermission, bool isRuntime)>
        {
        (global::Android.Manifest.Permission.ReadExternalStorage, true),
        (global::Android.Manifest.Permission.WriteExternalStorage, true)
        }.ToArray();
}

Anschließend überprüfen Sie die Berechtigung auf die gleiche Weise wie jeder andere Berechtigungstyp, der von .NET MAUI bereitgestellt wird:

PermissionStatus status = await Permissions.RequestAsync<ReadWriteStoragePerms>();

Wenn Sie diese API aus Ihrem plattformübergreifenden Code aufrufen möchten, können Sie eine Schnittstelle erstellen und die benutzerdefinierte Berechtigung als Abhängigkeit im Dienstcontainer der App registrieren. Das folgende Beispiel zeigt die IReadWritePermission-Schnittstelle.

public interface IReadWritePermission
{        
    Task<PermissionStatus> CheckStatusAsync();
    Task<PermissionStatus> RequestAsync();
}

Implementieren Sie dann die Schnittstelle in Ihrer benutzerdefinierten Berechtigung:

public class ReadWriteStoragePermission : Permissions.BasePlatformPermission, IReadWritePermission
{
    public override (string androidPermission, bool isRuntime)[] RequiredPermissions => new List<(string androidPermission, bool isRuntime)>
    {
        (Android.Manifest.Permission.ReadExternalStorage, true),
        (Android.Manifest.Permission.WriteExternalStorage, true)
    }.ToArray();
}

In der MauiProgram-Klasse sollten Sie dann die Schnittstelle und den konkreten Typ registrieren und den Typ, der die benutzerdefinierte Berechtigung verwendet, im Dienstcontainer der App:

builder.Services.AddTransient<MyViewModel>();
builder.Services.AddSingleton<IReadWritePermission, ReadWriteStoragePermission>();

Die Implementierung der benutzerdefinierten Berechtigung kann dann aufgelöst und von einem Ihrer Typen aufgerufen werden, wie z. B. einem ViewModel:

public class MyViewModel
{
    IReadWritePermission _readWritePermission;

    public MyViewModel(IReadWritePermission readWritePermission)
    {
        _readWritePermission = readWritePermission;
    }

    public async Task CheckPermissionAsync()
    {
        var status = await _readWritePermission.CheckStatusAsync();
        if (status != PermissionStatus.Granted)
        {
            status = await _readWritePermission.RequestAsync();
        }
    }
}

Plattformunterschiede

In diesem Abschnitt werden die plattformspezifischen Unterschiede mit der Berechtigungs-API beschrieben.