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 TypesEnvDTE 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: 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 AccessCategory | 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. |