增益集登錄

發行項
06/10/2015

.Visual Studio 增益集在 Visual Studio 2013 中已被取代。您應該將增益集升級為 VSPackage 擴充功能。如需升級的詳細資訊，請參閱常見問題集：將增益集轉換成 VSPackage 擴充功能。

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

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

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

檔案位置

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

.Addin 檔案位置	.DLL 檔案位置	描述
根專案資料夾 \Documents\Visual Studio 2013\Projects\MyAddin1\MyAddin1\	本機路徑 (MyAddin1.dll)	用來部署增益集專案。包含在專案中以便輕鬆編輯，而且具有 xcopy 部署方式的本機路徑。
增益集資料夾 \Documents\Visual Studio 2013\Addins\ -或- Shared Documents Location\Addins\	專案偵錯資料夾 (例如 \Documents\Visual Studio 2013 Projects\MyAddin1\MyAddin1\bin\)	用來在偵錯環境中執行增益集。必須指向目前組建組態的輸出路徑。

根專案資料夾

\Documents\Visual Studio 2013\Projects\MyAddin1\MyAddin1\

本機路徑 (MyAddin1.dll)

用來部署增益集專案。包含在專案中以便輕鬆編輯，而且具有 xcopy 部署方式的本機路徑。

增益集資料夾

\Documents\Visual Studio 2013\Addins\

-或-

Shared Documents Location\Addins\

專案偵錯資料夾

(例如 \Documents\Visual Studio 2013

Projects\MyAddin1\MyAddin1\bin\)

用來在偵錯環境中執行增益集。必須指向目前組建組態的輸出路徑。

若要在另一台電腦上安裝增益集，必須將 .addin 檔放在 Visual Studio 檢查增益集的位置中。這些位置列於 [增益集安全性] 頁面上 [環境] 節點中的 [選項] 對話方塊中。如需詳細資訊，請參閱增益集安全性。

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

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

.Addin 檔

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

區段	描述
主機應用程式	(必要項。)指定可以載入增益集之應用程式的名稱和版本號碼。
Addin	(必要項) 包含描述增益集的項目。
工具選項頁面	(選擇性) 在 [選項] 對話方塊中指定可以在其中設定增益集的頁面。子節點指定 [選項] 頁面的分類和子分類，並指定其組件名稱和完整類別名稱。

下列項目是 <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"。

每個 .addin 檔可能會有多個主機應用程式值。每個值都必須以 <HostApplication> 項目中的 <Name> 標記括住。除了包含 <Name> 項目之外，每個 <HostApplication> 項目還必須包括以 <Version> 標記括住的應用程式版本號碼。例如：

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

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

易記名稱

<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\12.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。 (在 [增益集精靈] 中選取 [我的增益集絕不建立強制回應 UI] 即可完成此動作。)此外，它會指定與增益集相容的 Visual Studio 模式，例如僅命令列或僅 IDE。例如：

    <CommandLineSafe>0</CommandLineSafe>

值	描述
0	指定增益集並非命令列安全，並可能會顯示 UI。
1	指定增益集為命令列安全，且不會顯示 UI。

工具選項頁面

選擇性的 <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</Name>
        <Version>12.0</Version>
    </HostApplication> 
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>11.0</Version>
    </HostApplication>
    <Addin>
        <FriendlyName>My great new add-in.</FriendlyName>
        <Description>This add-in does it all.</Description>
        <AboutBoxDetails>Copyright 2013.</AboutBoxDetails>
        <AboutIconData>0000 . . . FFFF0000</AboutIconData>
        <Assembly>MyNewAddin.dll</Assembly>
        <FullClassName>MyNewAddin.Connect</FullClassName>
        <LoadBehavior>1</LoadBehavior>
        <CommandPreload>1</CommandPreload>
        <CommandLineSafe>0</CommandLineSafe>
    </Addin>
</Extensibility>

請參閱

共用方式為