Hinzufügen von Visual Studio-Befehlen

  • Artikel

Ein durch die Command Klasse dargestellter Befehl ist eine Aktion, die von einem Benutzer initiiert werden kann, z. B. wenn der Benutzer ein Menüelement auswählt, eine Symbolleistenschaltfläche drückt oder eine Tastenkombination eingibt. Befehle haben einen Anzeigenamen, eine Ausführungsmethode (ExecuteCommandAsync), die die Aktion ausführt, ein Symbol für die Anzeige in der Symbolleiste, um den Befehl zu identifizieren, und eine QuickInfo zur Erläuterung des Befehls für den Benutzer. Befehle können je nach verschiedenen Bedingungen aktiviert oder deaktiviert werden.

Befehle im neuen Erweiterbarkeitsmodell werden asynchron ausgeführt, damit der Benutzer weiterhin mit der IDE interagieren kann, während Befehle ausgeführt werden.

Arbeiten mit Befehlen

In dieser Übersicht werden die folgenden wichtigsten Szenarien für das Arbeiten mit Befehlen behandelt:

Befehl erstellen

Das Erstellen eines Befehls mit dem neuen Erweiterbarkeitsmodell beginnt mit dem Erweitern der Basisklasse Command, dem Schmücken der Klasse mit dem VisualStudioContribution Attribut und der Implementierung der CommandConfiguration Eigenschaft.

[VisualStudioContribution]
public class MyCommand : Command
{
  /// <inheritdoc />
  public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%");
}

CommandConfiguration-Klasse

Die CommandConfiguration Klasse verfügt über einige Parameter, mit denen Sie vertraut sein sollten:

Parameter Type Erforderlich Beschreibung
DisplayName Zeichenfolge Ja Der Standardanzeigename des Befehls. Umgeben Sie diese Zeichenfolge mit dem Zeichen "%", um die Lokalisierung dieser Zeichenfolge zu aktivieren. Siehe " Lokalisieren von Metadaten".
ToolTipText String Nein Der Text, der als QuickInfo angezeigt werden soll, wenn der Befehl mit dem Mauszeiger oder dem Fokus angezeigt wird. Umgeben Sie diese Zeichenfolge mit dem Zeichen "%", um die Lokalisierung dieser Zeichenfolge zu aktivieren. Siehe " Lokalisieren von Metadaten"
Flags CommandFlags Nein Flags zum Festlegen zusätzlicher Eigenschaften für den Befehl. Einige Optionen umfassen CanToggle und CanSelect. Siehe unter "Befehlskennzeichnungen".
Positionierung CommandPlacement[] Nein Gibt die vorhandenen Gruppen in Visual Studio an, zu denen der Befehl übergeordnet wird. Weitere Informationen finden Sie unter " Platzieren eines Befehls in der IDE". Auch ohne Platzierung steht Ihr Befehl weiterhin über das Visual Studio-Suchfeature zur Verfügung. Befehle können auch in Menüs, Symbolleisten und Gruppen platziert werden, die in Der Erweiterung definiert sind.
Schaltfläche CommandIconConfiguration Nein Befehle können auf der Benutzeroberfläche als nur ein Symbol, ein Symbol mit Text oder nur Text angezeigt werden. Diese Eigenschaft konfiguriert, was dieses Symbol sein soll, falls vorhanden, und wie es angezeigt werden soll.
Verknüpfungen CommandShortcutConfiguration[] Nein Definiert den Satz von Tastenkombinationen, die zum Ausführen des Befehls verwendet werden können. Tastenkombinationen können nur auf bestimmte IDE-Kontexte angewendet werden. Siehe tastenkombinationen.
ClientContexts[] String Nein Vom Befehl angeforderte Clientkontexte. Standardmäßig werden die Shell- und Editorkontexte zurückgegeben. Ein Clientkontext ist ein Momentaufnahme IDE-Status zum Zeitpunkt der ursprünglichen Ausführung eines Befehls. Da diese Befehle asynchron ausgeführt werden, kann sich dieser Zustand zwischen dem Zeitpunkt ändern, zu dem der Benutzer den Befehl ausgeführt hat, und dem ausgeführten Befehlshandler. Siehe unter Clientkontexten.

