Guardar y cargar la configuración en una aplicación para UWPSave and load settings in a UWP app

En este tema se explica lo que necesita saber para comenzar a cargar y guardar configuraciones en una aplicación de la Plataforma universal de Windows (UWP).This topic covers what you need to know to get started loading, and saving, settings in a Universal Windows Platform (UWP) app. Se presentan las API principales y se proporcionan vínculos que le ayudarán a obtener más información.The main APIs are introduced, and links are provided to help you learn more.

Use la configuración para recordar los aspectos personalizables de su aplicación.Use settings to remember the user-customizable aspects of your app. Por ejemplo, un lector de noticias podría usar la configuración de la aplicación para guardar qué fuentes de noticias se mostrarán y qué fuente se usará para leer artículos.For example, a news reader could use app settings to save which news sources to display and what font to use for reading articles.

Veremos el código para guardar y cargar la configuración de la aplicación, incluida la configuración local y de itinerancia.We’ll look at code to save and load app settings, including local and roaming settings.

Qué debe saberWhat do you need to know

Use la configuración de la aplicación para guardar datos de configuración como las preferencias del usuario y el estado de la aplicación.Use app settings to store configuration data such as user preferences and app state. La configuración específica del dispositivo se almacena localmente.Settings that are specific to the device are stored locally. Las configuraciones que se aplican en cualquier dispositivo en el que esté instalada su aplicación se almacenan en el almacén de datos de itinerancia.Settings that apply on whichever device your app is installed on are stored in the roaming data store. La configuración es móvil entre dispositivos en los que el usuario ha iniciado sesión con la misma cuenta de Microsoft y tiene instalada la misma versión de la aplicación.Settings are roamed between devices on which the user is signed in with the same Microsoft Account and have the same version of the app installed.

Se pueden usar los siguientes tipos de datos con la configuración: enteros, dobles, controles flotantes, caracteres, cadenas, puntos, fechas y horas, etc.The following data types can be used with settings: integers, doubles, floats, chars, strings, Points, DateTimes, and more. También puede almacenar instancias de la clase ApplicationDataCompositeValue que es útil cuando hay varias opciones de configuración que deben tratarse como una unidad.You can also store instances of the ApplicationDataCompositeValue class which is useful when there are multiple settings that should be treated as a unit. Por ejemplo, un tamaño de fuente y un tamaño de punto para mostrar texto en el panel de lectura de su aplicación se deben guardar y restaurar como una sola unidad.For example, a font name and point size for displaying text in the reading pane of your app should be saved/restored as a single unit. Esto impide que una configuración pierda la sincronización con la otra debido a retrasos en la itinerancia de una configuración antes de la otra.This prevents one setting from getting out of sync with the other due to delays in roaming one setting before the other.

Estas son las principales API que debe conocer para guardar o cargar la configuración de la aplicación:Here are the main APIs you need to know about to save or load app settings:

Guardar configuración de la aplicaciónSave app settings

Para esta introducción, nos centraremos en dos escenarios sencillos: guardar y cargar una configuración de aplicación localmente, y realizar la itinerancia de una configuración de tamaño de fuente o fuente compuesta entre dispositivos.For this introduction, we will focus on two simple scenarios: saving and loading an app setting locally, and roaming a composite font/font size setting between devices.

// Save a setting locally on the device
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
localSettings.Values["test setting"] = "a device specific setting";

// Save a composite setting that will be roamed between devices
ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;
Windows.Storage.ApplicationDataCompositeValue composite = new Windows.Storage.ApplicationDataCompositeValue();
composite["Font"] = "Calibri";
composite["FontSize"] = 11;
roamingSettings.Values["RoamingFontInfo"] = composite;

Para guardar una configuración en el dispositivo local, obtenga primero un ApplicationDataContainer para el almacén de datos de configuración local con Windows.Storage.ApplicationData.Current.LocalSettings.Save a setting to the local device, by first getting an ApplicationDataContainer for the local settings data store with Windows.Storage.ApplicationData.Current.LocalSettings. Los pares de diccionario clave/valor que asigna a esta instancia se guardan en el almacén de datos de configuración de dispositivo local.Key/value dictionary pairs that you assign to this instance are saved in the local device setting data store.

Guarda una configuración de itinerancia con una trama similar.Save a roaming setting using a similar pattern. Obtenga primero un ApplicationDataContainer para el almacén de datos de configuración de itinerancia con Windows.Storage.ApplicationData.Current.RoamingSettings.First get an ApplicationDataContainer for the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. A continuación, asigne pares clave/valor a esta instancia.Then assign key/value pairs to this instance. Esos pares clave/valor se pasarán automáticamente de un dispositivo a otro.Those key/value pairs will automatically roam between devices.

