Salvar e carregar configurações em um aplicativo UWPSave and load settings in a UWP app

Este tópico aborda o que você precisa saber para começar a carregar, salvar configurações em um aplicativo UWP (Plataforma Universal do Windows).This topic covers what you need to know to get started loading, and saving, settings in a Universal Windows Platform (UWP) app. As APIs principais são introduzidas e os links são fornecidos para ajudar você a aprender mais.The main APIs are introduced, and links are provided to help you learn more.

Use as configurações para lembrar os aspectos personalizáveis pelo usuário de seu aplicativo.Use settings to remember the user-customizable aspects of your app. Por exemplo, um leitor de notícias pode usar as configurações do aplicativo para salvar as fontes de notícias para exibição e qual fonte será usada para ler artigos.For example, a news reader could use app settings to save which news sources to display and what font to use for reading articles.

Vamos examinar o código para salvar e carregar as configurações do aplicativo, incluindo as configurações locais e em roaming.We’ll look at code to save and load app settings, including local and roaming settings.

O que você precisa saberWhat do you need to know

Use as configurações do aplicativo para armazenar dados de configuração, como as preferências do usuário e o estado do aplicativo.Use app settings to store configuration data such as user preferences and app state. Configurações específicas do dispositivo são armazenadas localmente.Settings that are specific to the device are stored locally. Configurações que se aplicam a qualquer dispositivo no qual o aplicativo está instalado são armazenadas no armazenamento de dados de roaming.Settings that apply on whichever device your app is installed on are stored in the roaming data store. Configurações fazem roaming entre os dispositivos nos quais o usuário está conectado com a mesma Conta Microsoft e têm a mesma versão do aplicativo instalado.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.

Os seguintes tipos de dados podem ser usados com as configurações: inteiros, duplicatas, flutuações, caracteres, cadeias de caracteres, pontos, DateTimes e muito mais.The following data types can be used with settings: integers, doubles, floats, chars, strings, Points, DateTimes, and more. Você também pode armazenar instâncias da classe ApplicationDataCompositeValue, o que é útil quando há várias configurações que devem ser tratadas como uma unidade.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 exemplo, um nome de fonte e um tamanho de ponto para exibir texto no painel de leitura do aplicativo deve ser salvo/restaurado como uma única unidade.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. Isso impede que uma configuração fique fora de sincronia com a outra devido a atrasos de roaming de uma configuração antes da outra.This prevents one setting from getting out of sync with the other due to delays in roaming one setting before the other.

Veja as principais APIs que você precisa conhecer para salvar ou carregar configurações do aplicativo:Here are the main APIs you need to know about to save or load app settings:

Salvar configurações do aplicativoSave app settings

Para essa introdução, destacaremos dois cenários simples: salvar e carregar um aplicativo definindo localmente e fazer o roaming da configuração de fonte composta/tamanho da fonte 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;

Salve uma configuração no dispositivo local obtendo primeiro um ApplicationDataContainer para o armazenamento de dados de configurações local com 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. Os pares de dicionário de chave/valor que você atribuir a essa instância serão salvos no armazenamento de dados de configuração do dispositivo local.Key/value dictionary pairs that you assign to this instance are saved in the local device setting data store.

Salve uma configuração de roaming usando um padrão semelhante.Save a roaming setting using a similar pattern. Primeiro obtenha ApplicationDataContainer para o armazenamento de dados de configurações de roaming com Windows.Storage.ApplicationData.Current.RoamingSettings.First get an ApplicationDataContainer for the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. Em seguida, atribua pares de chave/valor a essa instância.Then assign key/value pairs to this instance. Os pares chave/valor serão compartilhados automaticamente entre dispositivos.Those key/value pairs will automatically roam between devices.

No snippet de código acima, uma ApplicationDataCompositeValue armazena vários pares chave/valor.In the code snippet above, a ApplicationDataCompositeValue stores multiple key/value pairs. Valores de composição são úteis quando você tem várias configurações que não devem ficar fora de sincronia entre si.Composite values are useful when you have multiple settings that shouldn't get out of sync with each other. Ao salvar um ApplicationDataCompositeValue, os valores são salvos e carregados como uma unidade ou atomicamente.When you save a ApplicationDataCompositeValue, the values are saved and loaded as a unit, or atomically. Assim, as configurações relacionadas não ficam fora de sincronia, pois fazem roaming como uma unidade em vez de individualmente.This way settings that are related won't get out of sync because they are roamed as a unit instead of individually.

Carregar configurações de aplicativoLoad 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"];
}

Carregue uma configuração usando o dispositivo local obtendo primeiro uma instância ApplicationDataContainer do armazenamento de dados de configurações locais com 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. Em seguida, use- a para recuperar pares chave/valor.Then use it to retrieve key/value pairs.

Carregue uma configuração de roaming seguindo um padrão semelhante.Load a roaming setting by following a similar pattern. Primeiro obtenha uma instância ApplicationDataContainer para o armazenamento de dados de configurações de roaming com Windows.Storage.ApplicationData.Current.RoamingSettings.First get an ApplicationDataContainer instance from the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. Acesse pares de chave/valor dessa instância.Access key/value pairs from that instance. Se os dados ainda não foram movidos para o dispositivo usado para acessar as configurações, você receberá um 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. Por isso há uma verificação if (composite != null) no código de exemplo acima.That's why there is a if (composite != null) check in the example code above.

APIs e documentos úteisUseful APIs and docs

Veja um resumo rápido de APIs e outras documentações úteis para ajudar você a começar a salvar e carregar configurações de aplicativo.Here is a quick summary of APIs, and other useful documentation, to help get you started saving and loading app settings.

APIs úteisUseful APIs

APIAPI DescriçãoDescription
ApplicationData.LocalSettingsApplicationData.LocalSettings Obtém o contêiner de configurações do aplicativo do armazenamento de dados do aplicativo local.Gets the application settings container from the local app data store.
ApplicationData.RoamingSettingsApplicationData.RoamingSettings Obtém o contêiner de configurações do aplicativo do armazenamento de dados do aplicativo em roaming.Gets the application settings container from the roaming app data store.
ApplicationDataContainerApplicationDataContainer Um contêiner para configurações de aplicativo que dê suporte para criar, excluir, enumerar e percorrer a hierarquia do contêiner.A container for app settings that supports creating, deleting, enumerating, and traversing the container hierarchy.
Namespace Windows.UI.ApplicationSettingsWindows.UI.ApplicationSettings Namespace Fornece classes que você usará para definir as configurações do aplicativo que aparecem no painel configurações do Shell do Windows.Provides classes that you'll use to define the app settings that appear in the settings pane of the Windows shell.

Documentos úteisUseful docs

TópicoTopic DescriçãoDescription
Diretrizes para configurações de aplicativosGuidelines for app settings Descreve as melhores práticas para criar e exibir configurações de aplicativo.Describes best practices for creating and displaying app settings.
Armazene e recupere configurações e outros dados de aplicativoStore and retrieve settings and other app data Passo a passo para salvar e recuperar configurações, incluindo configurações de roaming.Walk-through for saving and retrieving settings, including roaming settings.

Exemplos de código úteisUseful code samples

Exemplo de códigoCode sample DescriçãoDescription
Amostra de dados de aplicativosApplication data sample Cenários 2 a 4: foco em configuraçõesScenarios 2-4 focus on settings