How to: Handle Environment Events in Macros

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:

• DTEEvents

• DocumentEvents

• WindowEvents

• TaskListEvents

• FindEvents

• OutputWindowEvents

• SelectionEvents

• SolutionEvents

• SolutionItemsEvents

• BuildEvents

• MiscFilesEvents

• DebuggerEvents

• CodeModelEvents

• CommandEvents

• DebuggerExpressionEvaluationEvents

• DebuggerProcessEvents

• TextDocumentKeyPressEvents

You can view these event procedures in the Class Name combo box and their events in the Method Name combo box. Both boxes are located at the top of the code editor.

To insert a pre-defined event procedure into your macro

1. 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.

2. 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.

3. 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

1. 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.
   

2. 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
   

3. 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
   

4. 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.

See Also

Tasks

How to: Record Macros

How to: Run Macros

How to: Record Macros

How to: Manage Macros

How to: Reference COM and .NET Framework Components in Macros

Concepts

Automating Repetitive Actions by Using Macros

Debugging Macros

Macro Recording and Running Issues

Macros Security and Sharing Issues