The Visual Studio Automation Object Model

Chapter 10. The Visual Studio Automation Object Model

IN THIS CHAPTER

Visual Studio is built to be "extensible." It ships with its own API to enable you, the developer, to control many of the pieces of the IDE.

The API is called the Visual Studio automation object model, and understanding its capabilities is the key to unlocking your ability to program and control the IDE itself by writing code in the form of macros and add-ins (discussed in Chapter 11, "Writing Macros, Add-Ins, and Wizards").

In this chapter, we discuss the layout and structure of the automation object model. We map the various objects in the object model to their IDE counterparts, delve into the various ways to interact with these objects through managed code, and, we hope, start to see a glimpse of the possibilities in terms of Visual Studio customization.

To drive home the object model concepts and place them in context, we have provided various code snippets and listings, nearly 100% of which are written in Visual Basic. The reason is that Visual Basic is the language of macros (other languages are not supported), and macros are by far the easiest and quickest way to reach out and touch elements of the IDE. As such, macros are a perfect vehicle for exploring and understanding the object model. In Chapter 11, we'll move beyond the object model and work to understand how to use, write, and run macros and add-ins (add-ins don't suffer from the Visual Basic limitation, so we'll switch gears and provide a majority of our add-in code using C#).

Don't worry too much about the mechanics of writing an add-in or macro at this point; concentrate instead on understanding the automation objects and how they are referenced and used. For the ambitious, know that the code listings here can be pasted directly into the Macros IDE Editor and run as is.

An Overview of the Automation Object Model

The automation object model is a structured class library with a top-level root object called DTE (or DTE2; more on this in a bit), which stands for Development Tools Environment. By referencing the assembly that implements the DTE/DTE2 object, you can instance this root object and use its members and child classes to access the IDE components.

Object Model Versions

The automation object model is actually implemented across two different, complementary primary interoperable assemblies: EnvDTE and EnvDTE80. EnvDTE is the original automation assembly distributed with previous versions of Visual Studio .NET. EnvDTE80 is a new library distributed with Visual Studio 2005. Visual Studio 2005 provides enhanced automation functionality. Because of this, Microsoft was faced with a common design decision: Replace or upgrade the current EnvDTE and risk introducing incompatibilities with current macros and add-ins, or ship a new assembly that could be leveraged in cases in which the new functionality was desired (existing code would still target the previous, unchanged library).

The latter path was chosen, and thus EnvDTE80 (80 represents version 8.0) represents the latest automation functions, while EnvDTE provides the base level of functionality and backward compatibility.

Within the EnvDTE80 assembly, you will find types that supersede their predecessors from the EnvDTE assembly. In these cases, the type name has been appended with a 2 to indicate the revised version. Thus, we have DTE and DTE2, Solution and Solution2, and so on.

Table 10.1 provides a side-by-side listing of some of the most important types implemented in EnvDTE and EnvDTE80. This type list is incomplete; it should be considered for reference only. This table is useful, however, for identifying some of the newly minted types in the new automation assembly; in the next section, we'll see how these types can be organized into broad Visual Studio automation categories and how they map onto physical IDE constructs.

Table 10.1. `EnvDTE` and `EnvDTE80` Types
`EnvDTE` Type	`EnvDTE80` Type	Description
`AddIn`		Represents a VS add-in.
`Breakpoint`	`Breakpoint2`	Returns the debugger object.
`BuildDependencies`		For the selected project, represents a collection of `BuildDependency` objects.
`BuildDependency`		For the selected project, represents the projects that it depends on for a successful build.
`BuildEvents`		Exposes a list of events relevant to a solution build.
`Command`		Represents a command action in the IDE.
`Commands`	`Commands2`	Returns a collection of all commands supported in the IDE.
`CommandWindow`		Represents the command window.
`Configuration`		Represents a project's configuration properties.
`Debugger`	`Debugger2`	Represents the Visual Studio debugger.
`DebuggerEvents`		Exposes events from the debugger.
`Document`		Represents an open document in the IDE.
`Documents`		Returns a collection of all open documents in the IDE.
`DTE`	`DTE2`	Represents the IDE; this is the top-level root object for the automation object model.
`EditPoint`	`EditPoint2`	Represents a text operation point within a document.
`Events`	`Events2`	Exposes all automation events.
`Find`	`Find2`	Represents the Find capability for text searches in the IDE.
`HTMLWindow`		Represents an HTML window.
`OutputWindow`		Represents the output window.
`Program`	(`Process2`)	Represents a program running within the IDE; useful for examining processes and threads within the program. `EnvDTE80` functionality is provided by the `Process2` object.
`Project`		Represents a project loaded in the IDE.
`ProjectItem`		Represents an item contained within a given project.
`ProjectItems`		Returns a collection of all items contained within a project.
`Property`		Represents a generic property for an object (this can be used across a variety of objects in the automation library).
`SelectedItem`		Represents projects or project items that are currently selected in the IDE.
`Solution`	`Solution2`	Represents the solution currently loaded in Visual Studio.
`SourceControl`	`SourceControl2`	Represents the source control system of record within Visual Studio.
`TaskItem`		Represents an item in the task list window.
`TaskItems`	`TaskItems2`	Returns a collection of all items in the task list window.
`TaskList`		Represents the task list window.
`TexTDocument`		Represents a text file open in the IDE.
`TextPane`	`TextPane2`	Represents a pane within an open text editor window.
`TextWindow`		Represents a text window.
`ToolBox`		Represents the Toolbox window.
`ToolBoxItem`	`ToolBoxItem2`	Represents an item within the Toolbox window.
`ToolBoxTab`	`ToolBoxTab2`	Represents a tab of items on the Toolbox window.
`Window`	`Window2`	Represents, generically, any window within the IDE.
`Windows`	`Windows2`	Returns a collection of all windows within the IDE.

Automation Categories

Because any automation effort with Visual Studio starts with the object model, you should understand first how it maps onto the IDE constructs and determine the exact capabilities that it exposes.

In general, you can think of the object model classes as being organized into categories that directly speak to these IDE concepts:

Solutions and projects
Windows and command bars (toolbars and menu bars)
Documents
Commands
Debugger
Events

Each of the objects in these categories touches a different piece of the IDE, and access to each object is always through the root-level DTE2 object.

The `DTE`/`DTE2` Root Object

The DTE/DTE2 object represents the tip of the API tree. You can think of it as representing Visual Studio itself, with the objects under it mapping to the various constituent parts of the IDE.

As mentioned previously, DTE2 is the object used with Visual Studio 2005, with DTE providing compatibility with previous versions. In this chapter, unless we specifically need to differentiate between their capabilities, we will generically refer to the DTE and DTE2 objects as simply DTE.

The DTE properties are used to gain a reference to a specific IDE object (or collection of objects). Methods on the object are used to execute commands in the IDE, launch wizards, or close the IDE.

Table 10.2 shows the major properties and methods defined on the DTE2 object; they have been organized within the six object categories itemized in the preceding section.