Beispiel

Der Command Konstruktor benötigt außerdem einen Konstruktor, der das VisualStudioExtensibility Objekt verwendet (was die Kommunikation mit der IDE zulässt) und eine Ausführungsmethode ExecuteCommandAsync. Das folgende Beispiel bietet eine minimale Implementierung eines generischen Befehls, der nichts tut:

[VisualStudioContribution]
public class MyCommand : Command
{
    /// <inheritdoc />
    public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%");

    public MyCommand(VisualStudioExtensibility extensibility)
        : base(extensibility)
    {
    }

    public override Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }
}

Platzieren eines Befehls in der IDE

Es gibt eine Reihe von gut definierten Stellen in Visual Studio, an denen Befehle platziert werden können. Diese Platzierungen werden durch die Eigenschaft KnownPlacements für die Klasse CommandPlacementdefiniert. Der aktuelle Satz von KnownPlacements ist:

  • ToolsMenu – Der Befehl wird in einer Gruppe unter dem Menü "Extras" auf oberster Ebene in Visual Studio platziert.
  • ViewOtherWindowsMenu – Der Befehl wird in einer Gruppe unter dem Menü "Ansicht"> der obersten Ebene " "Andere Windows" in Visual Studio platziert.
  • ExtensionsMenu – Der Befehl wird in Einer Gruppe unter dem Menü "Erweiterungen" der obersten Ebene in Visual Studio platziert.

Befehle können auch mithilfe der CommandPlacement.VsctParent Methode platziert werden, indem sie die Guid über VSCT definierte Gruppe und Id die Gruppe angeben.

Befehle, die der gleichen Gruppe zugeordnet sind, werden basierend auf der Eigenschaft ihrer Platzierung Priority relativ zu anderen Befehlen oder Menüs mit derselben Platzierung sortiert. Der Standardwert Priority für eine CommandPlacement Datei ist 0 und kann durch Aufrufen der CommandPlacement.WithPriority Methode geändert werden, wobei der gewünschte Priority Wert übergeben wird.

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    // The command will be parented to a group inside of the "Tools" top level menu,
    // a group inside of the "Extensions" top level menu, and the "About" group inside of the "Help" top level menu
    Placements = new CommandPlacement[]
    {
        CommandPlacement.KnownPlacements.ToolsMenu,
        CommandPlacement.KnownPlacements.ExtensionsMenu.WithPriority(0x0100),
        CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 0x016B, priority: 0x0801),
    },
};

Hinzufügen eines Symbols zu einem Befehl

Befehle unterstützen das Hinzufügen von Symbolen zu ihrem Menüelement, entweder zusätzlich oder anstelle des Anzeigenamens des Befehls. Wenn Sie ihrem Befehl ein Symbol hinzufügen möchten, legen Sie die Icon Eigenschaft für den Befehl fest CommandConfiguration.

CommandIconConfiguration

Dies CommandIconConfiguration hat zwei Parameter:

Parameter Type Erforderlich Beschreibung
IconName ImageMoniker Ja Sie können entweder einen benutzerdefinierten Moniker für ein Bild verwenden, das Sie nach dem Abschnitt "Hinzufügen von benutzerdefinierten Bildern " hinzugefügt haben, oder auf einen Visual Studio ImageMoniker verweisen, z. B. ImageMonikers.KnownValues.AddItem
Symbol Einstellungen Symbol Einstellungen Ja Konfiguriert, wie der Befehl angezeigt wird. Zeigt z. B IconSettings.IconAndText . das Symbol zusammen mit dem Anzeigenamen des Befehls an, während IconSettings.IconOnly nur das Symbol des Befehls und nicht dessen Anzeigename angezeigt werden, wenn er einer Symbolleiste zugeordnet ist.

ImageMoniker.KnownValues-Beispiel

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    Icon = new CommandIconConfiguration(ImageMoniker.KnownValues.Extension, IconSettings.IconAndText),
};

Verwenden eines benutzerdefinierten Bilds für das Befehlssymbol

