Autorizzazioni

Esplorare l'esempio

Questo articolo descrive come usare la classe .NET Multi-platform App UI (.NET MAUI). Permissions Questa classe consente di controllare e richiedere le autorizzazioni in fase di esecuzione. Il Permissions tipo è disponibile nello spazio dei Microsoft.Maui.ApplicationModel nomi .

Autorizzazioni disponibili

.NET MAUI tenta di astrarre il maggior numero possibile di autorizzazioni. Tuttavia, ogni sistema operativo ha un set diverso di autorizzazioni. Anche se l'API consente l'accesso a un'autorizzazione comune, potrebbero esserci differenze tra i sistemi operativi correlati a tale autorizzazione. Nella tabella seguente vengono descritte le autorizzazioni disponibili:

La tabella seguente usa ✔️ per indicare che l'autorizzazione è supportata e ❌ per indicare che l'autorizzazione non è supportata o non è necessaria:

Autorizzazione	Android	iOS	Windows	tvOS
Batteria	✔️	❌	❌	❌
Bluetooth	✔️	❌	❌	❌
CalendarRead	✔️	✔️	❌	❌
CalendarWrite	✔️	✔️	❌	❌
Fotocamera	✔️	✔️	❌	❌
ContactsRead	✔️	✔️	❌	❌
ContactsWrite	✔️	✔️	❌	❌
Torcia	✔️	❌	❌	❌
LocationWhenInUse	✔️	✔️	❌	✔️
LocationAlways	✔️	✔️	❌	❌
Media	❌	✔️	❌	❌
Microfono	✔️	✔️	❌	❌
NearbyWifiDevices	✔️	❌	❌	❌
Networkstate	✔️	❌	❌	❌
Telefono	✔️	✔️	❌	❌
Foto	❌	✔️	❌	✔️
Foto AddOnly	❌	✔️	❌	✔️
Promemoria	❌	✔️	❌	❌
Sensori	✔️	✔️	❌	❌
Sms	✔️	✔️	❌	❌
Comandi vocali	✔️	✔️	❌	❌
Archiviazione Read	✔️	❌	❌	❌
Archiviazione Write	✔️	❌	❌	❌
Vibrazione	✔️	❌	❌	❌

Se un'autorizzazione è contrassegnata come ❌, verrà sempre restituita Granted quando selezionata o richiesta.

Controllo delle autorizzazioni

Per controllare lo stato corrente di un'autorizzazione, usare il metodo Permissions.CheckStatusAsync insieme all'autorizzazione specifica di cui ottenere lo stato. L'esempio seguente controlla lo stato dell'autorizzazione LocationWhenInUse :

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

Viene PermissionException generata un'eccezione se l'autorizzazione richiesta non è dichiarata.

È consigliabile controllare lo stato dell'autorizzazione prima di richiederlo. Ogni sistema operativo restituisce uno stato predefinito diverso, se l'utente non è mai stato richiesto. iOS restituisce Unknown, mentre altri restituiscono Denied. Se lo stato è Granted , non è necessario effettuare altre chiamate. In iOS se lo stato è Denied necessario richiedere all'utente di modificare l'autorizzazione nelle impostazioni. In Android è possibile chiamare ShouldShowRationale per rilevare se l'utente ha già negato l'autorizzazione in passato.

Stato dell'autorizzazione

Quando si usa CheckStatusAsync o RequestAsync, viene restituito un oggetto PermissionStatus che può essere usato per determinare i passaggi successivi:

• Unknown
  L'autorizzazione è in uno stato sconosciuto o in iOS, l'utente non è mai stato richiesto.

• Denied
  L'utente ha negato la richiesta di autorizzazione.

• Disabled
  La funzionalità è disabilitata nel dispositivo.

• Granted
  L'utente ha concesso l'autorizzazione o viene concessa automaticamente.

• Restricted
  In uno stato con restrizioni.

• Limited
  In uno stato limitato. Solo iOS restituisce questo stato.

Richiesta di autorizzazioni

Per richiedere un'autorizzazione agli utenti, usare il metodo RequestAsync insieme all'autorizzazione specifica da richiedere. Se l'utente ha precedentemente concesso l'autorizzazione e non l'ha revocata, questo metodo restituirà Granted senza visualizzare una finestra di dialogo all'utente. Le autorizzazioni non devono essere richieste dalla classe MauiProgram o App e devono essere richieste solo dopo che è stata visualizzata la prima pagina dell'app.