Table 10.2. `DTE2` Properties and Methods for IDE Access
Category	Property	Description
Commands	`Commands`	Returns a collection of `Command` objects; in general, a command is an action that can be carried out within the IDE such as opening or saving a file.
Debugger	`Debugger`	Returns the debugger object.
Documents	`ActiveDocument`	Returns a `Document` object representing the currently active document.
Documents	`Documents`	Returns a collection of `Document` objects representing all open documents.
Event Notification	`Events`	Returns the `Events` object for handling event notifications.
Solutions and Projects	`ActiveSolutionProjects`	Returns a collection of the `Project` objects representing the projects that are currently selected within the Solution Explorer.
Solutions and Projects	`Solution`	Returns the `Solution` object for the currently loaded solution.
Windows and Command Bars	`ActiveWindow`	Returns a `Window` object representing the window within the IDE that currently has focus.
Windows and Command Bars	`CommandBars`	Returns a collection of `CommandBar` objects representing all the toolbars and menu bars.
Windows and Command Bars	`MainWindow`	Returns a `Window` object representing the IDE window itself.
Windows and Command Bars	`StatusBar`	Returns a `StatusBar` object representing Visual Studio's status bar.
Windows and Command Bars	`ToolWindows`	Returns a `ToolWindows` instance, which in turns provides access to a few of the most prominent tool windows: the command window, error list, output window, Solution Explorer, task list, and Toolbox.
Windows and Command Bars	`WindowConfigurations`	Returns a collection of `WindowConfiguration` objects; these objects represent the various window layouts in use by Visual Studio.
Commands	`ExecuteCommand`	Executes an environment command.
--	`LaunchWizard`	Starts the identified wizard with the given parameters.
--	`Quit`	Closes Visual Studio.

Note

The mechanics of referencing and instancing a DTE object change slightly depending on whether you are writing an add-in or a macro, so we'll cover the specifics in the macro and add-in sections in Chapter 11.

In summary, the DTE object is a tool for directly interacting with certain IDE components and providing access to the deeper layers of the API with its property collections. If you move one level down in the API, you find the major objects that form the keystone for automation.

`Solution` and `Project` Objects

The Solution object represents the currently loaded solution. The individual projects within the solution are available via Project objects returned within the Solution.Projects collection. Items within a project are accessed in a similar fashion through the Project.ProjectItems collection.

As you can see from Figure 10.1, this hierarchy exactly mirrors the solution/project hierarchy that we first discussed in Chapter 4, "Solutions and Projects."

Figure 10.1. Mapping the solution/project hierarchy.

[View full size image]

There are some mismatches heresolution folders, for instance, are treated as projectsbut for the most part, the object model tree closely resembles the solution project tree that you are used to.

The Solution object and Solution2 object members allow you to interact with the current solution to perform common tasks such as

Determining the number of projects in the solution (Count property)
Adding a project to the solution based on a project file (AddFromFile method)
Creating a new solution or closing the current one (Create and Close methods)
Saving the solution (SaveAs method)
Removing a project from the solution (Remove method)

You can also directly retrieve a reference to any of the projects within the currently loaded solution by iterating over the Solution.Projects collection. As an example of interacting with the Solution and Project objects, this Visual Basic code snippet removes the first project from the current solution:

Dim sol As Solution = DTE.Solution
Dim proj As Project = sol.Projects.Item(1)

If proj.Saved Then
             sol.Remove(proj)
Else
      ...
End If

Table 10.3 provides the combined list of the most commonly used properties and methods implemented by Solution2.

Table 10.3. Primary `Solution`/`Solution2` Object Members
Property	Description
`AddIns`	Returns a collection of `AddIn` objects associated with the current solution.
`Count`	Returns a count of the projects within the solution.
`DTE`	Provides a reference back to the parent `DTE` object.
`FullName`	Provides the full path and name of the solution file.
`IsOpen`	Indicates whether a solution is open.
`Projects`	Returns a collection of `Project` objects representing all the projects within the solution.
`Properties`	Returns a collection of `Property` objects that expose all the solution's properties.
`Saved`	Indicates whether the solution has been saved since the last modification.
`SolutionBuild`	Returns a reference to a `SolutionBuild` object. This is the entry point to the build automation objects applicable for the current solution.

Method	Description
`AddFromFile`	Adds a project to the solution using an existing project file.
`AddFromTemplate`	Takes an existing project, clones it, and adds it to the solution.
`AddSolutionFolder`	Creates a new solution folder in the solution.
`Close`	Closes the solution.
`Create`	Creates an empty solution.
`FindProjectItem`	Initiates a search for a given item in one of the solution's projects.
`Item`	Returns a `Project` instance.
`Open`	Opens a solution (using a specific view).
`Remove`	Removes a project from the solution.
`SaveAs`	Saves the solution.

Controlling Projects in a Solution

One of the things that the Solution object is good for is retrieving references to the various projects that belong to the solution. Each Project object has its own set of useful members for interacting with the projects and their items. By using these members, you can interact with the projects in various, expected ways, such as renaming a project, deleting a project, and saving a project.

See Table 10.4 for a summary of the most common Project members.

Table 10.4. Primary `Project` Object Members
Property	Description
`AddIns`	Returns a collection of `AddIn` objects associated with the current solution.
`Count`	Returns a count of the project within the solution.
`DTE`	Provides a reference back to the parent `DTE` object.
`FullName`	Provides the full path and name of the solution file.
`IsOpen`	Indicates whether a solution is open.
`Projects`	Returns a collection of `Project` objects representing all the projects within the solution.
`Properties`	Returns a collection of `Property` objects that expose all the solution's properties.
`Saved`	Indicates whether the solution has been saved since the last modification.
`SolutionBuild`	Returns a reference to a `SolutionBuild` object. This is the entry point to the build automation objects applicable for the current solution.

Method	Description
`AddFromFile`	Adds a project to the solution using an existing project file.
`AddFromTemplate`	Takes an existing project, clones it, and adds it to the solution.
`AddSolutionFolder`	Creates a new solution folder in the solution.
`Close`	Closes the solution.
`Create`	Creates an empty solution.
`FindProjectItem`	Initiates a search for a given item in one of the solution's projects.
`Item`	Returns a `Project` instance.

=350>

Property	Description
`Open`	Opens a solution (using a specific view).
`Remove`	Removes a project from the solution.
`SaveAs`	Saves the solution.

Accessing Code Within a Project

Beyond the basic project attributes and items, one of the cooler things that can be accessed via a Project instance is the actual code within the project's source files. Through the CodeModel property, you can access an entire line of proxy objects representing the code constructs within a project. For instance, the CodeClass interface allows you to examine and edit the code for a given class in a given project.

Note

Support for the different CodeModel entities varies from language to language. The MSDN documentation for each CodeModel type clearly indicates the source language support for that element.

