Xamarin.Essentials:Autorisations

La classe Permissions permet de vérifier et de demander des autorisations d’exécution.

Démarrage

Pour commencer à utiliser cette API, lisez le guide de prise en main pour Xamarin.Essentials vous assurer que la bibliothèque est correctement installée et configurée dans vos projets.

Cette API utilise des autorisations d’exécution sur Android. Vérifiez que la Xamarin.Essentials gestion des autorisations est entièrement initialisée et configurée dans votre application.

Dans le projet MainLauncher Android ou tout Activity projet lancé Xamarin.Essentials doit être initialisé dans la OnCreate méthode :

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

Pour gérer les autorisations d’exécution sur Android, Xamarin.Essentials doivent recevoir n’importe quel OnRequestPermissionsResult. Ajoutez le code suivant à toutes les classes 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);
}

Utilisation de Permissions

Ajoutez une référence à Xamarin.Essentials votre classe :

using Xamarin.Essentials;

Vérification des autorisations

Pour vérifier l’état actuel d’une autorisation, utilisez la méthode CheckStatusAsync, ainsi que l’autorisation spécifique pour laquelle obtenir l’état.

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

PermissionException est levé si l’autorisation requise n’est pas déclarée.

Il est préférable de vérifier l’état de l’autorisation avant de la demander. Chaque système d’exploitation retourne un état par défaut différent si l’utilisateur n’a jamais été invité. iOS retourne Unknown, tandis que d’autres systèmes d’exploitation retournent Denied. Si l’état est alors, il n’est Granted pas nécessaire d’effectuer d’autres appels. Sur iOS si l’état est Denied que vous devez inviter l’utilisateur à modifier l’autorisation dans les paramètres et sur Android, vous pouvez appeler ShouldShowRationale pour détecter si l’utilisateur a déjà refusé l’autorisation dans le passé.

Demande d’autorisations

Pour demander une autorisation aux utilisateurs, utilisez la méthode RequestAsync, ainsi que l’autorisation spécifique à demander. Si l’utilisateur a précédemment accordé l’autorisation et ne l’a pas révoqué, cette méthode retourne Granted immédiatement et n’affiche pas de boîte de dialogue.

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

PermissionException est levé si l’autorisation requise n’est pas déclarée.

Notez que sur certaines plateformes, une demande d’autorisation ne peut être activée qu’une seule fois. D’autres invites doivent être gérées par le développeur pour vérifier si une autorisation est dans l’état Denied et demander à l’utilisateur de l’activer manuellement.

État d’autorisation

Lors de l’utilisation CheckStatusAsync ou RequestAsync d’un PermissionStatus retour, qui peut être utilisé pour déterminer les étapes suivantes :

• Inconnu - L’autorisation est dans un état inconnu
• Refusé - L’utilisateur a refusé la demande d’autorisation
• Désactivé - La fonctionnalité est désactivée sur l’appareil
• Accordé - L’utilisateur a accordé l’autorisation ou celle-ci est automatiquement accordée
• Restreint - État restreint

Expliquer pourquoi l’autorisation est nécessaire

Il est recommandé d’expliquer pourquoi votre application a besoin d’une autorisation spécifique. Sur iOS, vous devez spécifier une chaîne affichée à l’utilisateur. Android n’a pas cette possibilité et également l’état d’autorisation par défaut sur Désactivé. Cela limite la possibilité de savoir si l’utilisateur a refusé l’autorisation ou s’il s’agit de la première fois d’inviter l’utilisateur. La ShouldShowRationale méthode peut être utilisée pour déterminer si une interface utilisateur éducative doit être affichée. Si la méthode retourne true cette valeur, c’est parce que l’utilisateur a refusé ou désactivé l’autorisation dans le passé. D’autres plateformes retournent false toujours lors de l’appel de cette méthode.

Autorisations disponibles

