Designing XML Command Table (.Vsct) Files
An XML command table (.vsct) file describes the layout and appearance of command items for a VSPackage. Command items include buttons, combo boxes, menus, toolbars, and groups of command items. This topic describes XML command table files, how they affect command items and menus, and how to create them.
Commands, Menus, Groups, and the .vsct File
.vsct files are organized around commands, menus, and command groups. XML tags in the .vsct file represent each of these items, along with other associated items such as command buttons, command placement, and bitmaps.
To create a new, blank .vsct file, see How to: Create a .Vsct File. Once created, you add XML elements, attributes, and values to the file to describe the command item layout. For a detailed XML schema, see the VSCT XML Schema Reference.
Differences Between .ctc and .vsct Files
While the meaning behind the XML tags in an .vsct file are the same as those in the now deprecated .ctc file format, their implementation is a bit different.
The new <extern> tag is where you reference other .h files to be compiled, such as those for the Visual Studio toolbar.
While .vsct files support the /include statement, as .ctc files do, it also features a new <import> element. The difference is, /include brings in all of the information, but <import> brings in only the names.
While .ctc files require a header file in which you define your preprocessor directives, one is not required for .vsct files. Instead, place your directives in the symbol table, located in the <Symbol> elements, located at the bottom of the .vsct file.
.vsct files feature an <Annotation> tag, which allows you to embed any information you like, such as notes or even pictures.
Values are stored as attributes on the item.
Command flags can be stored individually or stacked. Intellisense, however, does not work on stacked command flags. For more information about command flags, see the CommandFlag Element.
You can specify multiple types, such as split dropdowns, combos, etc.
Guids don't validate.
Each UI element has a string that represents the text that is displayed with it.
Parent is optional. If omitted, the value "Group Unknown" is used.
The Icon argument is optional.
The bitmap section -- The same as a .ctc file, except that you can now specify a file name via href that will be pulled in by the vsct.exe compiler at compile time.
ResID -- the old bitmap resource ID can be used and still works the same as in .ctc files.
HRef -- a new method that allows you to specify a file name for the bitmap resource. It assumes that all are used, so you can omit the Used section. The compiler will first search for local resources for the file, then on any net shares, and any resources defined by the /I switch.
Keybinding -- You no longer have to specify an emulator. If you do specify one, the compiler will assume that the editor and the emulator are the same.
Keychord -- has been dropped. The new format is Key1,Mod1,Key2,Mod2. You can specify either a character, hexadecimal, or VK constant.
The new compiler, vsct.exe, compiles both .ctc and .vsct files. The old clc.exe compiler, however, will neither recognize nor compile .vsct files.
You can use the vsct.exe compiler to convert an existing .cto file into an .vsct file. For more information about this, see How to: Create a .Vsct File from an Existing .Cto File.
The .vstc File Elements
The command table has the following hierarchy and elements:
CommandTable Element — Represents all of the commands, menu groups, and menus associated with the VSPackage.
Extern Element — References any external .h files you want to merge with the .vstc file.
.Vsct File Design Guidelines
To successfully design a .vsct file, follow these guidelines.
Commands can be placed only in groups, groups can be placed only in menus, and menus can be placed only in groups. Only menus are actually displayed in the IDE, groups and commands are not.
Submenus cannot be directly assigned to a menu, but must be assigned to a group, which is in turn assigned to a menu.
Commands, submenus and groups can be assigned to one parenting group or menu using the parent field of their defining directive.
Organizing a command table solely through the parent fields in the directives has a significant limitation. The directives that define objects can take only one parent argument.
Reusing commands, groups, or submenus requires the use of a new directive to create a new instance of the object with its own GUID:ID pair.
Each GUID:ID pair must be unique. Reusing a command that has, for example, been placed on a menu, a toolbar, or on a context menu, is handled by the IOleCommandTarget interface.
Commands and submenus can also be assigned to multiple groups, and groups can be assigned to multiple menus using the Commands Element.
.Vsct File Notes
If you make any changes to a .vsct file after you both compile it and place it in a native satellite DLL, you should run devenv.exe /setup /nosetupvstemplates. Doing this forces the VSPackage resources specified in the experimental registry to be reread and the internal database that describes Visual Studio to be rebuilt.
During development, it is possible for multiple VSPackage projects to be created and registered in the experimental registry hive that can lead to confusing clutter in the IDE. To fix this, you can reset the experimental hive to the default settings to remove all registered VSPackages and any changes they may have made to the IDE. To reset the experimental hive, use the vsregex.exe tool that comes with the Visual Studio SDK. This tool is located in the tools\bin or tools\bin\x86 folder of the VisualStudioIntegration folder (for example, C:\Program Files\Visual Studio Orcase SDK\<build number>\VisualStudioIntegration\Tools\Bin\vsregexe.exe). Run the tool with the command line vsregex GetOrig 8.0 Exp where "8.0" is the version of Visual Studio that you are using, and "Exp" is the suffix appended to the version to get to the experimental registry hive. Remember that the vsregex.exe tool removes from the experimental hive all registered VSPackages not normally installed with Visual Studio.
See Also
Concepts
Command Table Configuration (.Ctc) Files