After grabbing a CodeModel reference from a Project instance, you can access its CodeElements collection (which is, not surprisingly, a collection of CodeElement objects). A CodeElement is nothing more than a generic representation of a certain code structure within a project. The CodeElement object is generic, but it provides a property, Kind. This property is used to determine the exact native type of the code object contained within the CodeElement.

The CodeElement.Kind property is an enumeration (of type vsCMElement) that identifies the specific type of code construct lurking within the CodeElement object. Using the Kind property, you can first determine the true nature of the code element and then cast the CodeElement object to its strong type. Here is a snippet of C# code that does just that:

if (element.Kind == vsCMElement.vsCMElementClass)
            CodeClass myClass = (CodeClass)element;

For a better grasp of the code model hierarchy, consider the C# code presented in Listing 10.1; this is a "shell" solution that merely implements a namespace, a class within that namespace, and a function within the class.

Listing 10.1. A Simple Namespace and Class Implementation

using System;
using System.Collections.Generic;
using System.Text;

namespace MyNamespace
{
   class MyClass
   {
       public string SumInt(int x, int y)
       {
           return x + y;
       }
   }
}

If you map the code in Listing 10.1 to the code object model, you would end up with the structure you see in Figure 10.2.

Figure 10.2. Simple code model object hierarchy.

[View full size image]

To get an idea of the complete depth of the code model tree that can be accessed through the CodeElements collection, consult Table 10.5; this table shows all the possible vsCMElement values, the type they are used to represent, and a brief description of the type.

=200> =150> =150>

Table 10.5. Mapping the `vsCMElement` Enumeration Values
Enumeration Value	Type	Description
`vsCMElementAssignmentStmt`		An assignment statement
`vsCMElementAttribute`		An attribute
`vsCMElementClass`	`CodeClass`	A class
`vsCMElementDeclareDecl`		A declaration
`vsCMElementDefineStmt`		A define statement
`vsCMElementDelegate`	`CodeDelegate`	A delegate
`vsCMElementEnum`	`CodeEnum`	An enumeration
`vsCMElementEvent`	`CodeEvent`	An event
`vsCMElementEventsDeclaration`		An event declaration
`vsCMElementFunction`	`CodeFunction`	A function
`vsCMElementFunctionInvokeStmt`		A statement invoking a function
`vsCMElementIDLCoClass`		An IDL co-class
`vsCMElementIDLImport`		An IDL import statement
`vsCMElementIDLImportLib`		An IDL import library
`vsCMElementIDLLibrary`		An IDL library
`vsCMElementImplementsStmt`		An implements statement
`vsCMElementImportStmt`	`CodeImport`	An import statement
`vsCMElementIncludeStmt`		An include statement
`vsCMElementInheritsStmt`		An inherits statement
`vsCMElementInterface`	`CodeInterface`	An interface
`vsCMElementLocalDeclStmt`		A local declaration statement
`vsCMElementMacro`		A macro
`vsCMElementMap`		A map
`vsCMElementMapEntry`		A map entry
`vsCMElementModule`		A module
`vsCMElementNamespace`	`CodeNamespace`	A namespace
`vsCMElementOptionStmt`		An option statement
`vsCMElementOther`	`CodeElement`	A code element not otherwise identified in this enum
`vsCMElementParameter`	`CodeParameter`	A parameter
`vsCMElementProperty`	`CodeProperty`	A property
`vsCMElementPropertySetStmt`		A property set statement
`vsCMElementStruct`	`CodeStruct`	A structure
`vsCMElementTypeDef`		A type definition
`vsCMElementUDTDecl`		A user-defined type
`vsCMElementUnion`		A union
`vsCMElementUsingStmt`	`CodeImport`	A using statement
`vsCMElementVariable`		A variable
`vsCMElementVBAttributeGroup`		A Visual Basic attribute group
`vsCMElementVBAttributeStmt`		A Visual Basic attribute statement
`vsCMElementVCBase`		A Visual C++ base

Windows

The visible, content portion of Visual Studio is represented by Window objects. Window objects are instances of open windows within the IDE such as the Solution Explorer, the task list window, an open code editor window, and so on. Even the IDE itself is represented by a Window object.

Any given window is either a document window or a tool window. Document windows host documents that are editable by the Text Editor. Tool windows contain controls that display information relevant to the current context of the IDE; the Solution Explorer and task list windows are examples of tool windows, and a VB source code file open in an editor is an example of a document window.

Referencing Windows

If you need to retrieve an instance of a specific window, you have a few different options, each optimal for a given situation. For starters, the main IDE window is always available directly from the DTE object:

Dim IDE As Window
IDE = DTE.MainWindow

Obviously, if you need to perform a specific action against the IDE window, this is your quickest route.

The DTE.ActiveWindow property also provides direct and quick access to a Window object, in this case the currently active window:

Dim CurrentWindow As Window
CurrentWindow = DTE.ActiveWindow

The tool windows within the IDEthat is, the command window, the error list window, the output window, the Solution Explorer, the task list window, and the Toolboxalso have a direct way to retrieve their object model instances: You use the DTE.ToolWindows property. This property returns a ToolWindows object that exposes a separate property for each of the tool windows.

This Visual Basic code grabs a reference to the task list window and closes it:

Dim taskwin As Window

taskwin = DTE.ToolWindows.TaskList
taskwin.Close()

And finally, the fourth way to access an IDE window is through the DTE.Windows collection; this collection holds an entry for each IDE window. You can access a window from the collection by using either an integer representing the window's position within the collection, or by providing an object or string that represents the window you are trying to retrieve.

The following code grabs a handle to the Solution Explorer window:

Dim windows As Windows2 = DTE.Windows
Dim window As Window = windows.Item(Constants.vsWindowKindSolutionExplorer)

Interacting with Windows

Table 10.6 itemizes the properties and methods available on each Window object.

=150> =350>

Table 10.6. `Window` Object Members
Property	Description
`AutoHides`	A Boolean flag indicating whether the window can be hidden (applies only to tool windows).
`Caption`	The title/caption of the window.
`Collection`	The `Windows` collection that the current `Window` object belongs to.
`CommandBars`	A `CommandBars` collection of the command bars implemented by the window.
`ContextAttributes`	A collection of `ContextAttribute` objects; they are used to associate the current context of the window with the Dynamic Help window.
`Document`	If the `Window` object is hosting a document, this returns a reference to the document.
`DTE`	A reference to the root `DTE` object.
`Height`	The height of the window in pixels.
`IsFloating`	A Boolean flag indicating whether the window is floating or docked.
`Left`	The distance, in pixels, between the window's left edge and its container's left edge.
`Linkable`	A Boolean flag indicating whether the window can be docked with other windows.
`LinkedWindowFrame`	Returns a reference to the `Window` object that is acting as the frame for a docked window.
`LinkedWindows`	A collection of `Window` objects representing the windows that are linked together within the same frame.
`Object`	Returns an object proxy that represents the window and can be referenced by name.
`ObjectKind`	A GUID indicating the type of the object returned from `Window.Object`.
`Project`	A `Project` instance representing the project containing the `Window` object.
`ProjectItem`	A `ProjectItem` instance representing the project item containing the `Window` object.
`Selection`	Returns an object representing the currently selected item in the window (for document windows, this might be text; for tool windows, this might be an item in a list, and so on).
`Top`	The distance, in pixels, between the window's top edge and its parent's top edge.
`Visible`	A Boolean flag indicating whether the window is visible or hidden.
`Width`	The width of the window in pixels.
`WindowState`	Gets or sets the current state of the window (via a `vsWindowState` enum value: `vsWindowStateMaximize`, `vsWindowStateMinimize`, `vsWindowStateNormal`).

