Хранение и извлечение параметров и прочих данных приложенияStore and retrieve settings and other app data

Данные приложения являются изменяемыми данными, которые создаются и управляются конкретным приложением.App data is mutable data that is created and managed by a specific app. К ним относятся сведения о состоянии среды выполнения, параметры приложения, пользовательские настройки, справочная информация (например, определения слов в приложении-словаре) и другие параметры.It includes runtime state, app settings, user preferences, reference content (such as the dictionary definitions in a dictionary app), and other settings. Данные приложения – это не то же самое, что данные пользователя , данные, которые пользователь создает и которыми управляет при использовании приложения.App data is different from user data , data that the user creates and manages when using an app. К данным пользователя относятся файлы документов или мультимедиа, текст сообщений электронной почты или записи разговоров, а также записи баз данных, содержимое которых создано пользователем.User data includes document or media files, email or communication transcripts, or database records holding content created by the user. Данные пользователя могут быть полезными или имеющими смысл для нескольких приложений.User data may be useful or meaningful to more than one app. Часто это данные, которые пользователь меняет или передает как объект, не зависящий от самого приложения, например документ.Often, this is data that the user wants to manipulate or transmit as an entity independent of the app itself, such as a document.

Важное примечание о данных приложения Время существования данных приложения привязано ко времени существования приложения.Important note about app data: The lifetime of the app data is tied to the lifetime of the app. Если приложение удалить, все его данные будут потеряны.If the app is removed, all of the app data will be lost as a consequence. Не используйте данные приложения для хранения пользовательских данных или чего-либо ценного и незаменимого с точки зрения пользователей.Don't use app data to store user data or anything that users might perceive as valuable and irreplaceable. Рекомендуется сохранять информацию такого рода в библиотеках пользователя и Microsoft OneDrive.We recommend that the user's libraries and Microsoft OneDrive be used to store this sort of information. Данные приложения идеально подходят для хранения пользовательских настроек, параметров и избранного для приложения.App data is ideal for storing app-specific user preferences, settings, and favorites.

Типы данных приложенийTypes of app data

Существует два типа данных приложений: параметры и файлы.There are two types of app data: settings and files.

SettingsSettings

