File: System\Windows\Forms\Dialogs\CommonDialogs\FolderBrowserDialog.cs
Web Access
Project: src\src\System.Windows.Forms\src\System.Windows.Forms.csproj (System.Windows.Forms)
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
using System.ComponentModel;
using System.Drawing.Design;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using Windows.Win32.System.Com;
using static Windows.Win32.UI.Shell.FILEOPENDIALOGOPTIONS;
 
namespace System.Windows.Forms;
 
/// <summary>
///  Represents a common dialog box that allows the user to specify options for
///  selecting a folder. This class cannot be inherited.
/// </summary>
[DefaultEvent(nameof(HelpRequest))]
[DefaultProperty(nameof(SelectedPath))]
[Designer($"System.Windows.Forms.Design.FolderBrowserDialogDesigner, {AssemblyRef.SystemDesign}"),]
[SRDescription(nameof(SR.DescriptionFolderBrowserDialog))]
public sealed class FolderBrowserDialog : CommonDialog
{
    // Root node of the tree view.
    private Environment.SpecialFolder _rootFolder;
 
    // Description text to show.
    private string _descriptionText;
 
    // Folders picked by the user.
    private string[] _selectedPaths;
 
    // Initial folder.
    private string _initialDirectory;
 
    // Win32 file dialog FOS_* option flags.
    private FILEOPENDIALOGOPTIONS _options;
 
    /// <summary>
    ///  Initializes a new instance of the <see cref="FolderBrowserDialog"/> class.
    /// </summary>
    public FolderBrowserDialog()
    {
        Reset();
    }
 
    /// <summary>
    ///  Gets or sets a value indicating whether the dialog box adds the folder being selected to the recent list.
    /// </summary>
    [SRCategory(nameof(SR.CatBehavior))]
    [DefaultValue(true)]
    [SRDescription(nameof(SR.FolderBrowserDialogAddToRecent))]
    public bool AddToRecent
    {
        get => !GetOption(FOS_DONTADDTORECENT);
        set => SetOption(FOS_DONTADDTORECENT, !value);
    }
 
    /// <summary>
    ///  Gets or sets whether the dialog will be automatically upgraded to enable new features.
    /// </summary>
    [DefaultValue(true)]
    public bool AutoUpgradeEnabled { get; set; } = true;
 
    [Browsable(false)]
    [EditorBrowsable(EditorBrowsableState.Never)]
    public new event EventHandler? HelpRequest
    {
        add => base.HelpRequest += value;
        remove => base.HelpRequest -= value;
    }
 
    /// <summary>
    ///  Gets or sets a value indicating whether the dialog box allows multiple folders to be selected.
    /// </summary>
    [SRCategory(nameof(SR.CatBehavior))]
    [DefaultValue(false)]
    [SRDescription(nameof(SR.FolderBrowserDialogMultiSelectDescr))]
    public bool Multiselect
    {
        get => GetOption(FOS_ALLOWMULTISELECT);
        set => SetOption(FOS_ALLOWMULTISELECT, value);
    }
 
    /// <summary>
    ///  Gets or sets a value indicating whether the OK button of the dialog box is
    ///  disabled until the user navigates the view or edits the filename (if applicable).
    /// </summary>
    /// <remarks>
    ///  <para>
    ///  Note: Disabling of the OK button does not prevent the dialog from being submitted by the Enter key.
    ///  </para>
    /// </remarks>
    [SRCategory(nameof(SR.CatBehavior))]
    [DefaultValue(false)]
    [SRDescription(nameof(SR.FolderBrowserDialogOkRequiresInteraction))]
    public bool OkRequiresInteraction
    {
        get => GetOption(FOS_OKBUTTONNEEDSINTERACTION);
        set => SetOption(FOS_OKBUTTONNEEDSINTERACTION, value);
    }
 
