Dodawanie poleceń programu Visual Studio

  • Artykuł

Polecenie reprezentowane przez Command klasę to jakaś akcja, którą można zainicjować przez użytkownika, na przykład gdy użytkownik wybierze element menu, naciśnie przycisk paska narzędzi lub wpisze skrót klawiaturowy. Polecenia mają nazwę wyświetlaną, metodę wykonywania (ExecuteCommandAsync), która wykonuje akcję, ikonę wyświetlania na pasku narzędzi w celu zidentyfikowania polecenia oraz etykietkę narzędzia w celu wyjaśnienia polecenia użytkownikowi. Polecenia można włączać lub wyłączać w zależności od różnych warunków.

Polecenia w nowym modelu rozszerzalności są uruchamiane asynchronicznie, aby użytkownik mógł nadal korzystać ze środowiska IDE podczas wykonywania poleceń.

Praca z poleceniami

To omówienie obejmuje następujące najważniejsze scenariusze pracy z poleceniami:

Utwórz polecenie

Utworzenie polecenia za pomocą nowego modelu rozszerzalności rozpoczyna się od rozszerzenia klasy bazowej , adorowania klasy Commandza pomocą atrybutu VisualStudioContribution i implementowania CommandConfiguration właściwości.

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

CommandConfiguration, klasa

Klasa CommandConfiguration ma kilka parametrów, które należy znać:

Parametr Type Wymagania opis
DisplayName String Tak Domyślna nazwa wyświetlana polecenia. Umieść ten ciąg znakiem "%", aby umożliwić lokalizowanie tego ciągu. Zobacz w temacie Lokalizowanie metadanych.
ToolTipText String Nie Tekst wyświetlany jako etykietka narzędzia po umieszczeniu wskaźnika myszy na poleceniu lub fokusie. Umieść ten ciąg znakiem "%", aby umożliwić lokalizowanie tego ciągu. Zobacz w temacie Lokalizowanie metadanych
Flagi CommandFlags Nie. Flagi ustawiania dodatkowych właściwości w poleceniu. Niektóre opcje to CanToggle i CanSelect. Zobacz w temacie Command Flags (Flagi poleceń).
Miejsca docelowe CommandPlacement[] Nie. Określa istniejące grupy w programie Visual Studio, do których zostanie nadrzędne polecenie. Zobacz w temacie Place a command in the IDE (Umieść polecenie w środowisku IDE). Nawet bez umieszczania polecenie będzie nadal dostępne za pośrednictwem funkcji wyszukiwania programu Visual Studio. Polecenia można również umieszczać w menu, paskach narzędzi i grupach zdefiniowanych w rozszerzeniu.
Icon CommandIconConfiguration Nie. Polecenia mogą być wyświetlane w interfejsie użytkownika jako ikona, ikona z tekstem lub tylko tekst. Ta właściwość konfiguruje, jaka powinna być ikona, jeśli istnieje i jak powinna być wyświetlana.
Skróty CommandShortcutConfiguration[] Nie. Definiuje zestaw kombinacji klawiszy, których można użyć do wykonania polecenia. Skróty można ograniczyć do zakresu, aby dotyczyć tylko określonych kontekstów IDE. Zobacz skróty.
ClientContexts[] String Nie Konteksty klienta żądane przez polecenie . Domyślnie zwracane są konteksty powłoki i edytora. Kontekst klienta to migawka określonych stanów IDE w momencie, gdy polecenie zostało pierwotnie wykonane. Ponieważ te polecenia są wykonywane asynchronicznie, ten stan może ulec zmianie między czasem wykonania polecenia przez użytkownika a uruchomionym programem obsługi poleceń. Zobacz konteksty klienta.

Przykład

Obiekt Command wymaga również konstruktora, który przyjmuje VisualStudioExtensibility obiekt (który umożliwia komunikację ze środowiskiem IDE) i metodę ExecuteCommandAsyncwykonywania . W poniższym przykładzie przedstawiono minimalną implementację ogólnego polecenia, które nie wykonuje żadnych czynności:

[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;
    }
}

Umieszczanie polecenia w środowisku IDE