=150> =350>

Method	Description
`Activate`	Gives the window focus.
`Close`	Closes the window; you can indicate, with a `vsSaveChanges` enum value, whether the window's hosted document should be saved or not saved, or whether the IDE should prompt the user to make that decision.
`SetSelectionContainer`	Passes an array of objects to the Properties window when the `Window` object has focus. This property is mainly used for custom tool windows where you need to control what is displayed in the Properties window.
`SetTabPicture`	Specifies an object to use as a tab image; this image is displayed whenever the window is part of a tab group within the IDE.

Beyond the basics (such as using the Height and Width properties to query or affect a window's dimensions, or setting focus to the window with the SetFocus method), a few properties deserve special mention:

The Document property gives you a way to programmatically interact with the document that the window is hosting (if any).
The Project and ProjectItem properties serve to bridge the Window portion of the API with the Project/Solution portion; in a similar vein as the Document property, you can use these properties to interact with the project that is related to the window, or the project item (such as the VB code file, text file, resource file, and so on).
If you are dealing with a tool window, the SetTabPicture method provides a way to set the tab icon that is displayed when the tool window is part of a group of tabbed windows (for instance, the Toolbox window displays a wrench and hammer picture on its tab when part of a tabbed group).
Again, specifically for tool windows only, the SetSelectionContainer can be used to supply one or more objects for display within the Properties window. This capability is useful if you have a custom window where you need to control what is displayed in the Properties window when the window has focus (all the standard VS windows already do this for you).

Listing 10.2 contains a simple macro illustrating the use of the Window object; in this example, each window is queried to determine its type, and then a summary of each window is output in a simple message box.

Listing 10.2. VB Macro for Querying the Windows Collection

Imports EnvDTE
Imports EnvDTE80
Imports System.Diagnostics
Imports System.Windows.Forms


Public Module MacroExamples

    Public Sub InventoryWindows()
        ' Get collection of all open windows
        Dim windows As Windows2 = DTE.Windows

        ' Count the nbr of open windows
        Dim windowCount As Integer = windows.Count

        ' Local vars for looping and holding window and string
        ' results
        Dim idx As Integer
        Dim results As String
        Dim window As Window2

        results = windowCount.ToString + " windows open..." + vbCrLf

        ' Iterate the collection of windows
        For idx = 1 To windowCount

            window = windows.Item(idx)
            Dim title As String = window.Caption

            ' If the window is hosting a document, a valid Document
            ' object will be returned through Window.Document
            If Not (window.Document Is Nothing) Then
                ' Write this out as a document window
                Dim docName As String = window.Document.Name
                results = results + "Window '" + title + "' is a document window"
                    + vbCrLf
            Else
                ' If no document was present, this is a tool window
                ' (tool windows don't host documents)
                results = results + "Window '" + title + "' is a tool window"
                    + vbCrLf
            End If
        Next

        ' Show the results
        MessageBox.Show(results, "Window Documents", MessageBoxButtons.OK, _
            MessageBoxIcon.Information)

    End Sub

End Module

Note

If you want to embed your own custom control inside a tool window, you have to write an add-in and use the Windows.CreateToolWindow method. We cover this scenario in Chapter 11.

Text Windows and Window Panes

Text windows have their own specific object abstraction in addition to the generic Window object: The TextWindow object is used to represent text editor windows. To obtain a reference to a window's TextWindow object, you retrieve the Window object's value and assign it into a TextWindow type:

Dim textWindow As TextWindow
textWindow = DTE.ActiveWindow.Object

The TextWindow object doesn't provide much functionality over and above the functionality found in the Window type; its real value is the access it provides to window panes.

Text editor windows in Visual Studio can be split into two panes; with a text editor open, simply select Split from the Window menu to create a new pane within the window. The TextWindow.ActivePane property returns a TextPane object representing the currently active pane in the window, and the TextWindow.Panes property provides access to all the panes within a text window:

' Get pane instance from collection
Dim newPane As TextPane2
newPane = textWindow.Panes.Item(1)

' Get currently active pane
Dim currPane As TextPane2
currPane = textWindow.ActivePane

One of the more useful things you can do with the TextPane object is to scroll the client area of the pane (for example, the visible portion of the document within the pane) so that a specific range of text is visible. This is done via the TextPane.TryToShow method.

Here is the definition for the method:

Function TryToShow(Point As TextPoint, Optional How As vsPaneShowHow, _
    PointOrCount As Object)

The TextPoint parameter represents the specific location within the text document that you want visible in the text pane (we discuss TextPoint objects in depth in a later section of this chapter; see "Editing Text Documents"). The vsPaneShowHow value specifies how the pane should behave when scrolling to the indicated location:

vsPaneShowHow.vsPaneShowCentered will cause the pane to center the text/text selection in the middle of the pane (horizontally and vertically).
vsPaneShowHow.vsPaneShowTop will place the text point at the top of the viewable region in the pane.
vsPaneShowHow.vsPaneShowAsIs will show the text point as is with no changes in horizontal or vertical orientation within the viewable region in the pane.

The last parameter, the PointOrCount object, is used to specify the end of the text area that you want displayed. If you provide an integer here, this represents a count of characters past the original text point; if you provide another text point, then the selection is considered to be that text that resides between the two text points.

The TextPane object is also used to access the Incremental Search feature for a specific window pane. Listing 10.3 shows an example of this feature in action.

Listing 10.3. Controlling Incremental Search

Imports EnvDTE
Imports EnvDTE80
Imports Microsoft.VisualStudio.CommandBars
Imports System.Diagnostics
Imports System.Windows.Forms


Public Module MacroExamples

    Public Sub IncrementalSearch()
        ' Grab references to the active window;
        ' we assume, for this example, that the window
        ' is a text window.
        Dim window As Window2 = DTE.ActiveWindow
        ' Grab a TextWindow instance that maps to our
        ' active window
        Dim txtWindow As TextWindow = window.Object

        ' Get the active pane from the text window
        Dim pane As TextPane2 = txtWindow.ActivePane

        'Using the active pane, get an IncrementalSearch object
        ' for the pane
        Dim search As IncrementalSearch = pane.IncrementalSearch

        ' Try to find our IMessageMapper interface by looking
        ' for the string "IM"
        ' Configure the search:
        '   search forward in the document
        '   append the chars that we are searching for
        '   quit the search
        search.StartForward()
        search.AppendCharAndSearch(AscW("I"))
        search.AppendCharAndSearch(AscW("M"))

        ' To remove us from incremental search mode,
        ' we can call IncrementalSearch.Exit()...
        'search.Exit()

    End Sub
