System.Shell.chooseFile method

[ The Windows Gadget Platform/Sidebar is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. ]

Displays a file picker dialog box and retrieves a System.Shell.Item object that represents the selected file.


objRetVal = System.Shell.chooseFile(


bForOpen [in]

Boolean that specifies the type of file picker dialog box to display.




Save As.

strFilter [in]

String that specifies file descriptions and extensions. This string is in the format "Description:*.Extension:Description:*.Extension::".

strInitialDirectory [in]

String that specifies the root directory.

Note  If an empty string is specified, the root directory is set to the users desktop (%USERPROFILE%\Desktop).
strFileInit [in]

String that specifies the file name.

Return value

A System.Shell.Item that represents the selected file.


strFilter requires the double-colon terminator as the filter string must be terminated by two NULL characters.

The first string in each pair is a display string that describes the filter (for example, Text Files), and the second string specifies the filter pattern (for example, *.TXT). To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns (for example, *.TXT;*.DOC;*.BAK). A pattern string can be a combination of valid file name characters and the asterisk (*) wildcard character. Do not include spaces in the pattern string.

The system displays the filters in the order specified by strFilter in the File Types combo box.

If strFilter is an empty string, the dialog box does not display any filters.

The chooseFile Open dialog box:

File picker 'Open' dialog box.

The chooseFile Save As dialog box:

File picker 'Save As' dialog box.


The following example demonstrates how to specify .txt and .reg files for the file picker dialog box.

// Create a shell item object.
var oShellItem = System.Shell.chooseFile(true, "Text File:*.txt:Reg File:*.reg::", "C:\\", "");


Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

End of client support

Windows 7

End of server support

Windows Server 2008




Sidebar.Exe (version 1.00 or later)



Community Additions