Exploring the Connect Class Methods | Writing Add-Ins for Visual Studio .NET

< Free Open Study >

The Add-in Wizard created the Connect class for you, as you have already seen. Also, you have done some work in several of the methods of the class. At this point, you need to determine the purpose of all of the methods of the class, as the Connect class is the start-up point for any add-in.

OnConnection Method

As you have seen, OnConnection is the method that is called first by the IDE when it starts the add-in. Three parameters are passed to the method. The first is the pointer to the DTE, which is passed as the parameter application. This parameter has already been discussed in detail. The second parameter is ConnectMode. This parameter has the following values, which you can examine in the method to determine how or when the add-in was loaded:

ext_cm_AfterStartup – 0: The add-in was loaded after the application started or by setting the Connect property of the corresponding add-in to True.
ext_cm_Startup – 1: The add-in was loaded at IDE start-up.
ext_cm_External – 2: The add-in was loaded externally by another program or component.
ext_cm_CommandLine – 3: The add-in was loaded through the Visual Studio devenv command line.
ext_cm_Solution – 4: The add-in was loaded when a user loaded a solution that required the add-in.
ext_cm_UISetup – 5: The add-in was started for the first time since being installed.

You can see that the wizard creates code to test the ConnectMode parameter. It initially checks for ext_cm_UISetup, and if this is the setting, it places the UI menu option on the Tools menu. I changed it to check for ext_cm_Startup. The reason for this is that I always place and remove the UI from the IDE in the OnConnection and OnDisconnection procedures. In this case, you can actually remove the code for testing the ConnectMode parameter. It is really academic because of the way that I recommend that you place and remove the UI. The third parameter, addInInst, is an object representing the instance of the add-in. It is passed to the AddNamedCommand method of the Commands object when adding a menu to the IDE. It provides a pointer to the add-in connecting to the new command being created. The OnConnection method is the obvious point to place your UI (menus, toolbars, tool buttons) through which the user will communicate to the add-in. This method is also the place to put your validation code if you are licensing the add-in. You would normally do this before putting up the UI. If the user is not a valid user, you would not want to put the UI into the IDE.

OnDisconnection Method

This event occurs when the add-in is unloaded. Two parameters are passed, but Visual Studio .NET does not use the second parameter. The one parameter that is used is RemoveMode. It has four possible different values, which you can look up in the help file. Because I always remove the UI on add-in shutdown, I see no value in testing the RemoveMode parameter. This is also a good place to unload any forms that you may have loaded in the add-in. Because you never know when the IDE will shut down your add-in, either because the IDE is shutting down or because the user has unloaded the add-in from the Add-in Manager, you should unload any forms here. Forms can be left standing alone if you do not proactively remove them. Do not assume that your user has closed all of the forms before unloading the add-in or the IDE.

QueryStatus Event

When the user clicks a command (menu or tool button), the QueryStatus event is fired. The QueryStatus event returns the current status of the specified named command, whether it is enabled, disabled, or hidden in the vsCommandStatus parameter, which is passed to the event by reference. The event has the following parameters:

CmdName: The name of the command to check.
NeededText: A vsCommandStatusTextWanted constant specifying whether information is returned from the check, and if so, what type of information is returned.
StatusOption: A vsCommandStatus specifying the current status of the command. This parameter determines if the Exec event will be fired.
CommandText: The text to return if vsCommandStatusTextWantedStatus is specified.

The Add-in Wizard created the code for this event, and you have not modified it. If you use this event and have multiple commands, you will have to add more tests for the bold line of code in the event shown in Listing 2-6. If you have multiple commands, you would want to replace the "If neededText" with a Select Case construct. I discuss the use of multiple commands in Chapter 7. In that chapter, I also show you how to create a variety of types of user interfaces.

Listing 2-6: QueryStatus Event

     Private Sub QueryStatus(ByVal cmdName As String, _                 ByVal neededText As vsCommandStatusTextWanted, _                 ByRef statusOption As vsCommandStatus, _                 ByRef commandText As Object) _                 Implements IDTCommandTarget.QueryStatus         If neededText = _             EnvDTE.vsCommandStatusTextWanted.vsCommandStatusTextWantedNone _             Then             If cmdName = "MyAddinTest1.Connect.MyCommand1" Then                 statusOption = _                 CType(vsCommandStatus.vsCommandStatusEnabled + _                 vsCommandStatus.vsCommandStatusSupported, _                 vsCommandStatus)             Else                 statusOption = vsCommandStatus.vsCommandStatusUnsupported             End If         End If     End Sub

Exec Event

The Exec event is fired after the QueryStatus event is fired, assuming that the return to the statusOption parameter of QueryStatus is supported and enabled. This is the event where you place the actual code for handling the response to the user click on the command. Again, if you have multiple commands, you will need to replace the bold text in Listing 2-7 with a Select Case construct.

Listing 2-7: Exec Event

 Public Sub Exec(ByVal cmdName As String, _                     ByVal executeOption As vsCommandExecOption, _                     ByRef varIn As Object, _                     ByRef varOut As Object, _                     ByRef handled As Boolean) _                     Implements IDTCommandTarget.Exec         Dim oFrm As New frmTreeView()         handled = False         If (executeOption = _             vsCommandExecOption.vsCommandExecOptionDoDefault) _             Then            If cmdName = "MyAddinTest1.Connect.MyCommand1" Then               handled = True               'MsgBox("You Rang?", MsgBoxStyle.Question, "MyAddinTest1")               Try                   oFrm.Show()               Catch                   MsgBox("Can't load frmTreeview", MsgBoxStyle.Critical)               End Try               Exit Sub            End If         End If     End Sub

< Free Open Study >