FileOpenPicker FileOpenPicker FileOpenPicker FileOpenPicker Class

Represents a UI element that lets the user choose and open files.

Syntax

Declaration

public sealed class FileOpenPickerpublic sealed class FileOpenPickerPublic NotInheritable Class FileOpenPickerpublic sealed class FileOpenPicker

Remarks

To get started accessing files and folders file picker, see Quickstart: Accessing files with .

To learn about using file pickers in Windows Phone Store app, see How to continue your Windows Phone app after calling a file picker.

Important

In Windows 8 if you attempt to display 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. Note that Windows 8.1 does not define a specific snapped window size. Instead, users can resize apps to any width, down to the minimum. Therefore, if your app will deploy only on Windows 8.1, you can ignore the EnsureUnsnapped function and calls to it in this topic's example code.

Examples

The File picker sample demonstrates how to check whether the app is snapped, how to set file picker properties, and how to show a file picker so that the user can pick one 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.";
}
// Create the picker object and set options
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
// Users expect to have a filtered view of their folders depending on the scenario.
// For example, when choosing a documents folder, restrict the filetypes to documents for your application.
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);

// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().then(function (file) {
    if (file) {
        // Application now has read/write access to the picked file
        WinJS.log && WinJS.log("Picked photo: " + file.name, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});
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;
}
Note

You should always make sure that your app is not snapped (or that it can be unsnapped) and set file picker properties regardless of whether the user is picking a single file or multiple files.

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.";
}
openPicker.pickMultipleFilesAsync().then(function (files) {
    if (files.size > 0) {
        // Application now has read/write access to the picked file(s)
        var outputString = "Picked files:\n";
        for (var i = 0; i < files.size; i++) {
            outputString = outputString + files[i].name + "\n";
        }
        WinJS.log && WinJS.log(outputString, "sample", "status");
    } else {
        // The picker was dismissed with no selected file
        WinJS.log && WinJS.log("Operation cancelled.", "sample", "status");
    }
});

Constructors summary

Creates a new instance of a FileOpenPicker.

Properties summary

Gets or sets the label text of the file open picker's commit button.

Gets a set of values to be populated by the app before PickSingleFileAndContinue() or PickMultipleFilesAndContinue() operation that deactivates the app in order to provide context when the app is activated. (Windows Phone Store app)

Gets the collection of file types that the file open picker displays.

Gets or sets the settings identifier associated with the state of the file open picker.

Gets or sets the initial location where the file open picker looks for files to present to the user.

Gets or sets the view mode that the file open picker uses to display items.

Methods summary

Shows the file picker so that the user can pick multiple files, deactivating and the app and reactivating it when the operation is complete. (Windows Phone Store app)

Shows the file picker so that the user can pick multiple files. (Windows Store app)

Shows the file picker so that the user can pick one file, potentially deactivating the app and reactivating it when the operation is complete. (Windows Phone Store app)

Shows the file picker so that the user can pick one file.

Shows the file picker so that the user can pick one file.

Resumes the picking operation to retrieve the user-selected file if the user navigates away from the app after the picker operation has completed and the app is suspended.

Constructors

  • FileOpenPicker()
    FileOpenPicker()
    FileOpenPicker()
    FileOpenPicker()

    Creates a new instance of a FileOpenPicker.

    public FileOpenPicker()public New()Public Sub New()public FileOpenPicker()

