ApplicationData Classe

Definição

Namespace:

Windows.Storage

Fornece acesso ao armazenamento de dados do aplicativo. Os dados do aplicativo consistem em arquivos e configurações locais, móveis ou temporários.

public ref class ApplicationData sealed : IClosable

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
class ApplicationData final : IClosable

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
public sealed class ApplicationData : System.IDisposable

Public NotInheritable Class ApplicationData
Implements IDisposable

Herança

Object Platform::Object IInspectable ApplicationData

Atributos

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implementações

IClosable IDisposable

Requisitos do Windows

Família de dispositivos	Windows 10 (introduzida na 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduzida na v1.0)

Exemplos

O exemplo de código a seguir demonstra como ler ou gravar em uma pasta ApplicationData de sua escolha. Este exemplo usa o LocalFolder, mas o código pode ser ligeiramente modificado para acessar o LocalCacheFolder, RoamingFolder, SharedLocalFolder ou TemporaryFolder com base em como seus dados devem ser armazenados. SharedLocalFolder tem algumas restrições e precisa de permissões especiais para acessar, para obter mais informações, consulte SharedLocalFolder.

// This example code can be used to read or write to an ApplicationData folder of your choice.

// Change this to Windows.Storage.StorageFolder roamingFolder = Windows.Storage.ApplicationData.Current.RoamingFolder;
// to use the RoamingFolder instead, for example.
Windows.Storage.StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;

// Write data to a file
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(DateTime.Now));
}

// Read data from a file
async Task ReadTimestamp()
{
    try
    {
        StorageFile sampleFile = await localFolder.GetFileAsync("dataFile.txt");
        String timestamp = await FileIO.ReadTextAsync(sampleFile);
        // Data is contained in timestamp
    }
    catch (FileNotFoundException e)
    {
        // Cannot find file
    }
    catch (IOException e)
    {
        // Get information from the exception, then throw
        // the info to the parent method.
        if(e.Source != null)
        {
            Debug.WriteLine("IOException source: {0}", e.Source);
        }
        throw;
    }
}

#include <winrt/Windows.Globalization.h>
#include <winrt/Windows.Globalization.DateTimeFormatting.h>
#include <winrt/Windows.Storage.h>

using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Storage;
using namespace Windows::UI::Xaml;

// This example code can be used to read or write to an ApplicationData folder of your choice.

// Change this to StorageFolder m_localFolder{ Windows::Storage::ApplicationData::Current().RoamingFolder() }; to 
// use the RoamingFolder instead, for example.
StorageFolder m_localFolder{ Windows::Storage::ApplicationData::Current().LocalFolder() };

// Write data to a file.
IAsyncAction MainPage::WriteTimestampAsync()
{
    StorageFile sampleFile{ co_await m_localFolder.CreateFileAsync(L"dataFile.txt", CreationCollisionOption::ReplaceExisting) };
    Windows::Globalization::Calendar calendar;
    auto now = calendar.GetDateTime();
    Windows::Globalization::DateTimeFormatting::DateTimeFormatter formatter{ L"longtime" };

    try
    {
        co_await FileIO::WriteTextAsync(sampleFile, formatter.Format(now));
    }
    catch (winrt::hresult_error const& /* ex */)
    {
        // Timestamp not written.
    }
}

// Read data from a file.
IAsyncAction MainPage::ReadTimestampAsync()
{
    StorageFile file{ co_await m_localFolder.GetFileAsync(L"dataFile.txt") };

    try
    {
        winrt::hstring timestamp{ co_await Windows::Storage::FileIO::ReadTextAsync(file) };
    }
    catch (winrt::hresult_error const& /* ex */)
    {
        // Timestamp not read.
    }
}

IAsyncAction MainPage::ClickHandler(IInspectable const&, RoutedEventArgs const&)
{
    myButton().Content(box_value(L"Clicked"));

    co_await WriteTimestampAsync();
    co_await ReadTimestampAsync();
}

// This example code can be used to read or write to an ApplicationData folder of your choice.

// Change this to StorageFolder^ roamingFolder = ApplicationData::Current->RoamingFolder; to 
// use the RoamingFolder instead, for example.
StorageFolder^ localFolder = ApplicationData::Current->LocalFolder;