Nell'esempio seguente viene richiesta l'autorizzazione LocationWhenInUse :

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

Viene PermissionException generata un'eccezione se l'autorizzazione richiesta non è dichiarata.

Importante

In alcune piattaforme, una richiesta di autorizzazione può essere attivata solo una sola volta. Ulteriori richieste devono essere gestite dallo sviluppatore per verificare se un'autorizzazione Denied è nello stato e quindi chiedere all'utente di attivarla manualmente.

Spiegare perché è necessaria l'autorizzazione

È consigliabile spiegare all'utente perché l'applicazione necessita di un'autorizzazione specifica. In iOS è necessario specificare una stringa visualizzata all'utente. Android non ha questa capacità e anche lo stato di autorizzazione predefinito è Disabled. Ciò limita la possibilità di sapere se l'utente ha negato l'autorizzazione o se è la prima volta che viene richiesta l'autorizzazione. Il ShouldShowRationale metodo può essere usato per determinare se deve essere visualizzata un'interfaccia utente informativa. Se il metodo restituisce true, questo avviene perché l'utente ha negato o disabilitato l'autorizzazione in passato. Le altre piattaforme restituiscono false sempre quando si chiama questo metodo.

Esempio

Il codice seguente presenta il modello di utilizzo generale per determinare se è stata concessa un'autorizzazione e quindi richiederla se non è stata concessa.

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

Estensione delle autorizzazioni

L'API Autorizzazioni è stata creata per essere flessibile ed estendibile per le applicazioni che richiedono più convalida o autorizzazioni che non sono incluse in .NET MAUI. Creare una classe che eredita da Permissions.BasePermissione implementare i metodi astratti necessari. Il codice di esempio seguente illustra i membri astratti di base, ma senza implementazione:

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

Quando si implementa un'autorizzazione in una piattaforma specifica, è possibile ereditare la classe Permissions.BasePlatformPermission. Questa classe fornisce metodi helper aggiuntivi per la piattaforma per controllare automaticamente le dichiarazioni di autorizzazione. Ciò consente di creare autorizzazioni personalizzate che eseguono raggruppamenti, ad esempio richiedendo l'accesso in lettura e scrittura all'archiviazione in Android. L'esempio di codice seguente illustra la richiesta di accesso alle risorse di archiviazione di lettura e scrittura :

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

È quindi possibile controllare l'autorizzazione nello stesso modo di qualsiasi altro tipo di autorizzazione fornito da .NET MAUI:

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

Se si vuole chiamare questa API dal codice multipiattaforma, è possibile creare un'interfaccia e registrare l'autorizzazione personalizzata come dipendenza nel contenitore del servizio dell'app. L'esempio seguente illustra l'interfaccia IReadWritePermission :

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

Implementare quindi l'interfaccia nell'autorizzazione personalizzata:

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

MauiProgram Nella classe è quindi necessario registrare l'interfaccia e il relativo tipo concreto e il tipo che utilizzerà l'autorizzazione personalizzata, nel contenitore del servizio dell'app:

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

L'implementazione dell'autorizzazione personalizzata può quindi essere risolta e richiamata da uno dei tipi, ad esempio un modello di visualizzazione:

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

Differenze tra le piattaforme

Questa sezione descrive le differenze specifiche della piattaforma con l'API delle autorizzazioni.

Android

Per le autorizzazioni è necessario impostare gli attributi di corrispondenza nel file manifesto di Android. Per impostazione predefinita, lo stato delle autorizzazioni è Denied.

Catalyst iOS/Mac

Le autorizzazioni devono avere una stringa corrispondente nel file Info.plist . Una volta richiesta e negata un'autorizzazione, un popup non verrà più visualizzato se si richiede l'autorizzazione una seconda volta. È necessario richiedere all'utente di modificare manualmente l'impostazione nella schermata delle impostazioni delle applicazioni in iOS. Per impostazione predefinita, lo stato delle autorizzazioni è Unknown.

Windows

Non esistono differenze per questa piattaforma.