Preferences

Article
09/25/2024

Parcourez l’exemple. Parcourir l'exemple

Dans cet article, vous allez apprendre à utiliser l’interface IPreferences de l’application multiplateforme .NET (.NET MAUI). Cette interface permet de stocker les preferences d’application dans un magasin de clé-valeur.

L’implémentation par défaut de l’interface IPreferences est disponible via la propriété Preferences.Default. L’espace de noms Microsoft.Maui.Storage contient à la fois l’interface IPreferences et la classe Preferences.

Types de stockage

Les Preferences sont stockés avec une clé String. La valeur d’une préférence doit être l’un des types de données suivants :

Les valeurs de DateTime sont stockées dans un format binaire 64 bits (entier long) à l’aide de deux méthodes définies par la classe DateTime :

La méthode ToBinary est utilisée pour encoder la valeur DateTime.
La méthode FromBinary décode la valeur.

Consultez la documentation de ces méthodes pour voir les ajustements que vous pouvez apporter aux valeurs décodées lorsqu’un DateTime est stocké qui n’est pas une valeur de temps universel coordonné (UTC).

Définir preferences

Pour définir Preferences, appelez la méthode Preferences.Set en fournissant la clé et la valeur :

// Set a string value:
Preferences.Default.Set("first_name", "John");

// Set an numerical value:
Preferences.Default.Set("age", 28);

// Set a boolean value:
Preferences.Default.Set("has_pets", true);

Get preferences

Pour récupérer une valeur à partir des preferences, passez la clé de la préférence, suivie de la valeur par défaut lorsque la clé n’existe pas :

string firstName = Preferences.Default.Get("first_name", "Unknown");
int age = Preferences.Default.Get("age", -1);
bool hasPets = Preferences.Default.Get("has_pets", false);

Dans certains scénarios, vous devrez peut-être transmettre la clé de la préférence, suivie de la valeur par défaut et de son type :

long value = Preferences.Get("master_date", (long)0);

Rechercher une clé

Il peut être utile de vérifier si une clé existe ou non dans les preferences. Même si Get vous demande de définir une valeur par défaut lorsque la clé n’existe pas, il peut arriver que la clé existe et que sa valeur corresponde à la valeur par défaut. Vous ne pouvez donc pas vous fier à la valeur par défaut comme indicateur de l’inexistence de la clé. Utilisez la méthode ContainsKey pour déterminer si une clé existe :

bool hasKey = Preferences.Default.ContainsKey("my_key");

Supprimer une ou toutes les clés

Utilisez la méthode Remove pour supprimer une clé spécifique des preferences :

Preferences.Default.Remove("first_name");

Pour supprimer toutes les clés, utilisez la méthode Clear :

Preferences.Default.Clear();

Clés partagées

Les preferences stockées par votre application ne sont visibles que par votre application. Toutefois, vous pouvez également créer une préférence partagée qui peut être utilisée par d’autres extensions ou une application espion. Lorsque vous définissez, supprimez ou récupérez une préférence, vous pouvez fournir un paramètre de chaîne facultatif pour spécifier le nom du conteneur dans lequel la préférence est stockée.

Les méthodes suivantes prennent un paramètre de chaîne nommé sharedName:

Preferences.Set
Preferences.Get
Preferences.Remove
Preferences.Clear

Important

Lisez les spécificités de l’implémentation de la plateforme, car les preferences partagées ont des implémentations propres au comportement.

Intégrer aux paramètres système

Les Preferences sont stockés en mode natif, ce qui vous permet d’intégrer vos paramètres dans les paramètres système natifs. Suivez la documentation de la plateforme pour l’intégration à la plateforme :

Apple : Implémentation d’un ensemble de paramètres iOS
Android : Bien démarrer avec les écrans de paramètres

Différences selon les plateformes

Cette section décrit les différences propres à la plateforme concernant l’API preferences.

Toutes les données sont stockées dans un élément Preferences partagé. Si aucun sharedName n’est spécifié, l’élément Preferences partagé par défaut est utilisé. Sinon, le nom est utilisé pour obtenir un élément Preferences partagé privé avec le nom spécifié.

ApplicationDataContainer est utilisé pour stocker les valeurs sur l’appareil. Si aucun sharedName n’est spécifié, LocalSettings est utilisé. Sinon, le nom est utilisé pour créer un conteneur à l’intérieur de LocalSettings.

LocalSettings limite les noms de clés de préférence à 255 caractères. La taille maximale de chaque valeur de préférence est de 8 Ko, et celle de chaque paramètre composite est de 64 Ko.

Persistance

La désinstallation de l’application entraîne la suppression de toutes les preferences, sauf lorsque l’application s’exécute sur Android 6.0 (niveau d’API 23) ou une version ultérieure, lors de l’utilisation de la fonctionnalité de sauvegarde automatique. Cette fonctionnalité est activée par défaut et conserve les données d’application, notamment l’élément Preferences partagé qu’utilise l’API Preferences. Vous pouvez désactiver cette fonctionnalité en suivant la documentation sur la sauvegarde automatique de Google.

Limites

Les performances peuvent être affectées si vous stockez du texte en grande quantité, car l’API a été conçue pour stocker de petites quantités de texte.

Partager via