FileSavePicker Klasse

Definition

Namespace:

Windows.Storage.Pickers

Stellt eine Dateiauswahl dar, mit der der Benutzer den Dateinamen, die Erweiterung und den Speicherort für eine Datei auswählen kann.

Bevor Sie in einer Desktop-App eine Instanz dieser Klasse auf eine Weise verwenden, die die Benutzeroberfläche anzeigt, müssen Sie das Objekt dem Fensterhandle des Besitzers zuordnen. Weitere Informationen und Codebeispiele finden Sie unter Anzeigen von WinRT-UI-Objekten, die von CoreWindow abhängen.

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

Vererbung

Object Platform::Object IInspectable FileSavePicker

Attribute

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows-Anforderungen

Gerätefamilie	Windows 10 (eingeführt in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (eingeführt in v1.0)

Beispiele

Das Beispiel für die Dateiauswahl ist in C#- und C++/WinRT-Versionen verfügbar. Es veranschaulicht, wie überprüft wird, ob die App angedockt ist, wie Dateiauswahleigenschaften festgelegt werden und wie eine Dateiauswahl angezeigt wird, damit der Benutzer eine Datei speichern kann.

Hier ist ein Auszug aus der C#-Version der Beispiel-App.

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

Hinweise

Wichtig

Sie müssen die FileTypeChoices-Eigenschaft verwenden, um einen oder mehrere Dateitypen anzugeben, bevor Sie die PickSaveFileAsync-Methode aufrufen. Andernfalls löst die Auswahl eine Ausnahme aus.

Informationen zum Speichern von Dateien über die Dateiauswahl finden Sie unter Speichern von Dateien über Die Dateiauswahl.

Informationen zu den ersten Schritten mit dem Zugriff auf die Dateiauswahl für Dateien und Ordner finden Sie unter Dateien, Ordner und Bibliotheken .

Warnung

Wenn Sie versuchen, die Dateiauswahl anzuzeigen, während Ihre App angedockt ist, wird die Dateiauswahl nicht angezeigt, und es wird eine Ausnahme ausgelöst. Sie können dies vermeiden, indem Sie sicherstellen, dass Ihre App nicht angedockt ist, oder indem Sie sie aufheben, bevor Sie die Dateiauswahl aufrufen. Die folgenden Codebeispiele und das Beispiel für die Dateiauswahl zeigen Ihnen, wie das geht.

In einer Desktop-App, die eine Erhöhung erfordert

In einer Desktop-App (einschließlich WinUI 3-Apps) können Sie FileSavePicker (und andere Typen von Windows.Storage.Pickers) verwenden. Wenn für die Ausführung der Desktop-App jedoch Rechteerweiterungen erforderlich sind, benötigen Sie einen anderen Ansatz (weil diese APIs nicht für die Verwendung in einer App mit erhöhten Rechten konzipiert sind). Der folgende Codeausschnitt veranschaulicht, wie Sie stattdessen den C#/Win32 P/Invoke Source Generator (CsWin32) verwenden können, um die Win32-Auswahl-APIs aufzurufen. Informationen zur Verwendung von CsWin32 finden Sie unter diesem Link in der Dokumentation.

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

Versionsverlauf

Windows-Version	SDK-Version	Mehrwert
1903	18362	CreateForUser
1903	18362	Benutzer

Konstruktoren

FileSavePicker()

Erstellt eine neue Instanz eines FileSavePicker. Bevor Sie in einer Desktop-App eine Instanz dieser Klasse auf eine Weise verwenden, die die Benutzeroberfläche anzeigt, müssen Sie das Objekt dem Fensterhandle des Besitzers zuordnen. Weitere Informationen und Codebeispiele finden Sie unter Anzeigen von WinRT-UI-Objekten, die von CoreWindow abhängen.

Eigenschaften

CommitButtonText	Ruft den Bezeichnungstext der Commitschaltfläche auf der Benutzeroberfläche der Dateiauswahl ab oder legt diesen fest.
ContinuationData	Ruft einen Satz von Werten ab, die von der App vor einem PickSaveFileAndContinue-Vorgang aufgefüllt werden sollen, der die App deaktiviert, um Kontext bereitzustellen, wenn die App aktiviert wird. (Windows Phone 8.x-App)
DefaultFileExtension	Wichtig Verwenden Sie diese Eigenschaft nicht. Verwenden Sie stattdessen die FileTypeChoices-Eigenschaft . Die Standarddateierweiterung wird durch den ersten Dateityp in der ersten Dateitypgruppe in FileTypeChoices festgelegt. Ruft die Standarddateierweiterung ab, die fileSavePicker den zu speichernden Dateien übergibt, oder legt diese fest.
EnterpriseId	Ruft eine ID ab, die das Unternehmen angibt, das besitzer der Datei ist, oder legt diese fest.
FileTypeChoices	Ruft die Auflistung gültiger Dateitypen ab, die der Benutzer einer Datei zuweisen kann.
SettingsIdentifier	Ruft den Einstellungsbezeichner ab, der der aktuellen FileSavePicker-Instanz zugeordnet ist, oder legt diese fest.
SuggestedFileName	Ruft den Dateinamen ab, den die Dateispeicherauswahl dem Benutzer vorschlägt, oder legt diesen fest.
SuggestedSaveFile	Ruft die storageFile-Datei ab, die die Dateiauswahl dem Benutzer zum Speichern einer Datei vorschlägt, oder legt sie fest.
SuggestedStartLocation	Ruft den Speicherort ab, den die Dateispeicherauswahl dem Benutzer als Speicherort zum Speichern einer Datei vorschlägt, oder legt diesen fest.
User	Ruft Informationen zu dem Benutzer ab, für den fileSavePicker erstellt wurde. Verwenden Sie diese Eigenschaft für Mehrbenutzeranwendungen.

Methoden

CreateForUser(User)	Erstellt einen FileSavePicker , der auf das persönliche Verzeichnis des angegebenen Benutzers ausgerichtet ist. Verwenden Sie diese Methode für Anwendungen mit mehreren Benutzern.
PickSaveFileAndContinue()	Ab Windows 10 veraltet. Verwenden Sie stattdessen PickSaveFileAsync. Zeigt die Dateiauswahl an, damit der Benutzer eine Datei speichern und die App deaktivieren und nach Abschluss des Vorgangs reaktivieren kann. (Windows Phone 8.x-App)
PickSaveFileAsync()	Zeigt die Dateiauswahl an, damit der Benutzer eine Datei speichern und den Dateinamen, die Erweiterung und den Speicherort der zu speichernden Datei festlegen kann. (UWP-App)

Weitere Informationen

• StorageFile
• Beispiel für die Dateiauswahl (Windows 10)
• Dateien, Ordner und Bibliotheken
• Speichern von Dateien mit einer Dateiauswahl
• Anzeigen von WinRT UI-Objekten, die von CoreWindow abhängig sind