// Write data to a file
void MainPage::WriteTimestamp()
{
   concurrency::task<StorageFile^> fileOperation = 
       localFolder->CreateFileAsync("dataFile.txt", CreationCollisionOption::ReplaceExisting);
   fileOperation.then([this](StorageFile^ sampleFile)
   {
      auto calendar = ref new Calendar;
      auto now = calendar->ToDateTime();
      auto formatter = ref new Windows::Globalization::DateTimeFormatting::DateTimeFormatter("longtime");

      return FileIO::WriteTextAsync(sampleFile, formatter->Format(now));
   }).then([this](task<void> previousOperation) {
      try {
         previousOperation.get();
      } catch (Platform::Exception^) {
         // Timestamp not written
      }
   });
}

// Read data from a file
void MainPage::ReadTimestamp()
{
   concurrency::task<StorageFile^> getFileOperation(localFolder->GetFileAsync("dataFile.txt"));
   getFileOperation.then([this](StorageFile^ file)
   {
      return FileIO::ReadTextAsync(file);
   }).then([this](concurrency::task<String^> previousOperation) {
      String^ timestamp;

      try {
         // Data is contained in timestamp
         timestamp = previousOperation.get();
      } catch (...) {
         // Timestamp not found
      }
   });
}

' This example code can be used to read or write to an ApplicationData folder of your choice.

' Change this to Dim roamingFolder As Windows.Storage.StorageFolder = Windows.Storage.ApplicationData.Current.RoamingFolder
' to use the RoamingFolder instead, for example.
Dim localFolder As Windows.Storage.StorageFolder = Windows.Storage.ApplicationData.Current.LocalFolder

' Write data to a file
Private Async Sub WriteTimestamp()
   Dim formatter As DateTimeFormatter = New DateTimeFormatter("longtime")

   Dim sampleFile As StorageFile = Await localFolder.CreateFileAsync("dataFile.txt", 
       CreationCollisionOption.ReplaceExisting)
   Await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTime.Now));
End Sub

' Read data from a file
Private Async Function ReadTimestamp() As Task
   Try
      Dim sampleFile As StorageFile = Await localFolder.GetFileAsync("dataFile.txt")
      Dim timestamp As string = Await FileIO.ReadTextAsync(sampleFile)
      ' Data is contained in timestamp
   Catch e1 As Exception
      ' Timestamp not found
   End Try
End Function

Para obter mais exemplos e informações sobre leitura e gravação em um arquivo, consulte Criar, gravar e ler um arquivo.

Comentários

Tipos de dados do aplicativo

O ApplicationData fornece armazenamento local, móvel e temporário para dados de aplicativo por usuário. Use essa classe para preservar dados específicos do aplicativo entre sessões, usuários e em vários dispositivos.

ApplicationData não fornece acesso a arquivos em um pacote de aplicativos. Para fazer isso, use Windows.ApplicationModel.Package.InstalledLocation.

ApplicationData.Current fornece a instância ApplicationData do aplicativo. Use essa instância para obter pastas ou configurações de aplicativo.

As pastas são usadas para armazenar dados do aplicativo como arquivos no sistema de arquivos. As configurações do aplicativo são armazenadas em pares chave/valor que podem ser organizados em conjuntos aninhados. Os dados de configurações são salvos no Registro do Windows.

Estes são os tipos main de dados do aplicativo:

• Local: armazenado no dispositivo, backup na nuvem e persiste entre atualizações
• LocalCache: dados persistentes que existem no dispositivo atual, não fazem backup e persistem entre atualizações
• SharedLocal: persistente entre todos os usuários do aplicativo
• Roaming: existe em todos os dispositivos em que o usuário instalou o aplicativo
• Temporário: pode ser excluído pelo sistema a qualquer momento

Usando pastas de aplicativo

LocalFolder persiste entre atualizações e recebe backup na nuvem como parte do backup do dispositivo. Normalmente, essa pasta deve ser usada para dados de usuário que seriam perdidos se não fossem copiados em backup. Alguns exemplos de dados armazenados em LocalFolder são:

• um desenho de usuário para um aplicativo de arte
• histórico de exercícios diários para um aplicativo de fitness
• uma lista de compras para um aplicativo todo Armazenando informações no LocalFolder, o usuário não perderá dados depois de redefinir o dispositivo ou alternar para um novo dispositivo. Para outros tipos de dados locais que são fáceis de recriar e não são necessários para backup e restauração, use o LocalCacheFolder ou o TemporaryFolder.

