Data for Windows Phone 8

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

This topic contains the following sections.

• Installation folder
• Local folder
• Media library
• External storage (SD card)
• Win32 storage APIs supported on Windows Phone 8

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"));

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"));

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.

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.

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.

• CopyFile2

• CreateDirectoryW

• CreateFile2

• DeleteFileW

• FindClose

• FindFirstFileExW

• FindNextFileW

• FlushFileBuffers

• GetDiskFreeSpaceExW

• GetFileAttributesExW

• GetFileInformationByHandleEx

• GetOverlappedResultEx

• LockFileEx

• MoveFileExW

• ReadFile

• RemoveDirectoryW

• SetEndOfFile

• SetFileAttributesW

• SetFileInformationByHandle

• SetFilePointerEx

• UnlockFileEx

• WriteFile