Developers have always had a lot of complaints about the Revit.ini add-in registration facility. It was hard to access and modify the file in the Revit installation directory and the same file is shared by all users. Revit 2011 offers a completely new and vastly improved add-in registration facility using add-in manifest files. The new mechanism supports a number of new options and there is no reason to continue using the obsolete Revit.ini mechanism. Let's have a look at this new mechanism and also present a little tool that I developed to simplify one aspect in the creation of these files:
An add-in manifest is an XML file located in specific location on the hard disk. It can apply either to a specific user or all. There are some required tags which must be specified for both an external application and an external command, such as Assembly, FullClassName, ClientId. An external command also uses the Text and Description tags. These required tags provide the same information as the entries used in the obsolete Revit.ini add-in registration mechanism. However, the add-in manifest also offers a large number of exciting new functionality, and therefore many new optional tags can be used to define tooltip, image, visibility, availability, localisation and other features.
Here is an example of a minimal add-in manifest file for an external command:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIn>
<AddIn Type="Command">
<Text>Convert Pipes to Conduits</Text>
<Description>Convert Pipes to Conduits</Description>
<Assembly>C:\src\p2c\p2c\bin\Debug\p2c.dll</Assembly>
<FullClassName>p2c.Command</FullClassName>
<ClientId>835d6ad1-1a99-4039-95dc-e752ff635928</ClientId>
</AddIn>
</RevitAddIn>
Manifest files are read automatically by Revit when they are placed in one of the following two locations in the Application Data folder on a user's system. There are separate locations for individual users or all users, and they also depend on whether you are running Windows XP or Vista/Windows 7:
All files with an '.addin' filename extension found in these locations will be read and processed by Revit during start-up. Multiple add-ins may be loaded by a single manifest file. The manifest file syntax defines tags allowing you to specify all the information previously defined in the Revit.ini registration data, i.e. assembly path, full class name, text and description:
This significantly simplifies installation, since all you have to do is copy the add-in assembly to your hard disk, update the assembly path specified in the manifest file, and copy the manifest file to the desired location where Revit can pick it up without affecting any other existing functionality or touching any Revit files or other parts of the Revit installation.
So to install an add-in, you simply copy the manifest file to the appropriate application data location on the hard disk. An installer may obviously need to update the assembly path. The Revit SDK includes the add-in utility DLL which can be used to edit or automatically generate the manifest file on the fly. It supports reading, writing and manipulation of manifest files and also querying the Revit product installation locations.
One little thing to note is that for a serious application, due to .NET framework restrictions and issues with Load versus LoadFrom, it is recommended to place the add-in into the Revit Program folder in the same location as Revit.exe.
The Revit.ini registration mechanism remains in place for the 2011 release but will be removed in the future. It does not offer any of the new capabilities listed below.
The basic and obligatory add-in manifest tags include:
The add-in manifest mechanism also supports a long list of additional new functionality. Here is a complete list of the remaining XML tags that can be used in an add-in manifest file:
As you can see, there is a large amount of very useful new functionality buried in here! For full details, especially on localisation, external command accessibility and the IExternalCommandAvailability interface, please refer to the What's New section in the Revit API documentation.
One detail that may require some attention is the encoding of the add-in manifest file. Note that the xml tag also specifies the encoding, for example utf-8, utf-16, and others. You need to ensure that the file really is stored in a format matching that attribute.
A common problem during beta testing was to define the encoding="utf-16" in the xml tag, but actually save the manifest file as ASCII. As said, the file encoding needs to correspond to the defined encoding, so one would either have to change the encoding to "ASCII" or save the add-in file as UTF-16.
The simplest possible editor to use is probably Notepad, where you can use File > Save As... > Encoding > ANSI or Unicode.
In Visual Studio 2008, you can use File > Save As... > Drop down list button > Save with Encoding... > Yes > Encoding: > Choose the encoding > Line endings: Current Setting > OK.
Here is an overview of some of the possible encoding settings:
As you saw in the example add-in manifest presented above, the basic required information is completely analogous to the entries used in Revit.ini, except for the new client id.
As described in the overview of the manifest tags, it is a GUID which represents the id of this particular application. We discussed GUIDs in the context of the element identifiers generated for the DWF and IFC export.
You can query an application's client id programmatically through the API property UIApplication.ActiveAddInId.
The client id must be unique, and every single external command requires its own id. You cannot reuse the same client id for several commands, even if they are defined and implemented by the same application.
There are several different ways to generate a unique GUID for any purpose. One is provided with Visual Studio, guidgen.exe:
On my system, this utility is located in the folder C:\Program Files\Microsoft Visual Studio 9.0\Common7\Tools.
A new GUID can also be generated by the .NET framework API call System.Guid.NewGuid(), which I make use of in the utility presented below.
I want to present a little tool that I developed to automatically populate the client id tag in the new add-in manifest file.
As we discussed above, the new command registration mechanism requires every Revit plug-in to define its own unique client id in the add-in manifest file. While porting the Revit Introduction Labs and implementing add-in manifest files for all its commands, I got tired of manually generating GUIDs with gudgen.exe and editing them into the manifest files. I implemented a little tool that enabled me to write the manifest files without client id entries, and then let the tool populate them automatically afterwards. That saved me from manually running and copy and pasting dozens of client ids.
So, in case anybody is tired of manually generating GUIDs for Revit commands, I proudly present guidize, a Revit Add-In Manifest File Client Id GUID Generator.
It reads a Revit add-in manifest file, searches for all the ClientId tags, and populates them with newly generated GUIDs. By default it only populates empty ones, so that existing GUIDs are not overwritten. However, with the -o switch, you can also overwrite existing ones. The option -b creates a backup file, and the -v verbose mode prints out some info on what the tool is doing:
C:\a\j\adn\case\bsd\1256939\ >guidize -? guidize 1.0 -- populate Revit add-in manifest file ClientId tags Copyright (C) 2010 by Jeremy Tammik, Autodesk Inc. All rights reserved. usage: guidize [options] manifest_file -? or -h help -b backup previous version of the manifest file -o overwrite existing ClientId entries -v verbose
After manually creating and editing dozens of GUIDs and with the prospect of requiring many more, I found this little tool to be an extremely comfortable addition to my kit.
Here is the complete source code and Visual Studio solution file, and also the ready-built executable for non-programmers.