Поделиться через


ApplicationData Класс

Определение

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

public ref class ApplicationData sealed
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
/// [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
[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
Public NotInheritable Class ApplicationData
Implements IDisposable
Наследование
Object Platform::Object IInspectable ApplicationData
Атрибуты
Реализации

Требования к 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

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

Применяется к

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