Xamarin.Essentials:Autorizzazioni

La classe di autorizzazioni consente di controllare e richiedere le autorizzazioni di runtime.

Operazioni preliminari

Per iniziare a usare questa API, leggere la guida introduttiva per Xamarin.Essentials assicurarsi che la libreria sia installata e configurata correttamente nei progetti.

Questa API usa le autorizzazioni di runtime in Android. Assicurarsi che sia completamente inizializzata e che Xamarin.Essentials la gestione delle autorizzazioni sia configurata nell'app.

Nel progetto MainLauncher Android o in qualsiasi Activity elemento avviato Xamarin.Essentials deve essere inizializzato nel OnCreate metodo :

protected override void OnCreate(Bundle savedInstanceState) 
{
    //...
    base.OnCreate(savedInstanceState);
    Xamarin.Essentials.Platform.Init(this, savedInstanceState); // add this line to your code, it may also be called: bundle
    //...
}    

Per gestire le autorizzazioni di runtime in Android, Xamarin.Essentials deve ricevere qualsiasi OnRequestPermissionsResult. Aggiungere il codice seguente a tutte le classi Activity:

public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Android.Content.PM.Permission[] grantResults)
{
    Xamarin.Essentials.Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);

    base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
}

Uso delle autorizzazioni

Aggiungere un riferimento a Xamarin.Essentials nella classe :

using Xamarin.Essentials;

Controllo delle autorizzazioni

Per controllare lo stato corrente di un'autorizzazione, usare il metodo CheckStatusAsync insieme all'autorizzazione specifica di cui ottenere lo stato.

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

Se l'autorizzazione necessaria non è dichiarata, viene generata un'eccezione PermissionException.

È 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 chiedere all'utente di modificare l'autorizzazione nelle impostazioni e in Android è possibile chiamare ShouldShowRationale per rilevare se l'utente ha già negato l'autorizzazione in passato.

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 lo ha revocato, questo metodo restituirà Granted immediatamente e non visualizzerà una finestra di dialogo.

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

Se l'autorizzazione necessaria non è dichiarata, viene generata un'eccezione PermissionException.

Si noti che in alcune piattaforme è possibile attivare una richiesta di autorizzazione una sola volta. Ulteriori richieste devono essere gestite dallo sviluppatore per verificare se un'autorizzazione Denied è nello stato e chiedere all'utente di attivarla manualmente.

Stato dell'autorizzazione

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

• Sconosciuto: lo stato dell'autorizzazione è sconosciuto
• Negato: l'utente ha negato la richiesta dell'autorizzazione
• Disabilitato: la funzionalità è disabilitata nel dispositivo
• Concesso: l'autorizzazione è concessa dall'utente oppure automaticamente
• Con restrizioni: lo stato ha restrizioni

Spiegare perché è necessaria l'autorizzazione

È consigliabile spiegare 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 è Disabilitato. Ciò limita la possibilità di sapere se l'utente ha negato l'autorizzazione o se è la prima volta che richiede l'utente. Il ShouldShowRationale metodo può essere usato per determinare se deve essere visualizzata un'interfaccia utente didattica. Se il metodo restituisce true questo risultato è dovuto al fatto che l'utente ha negato o disabilitato l'autorizzazione in passato. Le altre piattaforme restituiranno false sempre quando si chiama questo metodo.

Autorizzazioni disponibili

Xamarin.Essentials tenta di astrarre il maggior numero possibile di autorizzazioni. Tuttavia, ogni sistema operativo ha un set diverso di autorizzazioni di runtime. Esistono inoltre differenze quando si fornisce una singola API per alcune autorizzazioni. Di seguito è riportata una guida per le autorizzazioni attualmente disponibili:

Guida alle icone:

• -Supportati
• - Non supportato/obbligatorio

Autorizzazione	Android	iOS	UWP	watchOS	tvOS	Tizen
CalendarRead
CalendarWrite
Fotocamera
ContactsRead
ContactsWrite
Torcia elettrica
LocationWhenInUse
LocationAlways
File media
Microphone
il numero
Foto
Promemoria
Sensors
Sms
Voce
StorageRead
StorageWrite

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

