第 146 页

Next document

End Sub

To get a reference to the active document window, use:

Dim document As Document = DTE.ActiveDocument

You can use the DTE.WindowConfigurations collection to manipulate the configuration of

windows in the IDE.

commands

Every executable action in Visual Studio is represented by a command. For example, all menu items

execute a command when selected. Every command has a unique name, numeric ID (within its

grouping), and GUID designating its grouping. Visual Studio has thousands of commands, as you

can see by enumerating the DTE.Commands collection like so:

Public Sub EnumerateCommands()

For Each command As Command In DTE.Commands

Debug.Print(command.Name & “, ID=” & command.ID & “, GUID=” & command.Guid)

Next command

End Sub

To perform an action in Visual Studio through your add-in or macro, you will need to get a

reference to the appropriate command and execute it. For example, say you want to comment out

the selected code in the code editor. This command is called Edit.CommentSelection, and you can

execute it using the following code:

Public Sub ExecuteCommentSelectionCommand()

DTE.ExecuteCommand(“Edit.CommentSelection”)

End Sub

Finding the command name for a specific action can be difficult considering the

number of commands that exist. The easiest way to find the name of a command

so you can use it is to record a macro (see Chapter 52) of you performing the

action, and inspect the code the macro recorder generates.

The Visual studio automation Model .

1007

You can also listen for commands being executed, which are raised by Visual Studio as events that you

can handle. An event will be raised before the command is executed, and another event will be raised

after the command has completed. For example, you may want to do something particular when

text is pasted into the code editor (that is, respond to the Edit.Paste command). Handling events is

covered later in this chapter.

debugger

You can control the various functions of the Visual Studio debugger using the DTE.Debugger

automation object. This allows you to work with breakpoints, control code execution, and examine

various aspects of the application being debugged (including processes and threads).

The following code demonstrates enumerating through all the breakpoints in the current solution:

Public Sub EnumerateBreakpoints()

For Each breakpoint As Breakpoint2 In DTE.Debugger.Breakpoints

Debug.Print(breakpoint.Name & " | File: " & breakpoint.File & _

" | Function: " & breakpoint.FunctionName & _

" | Line: " & breakpoint.FileLine)

Next breakpoint

End Sub

You can also control the execution of code when debugging an application, such as starting

debugging, terminating debugging, stepping over a line of code, running to the current cursor

position, and so on. The following code demonstrates starting the current solution in the debugger:

Public Sub RunApplicationInDebugger()

DTE.Debugger.Go()

End Sub

events

The automation model enables you to listen for various actions in Visual Studio and respond to

them by raising events that you can handle. The events are categorized into a number of objects

according to their functional area under the DTE.Events object, including DocumentEvents,

WindowEvents, BuildEvents, SolutionEvents, ProjectsEvents, DebuggerEvents, and many

others. Chapter 51 demonstrates handling events in add-ins. In macros, the EnvironmentEvents

module that is automatically added to each macro project defines event variables that you can

create event handler methods for (using the Handles keyword). The following code captures

the DocumentOpened event on the DTE.Events.DocumentEvents object (an instance of

which has previously been created and stored in the DocumentEvents variable in the default

EnvironmentEvents module). Place it in the EnvironmentEvents module, save the module, and

close the Macros IDE:

Private Sub DocumentEvents_DocumentOpened(ByVal Document As EnvDTE.Document) _

Handles DocumentEvents.DocumentOpened

MsgBox("Document opened: " & Document.Name & " at " & DateTime.Now)

End Sub

This event handler will be raised whenever you open a new document in the Visual Studio IDE.

1008 .

chaPter 50 The AuTomATion model

suMMary

In this chapter you were introduced to the various means of extending the functionality of

Visual Studio 2010, and you then took a look at the structure and capabilities of the Visual

Studio automation model, which both add-ins and macros use to extend Visual Studio.

The following two chapters look at these two means of extending Visual Studio using this

