Salvar e carregar configurações em um aplicativo UWP

Este tópico aborda o que você precisa saber para começar a carregar e salvar configurações em um aplicativo UWP (Plataforma Universal do Windows). As APIs principais são introduzidas e os links são fornecidos para ajudá-lo a saber mais.

Use as configurações para lembrar os aspectos personalizáveis pelo usuário do seu aplicativo. Por exemplo, um leitor de notícias pode usar configurações de aplicativo para salvar quais fontes de notícias exibir e qual fonte usar para ler artigos.

Examinaremos 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 preferências do usuário e estado do aplicativo.

Os seguintes tipos de dados podem ser usados com configurações: inteiros, duplos, flutuantes, caracteres, strings, pontos, datas e horas e muito mais. Você também pode armazenar instâncias da classe ApplicationDataCompositeValue , 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 devem ser salvos/restaurados como uma única unidade. Isso impede que uma configuração saia da sincronização com a outra devido ao acesso simultâneo, como entre o programa principal e uma tarefa em segundo plano.

Aqui estão as principais APIs que você precisa saber para salvar ou carregar as configurações do aplicativo:

• Windows.Storage.ApplicationData.Current.LocalSettings obtém o contêiner de configurações do aplicativo do armazenamento de dados locais do aplicativo. As configurações armazenadas aqui são mantidas no dispositivo.
• Windows.Storage.ApplicationData.Current.RoamingSettings obtém o contêiner de configurações de aplicativo da loja de dados de aplicativo de roaming. As configurações armazenadas aqui não são mais móveis (a partir do Windows 11), mas o repositório de configurações ainda está disponível. A substituição recomendada para RoamingSettings é Azure App Service. O Serviço de Aplicativo do Azure é amplamente compatível, bem documentado, confiável e dá suporte a cenários entre plataformas/ecossistemas, como iOS, Android e Web.
• Windows.Storage.ApplicationDataContainer é um contêiner que representa as configurações do aplicativo como pares chave/valor. Use essa classe para criar e recuperar valores de configuração.
• Windows.Storage.ApplicationDataCompositeValue representa várias 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

Para esta introdução, nos concentraremos em dois cenários simples: salvar e carregar uma configuração de aplicativo simples e salvar e carregar uma configuração de tamanho de fonte/fonte composta.

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;

Para salvar uma configuração, primeiro obtenha um objeto ApplicationDataContainer no armazenamento local de dados de configurações com Windows.Storage.ApplicationData.Current.LocalSettings. Os pares de dicionário chave/valor atribuídos a essa instância são salvos no armazenamento de dados de configuração do dispositivo local.

No snippet de código acima, um ApplicationDataCompositeValue armazena vários pares chave/valor. Os valores compostos são úteis quando você tem várias configurações que não devem sair de sincronia entre si. Quando você salva um ApplicationDataCompositeValue, os valores são salvos e carregados como uma unidade, de forma atômica. Dessa forma, as configurações relacionadas não sairão da sincronização.

Carregar configurações do 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 de ApplicationDataContainer para o armazenamento de dados das configurações locais com Windows.Storage.ApplicationData.Current.LocalSettings. Em seguida, use-o para recuperar pares chave/valor. Se os dados não estiverem presentes, você obterá um objeto nulo. Em C#, isso significa que o 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 repositório de dados de configurações locais. Se os dados não estiverem presentes, você obterá um ApplicationDataContainer nulo. É por isso que há uma verificação if (composite != null) no código de exemplo acima.

APIs e documentos úteis

Aqui está um resumo rápido das APIs e outras documentações úteis para ajudar você a começar a salvar e carregar as configurações do aplicativo.

APIs úteis

Documentos úteis

Exemplos de código úteis