Freigeben über

Regelbasierte Aktivierungseinschränkungen

Eines der allgemeinen Konzepte in VisualStudio.Extensibility ist die Verwendung kontextbasierter Aktivierungsregeln. Diese Regeln regeln die Bedingungen, unter denen eine Erweiterung oder ein Befehl für den Benutzer angezeigt wird. Ein Beispiel für eine kontextbasierte Aktivierungsregel ist die Eigenschaft in der VisibleWhen Konfiguration eines Befehls, die deklariert, wenn der Befehl sichtbar gemacht wird.

Einschränkungstypen

Jede Einschränkung wird als Instanz des ActivationConstraint-Typs definiert, der mit einer der Fabrikmethoden von ActivationConstraint, wie zum Beispiel ClientContext, erstellt wurde.

Mehrere Aktivierungseinschränkungen können mithilfe der Methoden And, Or und Not kombiniert werden. Sie können Aktivierungseinschränkungen auch mithilfe von Operatoren &, |, und ! kombinieren.

Beispieldefinition

Im folgenden Beispiel definiert die Befehlskonfigurationseigenschaft EnabledWhen , wann sich der Befehl im aktivierten Zustand befindet. Die ClientContext Methode ist eine der Methoden der Aktivierungseinschränkungs-Factory. Sie generiert die Aktivierungseinschränkung basierend auf den beiden Argumenten: einer Zeichenfolge und einem regulären Ausdrucksmuster, das mit dieser Zeichenfolge abgeglichen wird. Daher gibt der folgende Code an, dass ein Befehl aktiviert ist, wenn der Benutzer eine Datei mit einer dieser Erweiterungen auswählt.

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

Die ClientContextKey Klasse stellt den Bereich der IDE-Statusinformationen bereit, mit denen Sie testen können. Eine Tabelle mit Werten finden Sie unter Clientkontextschlüssel.

Das folgende Beispiel zeigt, wie mehrere Einschränkungen kombiniert werden:

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

oder kurz gesagt, indem Sie den &-Operator verwenden:

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

Eigenschaften der Aktivierungseinschränkung

Aktivierungseinschränkungen können verwendet werden, um eine Vielzahl von VisualStudio.Extensibility-Funktionen zu konfigurieren, einschließlich des Ladens einer Erweiterung und des aktivierten oder sichtbaren Zustands eines Befehls. Die Konfigurationstypen enthalten eigenschaft des Typs ActivationConstraint, in der Regel mit einem When Suffix, das impliziert, dass etwas aktiviert wird, wenn die angegebenen Bedingungen erfüllt sind.

Faktormethoden für Aktivierungseinschränkungen

In diesem Abschnitt wird die Liste der derzeit unterstützten Aktivierungseinschränkungen angezeigt. Jeder Eintrag in der Liste ist eine Factorymethode für den ActivationConstraint Typ.

Begriff Description
ClientContext(<key>=ClientContextKey, <pattern>=<regex>) True, wenn der angegebene Clientkontextschlüssel mit dem regulären Ausdruck übereinstimmt. Siehe Clientkontextschlüssel.
ActiveProjectCapability(<Ausdruck>=ProjectCapability) True, wenn eine Lösung ein Projekt mit Funktionen aufweist, die dem bereitgestellten Unterausdruck entsprechen. Ein Ausdruck kann etwa VB | CSharp sein. Weitere Informationen zu Projektfunktionen finden Sie in der Übersicht über die Project-Abfrage-API.
ProjectAddedItem(<pattern>=<regex>) Der Ausdruck gilt als wahr, wenn eine Datei, die dem "Muster" entspricht, zu einem Projekt in der geöffneten Lösung hinzugefügt wird.
SolutionHasProjectCapability(<Ausdruck>=ProjectCapability) True, wenn eine Lösung ein Projekt mit Funktionen aufweist, die dem bereitgestellten Unterausdruck entsprechen. Ein Ausdruck kann etwa wie VB | CSharp sein. Weitere Informationen zu Projektfunktionen finden Sie in der Übersicht über die Project-Abfrage-API.
SolutionState(<state>=SolutionState) True, wenn der Lösungszustand mit dem angegebenen Wert übereinstimmt, finden Sie unter Lösungsstatus eine Liste mit Werten.
EditorContentType(<contentType>) True, wenn der Inhaltstyp des aktiven Editors von einem bestimmten Inhaltstyp ist oder von diesem erbt.

Aus Kompatibilitätsgründen werden auch die folgenden Legacyaktivierungseinschränkungen unterstützt:

Begriff Description
ActiveProjectBuildProperty(<property>=<regex>) Der Ausdruck ist wahr, wenn das ausgewählte Projekt die angegebene Buildeigenschaft aufweist und der Eigenschaftswert mit dem angegebenen Regex-Muster übereinstimmt.
ActiveProjectFlavor(<GUID>) True, wenn das ausgewählte Projekt einen Geschmack aufweist, der der angegebenen Projekttyp-GUID entspricht.
SolutionHasProjectBuildProperty(<property>=<regex>) Der Begriff ist wahr, wenn die Lösung ein geladenes Projekt mit den angegebenen Buildeigenschafts- und Eigenschaftswert-Übereinstimmungen mit dem bereitgestellten regex-Filter aufweist.
SolutionHasProjectFlavor(<GUID>) Immer dann, wenn eine Projektmappe ein Projekt enthält, das aggregiert ist und eine Eigenschaft besitzt, die der angegebenen Projekttyp-GUID entspricht.
UIContext(<GUID>) True, wenn der angegebene UI-Kontext in der Visual Studio-Instanz aktiv ist.

Lösungszustände

Der Lösungsstatus bezieht sich auf den Zustand der Lösung und deren Projekte, ob eine Lösung geladen wird, ob sie null, eins oder mehrere Projekte aufweist und ob sie erstellt wird.

Aktivierungseinschränkungen, die Lösungszuständen entsprechen, können auf die gleiche Weise wie alle anderen Aktivierungseinschränkungen kombiniert werden. Sie können beispielsweise eine Aktivierungseinschränkung kombinieren, die eine FullyLoaded Lösung und eine SingleProject Lösung zum Erfassen von Einzelprojektlösungen angibt, wenn sie vollständig geladen werden.

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

Clientkontextschlüssel

Aktivierungsregeln können auch den Clientkontextinhalt als Teil des Ausdrucks verwenden.

Derzeit ist der Clientkontext auf einen kleinen Satz von Werten im IDE-Zustand beschränkt.

Verwandte Inhalte

  • Last updated on