Параметры используются для сохранения настроек пользователя и данных о состоянии приложения.Use settings to store user preferences and application state info. API данных приложения позволяет с легкостью создавать и восстанавливать параметры (мы покажем вам несколько примеров позже в этой статье).The app data API enables you to easily create and retrieve settings (we'll show you some examples later in this article).

В качестве параметров приложения можно использовать следующие типы данных.Here are data types you can use for app settings:

  • UInt8 , Int16 , UInt16 , Int32 , UInt32 , Int64 , UInt64 , Single , DoubleUInt8 , Int16 , UInt16 , Int32 , UInt32 , Int64 , UInt64 , Single , Double
  • ЛогическийBoolean
  • Char16 , StringChar16 , String
  • DateTime, TimeSpanDateTime, TimeSpan
  • GUID , Point, Size, RectGUID , Point, Size, Rect
  • ApplicationDataCompositeValue Набор связанных параметров приложения, которые необходимо сериализовать и десериализовать атомарным образом.ApplicationDataCompositeValue: A set of related app settings that must be serialized and deserialized atomically. Чтобы с легкостью управлять обновлениями взаимозависимых параметров, выполняемыми как одна неделимая операция, используйте композитные параметры.Use composite settings to easily handle atomic updates of interdependent settings. Система обеспечивает целостность композитных параметров при параллельном доступе и перемещении.The system ensures the integrity of composite settings during concurrent access and roaming. Композитные параметры оптимизированы для малых объемов данных и могут привести к значительному снижению производительности, если использовать их для крупных наборов данных.Composite settings are optimized for small amounts of data, and performance can be poor if you use them for large data sets.

ФайлыFiles

Файлы используют для хранения двоичных данных либо для включения собственных настраиваемых сериализованных типов.Use files to store binary data or to enable your own, customized serialized types.

Хранение данных приложения в хранилищах данных приложенияStoring app data in the app data stores

При установке приложения система выделяет для хранения параметров и файлов отдельные хранилища по количеству пользователей приложения.When an app is installed, the system gives it its own per-user data stores for settings and files. Вам не нужно знать, где или как хранятся эти данные, поскольку что система отвечает за управление физическим хранилищем, обеспечивая хранение этих данных изолированно от других приложений и других пользователей.You don't need to know where or how this data exists, because the system is responsible for managing the physical storage, ensuring that the data is kept isolated from other apps and other users. Система также сохраняет содержимое этих хранилищ данных в случае установки и обновления приложения пользователем, а также полностью удаляет это содержимое в случае удаления приложения.The system also preserves the contents of these data stores when the user installs an update to your app and removes the contents of these data stores completely and cleanly when your app is uninstalled.

В хранилище данных приложения каждое приложение имеет определяемые системой корневые каталоги — по одному для локальных, перемещаемых и временных файлов.Within its app data store, each app has system-defined root directories: one for local files, one for roaming files, and one for temporary files. Ваше приложение может добавлять новые файлы и новые контейнеры в каждый из корневых каталогов.Your app can add new files and new containers to each of these root directories.

Локальные данные приложенияLocal app data

В локальные данные приложения следует помещать информацию, которую нужно сохранить между сеансами приложения, но которая не подходит для перемещаемых данных приложения.Local app data should be used for any information that needs to be preserved between app sessions and is not suitable for roaming app data. Здесь также следует хранить данные, которые не применимы на других устройствах.Data that is not applicable on other devices should be stored here as well. Общего ограничения по размеру сохраненных локальных данных не существует.There is no general size restriction on local data stored. Используйте локальное хранилище данных приложения для данных, которые не имеет смысла перемещать, и для крупных наборов данных.Use the local app data store for data that it does not make sense to roam and for large data sets.

Извлечение локального хранилища данных приложенияRetrieve the local app data store

Прежде чем получить возможность чтения или записи локальных данных приложения, необходимо извлечь локальное хранилище данных приложения.Before you can read or write local app data, you must retrieve the local app data store. Для извлечения локального хранилища данных приложения используйте свойство ApplicationData.LocalSettings, чтобы получить локальные параметры приложения в виде объекта ApplicationDataContainer.To retrieve the local app data store, use the ApplicationData.LocalSettings property to get the app's local settings as an ApplicationDataContainer object. Используйте свойство ApplicationData.LocalFolder для загрузки файлов в объект StorageFolder.Use the ApplicationData.LocalFolder property to get the files in a StorageFolder object. Используйте свойство ApplicationData.LocalCacheFolder, чтобы получить папку в локальном хранилище данных приложения, в которой можно сохранить файлы, которые не включены в резервную копию и копию для восстановления.Use the ApplicationData.LocalCacheFolder property to get the folder in the local app data store where you can save files that are not included in backup and restore.

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

Создание и извлечение простого локального параметраCreate and retrieve a simple local setting

Для создания или записи параметра используйте свойство ApplicationDataContainer.Values для получения доступа к параметрам в контейнере localSettings, полученном на предыдущем этапе.To create or write a setting, use the ApplicationDataContainer.Values property to access the settings in the localSettings container we got in the previous step. В следующем примере создается параметр с именем exampleSetting.This example creates a setting named exampleSetting.

// Simple setting

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

Для извлечения параметра используйте то же свойство ApplicationDataContainer.Values, которое использовалось для создания этого параметра.To retrieve the setting, you use the same ApplicationDataContainer.Values property that you used to create the setting. В этом примере показано, как извлечь только что созданный параметр.This example shows how to retrieve the setting we just created.

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

Создание и извлечение локального составного значенияCreate and retrieve a local composite value

Для создания или записи составного значения создайте объект ApplicationDataCompositeValue.To create or write a composite value, create an ApplicationDataCompositeValue object. В следующем примере составной параметр с именем exampleCompositeSetting создается и добавляется в контейнер localSettings.This example creates a composite setting named exampleCompositeSetting and adds it to the localSettings container.

// Composite setting

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

localSettings.Values["exampleCompositeSetting"] = composite;

В этом примере показано, как извлечь только что созданное составное значение.This example shows how to retrieve the composite value we just created.

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

Создание и чтение локального файлаCreate and read a local file

Для создания и обновления файла в локальном хранилище данных приложения используйте файловые API, например, Windows.Storage.StorageFolder.CreateFileAsync и Windows.Storage.FileIO.WriteTextAsync.To create and update a file in the local app data store, use the file APIs, such as Windows.Storage.StorageFolder.CreateFileAsync and Windows.Storage.FileIO.WriteTextAsync. В следующем примере создается файл с именем dataFile.txt в контейнере localFolder и в этот файл записываются текущие дата и время.This example creates a file named dataFile.txt in the localFolder container and writes the current date and time to the file. Значение ReplaceExisting из перечисления CreationCollisionOption показывает, что, если файл уже существует, его следует заменить.The ReplaceExisting value from the CreationCollisionOption enumeration indicates to replace the file if it already exists.

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));
}

