Using event handlers

VSScript provides a way to handle events which Visual Studio raises e.g. when a solution is opened, command is executed, item is added, etc. You can assign one or more Lua functions to be called in each case of event occurrence.

Accessing event manager objects

The following Lua expression gets the single instance of Events object, which represents the root event handler manager in Visual Studio:

dte:getEvents()

Events are grouped into categories. You can use methods of the main object to access subsequent event managers for each category. For example, to access the build events manager, use the following Lua expression:

dte:getEvents():getBuildEvents()

There is a couple of events defined by the build event manager. For example, onBuildBegin is raised before build starts. To access the particular event object, use the following expression:

dte:getEvents():getBuildEvents():getOnBuildBegin()

The same rule applies to other event categories. The complete list of categories and events is included below.

Operations on event manager objects

Each event object provides the same set of methods, allowing to manage handler functions:

    add ( <function> )    -- adds a handler function. 
    remove ( <function> ) -- removes a handler function. 
    clear()               -- removes all handler functions. 
    isEmpty()             -- checks whether any handler functions are registered.
    count()               -- returns the number of registered handler functions.

For example, to add a handler to be launched before build starts, you can use the following code:

    -- pragma:global

    function handleBuildBegin ( scope, action )
        if scope == dte.vsBuildScopeSolution then
            -- handle solution build
        elseif scope == dte.vsBuildScopeProject then
            -- handle project build
        end;
    end;

    dte:getEvents():getBuildEvents():getOnBuildBegin():add ( handleBuildBegin );

Note that -- pragma:global directive has been used. This instructs VSScript to run the code in the global interpreter. This is necessary for the event handler to be run in the background, independently of any particular script invocation.

Event handlers can have parameters (scope and action in the example). These are exactly same parameters as for corresponding Visual Studio events. Meaning of each argument is explained in MSDN, mostly they have self-descriptive names. The reference section below lists all parameters and their types.

Events reference

onBuildBegin

Occurs before the solution builds, before a batch build begins, or just before a project begins to build.

Retrieval expression:

    dte:getEvents():getBuildEvents():getOnBuildBegin()

Handler prototype:

    function onBuildBegin ( scope, action )

Handler argument types:

    scope:
        dte.vsBuildScopeSolution
        dte.vsBuildScopeBatch
        dte.vsBuildScopeProject

    action:        
        dte.vsBuildActionBuild
        dte.vsBuildActionRebuildAll
        dte.vsBuildActionClean
        dte.vsBuildActionDeploy

onBuildDone

Occurs after a solution build completes.

Retrieval expression:

    dte:getEvents():getBuildEvents():getOnBuildDone()

Handler prototype:

    function onBuildDone ( scope, action )

Handler argument types:

    scope:
        dte.vsBuildScopeSolution
        dte.vsBuildScopeBatch
        dte.vsBuildScopeProject

    action:        
        dte.vsBuildActionBuild
        dte.vsBuildActionRebuildAll
        dte.vsBuildActionClean
        dte.vsBuildActionDeploy

onBuildProjConfigBegin

Occurs when a project configuration build begins.

Retrieval expression:

    dte:getEvents():getBuildEvents():getOnBuildProjConfigBegin()

Handler prototype:

    function onBuildProjConfigBegin ( project, projectConfig, platform, solutionConfig )

Handler argument types:

    project: string
    projectConfig: string
    platform: string
    solutionConfig: string

onBuildProjConfigDone

Occurs after a project configuration build completes.

Retrieval expression:

    dte:getEvents():getBuildEvents():getOnBuildProjConfigDone()

Handler prototype:

    function onBuildProjConfigDone ( project, projectConfig, platform, solutionConfig, success )

Handler argument types:

    project: string
    projectConfig: string
    platform: string
    solutionConfig: string
    success: bool

onAfterExecute

Occurs after a command executes.

Retrieval expression:

    dte:getEvents():getCommandEvents():getOnAfterExecute()

Handler prototype:

    function onAfterExecute ( groupGuid, commandId )

Handler argument types:

    groupGuid: string
    commandId: int

onBeforeExecute

Occurs before a command executes. Return true if execution has to be canceled.

Retrieval expression:

    dte:getEvents():getCommandEvents():getOnBeforeExecute()