Utilizzo generale

Il codice seguente presenta il modello di utilizzo generale per determinare se è stata concessa un'autorizzazione e richiederla in caso contrario. Questo codice usa funzionalità disponibili con Xamarin.Essentials la versione 1.6.0 o successiva.

public async Task<PermissionStatus> CheckAndRequestLocationPermission()
{
    var 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;
}

Ogni tipo di autorizzazione può includere un'istanza e i metodi possono essere chiamati direttamente.

public async Task GetLocationAsync()
{
    var status = await CheckAndRequestPermissionAsync(new Permissions.LocationWhenInUse());
    if (status != PermissionStatus.Granted)
    {
        // Notify user permission was denied
        return;
    }

    var location = await Geolocation.GetLocationAsync();
}

public async Task<PermissionStatus> CheckAndRequestPermissionAsync<T>(T permission)
            where T : BasePermission
{
    var status = await permission.CheckStatusAsync();
    if (status != PermissionStatus.Granted)
    {
        status = await permission.RequestAsync();
    }

    return status;
}

Estensione delle autorizzazioni

L'API Autorizzazioni è stata creata per essere flessibile ed estendibile per le applicazioni che richiedono una convalida aggiuntiva o autorizzazioni che non sono incluse in Xamarin.Essentials. Creare una nuova classe che eredita da BasePermission e implementare i metodi astratti richiesti.

public class MyPermission : 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();
    }
}

Quando si implementa un'autorizzazione in una piattaforma specifica, è possibile ereditare la classe BasePlatformPermission. In questo modo vengono forniti altri metodi helper della piattaforma per controllare automaticamente le dichiarazioni. Ciò può essere utile quando si creano autorizzazioni personalizzate che eseguono raggruppamenti. Ad esempio, è possibile richiedere l'accesso in lettura e scrittura all'archiviazione in Android usando l'autorizzazione personalizzata seguente.

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

È quindi possibile chiamare la nuova autorizzazione dal progetto Android.

await Permissions.RequestAsync<ReadWriteStoragePermission>();

Se si vuole chiamare questa API dal codice condiviso, è possibile creare un'interfaccia e usare un servizio di dipendenza per registrare e ottenere l'implementazione.

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

Implementare quindi l'interfaccia nel progetto di piattaforma:

public class ReadWriteStoragePermission : Xamarin.Essentials.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();
}

È quindi possibile registrare l'implementazione specifica:

DependencyService.Register<IReadWritePermission, ReadWriteStoragePermission>();

Quindi, dal progetto condiviso è possibile risolverlo e usarlo:

var readWritePermission = DependencyService.Get<IReadWritePermission>();
var status = await readWritePermission.CheckStatusAsync();
if (status != PermissionStatus.Granted)
{
    status = await readWritePermission.RequestAsync();
}

Informazioni di implementazione specifiche della piattaforma

Android

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

Altre informazioni sono disponibili nella documentazione Autorizzazioni in Xamarin.Android.

iOS

Le autorizzazioni devono includere una stringa di corrispondenza nel file Info.plist. Dopo aver richiesto un'autorizzazione e negato un popup, non verrà più visualizzata 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 è Sconosciuto.

Altre informazioni sono disponibili nella documentazione Funzionalità per la sicurezza e la privacy di iOS.

UWP

Per le autorizzazioni è necessario dichiarare le funzionalità di corrispondenza nel manifesto del pacchetto. Per impostazione predefinita, lo stato delle autorizzazioni è Sconosciuto nella maggior parte dei casi.

Altre informazioni sono disponibili nella documentazione Dichiarazioni di funzionalità delle app.

API

• Codice sorgente delle autorizzazioni
• Documentazione dell'API delle autorizzazioni

Video correlato

Altri video di Xamarin sono disponibili su Channel 9 e YouTube.