Sie können benutzerdefinierte Bilder hinzufügen, auf die Sie dann mit benutzerdefinierten Monikern verweisen können, indem Sie die folgenden Schritte ausführen:

  1. Benennen Sie die Bildquelldateien um, um dem %Custom Moniker%.* Muster zu folgen (z. B. MyImage.1.png). Dateien, die demselben Moniker vorangestellt sind, werden alle als Sicherungsquellen für denselben benutzerdefinierten Moniker verwendet. Je nach angeforderter Symbolgröße wird eine andere Quelle verwendet.
    • Beispiel: MyImage.16.16.png (16*16 png), MyImage.20.20.png (a 20*20 png) und MyImage.xaml werden alle als Quellen betrachtet MyImage.
    • Wenn die angeforderte Symbolgröße 16*16 ist, wird MyImage.16.16.png verwendet, wenn die angeforderte Größe 20*20 , MyImage.20.20.png verwendet wird, in allen anderen Fällen Wird MyImage.xaml verwendet.
  2. Fügen Sie alle Bildquelldateien unter Images "Ordner" ein.
    • Der Standardordner für Bildressourcen ist Images, Sie können ihn aber auch anpassen, indem Sie ihn hinzufügen. <ImageAssetsPath>%YourFolder%</ImageAssetsPath>

ImageMoniker.Custom(Beispiel)

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    Icon = new CommandIconConfiguration(ImageMoniker.Custom("MyImage"), IconSettings.IconAndText),
};

Verknüpfungen

Befehle können so konfiguriert werden, dass sie ausgeführt werden, wenn eine bestimmte Tastenkombination verwendet wird. Eine Verknüpfung besteht aus einem oder zwei Akkorden, wobei jeder Akkord aus einem ModifierKey und einem Keybesteht. Mögliche Werte sind ModifierKeyLeftAlt: , Shift, Control, ControlShift, ControlShiftLeftAlt, und None, wo None nur gültig ist, wenn sie im zweiten Akkord einer Verknüpfung verwendet werden. Das gleiche ModifierKey muss nicht für beide Akkorden in einer Verknüpfung verwendet werden. Der Key in einem Akkord verwendete Kann fast jede andere Tastaturtaste sein.

Viele Tastenkombinationen werden bereits in Visual Studio verwendet. Sie sollten nicht dieselbe Verknüpfung mehreren Befehlen zuweisen, da doppelte Bindungen schwer zu erkennen sind und auch zu unvorhersehbaren Ergebnissen führen können. Daher ist es ratsam, die Verfügbarkeit einer Verknüpfung zu überprüfen, bevor Sie sie zuweisen.

Einschränkung für die Tastenkombinationsaktivierung

Eine Aktivierungseinschränkung kann in die Konfiguration einbezogen werden, damit die Verknüpfung in verschiedenen Kontexten verfügbar ist. Diese Aktivierungseinschränkungen werden in Form eines Guid, und in der Regel mit einem Editor definiert. Wenn eine Verknüpfung eine Aktivierungseinschränkung erhält, ist sie nur in diesem bestimmten Kontext verfügbar. Verwenden Sie beispielsweise " Guid {5EFC7975-14BC-11CF-9B2B-00AA00573819}", um die Verknüpfung im Visual Studio-Editor verfügbar zu machen. In diesem Fall wäre die Verknüpfung nur verfügbar, wenn der Visual Studio-Editor fokussiert ist.

Verknüpfungsbeispiel

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    Shortcuts = new CommandShortcutConfiguration[]
    {
        new(ModifierKey.LeftAlt, Key.M),
        new(ModifierKey.ControlShift, Key.Y, ModifierKey.ControlShift, Key.B),
    },
};

Konfigurieren eines Befehls

Sie können die Sichtbarkeit und den Status "Aktiviert/Deaktiviert" eines Befehls konfigurieren und zusätzliche Metadaten mithilfe von Flags festlegen.

Sichtbarkeit

Die Sichtbarkeit eines Befehls kann gesteuert werden, indem die Eigenschaft für den VisibleWhen Befehl CommandConfigurationfestgelegt wird.

