Use the Revit Platform API and C# to create a Hello World program using the directions provided. For information about how to create an add-in application using VB.NET, refer to Hello World for VB.NET.
The Hello World walkthrough covers the following topics:
- Create a new project.
- Add references.
- Change the class name.
- Write the code
- Debug the add-in.
All operations and code in this section were created using Visual Studio 2010.
Create a New Project
The first step in writing a C# program with Visual Studio is to choose a project type and create a new Class Library.
- From the …. menu, select
- In the frame, click .
- In the right-hand frame, click Figure 1: Add New Project below). This walkthrough assumes that the project location is: D:\Sample. (see
- In the HelloWorld as the project name. field, type
- Click .
Figure 1: Add New Project
- To add the RevitAPI reference:
Repeat the steps above for the RevitAPIUI.dll.
Add the following code to create the add-in:
Code Region 2-1: Getting Started
public class Class1 : IExternalCommand
public Autodesk.Revit.UI.Result Execute(ExternalCommandData revit,
ref string message, ElementSet elements)
TaskDialog.Show("Revit", "Hello World");
TipThe Visual Studio Intellisense feature can create a skeleton implementation of an interface for you, adding stubs for all the required methods. After you add ":IExternaCommand" after Class1 in the example above, you can select "Implement IExternalCommand" from the Intellisense menu to get the code:
Figure 2: Using Intellisense to Implement Interface
Every Revit add-in application must have an entry point class that implements the IExternalCommand interface, and you must implement the Execute() method. The Execute() method is the entry point for the add-in application similar to the Main() method in other programs. The add-in entry point class definition is contained in an assembly. For more details, refer to Add-in Integration.
Build the Program
After completing the code, you must build the file. From the menu, click . Output from the build appears in the Output window indicating that the project compiled without errors.
Create a .addin manifest file
The HelloWorld.dll file appears in the project output directory. If you want to invoke the application in Revit, create a manifest file to register it into Revit.
- To create a manifest file, create a new text file in Notepad.
- Add the following text:
Code Region 2-2: Creating a .addin manifest file for an external command
<?xml version="1.0" encoding="utf-8" standalone="no"?>
- Save the file as HelloWorld.addin and put it in the following location:
- For Windows XP - C:\Documents and Settings\All Users\Application Data\Autodesk\Revit\Addins\2012\
- For Vista/Windows 7 - C:\ProgramData\Autodesk\Revit\Addins\2012\
- If your application assembly dll is on a network share instead of your local hard drive, you must modify Revit.exe.config to allow .NET assemblies outside your local machine to be loaded. In the "runtime" node in Revit.exe.config, add the element <loadFromRemoteSources enabled="true"/> " as shown below.
<generatePublisherEvidence enabled="false" />
Refer to Add-in Integration for more details using manifest files.
Debug the Add-in
Running a program in Debug mode uses breakpoints to pause the program so that you can examine the state of variables and objects. If there is an error, you can check the variables as the program runs to deduce why the value is not what you might expect.
- In the window, right-click the project to display a menu.
- From the menu, click . The window appears.
- Click the tab.
- Under the C:\Program Files\Autodesk\Revit Structure 2012\Program\Revit.exe. section, click and browse to the Revit.exe file. By default, the file is located at the following path,
Figure 3: Set debug environment
- From the menu, select (or press ) to set a breakpoint on the following line.
TaskDialog.Show("Revit", "Hello World");
- Press to start the debug procedure.
- On the tab, appears in the menu-button.
Figure 4: HelloWorld External Tools command
- Click to execute the program, activating the breakpoint.
- Press to continue executing the program. The following system message appears.
Figure 5: TaskDialog message
Q: My add-in application will not compile.
A: If an error appears when you compile the sample code, the problem may be with the version of the RevitAPI used to compile the add-in. Delete the old RevitAPI reference and load a new one. For more details, refer to Add Reference.
Q: Why is there no Add-Ins tab or why isn't my add-in application displayed under External Tools?
A: In many cases, if an add-in application fails to load, Revit will display an error dialog on startup with information about the failure. For example, if the add-in DLL cannot be found in the location specified in the manifest file, a message similar to the following appears.
Figure 6: External Tools Error Message
Error messages will also be displayed if the class name specified in ECClassName is not found or does not inherit from IExternalCommand.
However, in some cases, an add-in application may fail to load without any message. Possible causes include:
- The add-in application is compiled with a different RevitAPI version
- The manifest file is not found
- There is a formatting error in the .addin manifest file
Q: Why does my add-in application not work?
A: Even though your add-in application is available under External Tools, it may not work. This is most often caused by an exception in the code.
Code Region 2-3: Exceptions in Execute()
A a = new A();//line x
public IExternalCommand.Result Execute ()
The following two exceptions clearly identify the problem:
- An error in line x
- An exception is thrown in the Execute() method.
Revit will display an error dialog with information about the uncaught exception when the command fails.
Figure 7: Unhandled exception in External Command
This is intended as an aid to debugging your command; commands deployed to users should use try..catch..finally in the example entry method to prevent the exception from being caught by Revit. Here's an example:
Code Region 2-4: Using try catch in execute:
public IExternalCommand.Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
ExternalCommandData cdata = commandData;
Autodesk.Revit.ApplicationServices.Application app = cdata.Application;
// Do some stuff
catch (Exception ex)
message = ex.Message;