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