Properties

  • CommitButtonText
    CommitButtonText
    CommitButtonText
    CommitButtonText

    Gets or sets the label text of the file open picker's commit button.

    public string CommitButtonText { get; set; }public string CommitButtonText { get; set; }Public ReadWrite Property CommitButtonText As stringpublic string CommitButtonText { get; set; }

    Property Value

    • string
      string
      string
      string

      The label text.

    Remarks

    By default, the label text of the commit button is Open.

  • ContinuationData
    ContinuationData
    ContinuationData
    ContinuationData

    Gets a set of values to be populated by the app before PickSingleFileAndContinue() or PickMultipleFilesAndContinue() operation that deactivates the app in order to provide context when the app is activated. (Windows Phone Store app)

    public ValueSet ContinuationData { get; }public ValueSet ContinuationData { get; }Public ReadOnly Property ContinuationData As ValueSetpublic ValueSet ContinuationData { get; }

    Property Value

    Remarks

    Windows Phone Store app only. For more info, see How to continue your Windows Phone app after calling a file picker.

  • FileTypeFilter
    FileTypeFilter
    FileTypeFilter
    FileTypeFilter

    Gets the collection of file types that the file open picker displays.

    public IVector<string> FileTypeFilter { get; }public IVector<string> FileTypeFilter { get; }Public ReadOnly Property FileTypeFilter As IVector<string>public IVector<string> FileTypeFilter { get; }

    Property Value

    • A FileExtensionVector object that contains a collection of file types (file name extensions) , such as ".doc" and ".png". File name extensions are stored in this array as string objects.

    Remarks

    Examples

    The File picker sample demonstrates how to specify the file types that the user can see and pick from in the file picker.

    FileOpenPicker openPicker = new FileOpenPicker();
    openPicker.ViewMode = PickerViewMode.Thumbnail;
    openPicker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;
    openPicker.FileTypeFilter.Add(".jpg");
    openPicker.FileTypeFilter.Add(".jpeg");
    openPicker.FileTypeFilter.Add(".png");
    
    // Create the picker object and set options
    var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
    openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
    openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
    // Users expect to have a filtered view of their folders depending on the scenario.
    // For example, when choosing a documents folder, restrict the filetypes to documents for your application.
    openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);
    
    FileOpenPicker openPicker = new FileOpenPicker();
    openPicker.ViewMode = PickerViewMode.List;
    openPicker.SuggestedStartLocation = PickerLocationId.DocumentsLibrary;
    openPicker.FileTypeFilter.Add("*");
    
    var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
    openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.list;
    openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.documentsLibrary;
    openPicker.fileTypeFilter.replaceAll(["*"]);
    
  • SettingsIdentifier
    SettingsIdentifier
    SettingsIdentifier
    SettingsIdentifier

    Gets or sets the settings identifier associated with the state of the file open picker.

    public string SettingsIdentifier { get; set; }public string SettingsIdentifier { get; set; }Public ReadWrite Property SettingsIdentifier As stringpublic string SettingsIdentifier { get; set; }

    Property Value

    • string
      string
      string
      string

      The settings identifier.

    Remarks

    If your application uses multiple instances of the file open picker, you can use this property to identify the individual instances.

  • SuggestedStartLocation
    SuggestedStartLocation
    SuggestedStartLocation
    SuggestedStartLocation

    Gets or sets the initial location where the file open picker looks for files to present to the user.

    public PickerLocationId SuggestedStartLocation { get; set; }public PickerLocationId SuggestedStartLocation { get; set; }Public ReadWrite Property SuggestedStartLocation As PickerLocationIdpublic PickerLocationId SuggestedStartLocation { get; set; }

    Property Value

    Remarks

    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 navigated to and will generally start at that location.

  • ViewMode
    ViewMode
    ViewMode
    ViewMode

    Gets or sets the view mode that the file open picker uses to display items.

    public PickerViewMode ViewMode { get; set; }public PickerViewMode ViewMode { get; set; }Public ReadWrite Property ViewMode As PickerViewModepublic PickerViewMode ViewMode { get; set; }

    Property Value

