Share via

Data for Windows Phone 8

  • Article

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

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.

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 8. For info about accessing data that does not reside on the phone, see Communications for Windows Phone 8.

This topic contains the following sections.

Installation folder

The installation folder is the read-only folder that contains the files of your app 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

GetResourceStream

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 8.

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 8.

InstalledLocation

The InstalledLocation property of the current Package class returns the installation folder as a StorageFolder object. Use the Path property to get the full path of the installation folder.

StorageFile and StorageFolder

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

Installation folder URI schemes

Use the appdata or ms-appx URI scheme names to address the installation folder in a path. Although these URI schemes point to the same place, they cannot be used interchangeably. Use “ms-appx:///” when addressing the installation folder with APIs that are in the Windows namespace. For all other APIs, use “appdata:/”. The following code shows some examples of how to use these URI schemes.

// Reference the installation folder with the appdata URI scheme.
Uri myInitialSettingsFileUri = new System.Uri("appdata:/AppSetup/initialSettings1.xml");

// Get a file from the installation folder with the ms-appx URI scheme.
var file = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///AppSetup/initialSettings2.xml"));

Note

ms-appx requires three slashes (“///”) and appdata requires only one slash (“/”).

Local folder

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

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 8.

IsolatedStorageSettings

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

IsolatedStorageFile

Work with files and folders in the local folder. For an example, see Quickstart: Working with files and folders in Windows Phone 7.

StorageFile and StorageFolder

Use these APIs to work with files and folders in the local folder. For an example of StorageFolder, see Quickstart: Working with files and folders in Windows Phone 8.

LocalFolder

The LocalFolder property of the current ApplicationData class returns the local folder as a StorageFolder object. Use the Path property to get the full path of the local folder.

Local folder URI schemes

Use the isostore or ms-appdata URI scheme names when addressing the local folder in a path. Although you can use both of these URI schemes to access the local folder, they cannot be used interchangeably. Use “ms-appdata:///local/” to address the root of the local folder with APIs that are in the Windows namespace. For all other APIs, use “isostore:/” to address the root of the local folder. The following code shows some examples of how to use these URI schemes.

// Create a local database in the local folder with the isostore URI scheme.
MyDataContext db = new MyDataContext("isostore:/mydb.sdf");

// Get a file from the local folder with the ms-appdata URI scheme.
var file = await Windows.StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appdata:///local/AppConfigSettings.xml"));

Note

ms-appdata requires three slashes (“///”) and isostore requires only one slash (“/”).

Regardless of which URI scheme you use in your app, paths for new files and folders cannot exceed 185 characters after the last slash of the URI scheme name. For example, the path for isostore:/mydb.sdf uses 8 characters of the available 185.

Special-use folders in the local folder

In addition to general data storage, the local folder is used for the following special-use scenarios. Keep these folders in mind if your app iterates through the local folder to find directories that it created.

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 info, see How to integrate with the Music and Videos Hub for Windows Phone 8.

Shared/ShellContent

Tiles: Tiles can display background images on the front and back of each Tile. Background images can be stored in the local folder, 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 info, see Tiles for Windows Phone 8.

Shared/Transfers

Background file transfer: Apps can save files to the local folder 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 info, see Background file transfers for Windows Phone 8.

PlatformData

Photo chooser task

This folder is created when your app uses the photo chooser task. For more info, see How to use the photo chooser task for Windows Phone 8.

Exploring the local folder

Use Isolated Storage Explorer (ISETool.exe), to list, copy, and replace files and directories in the local folder. 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 info, see How to use the Isolated Storage Explorer tool for Windows Phone 8.

Media library

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 MediaLibrary APIs to access files in the media library. The media library extension APIs (from the Microsoft.Xna.Framework.Media.PhoneExtensions namespace) provide additional capabilities for media library objects. For more info about working with media, see Media for Windows Phone.

Important Note:

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

MediaLibrary API

Description

Supported in Windows Phone OS 7.1

Supported in Windows Phone 8

Albums, Artists, and Songs

Read-only music access.

Pictures, RootPictureAlbum, and SavedPictures

Read-only photos access.

SavePicture and SavePictureToCameraRoll

Add photos to the Saved Pictures and Camera Roll folders.

SaveSong and Delete

Adds and deletes songs from the media library. Note: don’t use the isostore URI scheme name when saving a song.

GetPath

Gets a file path to a photo from the specified Picture object.

Note

You must set a reference to the Microsoft.Xna.Framework.Media namespace to use these APIs in a Windows Phone OS 7.1 app. This reference is already set in new Windows Phone 8 projects. To use the media library extension APIs, set a reference to Microsoft.Xna.Framework.Media.PhoneExtensions in your Windows Phone 8 app.

External storage (SD card)

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 info about using external storage, see Reading from the SD card for Windows Phone 8.

You can use the following APIs to read from an SD card.

API

Description

Supported in Windows Phone OS 7.1

Supported in Windows Phone 8

ExternalStorageDevice

Represents an SD card. Use the ExternalStorageID property to uniquely identify a card.

GetExternalStorageDevicesAsync

Returns a collection of SD cards that are inserted in the phone. This collection will contain no more than one SD card.

ExternalStorageFolder

Represents a folder on the SD card. Use the Path property to access the folder later.

ExternalStorageFile

Represents a file on the SD card. Use the Path property to access the file later.

GetFileAsync(String) and GetFolderAsync(String)

Obtain a file or folder directly from the external storage device object.

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

Win32 storage APIs supported on Windows Phone 8

Windows Phone 8 supports the following Win32 storage APIs for working with the local folder. For the full list of supported Win32 APIs, see Supported Win32 APIs for Windows Phone 8.