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 Windows Store 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.
Note These kinds of files won't roam even if they are placed in the RoamingFolder:
- 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.
- 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.
Developers can use the Windows 8 Roaming Monitor to monitor and affect the status of their app's roaming state.
If you publish two versions of your app - a version for Windows Store and a version for Windows Phone - you can roam app data across the apps running on the two different types of devices. To roam data across different versions of your app on different types of devices, assign the same Package Family Name (PFN) to each version of the app.
For more info, see How to roam data between a Windows Store app and a Windows Phone Store app.
- App data overview
- Quickstart: Roaming application data
- For developers (Windows Runtime apps using C#/VB/C++ and XAML)
- App data overview
- Quickstart: Roaming application data (C#/VB/C++)
- Application data sample