FileSavePicker FileSavePicker FileSavePicker FileSavePicker Class

Represents a file picker that lets the user choose the file name, extension, and storage location for a file.

Syntax

Declaration

public sealed class FileSavePickerpublic sealed class FileSavePickerPublic NotInheritable Class FileSavePicker

Remarks

To learn how to save files through the file picker, see How to save files through file pickers.

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.

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.

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 save a file.

if (rootPage.EnsureUnsnapped())
{
    FileSavePicker savePicker = new FileSavePicker();
    savePicker.SuggestedStartLocation = PickerLocationId.DocumentsLibrary;
    // Dropdown of file types the user can save the file as
    savePicker.FileTypeChoices.Add("Plain Text", new List<string>() { ".txt" });
    // Default file name if the user does not type one in or select a file to replace
    savePicker.SuggestedFileName = "New Document";

    StorageFile file = await savePicker.PickSaveFileAsync();
    if (file != null)
    {
        // Prevent updates to the remote version of the file until we finish making changes and call CompleteUpdatesAsync.
        CachedFileManager.DeferUpdates(file);
        // write to file
        await FileIO.WriteTextAsync(file, file.Name);
        // Let Windows know that we're finished changing the file so the other app can update the remote version of the file.
        // Completing updates may require Windows to ask for user input.
        FileUpdateStatus status = await CachedFileManager.CompleteUpdatesAsync(file);
        if (status == FileUpdateStatus.Complete)
        {
            OutputTextBlock.Text = "File " + file.Name + " was saved.";
        }
        else
        {
            OutputTextBlock.Text = "File " + file.Name + " couldn't be saved.";
        }
    }
    else
    {
        OutputTextBlock.Text = "Operation cancelled.";
    }
}
// Verify that we are currently not snapped, or that we can unsnap to open the picker
var currentState = Windows.UI.ViewManagement.ApplicationView.value;
if (currentState === Windows.UI.ViewManagement.ApplicationViewState.snapped &&
    !Windows.UI.ViewManagement.ApplicationView.tryUnsnap()) {
    // Fail silently if we can't unsnap
    return;
}

// Create the picker object and set options
var savePicker = new Windows.Storage.Pickers.FileSavePicker();
savePicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.documentsLibrary;
// Dropdown of file types the user can save the file as
savePicker.fileTypeChoices.insert("Plain Text", [".txt"]);
// Default file name if the user does not type one in or select a file to replace
savePicker.suggestedFileName = "New Document";

