Introduction to Menu and Toolbar Commands
When you develop a VSPackage, you typically include user interface (UI) elements that make your commands available on menus or toolbars in the Visual Studio 2008 integrated development environment (IDE).
Menu and Toolbar Command Overview
When you create commands for a VSPackage, you define the new commands and write command handlers for them to respond to the events.
Defining Commands
To define new menu and toolbar commands:
Write a Command Table (.vsct) file. For more information, see XML-Based Command Table Configuration (.vsct) Files.
Compile the .vsct file to produce a binary .cto resource file.
Include the resulting resource file in your project.
Each time the user runs devenv.exe /setup the IDE customizes its interface by merging all of the command-set resources it finds when it examines the target experimental registry. After this merge, all the commands that all the VSPackages have in common are displayed in the IDE. Because command sets are defined outside of the VSPackage implementation code, the IDE can produce a union of all command sets without having to load each VSPackage. For more information, see How VSPackages Add User Interface Elements.
Visual Studio SDK defines a set of registration attributes that uses Visual C# reflection to register command sets (as well as other registry-defined resources) with the IDE. For more information, see Managed VSPackage Registration Keys.
In the Visual Studio SDK, .cto files may still reside in native satellite UI DLLs, but they may also be located as a resource in managed satellite DLLs or in managed VSPackages. For more information, see Resources in Managed VSPackages.
As the user interacts with the IDE, each command potentially should be hidden or shown, enabled or disabled, have its label text customized, or even have its values populated. Values are added, for example, in the cases of menu elements such as combo boxes, dynamic menus, or pickers. A great deal of customization may be automatically performed without ever loading and running your VSPackage code. For more information, see How VSPackages Add User Interface Elements.
Handlers for Commands
Each new command that you author also needs appropriate event handler code. If the user selects a command, the command should be appropriately routed. For more information, see Command Routing in VSPackages.
Routing a command means sending it to the correct VSPackage to enable or disable it, and hide or display it, and then execute it if the user chooses to do so. Selection is a similar notion. An example of this is when the selection of a node in a hierarchical view causes a properties grid in another window to be populated. The IDE manages the population of the properties grid, but there are some caveats with respect to performance. For information, see Selection Context Objects.
The Visual Studio Command Environment
Visual Studio 2008 implements its command interface of menus, context menus, and toolbars using the Visual Studio 2008 command bar architecture. Visual Studio 2008 can host between zero and an indefinite number of VSPackages, each contributing its own complex, full command set. The IDE displays only the commands that are most relevant to the current task. For more information, see How Command Context Affects Available Menu Items and Selection Context Objects.
A VSPackage that defines new commands, menus, toolbars, or context menus provides its command information to the IDE at installation time through registry entries that reference resources in native DLLs or managed assemblies. These resources in turn each reference a binary data resource (.cto) file, which is produced by compiling a Command Table (.vsct) file. This allows the IDE to provide completely merged command sets, menus, and toolbars without having to load every installed VSPackage.
Command Organization
The IDE positions commands in three ways: groups, priority, and menus.
Groups are logical collections of related commands, such as the Cut, Copy, and Paste command group. Groups are the commands that appear on menus.
Priority determines the order in which individual commands within a group appear in the menu.
Menus act as containers for groups.
The IDE predefines some common commands, groups, and menus for ease of use. For more information, see Default Commands, Groups, and Toolbars.
A command can be assigned to a primary group. The primary group controls the command's position in the main menu structure and in the Customize dialog box. A command can be in multiple groups; for example, a command can be on the main menu, on a context menu, and on a toolbar. For more information, see How VSPackages Add User Interface Elements.
Command Routing
The process of invoking and routing commands for VSPackages differs from that of calling methods on object instances.
The IDE routes commands sequentially from the innermost command context, based on current selection (local), to the outermost (global). The first context that is able to execute the command is the one that handles it. See Command Routing in VSPackages for more information.
In most instances, the IDE handles commands using the IOleCommandTarget interface. Because the command routing scheme makes it possible for many different objects to handle commands, IOleCommandTarget can be implemented by any number of objects, including Microsoft ActiveX controls, window view implementations, document objects, project hierarchies, and VSPackage objects themselves for global commands. In some specialized cases, such as routing commands in a hierarchy, the IVsHierarchy interface must be implemented.
See Also
Concepts
How VSPackages Add User Interface Elements