Xamarin.Essentials:Autorisations

La classe Permissions permet de case activée et de demander des autorisations d’exécution.

Bien démarrer

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. Assurez-vous que est entièrement initialisé et que Xamarin.Essentials la gestion des autorisations est configurée dans votre application.

Dans le projet MainLauncher Android ou tout autre 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 doit 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 des autorisations

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

using Xamarin.Essentials;

Vérification des autorisations

Pour case activée la status actuelle d’une autorisation, utilisez la CheckStatusAsync méthode ainsi que l’autorisation spécifique pour obtenir le status.

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

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

Il est préférable de case activée la status 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 retournent Denied. Si le status est, il n’est Granted pas nécessaire d’effectuer d’autres appels. Sur iOS, si le status estDenied, 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 RequestAsync méthode avec l’autorisation spécifique à demander. Si l’utilisateur a précédemment accordé l’autorisation et ne l’a pas révoquée, cette méthode retourne Granted immédiatement et n’affiche pas de boîte de dialogue.

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

Un PermissionException est levée 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 case activée si une autorisation est à l’état Denied et demander à l’utilisateur de l’activer manuellement.

État de l’autorisation

Lors de l’utilisation CheckStatusAsync ou RequestAsync d’un PermissionStatus sera retourné 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 est automatiquement accordé
• Restreint : dans un état restreint

Expliquer pourquoi une 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 qui s’affiche pour l’utilisateur. Android n’a pas cette capacité et l’autorisation par défaut status désactivé. Cela limite la possibilité de savoir si l’utilisateur a refusé l’autorisation ou s’il s’agit de la première invite de 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 cela est dû au fait que l’utilisateur a refusé ou désactivé l’autorisation dans le passé. Les 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 :

• - Prise en charge
• - Non pris en charge/obligatoire

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

Si une autorisation est marquée comme , elle est toujours retournée Granted lorsqu’elle est activée ou demandée.

Utilisation générale

Le code suivant présente le modèle d’utilisation général permettant de déterminer si une autorisation a été accordée et de la demander si ce n’est pas le cas. 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 un instance de celui-ci créé que les méthodes peuvent être appelées 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 supplémentaire ou des autorisations qui ne sont pas incluses dans Xamarin.Essentials. Créez une classe qui hérite de BasePermission et implémente 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 dans une plateforme spécifique, la BasePlatformPermission classe peut être héritée. Cela fournit des méthodes d’assistance de plateforme supplémentaires pour case activée 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 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 d’un 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épendances pour inscrire et obtenir l’implémentation.

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

Ensuite, implémentez 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 le 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. L’status d’autorisation par défaut est Refusé.

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

iOS

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

Pour en savoir plus, consultez la documentation sur les fonctionnalités de sécurité et de confidentialité iOS .

UWP

Les autorisations doivent avoir des fonctionnalités correspondantes déclarées dans le manifeste du package. L’autorisation status par défaut est Inconnue dans la plupart des instances.

Pour plus d’informations, consultez la documentation relative à la déclaration de capacité d’application .

API

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

Vidéo associée

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