This blog was written by Hector Barbera and Sean McKenna–Program Managers, Developer and Ecosystem Platform – Operating Systems Group
In the first of this pair of posts, we covered one of the biggest additions to Windows Phone’s backup-and-restore functionality in the 8.1 release: the Start screen. In this post, we’ll cover the other major addition: app data.
App data often includes valuable settings, configurations, game state, and usage history, any of which can take a long time to recreate. When this data doesn’t migrate to a new device, it’s both an inconvenience for the user and a loss of hours of valuable engagement with your app. With the addition of app-data backup and restore in Windows Phone 8.1, that inconvenience and loss of engagement become things of the past.
Background
To ensure that your app works well with backup and restore, it’s important to consider the full scope of app data that can be present on a phone. While most of an app’s state resides in its local app-data container—also known as isolated storage—other content resides in other places such as coupons in the wallet, contacts in the address book, and event data in the calendar. Not all of this data is backed up in Windows Phone 8.1, so there’s the potential for issues if your app has dependencies between what’s backed up and what isn’t. The goal of this post is to help you prepare your app to handle app-data restore.
The backup-and-restore feature itself is pretty straightforward. Assuming the user hasn’t disabled app-data backup, here’s how it works: once a day, when the phone is idle, connected to AC power, and connected to a Wi-Fi network, the backup and restore engine looks for changes across the device and syncs them to Microsoft OneDrive. This includes looking for changes in specific folders of backup-eligible apps. By default, the set of eligible apps includes all Store apps targeting Windows Phone 8.1, including Windows Runtime apps and Windows Phone Silverlight apps.
When the user sets up a new device and chooses to restore a backup, any app data included in that backup is restored as part of the system-initiated app installation. When an app is ready to launch for the first time, its app data is available in the same state as it was at the time of the backup.
What you need to do
The good news is that if you’re developing a Windows Phone 8.1 app and want to take advantage of app data backup, you don’t have to do much. The first step is simply to understand the options for storing data in the Windows Phone app data model, which is accessible through the Windows.Storage.ApplicationData class. Those options are:
- Roaming. This container supports both unstructured data (files) and structured data (settings). Data stored here is eligible for roaming synchronization between the user’s devices (including synchronization between Windows and Windows Phone for universal apps with a shared identity). Roaming data may also be backed up under certain conditions (for example, when the user has disabled roaming) in order to capture the entirety of the app’s state.
- Local. This is the default storage location. It also supports storage of both unstructured data (files) and structured data (settings). Note that for Windows Phone Silverlight apps, Local maps to the IsolatedStorage folder. All data in Local is backed up to the cloud.
- LocalCache. This is identical to Local except that it is always excluded from backups.
- Temporary. This container allows you to store unstructured data (files) that are excluded from backups. These files can be cleaned up by the system in the event of a low-storage situation.
Best practices for backup
Here are some tips for backing up your app data efficiently:
- Use Local to store only data that can’t be regenerated without user input. Examples of such data include app configuration, game progress, or user-generated content like voice recordings or typed notes. Because backed-up data counts against the user’s OneDrive quota, don’t use Local (or Roaming) for temporary files or data that can easily be recreated or download as needed.
- Use LocalCache to store data that you want to preserve across app sessions but that you don’t want to be backed up. LocalCache is intended for data that’s important to your app but that shouldn’t be replicated in OneDrive. There are several possible reasons to choose LocalCache:
- Avoiding duplication—The data is already available in the cloud and can easily be downloaded as needed (for example. an e-book title or news article).
- Privacy concerns—The data is confidential and should not leave the device.
- Encryption—The data is encrypted with a device-based key and would be unusable when restored on a different device.
- Use the Temporary folder for data that you don’t need to save between app sessions. The Temporary folder is eligible for clean up whenever the device reaches a low-storage threshold.
Potential issues
Here are some situations to look out for as you back up and restore app data.
Running for the first time
There are some tasks that an app might need to do when running for the first time, such as asking for user credentials. With the introduction of app-data backup, your app can no longer assume that it has already run on a particular device based on the presence of certain data in its Local app data location. If you need to keep track of whether your app has already run on the current device, persist a local flag and store it in the LocalCache folder.
Encryption
When you store sensitive data locally on the phone, it’s highly recommended that you use the Windows Data Protection API (DPAPI) to encrypt the data first. It’s important to note, however, that DPAPI uses an encryption key that is based on the device that it’s running on. So if you try to decrypt that data on after restoring it on a new device, the decryption operation will fail.
If you’re encrypting data with DPAPI, either store it in the LocalCache folder or be prepared to handle the decryption failure on a new device. If you’re storing user names and passwords, use the PasswordVault object in the Windows.Security.Credentials namespace. If enabled by the user, the PasswordVault roams across all Windows devices, which means that it’s available for use on a new phone following restore.
Content licenses
Content licenses present similar challenges to data encryption. If your app acquires licenses that are tied to a specific device, consider storing them in the LocalCache folder.
Testing your app with app-data backup and restore
If you store all of your app data in the Local folder, you can simulate a device restore using the Isolated Storage Explorer tool (ISETool) by following these steps. (Note that the ISETool does not currently support interaction with the Roaming, Temporary, or LocalCache folders, or the Local settings container.)
1. Deploy your app to your developer device or emulator using Microsoft Visual Studio.
2. Use the app and create the state you want to test on restore.
3. Close the app.
4. Using the Isolated Storage Explorer tool, copy your Local folder to your PC:
- Using the emulator:
ISETool.exe ts xd <your app’s product ID> <path to an empty folder on your PC> - Using a physical phone:
ISETool.exe ts de <your app’s product ID> <path to an empty folder on your PC>
5. Uninstall the app. This clears your app’s state.
6. Deploy your app again. If you want to test for hardware dependencies, try restoring to a device that’s different from the one you used in step 4.
7. Using the Isolated Storage Explorer tool, restore to your device the data that you backed up:
- Using the emulator:
ISETool.exe rs xd <your app’s product ID> <path to an empty folder on your PC> - Using a physical phone:
ISETool.exe rs de <your app’s product ID> <path to an empty folder on your PC>
8. Launch your app and make sure all features work as you would expect following a device restore.
Opting out
While we hope that most app developers are pleased with the arrival of app-data backup and restore, we understand that there are reasons why you might want to opt out some or all of your data. The preferred method is to segment your data based on the data model described earlier—that is, using the LocalCache folder for data that you do not wish to store outside the device. This approach lets you take advantage of backup for some data while opting out content that might be sensitive or inappropriate for backup.
Of course, because the segmented app-data model is new for Windows Phone 8.1, you probably need to do some work before your data is cleanly separated. If you’d like to update your Windows Phone Silverlight app to target Windows Phone 8.1 without worrying about data migration just yet, you can simply opt out of backup altogether. Just use a flag in the Packaging tab of the WMAppManifest.xml file, as shown here.
Final notes
App-data backup and restore is a significant new feature in Windows Phone 8.1. Users who have spent significant time and energy engaging with your apps will now be able to carry that forward to new devices with little or no work on your part. We hope this post has helped you understand how backup and restore works and how your app can take advantage of it.