    /// <summary>
    ///  Gets or sets a value indicating whether the dialog box displays hidden and system files.
    /// </summary>
    [SRCategory(nameof(SR.CatBehavior))]
    [DefaultValue(false)]
    [SRDescription(nameof(SR.FolderBrowserDialogShowHiddenFiles))]
    public bool ShowHiddenFiles
    {
        get => GetOption(FOS_FORCESHOWHIDDEN);
        set => SetOption(FOS_FORCESHOWHIDDEN, value);
    }
 
    /// <summary>
    ///  Gets or sets a value indicating whether the items shown by default in the view's
    ///  navigation pane are shown.
    /// </summary>
    [SRCategory(nameof(SR.CatBehavior))]
    [DefaultValue(true)]
    [SRDescription(nameof(SR.FolderBrowserDialogShowPinnedPlaces))]
    public bool ShowPinnedPlaces
    {
        get => !GetOption(FOS_HIDEPINNEDPLACES);
        set => SetOption(FOS_HIDEPINNEDPLACES, !value);
    }
 
    /// <summary>
    ///  Determines if the 'New Folder' button should be exposed.
    ///  This property has no effect if the Vista style dialog is used; in that case, the New Folder button is always shown.
    /// </summary>
    [Browsable(true)]
    [DefaultValue(true)]
    [Localizable(false)]
    [SRCategory(nameof(SR.CatFolderBrowsing))]
    [SRDescription(nameof(SR.FolderBrowserDialogShowNewFolderButton))]
    public bool ShowNewFolderButton { get; set; }
 
