|
1 | 1 | --- |
2 | 2 | description: Learn how to store and retrieve local and temporary app data. |
3 | 3 | title: Store and retrieve settings and other app data |
4 | | -ms.assetid: 41676A02-325A-455E-8565-C9EC0BC3A8FE |
5 | 4 | label: App settings and data |
6 | 5 | template: detail.hbs |
7 | | -ms.date: 11/14/2017 |
| 6 | +ms.date: 04/08/2026 |
8 | 7 | ms.topic: how-to |
9 | | -keywords: windows 10, uwp |
| 8 | +keywords: windows 11, winui |
10 | 9 | ms.localizationpriority: medium |
11 | 10 | --- |
12 | 11 | # Store and retrieve settings and other app data |
13 | 12 |
|
14 | | -*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. |
| 13 | +> [!IMPORTANT] |
| 14 | +> The [ApplicationData](/uwp/api/Windows.Storage.ApplicationData) APIs described in this article are designed for packaged apps. Unpackaged apps do not have access to the system-managed app data stores and should use alternative storage mechanisms such as direct file I/O or registry access. |
| 15 | +
|
| 16 | +*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. |
15 | 17 |
|
16 | 18 | **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. 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. |
17 | 19 |
|
@@ -149,188 +151,6 @@ async void ReadTimestamp() |
149 | 151 | > [!WARNING] |
150 | 152 | > Roaming data and settings is [no longer supported as of Windows 11](/windows/deployment/planning/windows-10-deprecated-features). |
151 | 153 | > The recommended replacement is [Azure App Service](/azure/app-service/). Azure App Service is widely supported, well documented, reliable, and supports cross-platform/cross-ecosystem scenarios such as iOS, Android and web. |
152 | | -> |
153 | | -> The following documentation applies to Windows 10 versions 1909 and lower. |
154 | | -
|
155 | | -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. |
156 | | - |
157 | | -The OS limits the size of the app data that each app may roam. See [**ApplicationData.RoamingStorageQuota**](/uwp/api/windows.storage.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. |
158 | | - |
159 | | -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. |
160 | | - |
161 | | -### Roaming data do's and don'ts |
162 | | - |
163 | | -> See important note about [roaming data](#roaming-data). |
164 | | -
|
165 | | -- 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. |
166 | | -- Use roaming to let users continue a task across devices. For example, roam app data like the contents of a drafted email or the most recently viewed page in a reader app. |
167 | | -- Handle the [**DataChanged**](/uwp/api/windows.storage.applicationdata.datachanged) event by updating app data. This event occurs when app data has just finished syncing from the cloud. |
168 | | -- Roam references to content rather than raw data. For example, roam a URL rather than the content of an online article. |
169 | | -- For important, time critical settings, use the *HighPriority* setting associated with [**RoamingSettings**](/uwp/api/windows.storage.applicationdata.roamingsettings). |
170 | | -- 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. |
171 | | -- Don't roam large sets of app data. There's a limit to the amount of app data an app may roam; use [**RoamingStorageQuota**](/uwp/api/windows.storage.applicationdata.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. For example, if saving a game state requires 10KB each, the app might only allow the user store up to 10 games. |
172 | | -- Don't use roaming for data that relies on instant syncing. 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. |
173 | | -- 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. |
174 | | - |
175 | | -### Roaming pre-requisites |
176 | | - |
177 | | -> See important note about [roaming data](#roaming-data). |
178 | | -
|
179 | | -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. |
180 | | - |
181 | | -Data stored in the [**PasswordVault**](/uwp/api/Windows.Security.Credentials.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. |
182 | | - |
183 | | -### Conflict resolution |
184 | | - |
185 | | -> See important note about [roaming data](#roaming-data). |
186 | | -
|
187 | | -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. |
188 | | - |
189 | | -### When to write data |
190 | | - |
191 | | -> See important note about [roaming data](#roaming-data). |
192 | | -
|
193 | | -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. 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. |
194 | | - |
195 | | -### Excessive usage protection |
196 | | - |
197 | | -> See important note about [roaming data](#roaming-data). |
198 | | -
|
199 | | -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. |
200 | | - |
201 | | -### Versioning |
202 | | - |
203 | | -> See important note about [roaming data](#roaming-data). |
204 | | -
|
205 | | -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. |
206 | | - |
207 | | -App data only roams between installed apps with the same version number. 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. |
208 | | - |
209 | | -### Testing and tools |
210 | | - |
211 | | -> See important note about [roaming data](#roaming-data). |
212 | | -
|
213 | | -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: |
214 | | - |
215 | | -- Your roaming data does not exceed the maximum size (see [**RoamingStorageQuota**](/uwp/api/windows.storage.applicationdata.roamingstoragequota) for details). |
216 | | -- Your files are closed and released properly. |
217 | | -- There are at least two devices running the same version of the app. |
218 | | - |
219 | | -### Register to receive notification when roaming data changes |
220 | | - |
221 | | -> See important note about [roaming data](#roaming-data). |
222 | | -
|
223 | | -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. |
224 | | - |
225 | | -1. Register to receive notification when roaming data changes. |
226 | | - |
227 | | - The [**DataChanged**](/uwp/api/windows.storage.applicationdata.datachanged) event notifies you when roaming data changes. This example sets `DataChangeHandler` as the handler for roaming data changes. |
228 | | - |
229 | | -```csharp |
230 | | -void InitHandlers() |
231 | | - { |
232 | | - Windows.Storage.ApplicationData.Current.DataChanged += |
233 | | - new TypedEventHandler<ApplicationData, object>(DataChangeHandler); |
234 | | - } |
235 | | - |
236 | | - void DataChangeHandler(Windows.Storage.ApplicationData appData, object o) |
237 | | - { |
238 | | - // TODO: Refresh your data |
239 | | - } |
240 | | -``` |
241 | | - |
242 | | -2. Get the containers for the app's settings and files. |
243 | | - |
244 | | - Use the [**ApplicationData.RoamingSettings**](/uwp/api/windows.storage.applicationdata.roamingsettings) property to get the settings and the [**ApplicationData.RoamingFolder**](/uwp/api/windows.storage.applicationdata.roamingfolder) property to get the files. |
245 | | - |
246 | | -```csharp |
247 | | -Windows.Storage.ApplicationDataContainer roamingSettings = |
248 | | - Windows.Storage.ApplicationData.Current.RoamingSettings; |
249 | | - Windows.Storage.StorageFolder roamingFolder = |
250 | | - Windows.Storage.ApplicationData.Current.RoamingFolder; |
251 | | -``` |
252 | | - |
253 | | -### Create and retrieve roaming settings |
254 | | - |
255 | | -> See important note about [roaming data](#roaming-data). |
256 | | -
|
257 | | -Use the [**ApplicationDataContainer.Values**](/uwp/api/windows.storage.applicationdatacontainer.values) property to access the settings in the `roamingSettings` container we got in the previous section. This example creates a simple setting named `exampleSetting` and a composite value named `composite`. |
258 | | - |
259 | | -```csharp |
260 | | -// Simple setting |
261 | | -
|
262 | | -roamingSettings.Values["exampleSetting"] = "Hello World"; |
263 | | -// High Priority setting, for example, last page position in book reader app |
264 | | -roamingSettings.values["HighPriority"] = "65"; |
265 | | - |
266 | | -// Composite setting |
267 | | -
|
268 | | -Windows.Storage.ApplicationDataCompositeValue composite = |
269 | | - new Windows.Storage.ApplicationDataCompositeValue(); |
270 | | -composite["intVal"] = 1; |
271 | | -composite["strVal"] = "string"; |
272 | | - |
273 | | -roamingSettings.Values["exampleCompositeSetting"] = composite; |
274 | | - |
275 | | -``` |
276 | | - |
277 | | -This example retrieves the settings we just created. |
278 | | - |
279 | | -```csharp |
280 | | -// Simple setting |
281 | | -
|
282 | | -Object value = roamingSettings.Values["exampleSetting"]; |
283 | | - |
284 | | -// Composite setting |
285 | | -
|
286 | | -Windows.Storage.ApplicationDataCompositeValue composite = |
287 | | - (Windows.Storage.ApplicationDataCompositeValue)roamingSettings.Values["exampleCompositeSetting"]; |
288 | | - |
289 | | -if (composite == null) |
290 | | -{ |
291 | | - // No data |
292 | | -} |
293 | | -else |
294 | | -{ |
295 | | - // Access data in composite["intVal"] and composite["strVal"] |
296 | | -} |
297 | | -``` |
298 | | - |
299 | | -### Create and retrieve roaming files |
300 | | - |
301 | | -> See important note about [roaming data](#roaming-data). |
302 | | -
|
303 | | -To create and update a file in the roaming app data store, use the file APIs, such as [**Windows.Storage.StorageFolder.CreateFileAsync**](/uwp/api/windows.storage.storagefolder.createfileasync) and [**Windows.Storage.FileIO.WriteTextAsync**](/uwp/api/windows.storage.fileio.writetextasync). This example creates a file named `dataFile.txt` in the `roamingFolder` container and writes the current date and time to the file. The **ReplaceExisting** value from the [**CreationCollisionOption**](/uwp/api/Windows.Storage.CreationCollisionOption) enumeration indicates to replace the file if it already exists. |
304 | | - |
305 | | -```csharp |
306 | | -async void WriteTimestamp() |
307 | | -{ |
308 | | - Windows.Globalization.DateTimeFormatting.DateTimeFormatter formatter = |
309 | | - new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("longtime"); |
310 | | - |
311 | | - StorageFile sampleFile = await roamingFolder.CreateFileAsync("dataFile.txt", |
312 | | - CreationCollisionOption.ReplaceExisting); |
313 | | - await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTimeOffset.Now)); |
314 | | -} |
315 | | -``` |
316 | | - |
317 | | -To open and read a file in the roaming app data store, use the file APIs, such as [**Windows.Storage.StorageFolder.GetFileAsync**](/uwp/api/windows.storage.storagefolder.getfileasync), [**Windows.Storage.StorageFile.GetFileFromApplicationUriAsync**](/uwp/api/windows.storage.storagefile.getfilefromapplicationuriasync), and [**Windows.Storage.FileIO.ReadTextAsync**](/uwp/api/windows.storage.fileio.readtextasync). 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](/previous-versions/windows/apps/hh965322(v=win.10)). |
318 | | - |
319 | | -```csharp |
320 | | -async void ReadTimestamp() |
321 | | -{ |
322 | | - try |
323 | | - { |
324 | | - StorageFile sampleFile = await roamingFolder.GetFileAsync("dataFile.txt"); |
325 | | - String timestamp = await FileIO.ReadTextAsync(sampleFile); |
326 | | - // Data is contained in timestamp |
327 | | - } |
328 | | - catch (Exception) |
329 | | - { |
330 | | - // Timestamp not found |
331 | | - } |
332 | | -} |
333 | | -``` |
334 | 154 |
|
335 | 155 | ## Temporary app data |
336 | 156 |
|
|
0 commit comments