Сохранение и загрузка параметров в приложении UWPSave and load settings in a UWP app

В этом разделе приведены инструкции по загрузке и сохранению параметров в приложении UWP.This topic covers what you need to know to get started loading, and saving, settings in a Universal Windows Platform (UWP) app. В этом разделе представлены основные интерфейсы API, а также необходимые ссылки на дополнительные ресурсы.The main APIs are introduced, and links are provided to help you learn more.

Используйте параметры, чтобы запомнить настраиваемые пользователем аспекты вашего приложения.Use settings to remember the user-customizable aspects of your app. Например, средство чтения новостей может использовать параметры приложения для сохранения того, какие источники новостей следует отображать и какой шрифт следует использовать для чтения статей.For example, a news reader could use app settings to save which news sources to display and what font to use for reading articles.

Мы рассмотрим код для сохранения и загрузки параметров приложения, включая локальные и перемещаемые параметры.We’ll look at code to save and load app settings, including local and roaming settings.

Что необходимо знать?What do you need to know

Параметры приложения используются для сохранения данных конфигурации, таких как предпочтения пользователя и состояние приложения.Use app settings to store configuration data such as user preferences and app state. Параметры, относящиеся к устройству, хранятся локально.Settings that are specific to the device are stored locally. Параметры, которые применяются независимо от того, на каком устройстве установлено ваше приложение, хранятся в хранилище перемещаемых данных.Settings that apply on whichever device your app is installed on are stored in the roaming data store. Параметры перемещаются между устройствами, на которых пользователь осуществляет вход в систему с одной и той же учетной записью Майкрософт и на которых совпадает версия установленного приложения.Settings are roamed between devices on which the user is signed in with the same Microsoft Account and have the same version of the app installed.

С параметрами можно использовать следующие типы данных: целые числа, числа двойной точности с плавающей запятой, значения с плавающей запятой, знаки, строки, точки, дату и время и другое.The following data types can be used with settings: integers, doubles, floats, chars, strings, Points, DateTimes, and more. Можно также хранить экземпляры класса ApplicationDataCompositeValue, которые бывают полезны, когда несколько параметров необходимо рассматривать как единое целое.You can also store instances of the ApplicationDataCompositeValue class which is useful when there are multiple settings that should be treated as a unit. Например, имя шрифта и размер точки для отображения текста в области чтения приложения необходимо сохранять или восстанавливать как единое целое.For example, a font name and point size for displaying text in the reading pane of your app should be saved/restored as a single unit. Это предотвращает рассинхронизацию параметров из-за задержек в перемещении одного параметра перед другим.This prevents one setting from getting out of sync with the other due to delays in roaming one setting before the other.

Ниже приведены основные интерфейсы API для сохранения и загрузки параметров приложения.Here are the main APIs you need to know about to save or load app settings:

  • Windows.Storage.ApplicationData.Current.LocalSettings получает контейнер параметров приложения из локального хранилища данных приложения.Windows.Storage.ApplicationData.Current.LocalSettings gets the application settings container from the local app data store. Здесь следует хранить те параметры, которые не подходят для перемещения между устройствами из-за того, что они представляют конкретное состояние устройства или являются слишком большими.Store settings here that are not appropriate to roam between devices because they represent state specific to this device, or are too big.
  • Windows.Storage.ApplicationData.Current.RoamingSettings получает контейнер параметров приложения из перемещаемого хранилища данных приложения.Windows.Storage.ApplicationData.Current.RoamingSettings gets the application settings container from the roaming app data store. Эти данные перемещаются между устройствами.This data roams between devices.
  • Windows.Storage.ApplicationDataContainer — это контейнер, представляющий параметры приложения в виде пар "ключ-значение".Windows.Storage.ApplicationDataContainer is a container that represents app settings as key/value pairs. Этот класс используется для создания и получения значений параметров.Use this class to create and retrieve setting values.
  • Windows.Storage.ApplicationDataCompositeValue представляет несколько параметров приложения, которые должны следует упорядочить как единое целое.Windows.Storage.ApplicationDataCompositeValue represents multiple app settings that should be serialized as a unit. Это удобно в тех случаях, когда один параметр не должен обновляться независимо от другого.This is useful when one setting shouldn't be updated independently of another.

Сохранение параметров приложенияSave app settings

Здесь мы расскажем о двух простых сценариях: локальное сохранение и загрузка параметра приложения и перемещение составного параметра шрифта и размера шрифта между устройствами.For this introduction, we will focus on two simple scenarios: saving and loading an app setting locally, and roaming a composite font/font size setting between devices.

// Save a setting locally on the device
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
localSettings.Values["test setting"] = "a device specific setting";

// Save a composite setting that will be roamed between devices
ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;
Windows.Storage.ApplicationDataCompositeValue composite = new Windows.Storage.ApplicationDataCompositeValue();
composite["Font"] = "Calibri";
composite["FontSize"] = 11;
roamingSettings.Values["RoamingFontInfo"] = composite;

