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.