Добавление команд Visual Studio

  • Статья

Команда, представленная Command классом, — это некоторые действия, которые могут быть инициированы пользователем, например, когда пользователь выбирает пункт меню, нажимает кнопку панели инструментов или вводит сочетание клавиш. Команды имеют отображаемое имя, метод выполнения (ExecuteCommandAsync), выполняющий действие, значок для отображения на панели инструментов для идентификации команды и подсказки, чтобы объяснить команду пользователю. Команды можно включить или отключить в зависимости от различных условий.

Команды в новой модели расширяемости выполняются асинхронно, чтобы пользователь продолжал взаимодействовать с интегрированной среды разработки во время выполнения команд.

Работа с командами

В этом обзоре рассматриваются следующие основные сценарии работы с командами:

Создать команду

Создание команды с новой моделью расширяемости начинается с расширения базового класса, украшения класса Commandатрибутом VisualStudioContribution и реализации CommandConfiguration свойства.

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

Класс CommandConfiguration

Класс CommandConfiguration имеет несколько параметров, с которыми вы должны ознакомиться:

Параметр Type Обязательно Описание
DisplayName String Да Отображаемое имя команды по умолчанию. Заключите эту строку символом "%", чтобы включить локализацию этой строки. См. раздел "Локализация метаданных".
ToolTipText Строка Нет Текст, отображаемый в виде подсказки при наведении указателя мыши или фокуса команды. Заключите эту строку символом "%", чтобы включить локализацию этой строки. См. сведения о локализации метаданных
Флаги CommandFlags No Флаги для задания дополнительных свойств в команде. Некоторые варианты включают CanToggle и CanSelect. См. раздел "Флаги команд".
Размещения CommandPlacement[] No Указывает существующие группы в Visual Studio, в которые будет вложена команда. См. команду в интегрированной среде разработки. Даже без размещения команда по-прежнему будет доступна с помощью функции поиска Visual Studio. Команды также можно поместить в меню, панели инструментов и группы , определенные в расширении.
Icon CommandIconConfiguration No Команды можно отображать в пользовательском интерфейсе как просто значок, значок с текстом или просто текстом. Это свойство настраивает то, что должен быть значок, если он есть, и как он должен отображаться.
Ярлыки CommandShortcutConfiguration[] No Определяет набор сочетаний ключей, которые можно использовать для выполнения команды. Ярлыки можно область вниз, чтобы применяться только к определенным контекстам интегрированной среды разработки. Ознакомьтесь с ярлыками.
ClientContexts[] Строка Нет Контексты клиента, запрошенные командой. По умолчанию возвращаются контексты оболочки и редактора. Контекст клиента — это моментальный снимок определенных состояний интегрированной среды разработки во время выполнения команды. Так как эти команды выполняются асинхронно, это состояние может измениться между временем выполнения команды и обработчиком команд. Ознакомьтесь с контекстами клиента.

Пример

Кроме Command того, требуется конструктор, который принимает VisualStudioExtensibility объект (который позволяет обмену данными с интегрированной среды разработки) и методом ExecuteCommandAsyncвыполнения. В следующем примере представлена минимальная реализация универсальной команды, которая ничего не делает:

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

Размещение команды в интегрированной среде разработки

В Visual Studio есть набор хорошо определенных мест, где можно разместить команды. Эти размещения определяются свойством KnownPlacements класса CommandPlacement. Текущий KnownPlacements набор:

  • ToolsMenu — Команда будет помещена в группу в меню "Сервис" верхнего уровня в Visual Studio.
  • ViewOtherWindowsMenu — Команда будет помещена в группу в меню верхнего уровня "Вид" —> "Другие окна" в Visual Studio.
  • ExtensionsMenu — Команда будет помещена в группу в меню "Расширения" верхнего уровня в Visual Studio.

Команды также можно поместить с помощью метода, указав Guid и Id группу, определенную с помощью CommandPlacement.VsctParent VSCT.

Команды, родительские для той же группы, сортируются по свойству размещения Priority относительно других команд или меню с тем же размещением. Значение по умолчанию Priority для объекта CommandPlacement is 0 и может быть изменено путем вызова CommandPlacement.WithPriority метода, передав требуемого Priority значения.

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

Добавление значка в команду

Команды поддерживают добавление значков в их пункт меню в дополнение или вместо отображаемого имени команды. Чтобы добавить значок в команду, задайте Icon свойство в команде CommandConfiguration.

CommandIconConfiguration

Имеет CommandIconConfiguration два параметра:

Параметр Type Обязательно Описание
IconName ImageMoniker Да Вы можете использовать пользовательский моникер для изображения, добавленного после раздела "Добавление пользовательских образов " или ссылаться на visual Studio ImageMoniker , например ImageMonikers.KnownValues.AddItem
Значок Параметры Значок Параметры Да Настраивает отображение команды. Например IconSettings.IconAndText , отображает значок рядом с отображаемым именем команды, в то время как IconSettings.IconOnly отображается только значок команды, а не displayName, если он родительский элемент на панели инструментов.

Пример ImageMoniker.KnownValues

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

Использование пользовательского образа для значка команды