object model.

551

add-ins

what’s in this chaPter?

.

Understanding the structure of add-ins

.

Creating add-ins

.

Testing and debugging add-ins

.

Deploying add-ins

As detailed in Chapter 50, Visual Studio add-ins are components that run within Visual

Studio and extend its functionality via the Visual Studio automation model.

This chapter takes you through the process of creating a Visual Studio add-in that integrates

with the Visual Studio IDE to display a tool window (that enables you to store some notes),

perform actions in Visual Studio (copy selected text from the code editor), and handle Visual

Studio events (capture the cut and copy command events from the code editor).

deVeloPinG an add-in

When you create a Visual Studio add-in project, the Add-in Wizard appears and helps you to

create the appropriate structure and base functionality in your add-in based on your input

to its questions. From there you are on your own to implement the functionality from this base

framework. You start from the base that it gives you and gradually add functionality to make

it a useful tool.

1010 .

chaPter 51 Add -inS

the add-in wizard

Start by creating a new project, using the Visual Studio Add-in project template in the Extensibility

project category (under the Other Project Type category), as shown in Figure 51-1.

fiGure 51-1

You’ll note that the Extensibility category also contains a Shared Add-in project

template. This template is similar to the Visual Studio Add-in, but is used for

creating add-ins for the various applications in Microsoft Office instead of

Visual Studio (although this has largely been taken over by VSTO).

Clicking OK starts the Add-in Wizard. The wizard consists of seven steps (including a welcome step

and summary step). This section goes through each of these steps in the wizard and the options that

each step provides.

There is a welcome page at the start, which gives a short description of the wizard (as shown in

Figure 51 - 2).

In the next step of the Add-in Wizard (as shown in Figure 51-3) you need to choose a development

language for your add-in (because the Visual Studio Add-in project template was not under a

particular language category in the New Project dialog). You have four options — Visual C#, Visual

Basic, Visual C++/CLR, and Visual C++/ATL. Visual Studio generates the project in the language

that you choose here.

Developing an add-in .

1011

fiGure 51-2 fiGure 51-3

Now you need to choose an application host for your add-in (as shown in Figure 51-4). Two

application hosts are available for your add-ins: the Visual Studio IDE and the Visual Studio Macros

IDE (which is discussed in the next chapter). You can check or uncheck each host to select or

deselect it. Your add-in will be available to the application host(s) that you select here.

Now you can enter a name and description for your add-in (as shown in Figure 51-5). This

information is what end users see in the Add-in Manager dialog in Visual Studio for your add-in.

fiGure 51-4 fiGure 51-5

The next step contains the options for how your add-in will load and interact with Visual Studio.

You can check three options to include in your add-in (as shown in Figure 51-6). The first option

specifies that your add-in will have a menu item in the Tools menu that can be used to activate it.

The second option indicates that you would like to load your add-in when the Visual Studio IDE

or Visual Studio Macros IDE starts, and the third option is used to specify that your add-in doesn’t

show any modal user interfaces, and thus can be used with command-line builds.

1012 .

chaPter 51 Add-inS

The next step (as shown in Figure 51-7) enables you to display some information in the Visual

Studio About box for your add-in — especially useful if you are releasing your add-in as a product.

fiGure 51-6 fiGure 51-7

In the final step you will see a summary of what

you have chosen in your wizard (as shown in

Figure 51-8). At this stage, you can go back and

change your options or click the Finish button to

go ahead and generate the solution and initial code

for your add-in.

After you click the Finish button, Visual Studio

generates a solution with the required files for

creating the add-in, configured according to the

options you’ve selected for the add-in.

Project structure

Once the project has been created, you will find

the project structure, shown in Figure 51-9.

As you can see, the project consists of a Connect.cs (or Connect.vb)

file, and two files with the .AddIn extension.

The Connect.cs/Connect.vb file contains the core class that controls

the add-in. The .AddIn files are used to enable Visual Studio to