En el fragmento de código anterior, un ApplicationDataCompositeValue almacena varios pares clave/valor.In the code snippet above, a ApplicationDataCompositeValue stores multiple key/value pairs. Los valores compuestos son útiles cuando tiene varias opciones de configuración que no deberían dejar de sincronizarse entre sí.Composite values are useful when you have multiple settings that shouldn't get out of sync with each other. Cuando guarde un ApplicationDataCompositeValue, los valores se guardan y se cargan como unidad o de forma atómica.When you save a ApplicationDataCompositeValue, the values are saved and loaded as a unit, or atomically. De esta manera, las configuraciones relacionadas no se dejan de sincronizar porque se desplazan como una unidad en lugar de en forma individual.This way settings that are related won't get out of sync because they are roamed as a unit instead of individually.

Cargar configuración de aplicacionesLoad app settings

// load a setting that is local to the device
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
String localValue = localSettings.Values["test setting"] as string;

// load a composite setting that roams between devices
ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;
Windows.Storage.ApplicationDataCompositeValue composite = (ApplicationDataCompositeValue)roamingSettings.Values["RoamingFontInfo"];
if (composite != null)
{
    String fontName = composite["Font"] as string;
    int fontSize = (int)composite["FontSize"];
}

Para cargar una configuración desde el dispositivo local, obtenga primero una instancia de ApplicationDataContainer para el almacén de datos de configuración local con Windows.Storage.ApplicationData.Current.LocalSettings.Load a setting from the local device, by first getting an ApplicationDataContainer instance for the local settings data store with Windows.Storage.ApplicationData.Current.LocalSettings. A continuación, úsela para recuperar pares de clave y valor.Then use it to retrieve key/value pairs.

Para cargar una configuración de itinerancia, siga una trama similar.Load a roaming setting by following a similar pattern. Obtenga primero una instancia de ApplicationDataContainer desde el almacén de datos de configuración de itinerancia con Windows.Storage.ApplicationData.Current.RoamingSettings.First get an ApplicationDataContainer instance from the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. Obtenga acceso a los pares de clave y valor desde esa instancia.Access key/value pairs from that instance. Si los datos no se han pasado aún al dispositivo desde el que está obteniendo acceso a la configuración, obtendrá un valor de ApplicationDataContainer nulo.If the data hasn't roamed yet to the device that you are accessing the settings from, you'll get a null ApplicationDataContainer. Ese es el motivo por el que hay una comprobación if (composite != null) en el código de ejemplo anterior.That's why there is a if (composite != null) check in the example code above.

API y documentos útilesUseful APIs and docs

Este es un resumen rápido de las API y otra documentación útil para ayudarlo a comenzar a guardar y cargar la configuración de la aplicación.Here is a quick summary of APIs, and other useful documentation, to help get you started saving and loading app settings.

API útilesUseful APIs

APIAPI DescripciónDescription
ApplicationData.LocalSettingsApplicationData.LocalSettings Obtiene el contenedor de configuración de la aplicación del almacén de datos de la aplicación local.Gets the application settings container from the local app data store.
ApplicationData.RoamingSettingsApplicationData.RoamingSettings Obtiene el contenedor de configuración de la aplicación del almacén de datos de la aplicación de itinerancia.Gets the application settings container from the roaming app data store.
ApplicationDataContainerApplicationDataContainer Un contenedor para la configuración de la aplicación que soporte crear, eliminar, enumerar y el recorrido de la jerarquía de contenedores.A container for app settings that supports creating, deleting, enumerating, and traversing the container hierarchy.
Windows.UI.ApplicationSettings NamespaceWindows.UI.ApplicationSettings Namespace Proporciona clases que utilizará para definir la configuración de la aplicación que aparece en el panel de configuración del shell de Windows.Provides classes that you'll use to define the app settings that appear in the settings pane of the Windows shell.

Documentos útilesUseful docs

TemaTopic DescripciónDescription
Instrucciones para la configuración de una aplicaciónGuidelines for app settings Describe los procedimientos recomendados para crear y mostrar la configuración de la aplicación.Describes best practices for creating and displaying app settings.
Almacenar y recuperar la configuración y otros datos de aplicaciónStore and retrieve settings and other app data Recorrido para guardar y recuperar la configuración, incluida la configuración de itinerancia.Walk-through for saving and retrieving settings, including roaming settings.

Ejemplos de código útilesUseful code samples

Ejemplo de códigoCode sample DescripciónDescription
Application data sample (ejemplo de datos de aplicaciones)Application data sample Los escenarios 2-4 se centran en la configuraciónScenarios 2-4 focus on settings