Guidelines for roaming app data
When you store app data using the roaming ApplicationData APIs, Windows replicates this data to the cloud and synchronizes the data to all other user devices on which the app is installed. Follow these guidelines when you design your Universal Windows Platform (UWP) app to include roaming app data.
Use roaming data to store a user's settings, preferences, and session info to create a cohesive app experience across multiple devices. Keep in mind that roaming data is associated with a user's Microsoft account. Roaming data will only sync if a user logs into her devices using the same Microsoft account and installs the app on several devices.
For example, if a user installs your app on a second device after installing it on another device, all preferences set on the first device are automatically applied to the app on the second device (assuming the user uses the same Microsoft account to log into both devices). Any future changes to these settings and preferences will also transition automatically, providing a uniform experience regardless of device. By storing session info as roaming data, you'll enable users to continue an app session that was closed or abandoned on one device when they transfer to another device.
- File types that behave like folders (for example, files with the .zip and .cab extensions)
- Files that have names with leading spaces
- Files that have names with these unicode characters:
e794, e795, e796, e7c7, e816, e817, e818, e81e, e826, e82b, e82c, e831, e832, e83b, e843, e854, e855, e864, e7e2, e7e3, and e7f3
- File paths (file name + extension) that are longer than 256 characters
- Empty folders
- Files with open handles
- 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.
- 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. For example, roam a URL rather than the content of an online article.
- 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. 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. 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 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 roam 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.
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 be local to each device.
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.
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.
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.
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.
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. 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.
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:
- 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.
- For developers (XAML)
- Store and retrieve app data