Armazenar e recuperar configurações e outros dados do aplicativo

Os dados do aplicativo são dados mutáveis criados e gerenciados por um aplicativo específico. Ele inclui estado de runtime, configurações de aplicativo, preferências do usuário, conteúdo de referência (como as definições de dicionário em um aplicativo de dicionário) e outras configurações. Os dados do aplicativo são diferentes dos dados do usuário, dados que o usuário cria e gerencia ao usar um aplicativo. Os dados do usuário incluem arquivos de documentos ou de mídia, transcrições de email ou comunicação ou registros de banco de dados que contêm o conteúdo criado pelo usuário. Os dados do usuário podem ser úteis ou significativos para mais de um aplicativo. Geralmente, esses são dados que o usuário deseja manipular ou transmitir como uma entidade independente do próprio aplicativo, como um documento.

Observação importante sobre os dados do aplicativo: O tempo de vida dos dados do aplicativo está vinculado ao tempo de vida do aplicativo. Se o aplicativo for removido, todos os dados do aplicativo serão perdidos como consequência. Não use dados do aplicativo para armazenar dados do usuário ou qualquer coisa que os usuários possam perceber como valiosos e insubstituíveis. Recomendamos que as bibliotecas e Microsoft OneDrive do usuário sejam usadas para armazenar esse tipo de informação. Os dados do aplicativo são ideais para armazenar preferências, configurações e favoritos do usuário específicos do aplicativo.

Tipos de dados do aplicativo

Há dois tipos de dados de aplicativo: configurações e arquivos.

Settings

Use as configurações para armazenar as preferências do usuário e as informações de estado do aplicativo. A API de dados do aplicativo permite que você crie e recupere facilmente as configurações (mostraremos alguns exemplos posteriormente neste artigo).

Aqui estão os tipos de dados que você pode usar para configurações de aplicativo:

• UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, Double
• Boolean
• Char16, String
• DateTime, TimeSpan
  • Para C#/.NET, use: System.DateTimeOffset, System.TimeSpan
• GUIDPoint, Size, Rect
• ApplicationDataCompositeValue: um conjunto de configurações de aplicativo relacionadas que devem ser serializadas e desserializadas atomicamente. Utilize configurações de composição para lidar facilmente com atualizações atômicas de configurações interdependentes. O sistema garante a integridade das configurações combinadas durante o acesso simultâneo e o roaming. As configurações de composição são otimizadas para pequenas quantidades de dados e o desempenho pode ser ruim se você usá-las para grandes conjuntos de dados.

Arquivos

Use arquivos para armazenar dados binários ou para habilitar seus próprios tipos serializados personalizados.

Armazenando dados do aplicativo nas lojas de dados do aplicativo

Quando um aplicativo é instalado, o sistema fornece seus próprios armazenamentos de dados por usuário para configurações e arquivos. Você não precisa saber onde ou como esses dados existem, pois o sistema é responsável pelo gerenciamento do armazenamento físico, garantindo que os dados sejam mantidos isolados de outros aplicativos e outros usuários. O sistema geralmente preserva o conteúdo desses armazenamentos de dados quando o usuário instala uma atualização em seu aplicativo, embora RoamingSettings possa não persistir por meio de atualizações Microsoft Store (consulte Roaming data). Para configurações que devem sobreviver às atualizações do aplicativo, use LocalSettings. O sistema remove o conteúdo desses armazenamentos de dados de forma completa e limpa quando seu aplicativo é desinstalado.

No armazenamento de dados do aplicativo, cada aplicativo tem diretórios raiz definidos pelo sistema: um para arquivos locais, um para arquivos móveis e outro para arquivos temporários. Seu aplicativo pode adicionar novos arquivos e novos contêineres a cada um desses diretórios raiz.

Dados do aplicativo local

Os dados do aplicativo local devem ser usados para qualquer informação que precise ser preservada entre sessões de aplicativo e não seja adequada para dados de aplicativo móvel. Os dados que não são aplicáveis em outros dispositivos também devem ser armazenados aqui. Não há nenhuma restrição de tamanho geral nos dados locais armazenados. Armazene os dados no armazenamento local do aplicativo para informações que não faz sentido sincronizar e para grandes conjuntos de dados. Os dados locais do aplicativo persistem de forma confiável através de atualizações do aplicativo, tornando as ConfiguraçõesLocais a opção recomendada para preferências do usuário e estado do aplicativo que devem sobreviver às atualizações da Microsoft Store.

Recuperar o repositório de dados do aplicativo local