Для открытия и чтения файла в локальном хранилище данных приложения используйте файловые API, например, Windows.Storage.StorageFolder.GetFileAsync, Windows.Storage.StorageFile.GetFileFromApplicationUriAsync и Windows.Storage.FileIO.ReadTextAsync.To open and read a file in the local app data store, use the file APIs, such as Windows.Storage.StorageFolder.GetFileAsync, Windows.Storage.StorageFile.GetFileFromApplicationUriAsync, and Windows.Storage.FileIO.ReadTextAsync. В следующем примере открывается файл dataFile.txt, созданный на предыдущем шаге, и из него считывается дата.This example opens the dataFile.txt file created in the previous step and reads the date from the file. Подробные сведения о загрузке файловых ресурсов из различных расположений см. в разделе Загрузка файловых ресурсов.For details on loading file resources from various locations, see How to load file resources.

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
   }
}

Перемещение данныхRoaming data

Если в приложении используются перемещаемые данные, то пользователи с легкостью смогут синхронизировать данные приложения на нескольких устройствах.If you use roaming data in your app, your users can easily keep your app's app data in sync across multiple devices. Если пользователь устанавливает приложение на несколько устройств, ОС следит за своевременной синхронизацией данных приложения, тем самым уменьшая объем работ по настройке приложения, которые пользователь должен выполнить на втором устройстве.If a user installs your app on multiple devices, the OS keeps the app data in sync, reducing the amount of setup work that the user needs to do for your app on their second device. Кроме того, использование перемещаемых данных позволяет пользователю продолжить выполнение задачи, например составление списка, с того самого места, на котором он остановился, даже если работа выполнялась на другом устройстве.Roaming also enables your users to continue a task, such as composing a list, right where they left off even on a different device. Когда перемещаемые данные обновляются, ОС реплицирует их в облаке и синхронизирует данные с другими устройствами, на которых установлено приложение.The OS replicates roaming data to the cloud when it is updated, and synchronizes the data to the other devices on which the app is installed.

ОС ограничивает объем данных приложения, которые каждое приложение может отнести к перемещаемым.The OS limits the size of the app data that each app may roam. См. раздел ApplicationData.RoamingStorageQuota.See ApplicationData.RoamingStorageQuota. Если приложение достигает указанного предельного значения, то никакие данные приложения не будут реплицироваться в облаке до тех пор, пока общий объем перемещаемых данных приложения снова не окажется меньше предельного значения.If the app hits this limit, none of the app's app data will be replicated to the cloud until the app's total roamed app data is less than the limit again. По этой причине рекомендуется использовать перемещаемые данные только для предпочтений пользователей, ссылок и небольших файлов данных.For this reason, it is a best practice to use roaming data only for user preferences, links, and small data files.