savePicker.pickSaveFileAsync().then(function (file) {
    if (file) {
        // Prevent updates to the remote version of the file until we finish making changes and call CompleteUpdatesAsync.
        Windows.Storage.CachedFileManager.deferUpdates(file);
        // write to file
        Windows.Storage.FileIO.writeTextAsync(file, file.name).done(function () {
            // Let Windows know that we're finished changing the file so the other app can update the remote version of the file.
            // Completing updates may require Windows to ask for user input.
            Windows.Storage.CachedFileManager.completeUpdatesAsync(file).done(function (updateStatus) {
                if (updateStatus === Windows.Storage.Provider.FileUpdateStatus.complete) {
                    WinJS.log && WinJS.log("File " + file.name + " was saved.", "sample", "status");
                } else {
                    WinJS.log && WinJS.log("File " + file.name + " couldn't be saved.", "sample", "status");
                }
            });
        });
    } else {
        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;
}

Constructors summary

Creates a new instance of a FileSavePicker.

Properties summary

Gets or sets the label text of the commit button in the file picker UI.

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

Gets or sets the default file name extension that the FileSavePicker gives to files to be saved.

Gets or sets an ID that specifies the enterprise that owns the file.

Gets the collection of valid file types that the user can choose to assign to a file.

Gets or sets the settings identifier associated with the current FileSavePicker instance.

Gets or sets the file name that the file save picker suggests to the user.

Gets or sets the StorageFile that the file picker suggests to the user for saving a file.

Gets or sets the location that the file save picker suggests to the user as the location to save a file.

Methods summary

Shows the file picker so that the user can save a file, 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 save a file and set the file name, extension, and location of the file to be saved. (Windows Store app)

Constructors

  • FileSavePicker()
    FileSavePicker()
    FileSavePicker()
    FileSavePicker()

    Creates a new instance of a FileSavePicker.

    public FileSavePicker()public FileSavePicker()Public Function FileSavePicker() As

Properties

  • CommitButtonText
    CommitButtonText
    CommitButtonText
    CommitButtonText

    Gets or sets the label text of the commit button in the file picker UI.

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

    Property Value

    • string
      string
      string
      string

      The label text.

    Remarks

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

  • ContinuationData
    ContinuationData
    ContinuationData
    ContinuationData

    Gets a set of values to be populated by the app before a PickSaveFileAndContinue() 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 ValueSet

    Property Value

    Remarks

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

  • DefaultFileExtension
    DefaultFileExtension
    DefaultFileExtension
    DefaultFileExtension

    Gets or sets the default file name extension that the FileSavePicker gives to files to be saved.

    public string DefaultFileExtension { get; set; }public string DefaultFileExtension { get; set; }Public ReadWrite Property DefaultFileExtension As string

    Property Value

    • string
      string
      string
      string

      The default file name extension.

  • EnterpriseId
    EnterpriseId
    EnterpriseId
    EnterpriseId

    Gets or sets an ID that specifies the enterprise that owns the file.

    public string EnterpriseId { get; set; }public string EnterpriseId { get; set; }Public ReadWrite Property EnterpriseId As string

    Property Value

    • string
      string
      string
      string

      An ID that specifies the enterprise that owns the file.

  • FileTypeChoices
    FileTypeChoices
    FileTypeChoices
    FileTypeChoices

    Gets the collection of valid file types that the user can choose to assign to a file.

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

    Property Value

    • A FilePickerFileTypesOrderedMap object that contains a collection of valid file types (extensions) that the user can use to save a file. Each element in this collection maps a display name to a corresponding collection of file name extensions. The key is a single string, the value is a list/vector of strings representing one or more extension choices.

    Remarks

    Some apps do not need to understand a file format in order to process it - such as a cloud storage provider. Therefore, using the file wildcard character - "*" - is supported for the FileTypeFilter collection. However, writing a file requires knowledge of its format. As a result, the wildcard is not supported for FileTypeChoices.

    One display name as a classification of file types might have multiple file types that support it. For example, a display name of "HTML page" could be saved either with ".htm" or ".html" extension. That is why the value of each entry in a FilePickerFileTypesOrderedMap is an ordered list (vector) of strings, displayed in the UI in the order that you place the extensions in the vector.

    Examples

    The File picker sample demonstrates how to add file type choices with a display name.

    FileSavePicker savePicker = new FileSavePicker();
    savePicker.SuggestedStartLocation = PickerLocationId.DocumentsLibrary;
    // Dropdown of file types the user can save the file as
    savePicker.FileTypeChoices.Add("Plain Text", new List<string>() { ".txt" });
    // Default file name if the user does not type one in or select a file to replace
    savePicker.SuggestedFileName = "New Document";
    
    // Create the picker object and set options
    var savePicker = new Windows.Storage.Pickers.FileSavePicker();
    savePicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.documentsLibrary;
    // Dropdown of file types the user can save the file as
    savePicker.fileTypeChoices.insert("Plain Text", [".txt"]);
    // Default file name if the user does not type one in or select a file to replace
    savePicker.suggestedFileName = "New Document";
    
  • SettingsIdentifier
    SettingsIdentifier
    SettingsIdentifier
    SettingsIdentifier

    Gets or sets the settings identifier associated with the current FileSavePicker instance.

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

    Property Value

    • string
      string
      string
      string

      The settings identifier.

    Remarks

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

  • SuggestedFileName
    SuggestedFileName
    SuggestedFileName
    SuggestedFileName

    Gets or sets the file name that the file save picker suggests to the user.

    public string SuggestedFileName { get; set; }public string SuggestedFileName { get; set; }Public ReadWrite Property SuggestedFileName As string

    Property Value

    • string
      string
      string
      string

      The initial suggested file name.

  • SuggestedSaveFile
    SuggestedSaveFile
    SuggestedSaveFile
    SuggestedSaveFile

    Gets or sets the StorageFile that the file picker suggests to the user for saving a file.

    public StorageFile SuggestedSaveFile { get; set; }public StorageFile SuggestedSaveFile { get; set; }Public ReadWrite Property SuggestedSaveFile As StorageFile

    Property Value

  • SuggestedStartLocation
    SuggestedStartLocation
    SuggestedStartLocation
    SuggestedStartLocation

    Gets or sets the location that the file save picker suggests to the user as the location to save a file.

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

    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.

Methods

  • PickSaveFileAndContinue()
    PickSaveFileAndContinue()
    PickSaveFileAndContinue()
    PickSaveFileAndContinue()

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

    public void PickSaveFileAndContinue()public void PickSaveFileAndContinue()Public Function PickSaveFileAndContinue() As void

    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.

  • PickSaveFileAsync()
    PickSaveFileAsync()
    PickSaveFileAsync()
    PickSaveFileAsync()

    Shows the file picker so that the user can save a file and set the file name, extension, and location of the file to be saved. (Windows Store app)

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

    Returns

    • When the call to this method completes successfully, it returns a StorageFile object that was created to represent the saved file. The file name, extension, and location of this StorageFile match those specified by the user, but the file has no content.

      To save the content of the file, your app must write the content to this StorageFile.

    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 FileSavePicker and the File picker sample show you how.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

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

Details

Assembly

Windows.Storage.Pickers.dll