Handler prototype:

    function onBeforeExecute ( groupGuid, commandId )

Handler argument and return types:

    groupGuid: string
    commandId: int
    return: bool

onModeChanged

Occurs when the mode of the development environment (build, run, or debug) is changed.

Retrieval expression:

    dte:getEvents():getDTEEvents():getOnModeChanged()

Handler prototype:

    function onModeChanged ( prevMode )

Handler argument types:

    prevMode:
        dte.vsIDEModeDesign
        dte.vsIDEModeDebug

onBeginShutdown

Occurs when the development environment is closing.

Retrieval expression:

    dte:getEvents():getDTEEvents():getOnBeginShutdown()

Handler prototype:

    function onBeginShutdown()

onMacrosRuntimeReset

Occurs when the common language runtime resets, clearing all global variable data and losing all event connections.

Retrieval expression:

    dte:getEvents():getDTEEvents():getOnMacrosRuntimeReset()

Handler prototype:

    function onMacrosRuntimeReset()

onStartupComplete

Occurs when the environment has completed initializing.

Retrieval expression:

    dte:getEvents():getDTEEvents():getOnStartupComplete()

Handler prototype:

    function onStartupComplete()

onDocumentClosing

Occurs just before a document is closed.

Retrieval expression:

    dte:getEvents():getDocumentEvents():getOnDocumentClosing()

Handler prototype:

    function onDocumentClosing ( document )

Handler argument types:

    document: Document

onDocumentOpened

Occurs after a document is opened.

Retrieval expression:

    dte:getEvents():getDocumentEvents():getOnDocumentOpened()

Handler prototype:

    function onDocumentOpened ( document )

Handler argument types:

    document: Document

onDocumentOpening

Occurs before a document is opened.

Retrieval expression:

    dte:getEvents():getDocumentEvents():getOnDocumentOpening()

Handler prototype:

    function onDocumentOpening ( path, readOnly )

Handler argument types:

    path: string
    readOnly: bool

onDocumentSaved

Occurs when a document is saved.

Retrieval expression:

    dte:getEvents():getDocumentEvents():getOnDocumentSaved()

Handler prototype:

    function onDocumentSaved ( document )

Handler argument types:

    document: Document

onContextChanged

Fired whenever the current process, program, thread, or stack has been changed through the user interface or through the automation model.

Retrieval expression:

    dte:getEvents():getDebuggerEvents():getOnContextChanged()

Handler prototype:

    function onContextChanged ( process, program, thread, frame )

Handler argument types:

    process: Process
    program: Program
    thread: Thread
    frame: StackFrame

onEnterBreakMode

Fired when entering break mode. Return the action which the debugger should perform next.

Retrieval expression:

    dte:getEvents():getDebuggerEvents():getOnEnterBreakMode()

Handler prototype:

    function onEnterBreakMode ( reason )

Handler argument and return types:

    reason:
        dte.dbgEventReasonNone
        dte.dbgEventReasonGo
        dte.dbgEventReasonAttachProgram
        dte.dbgEventReasonDetachProgram
        dte.dbgEventReasonLaunchProgram
        dte.dbgEventReasonEndProgram
        dte.dbgEventReasonStopDebugging
        dte.dbgEventReasonStep
        dte.dbgEventReasonBreakpoint
        dte.dbgEventReasonExceptionThrown
        dte.dbgEventReasonExceptionNotHandled
        dte.dbgEventReasonUserBreak
        dte.dbgEventReasonContextSwitch

    return:
        dte.dbgExecutionActionDefault
        dte.dbgExecutionActionGo
        dte.dbgExecutionActionStopDebugging
        dte.dbgExecutionActionStepInto
        dte.dbgExecutionActionStepOut
        dte.dbgExecutionActionStepOver
        dte.dbgExecutionActionRunToCursor

onEnterDesignMode

Fired when leaving run mode or debug mode, and when the debugger establishes design mode after debugging.

Retrieval expression:

    dte:getEvents():getDebuggerEvents():getOnEnterDesignMode()

Handler prototype:

    function onEnterDesignMode ( reason )

