Add-in Registration

External commands and external applications need to be registered in order to appear inside Revit. They can be registered by adding them to a .addin manifest file.

The order that external commands and applications are listed in Revit is determined by the order in which they are read in when Revit starts up.

Manifest Files

Starting with Revit 2011, the Revit API offers the ability to register API applications via a .addin manifest file. Manifest files are read automatically by Revit when they are placed in one of two locations on a user's system:

In a non-user-specific location in "application data":

For Windows XP - C:\Documents and Settings\All Users\Application Data\Autodesk\Revit\Addins\2014\
For Vista/Windows 7 - C:\ProgramData\Autodesk\Revit\Addins\2014\

In a user-specific location in "application data":

For Windows XP - C:\Documents and Settings\<user>\Application Data\Autodesk\Revit\Addins\2014\
For Vista/Windows 7 - C:\Users\<user>\AppData\Roaming\Autodesk\Revit\Addins\2014\

All files named .addin in these locations will be read and processed by Revit during startup. All of the files in both the user-specific location and the all users location are considered together and loaded in alphabetical order. If an all users manifest file shares the same name with a user-specific manifest file, the all users manifest file is ignored. Within each manifest file, the external commands and external applications are loaded in the order in which they are listed.

A basic file adding one ExternalCommand looks like this:

Code Region 3-9: Manifest .addin ExternalCommand

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
        <AddIn Type="Command">
                <Assembly>c:\MyProgram\MyProgram.dll</Assembly>
                <AddInId>76eb700a-2c85-4888-a78d-31429ecae9ed</AddInId>
                <FullClassName>Revit.Samples.SampleCommand</FullClassName>
                <Text>Sample command</Text>
                <VendorId>ADSK</VendorId>
                <VendorDescription>Autodesk, www.autodesk.com</VendorDescription> 
                <VisibilityMode>NotVisibleInFamily</VisibilityMode>
                <Discipline>Structure</Discipline>
                <Discipline>Architecture</Discipline>
                <AvailabilityClassName>Revit.Samples.SampleAccessibilityCheck</AvailabilityClassName>
                <LongDescription>
                        This is the long description for my command.
                        This is another descriptive paragraph, with notes about how to use the command properly.
                </LongDescription>
                <TooltipImage>c:\MyProgram\Autodesk.png</TooltipImage>
                <LargeImage>c:\MyProgram\MyProgramIcon.png</LargeImage>
        </AddIn>
</RevitAddIns>

A basic file adding one ExternalApplication looks like this:

Code Region 3-10: Manifest .addin ExternalApplication

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="Application">
                <Name>SampleApplication</Name>
                <Assembly>c:\MyProgram\MyProgram.dll</Assembly>
                <AddInId>604B1052-F742-4951-8576-C261D1993107</AddInId>
                <FullClassName>Revit.Samples.SampleApplication</FullClassName>
                <VendorId>ADSK</VendorId>
                <VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
</AddIn>
</RevitAddIns>

A basic file adding one DB-level External Application looks like this:

Code Region: Manifest .addin ExternalDBApplication

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="DBApplication">
                <Assembly>c:\MyDBLevelApplication\MyDBLevelApplication.dll</Assembly>
                <AddInId>DA3D570A-1AB3-4a4b-B09F-8C15DFEC6BF0</AddInId>

                <FullClassName>MyCompany.MyDBLevelAddIn</FullClassName>

                <Name>My DB-Level AddIn</Name>                    
                <VendorId>ADSK</VendorId>
                <VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
</AddIn>
</RevitAddIns>

Multiple AddIn elements may be provided in a single manifest file.

The following table describes the available XML tags:

