共用方式為

增益集登錄

  • 發行項

更新：2007 年 11 月

建立增益集 (Add-In) 之後，您必須先將它登錄至 Visual Studio 中，才能在 [增益集管理員] 中啟動該增益集。在舊版的 Visual Studio 中，這個程序是透過登錄機碼 (Registry Key) 來完成，現在則是透過 XML 檔案來完成。

注意事項：

使用 [增益集精靈] 建立增益集時，會自動建立 .Addin 檔案。只有當您想要以手動方式建立或編輯增益集的登錄檔案時，下列資訊才適用。

在 Visual Studio .NET 2002 和 Visual Studio .NET 2003 中，您必須使用組件登錄工具 (regasm.exe) 將增益集組件 (Assembly) 登錄為 Windows 中的 COM 元件。此外，您必須先使用 Windows 登錄中的機碼將增益集登錄至 Visual Studio 中，增益集才會出現在 [增益集管理員] 中。

這些步驟從 Visual Studio 2005 開始已有所變更。您不再需要使用 regasm 將 .NET 組件登錄至 Windows 中，只需要將組件的 .DLL 檔案與副檔名為 .Addin 的 XML 檔案一起放在特定的目錄中 (本主題稍後會有說明) 就可以了。這個 XML 檔案會描述 Visual Studio 將增益集顯示在 [增益集管理員] 中所需要的資訊。當 Visual Studio 啟動時，它會查看 .Addin 檔案的位置 (如下所示)，以尋找可用的 .Addin 檔案。如果找到檔案，就會讀取 XML 檔案，並將按一下以啟動增益集時所需要的資訊提供給 [增益集管理員]。

這種簡化的登錄方式可以讓 Managed 程式碼增益集採用 XCopy 的安裝方式。只要您將所有檔案都放在正確位置，增益集就可以正常運作。此外，相較於登錄機碼，這種方式會使用加了註解的 XML 來定義增益集的登錄設定，讓使用者更容易了解及編輯相關資訊。

.Addin 檔案

新的 XML 檔案具有 .Addin 副檔名，會取代舊的增益集登錄設定。[增益集精靈] 完成時，會自動建立兩個 .Addin 檔案的複本：

.Addin 檔案位置

.DLL 檔案位置

描述

增益集資料夾

(例如 \Documents and Settings\All Users\Shared Documents\Visual Studio 2008\Addins)

-或-

\Documents and Settings\<user name>\My Documents\Visual Studio 2008\Addins)

專案偵錯資料夾

(例如 \My Documents\Visual Studio Projects\MyAddin1\MyAddin1\bin)

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

根專案資料夾

(例如 \My Documents\Visual Studio\Projects\MyAddin1)

本機路徑 (MyAddin1.dll)

用來部署增益集專案。將其包含在專案中是為了方便編輯，而且已依據 XCopy 部署方式的本機路徑進行設定。

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

設定

描述

主應用程式

(必要項) 指定可以載入增益集之應用程式的名稱和版本號碼。

組件

(必要項) 指定增益集二進位碼檔案的位置。這個欄位可以設定為本機路徑、網路路徑或有效的 URL。

完整類別名稱

(必要項) 指定用來連接至增益集之類別的名稱。

載入行為

(選擇項) 定義增益集是在啟動時載入，還是以手動方式載入。

命令預先載入

(選擇項) 指定增益集的預先載入 (Preload) 狀態，也就是說，增益集是否要使用方法建立使用者介面 (UI)，例如 Commands.AddNamedCommand。

命令列安全

(選擇項) 指定與增益集相容的 Visual Studio 模式，例如僅適用於命令列、僅適用於整合式開發環境 (IDE)，或兩者都適用。

以下將詳細說明各項設定。

主應用程式

主應用程式 (Host Application) 的 <Name> 標記 (Tag) 包含應用程式的名稱。這是顯示在應用程式標題列中的名稱，或是由 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>9.0</Version>
   </HostApplication>
   <HostApplication>
      <!-- An additional supported program/version. -->
      <Name>Microsoft Visual Studio Macros</Name>
      <Version>9.0</Version>
   </HostApplication>

