handling-build-events

Handling Build Events in Visual Studio Extensions

When your extension needs to react to solution or project builds — for example, running analysis after a successful build, showing a notification on failure, or tracking build timing — you need to subscribe to build events. Visual Studio provides multiple mechanisms across its extensibility models.

Build events let extensions integrate into the development feedback loop — the moment code compiles, your extension can validate output, update UI, or trigger downstream processes. The critical nuance is that build event handlers run on the UI thread, so long-running work freezes the IDE.

When to use this vs. alternatives:

• React to build start, completion, or failure → this skill
• React to solution/project open, close, or rename → vs-solution-events
• Surface build errors/warnings in the Error List → vs-error-list
• Show progress during a long custom build step → vs-background-tasks-progress
• Intercept the Build command itself (before it runs) → vs-command-intercept

Decision guide: which build event API to use

Approach	Scope	Key feature
VisualStudio.Extensibility	Out-of-process	No dedicated build event API yet — use activation constraints or in-proc hybrid
Community Toolkit VS.Events.BuildEvents	In-process	Simple .NET events wrapping IVsUpdateSolutionEvents2
VSSDK IVsUpdateSolutionEvents / IVsUpdateSolutionEvents2	In-process	Full control — solution-level build begin/done, per-project begin/done, cancel
DTE BuildEvents (EnvDTE)	In-process (legacy)	COM automation events — OnBuildBegin, OnBuildDone, OnBuildProjConfigBegin/Done

Recommendation: For in-process extensions, use the Community Toolkit (VS.Events.BuildEvents) for the simplest subscription model. Fall back to VSSDK IVsUpdateSolutionEvents2 when you need to cancel builds or access configuration-level details. The VisualStudio.Extensibility model does not yet have a dedicated build events API.

---

1. VisualStudio.Extensibility (out-of-process, recommended)

The VisualStudio.Extensibility SDK does not currently provide a dedicated API for subscribing to build events from out-of-process extensions.

Workaround: activation constraints

You can use ActivationConstraint.SolutionState or other activation constraints to control when your extension components become active based on solution state, but these are not build event callbacks.

Workaround: in-proc hybrid extension

If you need to react to build events from an Extensibility extension, use an in-proc hybrid approach:

[VisualStudioContribution]
internal class MyExtension : Extension
{
    public override ExtensionConfiguration? ExtensionConfiguration => new()
    {
        RequiresInProcessHosting = true,
    };
}

Then use the Toolkit or VSSDK APIs described in sections 2 and 3 below.

---

2. VSIX Community Toolkit (in-process)

The Toolkit wraps IVsUpdateSolutionEvents2 into simple .NET events accessible via VS.Events.BuildEvents.

NuGet package: Community.VisualStudio.Toolkit Key namespace: Community.VisualStudio.Toolkit

Subscribe to build events

public sealed class MyExtensionPackage : ToolkitPackage
{
    protected override async Task InitializeAsync(
        CancellationToken cancellationToken, IProgress<ServiceProgressData> progress)
    {
        await this.RegisterCommandsAsync();

        // Solution-level events
        VS.Events.BuildEvents.SolutionBuildStarted += OnSolutionBuildStarted;
        VS.Events.BuildEvents.SolutionBuildDone += OnSolutionBuildDone;
        VS.Events.BuildEvents.SolutionBuildCancelled += OnSolutionBuildCancelled;

        // Per-project events
        VS.Events.BuildEvents.ProjectBuildStarted += OnProjectBuildStarted;
        VS.Events.BuildEvents.ProjectBuildDone += OnProjectBuildDone;

        // Clean events
        VS.Events.BuildEvents.ProjectCleanStarted += OnProjectCleanStarted;
        VS.Events.BuildEvents.ProjectCleanDone += OnProjectCleanDone;

        // Configuration change events
        VS.Events.BuildEvents.ProjectConfigurationChanged += OnProjectConfigChanged;
        VS.Events.BuildEvents.SolutionConfigurationChanged += OnSolutionConfigChanged;
    }

    private void OnSolutionBuildStarted(object sender, EventArgs e)
    {
        // Solution build has started
    }

    private void OnSolutionBuildDone(bool succeeded)
    {
        // Solution build complete — 'succeeded' is true if no projects failed
        if (!succeeded)
        {
            // Show a notification about build failure
        }
    }

    private void OnSolutionBuildCancelled()
    {
        // User cancelled the build
    }

    private void OnProjectBuildStarted(Project? project)
    {
        // A specific project started building
        string? name = project?.Name;
    }

    private void OnProjectBuildDone(ProjectBuildDoneEventArgs args)
    {
        // A specific project finished building
        string? name = args.Project?.Name;
        bool success = args.IsSuccessful;
    }

    private void OnProjectCleanStarted(Project? project)
    {
        // A project clean operation started
    }

    private void OnProjectCleanDone(ProjectBuildDoneEventArgs args)
    {
        // A project clean operation completed
    }

    private void OnProjectConfigChanged(Project? project)
    {
        // Active project configuration changed (e.g., Debug → Release)
    }

    private void OnSolutionConfigChanged()
    {
        // Active solution configuration changed
    }
}