Перемещаемые данные приложения доступны в облаке до тех пор, пока пользователь обращается к ним с каких-либо устройств в течение заданного интервала времени.Roaming data for an app is available in the cloud as long as it is accessed by the user from some device within the required time interval. Если пользователь не запускает приложение дольше этого временного интервала, то его перемещаемые данные удаляются из облака.If the user does not run an app for longer than this time interval, its roaming data is removed from the cloud. Если пользователь удаляет приложение, его перемещаемые данные не удаляются из облака автоматически, они сохраняются.If a user uninstalls an app, its roaming data isn't automatically removed from the cloud, it's preserved. Если пользователь повторно устанавливает приложение в течение указанного временного интервала, то перемещаемые данные синхронизируются с данными, сохраненными в облаке.If the user reinstalls the app within the time interval, the roaming data is synchronized from the cloud.

Рекомендации по перемещению данныхRoaming data do's and don'ts

  • Используйте перемещение данных для пользовательских предпочтений и настроек, ссылок и небольших файлов данных.Use roaming for user preferences and customizations, links, and small data files. Например, используйте перемещаемые данные, чтобы сохранить настройку цвета фона на всех своих устройствах.For example, use roaming to preserve a user's background color preference across all devices.
  • Используйте перемещение данных, чтобы предоставить пользователям возможность продолжать работу над задачей на разных устройствах.Use roaming to let users continue a task across devices. Например, перемещайте такие данные приложения, как содержимое черновика сообщения электронной почты или последнюю просматриваемую страницу в средстве просмотра.For example, roam app data like the contents of an drafted email or the most recently viewed page in a reader app.
  • Обрабатывайте событие DataChanged, обновляя данные приложения.Handle the DataChanged event by updating app data. Это событие возникает сразу после завершения синхронизации данных приложения из облака.This event occurs when app data has just finished syncing from the cloud.
  • Перемещайте ссылки на содержимое вместо необработанных данных.Roam references to content rather than raw data. Например, перемещайте URL-адрес вместо содержимого статьи в сети.For example, roam a URL rather than the content of an online article.
  • Для важных зависящих от времени настроек используйте параметр HighPriority , связанный с RoamingSettings.For important, time critical settings, use the HighPriority setting associated with RoamingSettings.
  • Не перемещайте данные приложения, относящиеся к устройству.Don't roam app data that is specific to a device. Некоторая информация, например путь к локальному файловому ресурсу, имеет смысл только на локальном уровне.Some info is only pertinent locally, such as a path name to a local file resource. Если вы перемещаете локальные данные, убедитесь, что приложение может проверять, является ли эта информация действительной на втором устройстве.If you do decide to roam local information, make sure that the app can recover if the info isn't valid on the secondary device.
  • Не перемещайте большие наборы данных приложения.Don't roam large sets of app data. Существует предел объема данных, который может перемещать приложение; значение этого максимума можно получить с помощью свойства RoamingStorageQuota.There's a limit to the amount of app data an app may roam; use RoamingStorageQuota property to get this maximum. Если в приложении достигается этот предел, перемещение данных становится невозможным до тех пор, пока объем данных в хранилище приложения не станет меньше предельного.If an app hits this limit, no data can roam until the size of the app data store no longer exceeds the limit. При проектировании приложения рекомендуется рассмотреть способ установки ограничения для данных большего размера, чтобы не превышать заданный предел.When you design your app, consider how to put a bound on larger data so as to not exceed the limit. Например, если для каждого сохранения состояния игры требуется 10 КБ, приложение может позволить пользователю выполнять сохранение не более 10 раз.For example, if saving a game state requires 10KB each, the app might only allow the user store up to 10 games.
  • Не используйте перемещение для данных, которые нуждаются в мгновенной синхронизации.Don't use roaming for data that relies on instant syncing. Windows не гарантирует мгновенную синхронизацию. Перемещение может существенно задерживаться, если пользователь вышел из сети или используется сеть с высокой задержкой.Windows doesn't guarantee an instant sync; roaming could be significantly delayed if a user is offline or on a high latency network. Убедитесь, что ваш пользовательский интерфейс не зависит от мгновенной синхронизации.Ensure that your UI doesn't depend on instant syncing.
  • Не используйте перемещение для часто изменяющихся данных.Don't use roaming for frequently changing data. Например, если ваше приложение отслеживает часто меняющуюся информацию, такую как позиция при воспроизведении композиции, не сохраняйте эти данные как перемещаемые.For example, if your app tracks frequently changing info, such as the position in a song by second, don't store this as roaming app data. Вместо этого выберите реже меняющееся представление, которое при этом обеспечивает хорошее взаимодействие, например представление текущей композиции.Instead, pick a less frequent representation that still provides a good user experience, like the currently playing song.