Tag	Description
Assembly	The full path to the add-in assembly file. Required for all ExternalCommands and ExternalApplications.
FullClassName	The full name of the class in the assembly file which implements IExternalCommand or IExternalApplication. Required for all ExternalCommands and ExternalApplications.
AddInId	A GUID which represents the id of this particular application. AddInIds must be unique for a given session of Revit. Autodesk recommends you generate a unique GUID for each registered application or command. Required for all ExternalCommands and ExternalApplications.
Name	The name of application. Required; for ExternalApplications only.
Text	The name of the button. Optional; use this tag for ExternalCommands only. The default is "External Tool".
VendorId	A string conforming to the Autodesk vendor ID standard. Required for all ExternalCommands and ExternalApplications. Register your vendor id string with Autodesk at http://www.autodesk.com/symbreg.
VendorDescription	Description containing vendor's legal name and/or other pertinent information. Optional.
Description	Short description of the command, will be used as the button tooltip. Optional; use this tag for ExternalCommands only. The default is a tooltip with just the command text.
VisibilityMode	The modes in which the external command will be visible. Multiple values may be set for this option. Optional; use this tag for ExternalCommands only. The default is to display the command in all modes, including when there is no active document. Previously written external commands which need to run against the active document should either be modified to ensure that the code deals with invocation of the command when there is no active document, or apply the NotVisibleWhenNoActiveDocument mode. See table below for more information.
Discipline	The disciplines in which the external command will be visible. Multiple values may be set for this option. Optional; use this tag for ExternalCommands only. The default is to display the command in all disciplines. If any specific disciplines are listed, the command will only be visible in those disciplines. See table below for more information.
AvailabilityClassName	The full name of the class in the assembly file which implemented IExternalCommandAvailability. This class allows the command button to be selectively grayed out depending on context. Optional; use this tag for ExternalCommands only. The default is a command that is available whenever it is visible.
LargeImage	The icon to use for the button in the External Tools pulldown menu. Optional; use this tag for ExternalCommands only. The default is to show a button without an icon.
SmallImage	The icon to use if the button is promoted to the Quick Access Toolbar. Optional; use this tag for ExternalCommands only. The default is to show a Quick Access Toolbar button without an icon, which can be confusing to users.
LongDescription	Long description of the command, will be used as part of the button extended tooltip, shown when the mouse hovers over the command for a longer amount of time. Optional; use this tag for ExternalCommands only. If this property and TooltipImage are not supplied, the button will not have an extended tooltip.
TooltipImage	An image file to show as a part of the button extended tooltip, shown when the mouse hovers over the command for a longer amount of time. Optional; use this tag for ExternalCommands only. If this property and TooltipImage are not supplied, the button will not have an extended tooltip.
LanguageType	Localization setting for Text, Description, LargeImage, LongDescription, and TooltipImage of external tools buttons. Revit will load the resource values from the specified language resource dll. The value can be one of the eleven languages supported by Revit. If no LanguageType is specified, the language resource which the current session of Revit is using will be automatically loaded. For more details see the section on Localization.
AllowLoadIntoExistingSession	The flag for loading permission. Set to false to prevent Revit from automatically loading addins in a newly added .addin manifest file without restarting. Optional. By default. Revit will automatically load addins from newly added .addin manifest files without restarting Revit.

Table 3: VisibilityMode Members

Member Name	Description
AlwaysVisible	The command is available in all possible modes supported by the Revit API.
NotVisibleInProject	The command is invisible when there is a project document active.
NotVisibleInFamily	The command is invisible when there is a family document active.
NotVisibleWhenNoActiveDocument	The command is invisible when there is no active document.

Table 4: Discipline Members

Member Name	Description
Any	The command is available in all possible disciplines supported by the Revit API.
Architecture	The command is visible in Autodesk Revit Architecture.
Structure	The command is visible in Autodesk Revit Structure.
StructuralAnalysis	The command is visible when the Structural Analysis discipline editing tools are available.
MassingAndSite	The command is visible when the Massing and Site discipline editing tools are available.
EnergyAnalysis	The command is visible when Energy Analysis discipline editing tools are available.
Mechanical	The command is visible when the Mechanical discipline editing tools are available, e.g. in Autodesk Revit MEP.
Electrical	The command is visible when the Electrical discipline editing tools are available, e.g. in Autodesk Revit MEP.
Piping	The command is visible when the Piping discipline editing tools are available, e.g. in Autodesk Revit MEP.
MechanicalAnalysis	The command is visible when the Mechanical Analysis discipline editing tools are available.
PipingAnalysis	The command is visible when the Piping Analysis discipline editing tools are available.
ElectricalAnalysis	The command is visible when the Electrical Analysis discipline editing tools are available.

.NET Add-in Utility for manifest files

The .NET utility DLL RevitAddInUtility.dll offers a dedicated API capable of reading, writing and modifying Revit Add-In manifest files. It is intended for use from product installers and scripts. Consult the API documentation in the RevitAddInUtility.chm help file in the SDK installation folder.

Code Region 3-11: Creating and editing a manifest file

//create a new addin manifest
RevitAddInManifest Manifest = new RevitAddInManifest();

//create an external command
RevitAddInCommand command1 = new RevitAddInCommand("full path\\assemblyName.dll", 
     Guid.NewGuid(), "namespace.className");
command1.Description = "description";
command1.Text = "display text";

// this command only visible in Revit MEP, Structure, and only visible 
// in Project document or when no document at all
command1.Discipline = Discipline.Mechanical | Discipline.Electrical |
                        Discipline.Piping | Discipline.Structure;
command1.VisibilityMode = VisibilityMode.NotVisibleInFamily;

//create an external application
RevitAddInApplication application1 = new RevitAddInApplication("appName",
    "full path\\assemblyName.dll", Guid.NewGuid(), "namespace.className");

//add both command(s) and application(s) into manifest
Manifest.AddInCommands.Add(command1);
Manifest.AddInApplications.Add(application1);

//save manifest to a file
RevitProduct revitProduct1 = RevitProductUtility.GetAllInstalledRevitProducts()[0];
Manifest.SaveAs(revitProduct1.AllUsersAddInFolder + "\\RevitAddInUtilitySample.addin");

Code Region 3-12: Reading an existing manifest file

RevitProduct revitProduct1 = RevitProductUtility.GetAllInstalledRevitProducts()[0];

RevitAddInManifest revitAddInManifest = 
     Autodesk.RevitAddIns.AddInManifestUtility.GetRevitAddInManifest(
          revitProduct1.AllUsersAddInFolder + "\\RevitAddInUtilitySample.addin");