Salvar e carregar configurações em um aplicativo UWP

Este tópico cobre o que precisa de saber para começar a carregar e guardar definições numa aplicação da Plataforma Universal do Windows (UWP). As principais APIs são apresentadas e links são fornecidos para ajudá-lo a saber mais.

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

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

O que precisa de 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 configurações: inteiros, duplos, floats, chars, strings, Points, DateTimes e muito mais. Também pode armazenar instâncias da classe ApplicationDataCompositeValue, o que é útil quando existem várias definiçõ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 seu aplicativo devem ser salvos/restaurados como uma única unidade. Isso evita que uma configuração fique fora de sincronia 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 contentor de definições da aplicação da loja local de dados de aplicações. As definições aqui guardadas são mantidas no dispositivo e mantêm-se de forma fiável através das atualizações da aplicação.
• Windows. Storage.ApplicationData.Current.RoamingSettings obtém o contentor de definições da aplicação da loja de dados de roaming. As definições guardadas aqui já não sincronizam desde o Windows 11, mas o armazenamento de definições continua disponível. A substituição recomendada para RoamingSettings é Serviço de Aplicações do Azure. O Serviço de Aplicações do Azure é amplamente suportado, bem documentado, fiável e suporta cenários multiplataforma/ecossistema como iOS, Android e web.
• Windows. Storage.ApplicationDataContainer é um contentor que representa as definições da aplicação como pares chave/valor. Use essa classe para criar e recuperar valores de configuração.
• Windows. Storage.ApplicationDataCompositeValue representa múltiplas definições de aplicação que devem ser serializadas como uma unidade. Isso é útil quando uma configuração não deve ser atualizada independentemente de outra.

Guardar definições da aplicação

Para esta introdução, vamos nos concentrar 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;

Guarde uma configuração obtendo primeiro um ApplicationDataContainer para o armazenamento de dados das configurações locais com Windows.Storage.ApplicationData.Current.LocalSettings. Os pares de dicionário chave/valor atribuídos a esta instância são salvos no armazenamento de dados de configuração de dispositivo local.

No trecho 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 ficar fora de sincronia umas com as outras. Quando você salva um ApplicationDataCompositeValue, os valores são salvos e carregados como uma unidade ou atomicamente. Desta forma, as configurações relacionadas não sairão de sincronia.

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 definição obtendo primeiro uma instância de ApplicationDataContainer para o repositório de dados de definições local 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 composta seguindo um padrão similar. Acesse pares chave/valor a partir do armazenamento de dados de configurações locais. Se os dados não estiverem presentes, obterá um valor nulo em ApplicationDataContainer. É 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 outra documentação útil para ajudá-lo a começar a salvar e carregar as configurações do aplicativo.

APIs úteis

Documentos úteis

Exemplos de código úteis