Необходимые условия для перемещенияRoaming pre-requisites

Любой пользователь может воспользоваться преимуществами перемещения данных приложения, если он использует учетную запись Майкрософт для входа на своем устройстве.Any user can benefit from roaming app data if they use a Microsoft account to log on to their device. Однако пользователи и администраторы групповой политики могут в любое время отключить перемещение данных приложения на устройстве.However, users and group policy administrators can switch off roaming app data on a device at any time. Если пользователь принимает решение не использовать учетную запись Майкрософт или отключает возможности перемещения данных, он по-прежнему сможет использовать данные вашего приложения, но данные приложения будут локальными на каждом устройстве.If a user chooses not to use a Microsoft account or disables roaming data capabilities, she will still be able to use your app, but app data will be local to each device.

Данные, сохраненные в PasswordVault, перемещаются только в том случае, если пользователь присвоил своему устройству статус доверенного.Data stored in the PasswordVault will only transition if a user has made a device “trusted”. Если устройство не является доверенным, данные, сохраненные в этом хранилище, не будут перемещаться.If a device isn't trusted, data secured in this vault will not roam.

Устранение конфликтовConflict resolution

Перемещаемые данные приложения не предназначены для использования на нескольких устройствах одновременно.Roaming app data is not intended for simultaneous use on more than one device at a time. Если во время синхронизации возникает конфликт из-за изменения конкретного блока данных на двух устройствах, система всегда будет выбирать значение, которое было записано последним.If a conflict arises during synchronization because a particular data unit was changed on two devices, the system will always favor the value that was written last. Это гарантирует использование самой новой информации.This ensures that the app utilizes the most up-to-date information. Если блок данных представляет собой составной параметр, то разрешение конфликтов все равно будет выполняться на уровне единиц параметра, то есть будет синхронизироваться составной параметр с последним изменением.If the data unit is a setting composite, conflict resolution will still occur on the level of the setting unit, which means that the composite with the latest change will be synchronized.

Когда следует записывать данныеWhen to write data

В зависимости от ожидаемой частоты изменения параметра данные следует записывать в разное время.Depending on the expected lifetime of the setting, data should be written at different times. Редко меняющиеся данные приложения следует записывать немедленно.Infrequently or slowly changing app data should be written immediately. Часто меняющиеся данные следует записывать периодически через регулярные интервалы (например, раз в 5 минут), а также при приостановке приложения.However, app data that changes frequently should only be written periodically at regular intervals (such as once every 5 minutes), as well as when the app is suspended. Например, музыкальное приложение может записывать параметр "текущая композиция" в начале воспроизведения новой композиции, а фактическое положение в песне следует записывать только при приостановке.For example, a music app might write the “current song” settings whenever a new song starts to play, however, the actual position in the song should only be written on suspend.

Защита от чрезмерного использованияExcessive usage protection

У системы есть несколько механизмов для защиты от ненадлежащего использования ресурсов.The system has various protection mechanisms in place to avoid inappropriate use of resources. Если ожидаемого перемещения данных не происходит, возможно, устройство временно ограничено.If app data does not transition as expected, it is likely that the device has been temporarily restricted. Через некоторое время ситуация разрешится сама собой, и никакие действия предпринимать не потребуется.Waiting for some time will usually resolve this situation automatically and no action is required.

Управление версиямиVersioning

Данные приложения могут использовать управление версиями для обновления с одной структуры данных до другой.App data can utilize versioning to upgrade from one data structure to another. Номер версии отличается от версии приложения и может быть установлен по желанию.The version number is different from the app version and can be set at will. Хотя это и не обязательно, мы настоятельно рекомендуем использовать только возрастающие номера версий, так как при переходе на версию с меньшим номером и новыми данными возможны нежелательные ситуации, включая потерю данных.Although not enforced, it is highly recommended that you use increasing version numbers, since undesirable complications (including data loss)could occur if you try to transition to a lower data version number that represents newer data.