End Module

The Tool Window Types

In addition to having a Window object abstraction, each default tool window in the IDEthe command window, output window, Toolbox window, and task list windowis also represented by a discrete type that exposes methods and properties unique to that tool window. Table 10.7 lists the default tool windows and their underlying type in the automation object model.

=150> =350>

Table 10.7. Tool Windows and Their Types
Tool Window	Type
Command Window	`CommandWindow`
Output Window	`OutputWindow`
Task List Window	`TaskList`
Toolbox Window	`ToolBox`

To reference one of these objects, you first start with its Window representation and then cast its Window.Object value to the matching type. For instance, this VB snippet starts with a Window reference to the task list window and then uses that Window object to obtain a reference to the TaskList object:

Dim windows As Windows = DTE.Windows
Dim twindow As Window = _
    DTE.Windows.Item(EnvDTE.Constants.vsWindowKindTaskList)

Tasks and the Task List Window

The TaskList object enables you to access the items currently displayed in the task list window; each item in the window is represented by its own TaskItem object. The TaskItem object exposes methods and properties that allow you to manipulate the task items. For instance, you can mark an item as complete, get or set the line number associated with the task, and change the priority of the task.

You remove tasks from the list by using the TaskItem.Delete method and add them by using the TaskItems.Add method. The Add method allows you to specify the task category, subcategory, description, priority, icon, and so on:

Dim tlist As TaskList = CType(twindow.Object, TaskList)

tlist.TaskItems.Add("Best Practices", "Coding Style", _
   "Use of brace indenting is inconsistent", _
   vsTaskPriority.vsTaskPriorityMedium, _
   vsTaskIcon.vsTaskIconUser, True, _
   "S:\ContosoCommonFramework\Contoso.Fx.Common\Class1.cs", _
   7, True, True)

Table 10.8 provides an inventory of the TaskItem members.

=150> =350>

Table 10.8. `TaskItem` Members
Property	Description
`Category`	The category of the task.
`Checked`	A Boolean flag indicating whether the task is marked as completed (a check mark appears in the check box next to the task).
`Collection`	The `TaskList` collection that the current `TaskItem` object belongs to.
`Description`	The description of the task.
`Displayed`	A Boolean flag indicating whether the task is currently visible in the task list window.
`DTE`	A reference to the root `DTE` object.
`FileName`	The name of the file associated with the task (if any).
`IsSettable`	By passing in a `vsTaskListColumn` enum value to this property, you can determine whether that column is editable or not.
`Line`	The line number associated with the task.
`Priority`	A `vsTaskPriority` value indicating the task's priority level. Possible values include `vsTaskPriorityHigh`, `vsTaskPriorityMedium`, and `vsTaskPriorityLow`.
`SubCategory`	The subcategory of the task.
`LinkedWindows`	A collection of `Window` objects representing the windows that are linked together within the same frame.
`Object`	Returns an object proxy that represents the `Window` and can be referenced by name.
`ObjectKind`	A GUID indicating the type of the object returned from `Window.Object`.
`Project`	A `Project` instance representing the project containing the `Window` object.
`ProjectItem`	A `ProjectItem` instance representing the project item containing the `Window` object.
`Selection`	Returns an object representing the currently selected item in the `Window` (for document windows, this might be text; for tool windows, this might be an item in a list, and so on).
`Top`	The distance, in pixels, between the window's top edge and its parent's top edge.
`Visible`	A Boolean flag indicating whether the window is visible or hidden.
`Width`	The width of the window in pixels.
`WindowState`	Gets or sets the current state of the window (via a `vsWindowState` enum value: `vsWindowStateMaximize`, `vsWindowStateMinimize`, `vsWindowStateNormal`).

=150> =350>

Method	Description
`Delete`	Removes the task from the task list window.
`Navigate`	Causes the IDE to navigate to the location (for example, file and line) associated to the task.
`Select`	Selects or moves the focus to the task within the task list window.

Listing 10.4 contains a short VB macro demonstrating the use of the TaskList, TaskItems, and TaskItem objects to iterate the tasks and toggle their completed status.

Listing 10.4. Toggling Task Item Completion

Imports EnvDTE
Imports EnvDTE80
Imports Microsoft.VisualStudio.CommandBars
Imports System.Diagnostics
Imports System.Windows.Forms


Public Module MacroExamples

    Public Sub ToggleAllTasks()
        ' Reference the windows collection
        Dim windows As Windows = DTE.Windows

        ' Pluck the task list window from the collection
        Dim twindow As Window = _
            DTE.Windows.Item(EnvDTE.Constants.vsWindowKindTaskList)

        ' Convert the window object to a TaskList instance by
        ' casting its Object property
        Dim tlist As TaskList = CType(twindow.Object, TaskList)

        ' Iterate all of the task items in the task list
        For Each task As TaskItem In tlist.TaskItems
            ' Toggle the "completed" check mark on each item
            task.Checked = Not task.Checked
        Next


    End Sub
End Module

The ToolBox

Four objects are used to programmatically interface with the Toolbox:

ToolBoxAn object representing the Toolbox itself
ToolBoxTabsA collection representing the tab panes on the Toolbox
ToolBoxItemsA collection representing the items within a tab on the Toolbox
ToolBoxItemA discrete item displayed within a Toolbox tab

Figure 10.3 illustrates the Toolbox object hierarchy.

Figure 10.3. ToolBox object hierarchy.

These objects are used primarily to add, remove, or alter the items hosted by the Toolbox. For instance, you can easily add a custom tab to the Toolbox by using the ToolBoxTabs collection:

Dim tBox As ToolBox
Dim myTab As ToolBoxTab
tBox = DTE.Windows.Item(Constants.vsWindowKindToolbox).Object
myTab = tBox.ToolBoxTabs.Add("My TBox Tab")

You can also add items to any tab with the ToolBoxItems.Add method, which accepts a name for the item to add, a "data" object representing the item, and a vsToolBoxItem-Format enum, which specifies the format of the item. The Add method uses the vsToolBoxItemFormat to determine how to interpret the "data" object value. For instance, if you wanted to add a .NET control to the tab created in the previous code snippet, you could accomplish that with just one line of code:

tlBoxTab.ToolBoxItems.Add("ContosoControl", _
        "C:\Contoso\Controls\CalendarControl.dll", _
        vsToolBoxItemFormat.vsToolBoxItemFormatDotNETComponent)

Notice that the item, in this case, is represented by a path to the assembly that implements the control and that it has an item format of vsToolBoxItemFormatDotNET-Component.

Listing 10.5 contains a VB function that adds a tab to the Toolbox, adds a control and a text fragment to the tab, and then removes the tab.

Listing 10.5. Adding and Removing Items in the Toolbox Window

