FileSavePicker Classe

Definição

Namespace:

Windows.Storage.Pickers

Representa um seletor de arquivos que permite que o usuário escolha o nome do arquivo, a extensão e o local de armazenamento de um arquivo.

Em um aplicativo da área de trabalho, antes de usar uma instância dessa classe de uma maneira que exiba a interface do usuário, você precisará associar o objeto ao identificador de janela do proprietário. Para obter mais informações e exemplos de código, consulte Exibir objetos de interface do usuário do WinRT que dependem do CoreWindow.

public ref class FileSavePicker sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class FileSavePicker final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class FileSavePicker

function FileSavePicker()

Public NotInheritable Class FileSavePicker

Herança

Object Platform::Object IInspectable FileSavePicker

Atributos

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Requisitos do Windows

Família de dispositivos	Windows 10 (introduzida na 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduzida na v1.0)

Exemplos

O exemplo do seletor de arquivos está disponível nas versões C# e C++/WinRT. Ele demonstra como verificar se o aplicativo foi ajustado, como definir propriedades do seletor de arquivos e como mostrar um seletor de arquivos para que o usuário possa salvar um arquivo.

Aqui está um trecho da versão C# do aplicativo de exemplo.

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.";
    }
}

Comentários

Importante

Você deve usar a propriedade FileTypeChoices para especificar um ou mais tipos de arquivo antes de chamar o método PickSaveFileAsync ou o seletor gerará uma exceção.

Para saber como salvar arquivos por meio do seletor de arquivos, consulte Como salvar arquivos por meio de seletores de arquivos.

Para começar a acessar o seletor de arquivos e pastas, consulte Arquivos, pastas e bibliotecas .

Aviso

Se você tentar mostrar o seletor de arquivos enquanto o aplicativo estiver ajustado, o seletor de arquivos não será mostrado e uma exceção será gerada. Você pode evitar isso certificando-se de que seu aplicativo não esteja ajustado ou desmarcando-o antes de chamar o seletor de arquivos. Os exemplos de código a seguir e o exemplo do seletor de arquivos mostram como.

Em um aplicativo da área de trabalho que requer elevação

Em um aplicativo da área de trabalho (que inclui aplicativos WinUI 3), você pode usar FileSavePicker (e outros tipos de Windows.Storage.Pickers). Mas se o aplicativo da área de trabalho exigir elevação para ser executado, você precisará de uma abordagem diferente (isso porque essas APIs não foram projetadas para serem usadas em um aplicativo com privilégios elevados). O snippet de código abaixo ilustra como você pode usar o C#/Win32 P/Invoke Source Generator (CsWin32) para chamar as APIs de seleção do Win32. Para saber como usar CsWin32, siga esse link para a documentação.

// NativeMethods.txt
CoCreateInstance
FileSaveDialog
IFileSaveDialog
SHCreateItemFromParsingName

// MainWindow.xaml
...
<TextBlock x:Name="OutputTextBlock"/>
...

// MainWindow.xaml.cs
using Microsoft.UI.Xaml;
using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;

using Windows.Win32;
using Windows.Win32.Foundation;
using Windows.Win32.System.Com;
using Windows.Win32.UI.Shell;
using Windows.Win32.UI.Shell.Common;

