App data storage

Artigo
10/06/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

App data is mutable data that is specific to a particular app. It includes runtime state, user preferences, and other settings. App data is created, read, updated, and deleted when the app is running.

We recommend that Windows Runtime apps use app data stores for settings and files that are specific to each app and user. The system manages the data stores for an app, ensuring that they are kept isolated from other apps and other users. The system also preserves the contents of these data stores when the user installs an update to your app and removes the contents of these data stores completely and cleanly when your app is uninstalled.

The application data sample shows how to use the Windows Runtime app data APIs to store and retrieve data that is specific to each user and Windows Runtime app.

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 OneDrive be used to store this sort of information. App data is ideal for storing app-specific user preferences, settings, and favorites.

App data storage

When an app is installed, the system gives it its own per-user data stores for app data such as settings and files. You don't need to know where or how this data exists, because the system is responsible for managing the physical storage. Just use the app data API, which makes it easy for you to work with your app data.

These are the data stores:

local
Data that exists on the current device and is backed up in the cloud.
roaming
Data that exists on all devices on which the user has installed the app.
temporary
Data that could be removed by the system at any time.
localcache
Persistent data that exists only on the current device.

If your app is removed, these data stores are deleted.

You can optionally version the app data for your app. This would enable you to create a future version of your app that changes the format of its app data without causing compatibility problems with the previous version of your app. The app checks the version of the app data in the data store, and if the version is less than the version the app expects, the app should update the app data to the new format and update the version. For more info, see the Application.Version property and the ApplicationData.SetVersionAsync method.

App settings

Settings in the app data store are stored in the registry. When you use the app data API, registry access is transparent. Within its app data store, each app has a root container for settings. Your app can add settings and new containers to the root container. Create new containers to help you organize your settings. Note that containers can be nested up to 32 levels deep, with no restriction on the breadth of the tree.

Use composite settings to easily handle atomic updates of interdependent settings. The system ensures the integrity of composite settings during concurrent access and roaming. Composite settings are optimized for small amounts of data, and performance can be poor if you use them for large data sets.

App settings can be local or roaming. The settings that your app adds to the local data store are present only on the local device. The system automatically synchronizes settings your app adds to the roaming data store on all devices on which the user has installed the app.

Most of the Windows Runtime data types are supported for app settings:

UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, Double
Boolean
Char16, String
DateTime, TimeSpan
GUID, Point, Size, Rect
ApplicationDataCompositeValue

Note that there is no binary type. If you need to store binary data, use an app file.

You can't directly assign other types of objects to app data. You can serialize data to one of the supported data types, for example you can serialize your data as JSON and store it as a string, but you need to handle the serialization.

The system ensures that the size of the data written matches the size of the data type. The system does not validate the data, so you must check whether the data has changed between the time you write it and read it back.

App files

Files in the app data store are stored in the file system. Apps can use files in the app data store just as they use files in the AppData part of the user's profile in Windows 7. Within its app data store, each app has system-defined root directories: one for local files, one for roaming files, and one for temporary files. Your app can add new files and new directories to the root directory. Create new directories to help you organize your files. Note that directories in the app data store can be nested up to 32 levels deep, with no restriction on the breadth of the tree.

App files can be local or roaming. The files that your app adds to the local data store are present only on the local device. The system automatically synchronizes files your app adds to the roaming data store on all devices on which the user has installed the app.

Local app data

Local app data should be used for any information that needs to be preserved between app sessions and is not suitable type or size wise, for roaming app data. Data that is not applicable on other devices should be stored here as well. There are no general size restriction on local data stored. Location is available via thelocalFolder property. Use the local app data store for data that it does not make sense to roam and for large data sets.

For example code, see:

Roaming app data

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.

The OS limits the size of the app data that each app may roam. See ApplicationData.RoamingStorageQuota | 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.

Typically, an app does not expect its data to change. However, roaming app data can change at any time. An app should register to handle the DataChanged | datachanged event, which occurs whenever roaming app data changes.

If the app data on a device is updated to a new version because the user installed a newer version of the app, its app data is copied to the cloud. The system does not update app data to other devices on which the user has the app installed until the app is updated on those devices as well.

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. The current policy specifies that this time interval is 30 days. Location is available via the roamingFolder property.

The operating system roams app data opportunistically and doesn't guarantee an instant sync. In scenarios where a user is offline or on a high latency network, roaming could be delayed significantly. For important, time critical settings a special high priority settings unit is available that provides more frequent updates. It is limited to one specific settings unit that must be named “HighPriority”. It can be a composite, but the total size is limited to 8KB. This limit is not enforced and the setting unit or setting composite will be treated as a regular setting unit or a composite in case the limit is exceeded.

For example code, see:

For guidelines, see Guidelines for roaming app data.

Temporary app data

The temporary app data store works like a cache. Its files do not roam and could be removed at any time. The System Maintenance task can automatically delete data stored at this location at any time. The user can also clear files from the temporary data store using Disk Cleanup. Temporary app data can be used for storing temporary information during an app session. There is no guarantee that this data will persist beyond the end of the app session as the system might reclaim the used space if needed. Location is available via temporaryFolder property.

For example code, see: