Walkthrough: Adding a Command to the Solution Explorer Toolbar (C#)

This walkthrough shows how to add a button to the Visual Studio Solution Explorer toolbar.

Any command, whether on a toolbar or on a menu, is considered a button by Visual Studio. When the button is clicked, the code in the command handler is executed. Typically, related commands are grouped together to form one group. Menus or toolbars act as containers for groups. Priority determines the order in which individual commands in a group appear in the menu or on the toolbar. You can prevent a button from being displayed on the toolbar or the menu by controlling its visibility. A command that is listed in a <VisibilityConstraints> section of the .vsct file appears only in the associated context. The visibility cannot be applied to groups.

For more information about menus, toolbar commands, and .vsct files, see Commands, Menus, and Toolbars.

Prerequisites

To follow this walkthrough, you must install the Visual Studio SDK.

Locations for the Visual Studio Package Project Template

The Visual Studio Package project template is available in three locations in the New Project dialog box:

• Under Visual Basic Extensibility. The default language of the project is Visual Basic.

• Under C# Extensibility. The default language of the project is C#.

• Under Other Project Types Extensibility. The default language of the project is C++.

Creating a VSPackage That Contains a Single Menu Command

This section of the walkthrough shows how to use the Visual Studio Package project template to create a VSPackage that supports a menu command.

To create the SolutionToolbar VSPackage

1. Create a VSPackage named SolutionToolbar. For more information, see Walkthrough: Creating a Menu Command By Using the Visual Studio Package Template.

2. Set the programming language to Visual C#, select Menu Command, set the command name to Toolbar ButtonTest Command, and set the command ID to cmdidTestCmd.

Adding a Button to the Solution Explorer Toolbar

This section of the walkthrough shows how to add a button to the Solution Explorer toolbar. When the button is clicked, the code in the callback method is run.

To add a button to the Solution Explorer toolbar

1. In Solution Explorer, double-click SolutionToolbar.vsct to open it in a text editor.

2. In the <Symbols> section, the <GuidSymbol> node whose name ends in "CmdSet" contains the menu group and command that was generated by the package template. Add an <IDSymbol> element to this node to declare the group that will hold your command.

   <IDSymbol name="SolutionToolbarGroup" value="0x0190"/>
   

3. In the <Groups> section, after the existing group entry, define the new group that you declared in the previous step.

   <Group guid="guidSolutionToolbarCmdSet"
          id="SolutionToolbarGroup" priority="0xF000">
     <Parent guid="guidSHLMainMenu" id="IDM_VS_TOOL_PROJWIN"/>
   </Group>
   

   Setting the parent guid:id pair to guidSHLMainMenu and IDM_VS_TOOL_PROJWIN puts this group on the Solution Explorer toolbar, and setting a high-priority value puts it after the other command groups.

4. In the <Buttons> section, change the parent ID of the generated <Button> entry to reflect the group that you defined in the previous step. The modified <Button> element should resemble the following markup.

   <Button guid="guidSolutionToolbarCmdSet" id="cmdidTestCmd" priority="0x0100" type="Button">
     <Parent guid="guidSolutionToolbarCmdSet" id="SolutionToolbarGroup" />
     <Icon guid="guidImages" id="bmpPic1" />
     <Strings>
       <CommandName>cmdidTestCmd</CommandName>
       <ButtonText>Toolbar Button Test Command</ButtonText>
     </Strings>
   </Button>
   

5. Build the solution and check for errors.

6. Press F5 to open the Visual Studio experimental build in a second window.

   The Solution Explorer toolbar should display the new command button to the right of the existing buttons. The button icon is the numeral 1 in a square.

7. Click the new button.

   A dialog box that has the message, "Inside Microsoft.SolutionToolbar.SolutionToolbarPackage.MenuItemCallback()" should be displayed.

Controlling the Visibility of a Button

This section of the walkthrough shows how to control the visibility of a button on a toolbar. By setting a context to one or more projects in the <VisibilityConstraints> section of the SolutionToolbar.vsct file, you restrict a button to appear only when a project or projects are open.

To display a button when one or more projects are open

1. If you have not already closed the Visual Studio experimental build, close it now.

2. In the <Buttons> section of SolutionToolbar.vsct, add two command flags to the existing <Button> element, between the <Strings> and <Icons> tags.

   <CommandFlag>DefaultInvisible</CommandFlag>
   <CommandFlag>DynamicVisibility</CommandFlag>
   

   The DefaultInvisible and DynamicVisibility flags must be set so that entries in the <VisibilityConstraints> section can take effect.

3. Create a <VisibilityConstraints> section that has two <VisibilityItem> entries. Put the new section just after the closing </Commands> tag.

   <VisibilityConstraints>
     <VisibilityItem guid="guidSolutionToolbarCmdSet"
           id="cmdidTestCmd"
           context="UICONTEXT_SolutionHasSingleProject" />
     <VisibilityItem guid="guidSolutionToolbarCmdSet"
           id="cmdidTestCmd"
           context="UICONTEXT_SolutionHasMultipleProjects" />
   </VisibilityConstraints>
   

   Each visibility item represents a condition under which the specified button is displayed. To apply multiple conditions, you must create multiple entries for the same button.

4. On the Build menu, click Rebuild Solution. You must rebuild the solution to see the menu change.

5. Press F5 to open the Visual Studio experimental build.

   The Solution Explorer toolbar does not contain the button that has the numeral 1.

6. Open any solution that contains a project or multiple projects.

   The button that has the numeral 1 appears on the toolbar to the right of the existing buttons.

7. On the File menu, click Close Solution. The button disappears from the toolbar.

The visibility of the button is controlled by Visual Studio until the VSPackage is loaded. After the VSPackage is loaded, the visibility of the button is controlled by the VSPackage. For more information, see How to: Create and Handle Commands in VSPackages (C#).

See Also

Other Resources

Commands, Menus, and Toolbars

Walkthroughs for Commands, Menus, and Toolbars