macro-triggers

name	macro-triggers
description	Trigger syntax for Macros .csx files: events, commands, filters, and header edits
domain	visual-studio-macros
confidence	high
source	derived from docs/triggers.md and CSharpCodeGenerator.EmitHeader

Macro triggers

Add // @trigger lines to the top comment block so a macro runs automatically on IDE events or commands.

When to use this skill

Use this skill when the user wants a macro to run on save, build, solution open, debugger events, or before/after a named Visual Studio command.

Do not use this skill for VSIX event handlers, MEF listeners, command filters, or other extensibility plumbing.

Trigger directive syntax

A trigger is always a top-of-file comment line:

// @trigger Manual
// @trigger Build.SolutionBuildDone
// @trigger Build.SolutionBuildDone when success=false
// @trigger Document.Saved when filename=*.cs
// @trigger BeforeCommand File.Save
// @trigger AfterCommand Build.BuildSolution

Rules:

• Put trigger lines in the header comment block before any executable code
• Multiple trigger lines are OR-combined; any one can start the macro
• If you omit triggers, the macro is effectively manual

Event triggers

Event triggers use {Category}.{EventName}:

// @trigger Build.SolutionBuildDone
// @trigger Document.Saved
// @trigger Document.Opened
// @trigger Solution.OnAfterOpenSolution
// @trigger Debugger.EnterBreakMode

Common categories in this repo include Build, Document, Solution, Debugger, Selection, Window, and Shell. Practical example:

// @trigger Document.Saved when filename=*.cs
#load ".intellisense/Macros.Intellisense.csx"

await ExecuteCommandAsync("Edit.FormatDocument");
await VS.StatusBar.ShowMessageAsync("Formatted after save");

Command triggers

Command triggers attach to named VS commands:

// @trigger BeforeCommand File.Save
// @trigger AfterCommand Build.BuildSolution

Use BeforeCommand to intervene before execution and AfterCommand to react after execution.

// @trigger BeforeCommand File.Save
#load ".intellisense/Macros.Intellisense.csx"

if (DTE.Solution.SolutionBuild.BuildState == EnvDTE.vsBuildState.vsBuildStateInProgress)
{
    await VS.MessageBox.ShowWarningAsync("Macros", "Cannot save during a build.");
    Trigger.CancelCommand();
}

when filters

Add when key=value after the trigger name to narrow when it fires.

Common filters:

• filename=*.cs
• success=false
• project=*Tests*
• exception=*NullReferenceException*

// @trigger Document.Saved when filename=*.cs
// @trigger Build.SolutionBuildDone when success=false
// @trigger Build.ProjectBuildDone when project=*Tests* success=true
// @trigger Debugger.ExceptionThrown when exception=*ArgumentException*

Filter rules:

• Multiple key=value pairs are AND-combined
• filename is a glob, not a regex
• success is a boolean
• Unrecognized keys are ignored by the trigger system

How to add a trigger to an existing macro

Existing file:

// Macro: Format on Save
// Recorded: 2026-05-02T17:10:39Z
// Steps: 1
// Generated by Macros — edit freely.

#load ".intellisense/Macros.Intellisense.csx"
await ExecuteCommandAsync("Edit.FormatDocument");

Add a trigger line inside the header block:

// Macro: Format on Save
// Recorded: 2026-05-02T17:10:39Z
// Steps: 1
// Generated by Macros — edit freely.
// @trigger Document.Saved when filename=*.cs

#load ".intellisense/Macros.Intellisense.csx"
await ExecuteCommandAsync("Edit.FormatDocument");

Do not move the trigger below #load or below executable statements.

Generated EXAMPLE lines

Generated macros include examples like these:

// EXAMPLE: // @trigger Build.SolutionBuildDone
// EXAMPLE: // @trigger Document.Saved when filename=*.cs
// EXAMPLE: // @trigger BeforeCommand File.Save
// EXAMPLE: // @trigger AfterCommand Build.BuildSolution

To activate one, remove only the // EXAMPLE: prefix.

Good trigger recipes

// @trigger Build.SolutionBuildDone when success=false
// @trigger Document.Opened when filename=*.xaml
// @trigger AfterCommand Edit.FormatDocument

Good defaults for Copilot

• Put // @trigger ... in the header block
• Use Document.Saved or Document.Opened for document automation
• Use BeforeCommand only when cancellation/interception matters
• Use AfterCommand for logging or follow-up work
• Add when filters instead of branching later when the condition is simple