Add-in Registration

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:

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.

The .Addin File

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

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

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.

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.

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>

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>

See Also

Tasks

How to: Control Add-ins with the Add-In Manager

How to: Create an Add-In

Walkthrough: Creating a Wizard

Concepts

Automation Object Model Chart

Reference

Visual Studio Commands and Switches

Other Resources

Creating Add-ins and Wizards