Tutorial: Salvar um arquivo com seletores de Windows App SDK no WinUI

Ao criar Windows aplicativos com Windows App SDK, os usuários geralmente precisam salvar arquivos como documentos, imagens ou outros conteúdos em locais específicos em seu dispositivo. O Windows App SDK fornece a classe FileSavePicker para criar uma interface consistente e amigável que permite que os usuários escolham onde salvar arquivos e o que nomeá-los.

Este artigo mostra como implementar um seletor de salvamento de arquivos em seu aplicativo WinUI. Você aprenderá a configurar a aparência e o comportamento do seletor, manipular a seleção do usuário e salvar o conteúdo no local escolhido.

O seletor de arquivos de salvamento pode ser preenchido com um nome de arquivo sugerido e outras configurações padrão para facilitar a salvação dos arquivos pelos usuários:

Pré-requisitos

Antes de começar, verifique se você tem:

• Um projeto WinUI configurado com Windows App SDK
• Familiaridade básica com C# e XAML
• Noções básicas sobre padrões assíncronos/de espera em C#

APIs importantes

As seguintes APIs são usadas neste tópico:

• FileSavePicker
• StorageFile

Use o FileSavePicker para permitir que os usuários especifiquem o nome e o local onde desejam que seu aplicativo salve um arquivo.

Salvar um documento com FileSavePicker

Use um FileSavePicker para que os usuários possam especificar o nome, o tipo e o local de um arquivo a ser salvo. Crie, personalize e mostre um objeto seletor de arquivo e salve dados por meio do objeto StorageFile retornado que representa o arquivo escolhido.

1. Crie e personalize o FileSavePicker. Comece criando um novo objeto FileSavePicker e defina propriedades no objeto para personalizar o seletor de arquivos para seu aplicativo e seus usuários:

    using Microsoft.Windows.Storage.Pickers;
    ...
    var savePicker = new FileSavePicker(this.AppWindow.Id)
    {
        // (Optional) Specify the initial location for the picker. 
        //     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
        //     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
        SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
        
        // (Optional) specify the default file name. If not specified, use system default.
        SuggestedFileName = "My Document",
    
        // (Optional) Sets the folder that the file save dialog displays when it opens.
        //     If not specified or the specified path doesn't exist, defaults to the last folder the user visited.
        SuggestedFolder = @"C:\MyFiles",
    
        // (Optional) specify the text displayed on the commit button. 
        //     If not specified, the system uses a default label of "Save" (suitably translated).
        CommitButtonText = "Save Document",
    
        // (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
        //     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
        FileTypeChoices = {
            { "Documents", new List<string> { ".txt", ".doc", ".docx" } }
        },
    
        // (Optional) specify the default file extension (will be appended to SuggestedFileName).
        //      If not specified, no extension will be appended.
        DefaultFileExtension = ".txt",
    };

    #include <winrt/Microsoft.Windows.Storage.Pickers.h>
    using namespace winrt::Microsoft::Windows::Storage::Pickers;
    
    FileSavePicker savePicker(AppWindow().Id());
    
    // (Optional) Specify the initial location for the picker. 
    //     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
    //     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
    savePicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);
    
    // (Optional) specify the default file name. If not specified, use system default.
    savePicker.SuggestedFileName(L"NewDocument");
    
    // (Optional) Sets the folder that the file save dialog displays when it opens.
    //     If not specified or the specified path doesn't exist, defaults to the last folder the user visited.
    savePicker.SuggestedFolder = L"C:\\MyFiles",
    
    // (Optional) specify the text displayed on the commit button. 
    //     If not specified, the system uses a default label of "Save" (suitably translated).
    savePicker.CommitButtonText(L"Save Document");
    
    // (Optional) categorized extension types. If not specified, "All Files (*.*)" is allowed.
    //     Note that when "All Files (*.*)" is allowed, end users can save a file without an extension.
    savePicker.FileTypeChoices().Insert(L"Text", winrt::single_threaded_vector<winrt::hstring>({ L".txt" }));
    
    // (Optional) specify the default file extension (will be appended to SuggestedFileName).
    //      If not specified, no extension will be appended.
    savePicker.DefaultFileExtension(L".txt");

