Compartir a través de

Cómo: Crear y controlar los comandos en VSPackages (C#)

  • Artículo

Agregar un comando a un VSPackage es un proceso de dos pasos. Primero, el comando se define como un elemento XML en el archivo de .vsct. Se implementa en código. La información proporcionada en el archivo de .vsct determina la apariencia del comando, su posición en el (IDE) IDE, y algunos de su comportamiento. El comando es a definido en código, normalmente como MenuCommand u objeto de OleMenuCommand , e implementar los controladores de eventos.

Los comandos que un VSPackage pone a disposición del IDE deben estar visible y habilitado antes de que un usuario puede utilizarlos. Cuando se crean los comandos en un archivo de .vsct mediante la plantilla de proyecto paquete de Visual Studio, son visibles y habilitados de forma predeterminada. Establecer algunos marcadores de comando, como DynamicItemStart, puede cambiar el comportamiento predeterminado. La visibilidad, el estado habilitado, y otras propiedades de un comando también se pueden cambiar en código en tiempo de ejecución teniendo acceso al objeto de OleMenuCommand que está asociado al comando.

crear un comando

Todos los comandos, grupos de comando, menús, barras de herramientas, y ventanas de herramientas se definen en el archivo de .vsct. Si el Paquete no tiene un archivo de .vsct, debe agregar uno. Para obtener más información, vea Tabla de comandos de Visual Studio (. archivos de Vsct).

Si está creando un VSPackage utilizando la plantilla de paquete, Comando de menú seleccione para crear un archivo de .vsct y definir un comando de menú predeterminado. Para obtener más información, vea tutorial: Crear un comando de menú mediante la plantilla de paquete de Visual Studio.

Para agregar un comando en el IDE

  1. Abra el archivo de .vsct.

  2. En la sección de Symbols , busque el elemento de GuidSymbol que contiene los grupos y los comandos.

  3. Cree un elemento de IDSymbol para cada menú, grupo, o comando que desee agregar, como se muestra en el ejemplo siguiente.

    <GuidSymbol name="guidButtonGroupCmdSet" value="{f69209e9-975a-4543-821d-1f4a2c52d737}">
  <IDSymbol name="MyMenuGroup" value="0x1020" />
  <IDSymbol name="cmdidMyCommand" value="0x0100" />
</GuidSymbol>

    los atributos de name de los elementos de GuidSymbol y de IDSymbol proporcionan GUID: Pares de cada nuevo menú, grupo, o comando. guid representa un comando establecido que está definido para el Paquete. Puede definir varios conjuntos de comando. cada GUID: Los pares de identificador deben ser únicos.

  4. En la sección de Botones , cree un elemento de Botn para definir el comando, como se muestra en el ejemplo siguiente.

    <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>

    1. establezca los campos de guid y de id para coincidir GUID: Identificador del nuevo comando.

    2. Establezca el atributo priority.

      El atributo de priority usa el .vsct para determinar la ubicación del botón entre los demás objetos del grupo primario.

      Muestra los comandos que tienen valores de menor prioridad anterior, o a la izquierda de, los comandos que tienen valores de prioridad máxima. Se permiten los valores de prioridad duplicados, pero la posición relativa de los comandos cuya prioridad sea igual viene determinada por el orden en que VSPackages se procesa en tiempo de ejecución, y la que no puede ser predeterminada el orden.

      La omisión del atributo de priority establece su valor en 0.

    3. Establezca el atributo type. En la mayoría de los casos, el valor se “Button”. Para las descripciones de otros tipos de botón válidos, vea Button (Elemento).

  5. En la definición del botón, cree un elemento de Cadenas que contiene un elemento de ButtonText para contener el nombre del menú que aparece en el IDE, y un elemento de CommandName para contener el nombre del comando que se utiliza para tener acceso al menú de la ventana de comandos.

    Si la cadena de texto del botón incluye “y” el carácter, puede abrir el menú presionando ALT más el carácter que sigue inmediatamente a “y”.

    Agregar un elemento de Tooltip hará el texto contenido aparezca cuando se mantiene el puntero sobre el botón.

  6. Agregue un elemento de Icon para especificar el icono, si existe, para mostrar con el comando. Los iconos se requieren para los botones de las barras de herramientas pero no para los elementos de menú. guid y id de elemento de Icon deben coincidir con los de un elemento de mapa de bits definido en la sección de Bitmaps .

  7. Agregue marcadores de comando, según corresponda, para cambiar el aspecto y el comportamiento del botón. Para ello, agregue un elemento de CommandFlag en la definición de menú.

  8. Establezca el grupo primario de comando. El grupo primario puede ser un grupo que se crea, un grupo de otro paquete, o un grupo del IDE. Por ejemplo, agregar el comando a la barra de herramientas edición de Visual Studio, junto a los botones de comentario y de quite el comentario , establece el elemento primario a guidStdEditor: IDG_VS_EDITTOOLBAR_COMMENT. Si el elemento primario es un grupo definido por el usuario, debe ser el elemento secundario de un menú, una barra de herramientas, o ventana de herramientas que aparece en el IDE.

    Puede hacerlo de dos maneras, dependiendo del diseño:

    • En el elemento de Button , cree un elemento de elemento primario y establezca sus campos de guid y de id a Guid y el identificador del grupo que hospeda el comando, también conocidos como grupo primario principal.

      El ejemplo siguiente se define un comando que aparece en un menú definido por el usuario.

      <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>

    • Puede omitir el elemento de Parent si el comando a colocarse mediante la posición del comando. Cree un elemento de CommandPlacements antes de la sección de Symbols , y agregue un elemento de CommandPlacement que tiene guid y id de comando, de priority, y un elemento primario, como se muestra en el ejemplo siguiente.

      <CommandPlacements>
  <CommandPlacement guid="guidButtonGroupCmdSet" id="cmdidMyCommand" priority="0x105">
    <Parent guid="guidButtonGroupCmdSet" id="MyMenuGroup" />
  </CommandPlacement>
</CommandPlacements>

      Crear las posiciones varias de comando que tienen el mismo GUID: El identificador y tiene varias causas de los elementos primarios un menú de aparecer en varias ubicaciones. Para obtener más información, vea el elemento de CommandPlacements .

    Para obtener más información sobre los grupos y relación jerárquica de comando, vea Cómo: Crear grupos reutilizable de botones.

En este punto, el comando estará visible en el IDE, pero no tendrá ninguna funcionalidad. Si la plantilla de paquete creó el comando, de forma predeterminada tendrá un controlador click que muestra un mensaje.

Administrar el comando New

La mayoría de los comandos en código administrado se pueden controlar por el (MPF) managed package asociando el comando a un objeto de MenuCommand o el objeto de OleMenuCommand e implementar los controladores de eventos.

Para el código que utiliza la interfaz de IOleCommandTarget directamente para el comando que administra, debe implementar la interfaz de IOleCommandTarget y sus métodos. los dos métodos más importantes son QueryStatus y Exec.

Para administrar el nuevo comando utilizando MPF

  1. Obtiene la instancia de OleMenuCommandService , como se muestra en el ejemplo siguiente.

    OleMenuCommandService mcs = 
    GetService(typeof(IMenuCommandService)) as OleMenuCommandService;

  2. Cree un objeto de CommandID que tenga como parámetros el GUID y el identificador de comando de administración, como se muestra en el ejemplo siguiente.

    CommandID menuCommandID = 
    new CommandID(GuidList.guidButtonGroupCmdSet, 
        (int)PkgCmdIDList.cmdidMyCommand);

    La plantilla de paquete de Visual Studio proporciona dos colecciones, GuidList y PkgCmdIDList, para contener el GUID y los id. de comandos. Éstos se rellenan automáticamente para los comandos que se agregan por la plantilla, pero para los comandos que agrega manualmente, también debe agregar la entrada del identificador de la clase de PkgCmdIdList .

    Alternativamente, puede rellenar el objeto de CommandID utilizando el valor de cadena sin formato del GUID y el valor entero de identificación

  3. Cree instancias MenuCommand o el objeto de OleMenuCommand que especifican el método que administra el comando así como CommandID, como se muestra en el ejemplo siguiente.

    MenuCommand menuItem = 
    new MenuCommand(MenuItemCallback, menuCommandID);

    MenuCommand es adecuado para los comandos estáticos. Muestra dinámicas del elemento de menú requieren los controladores de eventos QueryStatus. OleMenuCommand agrega el evento de BeforeQueryStatus , que aparece cuando se abre el menú host de comando, y otras propiedades, como Text.

    Pasan a los comandos creados por la plantilla de paquete de forma predeterminada a un objeto de OleMenuCommand en el método de Initialize() de la clase de paquete.

  4. MenuCommand es adecuado para los comandos estáticos. Muestra dinámicas del elemento de menú requieren los controladores de eventos QueryStatus. OleMenuCommand agrega el evento de BeforeQueryStatus , que aparece cuando se abre el menú host de comando, y otras propiedades, como Text.

    Pasan a los comandos creados por la plantilla de paquete de forma predeterminada a un objeto de OleMenuCommand en el método de Initialize() de la clase de paquete. El asistente de Visual Studio implementa el método de Initialize mediante MenuCommand. Para presentaciones dinámicas de elementos de menú, debe cambiar esto a OleMenuCommand, como se muestra en el paso siguiente. Además, para cambiar el texto del elemento de menú, debe agregar un indicador de comando de TextChanges al botón de comando de menú en el archivo de .vsct, como se muestra en el siguiente ejemplo

    <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>

  5. Pase el nuevo comando de menú al método de AddCommand en la interfaz de IMenuCommandService . Esto se realiza de forma predeterminada para los comandos creados por la plantilla de paquete, como se muestra en el ejemplo siguiente

    mcs.AddCommand( menuItem );

  6. Implemente el método que administra el comando.

Para implementar QueryStatus mediante clases de MPF

  1. El evento QueryStatus aparece antes de enviar un comando. Esto permite propiedades de ese comando de establecer en el controlador de eventos antes de llegar al usuario. Sólo comandos que se agregan como objetos de OleMenuCommand pueden tener acceso a este método.

    Agregue un objeto de EventHandler al evento de BeforeQueryStatus en el objeto de OleMenuCommand que se crea para controlar el comando, como se muestra en el ejemplo siguiente (menuItem es la instancia de OleMenuCommand ).

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

    El objeto de EventHandler recibe el nombre de un método que se llama cuando se consulta el estado del comando de menú.

  2. Implemente el método de controlador de estado de consulta para el comando. El parámetro de objectsender se puede convertir a un objeto de OleMenuCommand , que se utiliza para establecer los distintos atributos de comando de menú, incluido el texto. La tabla siguiente se muestran las propiedades de la clase de MenuCommand (qué la clase OleMenuCommand de MPF deriva) que corresponden a OLECMDF marcas.

    propiedad de MenuCommand

    indicador de OLECMDF

    Checked = true

    OLECMDF_LATCHED

    Visible = false

    OLECMDF_INVISIBLE

    Enabled = true

    OLECMDF_ENABLED

    Para cambiar el texto de un comando de menú, utilice la propiedad de Text en el objeto de OleMenuCommand , como se muestra en el ejemplo siguiente.

    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 Sub

    private void OnBeforeQueryStatus(object sender, EventArgs e)
{
    var myCommand = sender as OleMenuCommand;
    if (null != myCommand)
    {
        myCommand.Text = "New Text";
    }
}

El MPF controla automáticamente el caso de grupos no compatible o desconocidos. A menos que haya agregado un comando a OleMenuCommandService utilizando el método de AddCommand , no admite el comando.

Control de comandos mediante la interfaz de IOleCommandTarget

Para el código que utiliza la interfaz de IOleCommandTarget directamente, el Paquete debe implementar el QueryStatus y los métodos de Exec de la interfaz de IOleCommandTarget . Si el paquete VSPackage implementa una jerarquía de proyecto, el QueryStatusCommand y los métodos de ExecCommand de la interfaz de IVsUIHierarchy se deben implementar en su lugar.

El QueryStatus y los métodos de Exec están diseñados para recibir un único comando GUID determinado y una matriz de id. de comando como entrada. Se recomienda compatibilidad de VSPackages totalmente este concepto de id. de una llamada. Sin embargo, mientras un VSPackage no se llama desde el otro VSPackages, puede suponer que la matriz de comando contiene sólo un identificador de comando porque el QueryStatus y los métodos de Exec se ejecutan en un orden bien definido. Para obtener más información sobre el enrutamiento, vea Command Routing in VSPackages.

Para el código que utiliza la interfaz de IOleCommandTarget directamente para el comando que administra, debe implementar el método de QueryStatus en el paquete VSPackage la siguiente para controlar los comandos.

Para implementar el método QueryStatus

  1. S_OK return para los comandos válidos.

  2. Establezca el elemento de cmdf de parámetro de prgCmds .

    El valor de cmdf es la unión lógica de valores de enumeración de OLECMDF , combinada con la disyunción lógica (|) operador.

    Utilice la enumeración adecuada, basándose en el estado del comando:

    • Si admite el comando:

      prgCmds[0].cmdf = OLECMDF_SUPPORTED;

    • Si el comando no está visible en el punto:

      prgCmds[0].cmdf |= OLECMDF_INVISIBLE;

    • Si alternan en y aparece el comando para que se hizo clic:

      prgCmds[0].cmdf |= OLECMDF_LATCHED;

      En el caso de los comandos de procesamiento que se hospedan en un menú de MenuControllerLatchedescrito, el primer comando que está marcado el marcador de OLECMDF_LATCHED es el comando predeterminado que muestra el menú de inicio. Para obtener más información sobre los tipos de menú de MenuController , vea Menu (Elemento).

    • Si habilita el comando actualmente:

      prgCmds[0].cmdf |= OLECMDF_ENABLED;

    • si el comando es parte de un menú contextual y se oculta de forma predeterminada:

      prgCmds[0] cmdf |= OLECMDF_DEFHIDEONCTXMENU

    • Si el comando utiliza el indicador de TEXTCHANGES , establezca el elemento de rgwz de parámetro de pCmdText al nuevo texto de comando y establezca el elemento de cwActual de parámetro de pCmdText al tamaño de la cadena de comando.

    Para las condiciones de error, el método de QueryStatus debe controlar los siguientes casos de error:

    • Si el GUID es desconocido o no compatible, devuelve OLECMDERR_E_UNKNOWNGROUP.

    • Si se conoce GUID pero el identificador de comando es desconocido o no compatible, OLECMDERR_E_NOTSUPPORTEDreturn.

La implementación de VSPackage del método de Exec también debe devolver códigos de error específicos, dependiendo de si admite el comando y si manejaron correctamente el comando.

Para implementar el método Exec

  • Si el comando GUID es OLECMDERR_E_UNKNOWNGROUPdesconocido, return.

  • Si se conoce GUID pero el identificador de comando es OLECMDERR_E_NOTSUPPORTEDdesconocido, return.

  • Si GUID y el identificador de comando GUID: Los pares de identificador usados por el comando en el archivo de .vsct, ejecutan código que está asociado al comando y devuelven S_OK.

Vea también

Conceptos

Referencia del esquema XML de VSCT

Otros recursos

Tareas comunes con los comandos, menús, barras de herramientas y

Walkthrough: Adding a Command to a Visual Studio Menu