discover the add-in so it can load it. One is located in your project

folder, but you’ll note that the other is a linked file (MyNotesTool -

For Testing.AddIn), located in the My Documents\Visual Studio

2010\Addins folder of your Windows user profile. As its name suggests, this file is used so that

Visual Studio can discover your add-in during its testing and debugging. The reason the file is in

this folder is that it is one of the paths that Visual Studio looks in to discover add-in files. If you

open both files, you will find that they are identical with one exception — the Assembly node of the

linked file includes the full path to the compiled add-in assembly, whereas the other only includes

fiGure 51-8

fiGure 51-9

Developing an add-in .

1013

the name of the assembly (expecting it to be in the same folder as the .AddIn file). We take a closer

look at .AddIn files later in this chapter.

testing your add-in

First, check to make sure everything works OK by simply running your project. This starts a new

instance of Visual Studio 2010 in which you can test and debug the add-in. If you selected the

options in the wizard to start automatically when the IDE is started and to create a Tool menu item,

you should see a menu item at the top of the Tools menu for your add-in, with a default smiley face

icon (which you can change to your own icon), as shown in Figure 51-10.

If you haven’t selected the add-in to load automatically with the IDE, you can start it from the Add-

in Manager (Tools . Add-in Manager) and put a check mark in the checkbox next to its name, as

shown in Figure 51-11.

fiGure 51-10 fiGure 51-11

If your add - in is not appearing in the Add - in Manager, Visual Studio is unable to

fi nd the .AddIn fi le. Go to Tools . Options and select the Add - in/Macro Security

category (under the Environment category, as shown in Figure 51 - 12). Make sure

that the path where the testing .AddIn fi le is located is listed in the Add - in File

Paths list. It ’s also possible that the environment variables used in this dialog are

not declared in your system, so check these too.

fiGure 51-12

1014 .

chaPter 51 Add-inS

Close the debugging instance of Visual Studio to finish debugging the add-in.

the addin file

As mentioned earlier in this chapter, there are two .AddIn files in your solution: one in the

project folder, and a linked file that has been placed in the My Documents\Visual Studio 2010\

Addins folder on your machine.

In early versions of Visual Studio, you had to register the COM component by hand for an add-in

on the machine, making deployment a little difficult (the add-in couldn’t be deployed using a simple

XCOPY). .AddIn files were designed to make the process of deploying add-ins easier. By placing

the .AddIn file in a folder that Visual Studio is configured to look in, Visual Studio will use it to

discover your add-in and load it (without worrying about the need to register the add-in). Essentially,

.AddIn files point Visual Studio to where your add-in is (which will usually be in the same path as

the .AddIn file).

.AddIn files are XML files, and in addition to pointing Visual Studio to the location of your add-in,

they also contain configuration information such as what hosts the add-in should be accessible to

(including different versions of Visual Studio), what will appear in the Add-in Manager to describe

the add-in, and startup options for the add-in.

If you open up an .AddIn file, you will find XML similar to the following:

<?xml version="1.0" encoding="UTF-16" standalone="no"?>

<Extensibility xmlns="http://schemas.microsoft.com/AutomationExtensibility">

<HostApplication>

<Name>Microsoft Visual Studio Macros</Name>

<Version>10.0</Version>

</HostApplication>

<HostApplication>

<Name>Microsoft Visual Studio</Name>

<Version>10.0</Version>

</HostApplication>

<Addin>

<FriendlyName>My Notes</FriendlyName>

<Description>My Notes</Description>

<Assembly>MyNotesTool.dll</Assembly>

<FullClassName>MyNotesTool.Connect</FullClassName>

<LoadBehavior>5</LoadBehavior>

<CommandPreload>1</CommandPreload>

<CommandLineSafe>1</CommandLineSafe>

</Addin>

</Extensibility>

Of particular note are the HostApplication nodes, listing each host application name and its specific