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 a single 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 Menus and Toolbars.

Prerequisites

This walkthrough requires installation of the Visual Studio SDK. When you perform certain steps in this walkthrough, information is written to the experimental registry hive for Visual Studio.

Creating a VSPackage That Contains a Single Menu Command

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

To create the SolutionToolbar VSPackage

1. Create a VSPackage named SolutionToolbar. For more information, see How to: Create VSPackages (C# and Visual Basic).

2. In the Visual Studio Integration Package Wizard, 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 single button to the Solution Explorer toolbar. Then you click the button to execute the code that is contained in the callback method.

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 wizard. 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 places this group on the Solution Explorer toolbar, and setting a high priority value places 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:

   <Button guid="guidSolutionToolbarCmdSet" id="cmdidTestCmd"
           priority="0x0100" type="Button">
     <Parent guid="guidSolutionToolbarCmdSet"
             id="SolutionToolbarGroup" />
     <Icon guid="guidImages" id="bmpPic1" />
     <Strings>
       <CommandName>cmdidTestCmd</CommandName>
       <ButtonText>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.

   You should see a dialog box that has the message, "Inside Company.SolutionToolbar.SolutionToolbarPackage.MenuItemCallback()".

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 single project or multiple projects in the <VisibilityConstraints> section of the SolutionToolbar.vsct file, you restrict a button to appear either when a single project is open or when multiple projects are open.

To display a button when either a single project is open or multiple 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.

   <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.

   <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 Build Solution.

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.

   Note

   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.

See Also

Other Resources

Menus and Toolbars

Menu and Toolbar Command Walkthroughs