Adding Wizards to the Add Item and New Project Dialog Boxes by Using .Vsdir Files

  • Article

A VSDir file is a text file with a .vsdir extension that you create to provide information about how to display its items to the Add Item and New Project dialog boxes. The information includes the names of items, the order in which they appear, and the icon displayed with them. You can change any of these items. VSDir files are used to add new templates or wizards to the Add Item and New Project dialog boxes.

There is no default VSDir file. If one is present, then Visual Studio reads it and adds its contents to the dialog boxes. If one is not present, then the default templates and wizards display. You can have multiple VSDir files in a single directory and all of their contents will be added to the dialog boxes. Typically, a single VSDir file contains records for multiple wizards, folders, and templates. Each record in the file is separated by a newline character. Pipe (|) characters separate the fields in each record. Any optional field for which there is no meaningful data contains a zero (0) or a space as a placeholder. Strings entered into fields do not require quotation marks around them.

VSDir File Components

Following are examples VSDir files. The first one references a single wizard, one that was created in the topic Walkthrough: Creating a Wizard:

MyNewWizard.vsz| |A New Wizard|1|My New Wizard|C:\Addins\MyNewWizard\MyNewWizard\bin\Debug| | |MyNewWizard99

The next example VSDir file references a number of wizard .vsz files, along with other pertinent information relating to each wizard (as outlined later in this topic). These are different from the previous VSDir file in that they reference strings as resource ID numbers, not literal strings. Also, they use GUIDs to reference DLLs.

..\..\Projects\csharp building blocks\BusinessFacade.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|#5015|10|#5022|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|127|0|Project
..\..\Projects\csharp building blocks\BusinessRules.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|#5016|20|#5023|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|128|0|Project
..\..\Projects\csharp building blocks\DataAccess.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|#5017|30|#5024|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|129|0|Project
..\..\Projects\csharp building blocks\SystemFrameworks.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|#5018|40|#5025|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|130|0|Project
..\..\Projects\csharp building blocks\WebService.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|#5019|50|#5026|{FAE04EC1-301F-11d3-BF4B-00C04F79EFBC}|4547|1|WebService|Web
..\..\Projects\csharp building blocks\WebUI.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|#5020|60|#5027|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|131|1|WebUI|web
..\..\Projects\csharp building blocks\WinUI.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|#5021|70|#5028|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|132|0|Project

The following fields can be specified for each record in a VSDir file:

Field

Meaning

RelPathName

Required. The name of the wizard's .vsz file, such as MyWizard.vsz, relative to the Visual Studio install directory.

{clsidPackage}

Optional. A GUID representing a product (such as Visual C+) that has a DLL containing localized resources. Normally, this field is blank for VSDir files that correspond with third-party wizards.

LocalizedName

Optional. This is the localizable name of the wizard or template and the name that appears in the Add Item dialog box. This can be a string or a resource identifier of the form #ResID.

SortPriority

Required. An integer representing the sort order and relative priority of the wizard, with 1 being highest. For instance, if this item is "1," then this will appear next to other 1s and ahead of all 2s or lower.

Description

Required. A localizable description of the template or wizard as it will appear in the Add Item dialog box when the item is selected. This can be a string or a resource identifier of the form #ResID. It applies only to template files, not folders.

DLLPath or {clsidPackage}

Required. Specifies a full path to a DLL or EXE file, or a GUID of a product that has a .dll file that contains an icon to load for the wizard. The icon is loaded as a resource out of a DLL/EXE file by using the given IconResourceId. This setting overrides {clsidPackage}, if specified, for icon location. It applies only to template files, not folders.

IconResourceId

Optional. A resource identifier within the DLL file that determines the icon to display. If no icon is defined, the environment substitutes the default icon for a file with the same extension as the item. It applies only to template files, not folders.

Flags

Optional. See Flags description and table below. It applies only to template files, not folders.

SuggestedBaseName

Required. The default name for the wizard, displayed in the Name field in the dialog box. This is either a string or a resource identifier of the form #ResID. If the name is not unique, the environment appends the name with an integer. For example, MyFile.aspx might be changed to MyFile1.aspx. If no name is provided, then "Project" is used. It applies only to template files, not folders.

  • Notes
    Any non-required field for which there is no meaningful data should contain a 0 (zero) as a placeholder.

    If no localized name is provided, the relative path is used.

    If no icon is defined, the IDE substitutes the default icon for a file with that extension.

    If no suggested base name is provided, "Project" is used.

  • Flags
    A group of bitwise flags used to enable or disable the Name and Location fields on the Add Item dialog box. That is, when the user selects Add New Item from the Add menu, the project determines whether the name and location are displayed in the Templates pane, but the flags determine if the name and location are available to the user.

    Set the value of Flags to the sum of the individual values. That is, 33 is equivalent to VSDIRFLAG_NonLocalTemplate | VSDIRITEM_DisableLocationField.

    Flag name

    Decimal value

    Description

    VSDIRFLAG_NonLocalTemplate

    1

    Use non-local user interface behavior and save mechanisms.

    VSDIRFLAG_BlankSolution

    2

    Create a blank (empty) solution. Do not create a project.

    VSDIRFLAG_DisableBrowseButton

    4

    Disable the Browse button for this project or item.

    VSDIRFLAG_DontAddDefExtension

    8

    Do not append a default extension to the name provided for the item. (This setting is not valid for projects.)

    VSDIRFLAG_DisableLocationField

    32

    Disable the location field for this project or item.

    VSDIRFLAG_DontInitNameField

    4096

    Do not initialize the name field for this project or item with a valid name.

    VSDIRFLAG_DisableNameField

    8192

    Disable the name field for this project or item.

See Also

Tasks

How to: Create an Add-In

Walkthrough: Creating a Wizard

Concepts

Designing a Wizard

Configuring .Vsz Files to Start Wizards

Other Resources

Creating Add-ins and Wizards