Language: JavaScript and HTML | VB/C#/C++ and XAML

Quickstart: Accessing files with file pickers (Windows Runtime apps using C#/VB/C++ and XAML)

Applies to Windows and Windows Phone

Access files and folders through the file picker by letting users pick files and folders. You can use the FileOpenPicker class to gain access to files and the FolderPicker to gain access to folders.

Prerequisites

Understand async programming for Windows Runtime apps using C++, C#, or Visual Basic

You can learn how to write asynchronous apps in Quickstart: Using the await operator for asynchronous programming.

File picker UI

File pickers have areas at the top and bottom of the screen that display information, to orient users and provide a consistent experience when users access or save files.

The displayed information includes:

  • The current location, which is in the upper left
  • A basket of items that the user chose, which is along the bottom
  • A drop-down list of locations that the user can browse, which can be selected from the down-caret in the upper left

For example, this screen shot shows a file picker that was called by an email app to let the user choose some photos (though the user hasn't picked any photos in the screen shot).

A screen capture of the file picker with two files selected to be opened.

The user can view the drop-down list of available locations, like the list shown in the screen shot on the right, by selecting the down-caret in the upper left of the file picker. These locations include file system locations, like the Music or Downloads folder. They also include other apps, if these other apps (like Microsoft OneDrive) participate file picker contracts , which you can see at the bottom of the list in the screen shot.

A cropped screen capture of the file picker that shows the dropdown list of locations in the upper left.

 

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 select files (or folders) to access and save. 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.

The file picker uses a single, unified interface to let the user pick files and folders from the files system or from other apps. Files picked from other apps are like files from the file system: they are returned as StorageFile objects. In general, your app can operate on them in the same ways as other such objects. Other apps make files available by participating in file picker contracts. If you think you might want your app to provide files through the file picker, you can learn more in Integrating with file picker contracts.

For example, you might call the file picker in your app so that your user can open a file. This makes your app the calling app. The file picker interacts with the system and other apps to let the user navigate and pick the file. When your user chooses a file, the file picker returns that file to your app. The diagram illustrates this process for the case where the user chooses a file from another app like OneDrive. In this case OneDrive is the providing app.

A daigram that shows the process of one app getting a file to open from another app using the file picker as an interface bewteen the two apps.

Complete code to pick one file

The File picker sample demonstrates how to use FileOpenPicker to let the user pick a single file.


if (rootPage.EnsureUnsnapped())
{
    FileOpenPicker openPicker = new FileOpenPicker();
    openPicker.ViewMode = PickerViewMode.Thumbnail;
    openPicker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;
    openPicker.FileTypeFilter.Add(".jpg");
    openPicker.FileTypeFilter.Add(".jpeg");
    openPicker.FileTypeFilter.Add(".png");

    StorageFile file = await openPicker.PickSingleFileAsync();
    if (file != null)
    {
        // Application now has read/write access to the picked file
        OutputTextBlock.Text = "Picked photo: " + file.Name;
    }
    else
    {
        OutputTextBlock.Text = "Operation cancelled.";
    }
}


For the complete code to pick multiple files, see the File picker sample.

The File picker sample also demonstrates how to write an EnsureUnsnapped method.


internal bool EnsureUnsnapped()
{
    // FilePicker APIs will not work if the application is in a snapped state.
    // If an app wants to show a FilePicker while snapped, it must attempt to unsnap first
    bool unsnapped = ((ApplicationView.Value != ApplicationViewState.Snapped) || ApplicationView.TryUnsnap());
    if (!unsnapped)
    {
        NotifyUser("Cannot unsnap the sample.", NotifyType.StatusMessage);
    }

    return unsnapped;
}


We use the EnsureUnsnapped method every time we try to call a file picker to make sure that the sample app will be able to show the file picker successfully. You can see EnsureUnsnapped used in a number of examples on this page and you can see it in context in the Constants.cs file of the File picker sample.

Warning  If you try to show the file picker while your app is snapped the file picker will not be shown and an exception will be thrown. You can avoid this by making sure your app is not snapped or by unsnapping it before you call the file picker. The following code examples and the File picker sample show you how.

Walkthrough for picking one file

Calling the file picker requires three basic tasks: ensuring that the file picker can be called, creating and customizing a file picker object, and showing the file picker so the user can pick an item or items.

  1. Make sure you can call the file picker

    Every time you want to call a file picker you must first make sure that your app can show the file picker. Do this by verifying that your app in not snapped or, if your app is snapped, that it can be unsnapped in order to show the file picker.

    The File picker sample demonstrates how to create a method that will check the app's ApplicationView.Value and try to unsnap before the sample tries to create and show a file picker.

    
    internal bool EnsureUnsnapped()
    {
        // FilePicker APIs will not work if the application is in a snapped state.
        // If an app wants to show a FilePicker while snapped, it must attempt to unsnap first
        bool unsnapped = ((ApplicationView.Value != ApplicationViewState.Snapped) || ApplicationView.TryUnsnap());
        if (!unsnapped)
        {
            NotifyUser("Cannot unsnap the sample.", NotifyType.StatusMessage);
        }
    
        return unsnapped;
    }
    
    
    

    You should use this method to make sure you can call a file picker like this:

    
    if (MainPage.Current.EnsureUnsnapped())
    {
        // Code to call file picker
    }
    
    

    We use the EnsureUnsnapped method every time we try to call a file picker to make sure that the sample app will be able to show the file picker successfully. You can see EnsureUnsnapped used in a number of examples on this page and you can see it in context in the Constants.cs file of the File picker sample.

    Warning  If you try to show the file picker while your app is snapped the call will fail and you will encounter an exception.

  2. Create and customize a FileOpenPicker

    Use FileOpenPicker if the user is picking files. You can customize this class by setting properties on the object you create.

    The File picker sample demonstrates how to create and customize a FileOpenPicker.

    
    FileOpenPicker openPicker = new FileOpenPicker();
    openPicker.ViewMode = PickerViewMode.Thumbnail;
    openPicker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;
    openPicker.FileTypeFilter.Add(".jpg");
    openPicker.FileTypeFilter.Add(".jpeg");
    openPicker.FileTypeFilter.Add(".png");
    
    
    

    You should set the properties on the file picker object that are relevant to your users and your app. For guidelines to help you decide how to customize the file picker, see Guidelines and checklist for file pickers. For explanations of why we set certain properties to customize the file pickers in the File picker sample, continue reading.

    File picker sample FileOpenPicker customizations, explained

    The File picker sample creates a rich, visual display of pictures in a convenient location that the user can pick from by setting three FileOpenPicker properties: ViewMode, SuggestedStartLocation, and FileTypeFilter properties.

    • Setting openPicker.ViewMode to the Thumbnail PickerViewMode enum value creates a rich, visual display by using picture thumbnails to represent files in file picker.

      
      openPicker.ViewMode = PickerViewMode.Thumbnail;
      
      

      You should consider setting ViewMode to PickerViewMode.Thumbnail if you are using the file picker to display visual files like pictures or videos. Otherwise, use PickerViewMode.List.

      In some cases, the user may want to pick a picture or video or any other kind of file. For example, the user may be picking a file to attach to an email or to send via IM. In this case, you should support both view modes by adding two UI controls to your app. One control should call the file picker by using the Thumbnail view mode, so that the user can pick pictures and videos. The other control should call the file picker by using the List view mode, so that the user can pick other kinds of files. For example, a mail app would have two buttons: Attach Picture or Video and Attach Document.

    • Setting openPicker.SuggestedStartLocation to Pictures using PickerLocationId.PicturesLibrary lets the user start in a location where they are likely to find pictures.

      
      openPicker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;
      
      

      You should set SuggestedStartLocation to file system location that is appropriate for the type of file that is being picked. If the user is picking music, pictures, or videos, set the start location to Music, Pictures, or Videos respectively. For all other types of files, set the start location to Documents. This is just a starting location. Users can navigate to other locations while they are using the file picker.

      Additionally, the SuggestedStartLocation is not always used as the start location for the file picker. To give the user a sense of consistency, the file picker remembers the last location that the user viewed and will generally start at that location.

    • Using openPicker.FileTypeFilter.Add to specify the types of files that the user can see in the file picker lets us keep the user focused on picking files that are relevant and usable.

      
      openPicker.FileTypeFilter.Add(".jpg");
      openPicker.FileTypeFilter.Add(".jpeg");
      openPicker.FileTypeFilter.Add(".png");
      
      

      For C#:  Add is the name of the Append method for C# developers.

      You should consider specifying the types of files to display in the file picker to help keep the files that are displayed relevant. For example, if your app is a video player, you can use the FileTypeFilter property to ensure that the files displayed in the file picker are in video formats that your player supports, based on the video file name extension.

      If you want to replace previous file types in the FileTypeFilter with new entries, you can use the ReplaceAll method instead of Add.

  3. Show the FileOpenPicker

    You can now show the file picker so that the user can pick either a single file or multiple files:

    • Show so the user can pick a single file

      After you create and customize a file picker, let the user pick one file by calling await on FileOpenPicker.PickSingleFileAsync.

      When the user picks a file, FileOpenPicker.PickSingleFileAsync returns a StorageFile object that represents the picked file.

      The File picker sample demonstrates how to display the file picker to let the user pick one file.

      
      StorageFile file = await openPicker.PickSingleFileAsync();
      if (file != null)
      {
          // Application now has read/write access to the picked file
          OutputTextBlock.Text = "Picked photo: " + file.Name;
      }
      else
      {
          OutputTextBlock.Text = "Operation cancelled.";
      }
      
      
      
    • Show so the user can pick a multiple files

      After you create and customize a file picker, let the user pick multiple files by calling await on FileOpenPicker.PickMultipleFilesAsync.

      When the user picks multiple files, FileOpenPicker.PickMultipleFilesAsync returns a list of picked files. The files in the list are represented by StorageFile objects.

      The File picker sample demonstrates how to display the file picker to let the user pick multiple files, and how to capture the list of picked files for processing.

      
      IReadOnlyList<StorageFile> files = await openPicker.PickMultipleFilesAsync();
      if (files.Count > 0)
      {
          StringBuilder output = new StringBuilder("Picked files:\n");
          // Application now has read/write access to the picked file(s)
          foreach (StorageFile file in files)
          {
              output.Append(file.Name + "\n");
          }
          OutputTextBlock.Text = output.ToString();
      }
      else
      {
          OutputTextBlock.Text = "Operation cancelled.";
      }
      
      
      

Complete code to pick one folder

The File picker sample demonstrates how to use FolderPicker to let the user pick a single file.


if (rootPage.EnsureUnsnapped())
{
    FolderPicker folderPicker = new FolderPicker();
    folderPicker.SuggestedStartLocation = PickerLocationId.Desktop;
    folderPicker.FileTypeFilter.Add(".docx");
    folderPicker.FileTypeFilter.Add(".xlsx");
    folderPicker.FileTypeFilter.Add(".pptx");

    StorageFolder folder = await folderPicker.PickSingleFolderAsync();
    if (folder != null)
    {
        // Application now has read/write access to all contents in the picked folder (including other sub-folder contents)
        StorageApplicationPermissions.FutureAccessList.AddOrReplace("PickedFolderToken", folder);
        OutputTextBlock.Text = "Picked folder: " + folder.Name;
    }
    else
    {
        OutputTextBlock.Text = "Operation cancelled.";
    }
}


For the complete code to pick multiple files, see the File picker sample.

The File picker sample also demonstrates how to write an EnsureUnsnapped method.


internal bool EnsureUnsnapped()
{
    // FilePicker APIs will not work if the application is in a snapped state.
    // If an app wants to show a FilePicker while snapped, it must attempt to unsnap first
    bool unsnapped = ((ApplicationView.Value != ApplicationViewState.Snapped) || ApplicationView.TryUnsnap());
    if (!unsnapped)
    {
        NotifyUser("Cannot unsnap the sample.", NotifyType.StatusMessage);
    }

    return unsnapped;
}


We use the EnsureUnsnapped method every time we try to call a file picker to make sure that the sample app will be able to show the file picker successfully. You can see EnsureUnsnapped used in a number of examples on this page and you can see it in context in the Constants.cs file of the File picker sample.

Warning  If you try to show the file picker while your app is snapped the file picker will not be shown and an exception will be thrown. You can avoid this by making sure your app is not snapped or by unsnapping it before you call the file picker. The following code examples and the File picker sample show you how.

Walkthrough for picking one folder

Calling the file picker requires three basic tasks: ensure that the file picker can be called, create and customize a file picker object, and show the file picker so the user can pick an item or items.

  1. Make sure you can call the file picker

    Every time you want to call a file picker you must first make sure that your app can show the file picker. Do this by verifying that your app in not snapped or, if your app is snapped, that it can be unsnapped in order to show the file picker.

    The File picker sample demonstrates how to create a method that will check the app's ApplicationView.Value and try to unsnap before the sample tries to create and show a file picker.

    
    internal bool EnsureUnsnapped()
    {
        // FilePicker APIs will not work if the application is in a snapped state.
        // If an app wants to show a FilePicker while snapped, it must attempt to unsnap first
        bool unsnapped = ((ApplicationView.Value != ApplicationViewState.Snapped) || ApplicationView.TryUnsnap());
        if (!unsnapped)
        {
            NotifyUser("Cannot unsnap the sample.", NotifyType.StatusMessage);
        }
    
        return unsnapped;
    }
    
    
    

    You should use this method to make sure you can call a file picker like this:

    
    if (MainPage.Current.EnsureUnsnapped())
    {
        // Code to call file picker
    }
    
    

    We use the EnsureUnsnapped method every time we try to call a file picker to make sure that the sample app will be able to show the file picker successfully. You can see EnsureUnsnapped used in a number of examples on this page and you can see it in context in the Constants.cs file of the File picker sample.

    Warning  If you try to show the file picker while your app is snapped the call will fail and you will encounter an exception.

  2. Create and customize a FolderPicker

    Use FolderPicker if the user is picking a folder. You can customize this class by setting properties on the object you create.

    The File picker sample demonstrates how to create and customize a FolderPicker.

    
    FolderPicker folderPicker = new FolderPicker();
    folderPicker.SuggestedStartLocation = PickerLocationId.Desktop;
    folderPicker.FileTypeFilter.Add(".docx");
    folderPicker.FileTypeFilter.Add(".xlsx");
    folderPicker.FileTypeFilter.Add(".pptx");
    
    
    

    You should set the properties on the file picker object that are relevant to your users and your app. For guidelines to help you decide how to customize the file picker, see Guidelines and checklist for file pickers. For explanations of why we set certain properties to customize the file pickers in the File picker sample, continue reading.

    File picker sample FolderPicker customizations, explained

    The File picker sample customizes the file picker to pick folders by using three FolderPicker properties: ViewMode, SuggestedStartLocation, and FileTypeFilter properties.

    • Using the default PickerViewMode.List for the folderPicker.ViewMode lets us create a list-like display in the file picker. This list is good for selecting files that are not very visual, like documents.

      You should consider setting ViewMode to PickerViewMode.Thumbnail if you are using the file picker to display visual files like pictures or videos. Otherwise, use PickerViewMode.List.

      If you are displaying visual files like pictures or videos, you should set the folderPicker.ViewMode to Thumbnail like this:

      
      folderPicker.ViewMode = PickerViewMode.Thumbnail;
      
      
    • Setting folderPicker.SuggestedStartLocation to the user's desktop using PickerLocationId.Desktop lets the user start in a familiar, highly used location.

      
      folderPicker.SuggestedStartLocation = PickerLocationId.Desktop;
      
      

      You should set SuggestedStartLocation to file system location that is appropriate for type of folder that the user wants to pick. For example, if the user is picking a folder that contains music files, you should start them in Music. This is just a starting location; users can navigate to other locations while they are using the file picker.

      Additionally, the SuggestedStartLocation is not always used as the start location for the file picker. To give the user a sense of consistency, the file picker remembers the last location that the user viewed and will generally start at that location.

    • Using folderPicker.FileTypeFilter.Add to specify the types of files that the user can see in the file picker lets us keep the user focused on picking a relevant folder.

      
      folderPicker.FileTypeFilter.Add(".docx");
      folderPicker.FileTypeFilter.Add(".xlsx");
      folderPicker.FileTypeFilter.Add(".pptx");
      
      

      Note  Add is the Append method as it is projected for C# developers.

      Users can only select folders through a FolderPicker, they will not be able to select individual files. However, showing relevant files in the FolderPicker helps users determine which folder they want to select. For example, when using the FolderPicker to select a location to import pictures from, showing image files helps the user identify what items will be imported when the location is selected.

  3. Show the FolderPicker so the user can pick a single folder

    After you create and customize a FolderPicker, let the user pick one file by calling await on FolderPicker.PickSingleFolderAsync.

    When the user picks a folder, FolderPicker.PickSingleFolderAsync returns a StorageFolder that represents the picked folder.

    The File picker sample demonstrates how to display the file picker to let the user pick a folder, and how to capture the picked folder for processing.

    
    StorageFolder folder = await folderPicker.PickSingleFolderAsync();
    if (folder != null)
    {
        // Application now has read/write access to all contents in the picked folder (including other sub-folder contents)
        StorageApplicationPermissions.FutureAccessList.AddOrReplace("PickedFolderToken", folder);
        OutputTextBlock.Text = "Picked folder: " + folder.Name;
    }
    else
    {
        OutputTextBlock.Text = "Operation cancelled.";
    }
    
    
    

Summary and next steps

If you use code similar to what is shown here, your app will display a file picker that lets users pick one or more files or folders that your app can then open.

Tip  Whenever your app accesses a file or folder through the file picker, add that item to your app's FutureAccessList or MostRecentlyUsedList to keep track of it. You can learn more about using these lists in How to How to track recently used files and folders.

To learn about reading and writing files, see Quickstart: Reading and writing a file and the File access sample. To learn about working with image files, see Quickstart: Image and ImageBrush, Quickstart: Imaging, and the XAML image sample.

If you want to learn about calling the file picker to save files, see How to save files through file pickers.

If you want your app to provide files, a save location, or file updates to other apps, see Quickstart: Integrating with file picker contracts.

Related topics

File picker sample
File access sample
XAML image sample
Guidelines and checklist for file pickers
How to save files through file pickers
How to track recently used files and folders
Quickstart: Reading and writing a file
Quickstart: Image and ImageBrush
Quickstart: Imaging
File access and permissions
Quickstart: Integrating with file picker contracts
Namespace reference
Windows.Storage.Pickers namespace
Windows.Storage.Pickers.FileOpenPicker class
Windows.Storage.Pickers.FolderPicker class
Windows.Storage.Pickers.PickerLocationId enum
Windows.Storage.Pickers.PickerViewMode enum

 

 

Show:
© 2014 Microsoft. All rights reserved.