Export (0) Print
Expand All

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 was done in previous versions of Visual Studio by using registry keys, but this is now accomplished by using an XML file.

NoteNote

The .Addin file is created automatically when you create an add-in by using the Add-In Wizard. The following information applies only if you want to manually create or edit the add-in's registration file.

In Visual Studio .NET 2002 and Visual Studio .NET 2003, you were required to register add-in assemblies with Windows as COM components by using the Assembly Registration Tool (regasm.exe). Also, you were required to register the add-in with Visual Studio by using keys in the Windows registry before the add-in would appear in the Add-In Manager.

These steps have changed in Visual Studio 2005. You no longer need to register the .NET assemblies with Windows by using regasm. Instead, you simply place the assembly .DLL file into a specific directory (described later in this topic) along with an XML file that has an .Addin file extension. This XML 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 (listed below) 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.

This simplified registration method allows XCopy-style installations for managed code add-ins. If you put all the files in the right place, then your add-in works just fine. Also, its use of commented XML to define the registration settings for add-ins allows the information to be more easily understood and edited than registry keys.

The .Addin File

A new XML file with the extension, .Addin, replaces the old add-in registry settings. Two copies of the .Addin file are automatically created upon completion of the Add-In Wizard:

.Addin File location .DLL File Location Description

Addin folder

(for example, \Documents and Settings\All Users\My Documents\Visual Studio 2005\Addins)

-or-

\Documents and Settings\<user name>\My Documents\Visual Studio 2005\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

(for example, \My Documents\Visual Studio\Projects\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.

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.

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.

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.

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 EnvDTE.Commands.AddNamedCommand(EnvDTE.AddIn,System.String,System.String,System.String,System.Boolean,System.Int32,System.Object[],System.Int32).

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.

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>8.0</Version>
   </HostApplication>
   <HostApplication>
      <!-- An additional supported program/version. -->
      <Name>Microsoft Visual Studio Macros</Name>
      <Version>8.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.

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.

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="http://schemas.microsoft.com/AutomationExtensibility">
    <HostApplication>
        <Name>Microsoft Visual Studio Macros</Name>
        <Version>8.0</Version>
    </HostApplication> 
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>8.0</Version>
    </HostApplication>
    <Addin>
        <FriendlyName>My great new add-in.</FriendlyName>
        <Description>This add-in does it all.</Description>
        <AboutBoxDetails>Copyright 2005.</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

Community Additions

ADD
Show:
© 2014 Microsoft