Diseñar archivos de tabla de comandos XML (.vsct)

Un archivo de tabla de comandos XML (.vsct) describe el diseño y la apariencia de los elementos de comando de un VSPackage. Los elementos de comando incluyen botones, cuadros combinados, menús, barras de herramientas y grupos de elementos de comando. En este artículo se describen los archivos de tabla de comandos XML, cómo afectan a los elementos y menús de comandos y a cómo crearlos.

Comandos, menús, grupos y el archivo .vsct

Los archivos .vsct se organizan en torno a comandos, menús y grupos de comandos. Las etiquetas XML del archivo .vsct representan cada uno de estos elementos, junto con otros elementos asociados, como botones de comando, ubicación de comandos y mapas de bits.

Al crear un nuevo VSPackage ejecutando la plantilla de paquete de Visual Studio, la plantilla genera un archivo .vsct con los elementos necesarios para un comando de menú, una ventana de herramientas o un editor personalizado, en función de las selecciones. Este archivo .vsct se puede modificar para cumplir los requisitos de un VSPackage específico. Para obtener ejemplos de cómo modificar un archivo .vsct , vea Extender menús y comandos.

Para crear un nuevo archivo .vsct en blanco, vea How to: Create a .vsct file. Una vez creado, agregue elementos XML, atributos y valores al archivo para describir el diseño del elemento de comando. Para obtener un esquema XML detallado, consulte la referencia del esquema XML de VSCT.

Diferencias entre los archivos .ctc y .vsct

Aunque el significado de las etiquetas XML en un archivo .vsct es el mismo que esas etiquetas en el formato de archivo .ctc ahora en desuso, su implementación es un poco diferente:

• La nueva <etiqueta extern> es donde se hace referencia a otros archivos .h que se van a compilar, como esos archivos para la barra de herramientas de Visual Studio.

• Aunque los archivos .vsct admiten la instrucción /include , como lo hacen los archivos .ctc , también incluye un nuevo <elemento de importación> . La diferencia es que /include incluye toda la información, mientras que <la importación> solo incluye los nombres.

• Aunque los archivos .ctc requieren un archivo de encabezado en el que se definen las directivas de preprocesador, no se requiere uno para los archivos .vsct . En su lugar, coloque las directivas en la tabla de símbolos, ubicadas en los elementos Symbol>, ubicados en la parte inferior del archivo .vsct.<

• Los archivos .vsct presentan una <etiqueta Annotation> , que permite insertar información que desee, como notas o incluso imágenes.

• Los valores se almacenan como atributos en el elemento.

• Las marcas de comandos se pueden almacenar individualmente o apilar. Sin embargo, IntelliSense no funciona en marcas de comandos apiladas. Para obtener más información sobre las marcas de comandos, vea el elemento CommandFlag.

• Puede especificar varios tipos, como las listas desplegables divididas, los combos, etc.

• Los GUID no se validan.

• Cada elemento de interfaz de usuario tiene una cadena que representa el texto que se muestra con él.

• El elemento primario es opcional. Si se omite, se usa el valor Group Unknown .

• El argumento Icon es opcional.

• Sección mapa de bits: esta sección es la misma que en un archivo .ctc, excepto que ahora puede especificar un nombre de archivo a través de Href que el compilador vsct.exe extraerá en tiempo de compilación.

• ResID: el identificador de recurso de mapa de bits antiguo se puede usar y sigue funcionando igual que en los archivos .ctc .

• HRef: nuevo método que permite especificar un nombre de archivo para el recurso de mapa de bits. Se supone que se usan todos, por lo que puede omitir la sección Usado. El compilador buscará primero los recursos locales del archivo, después en los recursos compartidos netos y los recursos definidos por el modificador /I .

• Enlace de claves: ya no tiene que especificar un emulador. Si especifica una, el compilador asume que el editor y el emulador son los mismos.

• Keychord: se ha quitado Keychord. El nuevo formato es Key1,Mod1,Key2,Mod2. Puede especificar un carácter, una constante hexadecimal o VK.

El nuevo compilador, vsct.exe, compila los archivos .ctc y .vsct . Sin embargo, el compilador ctc.exe antiguo no reconocerá ni compilará archivos .vsct.

Puede usar el compilador vsct.exe para convertir un archivo .cto existente en un archivo .vsct. Para obtener más información, vea Cómo: Crear un archivo .vsct a partir de un archivo .cto existente.

Elementos del archivo .vsct

La tabla de comandos tiene la siguiente jerarquía y elementos:

• Elemento CommandTable: representa todos los comandos, grupos de menús y menús asociados con VSPackage.

• Elemento Extern: hace referencia a cualquier archivo .h externo que desee combinar con el archivo .vsct .

• Elemento Include: hace referencia a cualquier archivo de encabezado adicional (.h) que desee compilar junto con el archivo .vsct. Un archivo .vsct puede incluir archivos .h que contienen constantes que definen comandos, grupos de menús y menús que proporciona el IDE u otro VSPackage.

• Elemento Commands: representa todos los comandos individuales que se pueden ejecutar. Cada comando tiene los cuatro elementos secundarios siguientes:

• Elemento Menus: representa todos los menús y barras de herramientas del VSPackage. Los menús son contenedores para grupos de comandos.

• Elemento Groups: representa todos los grupos del VSPackage. Los grupos son colecciones de comandos individuales.

• Elemento Buttons: representa todos los botones de comando y los elementos de menú del VSPackage. Los botones son controles visuales que se pueden asociar a comandos.

• Elemento Bitmaps: representa todos los mapas de bits de todos los botones del VSPackage. Los mapas de bits son imágenes que se muestran junto a o en los botones de comando, en función del contexto.

• Elemento CommandPlacements: indica ubicaciones adicionales en las que se deben colocar los comandos individuales en los menús de VSPackage.

• Elemento VisibilityConstraints: especifica si un comando se muestra en todo momento o solo en determinados contextos, como cuando se muestra un cuadro de diálogo o ventana determinado. Los menús y comandos que tienen un valor para este elemento solo se mostrarán cuando el contexto especificado esté activo. El comportamiento predeterminado es mostrar el comando en todo momento.

• Elemento KeyBindings: especifica los enlaces de clave para los comandos. Es decir, una o varias combinaciones de teclas que se deben presionar para ejecutar el comando, como Ctrl+S.

• Elemento UsedCommands: informa al entorno de Visual Studio que, aunque el comando especificado se implementa mediante otro código, cuando el VSPackage actual está activo, proporciona la implementación del comando.

• Elemento Symbols: contiene los nombres de símbolo y los identificadores GUID de todos los comandos del paquete.

Directrices de diseño de archivos .vsct

Para diseñar correctamente un archivo .vsct , siga estas instrucciones.

• Los comandos solo se pueden colocar en grupos, los grupos solo se pueden colocar en menús y los menús solo se pueden colocar en grupos. Solo los menús se muestran realmente en el IDE, los grupos y los comandos no.

• Los submenús no se pueden asignar directamente a un menú, pero deben asignarse a un grupo, que a su vez se asigna a un menú.

• Los comandos, los submenús y los grupos se pueden asignar a un grupo o menú primario mediante el campo primario de su directiva de definición.

• La organización de una tabla de comandos únicamente a través de los campos primarios de las directivas tiene una limitación significativa. Las directivas que definen objetos solo pueden tomar un argumento primario.

• La reutilización de comandos, grupos o submenús requiere el uso de una nueva directiva para crear una nueva instancia del objeto con su propio GUID:ID par.

• Cada GUID:ID par debe ser único. La interfaz controla IOleCommandTarget la reutilización de un comando que, por ejemplo, se ha colocado en un menú, una barra de herramientas o en un menú contextual.

• Los comandos y submenús también se pueden asignar a varios grupos y los grupos se pueden asignar a varios menús mediante el elemento Commands.

Notas del archivo .vsct

Si realiza algún cambio en un archivo .vsct después de compilarlo y colocarlo en un archivo DLL satélite nativo, debe ejecutar devenv.exe /setup /nosetupvstemplates. Al hacerlo, los recursos de VSPackage especificados en el registro experimental se vuelven a leer y la base de datos interna que describe Visual Studio que se va a volver a compilar.

Durante el desarrollo, es posible crear y registrar varios proyectos de VSPackage en el subárbol del registro experimental que pueden provocar confusión en el IDE. Para corregirlo, puede restablecer el subárbol experimental a la configuración predeterminada para quitar todos los VSPackages registrados y los cambios que puedan haber realizado en el IDE. Para restablecer el subárbol experimental, use la herramienta CreateExpInstance.exe que se incluye con el SDK de Visual Studio. Puede encontrarlo en:

%PROGRAMFILES(x86)%\Visual Studio\version> SDK\<VisualStudioIntegration\Tools\Bin\CreateExpInstance.exe

Ejecute la herramienta mediante el comando CreateExpInstance /Reset. Recuerde que esta herramienta quita del subárbol experimental todos los VSPackages registrados que normalmente no se instalan con Visual Studio.

Contenido relacionado

• Extender menús y comandos