设计 XML 命令表 (.vsct) 文件

XML 命令表 (.vsct) 文件描述 VSPackage 的命令项的布局和外观。 命令项包括按钮、组合框、菜单、工具栏和命令项组。 本文介绍 XML 命令表文件、它们如何影响命令项和菜单,以及如何创建它们。

命令、菜单、组和 .vsct 文件

.vsct 文件围绕命令、菜单和命令组进行组织。 .vsct 文件中的 XML 标记表示其中每个项,以及其他关联的项,例如命令按钮、命令放置和位图。

通过运行 Visual Studio 包模板创建新的 VSPackage 时,模板将生成一个 .vsct 文件,其中包含菜单命令、工具窗口或自定义编辑器所需的元素,具体取决于你的选择。 然后,可以修改此 .vsct 文件以满足特定 VSPackage 的要求。 有关如何修改 .vsct 文件的示例,请参阅 扩展菜单和命令

若要创建新的空白 .vsct 文件,请参阅 如何:创建 .vsct 文件。 创建后,可以向文件添加 XML 元素、属性和值,以描述命令项布局。 有关详细的 XML 架构,请参阅 VSCT XML 架构参考

.wifi 和 .vsct 文件之间的差异

虽然 .vsct 文件中 XML 标记背后的含义与现在弃用的 .wifi 文件格式中的标记的含义相同,但其实现略有不同:

  • 新的 <外部> 标记是引用要编译的其他 .h 文件的位置,例如 Visual Studio 工具栏的文件。

  • 虽然 .vsct 文件支持 /include 语句,但正如 .wifi 文件所做的那样,它还具有新的 <导入> 元素。 区别在于, /include 会引入 所有 信息,而 <导入> 仅引入名称。

  • 虽然 .wifi 文件需要一个头文件,在其中定义预处理器指令,但 .vsct 文件不需要一个文件。 而是将指令放在符号表中,位于 <.vsct 文件的底部的 Symbol> 元素中。

  • .vsct 文件具有 <批注> 标记,可用于嵌入所需的任何信息,例如备注甚至图片。

  • 值存储为项的属性。

  • 命令标志可以单独存储或堆叠。 但是,IntelliSense 不适用于堆叠命令标志。 有关命令标志的详细信息,请参阅 CommandFlag 元素

  • 可以指定多个类型,例如拆分下拉列表、组合等。

  • GUID 不会验证。

  • 每个 UI 元素都有一个字符串,表示随它一起显示的文本。

  • 父级是可选的。 如果省略,则使用“未知组”值

  • Icon 参数是可选的。

  • 位图部分:本节与 .wifi 文件中的相同,只是现在可以通过 Href 指定文件名,该名称将在编译时由 vsct.exe 编译器拉取。

  • ResID:可以使用旧的位图资源 ID,并且仍与 .http 文件中的工作方式相同。

  • HRef:一种新方法,可用于指定位图资源的文件名。 它假定已使用所有内容,因此可以省略“已用”部分。 编译器将首先搜索文件的本地资源,然后在 /I 开关定义的任何网络共享和任何资源上搜索。

  • 键绑定:不再需要指定模拟器。 如果确实指定了一个,编译器将假定编辑器和模拟器相同。

  • Keychord:Keychord 已删除。 新格式为 Key1、Mod1、Key2、Mod2。 可以指定字符、十六进制或 VK 常量。

新的编译器 vsct.exe 编译 .wifi.vsct 文件。 但是,旧的 compiler.exe 编译器无法识别或编译 .vsct 文件。

可以使用 vsct.exe 编译器将现有 .cto 文件转换为 .vsct 文件。 有关详细信息,请参阅 How to: Create a .vsct file from an existing .cto file.

.vsct 文件元素

命令表具有以下层次结构和元素:

  • CommandTable 元素:表示与 VSPackage 关联的所有命令、菜单组和菜单。

  • Extern 元素:引用要与 .vsct 文件合并的任何外部 .h 文件。

  • Include 元素:引用要与 .vsct 文件一起编译的任何其他标头 (.h) 文件。 .vsct 文件可以包含 .h 文件,其中包含定义 IDE 或其他 VSPackage 提供的命令、菜单组和菜单的常量。

  • Commands 元素:表示可以执行的所有单个命令。 每个命令包含以下四个子元素:

  • Menus 元素:表示 VSPackage 中的所有菜单和工具栏。 菜单是命令组的容器。

  • Groups 元素:表示 VSPackage 中的所有组。 组是单个命令的集合。

  • Buttons 元素:表示 VSPackage 中的所有命令按钮和菜单项。 按钮是可与命令关联的可视控件。

  • Bitmaps 元素:表示 VSPackage 中所有按钮的所有位图。 位图是命令按钮旁边或命令按钮上显示的图片,具体取决于上下文。

  • CommandPlacements 元素:指示应在 VSPackage 菜单中定位各个命令的其他位置。

  • VisibilityConstraints 元素:指定命令是随时显示还是仅在特定上下文中显示,例如显示特定对话框或窗口的时间。 仅当指定上下文处于活动状态时,才会显示具有此元素值的菜单和命令。 默认行为是随时显示命令。

  • KeyBindings 元素:指定命令的任何键绑定。 也就是说,必须按下一个或多个键组合来执行命令,例如 Ctrl+S。

  • UsedCommands 元素:通知 Visual Studio 环境,尽管指定的命令是由其他代码实现的,但当当前 VSPackage 处于活动状态时,它将提供命令实现。

  • Symbols 元素:包含包中所有命令的符号名称和 GUID ID。

.vsct 文件设计指南

若要成功设计 .vsct 文件,请遵循以下准则。

  • 命令只能放置在组中,组只能放在菜单中,菜单只能放在组中。 实际上,只有菜单显示在 IDE 中,组和命令不显示。

  • 子菜单不能直接分配给菜单,但必须分配给一个组,该组又分配给菜单。

  • 可以使用其定义指令的父字段将命令、子菜单和组分配给一个父组或菜单。

  • 仅通过指令中的父字段组织命令表具有重大限制。 定义对象的指令只能采用一个父参数。

  • 重用命令、组或子菜单需要使用新指令来创建具有其自己的 GUID:ID 对的对象的新实例。

  • 每个 GUID:ID 对必须是唯一的。 例如,重用已放置在菜单、工具栏或上下文菜单上的命令由 IOleCommandTarget 接口处理。

  • 还可以将命令和子菜单分配给多个组,并且可以使用 Commands 元素将组分配给多个菜单

.vsct 文件说明

如果在编译 .vsct 文件并将其置于本机附属 DLL 后对 .vsct 文件进行任何更改,则应运行 devenv.exe /setup /nosetupvstemplates。 这样做会强制重新读取实验注册表中指定的 VSPackage 资源,并强制重新生成描述 Visual Studio 的内部数据库。

在开发过程中,可以在实验性注册表配置单元中创建和注册多个 VSPackage 项目,从而导致 IDE 中的混乱。 若要解决此问题,可以将实验配置单元重置为默认设置,以删除所有已注册的 VSPackage 以及它们可能对 IDE 所做的任何更改。 若要重置实验性配置单元,请使用 Visual Studio SDK 附带的 CreateExpInstance.exe 工具。 可以在以下位置找到它:

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

使用命令 CreateExpInstance /Reset 运行该工具。 请记住,此工具从实验配置单元中删除所有注册的 VSPackage,这些 VSPackage 通常未随 Visual Studio 一起安装。