Данные приложения перемещаются только между установленными приложениями с одинаковым номером версии.App data only roams between installed apps with the same version number. Например, данные будут перемещаться между устройствами с приложениями версии 2 или между устройствами с приложениями версии 3, но перемещение данных между устройством с приложением версии 2 и устройством с приложением версии 3 выполняться не будет.For example, devices on version 2 will transition data between each other and devices on version 3 will do the same, but no roaming will occur between a device running version 2 and a device running version 3. Если вы устанавливаете новое приложение, которое использует разные номера версий на других устройствах, то новое установленное приложение будет выполнять синхронизацию данных приложения, связанных с самым высоким номером версии.If you install a new app that utilized various version numbers on other devices, the newly installed app will sync the app data associated with the highest version number.

Тестирование и инструментыTesting and tools

Разработчики могут заблокировать свое устройство, чтобы запустить синхронизацию перемещаемых данных приложения.Developers can lock their device in order to trigger a synchronization of roaming app data. Если создается впечатление, что данные приложения не перемещаются в течение определенного времени, убедитесь в следующем:If it seems that the app data does not transition within a certain time frame, please check the following items and make sure that:

  • размер перемещаемых данных не превышает установленный предел (дополнительную информацию см. в разделе RoamingStorageQuota);Your roaming data does not exceed the maximum size (see RoamingStorageQuota for details).
  • ваши файлы закрыты и выпущены надлежащим образом;Your files are closed and released properly.
  • есть минимум два устройства с приложениями одной и той же версии.There are at least two devices running the same version of the app.

Регистрация для получения уведомлений об изменении перемещаемых данныхRegister to receive notification when roaming data changes

Для использования перемещаемых данных приложения необходимо включить функцию уведомления об изменениях перемещаемых данных и извлечь контейнеры перемещаемых данных, чтобы иметь возможность читать и записывать параметры.To use roaming app data, you need to register for roaming data changes and retrieve the roaming data containers so you can read and write settings.

  1. Регистрация для получения уведомлений об изменении перемещаемых данных.Register to receive notification when roaming data changes.

    Событие DataChanged уведомляет об изменении перемещаемых данных.The DataChanged event notifies you when roaming data changes. В следующем примере DataChangeHandler определяется как обработчик изменений перемещаемых данных.This example sets DataChangeHandler as the handler for roaming data changes.

void InitHandlers()
    {
       Windows.Storage.ApplicationData.Current.DataChanged += 
          new TypedEventHandler<ApplicationData, object>(DataChangeHandler);
    }

    void DataChangeHandler(Windows.Storage.ApplicationData appData, object o)
    {
       // TODO: Refresh your data
    }
  1. Получение контейнеров для параметров и файлов приложения.Get the containers for the app's settings and files.

    Используйте свойство ApplicationData.RoamingSettings для получения параметров, а свойство ApplicationData.RoamingFolder для получения файлов.Use the ApplicationData.RoamingSettings property to get the settings and the ApplicationData.RoamingFolder property to get the files.

Windows.Storage.ApplicationDataContainer roamingSettings = 
        Windows.Storage.ApplicationData.Current.RoamingSettings;
    Windows.Storage.StorageFolder roamingFolder = 
        Windows.Storage.ApplicationData.Current.RoamingFolder;

Создание и извлечение параметров перемещенияCreate and retrieve roaming settings

Используйте свойство ApplicationDataContainer.Values для доступа к параметрам в контейнере roamingSettings, полученном в предыдущем разделе.Use the ApplicationDataContainer.Values property to access the settings in the roamingSettings container we got in the previous section. В следующем примере создается простой параметр с именем exampleSetting и составное значение composite.This example creates a simple setting named exampleSetting and a composite value named composite.

// Simple setting

roamingSettings.Values["exampleSetting"] = "Hello World";
// High Priority setting, for example, last page position in book reader app
roamingSettings.values["HighPriority"] = "65";

// Composite setting

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

roamingSettings.Values["exampleCompositeSetting"] = composite;