W programie Visual Studio istnieje zestaw dobrze zdefiniowanych miejsc, w których można umieszczać polecenia. Te umieszczania są definiowane przez właściwość KnownPlacements klasy CommandPlacement. Bieżący zestaw to KnownPlacements :

  • ToolsMenu - Polecenie zostanie umieszczone w grupie w menu "Narzędzia" najwyższego poziomu w programie Visual Studio.
  • ViewOtherWindowsMenu — Polecenie zostanie umieszczone w grupie w menu "Widok" najwyższego poziomu —> "Inne okna" w programie Visual Studio.
  • ExtensionsMenu — Polecenie zostanie umieszczone w grupie w menu "Rozszerzenia" najwyższego poziomu w programie Visual Studio.

Polecenia można również umieścić przy użyciu CommandPlacement.VsctParent metody , określając grupę GuidId i zdefiniowaną za pośrednictwem programu VSCT.

Polecenia nadrzędne dla tej samej grupy są sortowane na podstawie właściwości ich umieszczania Priority względem innych poleceń lub menu z tym samym rozmieszczeniem. Wartość domyślna Priority elementu CommandPlacement to 0 i może zostać zmodyfikowana przez wywołanie CommandPlacement.WithPriority metody , przekazując żądaną Priority wartość.

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),
    },
};

Dodawanie ikony do polecenia

Polecenia obsługują dodawanie ikon do elementu menu, oprócz nazwy wyświetlanej polecenia lub zamiast nazwy wyświetlanej polecenia. Aby dodać ikonę do polecenia, ustaw Icon właściwość w poleceniu CommandConfiguration.

CommandIconConfiguration

Parametr CommandIconConfiguration ma dwa parametry:

Parametr Type Wymagania opis
IconName ImageMoniker Tak Możesz użyć niestandardowego monikera dla obrazu dodanego po sekcji Dodawanie obrazów niestandardowych lub odwołać się do programu Visual Studio ImageMoniker , na przykład ImageMonikers.KnownValues.AddItem
Ikona Ustawienia Ikona Ustawienia Tak Konfiguruje sposób wyświetlania polecenia. Na przykład IconSettings.IconAndText wyświetla ikonę obok nazwy wyświetlanej polecenia, natomiast IconSettings.IconOnly w przypadku elementu nadrzędnego na pasku narzędzi będzie wyświetlana tylko ikona polecenia, a nie jej Nazwa Wyświetlana.

Przykład imageMoniker.KnownValues

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

Używanie obrazu niestandardowego dla ikony polecenia

Możesz dodać obrazy niestandardowe, do których można następnie odwoływać się za pomocą niestandardowych elementów monikers, wykonując następujące kroki:

  1. Zmień nazwę plików źródłowych obrazu, aby postępować zgodnie ze wzorcem %Custom Moniker%.* (na przykład MyImage.1.png). Pliki poprzedzone tym samym pseudonimem będą używane jako źródła kopii zapasowej dla tego samego niestandardowego monikera. Różne źródło będzie używane na podstawie żądanego rozmiaru ikony.
    • Na przykład MyImage.16.16.png (a 16*16 png), MyImage.20.20.png (20*20 png) i MyImage.xaml są traktowane jako źródła dla MyImage.
    • Jeśli żądany rozmiar ikony to 16*16, zostanie użyty obraz MyImage.16.16.png , gdy żądany rozmiar to 20*20, zostanie użyty plik MyImage.20.20.png , we wszystkich innych przypadkach zostanie użyty plik MyImage.xaml .
  2. Umieść wszystkie pliki źródłowe obrazów w Images folderze.
    • Domyślny folder zasobów obrazu to Images, ale można go również dostosować, dodając <ImageAssetsPath>%YourFolder%</ImageAssetsPath>

ImageMoniker.Custom — przykład

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

Skróty

Polecenia można skonfigurować tak, aby były wykonywane, gdy jest używana określona kombinacja klawiszy. Skrót składa się z jednego lub dwóch akordów, gdzie każdy akord składa się z i ModifierKey jeden Key. Możliwe wartości ModifierKey to LeftAlt, , Shift, ControlControlShift, ControlShiftLeftAlti None, gdzie None są prawidłowe tylko wtedy, gdy są używane w drugim akord skrótu. To samo ModifierKey nie musi być używane dla obu akordów w skrótach. Używany Key w akord może być prawie każdy inny klawisz klawiatury.

Wiele skrótów klawiaturowych jest już używanych w programie Visual Studio. Nie należy przypisywać tego samego skrótu do więcej niż jednego polecenia, ponieważ zduplikowane powiązania są trudne do wykrycia i mogą również powodować nieprzewidywalne wyniki. W związku z tym warto sprawdzić dostępność skrótu przed jego przypisaniem.

