Leggere in inglese

Condividi tramite


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 :

C#
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:

C#
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 :

C#
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.

C#
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.

C#
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:

  • supporto completo -Sostenuto
  • Non supportato - Non supportato/obbligatorio
Autorizzazione Android iOS UWP watchOS tvOS Tizen
CalendarRead Android supportato iOS supportato UWP non supportato watchOS supportato tvOS non supportato Tizen non supportato
CalendarWrite Android supportato iOS supportato UWP non supportato watchOS supportato tvOS non supportato Tizen non supportato
Fotocamera Android supportato iOS supportato UWP non supportato watchOS non supportato tvOS non supportato Tizen supportato
ContactsRead Android supportato iOS supportato UWP supportato watchOS non supportato tvOS non supportato Tizen non supportato
ContactsWrite Android supportato iOS supportato UWP supportato watchOS non supportato tvOS non supportato Tizen non supportato
Torcia elettrica Android supportato iOS non supportato UWP non supportato watchOS non supportato tvOS non supportato Tizen supportato
LocationWhenInUse Android supportato iOS supportato UWP supportato watchOS supportato tvOS supportato Tizen supportato
LocationAlways Android supportato iOS supportato UWP supportato watchOS supportato tvOS non supportato Tizen supportato
Media Android non supportato iOS supportato UWP non supportato watchOS non supportato tvOS non supportato Tizen non supportato
Microphone Android supportato iOS supportato UWP supportato watchOS non supportato tvOS non supportato Tizen supportato
Telefono Android supportato iOS supportato UWP non supportato watchOS non supportato tvOS non supportato Tizen non supportato
Foto Android non supportato iOS supportato UWP non supportato watchOS non supportato tvOS supportato Tizen non supportato
Promemoria Android non supportato iOS supportato UWP non supportato watchOS supportato tvOS non supportato Tizen non supportato
Sensors Android supportato iOS supportato UWP supportato watchOS supportato tvOS non supportato Tizen non supportato
Sms Android supportato iOS supportato UWP non supportato watchOS non supportato tvOS non supportato Tizen non supportato
Comandi vocali Android supportato iOS supportato UWP non supportato watchOS non supportato tvOS non supportato Tizen non supportato
StorageRead Android supportato iOS non supportato UWP non supportato watchOS non supportato tvOS non supportato Tizen non supportato
StorageWrite Android supportato iOS non supportato UWP non supportato watchOS non supportato tvOS non supportato Tizen non supportato

Se un'autorizzazione è contrassegnata come non supportato 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.

C#
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.

C#
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.

C#
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.

C#
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.

C#
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.

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

Implementare quindi l'interfaccia nel progetto di piattaforma:

C#
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:

C#
DependencyService.Register<IReadWritePermission, ReadWriteStoragePermission>();

Quindi, dal progetto condiviso è possibile risolverlo e usarlo:

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

Informazioni di implementazione specifiche della piattaforma

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.

API

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