Вы можете добавить пользовательские изображения, на которые можно ссылаться с помощью пользовательских моникеров, выполнив следующие действия.

  1. Переименуйте исходные файлы изображения, чтобы следовать шаблону %Custom Moniker%.* (например, MyImage.1.png). Файлы, префиксированные с тем же моникером, будут использоваться в качестве резервных источников для одного и того же пользовательского моникера. Другой источник будет использоваться на основе запрошенного размера значка.
    • Например, MyImage.16.16.png (16*16 png), MyImage.20.20.png (20*20 png) и MyImage.xaml все считаются источниками.MyImage
    • Если запрошенный размер значка равен 16*16, будет использоваться MyImage.16.16.png, если запрошенный размер равен 20*20, MyImage.20.20.png будет использоваться во всех остальных случаях MyImage.xaml.
  2. Поместите все исходные файлы образа в Images папку.
    • Папка ресурсов Imagesобраза по умолчанию, но ее можно также настроить, добавив его. <ImageAssetsPath>%YourFolder%</ImageAssetsPath>

Пример ImageMoniker.Custom

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

Ярлыки

Команды можно настроить для выполнения при использовании определенного сочетания ключей. Ярлык состоит из одного или двух аккордов, где каждый аккорд состоит из ModifierKey одного и одного Key. Возможные значения: ModifierKeyLeftAlt, Shift, , ControlShiftControlShiftLeftAltControlи None, где None допустимы только при использовании во втором аккорде ярлыка. То же ModifierKey самое не нужно использовать для обоих аккордов в сочетании клавиш. Используемый Key в аккорде может быть почти любой другой клавишей клавиатуры.

Многие сочетания клавиш уже используются в Visual Studio. Не следует назначать один и тот же ярлык нескольким командам, так как повторяющиеся привязки трудно обнаружить, а также может привести к непредсказуемым результатам. Поэтому рекомендуется проверить доступность ярлыка перед назначением.

Ограничение сочетания клавиш

Ограничение активации можно включить в конфигурацию, чтобы ярлык был доступен в разных контекстах. Эти ограничения активации определяются в виде редактора Guidи обычно относятся к редактору. Если ярлык предоставляет ограничение активации, он будет доступен только в этом конкретном контексте. Например, используйте Guid "{5EFC7975-14BC-11CF-9B2B-00AA00573819}", чтобы сделать ярлык доступным в редакторе Visual Studio. В этом случае ярлык будет доступен только при фокусе редактора Visual Studio.

Пример ярлыка

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

Настройка команды

Вы можете настроить видимость и состояние включенной или отключенной команды и задать дополнительные метаданные с помощью флагов.

Visibility

Видимость команды можно контролировать, задав VisibleWhen свойство в команде CommandConfiguration.

Атрибут поддерживает указание условия с помощью ряда отдельных параметров, которые вместе указывают условие и все его логику и входные данные. Чтобы указать условие, необходимо указать выражение в одном параметре, определить набор терминов (строк), используемых в выражении в другом параметре, и какие значения эти термины следует заменить при оценке в третьем параметре. Сочетание выражения, терминов и значений называется ограничением активации на основе правил и полностью описано в ограничениях активации на основе правил.

Если это свойство не указано в конфигурации, по умолчанию команда всегда отображается.

Пример видимости

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

Состояние "Включено/отключено"

Состояние включенной или отключенной команды можно контролировать, задав EnabledWhen свойство в команде CommandConfiguration.

Этот тип конфигурации называется ограничением активации на основе правил и полностью описан в ограничениях активации на основе правил.

Если эта конфигурация опущена из команды, по умолчанию команда всегда будет включена. Вы также можете автоматически отключить команду, если она выполняется в данный момент, задав this.DisableDuringExecution = true; конструктор класса команд. Установка этого свойства переопределяет состояние включено или отключено, определенное EnabledWhen конфигурацией во время выполнения команды.

Пример состояния включено или отключено

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

Дополнительные сведения о допустимых значениях терминов см. в разделе ограничения активации на основе правил.

Флаги команд

Флаги команд помогают определить дополнительные свойства в командах, которые используются во время выполнения для определения специальных действий, которые могут иметь ваша команда. Поддерживаемые в настоящее время флаги:

  • CanToggle — Указывает, что IsChecked свойство команды может измениться, чтобы средства чтения с экрана могли правильно объявить команду. Функционально это гарантирует, что свойство IsTogglePatternAvailable автоматизации возвращает значение true для элемента пользовательского интерфейса.
  • CanSelect — Указывает, что IsChecked свойство команды может измениться, чтобы средства чтения с экрана могли правильно объявить команду. Функционально это гарантирует, что свойство IsSelectionPatternAvailable автоматизации возвращает значение true для элемента пользовательского интерфейса.

Изменение отображаемого имени команды

Хотя отображаемое имя для команды изначально задано ( CommandConfiguration см. раздел "Создание команды"), его можно изменить во время выполнения, задав DisplayName свойство в команде. Свойство ToolTipText можно обновить аналогичным образом.

Пример изменения DisplayName

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

Следующие шаги