Ograniczenie aktywacji skrótów

Ograniczenie aktywacji można uwzględnić w konfiguracji, aby skrót był dostępny w różnych kontekstach. Te ograniczenia aktywacji są definiowane w postaci Guidelementu i zwykle odnoszą się do edytora. Po podaniu skrótu ograniczenia aktywacji będzie on dostępny tylko w tym konkretnym kontekście. Na przykład użyj polecenia Guid "{5EFC7975-14BC-11CF-9B2B-00A00573819}", aby udostępnić skrót w edytorze programu Visual Studio. W takim przypadku skrót będzie dostępny tylko wtedy, gdy edytor programu Visual Studio jest skoncentrowany.

Przykładowy skrót

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

Konfigurowanie polecenia

Widoczność i stan włączone/wyłączone polecenia można skonfigurować i ustawić dodatkowe metadane przy użyciu flag.

Widoczność

Widoczność polecenia można kontrolować, ustawiając VisibleWhen właściwość w poleceniu CommandConfiguration.

Atrybut obsługuje określanie warunku za pomocą wielu pojedynczych parametrów, które razem określają warunek i wszystkie jego logiki i dane wejściowe. Aby określić warunek, należy określić wyrażenie w jednym parametrze, zdefiniować zestaw terminów (ciągów) używanych w wyrażeniu w innym parametrze i wartości, które te terminy powinny zostać zastąpione podczas oceny w trzecim parametrze. Kombinacja wyrażeń, terminów i wartości jest nazywana ograniczeniem aktywacji opartym na regułach i jest w pełni opisana w temacie Ograniczenia aktywacji oparte na regułach.

Jeśli ta właściwość zostanie pominięta w konfiguracji, wartością domyślną jest, aby polecenie zawsze było widoczne.

Przykład widoczności

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

Stan włączony/wyłączony

Stan włączone/wyłączone polecenia można kontrolować, ustawiając EnabledWhen właściwość na poleceniu CommandConfiguration.

Ten typ konfiguracji jest nazywany ograniczeniem aktywacji opartym na regułach i jest w pełni opisany w temacie Korzystanie z ograniczeń aktywacji opartych na regułach.

Jeśli ta konfiguracja zostanie pominięta w poleceniu, wartością domyślną jest zawsze włączenie polecenia. Możesz również automatycznie wyłączyć polecenie, jeśli jest ono obecnie wykonywane, ustawiając this.DisableDuringExecution = true; w konstruktorze klasy poleceń. Ustawienie tej właściwości zastępuje stan włączony/wyłączony zdefiniowany przez konfigurację EnabledWhen podczas wykonywania polecenia.

Przykład stanu włączonego/wyłączonego

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

Aby uzyskać więcej informacji na temat prawidłowych wartości terminów, zobacz Ograniczenia aktywacji oparte na regułach.

Flagi poleceń

Flagi poleceń ułatwiają definiowanie dodatkowych właściwości poleceń, które są używane w czasie wykonywania do definiowania specjalnych zachowań, które mogą mieć polecenia. Flagi, które są obecnie obsługiwane, to:

  • CanToggle — Wskazuje, że IsChecked właściwość polecenia może ulec zmianie, aby czytniki zawartości ekranu mogły prawidłowo ogłosić polecenie. Funkcjonalnie zapewnia, że właściwość IsTogglePatternAvailable automatyzacji zwraca wartość true dla elementu interfejsu użytkownika.
  • CanSelect — Wskazuje, że IsChecked właściwość polecenia może ulec zmianie, aby czytniki zawartości ekranu mogły prawidłowo ogłosić polecenie. Funkcjonalnie zapewnia, że właściwość IsSelectionPatternAvailable automatyzacji zwraca wartość true dla elementu interfejsu użytkownika.

Zmienianie nazwy wyświetlanej polecenia

Podczas gdy nazwa wyświetlana polecenia jest początkowo ustawiona w CommandConfiguration obiekcie (zobacz Tworzenie polecenia), można ją zmienić w czasie wykonywania, ustawiając DisplayName właściwość w poleceniu. Właściwość ToolTipText można zaktualizować w podobny sposób.

Zmiana przykładu nazwy wyświetlana

[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;
    }
}

Następne kroki