增益集登錄

建立增益集之後，您必須先將它登錄至 Visual Studio 中，才能在 [增益集管理員] 中啟動該增益集。 使用具有 .addin 副檔名的 XML 檔，即可完成這項作業。

.addin 檔案會描述 Visual Studio 將增益集顯示在 [增益集管理員] 中所需的資訊。 當 Visual Studio 啟動時，它會查看 .addin 檔案位置，以尋找可用的 .addin 檔案。 如果找到檔案，就會讀取 XML 檔案，並將按一下以啟動增益集時所需的資訊提供給 [增益集管理員]。

使用 [增益集精靈] 建立增益集時，會自動建立 .addin 檔案。 您也可以使用本主題中的資訊手動建立 .addin 檔案。

檔案位置

[增益集精靈] 會自動建立兩個 .addin 檔案的複本，如下所述：

若要將增益集安裝在其他電腦上，必須將 .addin 檔放在 Visual Studio 檢查增益集的位置。 在 [增益集/巨集安全性] 頁面上，這些位置會列在 [環境] 節點的 [選項] 對話方塊中。 如需詳細資訊，請參閱Add-in/Macros Security, Environment, Options Dialog Box和增益集安全性。

包含增益集的 .dll 檔可以安裝於用戶端電腦上的任何位置。 不過，我們建議您將它與 .addin 檔放在一起。

注意事項
.addin 檔的 <Assembly> 項目必須指向內含增益集之二進位檔的 .dll 檔案。

.Addin 檔案

.addin XML 檔案分成下列幾個標記區段：

下列項目是 <Addin> 區段的子系：

以下是各項設定的詳細資料。 如需所描述之許多項目的階層位置詳細資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞。

主應用程式

Host Application 區段的 <Name> 項目包含應用程式的名稱。 這是顯示在應用程式標題列上的名稱，或是由 DTE.Name 傳回的名稱。 例如，對於 Visual Studio，此標記會包含 "Microsoft Visual Studio"，而對於巨集 IDE，此標記則會包含 "Microsoft Visual Studio Macros"。

每個 .addin 檔案中可以有一個以上的主應用程式值。 每一個值都必須使用 <Name> 標記括住，並且放在 <HostApplication> 項目內。 除了包含 <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>

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

易記名稱

<FriendlyName> 項目位於 <Addin> 項目之下，用來指定要顯示在 [增益集管理員] 的 [可用的增益集] 欄中的字串。 例如：

   <FriendlyName>My New Super Addin</FriendlyName>

說明

<Description> 項目位於 <Addin> 項目之下，用來指定要顯示在 [增益集管理員] 的 [描述] 方塊中的字串。 例如：

   <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>

組件

<Assembly> 項目位於 <Addin> 項目之下，用來指定增益集二進位檔案的位置。 這個項目可以設定為相對路徑、絕對路徑 ("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 的網路位置。

  <Assembly src="url">http://somewebsite.com/MyAddin4.dll</Assembly>
  

完整類別名稱

<FullClassName> 項目指定用來連接至增益集之類別的完整名稱。 這個項目包含類別的命名空間。 例如：

    <FullClassName>MyAddin4.Connect</FullClassName>

載入行為

<LoadBehavior> 項目可定義增益集是在 IDE 啟動時自動載入，還是以手動方式啟動。 <LoadBehavior> 項目位於 <Addin> 項目之下。 例如：

    <LoadBehavior>1</LoadBehavior>

雖然 <LoadBehavior> 是選擇性使用，但是建議您使用它來明確定義增益集的載入時機。

命令預先載入

<CommandPreload> 項目指定增益集是否必須預先載入。 如果指定預先載入，在安裝 .addin 檔案之後，第一次啟動 Visual Studio 時便會載入增益集。 例如：

    <CommandPreload>1</CommandPreload>

這個項目可讓您指定增益集必須在 Visual Studio 啟動之後載入。 這樣一來，增益集就可以建立必要的 UI 項目 (例如命令列按鈕)，或是執行其他只能在第一次啟動時執行的初始化工作 (例如建立預設的增益集設定)。 增益集會接著卸載，直到使用者執行增益集所建立的其中一個命令為止。 此後，增益集會視需要載入。

您可以檢查您所實作的 OnConnection 方法，確認使用 OnConnection 的第二個引數所指定的連線類型是否為 ext_cm_UISetup。 如果是，就可以使用 AddNamedCommand 或 AddControl 方法，執行您所要的任何命令。

命令列安全

選擇性的 <CommandLineSafe> 項目指示增益集是否設計為在命令提示字元中啟動時不要顯示 UI，例如當您執行命令列建置 (Build) 或類似作業時 (其做法為在 [增益集精靈] 中選取 [我的增益集不會建立強制回應 UI])。此外，它也用來指定與增益集相容的 Visual Studio 模式，例如僅適用於命令列，或僅適用於 IDE。 例如：

    <CommandLineSafe>0</CommandLineSafe>

工具選項頁

選擇性 <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>

請參閱

工作

HOW TO：使用增益集管理員來控制增益集

HOW TO：建立增益集

逐步解說：建立精靈

參考

Visual Studio 命令和參數

概念

Automation 物件模型圖表

其他資源

建立增益集和精靈