Este exemplo define seis propriedades: SuggestedStartLocation, SuggestedFileName, SuggestedFolder, CommitButtonText, FileTypeChoices e DefaultFileExtension.

Como o usuário está salvando um documento ou arquivo de texto, o exemplo define o SuggestedStartLocation como a pasta da biblioteca de Documentos, usando o valor DocumentsLibrary do PickerLocationId. Defina SuggestedStartLocation como um local apropriado para o tipo de arquivo que está sendo salvo, por exemplo, Música, Imagens, Vídeos ou Documentos. No local de início, o usuário pode navegar e selecionar outros locais.

Para poupar o usuário de um pouco de digitação, o exemplo define um SuggestedFileName. O nome do arquivo sugerido deve ser relevante para o arquivo que está sendo salvo. Por exemplo, como Word, você pode sugerir o nome do arquivo existente se houver um ou a primeira linha de um documento se o usuário estiver salvando um arquivo que ainda não tenha um nome.

Use a propriedade FileTypeChoices ao especificar os tipos de arquivo compatíveis com o exemplo (Microsoft Word documentos e arquivos de texto). Isso garante que o aplicativo possa abrir o arquivo depois que ele for salvo. Verifique se todos os tipos de arquivo especificados são compatíveis com seu aplicativo. Os usuários poderão salvar o arquivo como qualquer um dos tipos de arquivo especificados. Eles também podem alterar o tipo de arquivo selecionando outro dos tipos de arquivo especificados. A primeira opção de tipo de arquivo na lista será selecionada por padrão. Para controlar isso, defina a propriedade DefaultFileExtension .

2. Em seguida, mostre o FileSavePicker e salve-o no local do arquivo escolhido. Exiba o seletor de arquivos chamando PickSaveFileAsync. Depois que o usuário especifica o nome, o tipo de arquivo e o local e confirma para salvar o arquivo, PickSaveFileAsync retorna um objeto FilePickResult leve que contém o caminho para o arquivo salvo e o nome do arquivo. Você pode capturar e processar esse arquivo se tiver acesso de leitura e gravação a ele.

    using Microsoft.Windows.Storage.Pickers;
    ...
    var savePicker = new FileSavePicker(this.AppWindow.Id);
    var result = await savePicker.PickSaveFileAsync();
    if (result != null)
    {
        if (!System.IO.File.Exists(result.Path))
        {
            // Create a file and write to it.
            System.IO.File.WriteAllText(result.Path, "Hello world." + Environment.NewLine);
        }
        else
        {
            // Append to the existing file.
            System.IO.File.AppendAllText(result.Path, "Hello again." + Environment.NewLine);
        }
    }
    else
    {
        this.textBlock.Text = "Operation cancelled.";
    }

    #include <winrt/Microsoft.Windows.Storage.Pickers.h>
    #include <fstream>
    #include <string>
    using namespace winrt::Microsoft::Windows::Storage::Pickers;
    
    FileSavePicker savePicker(AppWindow().Id());
    auto result{ co_await savePicker.PickSaveFileAsync() };
    if (result)
    {
        // Check if the file exists.
        if (!std::ifstream(result.Path().c_str()))
        {
            std::ofstream outFile(result.Path().c_str());
            outFile << "Hello world.";
            outFile.close();
        }
        else
        {
            // Append to the existing file.
            std::ofstream outFile(result.Path().c_str(), std::ios::app);
            outFile << "Hello again.";
            outFile.close();
        }
    }
    else
    {
        textBlock().Text(L"Operation cancelled.");
    }

O exemplo verifica se o arquivo existe e cria um novo arquivo ou acrescenta ao arquivo existente. Se o usuário cancelar a operação, o resultado será nulle você poderá lidar com esse caso adequadamente, como exibir uma mensagem para o usuário.

Conteúdo relacionado

Windows. Storage.Pickers

Files, pastas e bibliotecas com Windows App SDK

PickSaveFileAsync