FileSavePicker Classe

Definizione

Spazio dei nomi:

Windows.Storage.Pickers

Rappresenta un selettore di file che consente all'utente di scegliere il nome, l'estensione e il percorso di archiviazione per un file.

In un'app desktop prima di usare un'istanza di questa classe in modo da visualizzare l'interfaccia utente, sarà necessario associare l'oggetto all'handle della finestra del proprietario. Per altre informazioni ed esempi di codice, vedere Visualizzare gli oggetti dell'interfaccia utente WinRT che dipendono da 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

Ereditarietà

Object Platform::Object IInspectable FileSavePicker

Attributi

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Requisiti Windows

Famiglia di dispositivi	Windows 10 (è stato introdotto in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (è stato introdotto in v1.0)

Esempio

L'esempio di selezione file è disponibile nelle versioni C# e C++/WinRT. Viene illustrato come verificare se l'app viene interrotta, come impostare le proprietà del selettore file e come visualizzare una selezione file in modo che l'utente possa salvare un file.

Ecco un estratto dalla versione C# dell'app di esempio.

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

Commenti

Importante

È necessario utilizzare la proprietà FileTypeChoices per specificare uno o più tipi di file prima di chiamare il metodo PickSaveFileAsync oppure il selettore genererà un'eccezione.

Per informazioni su come salvare i file tramite la selezione file, vedere Come salvare i file tramite selezione file.

Per iniziare a accedere ai file e alla selezione file delle cartelle, vedere File, cartelle e librerie .

Avviso

Se si tenta di visualizzare la selezione file mentre l'app viene ignorata, la selezione file non verrà visualizzata e verrà generata un'eccezione. È possibile evitare questa operazione assicurandosi che l'app non venga ignorata o annullandola prima di chiamare la selezione file. Gli esempi di codice seguenti e l'esempio di selezione file illustrano come.

In un'app desktop che richiede l'elevazione

In un'app desktop (che include app WinUI 3), è possibile usare FileSavePicker (e altri tipi da Windows.Storage.Pickers). Tuttavia, se l'app desktop richiede l'elevazione dell'esecuzione, sarà necessario un approccio diverso, perché queste API non sono progettate per essere usate in un'app con privilegi elevati. Il frammento di codice riportato di seguito illustra come usare invece le API di selezione Win32 C#/Win32 P/Invoke Source Generator (CsWin32). Per informazioni su come usare CsWin32, seguire questo collegamento per la documentazione.

// 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;
            }
        }
    }
}

Cronologia delle versioni

Versione di Windows	Versione dell'SDK	Valore aggiunto
1903	18362	CreateForUser
1903	18362	Utente

Costruttori

FileSavePicker()

Crea una nuova istanza di fileSavePicker. In un'app desktop prima di usare un'istanza di questa classe in modo da visualizzare l'interfaccia utente, sarà necessario associare l'oggetto all'handle della finestra del proprietario. Per altre informazioni ed esempi di codice, vedere Visualizzare gli oggetti dell'interfaccia utente WinRT che dipendono da CoreWindow.

Proprietà

CommitButtonText	Ottiene o imposta il testo dell'etichetta del pulsante di commit nell'interfaccia utente del selettore file.
ContinuationData	Ottiene un set di valori da popolare dall'app prima di un'operazione PickSaveFileAndContinue che disattiva l'app per fornire contesto quando l'app viene attivata. (Windows Phone app 8.x)
DefaultFileExtension	Importante Non usare questa proprietà. Utilizzare invece la proprietà FileTypeChoices . L'estensione di file predefinita è impostata dal primo tipo di file nel primo gruppo di tipi di file in FileTypeChoices. Ottiene o imposta l'estensione del nome file predefinita che il fileSavePicker fornisce ai file da salvare.
EnterpriseId	Ottiene o imposta un ID che specifica l'organizzazione proprietaria del file.
FileTypeChoices	Ottiene la raccolta di tipi di file validi che l'utente può scegliere di assegnare a un file.
SettingsIdentifier	Ottiene o imposta l'identificatore delle impostazioni associato all'istanza corrente di FileSavePicker .
SuggestedFileName	Ottiene o imposta il nome del file che il selettore di salvataggio del file suggerisce all'utente.
SuggestedSaveFile	Ottiene o imposta il file di archiviazione che il selettore file suggerisce all'utente per salvare un file.
SuggestedStartLocation	Ottiene o imposta il percorso che il selettore di salvataggio file suggerisce all'utente come percorso per salvare un file.
User	Ottiene informazioni sull'utente per cui è stato creato FileSavePicker . Usare questa proprietà per le applicazioni multiutente.

Metodi

CreateForUser(User)	Crea un FileSavePicker con ambito nella directory personale dell'utente specificato. Usare questo metodo per applicazioni multiutente.
PickSaveFileAndContinue()	Obsoleto a partire da Windows 10; usare invece PickSaveFileAsync. Mostra la selezione file in modo che l'utente possa salvare un file, disattivarlo e riattivarlo al termine dell'operazione. (Windows Phone app 8.x)
PickSaveFileAsync()	Mostra la selezione file in modo che l'utente possa salvare un file e impostare il nome, l'estensione e il percorso del file da salvare. (app UWP)

Vedi anche

• StorageFile
• Esempio di selezione file (Windows 10)
• File, cartelle e raccolte
• Come salvare i file con una selezione file
• Visualizzare oggetti dell'interfaccia utente WinRT che dipendono da CoreWindow