外接程序注册

项目
02/21/2013

创建了外接程序后，必须先向 Visual Studio 注册此外接程序，然后才能在**“外接程序管理器”**中激活它。使用具有 .addin 文件扩展名的 XML 文件来完成此操作。

.addin 文件描述了 Visual Studio 在**“外接程序管理器”中显示外接程序所需的信息。在 Visual Studio 启动时，它会查找 .addin 文件位置，获取任何可用的 .addin 文件。如果找到相应文件，则会读取 XML 文件并向“外接程序管理器”**提供在单击外接程序进行启动时所需的信息。

使用外接程序向导创建外接程序时，会自动创建一个 .addin 文件。您也可以使用本主题中的信息手动创建 .addin 文件。

文件位置

外接程序向导会自动创建 .addin 文件的两个副本，如下所示：

.Addin 文件位置	.Dll 文件位置	说明
根项目文件夹 \Documents\Visual Studio 2010\Projects\MyAddin1\MyAddin1\	本地路径 (MyAddin1.dll)	用于部署外接程序项目。包含在项目中以方便编辑，并使用本地路径安装以进行 XCopy 式部署。
外接程序文件夹 \Documents\Visual Studio 2010\Addins\ - 或 - 共享文档位置\Addins\	项目调试文件夹（例如，\ Documents\Visual Studio 2010 Projects\MyAddin1\MyAddin1\bin\）	用于在调试环境中运行外接程序。应该始终指向当前生成配置的输出路径。

根项目文件夹

\Documents\Visual Studio 2010\Projects\MyAddin1\MyAddin1\

本地路径 (MyAddin1.dll)

用于部署外接程序项目。包含在项目中以方便编辑，并使用本地路径安装以进行 XCopy 式部署。

外接程序文件夹

\Documents\Visual Studio 2010\Addins\

- 或 -

共享文档位置\Addins\

项目调试文件夹

（例如，\ Documents\Visual Studio 2010

Projects\MyAddin1\MyAddin1\bin\）

用于在调试环境中运行外接程序。应该始终指向当前生成配置的输出路径。

若要将外接程序安装在另一台计算机上，必须将 .addin 文件放在 Visual Studio 将在其中检查外接程序的位置中。这些位置。选项对话框中，在环境节点，请在 外接程序安全性 页。有关更多信息，请参见外接程序安全性。

包含外接程序的 .dll 文件可以安装在客户端计算机上的任意位置。不过，我们建议您将该文件与 .addin 文件放在一起。

备注

.addin 文件的 <Assembly> 元素必须指向包含外接程序二进制文件的 .dll 文件。

.Addin 文件

.addin XML 文件拆分为下面的标记部分：

节	说明
宿主应用程序	（必选。）指定可以加载外接程序的应用程序的名称和版本号。
外接程序	（必选）包含描述外接程序的元素。
“工具选项”页	（可选）在“选项”对话框中指定可在其中配置外接程序的页。子节点指定“选项”页的类别和子类别，并且还指定其程序集名称和完整的类名。

下面的元素是 <Addin> 节的子级：

元素	说明
“关于”框的详细信息	（可选）指定将在 Visual Studio 的“关于”对话框中为外接程序显示的文本。
“关于”图标数据	（可选）包含二进制数据，可用来指定将在 Visual Studio 的“关于”对话框中为外接程序显示的图标。
“关于”图标位置	（可选）指定将在 Visual Studio 的“关于”对话框中为外接程序显示的图标的绝对路径或相对路径。
程序集	（必选。）指定外接程序的二进制形式的位置。此字段可以设置为本地路径、网络路径或 URL。
命令行安全	（可选）指定外接程序兼容的 Visual Studio 模式，例如，仅支持命令行、仅支持集成开发环境 (IDE) 或同时支持两者。
命令预加载	（可选）指定外接程序的预加载状态；即外接程序是否应该使用一种方法（例如 Commands.AddNamedCommand）来创建自己的 UI。
完整的类名称	（必选。）指定用于连接到外接程序的类的名称。
加载行为	（可选）定义是在启动时加载外接程序还是手动加载外接程序。

