VisualStudio.Extensibility の一般的な概念の 1 つは、コンテキストベースのアクティブ化ルールの使用です。 これらのルールは、拡張機能またはコマンドがユーザーに表示される条件を管理します。 コンテキストベースのアクティブ化ルールの例として、コマンドが表示されるときに宣言するコマンドの構成の VisibleWhen プロパティがあります。
制約の種類
各制約は、ClientContext のような ActivationConstraint のファクトリメソッドのいずれかで作成された ActivationConstraint 型のインスタンスとして定義されています。
複数のアクティブ化制約は、And、Or、および Not メソッドを使用して組み合わせることができます。 また、演算子 &、|、および ! を使用してアクティブ化制約を組み合わせることもできます。
定義の例
次の例では、コマンド構成プロパティ EnabledWhen は、コマンドが有効な状態である場合を定義します。 この ClientContext メソッドは、アクティブ化制約ファクトリ メソッドの 1 つです。 2 つの引数、文字列、およびその文字列に一致する正規表現パターンを指定すると、アクティブ化制約が生成されます。 したがって、次のコードは、ユーザーがそれらの拡張子のいずれかを持つファイルを選択したときにコマンドが有効になっていることを示しています。
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 になります。 |
ソリューションの状態
ソリューションの状態とは、ソリューションとそのプロジェクトの状態、ソリューションが読み込まれるかどうか、ゼロ、1、または複数のプロジェクトがあるかどうか、およびビルドしているかどうかを指します。
ソリューションの状態に対応するアクティブ化制約は、他のアクティブ化制約と同じ方法で組み合わせることができます。 たとえば、FullyLoaded ソリューションを指定するアクティブ化制約と、単一プロジェクト ソリューションが完全に読み込まれたときにキャプチャする SingleProject ソリューションを組み合わせることができます。
this.EnabledWhen = ActivationConstraint.And(
ActivationConstraint.SolutionState(SolutionState.SingleProject),
ActivationConstraint.SolutionState(SolutionState.FullyLoaded));
クライアント コンテキスト キー
アクティブ化ルールでは、クライアント コンテキストの内容を式の一部として利用することもできます。
現在、クライアント コンテキストは IDE 状態の小規模な値のセットに制限されています。