Methods

  • PickMultipleFilesAndContinue()
    PickMultipleFilesAndContinue()
    PickMultipleFilesAndContinue()
    PickMultipleFilesAndContinue()

    Shows the file picker so that the user can pick multiple files, deactivating and the app and reactivating it when the operation is complete. (Windows Phone Store app)

    public void PickMultipleFilesAndContinue()public void PickMultipleFilesAndContinue()Public Function PickMultipleFilesAndContinue() As voidpublic void PickMultipleFilesAndContinue()

    Remarks

    Windows Phone Store app only. Use the ContinuationData property to store context information that can be retrieved when the app is reactivated. For more info, see How to continue your Windows Phone app after calling a file picker.

  • PickMultipleFilesAsync()
    PickMultipleFilesAsync()
    PickMultipleFilesAsync()
    PickMultipleFilesAsync()

    Shows the file picker so that the user can pick multiple files. (Windows Store app)

    public IAsyncOperation<IVectorView<StorageFile>> PickMultipleFilesAsync()public IAsyncOperation<IVectorView<StorageFile>> PickMultipleFilesAsync()Public Function PickMultipleFilesAsync() As IAsyncOperation( Of IVectorViewStorageFile )public IAsyncOperation<IVectorView<StorageFile>> PickMultipleFilesAsync()

    Returns

    • When the call to this method completes successfully, it returns a FilePickerSelectedFilesArray object that contains all the files that were picked by the user. Picked files in this array are represented by StorageFile objects.

    Remarks

    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 code examples in FileOpenPicker and the File picker sample show you how.

  • PickSingleFileAndContinue()
    PickSingleFileAndContinue()
    PickSingleFileAndContinue()
    PickSingleFileAndContinue()

    Shows the file picker so that the user can pick one file, potentially deactivating the app and reactivating it when the operation is complete. (Windows Phone Store app)

    public void PickSingleFileAndContinue()public void PickSingleFileAndContinue()Public Function PickSingleFileAndContinue() As voidpublic void PickSingleFileAndContinue()

    Remarks

    Windows Phone Store app only. Use the ContinuationData property to store context information that can be retrieved when the app is reactivated. For more info, see How to continue your Windows Phone app after calling a file picker.

  • PickSingleFileAsync()
    PickSingleFileAsync()
    PickSingleFileAsync()
    PickSingleFileAsync()

    Shows the file picker so that the user can pick one file.

    public IAsyncOperation<StorageFile> PickSingleFileAsync()public IAsyncOperation<StorageFile> PickSingleFileAsync()Public Function PickSingleFileAsync() As IAsyncOperation( Of StorageFile )public IAsyncOperation<StorageFile> PickSingleFileAsync()

    Returns

    • When the call to this method completes successfully, it returns a StorageFile object that represents the file that the user picked.

    Remarks

    This API isn't supported for Windows Phone for either Windows Runtime or Microsoft Silverlight. Use PickSingleFileAndContinue() instead.

  • PickSingleFileAsync(String)
    PickSingleFileAsync(String)
    PickSingleFileAsync(String)
    PickSingleFileAsync(String)

    Shows the file picker so that the user can pick one file.

    public IAsyncOperation<StorageFile> PickSingleFileAsync(String pickerOperationId)public IAsyncOperation<StorageFile> PickSingleFileAsync(String pickerOperationId)Public Function PickSingleFileAsync(pickerOperationId As String) As IAsyncOperation( Of StorageFile )public IAsyncOperation<StorageFile> PickSingleFileAsync(String pickerOperationId)

    Parameters

    • pickerOperationId
      System.String
      System.String
      System.String
      System.String

      This argument is ignored and has no effect.

    Returns

    • When the call to this method completes successfully, it returns a StorageFile object that represents the file that the user picked.

    Remarks

    Windows Store app only. This signature isn't supported. Use PickSingleFileAsync() instead.

    Windows Phone Store app only. This signature isn't supported. Use PickSingleFileAndContinue() instead.

  • ResumePickSingleFileAsync()
    ResumePickSingleFileAsync()
    ResumePickSingleFileAsync()
    ResumePickSingleFileAsync()

    Resumes the picking operation to retrieve the user-selected file if the user navigates away from the app after the picker operation has completed and the app is suspended.

    public static IAsyncOperation<StorageFile> ResumePickSingleFileAsync()public static IAsyncOperation<StorageFile> ResumePickSingleFileAsync()Public Static Function ResumePickSingleFileAsync() As IAsyncOperation( Of StorageFile )public static IAsyncOperation<StorageFile> ResumePickSingleFileAsync()

    Returns

    • When the call to this method completes successfully, it returns a StorageFile object that represents the file that the user picked.

    Remarks

    Do not use.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MuseAttribute
Windows.Foundation.Metadata.StaticAttribute

Details

Assembly

Windows.Storage.Pickers.dll