FAQ: Revit Macros

This section answers frequently asked questions about Revit macros.

Question	Answer
I was expecting to see my newly created macro listed in the Macro Manager's categorized list, but it is not there. Why?	You must successfully build the macro project in the Revit macro IDE (use the Build menu) before your new macros will appear in the Macro Manager.
Do I need to add RevitAPI.dll and RevitAPIUI.dll as references when writing a new macro?	No. You do not need to reference RevitAPI.dll and RevitAPIUI files because this step was completed for you. A Revit macro project uses both as required references. Revit macros will fail if you delete these references in the IDE: See Restore RevitAPI.dll and RevitAPIUI.dll.
Do I need to edit my Revit.ini files?	No. Revit macros are automatically registered to appear in the macro manager without any further modification to the system.
In the Revit macro IDE, I deleted a macro by removing its method in the This.cs file or This.vb file. However, the deleted macro's name still appears when I open the Macro Manager's categorized list again. How do I clear the name from the list?	You must build your edited project successfully before Macro Manager recognizes the removal.
What are the differences between application-level and document-level macros?	Application-level macros can be run on all opened Revit projects within a single instance of the Revit application. Document-level macro projects are stored within an RVT file. They can be loaded from the current active document and run on that document.
How do I access the `Application` object or the `externalCommandData` equivalent?	All the Application-level macros are associated with the `UIApplication` object. In application-level macros, the `Application` keyword pointer in C# and VB.NET returns the API `Application` object. In document-level macros, the `Document` keyword returns the API Document object. To access the `UIApplication` object from a document-level macro, use `this.Application`.
What should I include in the startup and shutdown methods: `Module_Startup` and `Module_Shutdown`?	The `Module_Startup` method is called when a module loads and `Module_Shutdown` is called when a module unloads. For Application-level macro modules, `Module_Startup` is called when Revit starts and `Module_Shutdown` is called when Revit shuts down. For Document-level macro modules, `Module_Startup` is called when a Revit project opens and `Module_Shutdown` is called when the project document closes. `Module_Startup` and `Module_Shutdown` will also be called when the macro project is rebuilt. You can add your initializing code in the `Module_Startup` methods and do the cleanup work in `Module_Shutdown` methods. For example, you can register event handlers at start up and unregister them at shutdown (which is the recommended way).
How and why should I register and unregister my Revit event handler?	As noted previously, the recommended way to do this in the Revit IDE is to register event handlers in the `_Startup` method and unregister them in the `_Shutdown` method. Every macro will be loaded and unloaded dynamically. When you debug a macro, if the event handler is not properly unregistered, Revit may call a wrong method (maybe an invalid memory address). Although the Revit IDE may prevent Revit from crashing in this scenario, any event handlers that are not properly unregistered may cause performance issues during your current Revit session.
I have a dialog that does not seem to work correctly and is causing issues with Revit.	Modeless dialogs operating outside the scope of a running API callback may cause problems. It is recommended that you avoid such callbacks to prevent instability in Revit.
I want to experiment with the Startup and Shutdown methods and an event handler. Can you show me an example?	The following sample code shows how to register an `OnDocumentNewed` event handler, which will automatically launch a message box when a new Revit project is created. Note: One of the macro samples provided on the Revit SDK may show an example of a document-level event handler's startup and shutdown. This FAQ shows Application-level event handler examples. Please note that all API events can be accessed by the Revit IDE in 2011. Events prior to 2011 were removed. The following examples show the new events.

C# Example, Application-level:

private void Module_Startup(object sender, EventArgs e)
{
   this.Application.DocumentOpened
      += new EventHandler<Autodesk.Revit.DB.Events.DocumentOpenedEventArgs>(Application_DocumentOpened);
}

private void Module_Shutdown(object sender, EventArgs e)
{
   this.Application.DocumentOpened
      -= new EventHandler<Autodesk.Revit.DB.Events.DocumentOpenedEventArgs>(Application_DocumentOpened); 
}

void Application_DocumentOpened(object sender, Autodesk.Revit.DB.Events.DocumentOpenedEventArgs e)
{ 
   System.Windows.Forms.MessageBox.Show("message here");
}

VB.NET example, Application-level:

Private
Sub Module_Startup(ByVal sender As Object, ByVal e As System.EventArgs)
Handles Me.StartupAddHandler Me.OnDocumentNewed,
AddressOf Me.ThisApplication_OnDocumentNewed
End SubPrivate Sub Module_Shutdown(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Shutdown 
RemoveHandler Me.OnDocumentNewed,
AddressOf Me.ThisApplication_OnDocumentNewed
End SubPrivate Sub ThisApplication_OnDocumentNewed(ByVal document As Autodesk.Revit.Document) 
System.Windows.Forms.MessageBox.Show("VB.NET
Application event OnDocumentNewed")
End Sub