Preferences

Examinar el ejemplo

En este artículo se describe cómo puedes usar la interfaz IPreferences de .NET Multi-platform App UI (.NET MAUI). Esta interfaz ayuda a almacenar preferences de aplicación en un almacén de clave y valor.

La implementación predeterminada de la interfaz IPreferences está disponible a través de la propiedad Preferences.Default. Tanto la interfaz IPreferences como la clase Preferences están contenidas en el espacio de nombres Microsoft.Maui.Storage.

Tipos de almacenamiento

Preferences se almacenan con una clave String. El valor de una preferencia debe ser uno de los siguientes tipos de datos:

• Boolean
• Double
• Int32
• Single
• Int64
• String
• DateTime

Los valores de DateTime se almacenan en un formato binario de 64 bits (entero largo) mediante dos métodos definidos por la clase DateTime:

• El método ToBinary se usa para codificar el valor DateTime.
• El método FromBinary descodifica el valor.

Consulta la documentación de estos métodos para obtener los ajustes que se podrían realizar en los valores descodificados cuando se almacena un valor DateTime que no es de hora universal coordinada (UTC).

Establezca preferences

Preferences se establecen llamando al método Preferences.Set, proporcionando la clave y el valor:

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

Para recuperar un valor de preferences, pasa la clave de la preferencia, seguida del valor predeterminado cuando la clave no exista:

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

En algunos casos, es posible que tengas que pasar la clave de la preferencia, seguida del valor predeterminado y su tipo:

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

Comprobar una clave

Puede ser útil comprobar si existe una clave en preferences o no. Aunque Get haya establecido un valor predeterminado cuando la clave no existe, puede haber casos en los que existía la clave, pero el valor de la clave coincidía con el valor predeterminado. Por lo tanto, no puedes confiar en el valor predeterminado como un indicador de que la clave no existe. Usa el método ContainsKey para determinar si una clave existe:

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

Eliminación de una o todas las claves

Usa el método Remove para quitar una clave específica de preferences:

Preferences.Default.Remove("first_name");

Para quitar todas las claves, usa el método Clear:

Preferences.Default.Clear();

Claves compartidas

Solo tu aplicación puede ver los elementos preferences almacenados en ella. Pero también puedes crear una preferencia compartida que pueden usar otras extensiones o una aplicación de inspección. Al establecer, quitar o recuperar una preferencia, se puede proporcionar un parámetro de cadena opcional para especificar el nombre del contenedor en el que se almacena la preferencia.

Los métodos siguientes toman un parámetro de cadena denominado sharedName:

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

Importante

Lee los detalles de implementación de la plataforma, ya que los elementos preferences compartidos tienen implementaciones específicas del comportamiento.

Integración con la configuración del sistema

Preferences se almacenan de forma nativa, lo que permite integrar la configuración en la configuración nativa del sistema. Siga la documentación de la plataforma para integrar con la plataforma:

• Apple: Implementación de un lote de configuración de iOS
• Android: Introducción a las pantallas de configuración

Diferencias entre plataformas

En esta sección se describen las diferencias específicas de la plataforma con la API de preferences.

Android

Todos los datos se almacenan en preferencias compartidasPreferences. Si no se especifica ninguna sharedName, se usarán las compartidasPreferences predeterminadas. De lo contrario, el nombre se usa para obtener Preferences compartidas privadas con el nombre especificado.

iOS/Mac Catalyst

NSUserDefaults se usa para almacenar valores en dispositivos iOS. Si no se especifica sharedName, se usa StandardUserDefaults. De lo contrario, se usará el nombre para crear una nueva NSUserDefaults con el nombre especificado que se usa para el NSUserDefaultsType.SuiteName.

Windows

ApplicationDataContainer se usa para almacenar los valores en el dispositivo. Si no se especifica sharedName, se usa LocalSettings. De lo contrario, el nombre se usa para crear un nuevo contenedor dentro de LocalSettings.

LocalSettings restringe los nombres de las claves de preferencia a 255 caracteres o menos. Cada valor puede tener un tamaño máximo de 8 KB y cada valor compuesto puede tener un tamaño máximo de 64 KB.

Persistencia

La desinstalación de la aplicación hace que se quiten todos los elementos preferences, excepto cuando la aplicación se ejecuta en Android 6.0 (nivel de API 23) o posterior, mientras se usa la característica Copia de seguridad automática. Esta característica está activada de forma predeterminada y conserva los datos de aplicación, incluidas las Preferences compartidas, que son las que usa la API Preferences. Se puede deshabilitar si se sigue la documentación de copia de seguridad automática de Google.

Limitaciones

El rendimiento puede verse afectado si se almacena grandes cantidades de texto, ya que la API se diseñó para almacenar pequeñas cantidades de texto.