Практическое руководство. Создание и настройка команды в VSPackages (C#)
Добавление команды в VSPackage процесс 2 шага. Во-первых, команда идентифицируется как xml-элементы в файле .vsct. Затем она используется в коде. Сведения зарегистрированное в файле .vsct определяет внешний вид команды, своего размещения в интегрированной среде разработки (ide), и какой-либо из его расширениях функциональности. Команда затем задается в коде, обычно a MenuCommand или a OleMenuCommand объект и его обработчики событий реализованы.
Команды, VSPackage делает доступным в интегрированной среде разработки должны быть видимыми и включаются, прежде чем пользователь может их использования. Если команды создаются в файле .vsct с помощью шаблона проекта пакета Visual Studio, они являются видимыми и включен по умолчанию. Некоторые флаги команды, как устанавливать DynamicItemStartможет изменяться по умолчанию применяются расширения функциональности. Видимость, включенное состояние и другие свойства команды можно также изменить в коде во время выполнения, обратившись к OleMenuCommand объект, связанный с командой.
Создание команды
Все команды, группы команд меню, панели инструментов и окна инструментов определяются в файле .vsct. Если в VSPackage не содержит файла .vsct, необходимо добавить. Дополнительные сведения см. в разделе Файлы таблицы команд Visual Studio (.Vsct).
При создании VSPackage с помощью шаблона пакетов, то инструкции select Команда меню создание файла .vsct и определить по умолчанию команду меню. Дополнительные сведения см. в разделе Пошаговое руководство: Создание команды меню ресурсов с помощью шаблона пакета Visual Studio.
Добавление команды в интегрированной среде разработки
Откройте файл .vsct.
в Symbols раздел находит GuidSymbol элемент, содержащий группы и команд.
Создание IDSymbol элемент для каждого меню, группы или команды, который требуется добавить, как показано в следующем примере.
<GuidSymbol name="guidButtonGroupCmdSet" value="{f69209e9-975a-4543-821d-1f4a2c52d737}"> <IDSymbol name="MyMenuGroup" value="0x1020" /> <IDSymbol name="cmdidMyCommand" value="0x0100" /> </GuidSymbol>name атрибуты GuidSymbol и IDSymbol элементы предоставляют GUID: Пары идентификатор для всех новых меню, группы или команды. guid представляет набор команд, который определен в VSPackage. Можно определить несколько наборов команд. Каждый идентификатор GUID: Пары идентификатор должен быть уникальным.
в Кнопки раздел создает a кнопка элемент для указания команды, как показано в следующем примере.
<Button guid="guidButtonGroupCmdSet" id="cmdidMyCommand" priority="0x0100" type="Button"> <Parent guid="guidButtonGroupCmdSet" id="MyMenuGroup" /> <Icon guid="guidImages" id="bmpPic1" /> <Strings> <CommandName>cmdidMyCommand</CommandName> <ButtonText>My Command name</ButtonText> </Strings> </Button>Установка guid и id поля, чтобы сопоставить идентификатор GUID: Идентификатор новой команды.
Необходимо задать атрибут priority.
priority атрибут используется .vsct для определения положения кнопки среди других объектов в его родительской группе.
Команды, имеющих значения более низким приоритетом выше или отображаются слева от команды, имеющих значения с более высоким приоритетом. Дублирующиеся значения приоритета разрешены, но относительное положение команд, которые имеют одинаковый приоритет определяется порядком, в котором VSPackages обрабатывается во время выполнения, и котором заказ невозможно предопределить.
Пропуск priority наборы атрибутов также его значение равным 0.
Необходимо задать атрибут type. В большинстве случаев его значение будет "Кнопка". Описание других допустимых типов кнопки см. в разделе Элемент Button.
В определении кнопки, create a Строки элемент, содержащий a ButtonText элемент, содержащий имя меню, отображаемое в интегрированную среду разработки и a CommandName элемент, содержащий имя команды, которая используется для доступа к меню команда окна.
Если текстовая строка кнопки включает знак "&", то пользователь может открыть меню, нажав клавиши ALT + знак, который следует непосредственно за "&".
Добавление a Tooltip элемент вызовет, которые содержат текст отображаться, когда пользователь наводит указатель мыши на кнопку.
Добавление Значок элемент для определения значка, если таковые имеются, должны отображаться с командой. Значки, необходимые для кнопок в панели инструментов, но не для пунктов меню. guid и idIcon элемент должен совпадать с a растровое изображение элемент, определенный в Bitmaps раздел.
Добавьте флаги команды, чтобы изменить внешний вид и реакция на событие кнопки. Для этого добавьте a CommandFlag элемент в определении меню.
Задайте родительскую группу в составе команды. Родительская группа может быть группой, созданной из другого пакета, группой или группой из интегрированной среды разработки. Например, ваша команда добавить в Visual Studio, рядом с панели редактирования инструментов Примечание и удалите комментарий кнопки задать родительский объект для guidStdEditor: IDG_VS_EDITTOOLBAR_COMMENT. Если родительский определяемую пользователем группу, оно должно быть дочерним элементом меню, панели инструментов или окна инструментов, которое отображается в интегрированную среду разработки.
Это можно сделать одним из способов 2, в зависимости от конструкции:
в Button создает элемент, a Родительский элемент элемент и присвойте его guid и id поля и идентификатор Guid группы, которая будет узел команда, также известного как родительская группа primary.
Следующий пример определяет команду, которая будет отображаться на определенное пользователем меню.
<Button guid="guidTopLevelMenuCmdSet" id="cmdidTestCommand" priority="0x0100" type="Button"> <Parent guid="guidTopLevelMenuCmdSet" id="MyMenuGroup" /> <Icon guid="guidImages" id="bmpPic1" /> <Strings> <CommandName>cmdidTestCommand</CommandName> <ButtonText>Test Command</ButtonText> </Strings> </Button>Можно опустить Parent если команда элемент следует поместить с помощью размещения команды. Create a CommandPlacements элемент перед Symbols раздел и добавляет a CommandPlacement элемент, имеющий guid и id команды, a priorityи родительского, как показано в следующем примере.
<CommandPlacements> <CommandPlacement guid="guidButtonGroupCmdSet" id="cmdidMyCommand" priority="0x105"> <Parent guid="guidButtonGroupCmdSet" id="MyMenuGroup" /> </CommandPlacement> </CommandPlacements>Создание нескольких размещения команды, имеющих один и тот же идентификатор GUID: Идентификатор и имеет разные причины родительскиев меню, которая будет отображаться на несколько расположений. Дополнительные сведения см. в разделе CommandPlacements элемент.
Дополнительные сведения о группах команды и parenting см. в разделе Практическое руководство. Создание многократно используемые группы кнопок.
На этом этапе команда будет видна в интегрированной среде разработки, но не содержит никаких функций. Если команда была создана помощью шаблона пакетов по умолчанию, то она будет иметь обработчик click, указывающее сообщение.
Обработка новой команды
Большинство команд в управляемом коде могут обрабатываться управляемый пакетом .NET Framework (MPF), сопоставление команды with a MenuCommand объект или OleMenuCommand объект и его реализация обработчиков событий.
Для кода, использующего IOleCommandTarget интерфейс команды непосредственно для обработки необходимо реализовать IOleCommandTarget интерфейс и его методы. 2 Самых важных метода Execи QueryStatus .
Скорректировать новую команду с помощью MPF
Получите OleMenuCommandService экземпляр, как показано в следующем примере.
OleMenuCommandService mcs = GetService(typeof(IMenuCommandService)) as OleMenuCommandService;Create a CommandID объект, который принимает в качестве параметров GUID и идентификатор команды обработки, как показано в следующем примере.
CommandID menuCommandID = new CommandID(GuidList.guidButtonGroupCmdSet, (int)PkgCmdIDList.cmdidMyCommand);Шаблон пакета Visual Studio предоставляет коллекцию, 2 GuidList и PkgCmdIDListидентификаторы GUID и идентификаторы команд, сохранить. Эти автоматически заполняются для команд, которые добавляются шаблоном, но для команд, которые добавляются вручную, необходимо также добавить запись в id PkgCmdIdList класс.
Также можно заполнить CommandID объект с использованием начального значения строки GUID и значения целого числа id
Создайте экземпляр то a MenuCommand OR OleMenuCommand объект, определяющий метод, который обрабатывает команды вместе с CommandID, как показано в следующем примере.
MenuCommand menuItem = new MenuCommand(MenuItemCallback, menuCommandID);MenuCommand подходят для статических команд. Динамические отображает пункта меню требуется обработчиков событий QueryStatus. OleMenuCommand добавить BeforeQueryStatus событие, которое возникает при открытии меню узла команды и некоторые другие свойства, такие как Text.
Команды, созданные шаблоном пакета, передаются по умолчанию к a OleMenuCommand объект Initialize() метод класса пакета.
MenuCommand подходят для статических команд. Динамические отображает пункта меню требуется обработчиков событий QueryStatus. OleMenuCommand добавить BeforeQueryStatus событие, которое возникает при открытии меню узла команды и некоторые другие свойства, такие как Text.
Команды, созданные шаблоном пакета, передаются по умолчанию к a OleMenuCommand объект Initialize() метод класса пакета. Мастер Visual Studio реализует Initialize метод с помощью MenuCommand. Отображает для динамических пунктов меню, необходимо изменить это значение OleMenuCommandкак показано на следующем шаге. Кроме того, чтобы изменять текст пункта меню, необходимо добавить команды TextChanges пометить на кнопке команды меню в файле .vsct, как показано в приведенном ниже примере
<Button guid="guidMenuTextCmdSet" id="cmdidMyCommand" priority="0x0100" type="Button"> <Parent guid="guidMenuTextCmdSet" id="MyMenuGroup" /> <Icon guid="guidImages" id="bmpPic1" /> <CommandFlag>TextChanges</CommandFlag> <Strings> <CommandName>cmdidMyCommand</CommandName> <ButtonText>My Command name</ButtonText> </Strings> </Button>Передайте новую команду меню с AddCommand метод IMenuCommandService интерфейс. Это совершенное по умолчанию для команд, созданных на основе шаблона пакета, как показано в приведенном ниже примере
mcs.AddCommand( menuItem );Реализуйте метод, который обрабатывает команды.
Реализация QueryStatus с помощью классов MPF
Событие QueryStatus происходит до того, как команда отображается. Сюда входят свойства этой команды быть установлен в обработчике событий, прежде чем он достигает пользователя. Только команды, которые добавляются как OleMenuCommand объекты могут получить доступ к этот метод.
Добавление EventHandler объект BeforeQueryStatus события в OleMenuCommand объект, созданный для обработки команды, как показано в следующем примере (menuItemOleMenuCommand экземпляр).
Dim menuCommandID As CommandID = New CommandID(GuidList.guidMenuTextCmdSet, CInt(PkgCmdIDList.cmdidMyTextCommand)) Dim menuItem As OleMenuCommand = New OleMenuCommand(New EventHandler(AddressOf MenuItemCallback), menuCommandID) AddHandler menuItem.BeforeQueryStatus, AddressOf OnBeforeQueryStatus mcs.AddCommand(menuItem)// Create the command for the menu item. CommandID menuCommandID = new CommandID(GuidList.guidMenuTextCmdSet, (int)PkgCmdIDList.cmdidMyCommand); OleMenuCommand menuItem = new OleMenuCommand(MenuItemCallback, menuCommandID ); menuItem.BeforeQueryStatus += new EventHandler(OnBeforeQueryStatus); mcs.AddCommand(menuItem);EventHandler получает объект имя метода, который вызывается, если запрашивается состояние команды меню.
Реализуйте метод обработчика для состояния запроса для команды. object sender параметр может привести к OleMenuCommand объект, который используется для задания различные атрибуты команды меню, включая текст. В следующей таблице показаны свойства MenuCommand класс (MPF, класс OleMenuCommand наследует), соответствующее OLECMDF флаги.
Свойство MenuCommand
Пометить OLECMDF
Checked = true
Visible = false
Enabled = true
Чтобы изменить текст команды меню, используйте Text свойство OleMenuCommand объект, как показано в следующем примере.
Private Sub OnBeforeQueryStatus(ByVal sender As Object, ByVal e As EventArgs) Dim myCommand As OleMenuCommand = TryCast(sender, OleMenuCommand) If myCommand IsNot Nothing Then myCommand.Text = "New Text" End If End Subprivate void OnBeforeQueryStatus(object sender, EventArgs e) { var myCommand = sender as OleMenuCommand; if (null != myCommand) { myCommand.Text = "New Text"; } }
MPF автоматически обрабатывает случай неподдерживаемых или неизвестных групп. Если команда не будет добавлена к OleMenuCommandService с помощью AddCommand метод команда не поддерживается.
Обработка команд с помощью интерфейса IOleCommandTarget
Для кода, использующего Exec интерфейс напрямую VSPackage должен реализовать оба IOleCommandTarget и QueryStatus методы IOleCommandTarget интерфейс. Если VSPackage реализует иерархию проекта ExecCommand и IVsUIHierarchy методы QueryStatusCommand интерфейс должен быть реализован.
Оба Exec и GUID методы предназначены для получения набора одной команды QueryStatus и массив идентификаторов команд в качестве входных данных. Рекомендуется поддержка VSPackages полностью это понятие нескольких идентификаторов в одном вызове. Однако если VSPackage не вызывается из другого VSPackages, можно предполагать, что массив команды содержат только один идентификатор команды, поскольку Exec и QueryStatus методы выполняются в чётком порядке. Дополнительные сведения о маршрутизации см. в разделе Command Routing in VSPackages.
Для кода, использующего QueryStatus интерфейс команды непосредственно для обработки необходимо реализовать IOleCommandTarget метод в VSPackage следующим образом для обработки команд.
Реализация метода QueryStatus
Return S_OK для допустимых команд.
Установка cmdf элемент prgCmds параметр.
Значение cmdf элемент логическое объединение значений OLECMDF перечисление, в сочетании с помощью логического ИЛИ (|Оператор).
Используйте соответствующее перечисление, основанное на состоянии команды:
Если команда поддерживается:
prgCmds[0].cmdf = OLECMDF_SUPPORTED;
Если команда должна незрима в данный момент.
prgCmds[0].cmdf |= OLECMDF_INVISIBLE;
Если команда переключаемых on и кажется, что нажата.
prgCmds[0].cmdf |= OLECMDF_LATCHED;
В случае обработки команды, размещаемых в меню типа MenuControllerLatchedпервая команда, которая помечена OLECMDF_LATCHED пометить команда по умолчанию, которая отображается меню при запуске. Дополнительные сведения о MenuController типы меню, см. в разделе Элемент Menu.
Если в настоящий момент команда включена.
prgCmds[0].cmdf |= OLECMDF_ENABLED;
Если команда часть контекстного меню и скрыты по умолчанию:
prgCmds[0] cmdf |= OLECMDF_DEFHIDEONCTXMENU
Если команда использует TEXTCHANGES пометить присвойте rgwz элемент pCmdText параметр в новый текст команды, и присваивают cwActual элемент pCmdText параметр размера командной строки.
Для условий ошибки QueryStatus метод должен обрабатывать случаи об ошибке:
Если идентификатор GUID неизвестен или не поддерживается, возвращается OLECMDERR_E_UNKNOWNGROUP.
Если известен идентификатор GUID и идентификатор команды неизвестен или не поддерживается, возвращается OLECMDERR_E_NOTSUPPORTED.
Реализация VSPackage Exec метод должен также возвращать определенные коды ошибок, в зависимости от того, поддерживается ли команда была обработана и ли команда успешно.
Реализовать метод exec
Если команда GUID неизвестны, возвращают OLECMDERR_E_UNKNOWNGROUP.
Если GUID знает, но неизвестно, возвращает идентификатор команды OLECMDERR_E_NOTSUPPORTED.
Если GUID сопоставление команды и идентификатор GUID: Пары идентификатор, используемых командой в файле .vsct, выполните код, который связан с помощью команды и возвращать S_OK.