Available Toolkit build events

Event	Signature	When fired
SolutionBuildStarted	EventHandler	Before any build actions begin
SolutionBuildDone	Action<bool>	After all builds complete (true = all succeeded)
SolutionBuildCancelled	Action	When the user cancels the build
ProjectBuildStarted	Action<Project?>	When a specific project begins building
ProjectBuildDone	Action<ProjectBuildDoneEventArgs>	When a specific project finishes building
ProjectCleanStarted	Action<Project?>	When a project clean begins
ProjectCleanDone	Action<ProjectBuildDoneEventArgs>	When a project clean finishes
ProjectConfigurationChanged	Action<Project?>	When a project's active configuration changes
SolutionConfigurationChanged	Action	When the solution configuration changes

Example: show an InfoBar on build failure

VS.Events.BuildEvents.SolutionBuildDone += async (bool succeeded) =>
{
    if (!succeeded)
    {
        var model = new InfoBarModel(
            "Build failed. Check the Error List for details.",
            KnownMonikers.StatusError,
            isCloseButtonVisible: true);

        InfoBar infoBar = await VS.InfoBar.CreateAsync(model);
        await infoBar.TryShowInfoBarUIAsync();
    }
};

Example: track build timing

private System.Diagnostics.Stopwatch? _buildTimer;

VS.Events.BuildEvents.SolutionBuildStarted += (s, e) =>
{
    _buildTimer = System.Diagnostics.Stopwatch.StartNew();
};

VS.Events.BuildEvents.SolutionBuildDone += async (bool succeeded) =>
{
    _buildTimer?.Stop();
    string status = succeeded ? "succeeded" : "failed";
    await VS.StatusBar.ShowMessageAsync(
        $"Build {status} in {_buildTimer?.Elapsed.TotalSeconds:F1}s");
};

---

3. VSSDK (in-process, legacy)

Use IVsUpdateSolutionEvents2 with IVsSolutionBuildManager to receive build events. This gives you full control, including the ability to cancel a build in UpdateSolution_Begin.

NuGet package: Microsoft.VisualStudio.SDK Key namespaces: Microsoft.VisualStudio.Shell, Microsoft.VisualStudio.Shell.Interop

Implement IVsUpdateSolutionEvents2

public sealed class MyPackage : AsyncPackage, IVsUpdateSolutionEvents2
{
    private uint _buildEventsCookie;
    private IVsSolutionBuildManager2? _buildManager;

    protected override async Task InitializeAsync(
        CancellationToken cancellationToken,
        IProgress<ServiceProgressData> progress)
    {
        await JoinableTaskFactory.SwitchToMainThreadAsync(cancellationToken);

        _buildManager = (IVsSolutionBuildManager2)
            await GetServiceAsync(typeof(SVsSolutionBuildManager));
        _buildManager.AdviseUpdateSolutionEvents(this, out _buildEventsCookie);
    }

    protected override void Dispose(bool disposing)
    {
        ThreadHelper.ThrowIfNotOnUIThread();

        if (_buildEventsCookie != 0 && _buildManager != null)
        {
            _buildManager.UnadviseUpdateSolutionEvents(_buildEventsCookie);
            _buildEventsCookie = 0;
        }

        base.Dispose(disposing);
    }

    // --- Solution-level events ---

    public int UpdateSolution_Begin(ref int pfCancelUpdate)
    {
        // Called before any build actions. Set pfCancelUpdate = 1 to cancel.
        return VSConstants.S_OK;
    }

    public int UpdateSolution_Done(int fSucceeded, int fModified, int fCancelCommand)
    {
        // fSucceeded: 1 if no builds failed
        // fModified: 1 if any build succeeded
        // fCancelCommand: 1 if the build was cancelled
        return VSConstants.S_OK;
    }

    public int UpdateSolution_Cancel()
    {
        // Build was cancelled by the user
        return VSConstants.S_OK;
    }

    // --- Per-project events ---

    public int UpdateProjectCfg_Begin(
        IVsHierarchy pHierProj, IVsCfg pCfgProj,
        IVsCfg pCfgSln, uint dwAction, ref int pfCancel)
    {
        ThreadHelper.ThrowIfNotOnUIThread();

        // dwAction values:
        //   0x010000 = Build
        //   0x100000 = Clean
        //   0x410000 = Rebuild (clean + build)

        pHierProj.GetProperty(
            VSConstants.VSITEMID_ROOT,
            (int)__VSHPROPID.VSHPROPID_Name,
            out object nameObj);
        string projectName = nameObj as string ?? "Unknown";

        return VSConstants.S_OK;
    }

    public int UpdateProjectCfg_Done(
        IVsHierarchy pHierProj, IVsCfg pCfgProj,
        IVsCfg pCfgSln, uint dwAction, int fSuccess, int fCancel)
    {
        // fSuccess: 1 if the project built successfully
        return VSConstants.S_OK;
    }

    // --- Events not typically needed ---

    public int OnActiveProjectCfgChange(IVsHierarchy pIVsHierarchy)
    {
        // Active project or solution configuration changed
        // pIVsHierarchy == null means solution-level config change
        return VSConstants.S_OK;
    }

