Preferences

Browse sample. Navegue pelo exemplo

Este artigo descreve como você pode usar a interface .NET Multi-platform App UI (.NET MAUI). IPreferences Essa interface ajuda a armazenar preferências de aplicativo em um armazenamento de chave/valor.

A implementação padrão da interface está disponível por meio da IPreferencesPreferences.Default propriedade. A interface e Preferences a IPreferences classe estão contidas no Microsoft.Maui.Storage namespace.

Tipos de armazenamento

Preferences são armazenados com uma String chave. O valor de uma preferência deve ser um dos seguintes tipos de dados:

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 ToBinary método é usado para codificar o DateTime valor.
  • O FromBinary método decodifica o valor.

Consulte a documentação desses métodos para obter os ajustes que podem ser feitos em valores decodificados quando um é armazenado que não é um DateTime valor UTC (Tempo Universal Coordenado).

Definir preferências

Preferences são definidos chamando o método, fornecendo a chave e o Preferences.Set valor:

// Set a string value:
Preferences.Default.Set("first_name", "John");

// Set an numerical value:
Preferences.Default.Set("age", 28);

// Set a boolean value:
Preferences.Default.Set("has_pets", true);

Obter preferências

Para recuperar um valor das preferências, você passa a chave da preferência, seguida pelo valor padrão quando a chave não existe:

string firstName = Preferences.Default.Get("first_name", "Unknown");
int age = Preferences.Default.Get("age", -1);
bool hasPets = Preferences.Default.Get("has_pets", false);

Verificar se há uma chave

Pode ser útil verificar se existe uma chave nas preferências ou não. Mesmo que Get você tenha definido um valor padrão quando a chave não existe, pode haver casos em que a chave existiu, mas o valor da chave correspondeu ao valor padrão. Portanto, você não pode confiar no valor padrão como um indicador de que a chave não existe. Use o ContainsKey método para determinar se existe uma chave:

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

Remover uma ou todas as teclas

Use o Remove método para remover uma chave específica das preferências:

Preferences.Default.Remove("first_name");

Para remover todas as chaves, use o Clear método:

Preferences.Default.Clear();

Chaves compartilhadas

As preferências armazenadas pelo seu aplicativo só ficam visíveis para ele. No entanto, você também pode criar uma preferência compartilhada que pode ser usada por outras extensões ou um aplicativo de observação. Quando você define, remove ou recupera uma preferência, um parâmetro de cadeia de caracteres opcional pode ser fornecido para especificar o nome do contêiner em que a preferência está armazenada.

Os métodos a seguir usam um parâmetro de cadeia de caracteres chamado sharedName:

  • Preferences.Set
  • Preferences.Get
  • Preferences.Remove
  • Preferences.Clear

Importante

Leia as especificações de implementação da plataforma, pois as preferências compartilhadas têm implementações específicas de comportamento

Integração com as configurações do sistema

Preferences são armazenados nativamente, o que permite que você integre suas configurações nas configurações nativas do sistema. Siga a documentação e os exemplos da plataforma para integrar com a plataforma:

Diferenças de plataforma

Esta seção descreve as diferenças específicas da plataforma com a API de preferências.

Todos os dados são armazenados em Compartilhado Preferences. Se nenhum sharedName for especificado, os Compartilhados Preferences padrão serão usados. Caso contrário, o nome será usado para obter um Compartilhado Preferences privado com o nome especificado.

Persistência

A desinstalação do aplicativo faz com que todas as preferências sejam removidas, exceto quando o aplicativo é executado no Android 6.0 (API nível 23) ou posterior, ao usar o recurso Backup automático. Esse recurso está ativado por padrão e preserva os dados do aplicativo, incluindo Compartilhado Preferences, que é o que a Preferences API usa. Você pode desativar isso seguindo a documentação do Backup automático do Google.

Limitações

O desempenho pode ser afetado se você armazenar grandes quantidades de texto, pois a API foi projetada para armazenar pequenas quantidades de texto.