В следующем примере извлекаются только что созданные параметры.This example retrieves the settings we just created.

// Simple setting

Object value = roamingSettings.Values["exampleSetting"];

// Composite setting

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

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

Создайте и восстановление перемещаемых файловCreate and retrieve roaming files

Для создания и обновления файла в хранилище данных перемещаемого приложения используйте файловые API, например, Windows.Storage.StorageFolder.CreateFileAsync и Windows.Storage.FileIO.WriteTextAsync.To create and update a file in the roaming app data store, use the file APIs, such as Windows.Storage.StorageFolder.CreateFileAsync and Windows.Storage.FileIO.WriteTextAsync. В следующем примере создается файл с именем dataFile.txt в контейнере roamingFolder и в этот файл записываются текущие дата и время.This example creates a file named dataFile.txt in the roamingFolder container and writes the current date and time to the file. Значение ReplaceExisting из перечисления CreationCollisionOption показывает, что, если файл уже существует, его следует заменить.The ReplaceExisting value from the CreationCollisionOption enumeration indicates to replace the file if it already exists.

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

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

Для открытия и чтения файла в хранилище данных перемещаемого приложения используйте файловые API, например, Windows.Storage.StorageFolder.GetFileAsync, Windows.Storage.StorageFile.GetFileFromApplicationUriAsync и Windows.Storage.FileIO.ReadTextAsync.To open and read a file in the roaming app data store, use the file APIs, such as Windows.Storage.StorageFolder.GetFileAsync, Windows.Storage.StorageFile.GetFileFromApplicationUriAsync, and Windows.Storage.FileIO.ReadTextAsync. В следующем примере открывается файл dataFile.txt, созданный в предыдущем разделе, и из него считывается дата.This example opens the dataFile.txt file created in the previous section and reads the date from the file. Подробные сведения о загрузке файловых ресурсов из различных расположений см. в разделе Загрузка файловых ресурсов.For details on loading file resources from various locations, see How to load file resources.

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

Временные данные приложенияTemporary app data

Хранилище временных данных приложения действует подобно кэшу.The temporary app data store works like a cache. Его файлы не перемещаются и могут быть удалены в любое время.Its files do not roam and could be removed at any time. Задача обслуживания системы может автоматически удалить данные, сохраненные в этом месте хранения в любое время.The System Maintenance task can automatically delete data stored at this location at any time. Кроме того, пользователь может удалить файлы из хранилища временных файлов с помощью средства очистки диска.The user can also clear files from the temporary data store using Disk Cleanup. Временные данные приложения могут использоваться для хранения временной информации в течение сеанса приложения.Temporary app data can be used for storing temporary information during an app session. Нет никакой гарантии, что эти данные сохранятся после того, как сеанс приложения будет завершен, потому что система может при необходимости освободить занимаемое ими место.There is no guarantee that this data will persist beyond the end of the app session as the system might reclaim the used space if needed. Местоположение определяется свойством temporaryFolder.The location is available via the temporaryFolder property.

Восстановление контейнера временных данныхRetrieve the temporary data container

Используйте свойство ApplicationData.TemporaryFolder для получения файлов.Use the ApplicationData.TemporaryFolder property to get the files. Переменная temporaryFolder из этого шага используется на следующих шагах.The next steps use the temporaryFolder variable from this step.

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

Создание и чтение временных файловCreate and read temporary files

Для создания и обновления файла в хранилище временных данных приложения используйте файловые API, например, Windows.Storage.StorageFolder.CreateFileAsync и Windows.Storage.FileIO.WriteTextAsync.To create and update a file in the temporary app data store, use the file APIs, such as Windows.Storage.StorageFolder.CreateFileAsync and Windows.Storage.FileIO.WriteTextAsync. В следующем примере создается файл с именем dataFile.txt в контейнере temporaryFolder и в этот файл записываются текущие дата и время.This example creates a file named dataFile.txt in the temporaryFolder container and writes the current date and time to the file. Значение ReplaceExisting из перечисления CreationCollisionOption показывает, что, если файл уже существует, его следует заменить.The ReplaceExisting value from the CreationCollisionOption enumeration indicates to replace the file if it already exists.

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));
}