Imports EnvDTE
Imports EnvDTE80
Imports Microsoft.VisualStudio.CommandBars
Imports System.Diagnostics
Imports System.Windows.Forms


    Public Sub AddAToolBoxTab()
        Dim toolBox As ToolBox
        Dim tabs As ToolBoxTabs
        Dim tab As ToolBoxTab
        Dim tabItems As ToolBoxItems
        Dim win As Window

        Try
            ' Get a reference to the toolbox
            win = DTE.Windows.Item(Constants.vsWindowKindToolbox)
            toolBox = win.Object
            ' Get a reference to the toolbox tabs collection
            tabs = toolBox.ToolBoxTabs

            ' Add a new tab to the ToolBox
            tab = tabs.Add("New ToolBox Tab")

            ' Make the added tab the active tab
            tab.Activate()

            tabItems = tab.ToolBoxItems

            With tabItems
                ' Add a piece of text to the toolbox.
                ' Clicking on the text will add it to
                ' the active document...
                .Add("Code Comment", _
                    "This is some text to add to the toolbox", _
                    vsToolBoxItemFormat.vsToolBoxItemFormatText)

                'Now add a control to the toolbox.
                'When adding a control, you need to specify
                'the path to the assembly; you can add all
                'classes from the assembly (shown below)
                'or just one of the classes (see MSDN
                'docs for that syntax)
                .Add("My Login Control", _
                    "C:\MyComponents\Contoso\LoginControl.dll", _
                    vsToolBoxItemFormat.vsToolBoxItemFormatDotNETComponent)

                'For demonstration purposes, let's remove
                'the items that we had just added, and then
                'remove the newly created tab...

                'Put up a messagebox to confirm the deletes
                MessageBox.Show("Click OK to delete the tab and added items.", _
                    "Delete Toolbox Tab Items", MessageBoxButtons.OK, _
                    MessageBoxIcon.Information)

                'Delete the tab
                tab.Delete()

            End With

        Catch ex As Exception
            MsgBox("Error: " & ex.ToString())
        End Try

    End Sub

Executing Commands in the Command Window

The command window is a tool window used to execute IDE commands or aliases. IDE commands are essentially ways to tell the IDE to perform some action. Some commands map directly to menu items (such as File Open), whereas others don't have menu equivalents.

The CommandWindow object permits you to programmatically pipe commands into the command window and execute them. You can also output a text string (for informational purposes) to the window and clear its current content:

' Get a reference to the command window
Dim cmdWindow As CommandWindow = _
   DTE.Windows.Item(Constants.vsWindowKindCommandWindow).Object

' Display some text in the command window
cmdWindow.OutputString("Hello, World!")

' Clear the command window
cmdWindow.Clear()

Listing 10.6 shows how to programmatically execute commands in the CommandWindow object.

Listing 10.6. Executing Commands in the Command Window

Imports EnvDTE
Imports EnvDTE80
Imports Microsoft.VisualStudio.CommandBars
Imports System.Diagnostics
Imports System.Windows.Forms

Public Module MacroExamples

    Public Sub ExecCommandWindow()
        Dim cmdWindow As CommandWindow = _
            DTE.Windows.Item(Constants.vsWindowKindCommandWindow).Object
        ' Display some text in the command window
        cmdWindow.OutputString("Executing command from the automation OM...")

        ' Send some command strings to the command window and execute
        ' them...

        ' This command will start logging all input/output in the
        ' command window to the specified file
        cmdWindow.SendInput("Tools.LogCommandWindowOutput cmdwindow.log", True)

        ' Open a file in a code editor:
        '   1. We use an alias, 'of', for the File.OpenFile command
        '   2. This command takes quote-delimited parameters (in this case,
        '      the name of the editor to load the file in)
        Dim cmd As String = "of "
        cmd = cmd & """C:\Contoso\ContosoCommonFramework\Integration\Integration.cs"""
        cmd = cmd & "/e:""CSharp Editor"""

        cmdWindow.SendInput(cmd, True)

        cmdWindow.SendInput("Edit.Find MessageTrxId", True)

        ' Turn off logging
        cmdWindow.SendInput("Tools.LogCommandWindowOutput /off", True)

    End Sub
End Module

Output Window

The output window displays messages generated from a variety of different sources in the IDE. A prime example is the messages generated by the compiler when a project is being built. For a deeper look at the functionality provided by the output window, see Chapter 9, "Debugging with Visual Studio 2005."

The output window is controlled through three objects:

OutputWindow is the root object representing the output window.
OutputWindowPanes is a collection of OutputWindowPane objects.
OutputWindowPane represents one of the current panes within the output window.

Using these objects, you can add or remove panes from the output window, output text to any one of the panes, and respond to events transpiring in the window.

The following VB code fragment retrieves a reference to the output window and writes a test string in the Build pane:

Dim outWindow As OutputWindow = _
DTE.Windows.Item(Constants.vsWindowKindOutput).Object

Dim pane As OutputWindowPane = _
      outWindow.OutputWindowPanes.Item("Build")

pane.OutputString("test")

Using the OutputWindowPane object, you can also add items simultaneously to a specific output pane and the task list window. The OutputWindowPane.OutputTaskItemString method writes text into the output window and simultaneously adds that text as a task to the task list window:

Dim output As String = "Exception handler not found"
Dim task As String = "Add exception handler"
pane.OutputTaskItemString(output, _
   vsTaskPriority.vsTaskPriorityMedium,  "", vsTaskIcon.vsTaskIconNone, _
   "", 0, task, True)

Because most of the output window actions are conducted against a specific pane, most of the useful methods are concentrated in the OutputWindowPane object. For your reference, the OutputWindowPane members are itemized in Table 10.9.

=150> =350>

Table 10.9. `OutputWindowPane` Members
Property	Description
`Collection`	The `OutputWindowPanes` collection that the current `OutputWindowPane` object belongs to
`DTE`	A reference to the root `DTE` object
`Guid`	The GUID for the output window pane
`Name`	The name of the output window pane
`Textdocument`	A `Textdocument` object representing the window pane's content

=150> =350>

Method	Description
`Activate`	Moves the focus to the output window
`Clear`	Clears the contents of the window pane
`ForceItemsToTaskList`	Writes all task items not yet written to the task list window
`OutputString`	Writes a string to the output window pane
`OutputTaskItemString`	Writes a string to the output window pane and simultaneously adds a task to the task list window

Listing 10.7 demonstrates controlling the output window by adding a new pane to the window, writing text into that pane, and then clearing its content.

Listing 10.7. Writing to the Output Window

Imports EnvDTE
Imports EnvDTE80
Imports Microsoft.VisualStudio.CommandBars
Imports System.Diagnostics
Imports System.Windows.Forms


Public Module MacroExamples

    Public Sub WriteToOutputWindow()

        ' Grab a reference to the output window
        Dim outWindow As OutputWindow = _
            DTE.Windows.Item(Constants.vsWindowKindOutput).Object

        ' Create a new pane in the output window
        Dim pane As OutputWindowPane = _
            outWindow.OutputWindowPanes.Add("New Pane")

        pane.OutputString("Text in the 'New Pane'")

        pane.Clear()

    End Sub