namespace FileSavePickerExample
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
        }

        private unsafe void myButton_Click(object sender, RoutedEventArgs e)
        {
            try
            {
                // Retrieve the window handle (HWND) of the main WinUI 3 window.
                var hWnd = WinRT.Interop.WindowNative.GetWindowHandle(this);

                int hr = PInvoke.CoCreateInstance<IFileSaveDialog>(
                    typeof(FileSaveDialog).GUID,
                    null,
                    CLSCTX.CLSCTX_INPROC_SERVER,
                    out var fsd);
                if (hr < 0)
                {
                    Marshal.ThrowExceptionForHR(hr);
                }

                // Set file type filters.
                string filter = "Word Documents|*.docx|JPEG Files|*.jpg";

                List<COMDLG_FILTERSPEC> extensions = new List<COMDLG_FILTERSPEC>();

                if (!string.IsNullOrEmpty(filter))
                {
                    string[] tokens = filter.Split('|');
                    if (0 == tokens.Length % 2)
                    {
                        // All even numbered tokens should be labels.
                        // Odd numbered tokens are the associated extensions.
                        for (int i = 1; i < tokens.Length; i += 2)
                        {
                            COMDLG_FILTERSPEC extension;

                            extension.pszSpec = (char*)Marshal.StringToHGlobalUni(tokens[i]);
                            extension.pszName = (char*)Marshal.StringToHGlobalUni(tokens[i - 1]);
                            extensions.Add(extension);
                        }
                    }
                }

                fsd.SetFileTypes(extensions.ToArray());

                // Set the default folder.
                hr = PInvoke.SHCreateItemFromParsingName(
                    Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments),
                    null,
                    typeof(IShellItem).GUID,
                    out var directoryShellItem);
                if (hr < 0)
                {
                    Marshal.ThrowExceptionForHR(hr);
                }

                fsd.SetFolder((IShellItem)directoryShellItem);
                fsd.SetDefaultFolder((IShellItem)directoryShellItem);

                // Set the default file name.
                fsd.SetFileName($"{DateTime.Now:yyyyMMddHHmm}");

                // Set the default extension.
                fsd.SetDefaultExtension(".docx");

                fsd.Show(new HWND(hWnd));

                fsd.GetResult(out var ppsi);

                PWSTR filename;
                ppsi.GetDisplayName(SIGDN.SIGDN_FILESYSPATH, &filename);

                OutputTextBlock.Text = filename.ToString();
            }
            catch (Exception ex)
            {
                OutputTextBlock.Text = "a problem occured: " + ex.Message;
            }
        }
    }
}

Histórico de versão

Versão do Windows	Versão do SDK	Valor adicionado
1903	18362	CreateForUser
1903	18362	Usuário

Construtores

FileSavePicker()

Cria uma nova instância de um FileSavePicker. Em um aplicativo da área de trabalho, antes de usar uma instância dessa classe de uma maneira que exiba a interface do usuário, você precisará associar o objeto ao identificador de janela do proprietário. Para obter mais informações e exemplos de código, consulte Exibir objetos de interface do usuário do WinRT que dependem do CoreWindow.

Propriedades

CommitButtonText	Obtém ou define o texto do rótulo do botão confirmar na interface do usuário do seletor de arquivos.
ContinuationData	Obtém um conjunto de valores a serem preenchidos pelo aplicativo antes de uma operação PickSaveFileAndContinue que desativa o aplicativo para fornecer contexto quando o aplicativo é ativado. (aplicativo Windows Phone 8.x)
DefaultFileExtension	Importante Não use esta propriedade. Em vez disso, use a propriedade FileTypeChoices . A extensão de arquivo padrão é definida pelo primeiro tipo de arquivo no primeiro grupo de tipos de arquivo em FileTypeChoices. Obtém ou define a extensão de nome de arquivo padrão que o fileSavePicker dá aos arquivos a serem salvos.
EnterpriseId	Obtém ou define uma ID que especifica a empresa que possui o arquivo.
FileTypeChoices	Obtém a coleção de tipos de arquivo válidos que o usuário pode optar por atribuir a um arquivo.
SettingsIdentifier	Obtém ou define o identificador de configurações associado à instância atual do FileSavePicker .
SuggestedFileName	Obtém ou define o nome do arquivo que o seletor de salvamento de arquivo sugere ao usuário.
SuggestedSaveFile	Obtém ou define o storageFile que o seletor de arquivos sugere ao usuário para salvar um arquivo.
SuggestedStartLocation	Obtém ou define o local que o seletor de salvamento de arquivo sugere ao usuário como o local para salvar um arquivo.
User	Obtém informações sobre o usuário para o qual o FileSavePicker foi criado. Use essa propriedade para aplicativos multiusuários.

Métodos

CreateForUser(User)	Cria um FileSavePicker com escopo para o diretório pessoal do usuário especificado. Use esse método para aplicativos multiusuários.
PickSaveFileAndContinue()	Obsoleto a partir de Windows 10; use PickSaveFileAsync. Mostra o seletor de arquivos para que o usuário possa salvar um arquivo, desativando e o aplicativo e reativando-o quando a operação for concluída. (aplicativo Windows Phone 8.x)
PickSaveFileAsync()	Mostra o seletor de arquivos para que o usuário possa salvar um arquivo e definir o nome do arquivo, a extensão e o local do arquivo a ser salvo. (Aplicativo UWP)

Confira também

• StorageFile
• Exemplo de seletor de arquivo (Windows 10)
• Arquivos, pastas e bibliotecas
• Como salvar arquivos com um seletor de arquivos
• Exibir objetos da interface do usuário do WinRT que dependem do CoreWindow