In today’s blog post, we will talk about local data, or data that is tied to the specific device where it was created. We will be looking at the different features that the Universal Windows Platform provides you with to do this, examples, and best practices.
Types of app data
There are two types of app data: settings and files.
- Settings. Use settings to store app state and user preferences. The Universal Windows Platform (UWP) provides APIs to easily store and retrieve settings. The data types you can use in app settings are:
- Files. Use files to store binary data or to serialize your own custom types.
Storing app data locally
When an app is installed, the system creates a per-user app data container on the device. This app data container is within the app sandbox, which means no other app will be able to access it. The system will preserve the content of the data container when the app is updated and will remove it when the user uninstalls the app.
As a developer, you have three locations available in the app data container to store data locally:
Local
Local can contain both files (LocalFolder) and settings (LocalSettings) and should be used for any information that is of user value and can’t easily be recreated or downloaded. Data stored in Local can be backed up by the system if the device supports App Data Backup. Because of this, you should avoid using Local to store cached or temporary files that you could create or fetch again on demand.
App Data Backup
During a device backup operation, the system will grab any app data in Local and store it as part of a device backup image in OneDrive. If the user resets or replaces the device, he or she will be given the choice to restore a previous backup, which will restore the app data in Local as part of the app’s installation. Note that by not storing data in Local you will effectively be opting out of backup for your app.
Best practices for Local
- Use for data with user value that can’t be recreated or downloaded by your app. If you place cached content or throwaway data in Local you are wasting user storage on OneDrive and delaying how long it takes to install your app during a device restore.
- Use for settings that are unique to a device. In general, it is desirable to have common user settings on all of the user’s devices. However if you have settings that you don’t want roamed you should store them in Local.
- Do not store credentials in Local. In order to offer the best user experience around credentials, you should be using the Credential Locker feature.
- Avoid it for data tied to specific hardware. If you have data that can only be consumed on the same physical device where it was created do not place in Local, because the user may choose to restore this data to a different device. One example of data tied to specific hardware is anything derived from device ID.
Using LocalFolder
To read or write files in LocalFolder, you must use the ApplicationData.LocalFolder property; you will get back a StorageFolder. You can then use StorageFolder.CreateFileAsync and StorageFolder.GetFileAsync to write and read files.
[code language=”csharp”]
//Create dataFile.txt in LocalFolder and write “My text” to it
StorageFolder localFolder = ApplicationData.Current.LocalFolder;
StorageFile sampleFile = await localFolder.CreateFileAsync("dataFile.txt");
await FileIO.WriteTextAsync(sampleFile, "My text");
//Read the first line of dataFile.txt in LocalFolder and store it in a String
StorageFile sampleFile = await localFolder.GetFileAsync("dataFile.txt");
String fileContent = await FileIO.ReadTextAsync(sampleFile);
[/code]
Using LocalSettings
To read or write settings in LocalSettings, you must use the ApplicationData.LocalSettings property; you will get back an ApplicationDataContainer. You can then access the content of LocalSettings through the Values property.
[code language=”csharp”]
//Check if setting #postsToDownload exists and create it if it does not
ApplicationDataContainer localSettings = ApplicationData.Current.LocalSettings;
var value = localSettings.Values["#postsToDownload"];
if (value == null)
{
localSettings.Values["#postsToDownload"] = 5;
}
[/code]
LocalCache
Use LocalCache to store app data that you want persisted across app sessions, but that should not be backed up by the system. LocalCache is the right place for data with the same lifetime as your app and that can be easily recreated or downloaded as needed.
Best practices for LocalCache
- Use it for cached or generated content you need across app sessions. If you are downloading online files, LocalCache is probably the right place for them.
- Use it for authentication tokens. Authentication tokens should not be backed up and LocalCache is generally the right location for them.
Using LocalCache
LocalCache can only contain files and is accessed through the ApplicationData.LocalCacheFolder property.
[code language=”csharp”]
//Create dataFile.txt in LocalCacheFolder and write “My text” to it
StorageFolder localCacheFolder = ApplicationData.Current.LocalCacheFolder;
StorageFile sampleFile = await localCacheFolder.CreateFileAsync("dataFile.txt");
await FileIO.WriteTextAsync(sampleFile, "My text");
//Read the first line of dataFile.txt in LocalCacheFolder and store it in a String
StorageFile sampleFile = await localCacheFolder.GetFileAsync("dataFile.txt");
String fileContent = await FileIO.ReadTextAsync(sampleFile);
[/code]
Temporary
As the name suggests, the Temporary App Data store is the right place for data that you don’t want persisted after the current app session. The system can delete data stored at this location as needed to free up space.
Best practices for Temporary
- Use Temporary for any intermediate or temporary files. If you won’t need a file after your app is terminated or suspended, this is the right location for it.
- Clean your Temp folder during app initialization. If you are writing large amounts of data to Temp, it is a good idea to clear it when your app is initialized to avoid the system or the user having to take action to free up storage.
Using the Temporary App Data store
Use ApplicationData.TemporaryFolder to get a StorageFolder and access the Temporary App Data store. You can then use the different StorageFolder methods to write and read files.
[code language=”csharp”]
//Create dataFile.txt in TemporaryFolder and write “My text” to it
StorageFolder tempFolder = ApplicationData.Current.TemporaryFolder;
StorageFile sampleFile = await tempFolder.CreateFileAsync("dataFile.txt");
await FileIO.WriteTextAsync(sampleFile, "My text");
//Read the first line of dataFile.txt in Temp and store it in a String
StorageFile sampleFile = await tempFolder.GetFileAsync("dataFile.txt");
String fileContent = await FileIO.ReadTextAsync(sampleFile);
[/code]
Wrapping Up
In this post, we have provided you with an introduction to storing app data locally as well as examples and best practices. Hopefully, you’ll be able to use this information to create experiences that delight your users.
Additional Resources
- Build 2016 session on UWP Application Data
- Store and retrieve settings and other app data
- Windows Universal Samples – Application data sample
- ApplicationData class
- Getting started with roaming app data
- Roaming app data and the user experience
Written by Hector Barbera, Program Manager for Developer Ecosystem and Platform