Для открытия и чтения файла в хранилище временных данных приложения используйте файловые API, например, Windows.Storage.StorageFolder.GetFileAsync, Windows.Storage.StorageFile.GetFileFromApplicationUriAsync и Windows.Storage.FileIO.ReadTextAsync.To open and read a file in the temporary app data store, use the file APIs, such as Windows.Storage.StorageFolder.GetFileAsync, Windows.Storage.StorageFile.GetFileFromApplicationUriAsync, and Windows.Storage.FileIO.ReadTextAsync. В следующем примере открывается файл dataFile.txt, созданный на предыдущем шаге, и из него считывается дата.This example opens the dataFile.txt file created in the previous step and reads the date from the file. Подробные сведения о загрузке файловых ресурсов из различных расположений см. в разделе Загрузка файловых ресурсов.For details on loading file resources from various locations, see How to load file resources.

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
   }
}

Упорядочение данных приложения с помощью контейнеровOrganize app data with containers

Для упорядочения параметров и файлов данных приложения необходимо создать контейнеры (представленные объектами ApplicationDataContainer) вместо того, чтобы работать непосредственно с каталогами.To help you organize your app data settings and files, you create containers (represented by ApplicationDataContainer objects) instead of working directly with directories. Контейнеры можно добавлять в хранилища локальных, перемещаемых и временных данных приложения.You can add containers to the local, roaming, and temporary app data stores. Контейнеры могут иметь до 32 уровней вложенности.Containers can be nested up to 32 levels deep.

Для создания контейнера параметров вызовите метод ApplicationDataContainer.CreateContainer.To create a settings container, call the ApplicationDataContainer.CreateContainer method. В следующем примере создается контейнер локальных параметров с именем exampleContainer и добавляется параметр с именем exampleSetting.This example creates a local settings container named exampleContainer and adds a setting named exampleSetting. Значение Always из перечисления ApplicationDataCreateDisposition показывает, что, если контейнер не существует, он создается.The Always value from the ApplicationDataCreateDisposition enumeration indicates that the container is created if it doesn't already exist.

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";
}

Удаление параметров и контейнеров приложенияDelete app settings and containers

Для удаления простого параметра, который больше не требуется для вашего приложения, используйте метод ApplicationDataContainerSettings.Remove.To delete a simple setting that your app no longer needs, use the ApplicationDataContainerSettings.Remove method. В этом примере выполняется удаление ранее созданного локального параметра exampleSetting.This example deletesthe exampleSetting local setting that we created earlier.

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");

Для удаления составного параметра используйте метод ApplicationDataCompositeValue.Remove.To delete a composite setting, use the ApplicationDataCompositeValue.Remove method. В этом примере удаляется локальный составной параметр exampleCompositeSetting, созданный в примере выше.This example deletes the local exampleCompositeSetting composite setting we created in an earlier example.

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");

Для удаления контейнера вызовите метод ApplicationDataContainer.DeleteContainer.To delete a container, call the ApplicationDataContainer.DeleteContainer method. В этом примере удаляется ранее созданный контейнер локальных параметров exampleContainer.This example deletes the local exampleContainer settings container we created earlier.

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

// Delete container

localSettings.DeleteContainer("exampleContainer");

Управление версиями данных приложенияVersioning your app data

При желании вы можете назначить версию для данных приложения.You can optionally version the app data for your app. Это позволит вам создать следующую версию приложения, которая при изменении формата данных не вызовет проблем совместимости с предыдущей версией приложения.This would enable you to create a future version of your app that changes the format of its app data without causing compatibility problems with the previous version of your app. Приложение проверит версию данных приложения в хранилище данных и в случае, если версия окажется более ранней, чем ожидалось, обновит данные приложения до нового формата и изменит их версию.The app checks the version of the app data in the data store, and if the version is less than the version the app expects, the app should update the app data to the new format and update the version. Подробнее см. в описании свойства Application.Version и метода ApplicationData.SetVersionAsync.For more info, see the Application.Version property and the ApplicationData.SetVersionAsync method.