LearnVSXNow!-#3 创建一个带有简单命令的Package

为了演示如何给我们的package增加功能，本篇将创建一个带有简单菜单（命令）的VS Package。和上一篇一样，我们新建一个Visual Studio Integration Package类型的项目，这一次我们把它命名为SimpleCommand。当项目向导出现后，我们选择C#做为开发语言，并利用向导为我们的程序集自动生成一个key文件。在VSPackage Information页面，我们输入如下内容：

在下一步，为了创建一个简单的菜单命令，我们选中Menu Command：

当转到下一步的时候，向导会要求我们填写菜单的显示文本和菜单的标识，请参考下图填写：

在向导的最后一步我们可以建立集成测试项目和单元测试项目，请勾掉这两个选项并且点击Finish按钮。向导会在几秒钟内帮我们创建项目的源文件。

编译并运行SimpleCommand项目。当Visual Studio实验室运行后，你可以在工具菜单下发现我们的package的菜单命令：

点击菜单My First Command，可以看到一个消息框。证明这个package已经正常运行了。

源文件分析（What is inside?)

关掉VS实验室，让我们查看一下源文件。我们可以发现，与上一篇的EmptyPackage相比，这一次多了两个文件：PkgCmdID.cs 和SimpleCommand.vsct。在文件PkgCmdID.cs中定义了菜单“My First Command”的标识符：

 
//在英文原文中，命名空间是MyCompany.SimpleToolWindow 
namespace MyCompany.SimpleCommand 
{ 
  static class PkgCmdIDList 
  { 
    public const uint cmdidMyFirstCommand = 0x100; 
  }; 
} 
  

标识符的名字是我们在项目向导那里填入的，标识符的值0x100是由向导自动生成的。

第二个文件SimpleCommand.vsct似乎更“令人兴奋”，因为它包含XML内容，这更符合我们进行界面定义的习惯。出于可读性的考虑，我去掉了源文件中的注释，该文件内容如下：

 
<?xml version="1.0" encoding="utf-8"?> 
<CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable" xmlns:xs="http://www.w3.org/2001/XMLSchema"> 
  <Extern href="stdidcmd.h" mce_href="stdidcmd.h"/> 
  <Extern href="vsshlids.h" mce_href="vsshlids.h"/> 
  <Extern href="msobtnid.h" mce_href="msobtnid.h"/>   
  
  <Commands package="guidSimpleCommandPkg"> 
    <Groups> 
      <Group guid="guidSimpleCommandCmdSet" id="MyMenuGroup" priority="0x0600"> 
        <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/> 
      </Group> 
    </Groups>   
    <Buttons> 
      <Button guid="guidSimpleCommandCmdSet" id="cmdidMyFirstCommand" 
        priority="0x0100" type="Button"> 
        <Parent guid="guidSimpleCommandCmdSet" id="MyMenuGroup" /> 
        <Icon guid="guidImages" id="bmpPic1" /> 
        <Strings> 
          <CommandName>cmdidMyFirstCommand</CommandName> 
          <ButtonText>My First Command</ButtonText> 
        </Strings> 
      </Button> 
    </Buttons> 
  
    <Bitmaps> 
      <Bitmap guid="guidImages" href="Resources\Images_32bit.bmp" mce_href="Resources\Images_32bit.bmp" usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/> 
    </Bitmaps> 
  </Commands> 
   
  <Symbols> 
    <GuidSymbol name="guidSimpleCommandPkg" value="{2291da24-92e5-4ea4-bdb7-72a9b5ac7d59}" /> 
    <GuidSymbol name="guidSimpleCommandCmdSet" value="{a982b107-4ad4-437e-b2bc-cdf2708aa376}"> 
      <IDSymbol name="MyMenuGroup" value="0x1020" /> 
      <IDSymbol name="cmdidMyFirstCommand" value="0x0100" /> 
    </GuidSymbol> 
    <GuidSymbol name="guidImages" value="{5c3faf04-8190-48c4-a6e9-71f04f1848e5}" > 
      <IDSymbol name="bmpPic1" value="1" /> 
      <IDSymbol name="bmpPic2" value="2" /> 
      <IDSymbol name="bmpPicSearch" value="3" /> 
      <IDSymbol name="bmpPicX" value="4" /> 
      <IDSymbol name="bmpPicArrows" value="5" /> 
    </GuidSymbol> 
  </Symbols> 
</CommandTable> 
  

.vsct文件是Visual Studio 2008 SDK里的一种新的XML格式，vsct代表Visual Studio的命令表（Command Table），Visual Studio利用vsct文件的定义为我们的package的命令创建用户界面。如果你查看这个文件的属性的话，你会发现该文件的Build Action是VSCTCompile。在package编译过程中，vsct文件会被编译成二进制的资源，并以1000作为资源ID添加到VSPackage.resx资源文件中。当regpkg.exe去注册我们的package的时候，vsct文件代表的资源也会注册到Visual Studio中。而当VS实验室启动的时候，VS只需要去读取已注册的资源以便更新VS的界面（例如显示菜单或工具栏项），而不需要加载我们的package。

     我认为现在还不是深入研究vsct文件的时候，但是我想告诉你一些重要的东西：通过vsct文件，我们可以学习到VS是怎样架构的，以及它是怎样组织这么多的功能和用户界面的。
     －命令（动作）和触发命令的用户界面是分开的。同一个命令可以被不同的菜单或工具栏调用。
     －多个命令可以分组，利用分组，可以简单的合并到已存在的菜单中。
     — 元素是可标识的符号，而不是常量。这样就不容易出错：标识符的名字是唯一的，VSCT编译器会检测输入错误。

