Quickstart: Accessing files with file pickers (XAML)

Article
10/13/2015

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

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: Calling asynchronous APIs in C# or Visual Basic.

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

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.

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.

Complete code to pick one file

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

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.

Walkthrough for picking one file

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

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 **ThumbnailPickerViewMode 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**](https://msdn.microsoft.com/library/br207850) 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**](https://msdn.microsoft.com/library/br207850) with new entries, you can use the [**ReplaceAll**](br207844\(v=win.10\).md) method instead of [**Add**](https://msdn.microsoft.com/library/br207834).

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.

Walkthrough for picking one folder

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

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

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