DateTime, TimeSpan
- Для C#/.NET використовуйте: System.DateTimeOffset, System.TimeSpan
Файли
Використовуйте файли для зберігання двійкових даних або включення власних серіалізованих типів, що настроюються.
Зберігання даних програми у сховищах даних програми
Коли програму встановлено, система надає їй власні сховища даних для параметрів користувача та файлів. Вам не потрібно знати, де або як ці дані існують, оскільки система відповідає за керування фізичним сховищем, забезпечуючи ізоляцію даних від інших програм та інших користувачів. Система також зберігає вміст цих сховищ даних, коли користувач встановлює оновлення до програми та видаляє вміст цих сховищ даних повністю і чисто при видаленні програми.
У сховищі даних програми кожна програма має системні кореневі каталоги: один для локальних файлів, один для файлів, що переміщуються, і один для тимчасових файлів. Програма може додавати нові файли та нові контейнери до кожного з цих кореневих каталогів.
Дані локальної програми
Дані локальної програми повинні використовуватися для будь-яких відомостей, які необхідно зберегти між сеансами програм і не підходять для даних програми, що переміщуються. Дані, які не використовуються на інших пристроях, також повинні зберігатися тут. Немає загального обмеження для локальних даних, що зберігаються. Використовуйте локальне сховище даних для даних, які не мають сенсу переміщати і використовувати для великих наборів даних.
Отримання локального сховища даних програми
Перш ніж зчитувати або записувати дані локальної програми, необхідно отримати локальне сховище даних програми. Щоб отримати локальне сховище даних програми, використовуйте властивість ApplicationData.LocalSettings , щоб отримати локальні параметри програми як об'єкт ApplicationDataContainer . Використовуйте властивість ApplicationData.LocalFolder, щоб отримати файли в об'єкті
StorageFolder.
Використовуйте властивість ApplicationData.LocalCacheFolder, щоб отримати папку в локальному сховищі даних програми, де можна зберегти файли, які не включені до резервного копіювання та відновлення.
Windows.Storage.ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings; Windows.Storage.StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;
Створення та вилучення простого локального параметра
Щоб створити або записати параметр, використовуйте властивість ApplicationDataContainer.Values для доступу до параметрів у контейнері localSettings , який ми отримали на попередньому етапі. У цьому прикладі створюється параметр з ім'ям exampleSetting.
// Simple setting localSettings.Values["exampleSetting"] = "Hello Windows";
Щоб отримати цей параметр, використовуйте те саме властивість ApplicationDataContainer.Values , який використовувався для створення параметра. У цьому прикладі показано, як отримати щойно створений параметр.
// Simple setting Object value = localSettings.Values["exampleSetting"];
Створення та отримання локального складового значення
Щоб створити або записати складне значення, створіть об'єкт ApplicationDataCompositeValue . У цьому прикладі створюється складовий параметр з ім'ям exampleCompositeSetting і додається в localsettings контейнер.
// Composite setting Windows.Storage.ApplicationDataCompositeValue composite = new Windows.Storage.ApplicationDataCompositeValue(); composite["intVal"] = 1; composite["strVal"] = "string"; localSettings.Values["exampleCompositeSetting"] = composite;
У цьому прикладі показано, як отримати щойно створене складове значення.
// 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"] >
Створення та читання локального файлу
Щоб створити та оновити файл у локальному сховищі даних програми, використовуйте API-інтерфейси файлів, такі як Windows.StorageFolder.CreateFileAsync та Windows.Storage.FileIO.WriteTextAsync
. У цьому прикладі створюється файл з ім'ям dataFile.txt у контейнері localFolder і записується поточна дата та час у файл. Значення ReplaceExisting з переліку CreationCollisionOption вказує, щоб замінити файл, якщо він існує.
async void WriteTimestamp()
Щоб відкрити та прочитати файл у локальному сховищі даних програми, використовуйте API-інтерфейси файлів, такі як Windows.StorageFolder.GetFileAsync, Windows.StorageFile.GetFileFromApplicationUriAsync
і Windows.Storage.FileIO.ReadTextAsync. У цьому прикладі файл, dataFile.txt, створений на попередньому кроці, зчитує дату з файлу. Щоб отримати додаткові відомості про завантаження файлового ресурсу, див. у розділі "Завантаження файлового ресурсу".
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 >>
Переміщувані дані
Дані та параметри, що переміщуються, більше не підтримуються у Windows 11. Рекомендована заміна — Служба додатків Azure. Служба додатків Azure широко підтримується та добре описана. Це надійне рішення, яке підтримує сценарії з використанням різних платформ та екосистем, включаючи iOS, Android та інтернет-рішення.
Наступна документація відноситься до Windows 10 версії 1909 та нижчої.
При використанні даних, що переміщуються в програмі, користувачі можуть легко синхронізувати дані програми на декількох пристроях.Якщо користувач встановлює програму на кількох пристроях, ОС зберігає дані програми синхронізації, зменшуючи обсяг роботи установки, яку користувач повинен зробити для вашої програми на другому пристрої. Переміщення також дозволяє користувачам продовжувати завдання, наприклад створення списку праворуч, де вони звільнилися навіть на іншому пристрої. ОС реплікує дані, що переміщаються в хмару при оновленні, і синхронізує дані з іншими пристроями, на яких встановлено програму.
ОС обмежує розмір даних програми, які може переміщати кожну програму. розділ ApplicationData.RoamingStorageQuota . Якщо програма досягне цього обмеження, жоден з даних програми не буде реплікуватися в хмару, поки загальний обсяг даних програми, що переміщуються, не буде менше межі. З цієї причини рекомендується використовувати дані, що переміщуються, тільки для користувацьких переваг, посилань і невеликих файлів даних.
Дані, що переміщуються для програми, доступні в хмарі, якщо доступ до неї здійснюється користувачем з якогось пристрою протягом потрібного інтервалу часу. Якщо користувач не запускає програму довше цього інтервалу часу, його дані, що переміщаються, видаляються з хмари. Якщо користувач видаляє програму, його переміщувані дані не видаляються з хмари автоматично, він зберігається. Якщо користувач перевстановить програму протягом інтервалу часу, дані, що переміщаються, синхронізуються з хмари.
Дані, що переміщуються, виконуються і не виконуються
- Використовуйте роумінг для налаштувань і налаштувань, посилань і невеликих файлів даних. Наприклад, використовуйте роумінг для збереження переваги кольору фону користувача на всіх пристроях.
- Використовуйте рух, щоб користувачі продовжували завдання на різних пристроях.Наприклад, переміщуйте дані програми, такі як вміст чернетки електронної пошти або сторінку, що нещодавно переглядається в програмі читання.
- Обробіть подія DataChanged , оновивши дані програми. Ця подія виникає, коли дані програми щойно завершили синхронізацію з хмари.
- Переміщуйте посилання на вміст, а не на необроблені дані. Наприклад, переміщуйте URL-адресу, а не вміст веб-статті.
- Для важливих параметрів часу використовуйте параметр HighPriority, пов'язаний зRoamingSettings.
- Не переміщуйте дані програми, які стосуються Вашого пристрою. Деякі відомості стосуються лише локально, наприклад, ім'я шляху до локального ресурсу файлу. Якщо ви вирішите переміщувати локальну інформацію, переконайтеся, що програма може відновитися, якщо інформація не дійсна на додатковому пристрої.
- Не рухайте великі набори даних програми. Існує обмеження обсяг даних програми, які може переміщати додаток; використовуйте властивість RoamingStorageQuota , щоб отримати це максимальне значення. Якщо програма досягає цього обмеження, дані не можуть переміщатися, поки розмір сховища даних програми більше не перевищує межу. При розробці програми розгляньте, як помістити прив'язку до великих даних, щоб не перевищувати межу. Наприклад, якщо для збереження ігрового стану потрібно 10 КБ, програма може дозволити лише 10 ігор.
- Не використовуйте роумінг для даних на основі миттєвої синхронізації. Windows не гарантує миттєву синхронізацію; Переміщення може бути значно відкладено, якщо користувач перебуває в автономному режимі або в мережі з високою затримкою. Переконайтеся, що інтерфейс користувача не залежить від миттєвої синхронізації.
- Не використовуйте переміщення для даних, що часто змінюються.Наприклад, якщо ваша програма відстежує відомості, що часто змінюються, наприклад положення в пісні на секунду, не зберігайте це як дані програми, що переміщуються. Натомість виберіть менш часте уявлення, яке, як і раніше, забезпечує хороший інтерфейс користувача, як і в даний час граюча пісня.
Попередні вимоги для роумінгу
Будь-який користувач може скористатися даними програми, що переміщуються, якщо він використовує обліковий запис Майкрософт для входу на свій пристрій. Однак користувачі та адміністратори групової політики можуть вимкнути дані програми, що переміщуються, на пристрої в будь-який час. Якщо користувач приймає рішення не використовувати обліковий запис Майкрософт або вимкнути можливості переміщення даних, він, як і раніше, зможе використовувати дані вашої програми, але ці програми будуть локальними на кожному пристрої.
Дані, збережені в PasswordVault, переміщуються, лише якщо користувач надав своєму пристрою статус довіреного. Якщо пристрій не є довіреним, дані, захищені в цьому сховищі, не переміщуватимуться.
Вирішення конфліктів
Дані програми, що переміщується, не призначені для одночасного використання на декількох пристроях одночасно. Якщо під час синхронізації виникає конфлікт, оскільки на двох пристроях було змінено певну одиницю даних, система завжди буде віддавати перевагу значення, записане останнє. Це гарантує, що програма використовує найактуальнішу інформацію. Якщо одиниця даних є складовою, вирішення конфліктів, як і раніше, відбуватиметься на рівні одиниці установки, що означає, що складова з останньою зміною буде синхронізована.
Коли записувати дані
Залежно від очікуваного часу існування параметра, дані повинні записуватися в різний час. Нечасто або повільно змінюючи дані програми, повинні бути записані негайно.Однак ці програми, які часто змінюються, слід періодично записувати лише через регулярні інтервали (наприклад, кожні 5 хвилин), а також при зупинці програми. Наприклад, музична програма може записувати параметри поточної композиції на початку відтворення нової композиції, при цьому фактична позиція в пісні повинна записуватися лише при зупинці.
Надмірний захист використання
Система має різні механізми захисту, щоб уникнути неправильного використання ресурсів. Якщо дані програми не переходять належним чином, швидше за все, пристрій тимчасово обмежений. Очікування деякого часу зазвичай вирішує цю ситуацію автоматично, і жодних дій не потрібно.
Управління версіями
Ці програми можуть керувати версіями для оновлення однієї структури даних до іншої. Номер версії відрізняється від версії програми та може бути заданий. Хоча й не застосовується, рекомендується використовувати додаткові номери версій, оскільки небажані ускладнення (включаючи втрату даних) можуть виникнути при спробі перейти на нижчий номер версії даних, що представляє нові дані.
Ці програми переміщуються лише між встановленими програмами з однаковим номером версії. Наприклад, пристрої у версії 2 перемикають дані між собою та пристроями версії 3 будуть робити те ж саме, але переміщення між пристроєм під керуванням версії 2 та пристроєм під керуванням версії 3 не буде. При встановленні нової програми, яка використовувала різні номери версій на інших пристроях, щойно встановлена програма синхронізує дані програми, пов'язані з найвищим номером версії.
Тестування та засоби
Розробники можуть заблокувати свій пристрій для активації синхронізації даних програми. Якщо здається, що дані програми не переходять протягом певного інтервалу часу, перевірте такі елементи та переконайтеся, що:
- Дані, що переміщуються, не перевищують максимальний розмір (додаткові відомості див. у розділі RoamingStorageQuota).
- Файли закриті та звільнені належним чином.
- Існує принаймні два пристрої з однією і тією ж версією програми.
Реєстрація для отримання повідомлення при зміні даних, що переміщуються
Щоб використовувати дані програми, що переміщується, необхідно зареєструвати для зміни даних, що переміщуються, і отримати контейнери даних, що переміщуються, щоб можна було зчитувати і записувати параметри.
- Зареєструйтесь для отримання повідомлення при зміні даних, що переміщуються. Подія DataChanged повідомляє вас про зміну даних, що переміщуються. Цей приклад задає DataChangeHandler обробник для зміни даних, що переміщуються.
void InitHandlers() < Windows.Storage.ApplicationData.Current.DataChanged += new TypedEventHandler(DataChangeHandler); > void DataChangeHandler(Windows.Storage.ApplicationData appData, об'єкт o) < // TODO: Refresh your data >
- Отримайте контейнери для параметрів та файлів програми. Використовуйте властивість ApplicationData.RoamingSettings, щоб отримати параметри тавластивість ApplicationData.RoamingFolder, щоб отримати файли.
Windows.Storage.ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings; Windows.Storage.StorageFolder roamingFolder = Windows.Storage.ApplicationData.Current.RoamingFolder;
Створення та отримання параметрів роумінгу
Використовуйте властивість ApplicationDataContainer.Values для доступу до параметрів у контейнері roamingSettings, який ми отримали у попередньому розділі. У цьому прикладі створюється простий параметр з ім'ям exampleSetting 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;
У цьому прикладі виймаються щойно створені параметри.
// 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"] >
Створення та вилучення файлів, що переміщуються
Щоб створити та оновити файл у сховищі даних переміщуваної програми, використовуйте API-інтерфейси файлів, такі як Windows.Storage.StorageFolder.CreateFileAsync та Windows.Storage.FileIO.WriteTextAsync
. У цьому прикладі створюється файл з ім'ям dataFile.txt у контейнері roamingFolder і записується поточна дата та час у файл. Значення ReplaceExisting з переліку CreationCollisionOption вказує, щоб замінити файл, якщо він існує.
async void WriteTimestamp()
Щоб відкрити і прочитати файл у сховищі даних програми, використовуйте API-інтерфейси файлів, такі як Windows.Storage.StorageFolder.GetFileAsync,
Windows.StorageFile.GetFileFromApplicationUriAsync та Windows.Storage.FileIO.ReadTextAsync. У цьому прикладі відкривається dataFile.txt файл, створений у попередньому розділі, та зчитується дата з файлу. Щоб отримати додаткові відомості про завантаження файлового ресурсу, див. у розділі "Завантаження файлового ресурсу".
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 >>
Тимчасові дані програми
Тимчасове сховище даних програми працює як кеш. Його файли не переміщаються і можуть бути видалені будь-коли. Завдання обслуговування системи може автоматично видаляти дані, що зберігаються у цьому положенні у будь-який час. Користувач також може очистити файли з тимчасового сховища даних за допомогою очищення диска. Тимчасові дані програми можна використовувати для збереження тимчасових відомостей під час сеансу програми. Немає жодних гарантій, що ці дані будуть зберігатися після закінчення сеансу програми, оскільки система може звільнити простір, що використовується, за необхідності. Розташування доступне через тимчасове властивістьFolder .
Отримання тимчасового контейнера даних
Використовуйте властивість ApplicationData.TemporaryFolder для отримання файлів. Наступні кроки використовують temporaryFolder змінну з цього кроку.
Windows.Storage.StorageFolder temporaryFolder = ApplicationData.Current.TemporaryFolder;
Створення та читання тимчасових файлів
Щоб створити та оновити файл у тимчасовому сховищі даних програми, використовуйте API-інтерфейси файлів, такі як Windows.Storage.StorageFolder.CreateFileAsync та Windows.Storage.FileIO.WriteTextAsync
. У цьому прикладі створюється файл з ім'ям dataFile.txt у контейнері temporaryFolder і записується поточна дата та час у файл. Значення ReplaceExisting з переліку CreationCollisionOption вказує, щоб замінити файл, якщо він існує.
async void WriteTimestamp()
Щоб відкрити та прочитати файл у тимчасовому сховищі даних програми, використовуйте API-інтерфейси файлів, такі як Windows.Storage.StorageFolder.GetFileAsync, Windows.StorageFile.GetFileFromApplicationUriAsync та Windows.Storage.FileIO.ReadTextAsync . У цьому прикладі файл, dataFile.txt, створений на попередньому кроці, зчитує дату з файлу. Щоб отримати додаткові відомості про завантаження файлового ресурсу, див. у розділі "Завантаження файлового ресурсу".
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 >>
Впорядкування даних програми за допомогою контейнерів
Для організації параметрів і файлів даних програми можна створювати контейнери (представлені об'єктами ApplicationDataContainer ), а не працювати безпосередньо з каталогами. Контейнери можна додавати до локальних, переміщуваних та тимчасових сховищ даних програми. Контейнери можна вкласти глибоко до 32 рівнів.
Щоб створити контейнер параметрів, викличте метод ApplicationDataContainer.CreateContainer . У цьому прикладі створюється локальний контейнер параметрів з ім'ям exampleContainer і додається параметр з ім'ям exampleSetting. Значення Always з переліку ApplicationDataCreateDisposition вказує, що контейнер створюється, якщо він ще немає.
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"))
Видалення параметрів та контейнерів додатків
Щоб видалити простий параметр, який програма більше не потрібна, використовуйте метод ApplicationDataContainerSettings.Remove . У цьому прикладі видаляється локальний exampleSetting параметр, створений раніше.
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 . У цьому прикладі видаляється локальний exampleCompositeSetting складовий параметр, створений у попередньому прикладі.
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 . У цьому прикладі видаляється створений раніше контейнер локальних exampleContainer параметрів.
Windows.Storage.ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings; Windows.Storage.StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder; // Delete container localSettings.DeleteContainer("exampleContainer");
Керування версіями даних програми
За необхідності можна використовувати версію даних програми для програми. Це дозволить створити майбутню версію програми, яка змінює формат даних програми без проблем сумісності з попередньою версією програми. Програма перевіряє версію даних програми у сховищі даних, а якщо версія менша за версію, що очікується програмою, програма повинна оновити дані програми до нового формату і оновити версію. Додаткові відомості див. у властивості Application.Version та методі ApplicationData.SetVersionAsync.
Пов'язані статті
Джерело цього вмісту можна знайти на GitHub, де також можна створювати та переглядати проблеми та запити на витягування.Для отримання додаткових відомостей див. у нашому посібнику для учасників.