下面是每种设置的详细信息。有关所述的诸多元素的层级位置的更多信息，请参见本主题后面的“示例 .Addin XML 文件”一节。

宿主应用程序

Host Application 节中的 <Name> 元素包含应用程序的名称。这是在应用程序的标题栏中显示的名称或者由 DTE.Name 返回的名称。例如，对于 Visual Studio，标记将包含“Microsoft Visual Studio”，而对于宏 IDE，标记将包含“Microsoft Visual Studio Macros”。

每个 .addin 文件可以有多个 Host Application 值。每个值必须在 <HostApplication> 元素内用 <Name> 标记括起来。除了包含 <Name> 元素之外，每个 <HostApplication> 元素还必须包含由 <Version> 标记括起来的应用程序版本号。例如，

   <HostApplication>
      <!-- First Host App name (required). -->
      <Name>Microsoft Visual Studio</Name>
      <Version>10.0</Version>
   </HostApplication>
   <HostApplication>
      <!-- An additional supported program/version. -->
      <Name>Microsoft Visual Studio Macros</Name>
      <Version>10.0</Version>
   </HostApplication>

或者可以指定星号 (*)，表示任何版本的 Visual Studio 的 <Version> 值。

友好名称

位于 <Addin> 元素下的 <FriendlyName> 元素指定将在**“外接程序管理器”的“可用外接程序”**列中显示的字符串。例如，

   <FriendlyName>My New Super Addin</FriendlyName>

说明

位于 <Addin> 元素下的 <Description> 元素指定将在**“外接程序管理器”的“说明”**框中显示的字符串。例如，

   <Description>This add-in will change your life!</Description>

“关于”框的详细信息

创建外接程序时，如果选择了生成**“关于”对话框的设置的选项，则会将此元素添加到 .addin 文件中。此元素指定将在 Visual Studio 的“关于”**对话框中显示的文本。例如，

   <AboutBoxDetails>For add-in support, call 1-800-xxx-
     xxxx.</AboutBoxDetails>

“关于”图标数据

创建外接程序时，如果选择了生成**“关于”对话框的设置的选项，则会将此元素添加到 .addin 文件中。此元素包含二进制数据，该数据指定将在 Visual Studio 的“关于”**对话框中显示的图标。例如，

<AboutIconData>0000010006 . . . FFFF0000</AboutIconData>

程序集

位于 <Addin> 元素下的 <Assembly> 元素指定外接程序二进制文件的位置。此元素可以设置为相对路径、绝对路径（“file”）、注册程序集名称（“assembly”）或 URL（“url”）。

下面的示例演示绝对路径位置。在这种情形下，src 参数设置为 file，以指示外接程序 DLL 的位置。

<Assembly src="file">C:\Documents and Settings\jdoe\Application Data\Microsoft\Visual Studio\10.0\AddIns\MyAddin4.dll</Assembly>

下面的示例演示注册的位置。在这种情形下，src 参数设置为 assembly，以指示注册外接程序 DLL。
```
<Assembly src="assembly">BookshelfDefineAddin</Assembly>
```
下面的示例演示 URL 位置。在这种情形下，src 参数设置为 url，以指示外接程序 DLL 的基于 Web 的位置。
```
<Assembly src="url">http://somewebsite.com/MyAddin4.dll</Assembly>
```

完整的类名称

<FullClassName> 元素指定用于连接到外接程序的类的完整名称。此名称包括其中包含类的命名空间。例如，

    <FullClassName>MyAddin4.Connect</FullClassName>

加载行为

<LoadBehavior> 元素定义外接程序是在 IDE 启动时自动加载还是手动启动。 <LoadBehavior> 元素位于 <Addin> 元素下。例如，

    <LoadBehavior>1</LoadBehavior>