Handler argument types:

    reason:
        dte.dbgEventReasonNone
        dte.dbgEventReasonGo
        dte.dbgEventReasonAttachProgram
        dte.dbgEventReasonDetachProgram
        dte.dbgEventReasonLaunchProgram
        dte.dbgEventReasonEndProgram
        dte.dbgEventReasonStopDebugging
        dte.dbgEventReasonStep
        dte.dbgEventReasonBreakpoint
        dte.dbgEventReasonExceptionThrown
        dte.dbgEventReasonExceptionNotHandled
        dte.dbgEventReasonUserBreak
        dte.dbgEventReasonContextSwitch

onEnterRunMode

Fired when the debugger enters run mode.

Retrieval expression:

    dte:getEvents():getDebuggerEvents():getOnEnterRunMode()

Handler prototype:

    function onEnterRunMode ( reason )

Handler argument types:

    reason:
        dte.dbgEventReasonNone
        dte.dbgEventReasonGo
        dte.dbgEventReasonAttachProgram
        dte.dbgEventReasonDetachProgram
        dte.dbgEventReasonLaunchProgram
        dte.dbgEventReasonEndProgram
        dte.dbgEventReasonStopDebugging
        dte.dbgEventReasonStep
        dte.dbgEventReasonBreakpoint
        dte.dbgEventReasonExceptionThrown
        dte.dbgEventReasonExceptionNotHandled
        dte.dbgEventReasonUserBreak
        dte.dbgEventReasonContextSwitch

onExceptionNotHandled

Thrown before OnEnterBreakMode. Return the action which the debugger should perform next.

Retrieval expression:

    dte:getEvents():getDebuggerEvents():getOnExceptionNotHandled()

Handler prototype:

    function onExceptionNotHandled ( type, name, code, description )

Handler argument and return types:

    type: string
    name: string
    code: int
    description: string
    return:
        dte.dbgExceptionActionDefault
        dte.dbgExceptionActionIgnore
        dte.dbgExceptionActionBreak
        dte.dbgExceptionActionContinue

onExceptionThrown

Thrown before OnEnterBreakMode. Return the action which the debugger should perform next.

Retrieval expression:

    dte:getEvents():getDebuggerEvents():getOnExceptionThrown()

Handler prototype:

    function onExceptionThrown ( type, name, code, description )

Handler argument and return types:

    type: string
    name: string
    code: int
    description: string
    return:
        dte.dbgExceptionActionDefault
        dte.dbgExceptionActionIgnore
        dte.dbgExceptionActionBreak
        dte.dbgExceptionActionContinue

onFindDone

Occurs after a Find-in-files with a results list operation completes.

Retrieval expression:

    dte:getEvents():getFindEvents():getOnFindDone()

Handler prototype:

    function onFindDone ( result, canceled )

Handler argument types:

    result:
        dte.vsFindResultNotFound
        dte.vsFindResultFound
        dte.vsFindResultReplaceAndNotFound
        dte.vsFindResultReplaceAndFound
        dte.vsFindResultReplaced
        dte.vsFindResultPending
        dte.vsFindResultError
    canceled: bool

onItemAdded

Occurs immediately after you add a project to a solution or an item to a project.

Retrieval expression:

    dte:getEvents():getProjectItemsEvents():getOnItemAdded()

Handler prototype:

    function onItemAdded ( item )

Handler argument types:

    item: ProjectItem

onItemRemoved

Occurs immediately after you remove a project from a solution or a project item from a project.

Retrieval expression:

    dte:getEvents():getProjectItemsEvents():getOnItemRemoved()

Handler prototype:

    function onItemRemoved ( item )

Handler argument types:

    item: ProjectItem

onItemRenamed

Occurs immediately after you rename a project in a solution or a project item in a project.

Retrieval expression:

    dte:getEvents():getProjectItemsEvents():getOnItemRenamed()

Handler prototype:

    function onItemRenamed ( item, oldName )

Handler argument types:

    item: ProjectItem
    oldName: string

onChange

Occurs after the selection model changes.

Retrieval expression:

    dte:getEvents():getSelectionEvents():getOnChange()

Handler prototype:

    function onChange()

onAfterClosing

Occurs immediately after closing a solution.

Retrieval expression:

    dte:getEvents():getSolutionEvents():getOnAfterClosing()

Handler prototype:

    function onAfterClosing()

onBeforeClosing

Occurs immediately before closing a solution.