Antes de ler ou gravar dados do aplicativo local, você deve recuperar o repositório de dados do aplicativo local. Para recuperar o armazenamento de dados do aplicativo local, use a propriedade ApplicationData.LocalSettings para obter as configurações locais do aplicativo como um objeto ApplicationDataContainer. Use a propriedade ApplicationData.LocalFolder para obter os arquivos em um objeto StorageFolder. Use a propriedade ApplicationData.LocalCacheFolder para obter a pasta no repositório de dados do aplicativo local, onde você pode salvar arquivos que não estão incluídos no backup e na restauração.

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

Criar e recuperar uma configuração local simples

Para criar ou gravar uma configuração, use a propriedade ApplicationDataContainer.Values para acessar as configurações no localSettings contêiner que obtivemos na etapa anterior. Este exemplo cria uma configuração chamada exampleSetting.

// Simple setting

localSettings.Values["exampleSetting"] = "Hello Windows";

Para recuperar a configuração, use a mesma propriedade ApplicationDataContainer.Values usada para criar a configuração. Este exemplo mostra como recuperar a configuração que acabamos de criar.

// Simple setting
Object value = localSettings.Values["exampleSetting"];

Criar e recuperar um valor composto local

Para criar ou gravar um valor composto, crie um objeto ApplicationDataCompositeValue. Este exemplo cria uma configuração de composição nomeada exampleCompositeSetting e a adiciona ao localSettings contêiner.

// Composite setting

Windows.Storage.ApplicationDataCompositeValue composite = 
    new Windows.Storage.ApplicationDataCompositeValue();
composite["intVal"] = 1;
composite["strVal"] = "string";

localSettings.Values["exampleCompositeSetting"] = composite;

Este exemplo mostra como recuperar o valor composto que acabamos de criar.

// Composite setting

Windows.Storage.ApplicationDataCompositeValue composite = 
   (Windows.Storage.ApplicationDataCompositeValue)localSettings.Values["exampleCompositeSetting"];

if (composite == null)
{
   // No data
}
else
{
   // Access data in composite["intVal"] and composite["strVal"]
}

Criar e ler um arquivo local

Para criar e atualizar um arquivo no armazenamento de dados do aplicativo local, use as APIs de arquivo, como Windows. Storage.StorageFolder.CreateFileAsync e Windows. Storage.FileIO.WriteTextAsync. Este exemplo cria um arquivo nomeado dataFile.txt no localFolder contêiner e grava a data e a hora atuais no arquivo. O valor ReplaceExisting da enumeração CreationCollisionOption indica substituir o arquivo se ele já existir.

async void WriteTimestamp()
{
   Windows.Globalization.DateTimeFormatting.DateTimeFormatter formatter = 
       new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("longtime");

   StorageFile sampleFile = await localFolder.CreateFileAsync("dataFile.txt", 
       CreationCollisionOption.ReplaceExisting);
   await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTimeOffset.Now));
}

Para abrir e ler um arquivo no repositório de dados do aplicativo local, use as APIs de arquivo, como Windows. Storage.StorageFolder.GetFileAsync, Windows. Storage.StorageFile.GetFileFromApplicationUriAsync e Windows. Storage.FileIO.ReadTextAsync. Este exemplo abre o dataFile.txt arquivo criado na etapa anterior e lê a data do arquivo. Para obter detalhes sobre como carregar recursos de arquivos de vários locais, consulte Como carregar recursos de arquivo.

async void ReadTimestamp()
{
   try
   {
      StorageFile sampleFile = await localFolder.GetFileAsync("dataFile.txt");
      String timestamp = await FileIO.ReadTextAsync(sampleFile);
      // Data is contained in timestamp
   }
   catch (Exception)
   {
      // Timestamp not found
   }
}

Dados de roaming

Dados temporários do aplicativo

O repositório de dados de aplicativo temporário funciona como um cache. Seus arquivos não vagam e podem ser removidos a qualquer momento. A tarefa Manutenção do Sistema pode excluir automaticamente os dados armazenados nesse local a qualquer momento. O usuário também pode limpar arquivos do repositório de dados temporário usando a Limpeza de Disco. Os dados temporários do aplicativo podem ser usados para armazenar informações temporárias durante uma sessão de aplicativo. Não há nenhuma garantia de que esses dados persistirão além do final da sessão do aplicativo, pois o sistema poderá recuperar o espaço usado, se necessário. O local está disponível por meio da propriedade temporaryFolder.

Recuperar o contêiner de dados temporários

Use a propriedade ApplicationData.TemporaryFolder para obter os arquivos. As próximas etapas usam a temporaryFolder variável desta etapa.

Windows.Storage.StorageFolder temporaryFolder = ApplicationData.Current.TemporaryFolder;

Criar e ler arquivos temporários

