通过

基于规则的激活约束

  • 项目

VisualStudio.Extensibility 中的一个常见概念是使用基于上下文的激活规则。 这些规则控制扩展插件或命令向用户显示的条件。 基于上下文的激活规则的一个示例是命令配置中的 VisibleWhen 属性，该属性声明何时向用户显示命令。

约束类型

每个约束都定义为使用其中一个 ActivationConstraint 工厂方法创建的 ActivationConstraint 类型的实例，例如 ClientContext。

可以使用 And、Or 和 Not 方法，将多个激活约束组合在一起。 还可以使用运算符 &、| 和 ! 组合激活约束。

示例定义

在以下示例中，命令配置属性 EnabledWhen 定义命令何时处于启用状态。 ClientContext 方法是激活约束工厂方法之一。 给定两个参数、一个字符串和与该字符串匹配的正则表达式模式，它会生成激活约束。 因此，以下代码表示当用户选择具有这些扩展之一的文件时启用命令。

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

ClientContextKey 类提供可以测试的 IDE 状态信息范围；有关值表，请参阅客户端上下文键。

以下示例演示了如何组合多个约束：

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

或者，更简洁的方式是使用 & 运算符：

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

激活约束属性

激活约束可用于配置 VisualStudio.Extensibility 的各种功能，包括加载扩展插件以及命令的已启用或可见状态。 配置类型包含类型 ActivationConstraint 的属性，通常带有 When 后缀，表示满足指定条件时将激活某些内容。

激活约束工厂方法

本部分显示当前支持的激活约束列表。 列表中的每个条目都是 ActivationConstraint 类型的工厂方法。

术语 说明
ClientContext(<key>=ClientContextKey, <pattern>=<regex>) 如果提供的客户端上下文键与正则表达式匹配，则为 true。 请参阅客户端上下文键。
ActiveProjectCapability(<expression>=ProjectCapability) 如果解决方案具有与所提供子表达式匹配的功能的项目，则为 true。 表达式可以是 VB | CSharp 之类的内容。 有关项目功能的详细信息，请参阅项目查询 API 概述。
ProjectAddedItem(<pattern>=<regex>) 在将与“pattern”匹配的文件添加到打开的解决方案中的项目时，该条件为 true。
SolutionHasProjectCapability(<expression>=ProjectCapability) 如果解决方案具有与所提供子表达式匹配的功能的项目，则为 true。 表达式可以是 VB | CSharp 之类的内容。 有关项目功能的详细信息，请参阅项目查询 API 概述。
SolutionState(<state>=SolutionState) 当解决方案状态与提供的值匹配时，则为 True，有关值列表请参阅解决方案状态。
EditorContentType(<contentType>) 活动编辑器内容类型为或继承自特定内容类型时为 True。

出于兼容性原因，还支持以下旧版激活约束：

术语 说明
ActiveProjectBuildProperty(<property>=<regex>) 如果所选项目具有指定的生成属性，而且属性值与提供的正则表达式模式匹配，则条件为 true。
ActiveProjectFlavor(<guid>) 每当所选项目具有与给定项目类型 GUID 匹配的风格时，条件都将为 true。
SolutionHasProjectBuildProperty(<property>=<regex>) 如果解决方案具有带指定生成属性的已加载项目，并且属性值与提供的正则表达式筛选器匹配，则条件为 true。
SolutionHasProjectFlavor(<guid>) 每当解决方案具有已风格化处理（聚合）的项目，而且具有与给定项目类型 GUID 匹配的风格时，条件为 true。
UIContext(<guid>) 如果指定的 UI 上下文在 Visual Studio 实例中处于活动状态，则为 true。

解决方案状态

解决方案状态是指解决方案及其项目的状态,是加载解决方案、包含零、一个项目还是多个项目，以及是否正在生成解决方案。

与解决方案状态相对应的激活约束可以按照与任何其他激活约束相同的方式进行组合。 例如，可以组合激活约束，指定 FullyLoaded 解决方案和 SingleProject 解决方案，以便在单项目解决方案完全加载时捕获它们。

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

客户端上下文键

激活规则还可以利用客户端上下文内容作为其表达式的一部分。

目前，客户端上下文仅限于 IDE 状态中的一小部分值。

相关内容