Сохраните параметр на локальном устройстве путем получения ApplicationDataContainer для локального хранилища данных параметров с Windows.Storage.ApplicationData.Current.LocalSettings.Save a setting to the local device, by first getting an ApplicationDataContainer for the local settings data store with Windows.Storage.ApplicationData.Current.LocalSettings. Словарные пары "ключ-значение", присваиваемые этому экземпляру, сохраняются в хранилище данных параметров на локальном устройстве.Key/value dictionary pairs that you assign to this instance are saved in the local device setting data store.

Сохраните перемещаемый параметр, используя аналогичную схему.Save a roaming setting using a similar pattern. Сначала получите ApplicationDataContainer для перемещаемого хранилища данных параметров с Windows.Storage.ApplicationData.Current.RoamingSettings.First get an ApplicationDataContainer for the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. Затем назначьте пары "ключ-значение" этому экземпляру.Then assign key/value pairs to this instance. Эти пары "ключ-значение" будут автоматически перемещаться между устройствами.Those key/value pairs will automatically roam between devices.

В примере кода, приведенном выше, ApplicationDataCompositeValue сохраняет несколько пар "ключ-значение".In the code snippet above, a ApplicationDataCompositeValue stores multiple key/value pairs. Составные значения полезны в тех случаях, когда у вас есть несколько параметров, которые не должны быть рассинхронизированы.Composite values are useful when you have multiple settings that shouldn't get out of sync with each other. При сохранении ApplicationDataCompositeValue значения сохраняются и загружаются как единое целое или атомарным образом.When you save a ApplicationDataCompositeValue, the values are saved and loaded as a unit, or atomically. Таким образом, связанные параметры не будут рассинхронизироваться, так как они перемещаются как единое целое, а не по отдельности.This way settings that are related won't get out of sync because they are roamed as a unit instead of individually.

Загрузка параметров приложенияLoad app settings

// load a setting that is local to the device
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
String localValue = localSettings.Values["test setting"] as string;

// load a composite setting that roams between devices
ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;
Windows.Storage.ApplicationDataCompositeValue composite = (ApplicationDataCompositeValue)roamingSettings.Values["RoamingFontInfo"];
if (composite != null)
{
    String fontName = composite["Font"] as string;
    int fontSize = (int)composite["FontSize"];
}

Загрузите параметр из локального устройства путем получения экземпляра ApplicationDataContainer для локального хранилища данных параметров с Windows.Storage.ApplicationData.Current.LocalSettings.Load a setting from the local device, by first getting an ApplicationDataContainer instance for the local settings data store with Windows.Storage.ApplicationData.Current.LocalSettings. Затем используйте его для получения пар "ключ-значение".Then use it to retrieve key/value pairs.

Загрузите перемещаемый параметр, используя аналогичную схему.Load a roaming setting by following a similar pattern. Сначала получите экземпляр ApplicationDataContainer из перемещаемого хранилища данных параметров с Windows.Storage.ApplicationData.Current.RoamingSettings.First get an ApplicationDataContainer instance from the roaming settings data store with Windows.Storage.ApplicationData.Current.RoamingSettings. Обратитесь к парам "ключ-значение" из этого экземпляра.Access key/value pairs from that instance. Если данные пока не переместились на устройство, с которого вы осуществляете доступ к параметрам, значением экземпляра ApplicationDataContainer будет NULL.If the data hasn't roamed yet to the device that you are accessing the settings from, you'll get a null ApplicationDataContainer. Поэтому в примере кода выше присутствует проверка if (composite != null).That's why there is a if (composite != null) check in the example code above.

Полезные интерфейсы API и документыUseful APIs and docs

Вот краткое описание интерфейсов API и другая полезная документация, которая поможет вам сохранять и загружать параметры приложения.Here is a quick summary of APIs, and other useful documentation, to help get you started saving and loading app settings.

Полезные интерфейсы APIUseful APIs

APIAPI ОписаниеDescription
ApplicationData.LocalSettingsApplicationData.LocalSettings Получает контейнер параметров приложения из локального хранилища данных приложения.Gets the application settings container from the local app data store.
ApplicationData.RoamingSettingsApplicationData.RoamingSettings Получает контейнер параметров приложения из перемещаемого хранилища данных приложения.Gets the application settings container from the roaming app data store.
ApplicationDataContainerApplicationDataContainer Контейнер для параметров приложения, который поддерживает создание, удаление, перечисление и обход иерархии контейнеров.A container for app settings that supports creating, deleting, enumerating, and traversing the container hierarchy.
Windows.UI.ApplicationSettings NamespaceWindows.UI.ApplicationSettings Namespace Содержит классы, которые вы будете использовать для определения параметров приложения, отображающихся на панели параметров оболочки Windows.Provides classes that you'll use to define the app settings that appear in the settings pane of the Windows shell.

Полезные документыUseful docs

РазделTopic ОписаниеDescription
Руководство по параметрам приложенийGuidelines for app settings Рекомендации по созданию и отображению параметров приложения.Describes best practices for creating and displaying app settings.
Хранение и извлечение параметров и прочих данных приложенияStore and retrieve settings and other app data Руководство по сохранению и извлечению параметров, включая перемещаемые параметры.Walk-through for saving and retrieving settings, including roaming settings.

Полезные примеры кодаUseful code samples

Пример кодаCode sample ОписаниеDescription
Пример данных приложенияApplication data sample В сценариях 2–4 рассказывается о работе с параметрами.Scenarios 2-4 focus on settings