Designing Command Table Configuration Files

  • Article

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

Note

Beginning with Visual Studio 2008 SDK, use XML Command Table (.vsct) files instead of command table configuration (.ctc) files to define how menus and commands appear in your VSPackages. For more information, see Visual Studio Command Table (.Vsct) Files.

A command table configuration (.ctc) file defines the way that VSPackage menus and toolbars populate with groups of command items. The key elements of the Visual Studio user interface are command items (such as buttons and combo boxes) and menus (including context menus).

This page describes command table configuration files, how they affect UI elements, and how to create them.

Commands, Menus, Groups, and the .ctc File

The .ctc file is organized around commands, menus, and groups. Commands are contained in groups, groups are contained in menus, and menus are contained in other groups. Command items get input from the user, and menus send that input to the Visual Studio IDE. Any menu that is contained in a group that has the parent menu of guidSHLMainMenu:IDM_VS_TOOL_MAINMENU appears in the top level menu of the IDE. For more information about commands, command groups, and menus, see How VSPackages Add User Interface Elements to the IDE.

Once written, a .ctc file is compiled and loaded as a resource into the VSPackage's satellite DLL.

Each available command, command group, and menu is identified by a unique GUID:ID pair. The ctc.exe compiler requires the GUID to be in this format:

#define guidCmd  { 0xBC8DA515, 0x5743, 0x4FEB, { 0xA9, 0x29, 0x29, 0x38, 0x24, 0x9C, 0xBA, 0x26 } }

Note

Create your own unique GUID with the Create GUID tool by selecting Create GUID from the Tools menu.

A .ctc file can #include files containing constants that define commands, command groups, and menus that the IDE or another VSPackage provides because the Command Table Configuration file compiler (ctc.exe) passes the .ctc file through a preprocessor.

Each command table must include, at a minimum, one system header: vsshlids.h. The #include directive will look like:

   #include <vsshlids.h>

A .ctc file can also include other .ctc files. For more information, see Default Command, Group, and Toolbar Placement.

For an example of how to implement a .ctc file in a VSPackage, see the C# Single View Editor Reference Sample. By default, this sample is located in <Visual Studio SDK installation path>\VisualStudioIntegration\Samples

\IDE\CSharp\Reference.SingleViewEditor\. The \CtcComponents\ folder contains a file named PkgCmd.ctc. This file maps commands to the command and menu groups as outlined in this topic.

The .ctc File Format

The command table has five major sections; each section is marked with beginning and ending identifiers.

The Commands Section

The commands section has five subsections:

.Ctc File Design Guidelines

To successfully design a .ctc 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 placement directive CMDS_SECTION – CMDS_END.

.Ctc File Notes

If you make any changes to a .ctc file after you both compile it and place it in a native satellite DLL, you should run devenv.exe /setup. 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.

Managed code VSPackages often use native code satellite DLLs to contain the CTMENU resource. However, changes made to the .ctc file may not always update the satellite DLL itself when the satellite DLL project is built. To link with the changes made to the .ctc file and ensure that the satellite DLL always contains the latest changes to the .ctc file, right-click the satellite DLL project and select Rebuild from the shortcut menu.

During development, it is possible for multiple VSPackage projects to be created and registered in the experimental registry hive. This 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 <Visual Studio SDK installation path>\VisualStudioIntegration\Tools\Bin\ or <Visual Studio SDK installation path>\VisualStudioIntegration\Tools\Bin\x86\. Run the tool by using the command line vsregex GetOrig 9.0 Exp RANU where 9.0 is the version of Visual Studio that you are using, Exp is the suffix appended to the version to get to the experimental registry hive, and RANU is the switch used to write to the experimental registry hive under HKEY_CURRENT_USER.

Important

In Visual Studio Shell the experimental hive is added under HKEY_CURRENT_USER rather than HKEY_LOCAL_MACHINE, as in previous versions.

Remember that the vsregex.exe tool removes from the experimental hive all registered VSPackages not normally installed with Visual Studio.

The ctc.exe file only reads multi-byte character set (MBCS) encoded files, which it then converts to Unicode using the code page of the current console. It will not read files saved as Unicode. Keywords are case-sensitive, must be ASCII, and must match the documentation exactly. The entire .cto file must be copied and localized.

See Also

Tasks

How to: Create and Handle Commands in VSPackages (C#)

How to: Create Reusable Groups of Buttons

Concepts

Command Table Format Reference

User Interface Design Guidelines

Implementing Menu Commands for Optimal Availability

Guidelines for Command Placement

Experimental Build

Other Resources

Command Table Configuration (.Ctc) Files

Common Menu Tasks

Guidelines for Large Command Sets