Add-in Registration

Article
11/16/2012

After an add-in is created, you must register it with Visual Studio before it becomes available for activation in the Add-In Manager. This is accomplished by using an XML file with a .addin extension.

This file describes the information that Visual Studio requires to display the add-in in the Add-In Manager. When Visual Studio starts, it looks in the .Addin File location for any available .Addin files. If it finds any, it reads the XML file and provides the Add-In Manager with the information needed to start the add-in when it is clicked.

The .Addin file is created automatically when you create an add-in by using the Add-In Wizard, though you can create one manually by using the information in this document.

File Locations

Two copies of the .Addin file are automatically created upon completion of the Add-In Wizard:

.Addin File location	.DLL File Location	Description
Root project folder <My Documents>\Visual Studio 2008\Projects\MyAddin1\MyAddin1	Local path (MyAddin1.dll)	Used for deployment of the add-in project. It is included in the project for ease of editing and is set up with the local path for XCopy-style deployment.
Addin folder <My Documents>\Visual Studio 2008\Addins -or- <Shared Documents Location>\Visual Studio 2008\Addins	Project debug folder (for example, \My Documents\Visual Studio Projects\MyAddin1\MyAddin1\bin)	Used for running the add-in in the debugging environment. Should always point to the output path of the current build configuration.

Root project folder

<My Documents>\Visual Studio 2008\Projects\MyAddin1\MyAddin1

Local path (MyAddin1.dll)

Used for deployment of the add-in project. It is included in the project for ease of editing and is set up with the local path for XCopy-style deployment.

Addin folder

<My Documents>\Visual Studio 2008\Addins

-or-

<Shared Documents Location>\Visual Studio 2008\Addins

Project debug folder

(for example, \My Documents\Visual Studio Projects\MyAddin1\MyAddin1\bin)

Used for running the add-in in the debugging environment. Should always point to the output path of the current build configuration.

To install the add-in on another machine, the .addin file must be placed in a location where Visual Studio checks for addins. These locations are listed in the Add-in/Macros Security, Environment, Options Dialog Box. For more information, see Add-in Security.

The .dll file containing the add-in can reside anywhere on the client machine, but placing it alongside the .addin file is recommended.

Note

The <Assembly> element of the .addin file must point to the .dll file that contains the binaries for the add-in.

The .Addin File

The .Addin XML file is split into the following tagged sections:

Setting	Description
Host Application	(Required.) Specifies the names and version numbers of the applications that can load the add-in.
Addin	(Required) Contains the elements that describe the add-in.
Tools Options Page	(Optional) Specifies a Tools/Options page to configure the add-in. Child nodes specify the category and subcategory the page appears in, and the assembly name and full class name of the options page.

The following elements are children of the <Addin> section:

Setting	Description
About Box Details	(Optional) Specifies the text that will display for your add-in in the Visual Studio Help About dialog box.
About Icon Data	(Optional) Contains binary data that specifies the icon that will display for your add-in in the Visual Studio Help About dialog box.
About Icon Location	(Optional) Specifies the absolute or relative path to the icon that will display for your add-in in the Visual Studio Help About dialog box.
Assembly	(Required.) Specifies the location of the add-in binaries. This field can be set to a local path, a network path, or a valid URL.
Command Line Safe	(Optional) Specifies the Visual Studio modes with which the add-in is compatible, such as command line only, integrated development environment (IDE) only, or both.
Command Preload	(Optional) Specifies the add-in's preloaded state, that is, whether or not the add-in should create its user interface (UI) by using a method such as Commands.AddNamedCommand.
Full Class Name	(Required.) Specifies the name of the class used to connect to the add-in.
Load Behavior	(Optional) Defines whether an add-in is loaded at startup or manually.

Following are details for each setting.

Host Application

The Host Application's <Name> tag contains the name of the application. This is the name displayed in the title bar of the application or returned by DTE.Name. So, for example, for Visual Studio, the tag would contain "Microsoft Visual Studio," and for the Macros IDE, the tag would contain "Microsoft Visual Studio Macros."

There can be more than one Host Application value per .Addin file. Each value must be bracketed by the <Name> tag within the <HostApplication> tag. In addition to the <Name> tag, each <HostApplication> tag must also include the version number of that application bracketed by <Version> tags. For example:

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

Alternatively, you can specify an asterisk (*) to represent the value for <Version> for any version of Visual Studio. See the section, Example .Addin XML File, later in this topic for the hierarchical location of these tags.

Friendly Name

The <FriendlyName> tag, located under the <Addin> tag, specifies the string that will display in the Available Add-ins column for the add-in in the Add-in Manager. Following is an example of its usage:

   <FriendlyName>My New Super Addin</FriendlyName>

See the section, Example .Addin XML File, later in this topic for the hierarchical location of this tag.

Description

The <Description> tag, located under the <Addin> tag, specifies the string that will display in the Description box for the add-in in the Add-in Manager. Following is an example of its usage:

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

See the section, Example .Addin XML File, later in this topic for the hierarchical location of this tag.

About Box Details