Retrieval expression:

    dte:getEvents():getSolutionEvents():getOnBeforeClosing()

Handler prototype:

    function onBeforeClosing()

onOpened

Occurs immediately after opening a solution or project.

Retrieval expression:

    dte:getEvents():getSolutionEvents():getOnOpened()

Handler prototype:

    function onOpened()

onProjectAdded

Occurs immediately after adding a project to the solution.

Retrieval expression:

    dte:getEvents():getSolutionEvents():getOnProjectAdded()

Handler prototype:

    function onProjectAdded ( project )

Handler argument types:

    project: Project

onProjectRemoved

Occurs after you remove a project from the solution.

Retrieval expression:

    dte:getEvents():getSolutionEvents():getOnProjectRemoved()

Handler prototype:

    function onProjectRemoved ( project )

Handler argument types:

    project: Project

onProjectRenamed

Occurs after you rename a project in the solution.

Retrieval expression:

    dte:getEvents():getSolutionEvents():getOnProjectRenamed()

Handler prototype:

    function onProjectRenamed ( project, oldName )

Handler argument types:

    project: Project
    oldName: string

onQueryCloseSolution

Occurs before the BeforeClosing. Return true to cancel.

Retrieval expression:

    dte:getEvents():getSolutionEvents():getOnQueryCloseSolution()

Handler prototype:

    function onQueryCloseSolution()

Handler argument and return types:

    return: bool

onRenamed

Occurs after you rename a solution.

Retrieval expression:

    dte:getEvents():getSolutionEvents():getOnRenamed()

Handler prototype:

    function onRenamed ( oldName )

Handler argument types:

    oldName: string

onTaskAdded

Occurs when a new item is added to the Task List.

Retrieval expression:

    dte:getEvents():getTaskListEvents():getOnTaskAdded()

Handler prototype:

    function onTaskAdded ( taskItem )

Handler argument types:

    taskItem: TaskItem

onTaskModified

Occurs when an item in the Task List is modified.

Retrieval expression:

    dte:getEvents():getTaskListEvents():getOnTaskModified()

Handler prototype:

    function onTaskModified ( taskItem, columnModified )

Handler argument types:

    taskItem: TaskItem
    columnModified:
        dte.vsTaskListColumnPriority
        dte.vsTaskListColumnGlyph
        dte.vsTaskListColumnCheck
        dte.vsTaskListColumnDescription
        dte.vsTaskListColumnFile
        dte.vsTaskListColumnLine

onTaskNavigated

Occurs immediately before you navigate to the source of an item in the Task List. Return true if you handled the notification.

Retrieval expression:

    dte:getEvents():getTaskListEvents():getOnTaskNavigated()

Handler prototype:

    function onTaskNavigated ( taskItem )

Handler argument types:

    taskItem: TaskItem
    return: bool

onTaskRemoved

Occurs when a task is removed from the Task List.

Retrieval expression:

    dte:getEvents():getTaskListEvents():getOnTaskRemoved()

Handler prototype:

    function onTaskRemoved ( taskItem )

Handler argument types:

    taskItem: TaskItem

onWindowActivated

Occurs when a window receives the focus.

Retrieval expression:

    dte:getEvents():getWindowEvents():getOnWindowActivated()

Handler prototype:

    function onWindowActivated ( newActive, oldActive )

Handler argument types:

    newActive: Window
    oldActive: Window

onWindowClosing

Occurs just before a window closes.

Retrieval expression:

    dte:getEvents():getWindowEvents():getOnWindowClosing()

Handler prototype:

    function onWindowClosing ( window )

Handler argument types:

    window: Window

onWindowCreated

Occurs when a new window is created.

Retrieval expression:

    dte:getEvents():getWindowEvents():getOnWindowCreated()

Handler prototype:

    function onWindowCreated ( window )

Handler argument types:

    window: Window

onWindowMoved

Occurs after a window is moved or resized.

Retrieval expression:

    dte:getEvents():getWindowEvents():getOnWindowMoved()

Handler prototype:

    function onWindowMoved ( window, top, left, width, height )

Handler argument types:

    window: Window
    top: int
    left: int
    width: int
    height: int

Table of Contents


Copyright (C) 2012-2015 Soft-Erg. All rights reserved.