W
Windows Apps Team
This post was written by Kraig Brockschmidt, Senior Program Manager in the Operating Systems Group
Lately we’ve heard some recurring questions from you about files and app data, so we’ve compiled a list of those questions and provided some brief answers here. In this first part, we’ll cover your app data questions. In part 2, we’ll answer some common questions about files and file access. Both posts apply equally to Windows 8.1 and Windows Phone 8.1.
Questions in this post:
Q. How does app data differ from user data?
A. App data is state that an app manages within its app data folders (Local, Roaming, and Temporary, along with LocalCache on Windows Phone 8.1). Its existence is tied to the existence of the app so that uninstalling the app deletes the app data from that device. Roaming app data persists in the cloud independently (see the next question), and is shared between Windows and Windows Phone apps that have the same Package Family Name in their manifests. User data, like pictures, videos, music, and documents, is stored anywhere else on the file system or the cloud, in libraries or in other locations selected through the file picker or folder picker UI. The lifetime of user data is not tied to any particular app and is controlled entirely by the user. References: App data (overview docs), Accessing app data (overview docs), Windows.Storage.ApplicationData class, Application data sample.
Q. How should I store user credentials?
A. Always store user credentials (user name and password), as well as similarly sensitive data, in the Credential Locker by using the Windows.Security.PasswordVault class. The contents of the locker are automatically encrypted and, by default, roam across the user’s devices (if allowed through PC Settings > OneDrive > Sync Settings > Other Settings > Passwords and the device is trusted). Locker contents are also isolated between apps. Note that although PasswordVault is designed around user names and passwords, you can use it to help secure other values such as API access keys or tokens; just assign a suitable user ID to the user name and assign the key/token to the password. In short, think of the Credential Locker as the security-oriented extension to the other elements of the app data API. References: PasswordVault class, Storing user credentials (how-to documentation), Credential Locker sample.
Q. What happens to roaming app data when an app is uninstalled?
A. As noted in the previous question, an app’s app data folders are removed from a device when the app is uninstalled. Roaming app data, however, persists in the cloud so long as the user has the same app installed on other devices. When the user uninstalls the app from all of his or her devices, roaming app data continues to persist in the cloud for a reasonable time (a matter of a few weeks) so that it’s still available if the user decides to reinstall the app within that time. Note that when you make a change to an app project in Microsoft Visual Studio and that change (such as changing the manifest) forces a full reinstall, app data is removed as part of the process. References: Guidelines for roaming app data (overview docs).
Q. What happens to app data when an app is updated?
A. App data is preserved across app updates delivered by the Windows Store and the Windows Phone Store. So app updates must be prepared to load app data that was generated by any previous version of the app. References: Accessing app data (overview docs).
Q. How is app data affected during development with multiple build/deploy cycles?
A. As you develop an app, app data is normally preserved across build iterations. However, changing the manifest triggers a full uninstall and redeployment from within Visual Studio, and that deletes any existing app data. To manually preserve that app data, copy the contents of the %localappdata%\packages\<your package> folder to a temporary location, build and redeploy the app, and then copy the app data back. Note that this redeployment behavior in Visual Studio is a separate matter from updating an app from the Store or via side-loading, in which case the deployment engine does not uninstall the previous version and app data is therefore preserved.
Q. How does the system handle conflicts in roaming app data that’s been modified on multiple devices?
A. The policy is simple: the last writer wins. At run time, an app can detect whether new roaming data has arrived on the local device by listening for the ApplicationData.DataChanged event.
Q. What’s the difference between the Local, LocalCache, and Temporary app data locations?
A. On Windows Phone 8.1, the Local and LocalCache folders are both intended for storing device-specific (that is, non-roaming) app data. The difference is that Local app data is included with Windows Phone 8.1 backups, whereas LocalCache and Temporary are not. The difference between LocalCache and Temporary is that the system can delete Temporary app data at any time to free up storage resources, whereas LocalCache data is under the app’s control. References: ApplicationDataLocality enumeration,
Q. How does an app use the ms-appdata URI scheme?
A. The ms-appdata:/// URI scheme is a URI shortcut to app data folders, which is often more convenient for referring to images or content that you want to load into a Webview control. The specific forms are ms-appdata:///local (or localcache), ms-appdata:///roaming, and ms-appdata:///temp.
Q. What’s the difference between the folders and the settings containers in the Windows.Storage.ApplicationData class?
A. The LocalFolder, RoamingFolder, and TemporaryFolder properties (and LocalCacheFolder on Windows Phone 8.1) each map to discrete folders within the app’s root app data folder, which is located in %localappdata%\packages\{app_package_family_name}\. An app can create any files it wants within these folders, supporting what we call “unstructured” data. The LocalSettings and RoamingSettings properties map instead to a single data file in which the app can maintain a hierarchy of key-value pairs, which we call “structured” data. The settings file is names settings.dat and can be found in a folder called Settings in the same location as the other folders.
Q. Is local or roaming app data secured in any way?
A. No, there is no automatic encryption for local or roaming app data. You can add that yourself by using the Windows.Security.Cryptography APIs. Note that user credentials and other sensitive values are best stored in the Credential Locker (see the earlier question about storing credentials).
Q. How does app data version compare with the version of the app itself?
A. The version number that you set by using Windows.ApplicationData.SetVersionAsync is independent from the version number of the app as set in its manifest. Any number of app versions can share the same app data version. When an app update needs to change the structure of the app data, it should call SetVersionAsync and provide a callback method to handle migration of an older version of its state. Subsequent updates can then continue to use that same app data version until such time as another change is needed. Generally speaking, an app will change the version of its app data much less frequently than it changes the app version number in its manifest. Note also that the app data version applies to all state info as managed through the ApplicationData class, including the files in all the folders and the contents of both settings containers.
Q. What are the effects of app data versioning?
A. The version of your app data primarily determines how different versions of roaming state are managed in the cloud. OneDrive maintains the most recent copy of each version of roaming app data that is in use by those versions of the app that the user has installed. That is, there can be multiple simultaneous versions of the app data in the cloud at any one time. The version that’s roamed to a particular device is the one that’s appropriate to the app installed on that device, and only that one.
Q. How can an app clear its app data?
A. Call Windows.Storage.ApplicationData.Current.ClearAsync, with an optional ApplicationDataLocality value to limit the scope.
Q. Can I use my app’s installation location for app data?
A. At run time, the Windows.ApplicationModel.Package.InstalledLocation property contains a StorageFolder object through which you can access any of your app’s package contents with read-only permissions. You cannot write to the package folder, however. Apps typically use the InstalledLocation folder to load startup data or other initialization parameters, possibly copying those values to the app data LocalFolder if further modifications are to be made at run time. Note that the ms-appx:/// and ms-appx-web:/// URI schemes can also be used to access package contents.
Q. Can background tasks access app data?
A. Yes! App data is, in fact, the way to exchange information between an app and its background tasks, even if the background tasks are written in a different language than the app.
Resources:
Continue reading...
Lately we’ve heard some recurring questions from you about files and app data, so we’ve compiled a list of those questions and provided some brief answers here. In this first part, we’ll cover your app data questions. In part 2, we’ll answer some common questions about files and file access. Both posts apply equally to Windows 8.1 and Windows Phone 8.1.
Questions in this post:
- How does app data differ from user data?
- How should I store user credentials?
- What happens to roaming app data when an app is uninstalled?
- What happens to app data when an app is updated?
- How is app data affected during development with multiple build/deploy cycles?
- How does the system handle conflicts in roaming app data that’s been modified on multiple devices?
- What’s the difference between the Local, LocalCache, and Temporary app data locations?
- How does an app use the ms-appdata URI scheme?
- What’s the difference between the folders and the settings containers in the Windows.Storage.ApplicationData class?
- Is local or roaming app data secured in any way?
- How does app data version compare with the version of the app itself?
- What are the effects of app data versioning?
- How can an app clear its app data?
- Can I use my app’s installation location for app data?
- Can background tasks access app data?
Q. How does app data differ from user data?
A. App data is state that an app manages within its app data folders (Local, Roaming, and Temporary, along with LocalCache on Windows Phone 8.1). Its existence is tied to the existence of the app so that uninstalling the app deletes the app data from that device. Roaming app data persists in the cloud independently (see the next question), and is shared between Windows and Windows Phone apps that have the same Package Family Name in their manifests. User data, like pictures, videos, music, and documents, is stored anywhere else on the file system or the cloud, in libraries or in other locations selected through the file picker or folder picker UI. The lifetime of user data is not tied to any particular app and is controlled entirely by the user. References: App data (overview docs), Accessing app data (overview docs), Windows.Storage.ApplicationData class, Application data sample.
Q. How should I store user credentials?
A. Always store user credentials (user name and password), as well as similarly sensitive data, in the Credential Locker by using the Windows.Security.PasswordVault class. The contents of the locker are automatically encrypted and, by default, roam across the user’s devices (if allowed through PC Settings > OneDrive > Sync Settings > Other Settings > Passwords and the device is trusted). Locker contents are also isolated between apps. Note that although PasswordVault is designed around user names and passwords, you can use it to help secure other values such as API access keys or tokens; just assign a suitable user ID to the user name and assign the key/token to the password. In short, think of the Credential Locker as the security-oriented extension to the other elements of the app data API. References: PasswordVault class, Storing user credentials (how-to documentation), Credential Locker sample.
Q. What happens to roaming app data when an app is uninstalled?
A. As noted in the previous question, an app’s app data folders are removed from a device when the app is uninstalled. Roaming app data, however, persists in the cloud so long as the user has the same app installed on other devices. When the user uninstalls the app from all of his or her devices, roaming app data continues to persist in the cloud for a reasonable time (a matter of a few weeks) so that it’s still available if the user decides to reinstall the app within that time. Note that when you make a change to an app project in Microsoft Visual Studio and that change (such as changing the manifest) forces a full reinstall, app data is removed as part of the process. References: Guidelines for roaming app data (overview docs).
Q. What happens to app data when an app is updated?
A. App data is preserved across app updates delivered by the Windows Store and the Windows Phone Store. So app updates must be prepared to load app data that was generated by any previous version of the app. References: Accessing app data (overview docs).
Q. How is app data affected during development with multiple build/deploy cycles?
A. As you develop an app, app data is normally preserved across build iterations. However, changing the manifest triggers a full uninstall and redeployment from within Visual Studio, and that deletes any existing app data. To manually preserve that app data, copy the contents of the %localappdata%\packages\<your package> folder to a temporary location, build and redeploy the app, and then copy the app data back. Note that this redeployment behavior in Visual Studio is a separate matter from updating an app from the Store or via side-loading, in which case the deployment engine does not uninstall the previous version and app data is therefore preserved.
Q. How does the system handle conflicts in roaming app data that’s been modified on multiple devices?
A. The policy is simple: the last writer wins. At run time, an app can detect whether new roaming data has arrived on the local device by listening for the ApplicationData.DataChanged event.
Q. What’s the difference between the Local, LocalCache, and Temporary app data locations?
A. On Windows Phone 8.1, the Local and LocalCache folders are both intended for storing device-specific (that is, non-roaming) app data. The difference is that Local app data is included with Windows Phone 8.1 backups, whereas LocalCache and Temporary are not. The difference between LocalCache and Temporary is that the system can delete Temporary app data at any time to free up storage resources, whereas LocalCache data is under the app’s control. References: ApplicationDataLocality enumeration,
Q. How does an app use the ms-appdata URI scheme?
A. The ms-appdata:/// URI scheme is a URI shortcut to app data folders, which is often more convenient for referring to images or content that you want to load into a Webview control. The specific forms are ms-appdata:///local (or localcache), ms-appdata:///roaming, and ms-appdata:///temp.
Q. What’s the difference between the folders and the settings containers in the Windows.Storage.ApplicationData class?
A. The LocalFolder, RoamingFolder, and TemporaryFolder properties (and LocalCacheFolder on Windows Phone 8.1) each map to discrete folders within the app’s root app data folder, which is located in %localappdata%\packages\{app_package_family_name}\. An app can create any files it wants within these folders, supporting what we call “unstructured” data. The LocalSettings and RoamingSettings properties map instead to a single data file in which the app can maintain a hierarchy of key-value pairs, which we call “structured” data. The settings file is names settings.dat and can be found in a folder called Settings in the same location as the other folders.
Q. Is local or roaming app data secured in any way?
A. No, there is no automatic encryption for local or roaming app data. You can add that yourself by using the Windows.Security.Cryptography APIs. Note that user credentials and other sensitive values are best stored in the Credential Locker (see the earlier question about storing credentials).
Q. How does app data version compare with the version of the app itself?
A. The version number that you set by using Windows.ApplicationData.SetVersionAsync is independent from the version number of the app as set in its manifest. Any number of app versions can share the same app data version. When an app update needs to change the structure of the app data, it should call SetVersionAsync and provide a callback method to handle migration of an older version of its state. Subsequent updates can then continue to use that same app data version until such time as another change is needed. Generally speaking, an app will change the version of its app data much less frequently than it changes the app version number in its manifest. Note also that the app data version applies to all state info as managed through the ApplicationData class, including the files in all the folders and the contents of both settings containers.
Q. What are the effects of app data versioning?
A. The version of your app data primarily determines how different versions of roaming state are managed in the cloud. OneDrive maintains the most recent copy of each version of roaming app data that is in use by those versions of the app that the user has installed. That is, there can be multiple simultaneous versions of the app data in the cloud at any one time. The version that’s roamed to a particular device is the one that’s appropriate to the app installed on that device, and only that one.
Q. How can an app clear its app data?
A. Call Windows.Storage.ApplicationData.Current.ClearAsync, with an optional ApplicationDataLocality value to limit the scope.
Q. Can I use my app’s installation location for app data?
A. At run time, the Windows.ApplicationModel.Package.InstalledLocation property contains a StorageFolder object through which you can access any of your app’s package contents with read-only permissions. You cannot write to the package folder, however. Apps typically use the InstalledLocation folder to load startup data or other initialization parameters, possibly copying those values to the app data LocalFolder if further modifications are to be made at run time. Note that the ms-appx:/// and ms-appx-web:/// URI schemes can also be used to access package contents.
Q. Can background tasks access app data?
A. Yes! App data is, in fact, the way to exchange information between an app and its background tasks, even if the background tasks are written in a different language than the app.
Resources:
- Dealing with Data: Storage, Roaming, and Backup on Windows and Windows Phone by Sean McKenna and Adam Wilson, from //build 2014.
- The Story of State: App Data, Settings, and the Process Lifecycle by Kraig Brockschmidt, from //build 2013.
- Chapter 10 of the free ebook from Microsoft Press, Programming Windows Store Apps with HTML, CSS, and JavaScript, 2nd Edition, by Kraig Brockschmidt, which despite its title is a very helpful resource for developers in all programming languages.
Continue reading...