If you select the option to generate settings for the Help About dialog box when you create your add-in, this tag is added to the .Addin file. This tag specifies the text that will display for your add-in in the Visual Studio Help About dialog box. Following is an example of its usage:

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

See the section, Example .Addin XML File, later in this topic for the hierarchical location of this tag.

About Icon Data

If you select the option to generate settings for the Help About dialog box when you create your add-in, this tag is added to the .Addin file. This tag contains binary data that specifies the icon that will display for your add-in in the Visual Studio Help About dialog box. Following is an example of its usage:

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

See the section, Example .Addin XML File, later in this topic for the hierarchical location of this tag.

Assembly

The <Assembly> tag, located under the <Addin> tag, specifies the location of the add-in binary files. This tag can be set to a local path, a network path ("file"), a registered assembly name ("assembly"), or a valid URL ("url"). See the section, Example .Addin XML File, later in this topic for the hierarchical location of this tag.

Following is an example of a URL add-in location. In this case, the src parameter is set to url to indicate the Web-based location of the add-in's DLL:
```
<Assembly src="url">http://somewebsite.com/MyAddin4.dll</Assembly>
```
Following is an example of a local path location. In this case, the src parameter is set to file to indicate the local location of the add-in's DLL:
```
<Assembly src="file">C:\Documents and Settings\jdoe\Application Data\Microsoft\Visual Studio\8.0\AddIns\MyAddin4.dll</Assembly>
```
Following is an example of a local path. In this case, the src parameter is set to assembly to indicate the Web-based location of the add-in's DLL:
```
<Assembly src="assembly">BookshelfDefineAddin</Assembly>
```

Full Class Name

The <FullClassName> tag specifies the full name of the class used to connect to the add-in, including the namespace containing the class. Following is an example usage:

    <FullClassName>MyAddin4.Connect</FullClassName>

See the section, Example .Addin XML File, later in this topic for the hierarchical location of this tag.

Load Behavior

The <LoadBehavior> tag defines whether an add-in is loaded automatically at IDE startup or whether it is started manually. The <LoadBehavior> tag is under the <Addin> tag. Following is an example usage:

    <LoadBehavior>1</LoadBehavior>

While usage of the <LoadBehavior> tag is optional, it is recommended that you use it to explicitly define when an add-in loads.

Value	Description
0	The add-in is not loaded at IDE startup and must be started manually.
1	The add-in is automatically loaded at IDE startup.
4	The add-in is loaded when devenv is started from the command line with a build switch (devenv /build).

See the section, Example .Addin XML File, later in this topic for the hierarchical location of this tag.

Command Preload

The <CommandPreload> tag specifies whether or not the add-in must be preloaded. Preloading loads the add-in the first time that Visual Studio starts after placing the .Addin file on disk. Following is an example usage:

    <CommandPreload>1</CommandPreload>

This tag allows you to specify that an add-in must be loaded after Visual Studio starts. It gives your add-in a chance to create necessary user interface elements, such as command bar buttons, or perform other first-time-only initialization tasks, such as creating default add-in settings. The add-in is then immediately unloaded until a user executes one of the commands the add-in created, which then loads the add-in as needed in all successive instances of the IDE.

Value	Description
0	The add-in does not load until either the user starts it through the Add-In Manager or the add-in is set to load on startup.
1	The add-in is loaded automatically when Visual Studio starts for the first time after the .Addin XML file is placed on disk.

You can check the OnConnection method you implement to see if the type of connection, specified with the second argument to OnConnection, is ext_cm_UISetup. If it is, you can perform whatever command placements you want by using the AddNamedCommand or AddControl methods.

See the section, Example .Addin XML File, later in this topic for the hierarchical location of this tag.

Command Line Safe

The optional <CommandLineSafe> tag indicates whether the add-in was designed to avoid displaying a UI when started by the devenv command line, such as when performing command-line builds or similar operations. (This is done by choosing the My Add-in will never put up a modal UI option in the Add-in Wizard.) Also, it specifies the Visual Studio modes with which the add-in is compatible, such as command line only or IDE only. Following is an example usage:

    <CommandLineSafe>0</CommandLineSafe>

Value	Description
0	Specifies that the add-in is not command-line safe and may display a UI.
1	Specifies that the add-in is command-line safe and does not display a UI.

See the section, Example .Addin XML File, later in this topic for the hierarchical location of this tag.

Tools Options Page

The optional <ToolsOptionsPage> tag specifies a tools/options page for users to configure the add-in. Child nodes specify the category and subcategory the page appears in, and the assembly name and full class name of the options page. The following example shows the hierarchy of this element:

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

Example .Addin XML File

The following is an example of a complete .Addin XML file. It shows the hierarchy and locations for the aforementioned tags.

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

Share via

Add-in Registration

File Locations

The .Addin File

Host Application

Friendly Name

Description

About Box Details

About Icon Data

Assembly

Full Class Name

Load Behavior

Command Preload

Command Line Safe

Tools Options Page

Example .Addin XML File

See Also

Tasks

Concepts

Reference

Other Resources

Additional resources