Command Objects

Every action that is possible to execute through the menus and toolbars in Visual Studio is generically referred to as a command. For example, pasting text into a window is a command, as is building a project, toggling a breakpoint, and closing a window.

For each command supported in the IDE, there is a corresponding Command object; the DTE.Commands collection holds all the valid Command object instances. Each command is keyed by a name that categorizes, describes, and uniquely identifies the command. The "paste" command, for instance, is available via the string key "Edit.Paste". If you wanted to retrieve the Command object mapping to the paste command, you would pull from the Commands collection using that string key:

Dim commands As Commands2 = DTE.Commands Dim cmd As Command = commands.Item("Edit.Paste")

You can query a command's name via its Name property:

' name would = "Edit.Paste" Dim name As String = cmd.Name

Table 10.14 contains the members declared on the Command interface.

Table 10.14. Command Members

Property	Description
Bindings	The keystrokes that can be used to invoke the command
Collection	The Commands collection that the Command object belongs to
DTE	A reference to the root-level DTE object
GUID	A GUID that identifies the command's group
ID	An integer that identifies the command within its group
IsAvailable	A Boolean flag that indicates whether the command is currently enabled
LocalizedName	The localized name of the command
Name	The name of the command

Method	Description
AddControl	Creates a control for the command that can be hosted in a command bar
Delete	Removes a named command that was previously added with the Commands.AddNamedCommand method

The list of all available commands is extremely long (nearly 3,000 total), and it is therefore impossible to cover every one of them here, or even a large portion of them. To get an idea, however, of the specific commands available, you can visit the dialog box used to customize the Visual Studio toolbars. If you select the Customize option from the View, Toolbars menu, and then click on the Commands tab, you can investigate all the various commands by category (see Figure 10.9). Another alternative would be to programmatically iterate the DTE.Commands collection and view them that way. In fact, in the following chapter, we use this as one scenario for showcasing add-in development.

Figure 10.9. Using the Customize dialog box to view commands.

So, although we can't cover all the commands, you can learn how to perform common tasks with the Command objects such as executing a command, checking on a command's current status, and even adding your own commands to the command library.

Executing a Command

Commands can be executed in two different ways. The DTE object has an ExecuteCommand method that you can use to trigger a command based on its name:

DTE.ExecuteCommand("Window.CloseDocumentWindow")

The Commands collection is also a vehicle for launching commands through its Raise method. Instead of using the command's name, the Raise method uses its GUID and ID to identify the command:

Dim commands As Commands2 = DTE.Commands Dim cmd As Command = commands.Item("Window.CloseDocumentWindow") Dim customIn, customOut As Object commands.Raise(cmd.Guid, cmd.ID, customin, customout)

Some commands accept arguments. The Shell command is one example. It is used to launch an external application into the shell environment and thus takes the application filename as one of its parameters. You can launch this command by using the ExecuteCommand method like this:

Dim commands As Commands2 = DTE.Commands Dim cmd As Command = commands.Item("Tools.Shell") Dim arg1 = "MyApp.exe " DTE.ExecuteCommand(cmd.Name, arg1)

The Raise method also works with arguments: The last two parameters provided to the Raise method are used to specify an array of arguments to be used by the command and an array of output values returned from the command.

Mapping Key Bindings

Most commands can be invoked by a keyboard shortcut in addition to a menu entry or button on a command bar. You can set these keyboard shortcuts on a per-command basis by using the Command.Bindings property. This property returns or accepts a SafeArray (essentially an array of objects) that contains each shortcut as an element of the array.

Key bindings are represented as strings with the following format:

"[scopename]::[modifier+][key]".

Scopename is used to refer to the scope where the shortcut is valid, such as Text Editor or Global. The modifier token is used to specify the key modifier such as "ctrl+", "alt+", or "shift+" (modifiers are not required). And the key is the keyboard key that will be pressed (in conjunction with the modifier if present) to invoke the command.

To add a binding to an existing command, you first need to retrieve the current array of binding values, add your binding string to the array, and then assign the whole array back into the Bindings property like this:

Dim commands As Commands2 = DTE.Commands Dim cmd As Command = _      commands.Item("File.SaveSelectedItems") Dim bindings() As Object bindings = cmd.Bindings ' Increase the array size by 1 to hold the new binding ReDim Preserve bindings(bindings.GetUpperBound(0) + 1) ' Assign the new binding into the array bindings(bindings.GetUpperBound(0)) = "Global::Shift+F2" ' Assign the array back to the command object cmd.Bindings = bindings

Note

You can create your own named commands that can be launched from a command bar in the IDE (or from the command window for that matter). The Command object itself is added to the Commands collection by calling Commands.AddNamedCommand. The code that will run when the command is executed will have to be implemented by an add-in. We'll cover this scenario in Chapter 11.