或者，您可以指定用星號 (*) 來表示 <Version> 的值，以代表 Visual Studio 的任何版本。如需這些標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

易記名稱

<FriendlyName> 標記位於 <Addin> 標記之下，用來指定要顯示在 [增益集管理員] 中增益集的 [可用的增益集] 欄中的字串。下列是其使用方式範例：

   <FriendlyName>My New Super Addin</FriendlyName>

如需此標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

描述

<Description> 標記位於 <Addin> 標記之下，用來指定要顯示在 [增益集管理員] 中增益集的 [描述] 方塊中的字串。下列是其使用方式範例：

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

如需此標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

關於對話方塊詳細資料

如果您在建立增益集時選取要產生 [關於] 對話方塊之設定的選項，就會在 .Addin 檔案中加入這個標記。這個標記用來指定要顯示在 Visual Studio 說明 [關於] 對話方塊中的增益集文字。下列是其使用方式範例：

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

如需此標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

關於圖示資料

如果您在建立增益集時選取要產生 [關於] 對話方塊之設定的選項，就會在 .Addin 檔案中加入這個標記。這個標記包含二進位資料，用來指定要顯示在 Visual Studio 說明 [關於] 對話方塊中的增益集圖示。下列是其使用方式範例：

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

如需此標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

組件

<Assembly> 標記位於 <Addin> 標記之下，用來指定增益集二進位檔案 (Binary File) 的位置。這個標記可以設定為本機路徑、網路路徑 ("file")、已登錄的組件名稱 ("assembly") 或有效的 URL ("url")。如需此標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

  • 下列是 URL 增益集位置的範例。在這個範例中，src 參數設定為 url，用來指示增益集 DLL 的網路位置：

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

  • 下列是本機路徑位置的範例。在這個範例中，src 參數設定為 file，用來指示增益集 DLL 的本機位置：

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

  • 下列是本機路徑的範例。在這個範例中，src 參數設定為 assembly，用來指示增益集 DLL 的網路位置：

    <Assembly src="assembly">BookshelfDefineAddin</Assembly>

完整類別名稱

<FullClassName> 標記用來指定連接至增益集所使用的完整類別名稱，包括內含類別的命名空間。下列是使用方式範例：

    <FullClassName>MyAddin4.Connect</FullClassName>

如需此標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

載入行為

<LoadBehavior> 標記用來定義增益集是在 IDE 啟動時自動載入，還是以手動方式載入。<LoadBehavior> 標記位於 <Addin> 標記之下。下列是使用方式範例：

    <LoadBehavior>1</LoadBehavior>

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

值

描述

0

IDE 啟動時不要載入增益集，必須以手動方式載入。

1

IDE 啟動時自動載入增益集。

4

從命令列以 build 參數啟動 devenv (devenv /build) 時載入增益集。

如需此標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

命令預先載入

<CommandPreload> 標記用來指定增益集是否必須預先載入。如果指定預先載入，在將 .Addin 檔案放到磁碟上之後，Visual Studio 第一次啟動時便會載入增益集。下列是使用方式範例：

    <CommandPreload>1</CommandPreload>

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

值

描述

0

在使用者透過 [增益集管理員] 啟動增益集，或是將增益集設定為在啟動時自動載入之前，不會載入增益集。

1

在將 .Addin XML 檔案放到磁碟上之後，Visual Studio 第一次啟動時會自動載入增益集。

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

如需此標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

命令列安全

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

    <CommandLineSafe>0</CommandLineSafe>

值

描述

0

指定增益集非命令列安全，而且可以顯示 UI。

1

指定增益集為命令列安全，而且不會顯示 UI。

如需此標記的階層位置資訊，請參閱本主題中稍後的＜.Addin XML 檔案範例＞一節。

.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>9.0</Version>
    </HostApplication> 
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>9.0</Version>
    </HostApplication>
    <Addin>
        <FriendlyName>My great new add-in.</FriendlyName>
        <Description>This add-in does it all.</Description>
        <AboutBoxDetails>Copyright 2008.</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：建立增益集

逐步解說：建立精靈

概念

Automation 物件模型圖表

參考

Visual Studio 命令和參數

其他資源

建立增益集和精靈