Data for Windows Phone

[This documentation is preliminary and is subject to change.]

July 25, 2012

Applies to: Windows Phone 8 Developer Preview | Windows Phone OS 7.1

This topic describes where data resides, which APIs you can use to access data, and the versions of Windows Phone that support these APIs. This topic also lists the Win32 storage APIs that are supported on Windows Phone 8 Developer Preview.

Note Note:

This section is limited to persistent data that resides on the phone. For info about saving app and page state, see App activation and deactivation for Windows Phone. For info about accessing data that does not reside on the phone, see Communications for Windows Phone.

This topic contains the following sections.

The installation folder is the read-only folder that contains the files of your application package. In Windows Phone OS 7.1, you may have heard this folder referred to as the “appdata” folder. You can use the following APIs to access the installation folder.

API

Description

Supported in Windows Phone OS 7.1

Supported in Windows Phone 8 Developer Preview

GetResourceStream(Uri)

Use this method to stream files from the installation folder. For an example, see How to deploy a reference database with an app for Windows Phone.

green check mark green check mark

DataContext

To connect to a reference database that is part of the app package, use the installation folder protocol in the path when you create your local database object. For examples, see Local database connection strings for Windows Phone.

green check mark green check mark

PackageCurrent()()()()

This Package object has an PackageInstalledLocation()()()() property that returns the installation folder as a StorageFolder object.

red x green check mark

StorageFile and StorageFolder

Use these APIs to work with files and folders in the installation folder.

red x green check mark

Installation folder protocols

Use the appdata or ms-appx protocol to address the installation folder in a path. The following code shows some examples of how to use these protocols.

// Reference the installation folder with ms-appx.
Uri myInitialSettingsFileUri = new Uri("ms-appx:///AppSetup/initialSettings1.xml");

// Get a file from the installation folder with the isostore protocol.
var file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("appdata:///AppSetup/initialSettings2.xml "));

The local folder is the root folder of your app’s data store. Known in Windows Phone OS 7.1 as isolated storage, the local folder is isolated from other apps. Use this folder to persist data on the phone.

API

Description

Supported in Windows Phone OS 7.1

Supported in Windows Phone 8 Developer Preview

DataContext

Local database files are stored in the local folder. To connect to a local database, use the local folder protocol in the path when you create your local database object. For more info, see Local database for Windows Phone.

green check mark green check mark

IsolatedStorageSettings

Work with key/value pairs in the local folder. For an example see, How to create a settings page for Windows Phone.

green check mark green check mark

IsolatedStorageFile

Work with files and folders in the local folder. For an example, see How to store files and folders for Windows Phone.

green check mark green check mark

StorageFile and StorageFolder

Use these APIs to work with files and folders in the local folder.

red x green check mark

ApplicationDataLocalFolder()()()()

This property returns the local folder as a StorageFolder object.

red x green check mark

Local folder protocols

Use the isostore or ms-appdata protocol to address the local folder in a path. The following code shows some examples of how to use these protocols.

// Create a local database in the local folder with ms-appdata.
MyDataContext db = new MyDataContext ("ms-appdata:///mydb.sdf")

// Get a file from the local folder with the isostore protocol.
var file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("isostore:///AppConfigSettings.xml "));

Special-use folders in the local folder

In addition to general data storage, the local folder is used for the following special-use scenarios.

Path

Use

Notes

Shared

Used to host the Media, ShellContent, and Transfers folders.

This folder is created when your app is installed, but it can be deleted.

Shared/Media

Album Art: Apps can use this folder to display album art in the Universal Volume Control (UVC) while playing background audio.

This folder is created when your app is installed, but it can be deleted. For more information, see How to integrate with the Music and Videos Hub for Windows Phone.

Shared/ShellContent

Tiles: Tiles can display background images on the front and back of each Tile. Background images can be stored in isolated storage, but must be located in this folder or a subfolder of it.

This folder is created when your app is installed, but it can be deleted. For more information, see Tiles for Windows Phone.

Shared/Transfers

Background file transfer: Apps can save files to isolated storage in the background, even when the app is no longer running in the foreground.

This folder is created when your app is installed, but it can be deleted. For more information, see Background file transfers for Windows Phone.

Exploring the local folder

Use Isolated Storage Explorer (ISETool.exe), to list, copy, and replace files and directories in isolated storage in a Windows Phone app. Isolated Storage Explorer is a command-line tool that is installed with the Windows Phone SDK. Using this tool, you can verify that files are being saved in the correct location with the correct data. You can use Isolated Storage Explorer on the emulator or on a device. For more information, see How to use the isolated storage explorer tool for Windows Phone.

Accessing the local folder from native code

You can use a number of Win32 storage functions to access the local folder using native code. For more info, see Win32 and COM APIs for Windows Phone.

The media library is where the operating system stores photos, music, and videos on the phone. Media in the library is stored on a combination of internal storage and, when available on the phone, external storage (an SD card). However, the media library is a virtual storage container; it does not distinguish where files are stored. You can use the following Microsoft.Xna.Framework.Media..::..MediaLibrary APIs to access files in the media library. For more info about working with media, see Media for Windows Phone.

Important note Important Note:

To access media in your app, you must also specify the applicable capabilities in the application manifest file, WMAppManifest.xml. For more info, see Application manifest file for Windows Phone.

MediaLibrary API

Description

Supported in Windows Phone OS 7.1

Supported in Windows Phone 8 Developer Preview

MediaLibrary..::..Albums , MediaLibrary..::..Artists, and MediaLibrary..::..Songs

Read-only music access.

green check mark green check mark

MediaLibrary..::..Pictures , MediaLibrary..::..RootPictureAlbum, and MediaLibrary..::..SavedPictures

Read-only photos access.

green check mark green check mark

MediaLibrarySavePicture()()()() and MediaLibrarySavePictureToCameraRoll()()()()

Add photos to the Saved Pictures and Camera Roll folders.

green check mark green check mark
Note Note:

You must set a reference to the Microsoft.Xna.Framework namespace to use these APIs in a Windows Phone OS 7.1 app. This reference is already set in new Windows Phone 8 Developer Preview projects.

Direct access to the SD card is read-only and is limited to file types for which your app has registered to handle with a file association. For more information about file associations, see Auto-launching with file and protocol associations for Windows Phone 8. You can use the following APIs to read from an SD card.

Important note Important Note:

To access the SD card from your app, you must also specify the ID_CAP_REMOVABLE_STORAGE capability in the application manifest file, WMAppManifest.xml. For more info, see Application manifest file for Windows Phone.

API

Description

Supported in Windows Phone OS 7.1

Supported in Windows Phone 8 Developer Preview

Microsoft.Phone.Storage..::..ExternalStorageFolder

Represents a folder on the SD card.

red x green check mark

Microsoft.Phone.Storage..::..ExternalStorageFile

Represents a file on the SD card.

red x green check mark

Show: