Preferences

Artigo
09/24/2024

Este artigo descreve como você pode usar a interface do usuário do aplicativo .NET multiplataforma (.NET MAUI) IPreferences. Essa interface ajuda a armazenar as preferences do aplicativo em um repositório de chave/valor.

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

Tipos de armazenamento

Preferences são armazenados com uma chave String. O valor de uma preferência precisa 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 método ToBinary é usado para codificar o valor DateTime.
O método FromBinary decodifica o valor.

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

Defina preferences

Preferences são definidos chamando o método Preferences.Set, fornecendo a chave e o 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 preferences

Para recuperar um valor das preferences, passe a chave da preferência, seguida pelo valor padrão quando a chave não existir:

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

Em alguns cenários, pode ser necessário passar a chave da preferência, seguida pelo valor padrão e seu tipo:

long value = Preferences.Get("master_date", (long)0);

Verificar se há uma chave

Pode ser útil verificar se existe uma chave nas preferences ou não. Embora Get faça com que você defina um valor padrão quando a chave não existe, pode haver casos em que a chave existia, mas o valor da chave correspondia 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 método ContainsKey para determinar se uma chave existe:

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

Remover uma ou todas as chaves

Use o método Remove para remover uma chave específica das preferences:

Preferences.Default.Remove("first_name");

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

Preferences.Default.Clear();

Chaves compartilhadas

As preferences armazenadas pelo aplicativo só são visíveis para seu aplicativo. No entanto, você também pode criar uma preferência compartilhada que pode ser usada por outras extensões ou um aplicativo de inspeçã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 no qual a preferência é armazenada.

Os métodos a seguir levam 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 preferences compartilhadas têm implementações específicas a cada comportamento

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

Preferences 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 para se integrar à plataforma:

Apple: Implementando um pacote de configurações do iOS
Android: Introdução às telas de configurações

Diferenças de plataforma

Esta seção descreve as diferenças específicas da plataforma com a API preferences.

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

ApplicationDataContainer é usado para armazenar os valores no dispositivo. Se nenhum sharedName for especificado, os LocalSettings serão usados. Caso contrário, o nome é usado para criar um contêiner dentro de LocalSettings.

LocalSettings restringe os nomes de chave de preferência, permitindo 255 caracteres ou menos. Cada valor de preferência pode ter até 8K bytes de tamanho, e cada configuração composta pode ter até 64K bytes de tamanho.

Persistência

Desinstalar o aplicativo faz com que todas as preferences sejam removidas, exceto quando o aplicativo é executado no Android 6.0 (nível da API 23) ou mais recente, ao usar o recurso de Backup Automático. Esse recurso está ativado por padrão e preserva os dados do aplicativo, incluindo Preferences Compartilhadas, que é o que a API Preferences usa. Você pode desabilitar isso seguindo a documentação do Backup Automático do Google.

Limitações

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

Compartilhar via