End Module

Linked Windows

Tool windows can be positioned in a variety of ways within the IDE: You can float tool windows around within the overall IDE container; you can dock a tool window to one of the sides of the IDE; you can join windows together, pin and unpin them; and so on (see the section "Managing the Many Windows of the IDE" in Chapter 2, "A Quick Tour of the IDE," for an introduction to window layout).

A linked window refers to two or more tool windows that have been aggregated together. Figure 10.4 shows one common example of this: The Toolbox and Solution Explorer and the Data Sources window have all been joined together in a common frame. Each window that is part of the frame can be viewed by clicking on its tab.

Figure 10.4. Linked windows.

By joining together two or more tool windows, you actually create an additional window objectcalled a linked window or window framethat functions as the container for its hosted tool windows and is available as a part of the DTE.Windows collection.

By using the Window.LinkedWindows and Window.WindowFrame properties and the Windows2.CreateLinkedWindowFrame method, you can programmatically link and unlink any available tool windows. The Visual Basic code in Listing 10.8 demonstrates this process by doing the following:

You grab the window objects for the Toolbox window and the Solution Explorer window.
You programmatically join these two windows together, effectively creating the linked window that you see in Figure 10.4.
After joining the windows together, you get a reference to the newly created linked window and use its LinkedWindows property to unlink the windows that were previously just linked together.

Listing 10.8. Linking and Unlinking Tool Windows

Imports EnvDTE
Imports EnvDTE80
Imports System.Diagnostics
Imports System.Windows.Forms

Public Module MacroExamples

    Public Sub LinkUnLink()
        Dim windows As Windows2 = DTE.Windows

        ' Grab references to the solution explorer and the toolbox
        Dim solExplorer As Window2 = _
            windows.Item(Constants.vsWindowKindSolutionExplorer)
        Dim toolbox As Window2 = windows.Item(Constants.vsWindowKindToolbox)

        ' Use the Windows2 collection to create a linked window/window
        ' frame to hold the toolbox and solution explorer windows
        Dim windowFrame As Window2
        windowFrame = windows.CreateLinkedWindowFrame(solExplorer, _
            toolbox, vsLinkedWindowType.vsLinkedWindowTypeTabbed)

        ' At this point, we have created a linked window with two tabbed
        ' "interior" windows: the solution explorer, and the toolbox...

        MessageBox.Show("Press OK to Unlink the windows", "LinkUnLink", _
            MessageBoxButtons.OK, MessageBoxIcon.None)

        ' To unlink the windows:
        '   -- Use the window frame's
        '   -- Remove the window objects from this collection

        windowFrame.LinkedWindows.Remove(toolbox)
        windowFrame.LinkedWindows.Remove(solExplorer)

    End Sub
End Module

Command Bars

A command bar is a menu bar or toolbar; from an object model perspective, these are represented by CommandBar objects. Because menu bars and toolbars are hosted within a window, you reference specific CommandBar objects via the Window object, through the Window.CommandBars property. In turn, every CommandBar plays host to controls such as buttons, drop-downs, and so on. Figure 10.5 shows the Solution Explorer tool window with its command bar highlighted.

Figure 10.5. The Solution Explorer tool window and its command bar.

Note that there are six buttons hosted on the command bar.

Note

Unlike the Windows collection, which holds only an instance of each open window, the CommandBars collection holds instances for every single registered command bar, regardless of whether the command bar is currently being shown in the window.

The VB code in Listing 10.9 queries the CommandBar object for the Solution Explorer window and prints out the CommandBar objects that it finds.

Listing 10.9. Querying the `CommandBar` Object

Imports EnvDTE
Imports EnvDTE80
Imports Microsoft.VisualStudio.CommandBars
Imports System.Diagnostics
Imports System.Windows.Forms


Public Module MacroExamples

    Public Sub QueryCommandBar()
        Dim windows As Windows2 = DTE.Windows

        ' Grab reference to the solution explorer
        Dim solExplorer As Window2 = _
            windows.Item(Constants.vsWindowKindSolutionExplorer)

        ' Retrieve the solution explorer's command bar object
        Dim cmdBar As CommandBar = CType(solExplorer.CommandBars(1), CommandBar)

        ' Start building our output string
        Dim output As String = "Command bar contains: " + vbCrLf
        ' Get a reference to the controls hosted in the
        ' command bar
        Dim controls As CommandBarControls = cmdBar.Controls

        ' Count integer
        Dim i As Integer = 1

        ' Iterate the controls in the command bar
        For Each control As CommandBarControl In controls

            If control.Enabled Then

                output = output + i.ToString() + " " + _
                    control.Type.ToString() + _
                    ": " + control.Caption + vbCrLf

                i = i + 1

            End If

        Next

        MessageBox.Show(output, "Solution Explorer Command Bar", _
            MessageBoxButtons.OK)

    End Sub
End Module

Correlate the results in Figure 10.6 with Figure 10.4: Six buttons are visible on the tool window, and the code has found six items in the CommandBarControls collection (which is returned through the CommandBar.Controls property). Removing the following check against the Enabled property would result in many more controls produced in the message box:

If control.Enabled Then

Figure 10.6. Controls found in the command bar.

Notice in Listing 10.9 that you have to explicitly cast the object returned from the Window.CommandBars property: this is, interestingly, not a strongly typed property, and it returns an Object instead of an actual CommandBars instance.

Tip

Use the CommandBar.Type property to determine whether a command bar is a toolbar or a menu bar. A value of MsoBarType.msoBarTypeNormal indicates that the command bar is a toolbar, whereas a value of MsoBarType.msoBarTypeMenu indicates that the command bar is a menu bar.

The CommandBar object properties and methods are documented in Table 10.10.

=150> =350>

Table 10.10. `CommandBar` Members
Property	Description
`AdaptiveMenu`	For menu bars, this Boolean flag indicates whether the command bar has adaptive menus enabled. (Adaptive menus, sometimes referred to as personalized menus, are menus that alter their drop-down content based on projected or actual usage by the user; the intent is to display only those commands that are useful on the menu and hide the other nonessential commands.)
`Application`	An object representing the parent application to the command bar.
`BuiltIn`	Boolean flag used to distinguish between built-in and custom command bars.
`Context`	A string indicating where the `CommandBar` is saved (the format and expected content of this string are dictated by the hosting application).
`Controls`	A `CommandBarControls` collection containing `CommandBarControl` objects; each of these objects represents a control displayed by the command bar.
`Creator`	An integer value that identifies the application hosting the `CommandBar`.
`Enabled`	A Boolean flag indicating whether the command bar is enabled.
`Height`	The height of the command bar in pixels.
`Index`	The index of the command bar in the command bar collection.
`Left`	The distance, in pixels, between the left side of the command bar and the left edge of its parent container.
`Name`	The name of the command bar.
`NameLocal`	The localized name of the command bar.
`Parent`	An object that is the parent of the command bar.
`Position`	An `MsoBarPosition` enum value used to get or set the position of the command bar (for example, `MsoBarPosition.msoBarTop`).
`Protection`	An `MsoBarProtection` enum value that identifies the protection employed against used modification (for example, `MsoBarProtection.msoBarNoMove`).
`RowIndex`	An integer representing the docking row of the command bar.
`Top`	The distance, in pixels, between the top of the command bar and the top edge of its parent container.
`Type`	The type of the command bar (as an `MsobarType` enum value; for example, `MsoBarType.msoBarTypeNormal`).
`Visible`	A Boolean flag indicating whether the command bar is currently visible.
`Width`	The width of the command bar in pixels.