尽管 <LoadBehavior> 的使用是可选的，但建议使用它来明确定义外接程序何时加载。

值	说明
0	在 IDE 启动时不加载外接程序，而必须手动加载。
1	在 IDE 启动时自动加载外接程序。
4	在使用生成开关 (devenv /build) 从命令提示符处启动 devenv 时加载外接程序。

命令预加载

<CommandPreload> 元素指定是否必须预加载外接程序。在安装 .addin 文件之后首次启动 Visual Studio 时，预加载将加载外接程序。例如，

    <CommandPreload>1</CommandPreload>

此元素允许指定在 Visual Studio 启动后必须加载外接程序。它使外接程序有机会创建所需的 UI 元素（例如命令栏按钮）或者执行其他仅首次需要的初始化任务（例如创建默认的外接程序设置）。随后将卸载外接程序，直至用户执行外接程序创建的其中一个命令为止。之后，将根据需要加载外接程序。

值	说明
0	在用户通过使用“外接程序管理器”启动外接程序或者将外接程序设置为在启动时加载之前，外接程序将不会加载。
1	在安装 .addin 文件之后首次启动 Visual Studio 时，将会自动加载外接程序。

可以检查您实现的 OnConnection 方法，以查看使用第二个参数为 OnConnection 指定的连接类型是否为 ext_cm_UISetup。如果是，则可以使用 AddNamedCommand 或 AddControl 方法执行您需要的任何命令安排。

命令行安全

可选的 <CommandLineSafe> 元素指示外接程序是否已设计为在从命令提示符处启动时（例如执行命令行生成或类似操作时）避免显示 UI。（可以通过选择**“外接程序向导”中的“我的外接程序从不提供模式用户界面”**来完成此操作。）此外，它还指定外接程序兼容的 Visual Studio 模式，例如，仅支持命令行或仅支持 IDE。例如，

    <CommandLineSafe>0</CommandLineSafe>

值	说明
0	指定外接程序不是命令行安全的并且会显示用户界面。
1	指定外接程序是命令行安全的并且不会显示用户界面。

“工具选项”页

可选的 <ToolsOptionsPage> 元素指定**“选项”页，以便用户能够配置外接程序。子节点指定“选项”**页显示时所采用的类别和子类别，并且还指定该页的程序集名称和完整的类名。下面的示例演示此元素的层次结构：

  <ToolsOptionsPage>
    <Category Name="Text Editor">
      <SubCategory Name="General">
        <Assembly>"MyFilePath\MyAddInOptionPage.dll"</Assembly>
        <FullClassName>"MyNamespace.MyAddInOptionPage"</FullClassName>
      </SubCategory>
    </Category>
  </ToolsOptionsPage>

示例 .Addin XML 文件

下面的示例演示一个完整的 .addin XML 文件。它显示了本主题所述元素的层次结构和位置。

<?xml version="1.0" encoding="UTF-16" standalone="no"?>
<Extensibility 
  xmlns="https://schemas.microsoft.com/AutomationExtensibility">
    <HostApplication>
        <Name>Microsoft Visual Studio Macros</Name>
        <Version>10.0</Version>
    </HostApplication> 
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>10.0</Version>
    </HostApplication>
    <Addin>
        <FriendlyName>My great new add-in.</FriendlyName>
        <Description>This add-in does it all.</Description>
        <AboutBoxDetails>Copyright 2010.</AboutBoxDetails>
        <AboutIconData>0000 . . . FFFF0000</AboutIconData>
        <Assembly>MyNewAddin.dll</Assembly>
        <FullClassName>MyNewAddin.Connect</FullClassName>
        <LoadBehavior>1</LoadBehavior>
        <CommandPreload>1</CommandPreload>
        <CommandLineSafe>0</CommandLineSafe>
    </Addin>
</Extensibility>

请参见

通过