    /// <summary>
    ///  <para>
    ///   Gets or sets the GUID to associate with this dialog state. Typically, state such
    ///   as the last visited folder and the position and size of the dialog is persisted
    ///   based on the name of the executable file. By specifying a GUID, an application can
    ///   have different persisted states for different versions of the dialog within the
    ///   same application (for example, an import dialog and an open dialog).
    ///  </para>
    ///  <para>
    ///   This functionality is not available if an application is not using visual styles
    ///   or if <see cref="AutoUpgradeEnabled"/> is set to <see langword="false"/>.
    ///  </para>
    /// </summary>
    [Localizable(false)]
    [Browsable(false)]
    [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
    public Guid? ClientGuid { get; set; }
 
    /// <summary>
    ///  Gets the directory path of the folder the user picked.
    ///  Sets the directory path of the initial folder shown in the dialog box.
    /// </summary>
    [Browsable(true)]
    [DefaultValue("")]
    [Editor($"System.Windows.Forms.Design.SelectedPathEditor, {AssemblyRef.SystemDesign}", typeof(UITypeEditor))]
    [Localizable(true)]
    [SRCategory(nameof(SR.CatFolderBrowsing))]
    [SRDescription(nameof(SR.FolderBrowserDialogSelectedPath))]
    [AllowNull]
    public string SelectedPath
    {
        get => _selectedPaths.Length > 0 ? _selectedPaths[0] : string.Empty;
        set => _selectedPaths = value is not null ? [value] : [];
    }
 
    /// <summary>
    ///  Retrieves the paths of all selected folders in the dialog box.
    /// </summary>
    [Browsable(false)]
    [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
    [SRDescription(nameof(SR.FolderBrowserDialogSelectedPathsDescr))]
    public string[] SelectedPaths => _selectedPaths.Length > 0 ? (string[])_selectedPaths.Clone() : [];
 
    /// <summary>
    ///  Gets or sets the initial directory displayed by the folder browser dialog.
    /// </summary>
    [SRCategory(nameof(SR.CatFolderBrowsing))]
    [DefaultValue("")]
    [Editor("System.Windows.Forms.Design.InitialDirectoryEditor, System.Windows.Forms.Design, Version=6.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089", typeof(UITypeEditor))]
    [SRDescription(nameof(SR.FDinitialDirDescr))]
    public string InitialDirectory
    {
        get => _initialDirectory;
        set => _initialDirectory = value ?? string.Empty;
    }
 
    /// <summary>
    ///  Gets/sets the root node of the directory tree.
    /// </summary>
    [Browsable(true)]
    [DefaultValue(Environment.SpecialFolder.Desktop)]
    [Localizable(false)]
    [SRCategory(nameof(SR.CatFolderBrowsing))]
    [SRDescription(nameof(SR.FolderBrowserDialogRootFolder))]
    [TypeConverter(typeof(SpecialFolderEnumConverter))]
    public Environment.SpecialFolder RootFolder
    {
        get => _rootFolder;
        set
        {
            // If users want to use other CSIDL values that aren't in SpecialFolder (as are exposed in
            // FolderNameEditor.FolderBrowserFolder) then we'll let them as we're not calling Environment.GetFolderPath
            // directly.
            _rootFolder = value;
        }
    }
 
    /// <summary>
    ///  Gets or sets a description to show above the folders. Here you can provide
    ///  instructions for selecting a folder.
    /// </summary>
    [Browsable(true)]
    [DefaultValue("")]
    [Localizable(true)]
    [SRCategory(nameof(SR.CatFolderBrowsing))]
    [SRDescription(nameof(SR.FolderBrowserDialogDescription))]
    public string Description
    {
        get => _descriptionText;
        set => _descriptionText = value ?? string.Empty;
    }
 
    /// <summary>
    ///  Gets or sets a value that indicates whether to use the value of the <see cref="Description" /> property
    ///  as the dialog title for Vista style dialogs. This property has no effect on old style dialogs.
    /// </summary>
    /// <value>
    ///  <see langword="true" /> to indicate that the value of the <see cref="Description" /> property is used as dialog title;
    ///  <see langword="false" /> to indicate the value is added as additional text to the dialog.
    ///  The default is <see langword="false" />.
    /// </value>
    [Browsable(true)]
    [DefaultValue(false)]
    [Localizable(true)]
    [SRCategory(nameof(SR.CatFolderBrowsing))]
    [SRDescription(nameof(SR.FolderBrowserDialogUseDescriptionForTitle))]
    public bool UseDescriptionForTitle { get; set; }
 
    private bool UseVistaDialogInternal
    {
        get => AutoUpgradeEnabled && SystemInformation.BootMode == BootMode.Normal;
    }
 
    /// <summary>
    ///  Resets all properties to their default values.
    /// </summary>
    [MemberNotNull(nameof(_descriptionText))]
    [MemberNotNull(nameof(_selectedPaths))]
    [MemberNotNull(nameof(_initialDirectory))]
    public override void Reset()
    {
        _options = (FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_FILEMUSTEXIST);
        _rootFolder = Environment.SpecialFolder.Desktop;
        _descriptionText = string.Empty;
        _selectedPaths = [];
        _initialDirectory = string.Empty;
        ShowNewFolderButton = true;
        ClientGuid = null;
    }
 
    /// <summary>
    ///  Displays a folder browser dialog box.
    /// </summary>
    /// <param name="hwndOwner">A handle to the window that owns the folder browser dialog.</param>
    /// <returns>
    ///  <see langword="true" /> if the folder browser dialog was successfully run; otherwise, <see langword="false" />.
    /// </returns>
    protected override bool RunDialog(IntPtr hwndOwner) =>
 
        // If running the Vista dialog fails (e.g. on Server Core), we fall back to the
        // legacy dialog.
        UseVistaDialogInternal && TryRunDialogVista((HWND)hwndOwner, out bool returnValue)
            ? returnValue
            : RunDialogOld((HWND)hwndOwner);
 
    private unsafe bool TryRunDialogVista(HWND owner, out bool returnValue)
    {
        IFileOpenDialog* dialog;
        try
        {
            // Creating the Vista dialog can fail on Windows Server Core, even if the
            // Server Core App Compatibility FOD is installed.
            PInvokeCore.CoCreateInstance(
                CLSID.FileOpenDialog,
                pUnkOuter: null,
                CLSCTX.CLSCTX_INPROC_SERVER | CLSCTX.CLSCTX_LOCAL_SERVER | CLSCTX.CLSCTX_REMOTE_SERVER,
                out dialog).ThrowOnFailure();
        }
        catch (COMException)
        {
            returnValue = false;
            return false;
        }
 
        try
        {
            SetDialogProperties(dialog);
            HRESULT hr = dialog->Show(owner);
            if (!hr.Succeeded)
            {
                if (hr == HRESULT.FromWin32(WIN32_ERROR.ERROR_CANCELLED))
                {
                    returnValue = false;
                    return true;
                }
 
                throw Marshal.GetExceptionForHR((int)hr)!;
            }
 
            GetResult(dialog);
            returnValue = true;
            return true;
        }
        finally
        {
            dialog->Release();
        }
    }
 
    private unsafe void SetDialogProperties(IFileOpenDialog* dialog)
    {
        if (ClientGuid is { } clientGuid)
        {
            // IFileDialog::SetClientGuid should be called immediately after creation of the dialog object.
            // https://docs.microsoft.com/windows/win32/api/shobjidl_core/nf-shobjidl_core-ifiledialog-setclientguid#remarks
            dialog->SetClientGuid(in clientGuid);
        }
 
        // Description
        if (!string.IsNullOrEmpty(_descriptionText))
        {
            if (UseDescriptionForTitle)
            {
                dialog->SetTitle(_descriptionText);
            }
            else
            {
                using ComScope<IFileDialogCustomize> customize = new(null);
                if (dialog->QueryInterface(IID.Get<IFileDialogCustomize>(), customize).Succeeded)
                {
                    customize.Value->AddText(0, _descriptionText);
                }
            }
        }
 
        dialog->SetOptions(_options);
 
        if (!string.IsNullOrEmpty(_initialDirectory))
        {
            using ComScope<IShellItem> initialDirectory = new(PInvoke.SHCreateShellItem(_initialDirectory));
            if (!initialDirectory.IsNull)
            {
                dialog->SetDefaultFolder(initialDirectory);
                dialog->SetFolder(initialDirectory);
            }
        }
 
        if (_selectedPaths.Length > 0)
        {
            string selectedPath = _selectedPaths[0];
            if (!string.IsNullOrEmpty(selectedPath))
            {
                string? parent = Path.GetDirectoryName(selectedPath);
                if (parent is null || !string.IsNullOrEmpty(_initialDirectory) || !Directory.Exists(parent))
                {
                    dialog->SetFileName(selectedPath);
                }
                else
                {
                    string folder = Path.GetFileName(selectedPath);
                    dialog->SetFolder(PInvoke.SHCreateItemFromParsingName(parent));
                    dialog->SetFileName(folder);
                }
            }
        }
    }
 
    private bool GetOption(FILEOPENDIALOGOPTIONS option) => _options.HasFlag(option);
 
    /// <summary>
    ///  Sets the given option to the given boolean value.
    /// </summary>
    private void SetOption(FILEOPENDIALOGOPTIONS option, bool value)
    {
        if (value)
        {
            _options |= option;
        }
        else
        {
            _options &= ~option;
        }
    }
 
    private unsafe void GetResult(IFileOpenDialog* dialog)
    {
        if (Multiselect)
        {
            using ComScope<IShellItemArray> itemArray = new(null);
            dialog->GetResults(itemArray);
            itemArray.Value->GetCount(out uint itemCount);
            List<string> tempSelectedPaths = [];
            for (uint itemIndex = 0; itemIndex < itemCount; itemIndex++)
            {
                using ComScope<IShellItem> item = new(null);
                itemArray.Value->GetItemAt(itemIndex, item);
                if (!item.IsNull)
                {
                    item.Value->GetDisplayName(SIGDN.SIGDN_FILESYSPATH, out PWSTR ppszName);
                    // An exception would've been received if GetDisplayName failed.
                    tempSelectedPaths.Add(ppszName.ToStringAndCoTaskMemFree()!);
                }
            }
 
            _selectedPaths = [.. tempSelectedPaths];
        }
        else
        {
            using ComScope<IShellItem> item = new(null);
            dialog->GetResult(item);
            if (!item.IsNull)
            {
                item.Value->GetDisplayName(SIGDN.SIGDN_FILESYSPATH, out PWSTR ppszName);
                SelectedPath = ppszName.ToStringAndCoTaskMemFree();
            }
        }
    }
 
    private unsafe bool RunDialogOld(HWND owner)
    {
        uint mergedOptions = PInvoke.BIF_NEWDIALOGSTYLE;
        if (!ShowNewFolderButton)
        {
            mergedOptions |= PInvoke.BIF_NONEWFOLDERBUTTON;
        }
 
        // The SHBrowserForFolder dialog is OLE/COM based, and documented as only being safe to use under the STA
        // threading model if the BIF_NEWDIALOGSTYLE flag has been requested (which we always do in mergedOptions
        // above). So make sure OLE is initialized, and throw an exception if caller attempts to invoke dialog
        // under the MTA threading model (...dialog does appear under MTA, but is totally non-functional).
        if (Control.CheckForIllegalCrossThreadCalls && Application.OleRequired() != ApartmentState.STA)
        {
            throw new ThreadStateException(string.Format(SR.DebuggingExceptionOnly, SR.ThreadMustBeSTA));
        }
 
        GCHandle handle = GCHandle.Alloc(this);
 
        try
        {
            string? folder = FolderBrowserHelper.BrowseForFolder(
                _descriptionText,
                (int)_rootFolder,
                mergedOptions,
                owner,
                &FolderBrowserDialog_BrowseCallbackProc,
                GCHandle.ToIntPtr(handle));
 
            if (folder is not null)
            {
                SelectedPath = folder;
                return true;
            }
            else
            {
                SelectedPath = string.Empty;
                return false;
            }
        }
        finally
        {
            handle.Free();
        }
    }
 
    /// <summary>
    ///  Callback function used to enable/disable the OK button, and select the initial folder.
    /// </summary>
#pragma warning disable CS3016 // Arrays as attribute arguments is not CLS-compliant
    [UnmanagedCallersOnly(CallConvs = [typeof(CallConvStdcall)])]
#pragma warning restore CS3016
    private static unsafe int FolderBrowserDialog_BrowseCallbackProc(HWND hwnd, uint msg, LPARAM lParam, LPARAM lpData)
    {
        switch (msg)
        {
            case PInvoke.BFFM_INITIALIZED:
                // Indicates the browse dialog box has finished initializing. The lpData value is zero.
                var instance = (FolderBrowserDialog)GCHandle.FromIntPtr(lpData).Target!;
                if (instance._initialDirectory.Length != 0)
                {
                    // Try to expand the folder specified by initialDir
                    PInvokeCore.SendMessage(hwnd, PInvoke.BFFM_SETEXPANDED, (WPARAM)(BOOL)true, instance._initialDirectory);
                }
 
                if (instance.SelectedPath.Length != 0)
                {
                    // Try to select the folder specified by selectedPath
                    PInvokeCore.SendMessage(hwnd, PInvoke.BFFM_SETSELECTIONW, (WPARAM)(BOOL)true, instance.SelectedPath);
                }
 
                break;
            case PInvoke.BFFM_SELCHANGED:
                // Indicates the selection has changed. The lpData parameter points to the item identifier list for the newly selected item.
                ITEMIDLIST* selectedPidl = (ITEMIDLIST*)lParam;
                if (selectedPidl is not null)
                {
                    // Try to retrieve the path from the IDList
                    using BufferScope<char> buffer = new(stackalloc char[(int)PInvokeCore.MAX_PATH + 1]);
                    fixed (char* b = buffer)
                    {
                        bool isFileSystemFolder = PInvoke.SHGetPathFromIDListEx(selectedPidl, b, (uint)buffer.Length, GPFIDL_FLAGS.GPFIDL_UNCPRINTER);
                        PInvokeCore.SendMessage(hwnd, PInvoke.BFFM_ENABLEOK, 0, (nint)(BOOL)isFileSystemFolder);
                    }
                }
 
                break;
        }
 
        return 0;
    }
}