Quickstart: 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]
Provide access to app content, a save location, or file updates through the file picker by integrating your app with the File Open Picker contract, the File Save Picker contract, or the Cached File Updater contract.
Prerequisites
- JavaScript: How to activate an app
- C#/C++/VB: How to activate an app
- Recommended: Windows application contracts
Decide which services your app will provide from file picker windows
Your app can provide the following services to other apps by integrating with the associated app contract. To participate in a contract, you must declare the contract in your app manifest, respond to the corresponding activated event, and create a specialized app view.
Provide access to files
Make files accessible from a file picker if your app has a unique and/or valuable view of those files or if users cannot easily access the files another way.
App contract: File Open Picker contract
Activated event information: fileOpenPickerActivatedEventArgs
Provide a save location
Provide a save location through a file picker if you expect your users to want to save files in order to open and work with them in your app later.
App contract: File Save Picker contract
Activated event information: fileSavePickerActivatedEventArgs
Provide real-time updates for files
Track and update files through a file picker if you expect users to use your app as a central repository of files that your app provides access to, or that are saved using your app as the save location.
App contract: Cached File Updater contract
Activated event information: cachedFileUpdaterActivatedEventArgs
Learn more about the services your app can provide through a file picker in Accessing files with file pickers.
Declare the contract in your app manifest
With your project open in Microsoft Visual Studio, follow these steps to add an app contract to your manifest:
Add an app contract by bringing up the Add a New Item window for your project, selecting the contract from the center pane, and clicking the Add button.
You can bring up the Add a New Item window in Visual Studio in several ways:
- By selecting the Project > Add New Item... menu option
- By selecting the Add > New Item... menu option from the project's context menu
- By using the Crtl+Shift+A keyboard shortcut
Tip When you add these contracts, Visual Studio automatically updates your "package.appmanifest" manifest file and adds files to your project that you will use to define the layout and behavior of the view that will be hosted in the file picker window when your app's service is called.
Customize your contract settings in Visual Studio if the default settings are not appropriate for your app.
Open "package.appmanifest".
Open the Declarations tab.
Select your contract name from the Supported Declarations list.
Add support for specific files types.
In the Supported File Types box, uncheck the SupportsAnyFileType check box.
Add a new FileType field for each file type you want to support with these steps:
- Click the Add New button.
- Enter the extension of a file type that you want to support into the FileType field like this:
*.ext
Tip Add only those file types that are directly relevant to your app, your users, and the contract. Limiting file types in this way can help keep your file picker view uncluttered and easy to use.
You can also remove support for a file type by following the previous steps and clicking the Remove button of the type you want to remove. The Remove button is directly above the FileType field.
Your manifest file is updated with markup for the contract that you added. An element that represents the contract you added is inserted into the manifest XML markup as a child of the Extensions element. For example, markup for a File Open Picker contract that supports all file types looks like this:
<Extension Category="windows.filePicker" StartPage="filePicker.html">
<FileOpenPicker>
<SupportedFileTypes SupportsAnyFileType="true" />
</FileOpenPicker>
</Extension>
Respond when your app is activated from a file picker
Add code to your activated event handler that tests the object passed into your handler is associated with the contract that you declared in your manifest and then displays your app's file picker view.
Each contract is associated with an object that provides information about an activated event that is fired when one of the services your app provides is called from a file picker.
File Open Picker contract - fileOpenPickerActivatedEventArgs
File Save Picker contract - fileSavePickerActivatedEventArgs
Cached File Updater contract - cachedFileUpdaterActivatedEventArgs
Create a specialized view of your app that will be hosted in the file picker
The guidance in Guidelines and checklist for file pickers should help you design the app view that will be hosted in the file picker.
Ultimately, your view should consist of:
Code that customizes the file picker letterbox appropriately
Markup and styles that define the layout of the framed area of the file picker (where files are displayed)
Code that binds your data source to markup so that files are displayed in the framed area
Test the services provided by your app from a file picker that is called by another app
To test the services that your app provides from a file picker, you must trigger the activated event that corresponds to the service your app provides. You cannot trigger this event by running your app directly.
Instead, use these steps to trigger the corresponding activated event for each contract.
To test your app's participation in the File Open Picker contract:
Launch an app other than your own.
Use this other app's UI to call a file picker window to access files.
Select your app from the list of locations in the file picker to see your app hosted in the file picker.
To test your app's participation in the File Save Picker contract:
Launch an app other than your own.
Use this other app's UI to call a file picker window to save a file.
Select your app from the list of locations in the file picker to see your app hosted in the file picker.
To test your app's participation in the Cached File Updater contract:
Launch an app other than your own.
Use this other app's UI to call a file picker window to access or save a file that you have marked to be updated.
Summary
Your app can provide services to other apps by participating in an app contract. To participate in a contract, you must declare the contract in your app manifest, respond to the corresponding activated event, and create a specialized app view.
Related topics
Integrating with file pickers contracts
Guidelines and checklist for file picker contracts
Reference
Windows.Storage.Pickers.Provider namespace
Windows.ApplicationModel.Activation.fileOpenPickerActivatedEventArgs class
Windows.ApplicationModel.Activation.fileSavePickerActivatedEventArgs class
Windows.ApplicationModel.Activation.cachedFileUpdaterActivatedEventArgs class
Using file pickers
Quickstart: Accessing files with file pickers