Integrating with file picker contracts (Windows Runtime apps)

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

Apps can use the file picker to provide other apps with files, a save location, and even file updates by integrating with the File Open Picker contract, the File Save Picker contract, and the Cached File Updater contract (respectively).

How file pickers work

Through the file picker, your app can gain access to files and folders all over the user's system. When you call the file picker, the user can browse their system and other apps to select files (or folders). After the user picks files or folders, your app receives those picks as StorageFile and StorageFolder objects. Your app can then operate on picked files and folders by using those objects. To learn more about accessing files, see File access and permissions.

You can also use the file picker to let the user pick files and folders from your app through the file picker. Files picked from your apps through the file picker are treated like files from the file system: they are returned as StorageFile objects. This lets the user picks files from your app to operate on in another app. For example if your app is a photo gallery, you may want to provide the pictures in your gallery so that the user can use your app to select pictures to modify in a photo editor.

If you want your app to provide access to files, a save location, and/or file updates to other apps your app must participate in the associated app contract(s) like the File Save Picker contract, File Open Picker contract, and the Cached File Updater contract. You can participate in these contracts by declaring them in your app manifest and adding UI or code to your app to integrate with the contract(s).

Here is a diagram that shows how the file picker works to connect app like a photo editor (the calling app) with files provided by a gallery app (the providing app) so that the user can select files from the gallery app.

Participating in file pickers app contracts

Learn how: Quickstart: Providing access to files with file pickers

Reference: Windows.Storage.Pickers.Provider namespace

Sample: File picker contracts sample

Providing access to files

Consider using the file picker to provide files to other apps if your app has a unique and/or valuable display of those files or if users cannot easily access the files another way. You can let users browse and pick files that are provided by your app through a file picker window by participating in the File Open Picker contract. If your app participates in this contract, users will be able to select your app from the list of locations in the upper left of the file picker letterbox. When the user selects your app, the file picker will load any modifications you make to the letterbox and a page that you design to display files for the user to browse and pick.

This screen shot has been modified to emphasize and label the center area of a file picker window to show where your app's file display page will be loaded.

 

A music app might let users browse and pick files by artist or album title, regardless of how the files are organized on the user's system. Or a photo gallery app might let users browse and pick files that are not on the user's system but are hosted by a web service like Facebook or Flickr.

If you don't want to let users browse and pick files with your app through a file picker window, you also have the option of letting users share files from your app by integrating with the Share Source contract. To learn more about integrating with the Share Source contract, see How to share files.

Providing a save location

Consider using the file picker to provide your app as a location where the user can save files if your app connects the user to a service that hosts their files or if you expect the user to want to save a number of files in order to open and work with them in your app later. You can let users save files to your app by participating in the File Save Picker contract. If your app participates in this contract, users will be able to select your app from the list of locations in the upper left of the file picker letterbox when they use a file picker to save a file. When the user selects your app, the file picker a page that you will design to display your app's save location to the user (include existing files and/or subfolders if they exist).

This screen shot has been modified to emphasize and label the center area of a file picker window to show where the page that displays your app's save location will be loaded (an app page for Microsoft OneDrive is shown in the screen shot).

 

An app that connects the user with files that are hosted by Facebook or OneDrive might let users use the app as a save location so that users can easily upload files to be hosted. Or an app that lets the user edit audio files might let users use the app as a save location so that users can create a queue of audio files that they want to edit the next time they open the editor.

Letting other apps use your app as a save location for files makes sense when the user is working with files and folders. Its less intuitive when it comes to smaller sets of data, such as a URL or a text selection. In those cases, the Share charm or the copy and paste commands are better options. That said, there are plenty of situations in which it makes sense to support both the Share charm and saving. For example, consider a user who wants to store a file using a cloud-storage service, such as OneDrive. In this situation, both the Share charm and saving are equally valid options. In the end, you need to consider how your user interacts with your app, and support the contracts and features that match user expectations and provide the best overall experience. To learn more about integrating with the Share Target contract, see Quickstart: Receiving shared content. To learn more about using copy and paste commands, see Quickstart: Clipboard basics.

Tip  If your app acts as a save location, you should also provide access to your app's files by participating in the File Open Picker contract.

 

Providing real-time updates for files

Consider providing file updates if your app is used to connect to and/or manage a central repository of the user's files. Participating in the Cached File Updater contract lets your app both perform updates on files in your app's repository and provide updates to local versions of the files in your repository. If your app participates in this contract and encounters an update that requires user intervention, the file picker will load a page that you will design to gather the needed information from the user.

A remote storage app like OneDrive or DropBox might provide updates to local versions of a file to ensure that the user sees the latest version of the file in its repository, or might perform updates on a file in the repository if the user saves a newer version.

Tip  If your app provides file updates, it should also provide a save location, and access to files by participating in the File Save Picker contract and the File Open Picker contract, respectively.

 

Related topics

Accessing data and files

Samples

File picker sample

File picker contracts sample

Reference

Windows.Storage.AccessCache namespace

Windows.Storage.Pickers namespace

Windows.Storage.Pickers.fileOpenPicker class

Windows.Storage.Pickers.fileSavePicker class

Windows.Storage.Pickers.Provider namespace

Sharing

How to share files

Quickstart: Receiving shared content

Using file pickers

Quickstart: Accessing files with file pickers

How to save files through file pickers

Guidelines and checklist for file pickers