Share via


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

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:

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

     

  2. Customize your contract settings in Visual Studio if the default settings are not appropriate for your app.

    1. Open "package.appmanifest".

    2. Open the Declarations tab.

    3. Select your contract name from the Supported Declarations list.

    4. 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:

      1. Click the Add New button.
      2. 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:

  1. Launch an app other than your own.

  2. Use this other app's UI to call a file picker window to access files.

  3. 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:

  1. Launch an app other than your own.

  2. Use this other app's UI to call a file picker window to save a file.

  3. 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:

  1. Launch an app other than your own.

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

Accessing data and files

Integrating with file pickers contracts

File picker contracts sample

Guidelines and checklist for file picker contracts

How to activate an app

Windows application 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

How to save files through file pickers

Guidelines and checklist for file pickers