Salvar e carregar configurações em um aplicativo UWP

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). As APIs principais são introduzidas e os links são fornecidos para ajudar você a aprender mais.

Use as configurações para lembrar os aspectos personalizáveis pelo usuário de seu aplicativo. 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.

Veremos o código para salvar e carregar as configurações do aplicativo.

O que você precisa saber

Use as configurações do aplicativo para armazenar dados de configuração, como as preferências do usuário e o estado do aplicativo.

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. 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. 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. Isso impede que uma configuração saia de sincronia com a outra devido ao acesso simultâneo, como entre o programa principal e uma tarefa em segundo plano.

Veja as principais APIs que você precisa conhecer para salvar ou carregar configurações do aplicativo:

  • Windows.Storage.ApplicationData.Current.LocalSettings obtém o contêiner de configurações do aplicativo do armazenamento de dados de aplicativo local. As configurações armazenadas aqui são mantidas no dispositivo.
  • Windows.Storage.ApplicationData.Current.RoamingSettings obtém o contêiner de configurações do aplicativo do armazenamento de dados do aplicativo em roaming. As configurações armazenadas aqui não usam mais o perfil móvel (a partir do Windows 11), mas o repositório de configurações ainda está disponível. A substituição recomendada para o RoamingSettings é o Serviço de Aplicativo do Azure. O Serviço de Aplicativo do Azure tem amplo suporte, é bem documentado, confiável e dá suporte a cenários multiplataforma/de ecossistema cruzado, como iOS, Android e Web.
  • Windows.Storage.ApplicationDataContainer é um contêiner que representa as configurações de aplicativo como pares chave/valor. Use essa classe para criar e recuperar os valores de configuração.
  • Windows.Storage.ApplicationDataCompositeValue representa diversas configurações de aplicativo que devem ser serializadas como uma unidade. Isso é útil quando uma configuração não deve ser atualizada independentemente de outra.

Salvar configurações do aplicativo

Nesta introdução, abordaremos dois cenários simples: salvar e carregar uma configuração de aplicativo simples e salvar e carregar uma configuração da fonte de composição/tamanho da fonte.

ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;

// Save a setting locally on the device
localSettings.Values["test setting"] = "a device specific setting";

// Save a composite setting locally on the device
Windows.Storage.ApplicationDataCompositeValue composite = new Windows.Storage.ApplicationDataCompositeValue();
composite["Font"] = "Calibri";
composite["FontSize"] = 11;
localSettings.Values["FontInfo"] = composite;

Salve uma configuração obtendo primeiro um ApplicationDataContainer para o armazenamento de dados de configurações local com 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.

No snippet de código acima, um ApplicationDataCompositeValue armazena vários pares de chave/valor. Valores de composição são úteis quando você tem várias configurações que não devem ficar fora de sincronia entre si. Ao salvar um ApplicationDataCompositeValue, os valores são salvos e carregados como uma unidade ou atomicamente. Dessa maneira, as configurações relacionadas não sairão de sincronia.

Carregar configurações de aplicativo

ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;

// load a setting that is local to the device
String localValue = localSettings.Values["test setting"] as string;

// load a composite setting
Windows.Storage.ApplicationDataCompositeValue composite = (ApplicationDataCompositeValue)localSettings.Values["FontInfo"];
if (composite != null)
{
    String fontName = composite["Font"] as string;
    int fontSize = (int)composite["FontSize"];
}

Carregue uma configuração obtendo primeiro uma instância ApplicationDataContainer para o armazenamento de dados de configurações local com Windows.Storage.ApplicationData.Current.LocalSettings. Em seguida, use- a para recuperar pares chave/valor. Se os dados não estiverem presentes, você receberá um objeto nulo. Em C#, isso significa que localValue será null se a configuração não existir.

Carregue uma configuração de composição seguindo um padrão semelhante. Acesse pares chave-valor do armazenamento de dados de configurações locais. Se os dados não estiverem presentes, você receberá um ApplicationDataContainer nulo. Por isso há uma verificação if (composite != null) no código de exemplo acima.

APIs e documentos úteis

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.

APIs úteis

API Descrição
ApplicationData.LocalSettings Obtém o contêiner de configurações do aplicativo do armazenamento de dados do aplicativo local.
ApplicationData.RoamingSettings Obtém o contêiner de configurações do aplicativo do armazenamento de dados do aplicativo em roaming.
ApplicationDataContainer Um contêiner para configurações de aplicativo que dê suporte para criar, excluir, enumerar e percorrer a hierarquia do contêiner.
Namespace Windows.UI.ApplicationSettings Fornece classes que você usará para definir as configurações do aplicativo que aparecem no painel configurações do Shell do Windows.

Documentos úteis

Tópico Descrição
Diretrizes para configurações de aplicativos Descreve as melhores práticas para criar e exibir configurações de aplicativo.
Armazene e recupere configurações e outros dados de aplicativo Passo a passo para salvar e recuperar configurações.

Exemplos de código úteis

Exemplo de código Descrição
Amostra de dados de aplicativos Cenários 2 a 4: foco em configurações