How to: Handle Environment Events in Macros

Article
02/23/2011

Every new macro project includes a module called EnvironmentEvents, which is visible only in the Macros IDE. This is a template item that contains a number of useful pre-defined event procedures that you can implement in your macros, specifically:

You can view these event procedures in the object browers in the code editor.

To insert a pre-defined event procedure into your macro

On the Class View explorer pane, in the Macros IDE, double-click the EnvironmentEvents node to display it as an EnvironmentEvents tab and a drop-down menu on the macro editor pane.
From the EnvironmentEvents drop-down menu, select an events type, such as TaskListEvents. The Declarations combo box is now populated with the available Task List events.
On the Declarations drop-down menu, select an event, such as TaskAdded, to add its event procedure to the module.

The event is inserted into your macro and you can now add code to the event procedure.

In some cases, you might want to add more event procedures to the Class Name combo box, for example, the CommandEvents events.

Adding a New Event Procedure

To add a new event procedure to the Class Name combo box

Enter a declaration for the event after the hidden region of the EnvironmentEvents module labeled "Automatically generated code, do not modify":

<System.ContextStaticAttribute()> Public WithEvents CommandEvents As EnvDTE.CommandEvents
' This procedure handles DTEEvents.OnMacrosRuntimeReset.

Set up the OnMacrosRuntimeReset procedure so that the new event variable initializes each time a macro is re-run:

Public Sub DTEEvents_OnMacrosRuntimeReset() Handles _
  DTEEvents.OnMacrosRuntimeReset
   CommandEvents = DTE.Events.CommandEvents
End Sub

Set up the OnStartupComplete procedure to complete the initialization procedure in step 5.

Private Sub DTEEvents_OnStartupComplete() Handles_
  DTEEvents.OnStartupComplete
        CommandEvents = DTE.Events.CommandEvents
End Sub

Add code to respond to the event. In this example, after a command executes, this procedure reports on the details of the command that was issued:

Public Sub CommandEvents_AfterExecute(ByVal Guid As String, ByVal ID As Integer, ByVal CustomIn As Object, ByVal CustomOut as Object) Handles CommandEvents.AfterExecute
   MsgBox(DTE.Commands.Item(Guid, ID).Name)
End Sub

When you declare a new event, you must first initialize it in order to use it. For macros, the place to initialize the new event variable is in the OnMacrosRuntimeReset event procedure.

This event occurs whenever a macro's runtime is reset, such as when a macro is loaded or unloaded. When this occurs, there is a loss of global state. That is, the values of global variables are lost and event handlers are unhooked, meaning that code that formerly executed when an event occurs no longer does so.

When a macro's runtime is reset, the OnMacrosRuntimeReset event occurs. This allows you to automatically re-initialize variables and event handlers whenever a macro runtime reset occurs. By initializing event variables and handlers in OnMacrosRuntimeReset, you ensure that their values are reinitialized each time a macro's runtime is reset, and thus, that your new event procedures work correctly.

How to: Handle Environment Events in Macros

To insert a pre-defined event procedure into your macro

Adding a New Event Procedure

To add a new event procedure to the Class Name combo box

See Also

Tasks

Concepts

Additional resources