Inside Microsoft® Visual Studio® .NET 2003 [Electronic resources] نسخه متنی

Add-in Events

Add-ins are event-driven. Most everything an add-in does it does in response to some external prodding, and Visual Studio .NET prods add-ins with the IDTExtensibility2 interface. We'll begin our exploration of add-in events by examining the sequence in which Visual Studio .NET calls the IDTExtensibility2 methods.

The Add-in Event Sequence

Calls to the IDTExtensibility2 methods, which we'll also refer to as events, occur at predictable points in the lifetime of an add-in. Figure 6-4 shows the sequence of events from the time an add-in is loaded to the time it is unloaded.

You can guess the actions that trigger the events just from the events' names, and the events occur pretty much in the order you would expect: OnConnection when an add-in loads, OnDisconnection when an add-in unloads, and so on. But however straightforward the event sequence might seem, it still holds a few surprises for the programmer who believes everything she reads in the documentation. The first surprise is the initial OnAddInsUpdate event. The documentation says that an add-in receives OnAddInsUpdate events only when other add-ins are loaded or unloaded; in truth, the add-in itself triggers the first OnAddInsUpdate it receives. This isn't a bug; instead, it turns out that the documentation is wrong, but you could argue that Visual Studio .NET should be smarter about which add-ins get notified. After all, an add-in already knows that it's being loaded when it receives the OnConnection eventit doesn't need an OnAddInsUpdate event to remind it of that.

The second surprise involves the Add-in Manager. The Add-in Manager triggers OnAddInsUpdate events whenever its OK button is clicked, regardless of whether an add-in was loaded or unloaded. This happens because clicking the OK button resets the add-ins list automatically, thereby triggering a round of OnAddInsUpdate events. This behavior is by design, for better or worse, so don't assume that every OnAddInsUpdate event after the first has something important to tell.

The third surprise is that add-ins loaded by commands don't trigger OnAddInsUpdate events, and neither do add-ins loaded or unloaded by way of their Connected properties. (We'll go over commands in detail in Chapter 7.) There's no nice way to describe this behavior, so we'll call a bug a bug and move on.

The LifeCycle Add-in

You can get a feel for the add-in event sequence by running the LifeCycle sample add-in. LifeCycle, shown in Listing 6-2, handles each IDTExtensibility2 event by displaying the name of the event in the Output window. After you build and register LifeCycle, load it into Visual Studio .NET using the Add-in Manager. Then try loading and unloading other add-ins, such as Basic, to trigger the different IDTExtensibility2 events. To fire the OnStartupComplete event, you first need to select the Startup check box for LifeCycle in the Add-in Manager, and then you must restart Visual Studio .NET. To fire the OnBeginShutdown event, close Visual Studio .NET while LifeCycle is loaded.

Listing 6-2 The LifeCycle add-in source code

LifeCycle.cs
namespace InsideVSNET
{
namespace AddIns
{
using EnvDTE;
using Extensibility;
using InsideVSNET.Utilities;
using System;
using System.Runtime.InteropServices;
[GuidAttribute("D0C34F40-6A93-4601-B456-5A972E9C8D24")]
public class LifeCycle : IDTExtensibility2
{
private string title = "LifeCycle";
private OutputWindowPaneEx output;
public void OnConnection(object application, 
ext_ConnectMode connectMode, 
object addInInst, 
ref Array custom)
{
this.output = new OutputWindowPaneEx((DTE)application,
this.title);
this.output.WriteLine("OnConnection event fired");
}
public void OnStartupComplete(ref Array custom)
{
this.output.WriteLine("OnStartupComplete event fired");
}
public void OnAddInsUpdate(ref Array custom)
{
this.output.WriteLine("OnAddInsUpdate event fired");
}
public void OnBeginShutdown(ref Array custom)
{
this.output.WriteLine("OnBeginShutdown event fired");
}
public void OnDisconnection(ext_DisconnectMode removeMode,
ref Array custom)
{
this.output.WriteLine("OnDisconnection event fired");
}
}
}
}

You already know how to build an add-in from scratch using the command linenow it's time to learn how to build an add-in from scratch using Visual Studio .NET. (After all, this isn't a book about how command-line programming can make your life easier.)

To construct the LifeCycle project, first create a new solution by choosing File | New | Blank Solution in Visual Studio .NET. Add a project named LifeCycle to the solution by choosing File | Add Project | New Project and selecting Visual C# Projects | Empty Project in the Add New Project dialog box. Finally, add a CS file named LifeCycle.cs to the project by choosing File | Add New Item and selecting Code File from the Add New Item dialog box.

Next you need to alter two of the project's properties: output type and COM interoperability. A blank project builds a console application by default; to change the project into one that creates a DLL, right-click on the project name in Solution Explorer and choose Properties from the shortcut menu. In the LifeCycle Property Pages dialog box, select Common Properties | General in the left pane and then select Class Library from the Output Type drop-down list in the right pane. The same dialog box lets you enable COM interoperability, which directs Visual Studio .NET to add the registry entries necessary to allow the add-in to function as a COM component. To enable COM interoperability for the add-in, select Configuration Properties | Build in the left pane of the LifeCycle Property Pages dialog box and select True from the Register For COM Interop drop-down list in the right pane.

Note

If you've just changed the output type, you have to click Apply before the Register For COM Interop drop-down list is enabled. If you switch to Configuration Properties | Build before you apply the new output type, you're out of luckyou'll have to close and reopen the dialog box before you can select a new Register For COM Interop setting.

Once you've set up your project, enter the code from Listing 6-2 into the CS file. If you try to build the project at this point, the compiler will complain that it can't find the EnvDTE, Extensibility, and Utilities namespaces and the types they define. To add references to these namespaces, right-click References in Solution Explorer and choose Add Reference from the shortcut menu. On the .NET tab of the Add References dialog box, select envdte, extensibility, and InsideVSNET.Utilities from the component list. Once you've done this, you can build LifeCycle.dll without a problem.