Revit API 101.2

The topic for this post will be centered on the .addin manifest file and how Add-Ins get loaded into the Revit session. The schema or file organization of the .addin file format will be discussed at first and then I'll explain a little bit about the options you have for configuring the manifest file up so that it loads the resources necessary for your tool to run automatically during debug.

Sorry if you've been hoping for a video, but this kind of information is best absorbed through good old fashioned black and white. And as far as language examples, these concepts are virtually identical between C# and VB.NET.

What is the .addin Manifest File?

For those of you that have experience using Revit Add-Ins in versions prior to Revit 2010, you may remember the old cryptic method of loading an Add-In by editing the Revit.ini file. The old Revit.ini method of loading Add-Ins into Revit is now obsolete and replaced by what is referred to as a manifest file. Manifest files are XML formatted ASCII files that tell Revit where the Add-In resources are and what class that the required IExternalApplication, IExternalCommand, or IExternalDBApplication interface has been implemented so that Revit can load the necessary commands and functionality into the session.

Revit searches for .addin files in two locations. The directory paths shown here are for Windows 7. Replace the YYYY in the paths below to match your Revit 2010 or higher installation versions (2010, 2011, 2012, 2013, etc.).

Constant for all users on the machine (may require admin permissions to modify)

• C:\ProgramData\Autodesk\Revit\Addins\YYYY

Current user logged into Windows only (does not require admin permissions to modify)

• %USERPROFILE%\AppData\Roaming\Autodesk\Revit\Addins\YYYY

Required Manifest Tags

There are slightly different requirements between command and application load manifests and quite a few optional tags that you can utilize in your .addin manifest files. This section will focus on the required tags. First I'll outline the required tags that are consistent for both application and command loading manifests and then the one tag specific to application load sequences.

Assembly (Required all All)

This tag is required for all kinds of applications and commands. It must contain the full file name to your DLL file. It is only required to contain a full path to the DLL if the DLL does not exist within the same directory as the .addin file. Relative pathing is supported by entering ".\" before the file path and or name so long as the directory is located beneath the same directory that the .addin file resides.

ClientId (Required for All)

A complete and fully qualified global unique identifier is required in this tag. This GUID needs to be unique across all other application or command ClientId's loaded in your session.

FullClassName (Required for All)
This is where you would enter the namespace(s) followed by the class name that contains the command or application interface that you want to execute or load. This tag should never have any spaces contained in it.

VendorId (Required for All Revit 2012 and Higher)
The four digit registered developer ID that can be obtained from the ADN site to identify the developer.

VendorDescription (Required for All Revit 2012 and Higher)
An explanation or description for the developer. It is common to list the company name and or the web address to a support site that relates to the tool.

Name (Applications Only)
A unique name for the application.

A Sample Manifest File

As you can see in the sample .addin file below, it is possible to nest multiple command and applications load sequences into a common .addin file. A sample application load sequence is loaded first with a command after it. The important thing to remember when combining multiple command or application loads is that they are all nested inside a single "RevitAddIns" tag.

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Application">
    <Name>Application Name</Name>
    <Assembly>Namespace.dll</Assembly>
    <ClientId>4ea76ff3-bba7-4969-9371-c7a3eb8ac0a8</ClientId>
    <FullClassName>Namespace.Class</FullClassName>
    <VendorId>XXXX</VendorId>
    <VendorDescription>Something about the developer, Link</VendorDescription>
  </AddIn>
  <AddIn Type="Command">
    <Text>My Command Name</Text>
    <Description>Example Command Description</Description>
    <Assembly>Namespace.dll</Assembly>
    <FullClassName>Namespace.CommandClass</FullClassName>
    <ClientId>9db2c58d-33f2-4ad1-8932-329dd83a4d0a</ClientId>
    <VendorId>XXXX</VendorId>
    <VendorDescription>Something about the developer, Link</VendorDescription>
  </AddIn>
</RevitAddIns>

Automatic Copying of a Solution Manifest to Install on Debug

You can have your .addin manifest copied to your .addins load directory automatically while debugging in Visual Studio by setting a post build event. This requires that your .addin file exist in the root of your project and included within your project's solution. An example on where and how to enter this to work on a Visual Basic .NET example is shown below.

Note: If you left out a file path to your assembly (file name only), you will be able to debug from your debug directory location during debug mode as well as run the main DLL in your Add-In load directory using the same manifest file. You will need to adjust command below to match the Revit version year and .addin file name as required. Just remember, you will need to include your .addin file withini your Visual Studio solution for this trick to work.


copy "$(ProjectDir)MyAddinFile.addin"
"$(AppData)\Autodesk\REVIT\Addins\2012\MyAddinFile.addin"