    public int UpdateSolution_StartUpdate(ref int pfCancelUpdate)
    {
        return VSConstants.S_OK;
    }
}

Alternative: DTE BuildEvents (COM automation)

The older EnvDTE.BuildEvents interface provides COM-style events. Keep a strong reference to the BuildEvents object to prevent garbage collection of the COM event sink.

public sealed class MyPackage : AsyncPackage
{
    private EnvDTE.BuildEvents? _buildEvents; // Must keep a reference!

    protected override async Task InitializeAsync(
        CancellationToken cancellationToken,
        IProgress<ServiceProgressData> progress)
    {
        await JoinableTaskFactory.SwitchToMainThreadAsync(cancellationToken);

        DTE2 dte = (DTE2)await GetServiceAsync(typeof(EnvDTE.DTE));
        _buildEvents = dte.Events.BuildEvents;

        _buildEvents.OnBuildBegin += OnBuildBegin;
        _buildEvents.OnBuildDone += OnBuildDone;
        _buildEvents.OnBuildProjConfigBegin += OnBuildProjConfigBegin;
        _buildEvents.OnBuildProjConfigDone += OnBuildProjConfigDone;
    }

    private void OnBuildBegin(
        EnvDTE.vsBuildScope scope, EnvDTE.vsBuildAction action)
    {
        // scope: vsBuildScopeSolution, vsBuildScopeProject, vsBuildScopeBatch
        // action: vsBuildActionBuild, vsBuildActionRebuildAll, vsBuildActionClean, vsBuildActionDeploy
    }

    private void OnBuildDone(
        EnvDTE.vsBuildScope scope, EnvDTE.vsBuildAction action)
    {
        // Build completed
    }

    private void OnBuildProjConfigBegin(
        string project, string projectConfig, string platform, string solutionConfig)
    {
        // A specific project configuration started building
    }

    private void OnBuildProjConfigDone(
        string project, string projectConfig, string platform,
        string solutionConfig, bool success)
    {
        // A specific project configuration finished building
        // 'success' indicates whether it built successfully
    }
}

Important: Always keep a field reference to the BuildEvents (or any DTE event) object. The COM runtime will garbage-collect the event sink if the only reference is local, causing events to silently stop firing.

---

Guidelines

• Do unsubscribe from build events (UnadviseUpdateSolutionEvents) in Dispose when using the VSSDK approach to prevent leaks.
• Do keep a strong reference to DTE event objects to prevent COM garbage collection.
• Do use ThreadHelper.ThrowIfNotOnUIThread() in event handlers that access IVsHierarchy properties.
• Don't perform long-running work synchronously in build event handlers — queue it on a background thread.
• Don't use EnvDTE.BuildEvents in new extensions — prefer the Toolkit or IVsUpdateSolutionEvents2.
• Prefer VS.Events.BuildEvents (Toolkit) for the simplest subscription model.
• Prefer IVsUpdateSolutionEvents2 over IVsUpdateSolutionEvents — it adds per-project UpdateProjectCfg_Begin/Done methods.
• Note: The dwAction parameter in UpdateProjectCfg_Begin/Done distinguishes between Build (0x010000), Clean (0x100000), and Rebuild (0x410000).

Troubleshooting

• Build events stop firing after a while: The COM runtime garbage-collected your event sink because you only held a local reference. Store the BuildEvents object (DTE) or the advise cookie (IVsSolutionBuildManager) in a class-level field.
• Event handler throws COMException or RPC_E_WRONG_THREAD: You're accessing IVsHierarchy or other COM objects from a background thread. Add ThreadHelper.ThrowIfNotOnUIThread() at the top of your handler.
• UpdateSolution_Done reports success but a project actually failed: Check fSucceeded and fCanceled parameters carefully. fSucceeded == 1 means no errors; fSucceeded == 0 with fCanceled == 0 means there were failures.
• Per-project events not available: You're implementing IVsUpdateSolutionEvents (v1). Switch to IVsUpdateSolutionEvents2 which adds UpdateProjectCfg_Begin and UpdateProjectCfg_Done.
• Events fire but IVsSolutionBuildManager returns stale state: Build state queries during event callbacks may not reflect the final state. If you need post-build results, defer your logic with await Task.Yield() or queue it after the callback returns.

What NOT to do

Do NOT perform long-running work synchronously in build event handlers — they run on the UI thread. Queue background work with JoinableTaskFactory.RunAsync and return immediately.

Do NOT use EnvDTE.BuildEvents — legacy COM API that doesn't integrate with the modern threading model. Use VS.Events.BuildEvents (Toolkit) or IVsUpdateSolutionEvents2 (VSSDK).

Do NOT forget to unsubscribe (UnadviseUpdateSolutionEvents) when your package is disposed — leaked subscriptions cause memory leaks and crashes.

Do NOT hold only a local reference to DTE event objects — COM GC silently stops delivering events. Store in a class-level field.

See also

• vs-solution-events
• vs-error-list
• vs-command-intercept
• vs-async-threading
• vs-background-tasks-progress