Revit commands and the revit.ini file

My previous blog post on getting started with the Revit API showed you how to setup a template to start creating the .DLL files needed for revit external commands, but how do you actually get these into revit? Lets say, you have made a simple hello world command, one of which is in the API SDK for you to use as a reference. I mentioned, that the public IExternalCommand.Result Execute method is the start of your command, this is what gets called first, from here you can direct it to do what you would like it to do. For a simple example, import System.Windows.Forms, and add "MessageBox.Show("Hello World")" to your IExternalCommand.Result method, remember, we added try catch into the template, so put it into the try section. Now right click on your assembly, and click properties. Go to the "Build" section, and change the output path to the location you would like to store your .DLL files - I store mine on a network drive so that there only needs to be one copy of them for all users in our workplace, perhaps this isn't the best practice (I have to login to the server and kick others out of it if I want to update it), but it makes sense for my situation. Then go into the "Debug" section, and choose "Start external program:", and choose the Revit.exe on your system. This means that when we start Visual Studio's debugging mode, it will fire up Revit and provide some good debugging features. Now, you're set to start building your file. Go to "Build" at the top of your screen and go to Build *SolutionName* (this will be whatever you called your project). This builds the solution, ready for use. Now is where we get to the icky part, the Revit.Ini file. Autodesk, remembering the glory days of the 90's, have used a .ini text file to tell revit that we have some external commands that we would like to use. There is documentation on this in the Revit SDK, but here is what you need to do. :

1. Open your Revit.Ini file
2. Find [ExternalCommands] if there is one, if not, create that section.
3. Insert the reference to your .DLL external command file, it should look similar to as follows

[ExternalCommands] ECCount=1 ECName1=ImportedCategoriesToggle ECClassName1=ElementProperties.Command ECAssembly1=L:\Revit\bwtools\ElementProperties\ElementProperties.dll ECDescription1=ImportedCategoriesToggle There, you can see the [ExternalCommands] header, and then under that is the ECCount, which tells revit how many External Commands are present. This will need to be incremented each time you add another command. ECName1 states the name which will show up in revit, ECClassName1 points to the Namespace.Class of your DLL file. So say you called your project RevitCommandOne and then made a class called 'Command' (as many of the examples do - you can call it what you like, or even have more than one in each Namespace), it would be RevitCommandOne.Command ECAssembly1 points to the dll file you exported, remember how you chose where to store this in the Visual Studio 'Build' properties? ECDescription1 is just a description of your command, add what you like. Of course, the '1' on the end of each of these fields is just saying its the first one, change this to 2 for your second and so on. As you can see, the Revit.ini file is a bit of a weak point, it would be much better if it was an XML file or something, so that you could programmatically change it without fiddling with text streams and regular expressions, but thats the way it is, hopefully in 2010 this might be fixed.... Once you have inserted that section, save it, and start Revit (you must restart revit each time you change the revit.ini file), then your command should show up in the Tools > External Tools menu. Simply click to run it. If Hello World does not show up, then chances are you have made a mistake in your revit.ini file, double check it all, make sure the numbers are correct, you've incremented the ECCount etc.