Macros and the EnvironmentEvents Project Item

  • Article

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
  • SolutionItemsEvents
  • MiscFilesEvents
  • DebuggerEvents

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. In the Macros IDE, double-click the EnvironmentEvents module to display it.
  2. Select the Class Name combo box and choose an events type, such as TaskListEvents. The Method Names combo box is now populated with the available Task List events.
  3. In the Method Names combo box, choose 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.

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

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

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

The OnMacrosRuntimeReset Event

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

Automating Repetitive Actions by Using Macros | OnMacrosRuntimeReset Event | Recording Macros | Running Macros | Editing Macros | Debugging Macros | Macro Recording and Running Issues | Managing Macros | Referencing COM and .NET Framework Components in Macros | Macros Security and Sharing Issues