LocalCacheFolder e TemporaryFolder são armazenados localmente e não têm backup na nuvem. LocalCacheFolder está sob controle desse aplicativo e é persistente entre as sessões de aplicativo. LocalCacheFolder deve ser usado para o conteúdo gerado necessário em sessões de aplicativo, como arquivos armazenados em cache, logs ou tokens de autenticação. O TemporaryFolder não tem garantia de ser persistente entre as sessões e pode ser excluído pelo sistema a qualquer momento.

O RoamingFolder normalmente é usado para preferências do usuário e personalizações, links e arquivos de dados pequenos. O conteúdo do RoamingFolder percorre os dispositivos e instâncias do aplicativo do usuário. RoamingFolder não deve ser usado para grandes quantidades de dados, dados específicos de um dispositivo ou dados que dependem da sincronização instantânea.

Outra pasta, SharedLocalFolder, é persistente entre contas de usuário do aplicativo e deve ser usada para arquivos grandes acessados por vários usuários. Há alguma configuração extra necessária para acessar SharedLocalFolder. Para obter mais informações sobre como acessar e usar essa pasta, consulte SharedLocalFolder.

Você pode armazenar os dados do aplicativo em formatos com versão específicos do aplicativo. Para obter mais informações, consulte Versão e SetVersionAsync.

Para obter mais detalhes sobre como usar essas APIs, consulte Armazenar e recuperar configurações e outros dados do aplicativo.

Propriedades

Current	Fornece acesso ao repositório de dados do aplicativo associado ao pacote de aplicativos do aplicativo.
LocalCacheFolder	Obtém a pasta no repositório de dados do aplicativo local em que você pode salvar arquivos que não estão incluídos no backup e na restauração.
LocalFolder	Obtém a pasta raiz no armazenamento de dados do aplicativo local. Essa pasta faz backup na nuvem.
LocalSettings	Obtém o contêiner de configurações do aplicativo no armazenamento de dados do aplicativo local.
RoamingFolder	Obtém a pasta raiz no armazenamento de dados do aplicativo móvel.
RoamingSettings	Obtém o contêiner de configurações do aplicativo no armazenamento de dados do aplicativo móvel.
RoamingStorageQuota	Obtém o tamanho máximo dos dados que podem ser sincronizados com a nuvem do armazenamento de dados do aplicativo móvel.
SharedLocalFolder	Obtém a pasta raiz no armazenamento de dados do aplicativo compartilhado.
TemporaryFolder	Obtém a pasta raiz no armazenamento de dados de aplicativo temporário.
Version	Obtém o número de versão dos dados do aplicativo no armazenamento de dados do aplicativo.

Métodos

ClearAsync()	Remove todos os dados do aplicativo dos armazenamentos de dados de aplicativos locais, móveis e temporários. Observação O método ClearAsync() encontrará um erro se houver identificadores de arquivo abertos. Você deve ter o cuidado de fechar todos os arquivos abertos antes de chamar ClearAsync.
ClearAsync(ApplicationDataLocality)	Remove todos os dados do aplicativo do armazenamento de dados do aplicativo especificado. Observação O método ClearAsync(ApplicationDataLocality) encontrará um erro se houver identificadores de arquivo abertos. Você deve ter o cuidado de fechar todos os arquivos abertos antes de chamar ClearAsync.
ClearPublisherCacheFolderAsync(String)	Limpa os arquivos e subpastas da subpasta especificada da pasta de armazenamento compartilhado para o editor do aplicativo atual.
Close()	Observação Esse membro não é implementado em C#.
Dispose()	Realiza tarefas definidas pelo aplicativo associadas à liberação ou à redefinição de recursos não gerenciados.
GetForUserAsync(User)	Método estático que retorna o ApplicationData para um usuário.
GetPublisherCacheFolder(String)	Obtém a subpasta especificada da pasta de armazenamento compartilhado para o editor do aplicativo atual.
SetVersionAsync(UInt32, ApplicationDataSetVersionHandler)	Define o número de versão dos dados do aplicativo no armazenamento de dados do aplicativo.
SignalDataChanged()	Envia um evento DataChanged para todos os manipuladores de eventos registrados.

Eventos

DataChanged

Ocorre quando os dados do aplicativo móvel são sincronizados.

Confira também

• ApplicationDataCompositeValue
• ApplicationDataContainer
• ApplicationDataContainerSettings
• Armazene e recupere configurações e outros dados de aplicativo
• Diretrizes de dados de aplicativo em roaming
• Diretrizes para configurações de aplicativos
• Exemplo de configurações de aplicativo (Windows 8.1, Windows Phone 8.1)
• Amostra de dados de aplicativos