Para criar e atualizar um arquivo no armazenamento de dados de aplicativo temporário, use as APIs de arquivo, como Windows. Storage.StorageFolder.CreateFileAsync e Windows. Storage.FileIO.WriteTextAsync. Este exemplo cria um arquivo nomeado dataFile.txt no temporaryFolder contêiner e grava a data e a hora atuais no arquivo. O valor ReplaceExisting da enumeração CreationCollisionOption indica substituir o arquivo se ele já existir.

async void WriteTimestamp()
{
   Windows.Globalization.DateTimeFormatting.DateTimeFormatter formatter = 
       new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("longtime");

   StorageFile sampleFile = await temporaryFolder.CreateFileAsync("dataFile.txt", 
       CreateCollisionOption.ReplaceExisting);
   await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTimeOffset.Now));
}

Para abrir e ler um arquivo no repositório de dados de aplicativo temporário, use as APIs de arquivo, como Windows. Storage.StorageFolder.GetFileAsync, Windows. Storage.StorageFile.GetFileFromApplicationUriAsync e Windows. Storage.FileIO.ReadTextAsync. Este exemplo abre o dataFile.txt arquivo criado na etapa anterior e lê a data do arquivo. Para obter detalhes sobre como carregar recursos de arquivos de vários locais, consulte Como carregar recursos de arquivo.

async void ReadTimestamp()
{
   try
   {
      StorageFile sampleFile = await temporaryFolder.GetFileAsync("dataFile.txt");
      String timestamp = await FileIO.ReadTextAsync(sampleFile);
      // Data is contained in timestamp
   }
   catch (Exception)
   {
      // Timestamp not found
   }
}

Organizar dados do aplicativo com contêineres

Para ajudá-lo a organizar as configurações e os arquivos de dados do aplicativo, crie contêineres (representados por objetos ApplicationDataContainer) em vez de trabalhar diretamente com diretórios. Você pode adicionar contêineres aos armazenamentos de dados de aplicativos locais, móveis e temporários. Os contêineres podem ser aninhados com até 32 níveis de profundidade.

Para criar um contêiner de configurações, chame o método ApplicationDataContainer.CreateContainer . Este exemplo cria um contêiner de configurações local chamado exampleContainer e adiciona uma configuração chamada exampleSetting. O valor Always da enumeração ApplicationDataCreateDisposition indica que o contêiner será criado se ainda não existir.

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

// Setting in a container
Windows.Storage.ApplicationDataContainer container = 
   localSettings.CreateContainer("exampleContainer", Windows.Storage.ApplicationDataCreateDisposition.Always);

if (localSettings.Containers.ContainsKey("exampleContainer"))
{
   localSettings.Containers["exampleContainer"].Values["exampleSetting"] = "Hello Windows";
}

Excluir contêineres e configurações de aplicativo

Para excluir uma configuração simples de que seu aplicativo não precisa mais, use o método ApplicationDataContainerSettings.Remove . Este exemplo exclui a exampleSetting configuração local que criamos anteriormente.

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

// Delete simple setting

localSettings.Values.Remove("exampleSetting");

Para excluir uma configuração de composição, use o método ApplicationDataCompositeValue.Remove . Este exemplo exclui a configuração de composição local exampleCompositeSetting que criamos em um exemplo anterior.

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

// Delete composite setting

localSettings.Values.Remove("exampleCompositeSetting");

Para excluir um contêiner, chame o método ApplicationDataContainer.DeleteContainer . Este exemplo exclui o contêiner de configurações locais exampleContainer que criamos anteriormente.

Windows.Storage.ApplicationDataContainer localSettings = 
    Windows.Storage.ApplicationData.Current.LocalSettings;
Windows.Storage.StorageFolder localFolder = 
    Windows.Storage.ApplicationData.Current.LocalFolder;

// Delete container

localSettings.DeleteContainer("exampleContainer");

Controle de versão dos dados do aplicativo

Opcionalmente, você pode fazer a versão dos dados do aplicativo para seu aplicativo. Isso permitiria que você criasse uma versão futura do aplicativo que alterasse o formato dos dados do aplicativo sem causar problemas de compatibilidade com a versão anterior do aplicativo. O aplicativo verifica a versão dos dados do aplicativo no armazenamento de dados e, se a versão for menor do que a versão esperada pelo aplicativo, o aplicativo deverá atualizar os dados do aplicativo para o novo formato e atualizar a versão. Para obter mais informações, consulte a propriedadeApplication.Version e o método ApplicationData.SetVersionAsync .

Artigos relacionados

• Windows.Storage.ApplicationData
• Windows.Storage.ApplicationData.RoamingSettings
• Windows.Storage.ApplicationData.RoamingFolder
• Windows.Storage.ApplicationData.RoamingStorageQuota
• Windows.Storage.ApplicationDataCompositeValue