Das Attribut unterstützt die Angabe einer Bedingung über eine Reihe einzelner Parameter, die zusammen die Bedingung und alle zugehörigen Logik und Eingaben angeben. Um die Bedingung anzugeben, geben Sie einen Ausdruck in einem Parameter an, definieren einen Satz von Ausdrücken (Zeichenfolgen), die im Ausdruck in einem anderen Parameter verwendet werden, und mit welchen Werten diese Ausdrücke bei der Auswertung in einem dritten Parameter ersetzt werden sollen. Die Kombination aus Ausdruck, Ausdrücken und Werten wird als regelbasierte Aktivierungseinschränkung bezeichnet und wird in regelbasierten Aktivierungseinschränkungen vollständig beschrieben.

Wenn diese Eigenschaft aus Ihrer Konfiguration nicht angegeben wird, ist der Standardwert, dass der Befehl immer sichtbar ist.

Beispiel für Sichtbarkeit

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

Aktiviert/deaktivierter Zustand

Der Status "Aktiviert/Deaktiviert" eines Befehls kann gesteuert werden, indem die Eigenschaft für die EnabledWhen Befehle CommandConfigurationfestgelegt wird.

Dieser Konfigurationstyp wird als regelbasierte Aktivierungseinschränkung bezeichnet und unter Verwendung regelbasierter Aktivierungseinschränkungen vollständig beschrieben.

Wenn diese Konfiguration von Ihrem Befehl weggelassen wird, wird der Befehl standardmäßig immer aktiviert. Sie können ihren Befehl auch automatisch deaktivieren lassen, wenn er zurzeit ausgeführt wird, indem Sie im Konstruktor Ihrer Befehlsklasse festlegen this.DisableDuringExecution = true; . Durch Festlegen dieser Eigenschaft wird der durch die EnabledWhen Konfiguration definierte aktiviert/deaktivierte Zustand außer Kraft gesetzt, während der Befehl ausgeführt wird.

Beispiel für den Status "Enabled/disabled"

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

Weitere Informationen zu gültigen Begriffswerten finden Sie unter Regelbasierte Aktivierungseinschränkungen.

Befehlskennzeichnungen

Befehlskennzeichnungen helfen beim Definieren zusätzlicher Eigenschaften für Ihre Befehle, die zur Laufzeit verwendet werden, um spezielle Verhaltensweisen zu definieren, die Ihr Befehl haben kann. Die derzeit unterstützten Flags sind:

  • CanToggle – Gibt an, dass sich die IsChecked Eigenschaft des Befehls ändern kann, sodass Bildschirmsprachausgaben den Befehl ordnungsgemäß ankündigen können. Funktionell stellt sie sicher, dass die Automatisierungseigenschaft IsTogglePatternAvailable für das UI-Element "true" zurückgibt.
  • CanSelect – Gibt an, dass sich die IsChecked Eigenschaft des Befehls ändern kann, sodass Bildschirmsprachausgaben den Befehl ordnungsgemäß ankündigen können. Funktionell stellt sie sicher, dass die Automatisierungseigenschaft IsSelectionPatternAvailable für das UI-Element "true" zurückgibt.

Ändern des Anzeigenamens eines Befehls

Während der Anzeigename für einen Befehl anfänglich im CommandConfiguration Feld "Erstellen eines Befehls" festgelegt ist, kann er zur Laufzeit geändert werden, indem die DisplayName Eigenschaft in Ihrem Befehl festgelegt wird. Die ToolTipText Eigenschaft kann auf ähnliche Weise aktualisiert werden.

DisplayName-Beispiel ändern

[VisualStudioContribution]
public class MyCommand : Command
{
    /// <inheritdoc />
    public override CommandConfiguration CommandConfiguration => new("Initial Display Name");

    public MyCommand(VisualStudioExtensibility extensibility)
     : base(extensibility)
    {
    }

    public override Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        // Update the command's Display Name
        this.DisplayName = "Updated Display Name";
        return Task.CompletedTask;
    }
}

Nächste Schritte