=150> =350>

Method	Description
`Delete`	Removes the command bar from its parent collection.
`FindControl`	Enables you to retrieve a reference to a control hosted by the command bar that fits various parameters such as its type, ID, tag, and visibility.
`Reset`	Resets one of the built-in command bars to its default configuration.
`ShowPopup`	Displays a pop-up representing a command bar.

Note

Previous versions of Visual Studio actually relied on a Microsoft Office assembly for the CommandBar object definition (Microsoft.Office.Core). Visual Studio 2005 provides its own implementation of the CommandBar object that is defined in the Microsoft.VisualStudio.CommandBars namespace, although you will find some types that carry their nomenclature over from the MS Office assembly, such as the various MsoXXX enums.

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.

=150> =350>

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

=150> =350>

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.

[View full size image]

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.

Debugger Objects

The automation object model provides a Debugger object that allows you to control the Visual Studio debugger. A Debugger instance can be obtained through the DTE.Debugger property:

Dim debugger As Debugger
debugger = DTE.Debugger

With a valid Debugger object, you can

Set breakpoints
Start and stop the debugger for a given process
Control the various execution stepping actions supported by the debugger such as Step Into, Step Over, and Step Out
Issue the Run to Cursor command to the debugger
Query the debugger for its current mode (for example, break mode, design mode, or run mode)

The following code starts the debugger if it isn't already started:

Dim debugger As Debugger2
debugger = DTE.Debugger

If debugger.CurrentMode <> dbgDebugMode.dbgRunMode Then
    debugger.Go()
End If

Automation Events

If your macro or add-in needs to be notified when a certain event occurs, various event objects are supported in all the automation object categories previously discussed. There are events for windows, events for editors, events for projects, and so on. For every event supported by the IDE, a corresponding class in the automation model allows you to hook the event and take action if the event is raised. The event objects tree is rooted in the DTE.Events property, as depicted in Figure 10.10.

Figure 10.10. Event types.

Because events are handled differently depending on whether you are working with code in an add-in or code in a macro, we will wait until the next chapter to cover the details of handling events. The basic premise, however, is fairly simple: You obtain a reference to the event object that you are interested in and then write an event handler that responds to one of that object's published events.

This code, for instance, is how you might handle the "build complete" event from inside a Visual Basic add-in:

Dim WithEvents bldevents As BuildEvents
bldevents = DTE.Events.BuildEvents

After instantiating a BuildEvents object, you now have to write the actual event handler:

Private Sub bldevents_OnBuildDone(ByVal Scope As EnvDTE.vsBuildScope, _
     ByVal Action As EnvDTE.vsBuildAction) Handles bldevents.OnBuildDone
        ' Code to handle the event goes here
    End Sub

Summary

The Visual Studio automation object model is a deep and wide API that exposes many of the IDE components to managed code running as a macro or an add-in. In this chapter, we documented how this API is organized and described its capabilities in terms of controlling the Visual Studio debugger, editors, windows, tool windows, solutions, and projects.

We also discussed the eventing model exposed by the API and looked at the API's capabilities with regards to accessing the underlying code structure for a project, issuing commands inside the IDE, and editing text documents programmatically.

Using the methods and properties expressed on the automation objects, you can automate common tasks in the IDE and extend Visual Studio in ways that address your specific development tool needs.

In the next chapter, we will directly build on the concepts discussed here and specifically walk you through the process of building add-ins and writing macros that talk to the automation objects.

posted on 2007-08-29 15:15 共同学习，共同进步阅读(2308) 评论(1) 编辑收藏举报

刷新页面返回顶部

Try again

Chapter 10. The Visual Studio Automation Object Model

An Overview of the Automation Object Model

Object Model Versions

Table 10.1. EnvDTE and EnvDTE80 Types

Automation Categories

The DTE/DTE2 Root Object

Table 10.2. DTE2 Properties and Methods for IDE Access

Solution and Project Objects

Figure 10.1. Mapping the solution/project hierarchy.

Table 10.3. Primary Solution/Solution2 Object Members

Controlling Projects in a Solution

Table 10.4. Primary Project Object Members

Accessing Code Within a Project

Listing 10.1. A Simple Namespace and Class Implementation

Figure 10.2. Simple code model object hierarchy.

Table 10.5. Mapping the vsCMElement Enumeration Values

Windows

Referencing Windows

Interacting with Windows

Table 10.6. Window Object Members

Listing 10.2. VB Macro for Querying the Windows Collection

Text Windows and Window Panes

Listing 10.3. Controlling Incremental Search

The Tool Window Types

Table 10.7. Tool Windows and Their Types

Tasks and the Task List Window

Table 10.8. TaskItem Members

Listing 10.4. Toggling Task Item Completion

The ToolBox

Figure 10.3. ToolBox object hierarchy.

Listing 10.5. Adding and Removing Items in the Toolbox Window

Executing Commands in the Command Window

Listing 10.6. Executing Commands in the Command Window

Output Window

Table 10.9. OutputWindowPane Members

Listing 10.7. Writing to the Output Window

Linked Windows

Figure 10.4. Linked windows.

Listing 10.8. Linking and Unlinking Tool Windows

Command Bars

Figure 10.5. The Solution Explorer tool window and its command bar.

Listing 10.9. Querying the CommandBar Object

Figure 10.6. Controls found in the command bar.

Table 10.10. CommandBar Members

Command Objects

Table 10.14. Command Members

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

Executing a Command

Mapping Key Bindings

Debugger Objects

Automation Events

Figure 10.10. Event types.

Summary

Table 10.1. `EnvDTE` and `EnvDTE80` Types

The `DTE`/`DTE2` Root Object

Table 10.2. `DTE2` Properties and Methods for IDE Access

`Solution` and `Project` Objects

Table 10.3. Primary `Solution`/`Solution2` Object Members

Table 10.4. Primary `Project` Object Members

Table 10.5. Mapping the `vsCMElement` Enumeration Values

Table 10.6. `Window` Object Members

Table 10.8. `TaskItem` Members

Table 10.9. `OutputWindowPane` Members

Listing 10.9. Querying the `CommandBar` Object

Table 10.10. `CommandBar` Members

Table 10.14. `Command` Members