Xamarin.Essentials tente d’extraire autant d’autorisations que possible. Toutefois, chaque système d’exploitation dispose d’un ensemble différent d’autorisations d’exécution. En outre, il existe des différences lors de la fourniture d’une API unique pour certaines autorisations. Voici un guide des autorisations actuellement disponibles :

Guide des icônes :

• -Supporté
• - Non pris en charge/requis

Autorisation	Android	iOS	UWP	watchOS	tvOS	Tizen
CalendarRead
CalendarWrite
Appareil photo
ContactsRead
ContactsWrite
Lampe torche
LocationWhenInUse
LocationAlways
Média
Microphone
Téléphone
Photos
Relances
Capteurs
Sms
Speech
StorageRead
StorageWrite

Si une autorisation est marquée comme elle retourne Granted toujours une fois activée ou demandée.

Utilisation générale

Le code suivant présente le modèle d’utilisation général pour déterminer si une autorisation a été accordée et la demande si elle n’en a pas. Ce code utilise des fonctionnalités disponibles avec Xamarin.Essentials la version 1.6.0 ou ultérieure.

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

Chaque type d’autorisation peut avoir une instance d’elle créée que les méthodes peuvent appeler directement.

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

Extension des autorisations

L’API Autorisations a été créée pour être flexible et extensible pour les applications qui nécessitent une validation ou des autorisations supplémentaires qui ne sont pas incluses dans Xamarin.Essentials. Créez une nouvelle classe qui hérite de BasePermission et implémentez les méthodes abstraites requises.

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

Lors de l’implémentation d’une autorisation sur une plateforme spécifique, la classe BasePlatformPermission peut être héritée. Cela fournit des méthodes d’assistance de plateforme supplémentaires pour vérifier automatiquement les déclarations. Cela peut vous aider lors de la création d’autorisations personnalisées qui effectuent des regroupements. Par exemple, vous pouvez demander à la fois l’accès en lecture et en écriture au stockage sur Android à l’aide de l’autorisation personnalisée suivante.

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

Vous pouvez ensuite appeler votre nouvelle autorisation à partir du projet Android.

await Permissions.RequestAsync<ReadWriteStoragePermission>();

Si vous souhaitez appeler cette API à partir de votre code partagé, vous pouvez créer une interface et utiliser un service de dépendance pour inscrire et obtenir l’implémentation.

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

Implémentez ensuite l’interface dans votre projet de plateforme :

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

Vous pouvez ensuite inscrire l’implémentation spécifique :

DependencyService.Register<IReadWritePermission, ReadWriteStoragePermission>();

Ensuite, à partir de votre projet partagé, vous pouvez résoudre et l’utiliser :

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

Caractéristiques de mise en œuvre de la plateforme

Android

Les attributs correspondants doivent être définis dans le fichier manifeste Android des autorisations. L’état de l’autorisation est défini par défaut sur Refusé.

Pour plus d’informations, consultez la documentation Autorisations dans Xamarin.Android.

iOS

Les autorisations doivent avoir une chaîne correspondante dans le fichier Info.plist. Une fois qu’une autorisation est demandée et refusée, une fenêtre contextuelle ne s’affiche plus si vous demandez l’autorisation une deuxième fois. Vous devez inviter votre utilisateur à ajuster manuellement le paramètre dans l’écran Paramètres des applications dans iOS. L’état de l’autorisation est défini par défaut sur Inconnu.

Pour plus d’informations, consultez la documentation Fonctionnalités de sécurité et de confidentialité d’iOS.

UWP

Les autorisations doivent avoir des capacités correspondantes déclarées dans le manifeste du package. L’état de l’autorisation est défini par défaut sur Inconnu dans la plupart des instances.

Pour plus d’informations, consultez la documentation Déclaration des capacités de l’application.

API

• Code source des autorisations
• Documentation sur l’API Permissions

Vidéo associée

Retrouvez d’autres vidéos Xamarin sur Channel 9 et YouTube.