Xamarin.Essentials:Preferências

  • Artigo

A classe Preferences ajuda a armazenar as preferências do aplicativo em um repositório de chave/valor.

Introdução

Para começar a usar essa API, leia o guia de introdução para Xamarin.Essentials garantir que a biblioteca esteja instalada e configurada corretamente em seus projetos.

Como usar Preferences

Adicione uma referência a Xamarin.Essentials em sua classe:

using Xamarin.Essentials;

Para salvar um valor de uma determinada chave nas preferências:

Preferences.Set("my_key", "my_value");

Para recuperar um valor das preferências, ou um padrão, se não for definido:

var myValue = Preferences.Get("my_key", "default_value");

Para marcar se uma determinada chave existir nas preferências:

bool hasKey = Preferences.ContainsKey("my_key");

Para remover a chave das preferências:

Preferences.Remove("my_key");

Para remover todas as preferências:

Preferences.Clear();

Dica

Os métodos acima recebem um parâmetro opcional string chamado sharedName. Esse parâmetro é usado para criar contêineres adicionais para preferências que são úteis em alguns casos de uso. Um caso de uso é quando seu aplicativo precisa compartilhar preferências entre extensões ou com um aplicativo watch. Leia as especificações de implementação da plataforma abaixo.

Tipos de dados com suporte

Os tipos de dados a seguir têm suporte em Preferences:

  • bool
  • double
  • int
  • float
  • longo
  • cadeia de caracteres
  • DateTime

Integrar-se às Configurações do Sistema

As preferências são armazenadas nativamente, o que permite que você integre suas configurações às configurações do sistema nativo. Siga a documentação da plataforma e os exemplos para se integrar à plataforma:

Detalhes da implementação

Os valores de DateTime são armazenados em um formato binário de 64 bits (inteiro longo) usando dois métodos definidos pela classe DateTime: o método ToBinary é usado para codificar o valor DateTime e o método FromBinary decodifica o valor. Confira a documentação desses métodos para conhecer os ajustes que podem ser feitos em valores decodificados ao armazenar um DateTime que não seja um valor UTC (Tempo Universal Coordenado).

Particularidades de implementação da plataforma

Todos os dados são armazenados em Preferências Compartilhadas. Se não sharedName for especificado, as preferências compartilhadas padrão serão usadas, caso contrário, o nome será usado para obter preferências compartilhadas privadas com o nome especificado.

Persistência

A desinstalação do aplicativo fará com que todas as Preferências sejam removidas, com exceção de aplicativos direcionados e executados no Android 6.0 (nível de API 23) ou posterior que usam o Backup Automático. Esse recurso está ativado por padrão e preserva os dados do aplicativo, incluindo Preferências Compartilhadas, que é o que a API de Preferências utiliza. É possível desabilitar isso seguindo a documentação do Google.

Limitações

Ao armazenar uma cadeia de caracteres, essa API destina-se a armazenar pequenas quantidades de texto. O desempenho pode ser abaixo da média se você tentar usá-lo para armazenar grandes quantidades de texto.

API

Encontre mais vídeos sobre o Xamarin no Channel 9 e no YouTube.