Edit

Share via

Rule-based activation constraints

  • Article

One of the common concepts in VisualStudio.Extensibility is the use of context-based activation rules. These rules govern the conditions under which an extension or a command is surfaced to the user. An example of a context-based activation rule is the VisibleWhen property in a command's configuration that declares when the command is made visible.

Constraint types

Each constraint is defined as an instance of the ActivationConstraint type created with one of the ActivationConstraint's factory methods, like ClientContext.

Multiple activation constraints can be combined together using the And, Or, and Not methods. You can also combine activation constraints using operators &, |, and !.

Example definition

In the following example, the command configuration property EnabledWhen defines when the command is in the enabled state. The ClientContext method is one of the activation constraint factory methods. It generates the activation constraint, given the two arguments, a string and regular expression pattern to match against that string. Therefore, the following code indicates that a command is enabled when the user selects a file with one of those extensions.

public override CommandConfiguration CommandConfiguration => new("%My command.DisplayName%")
{
    EnabledWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveSelectionFileName, @"\.(jpg|jpeg|txt)$"),
};

The ClientContextKey class provides the range of IDE state information that you can test against; for a table of values, see Client context keys.

The following example shows how to combine multiple constraints:

EnabledWhen = ActivationConstraint.And(
    ActivationConstraint.SolutionState(SolutionState.Exists),
    ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveEditorFileName, @"\.(jpg|jpeg|txt)$")),

or, more succinctly, using the & operator:

EnabledWhen =
    ActivationConstraint.SolutionState(SolutionState.Exists) &
    ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveEditorFileName, @"\.(jpg|jpeg|txt)$")),

Activation constraint properties

Activation constraints can be used to configure a variety of VisualStudio.Extensibility functionalities, including the loading of an extension, and the enabled or visible state of a command. The configuration types contain property of type ActivationConstraint, typically with a When suffix that implies that something activates when the specified conditions are satisfied.

Activation constraint factory methods

This section shows the list of currently supported activation constraints. Each entry on the list is a factory method on the ActivationConstraint type.

Term Description
ClientContext(<key>=ClientContextKey, <pattern>=<regex>) True when the provided client context key matches to regular expression. See client context keys.
ActiveProjectCapability(<expression>=ProjectCapability) True whenever solution has a project with capabilities matching the provided subexpression. An expression can be something like VB | CSharp. For more about project capabilities, see Project query API overview.
ProjectAddedItem(<pattern>=<regex>) The term is true when a file matching the "pattern" is added to a project in the solution that is opened.
SolutionHasProjectCapability(<expression>=ProjectCapability) True whenever solution has a project with capabilities matching the provided subexpression. An expression can be something like VB | CSharp. For more about project capabilities, see Project query API overview.
SolutionState(<state>=SolutionState) True when solution state matches the provided value, see solution states for list of values.
EditorContentType(<contentType>) True when active editor content type is or inherits from specific content type.

For compatibility reasons, the following legacy activation constraints are also supported:

Term Description
ActiveProjectBuildProperty(<property>=<regex>) The term is true when the selected project has the specified build property and the property value matches the regex pattern provided.
ActiveProjectFlavor(<guid>) True whenever the selected project has a flavor matching the given project type GUID.
SolutionHasProjectBuildProperty(<property>=<regex>) The term is true when solution has a loaded project with the specified build property and property value matches to regex filter provided.
SolutionHasProjectFlavor(<guid>) True whenever a solution has project that is flavored (aggregated) and has a flavor matching the given project type GUID.
UIContext(<guid>) True when specified UI Context is active in Visual Studio instance.

Solution states

The solution state refers to the state of the solution and its projects, whether a solution is loaded, whether it has zero, one, or multiple projects, and whether it is building.

Activation constraints that correspond to solution states can be combined in the same way as any other activation constraints. For example, you can combine an activation constraint that specifies a FullyLoaded solution and a SingleProject solution to capture single-project solutions when they are fully loaded.

this.EnabledWhen = ActivationConstraint.And(
    ActivationConstraint.SolutionState(SolutionState.SingleProject),
    ActivationConstraint.SolutionState(SolutionState.FullyLoaded));

Client context keys

Activation rules can also utilize the client context contents as parts of its expression.

Currently, the client context is limited to a small set of values in IDE state.

Related content