ApplicationData Класс

Определение

Пространство имен:

Windows.Storage

Предоставляет доступ к хранилищу данных приложения. Данные приложения состоят из файлов и параметров, которые являются локальными, перемещаемыми или временными.

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

Наследование

Object Platform::Object IInspectable ApplicationData

Атрибуты

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Реализации

IClosable IDisposable

Требования к Windows

Семейство устройств	Windows 10 (появилось в 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (появилось в v1.0)

Примеры

В следующем примере кода показано, как выполнять чтение или запись в папку ApplicationData по своему усмотрению. В этом примере используется LocalFolder, но код можно немного изменить для доступа к LocalCacheFolder, RoamingFolder, SharedLocalFolder или TemporaryFolder в зависимости от способа хранения данных. SharedLocalFolder имеет некоторые ограничения и требует специальных разрешений для доступа. Дополнительные сведения см. в статье 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

Дополнительные примеры и сведения о чтении и записи в файл см. в статье Создание, запись и чтение файла.

Комментарии

Типы данных приложения

ApplicationData предоставляет локальное, перемещаемое и временное хранилище для данных приложения на уровне пользователя. Используйте этот класс для сохранения данных приложения между сеансами, пользователями и на нескольких устройствах.

ApplicationData не предоставляет доступ к файлам в пакете приложения. Для этого используйте Windows.ApplicationModel.Package.InstalledLocation.

ApplicationData.Current предоставляет экземпляр ApplicationData приложения. Используйте этот экземпляр для получения папок или параметров приложения.

Папки используются для хранения данных приложения в файловой системе в виде файлов. Параметры приложения хранятся в парах "ключ-значение", которые можно упорядочить во вложенные наборы. Данные параметров сохраняются в реестре Windows.

Ниже перечислены main типы данных приложения.

• Локальный: хранится на устройстве, выполняется резервное копирование в облаке и сохраняется в разных обновлениях.
• LocalCache: постоянные данные, которые существуют на текущем устройстве, не архивируются и сохраняются между обновлениями.
• SharedLocal: постоянная для всех пользователей приложения
• Роуминг: существует на всех устройствах, на которых пользователь установил приложение.
• Временный: может быть удален системой в любое время.

Использование папок приложений

LocalFolder сохраняется между обновлениями и создает резервную копию в облаке как часть резервного копирования устройства. Как правило, эту папку следует использовать для пользовательских данных, которые будут потеряны, если не создать резервную копию. Ниже приведены некоторые примеры данных, хранящихся в LocalFolder .

• рисунок пользователя для приложения изобразительного искусства
• ежедневная история упражнений для фитнес-приложения
• список покупок для приложения дел. Сохраняя сведения в LocalFolder, пользователь не потеряет данные после сброса устройства или переключения на новое устройство. Для других типов локальных данных, которые легко воссоздать и которые не нужны для резервного копирования и восстановления, используйте LocalCacheFolder или TemporaryFolder.

LocalCacheFolder и TemporaryFolder хранятся локально и не архивируются в облаке. LocalCacheFolder находится под контролем этого приложения и сохраняется в сеансах приложения. LocalCacheFolder следует использовать для создания содержимого, необходимого в сеансах приложения, например кэшированных файлов, журналов или маркеров проверки подлинности. Функция TemporaryFolder не гарантирует, что она будет постоянной в разных сеансах и может быть удалена системой в любое время.

RoamingFolder обычно используется для пользовательских настроек и настроек, ссылок и небольших файлов данных. Содержимое RoamingFolder перемещается между устройствами и экземплярами приложения пользователя. RoamingFolder не следует использовать для больших объемов данных, данных, относящихся к устройству, или данных, которые зависят от мгновенной синхронизации.

Другая папка , SharedLocalFolder, сохраняется в учетных записях пользователей приложений и должна использоваться для больших файлов, к которым обращаются несколько пользователей. Для доступа к SharedLocalFolder требуется дополнительная настройка. Дополнительные сведения о доступе и использовании этой папки см. в статье SharedLocalFolder.

Данные приложения можно хранить в форматах с версиями для конкретного приложения. Дополнительные сведения см. в разделе Version и SetVersionAsync.

Дополнительные сведения об использовании этих API см. в статье Хранение и извлечение параметров и других данных приложения.

Свойства

Current	Предоставляет доступ к хранилищу данных приложения, связанному с пакетом приложения.
LocalCacheFolder	Возвращает папку в локальном хранилище данных приложения, в которой можно сохранять файлы, не включенные в резервное копирование и восстановление.
LocalFolder	Возвращает корневую папку в локальном хранилище данных приложения. Резервная копия этой папки выполняется в облаке.
LocalSettings	Возвращает контейнер параметров приложения в локальном хранилище данных приложения.
RoamingFolder	Возвращает корневую папку в перемещаемом хранилище данных приложения.
RoamingSettings	Возвращает контейнер параметров приложения в перемещаемом хранилище данных приложения.
RoamingStorageQuota	Возвращает максимальный размер данных, которые можно синхронизировать с облаком из перемещаемого хранилища данных приложения.
SharedLocalFolder	Возвращает корневую папку в общем хранилище данных приложения.
TemporaryFolder	Возвращает корневую папку во временном хранилище данных приложения.
Version	Возвращает номер версии данных приложения в хранилище данных приложения.

Методы

ClearAsync()	Удаляет все данные приложения из локальных, перемещаемых и временных хранилищ данных приложений. Примечание Метод ClearAsync() обнаруживает ошибку при наличии открытых дескрипторов файлов. Перед вызовом ClearAsync необходимо закрыть все открытые файлы.
ClearAsync(ApplicationDataLocality)	Удаляет все данные приложения из указанного хранилища данных приложения. Примечание Метод ClearAsync(ApplicationDataLocality) вызывает ошибку при наличии открытых дескрипторов файлов. Перед вызовом ClearAsync необходимо закрыть все открытые файлы.
ClearPublisherCacheFolderAsync(String)	Очищает файлы и вложенные папки из указанной вложенной папки общего хранилища для издателя текущего приложения.
Close()	Примечание Этот элемент не реализован в C#.
Dispose()	Выполняет определяемые приложением задачи, связанные с удалением, высвобождением или сбросом неуправляемых ресурсов.
GetForUserAsync(User)	Статический метод, возвращающий ApplicationData для пользователя.
GetPublisherCacheFolder(String)	Возвращает указанную вложенную папку общего хранилища для издателя текущего приложения.
SetVersionAsync(UInt32, ApplicationDataSetVersionHandler)	Задает номер версии данных приложения в хранилище данных приложения.
SignalDataChanged()	Отправляет событие DataChanged всем зарегистрированным обработчикам событий.

События

DataChanged

Происходит при синхронизации перемещаемых данных приложения.

См. также раздел

• ApplicationDataCompositeValue
• ApplicationDataContainer
• ApplicationDataContainerSettings
• Хранение и извлечение параметров и прочих данных приложения
• Руководство по перемещаемым данным приложения
• Руководство по параметрам приложений
• Пример параметров приложения (Windows 8.1, Windows Phone 8.1)
• Пример данных приложения