Armazene e recupere definições e outros dados da aplicação

Os dados da aplicação são dados mutáveis que são criados e geridos por uma aplicação específica. Inclui o estado de execução, definições da aplicação, preferências do utilizador, conteúdo de referência (como as definições do dicionário numa aplicação de dicionário) e outras definições. Os dados da aplicação são diferentes dos dados do utilizador, dados que o utilizador cria e gere ao usar uma aplicação. Os dados do utilizador incluem ficheiros de documentos ou multimédia, transcrições de email ou comunicação, ou registos de bases de dados que contêm conteúdos criados pelo utilizador. Os dados dos utilizadores podem ser úteis ou significativos para mais do que uma aplicação. Muitas vezes, trata-se de dados que o utilizador quer manipular ou transmitir como uma entidade independente da própria aplicação, como um documento.

Nota importante sobre os dados da app: A vida útil dos dados da aplicação está ligada à vida útil da aplicação. Se a aplicação for removida, todos os dados da aplicação serão perdidos como consequência. Não uses dados de aplicações para armazenar dados de utilizadores ou qualquer coisa que estes possam considerar valiosa e insubstituível. Recomendamos que as bibliotecas do utilizador e o Microsoft OneDrive sejam usados para armazenar este tipo de informação. Os dados da aplicação são ideais para armazenar preferências, definições e favoritos específicos da aplicação.

Tipos de dados de aplicação

Existem dois tipos de dados de aplicação: definições e ficheiros.

Settings

Use as definições para guardar as preferências do utilizador e informações sobre o estado da aplicação. A API de dados da aplicação permite-lhe criar e recuperar facilmente definições (mostraremos alguns exemplos mais adiante neste artigo).

Aqui estão os tipos de dados que pode usar para as definições da aplicação:

• UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, Double
• Booleano
• Char16, String
• DateTime, TimeSpan
  • Para C#/.NET, use: System.DateTimeOffset, System.TimeSpan
• GUID, Point, Size, Rect
• ApplicationDataCompositeValue: Um conjunto de definições de aplicação relacionadas que devem ser serializadas e deserializadas atomicamente. Use definições compostas para lidar facilmente com atualizações atómicas de definições interdependentes. O sistema assegura a integridade das definições compostas durante o acesso concorrente e o roaming. As definições compostas estão otimizadas para pequenas quantidades de dados, e o desempenho pode ser fraco se as usar para grandes conjuntos de dados.

Ficheiros

Use ficheiros para armazenar dados binários ou para ativar os seus próprios tipos serializados personalizados.

Armazenar dados de aplicações nas lojas de dados de aplicações

Quando uma aplicação é instalada, o sistema dá-lhe os seus próprios armazenamentos de dados por utilizador para definições e ficheiros. Não precisa de saber onde ou como esses dados existem, porque o sistema é responsável por gerir o armazenamento físico, garantindo que os dados são mantidos isolados de outras aplicações e utilizadores. O sistema também preserva o conteúdo destes repositórios de dados quando o utilizador instala uma atualização na sua aplicação e remove o conteúdo desses armazenamentos de forma completa e limpa quando a sua aplicação é desinstalada.

Dentro da sua loja de dados de aplicações, cada aplicação tem diretórios raiz definidos pelo sistema: um para ficheiros locais, um para ficheiros itinerantes e um para ficheiros temporários. A sua aplicação pode adicionar novos ficheiros e novos contentores a cada um destes diretórios raiz.

Dados da aplicação local

Os dados locais da app devem ser usados para qualquer informação que precise de ser preservada entre sessões da app e que não seja adequada para os dados de roaming da aplicação. Dados que não são aplicáveis noutros dispositivos também devem ser armazenados aqui. Não existe uma restrição geral de tamanho para os dados locais armazenados. Use a loja local de dados de aplicações para dados que não faz sentido fazer roaming e para conjuntos de dados grandes.

Recuperar o armazenamento local de dados de aplicativos

Antes de poder ler ou escrever dados locais da app, deve recuperar o armazenamento de dados local da app. Para recuperar a loja local de dados da aplicação, use a propriedade ApplicationData.LocalSettings para obter as definições locais da aplicação como um objeto ApplicationDataContainer. Use a propriedade ApplicationData.LocalFolder para obter os ficheiros num objeto StorageFolder. Use a propriedade ApplicationData.LocalCacheFolder para obter a pasta na loja local de dados da aplicação, onde pode guardar ficheiros que não estão incluídos no backup e restaurar.

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

Crie e recupere uma configuração local simples

Para criar ou escrever uma definição, use a propriedade ApplicationDataContainer.Values para aceder às definições do localSettings contentor que obtivemos na etapa anterior. Este exemplo cria um cenário chamado exampleSetting.

// Simple setting

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

Para recuperar a definição, usa a mesma propriedade ApplicationDataContainer.Values que usou para criar a definição. Este exemplo mostra como recuperar a definição que acabámos de criar.

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