它是如何工作的？

现在让我们看看我们的菜单项“My First Command”是怎样显示在Visual Studio中的。我们必须先弄清楚最重要的问题：当我们点击我们的命令对应的菜单项时，Visual Studio是怎样调用相应的动作的？答案就在SimpleCommandPackage.cs文件中，所以让我们来看一下这个文件。

在上一篇中，我们看到EmptyPackage类有很多Attribute的标记，regpkg.exe用这些Attribute来注册我们的package。在这一篇里，SimpleCommandPackage类比EmptyPackage多了一个ProvideMenuResourceAttribute：

 
... 
[ProvideMenuResource(1000, 1)]  
... 
public sealed class SimpleCommandPackage : Package 
{ 
  ... 
} 
  

ProvideMenuResourceAttribute构造函数有两个参数，第一个参数是resourceID，这个参数值必须是1000，因为VSCT编译器在把vsct文件编译到VSPackage资源中的时候，默认用1000作为vsct文件对应的资源ID。第二个参数是versionID，它的取值在资源的缓存机制中非常重要。现在先不要深入研究它的细节了，只需要记住ProvideMenuResourceAttribute允许我们为package注册菜单资源。

    为了执行一个命令，我们需要做下面的两步：
     — 我们需要写一个Command Handler，里面放置命令执行时的逻辑。
     — 我们必须以某种方式告诉Visual Studio来调用我们的Command Handler。

在这个例子中，我们的Command Handler将显示一个消息框。Command Handler本身是一个简单的私有方法，包含众所周知的EventHandler的参数。但是，在这个方法体内，却不是仅仅调用Messagebox.Show这么简单：

 
private void MenuItemCallback(object sender, EventArgs e) 
{ 
  IVsUIShell uiShell = (IVsUIShell)GetService(typeof(SVsUIShell)); 
   
  Guid clsid = Guid.Empty; 
  int result; 
  
  Microsoft.VisualStudio.ErrorHandler.ThrowOnFailure( 
    uiShell.ShowMessageBox( 
      0, 
      ref clsid, 
      "SimpleCommand", 
      string.Format(CultureInfo.CurrentCulture, "Inside {0}.MenuItemCallback()",  
        this.ToString()), 
      string.Empty, 
      0, 
      OLEMSGBUTTON.OLEMSGBUTTON_OK, 
      OLEMSGDEFBUTTON.OLEMSGDEFBUTTON_FIRST, 
      OLEMSGICON.OLEMSGICON_INFO, 
      0,        // false 
      out result) 
    ); 
} 
  

为了使用Visual Studio提供给Add-in和Package的功能，我们必须使用一些service。在我们这个例子中，我们用到了IVsUIShell这个service，它提供了若干方法去实现与界面有关的功能。为了得到这个service的实例，我们必须调用Package基类的GetService方法，并把SVsUIShell类型作为参数传递给它。

通过这个service的实例，我们可以调用它的ShowMessageBox方法去弹出一个Visual Studio消息框。这一次我不会解释ShowMessageBox方法的参数，你只需要知道它会弹出一个带有“确定”按钮的消息框就行了。（译者注：我们也可以直接用System.Windows.Forms.MessageBox.Show方法来弹出一个消息框，读者可以自己试一下）

Visual Studio的底层用的是COM技术。所有实现的service都可以被COM的interop类访问。如你所知，COM没有提供一个运行时的异常处理机制，它仅仅通过函数的返回值去标识异常。当调用一个COM对象的方法时，我们必须手动的判断返回值，并根据情况抛出异常。Microsoft.VisualStudio.ErrorHandler类的ThrowOnFailure方法帮助我们做了这项工作。

所以，MenuItemCallback方法就是这样执行我们的命令的。不过，我们还得通过某种方式告诉Visual Studio这个方法的存在，这样当用户点击“My First Command”菜单的时候它才会执行我们的命令。秘诀就在Initialize方法中，当Visual Studio加载我们的Package的时候，会调用Package的Initialize方法：

 
protected override void Initialize() 
{ 
  Trace.WriteLine (string.Format(CultureInfo.CurrentCulture,  
    "Entering Initialize() of: {0}", this.ToString())); 
  base.Initialize(); 
   
  OleMenuCommandService mcs =  
    GetService(typeof(IMenuCommandService)) as OleMenuCommandService; 
  if ( null != mcs ) 
  { 
    CommandID menuCommandID = new CommandID(GuidList.guidSimpleCommandCmdSet,  
      (int)PkgCmdIDList.cmdidMyFirstCommand); 
    MenuCommand menuItem = new MenuCommand(MenuItemCallback, menuCommandID ); 
    mcs.AddCommand( menuItem ); 
  } 
} 
  
  

我们重写了Initialize方法，在做任何动作之前，先调用基类的Initialize方法。一个命令可以通过很多方式调用：通过主菜单、通过工具栏或者通过上下文菜单。所有的菜单项都是通过命令ID和相应的命令绑定起来的。在这里，我们把命令ID和命令处理方法绑定起来。

通过GetService方法，我们得到了一个OleMenuCommandService的实例，它实现了IMenuCommandService接口，有差不多20个方法和一些属性。我们利用AddCommand方法把了一个Command handler（在这里是MenuItemCallback)和一个命令ID（menuCommandId变量）绑定其来。

当用户点击“My First Command”菜单项时，它是与以GuidList.guidSimpleCommandCmdSet和PkgCmdIDList.cmdidMyFirstCommand为标识的命令绑定其来的，而这个命令ID又是和MenuItemCallback关联的，所以会弹出消息框。