Crie e recupere um valor composto local

Para criar ou escrever um valor composto, crie um objeto ApplicationDataCompositeValue. Este exemplo cria uma configuração composta nomeada exampleCompositeSetting e adiciona-a ao localSettings contentor.

// 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 acabámos 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"]
}

Crie e leia um ficheiro local

Para criar e atualizar um ficheiro na loja de dados de aplicações local, utilize as APIs de ficheiros, como Windows. Storage.StorageFolder.CreateFileAsync e Windows. Storage.FileIO.WriteTextAsync. Este exemplo cria um ficheiro nomeado dataFile.txt no localFolder contentor e escreve a data e hora atuais no ficheiro. O valor ReplaceExisting da enumeração CreationCollisionOption indica a substituição do ficheiro se este 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 ficheiro na loja de dados de aplicações local, utilize as APIs de ficheiros, como Windows. Storage.StorageFolder.GetFileAsync, Windows. Storage.StorageFile.GetFileFromApplicationUriAsync e Windows. Storage.FileIO.ReadTextAsync. Este exemplo abre o dataFile.txt ficheiro criado no passo anterior e lê a data do ficheiro. Para detalhes sobre o carregamento de recursos de ficheiros a partir de várias localizações, consulte Como carregar recursos de ficheiros.

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 da aplicação

A loja de dados temporária de aplicações funciona como uma cache. Os seus ficheiros não fazem roaming e podem ser removidos a qualquer momento. A tarefa de Manutenção do Sistema pode eliminar automaticamente os dados armazenados neste local a qualquer momento. O utilizador pode também limpar ficheiros do armazenamento temporário de dados usando a Limpeza de Disco. Os dados temporários da aplicação podem ser usados para armazenar informação temporária durante uma sessão da aplicação. Não há garantia de que estes dados persistam para além do final da sessão da aplicação, pois o sistema pode recuperar o espaço utilizado se necessário. A localização está disponível através da propriedade temporaryFolder .

Recuperar o contentor temporário de dados

Use a propriedade ApplicationData.TemporaryFolder para obter os ficheiros. Os passos seguintes usam a temporaryFolder variável deste passo.

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

Criar e ler ficheiros temporários

Para criar e atualizar um ficheiro na loja de dados temporária da aplicação, utilize as APIs de ficheiros, como Windows. Storage.StorageFolder.CreateFileAsync e Windows. Storage.FileIO.WriteTextAsync. Este exemplo cria um ficheiro nomeado dataFile.txt no temporaryFolder contentor e escreve a data e hora atuais no ficheiro. O valor ReplaceExisting da enumeração CreationCollisionOption indica a substituição do ficheiro se este 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 ficheiro na loja de dados temporária da aplicação, utilize as APIs de ficheiros, como Windows. Storage.StorageFolder.GetFileAsync, Windows. Storage.StorageFile.GetFileFromApplicationUriAsync e Windows. Storage.FileIO.ReadTextAsync. Este exemplo abre o dataFile.txt ficheiro criado no passo anterior e lê a data do ficheiro. Para detalhes sobre o carregamento de recursos de ficheiros a partir de várias localizações, consulte Como carregar recursos de ficheiros.

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 os dados da aplicação com contentores

Para o ajudar a organizar as definições e ficheiros dos dados da sua aplicação, cria contentores (representados por objetos ApplicationDataContainer) em vez de trabalhar diretamente com diretórios. Pode adicionar contentores às lojas de dados de aplicações locais, de roaming e temporárias. Os contentores podem ser aninhados até 32 níveis de profundidade.

Para criar um contentor de definições, chame o método ApplicationDataContainer.CreateContainer . Este exemplo cria um contentor de definições locais chamado exampleContainer e adiciona uma definição chamada exampleSetting. O valor Always da enumeração ApplicationDataCreateDisposition indica que o contentor foi 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";
}

Eliminar definições e contentores da aplicação

Para eliminar uma configuração simples que a sua aplicação já não precisa, use o método ApplicationDataContainerSettings.Remove . Este exemplo elimina a exampleSetting configuração local que criámos 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 eliminar uma configuração composta, utilize o método ApplicationDataCompositeValue.Remove . Este exemplo elimina a definição composta local exampleCompositeSetting que criámos num 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 eliminar um contentor, chame o método ApplicationDataContainer.DeleteContainer . Este exemplo elimina o contentor de definições locais exampleContainer que criámos anteriormente.

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

// Delete container

localSettings.DeleteContainer("exampleContainer");

Versionamento dos dados da sua aplicação

Pode opcionalmente versionar os dados da aplicação para a sua aplicação. Isto permitir-lhe-ia criar uma versão futura da sua aplicação que altere o formato dos seus dados sem causar problemas de compatibilidade com a versão anterior. A aplicação verifica a versão dos dados na loja de dados e, se a versão for inferior à que a esperada, a aplicação deve atualizar os dados para o novo formato e atualizar a versão. Para 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