How to Write Your First Revit Macro in 7 Easy Steps

Macros are one of the easiest ways to Automate Revit and get under the hood of
your software. Macros do not require any additional software other than Revit and
are a great way for beginners to learn programming.

So what exactly is a macro? A macro is a user-created command that is coded

using Revits API. Macros are run directly inside of Revit and are saved in the project
file. Other applications, like MS Office, provide the ability to record macros directly
from your actions on the screen. Unfortunately, Revit does not have this
functionality. You must code your Revit macros directly.

Your First Revit Macro

Ready to write your first macro? As youll see, the process is very easy. Follow the
steps below and youll be on your way to macro mastery.

1. Open the Macro Manager

Create a new project file. Click the Manage ribbon then click the Macro Manager
icon. This will open the Macro Manager dialog.

Macros can reside in a project file or within the Revit application. Macros saved in
the project file can be used by any user who opens that file. Macros saved in the
application are saved to the users Revit configuration. These macros can be used
on any model file but only by the user who created the macro.

Page 1 of 12
2. Create a New Module
Macros are organized in modules. When creating a macro in a new project file, you
must first create a module. A module is simply a collection of macros. A single
project file can contain several modules with each module having its own macros.
Module names cannot contain spaces or special characters.

To create a module, click the Project 1 tab then click the Module button in the
Create section. In the Create a New Module dialog box, title your module
MyFirstModule. You can write macros in C#, VB.Net, Python or Ruby. For this
exercise, choose VB.Net as the modules language. Click OK to create the module.

Page 2 of 12
Once Revit has created the module, SharpDevelop will launch. SharpDevelop is an
open-source development environment that is built into Revit for programming
macros.

3. Create a New Macro

Now that you have a module, you can create a macro inside the module. Click
the Macro button in the Create section of the Macro Manager dialog. In the
Create a New Macro dialog, title your first macro MyFirstMacro and set the
language to VB.NET. Click OK to create the macro.

4. Write the Macro

Switch over to SharpDevelop. Youll see the standard VB.NET code that is
automatically generated when you create a new module. Toward the bottom
youll see the starting code for MyFirstMacro.

Your first macro is simply going to popup a message box in Revit. It only takes one
line of code. After the public void MyFirstMacro(), type the following between the
brackets:

Page 3 of 12
5. Build the Macro
Once youve typed the code, youre ready to compile or build the macro. All
macros must be built before Revit can run them. In the SharpDevelop menu bar,
select Build then Build Solution.

SharpDevelop will compile your VB.NET code into the .Net intermediate code. Any
errors or warning will show up in the Errors and Warning window located at the
bottom of the SharpDevelop interface.

If you have an error, double-check your code. The code window will list errors by
line number so they are easy to pinpoint.

Page 4 of 12
6. Run the Macro
If your macro compiled correctly, go back to Revit and open the Macro Manager
dialog (Manage > Macro Manager). You should see MyFirstMacro in the list
below MyFirstModule.

Select MyFirstMacro from the list then click the Run button. This will execute your
macro. You should see the following on your screen:

You did it! You wrote your first Revit macro.

Page 5 of 12
7. Make Some Changes
To take this further, you can modify the code to report back something more useful.
Change your code to the following:

The Me.Application.ActiveUIDocument object represents the current model file.

The Document object contains data pertaining to the current file itself. To see the
active view in the current project file, change Document.PathName to
ActiveView.Name.

Note the underscore (_) character in the code above. This character represents a
line continuation symbol and SharpDevelop that the code continues in the line
below. Line continuation symbols are used when printing long lines of code to a
page. When you are typing the code, you can omit the _ and type the code on
a single line.

Next Steps
Congratulations! Youre on your way to Revit macro mastery!

While this tutorial is very basic, it illustrates the principles of writing Revit macros. For
a next step, I recommend downloading and installing the Revit 2017 Software
Development Kit or SDK. The SDK contains help files and sample code that will assist
you as you learn to program macros. The Revit 2017 SDK be installed from the main
page of the Revit installer or it can be downloaded from the Autodesk Developer
Network website using the following link: http://www.autodesk.com/developrevit

The SDK will install on your hard drive and create a bunch of subfolders and files.
Take some time to review the files. The macro samples are particularly useful as you
get started creating your own macros.

Page 6 of 12
Learning the Revit API
As you move beyond your first Revit macro, youll need to get familiar with the Revit
API. The help file is your roadmap to learning the API. You can find the help file in
the Revit 2017 SDK folder. Open the RevitAPI.chm file and click the Content tab.
The help file lists all of the namespaces in the Revit API.

A namespace is essentially a hierarchical container for the elements within the API.
A good analogy for namespaces is your computers folder structure. Each folder at
the same level of the directory structure must have a unique name. The folders can
contain similarly named files but the path to each file will be unique as the folder
names are unique.

Namespaces work the same way. There may be elements within the API that are
named the same. For example, many elements have a Geometry property but
namespaces provide a way to accurately identify which geometry youre
specifying. To reference the wall geometry property, you type
Autodesk.Revit.DB.Wall.Geometry.

To find more information about a specific element within the API, simply drill down
through the namespaces to find the element. For instance, if I want to learn more
about the properties of wall objects, I click Autodesk.Revit.DB Namespace > Wall
Class > Wall Properties. The hep file lists all the properties of wall elements.

Page 7 of 12
Reading the API help file is not easy. It takes some practice as it is not written in
plain English. Rather, it is a description of all the elements within the API. The help file
does contain code samples but it not a learning tool. Much like a road map will not
teach you to drive a car, the API help file will not teach you to code but it will help
you get where youre going.

Troubleshooting Macros
You will spend a lot of time troubleshooting and debugging your macros. One of
the great things about coding is that the feedback is immediate. You write some
code, compile it then run it. Your code will either work or it will not. Revit will tell you
immediately if it does not work and you will feel a sense of accomplishment when it
does work. SharpDevelop provides a number of tools to assist you while
troubleshooting your code.

Using Debug.Print and the Output Window

While writing code, it is often useful to have your macro report back information
while the macro is running. Writing code is an iterative process and you will need
feedback as you develop your macro. SharpDevelops output window is useful for
understanding whats going on inside your macro.

To output information to the output window, use the Debug.Print command. Before
you can use the command, however, youll need to add the Systems.Diagnostics
namespace to your macro. You do this by adding using System.Diagnostics to the
beginning of your macro code.

Stepping Through Your Code

When you compile your code and run it, Revit will run through the code
sequentially. While writing macros however, it is often useful to step through your

Page 8 of 12
code line by line so you can see exactly what is going on. You can step through
your code using the Step Into button in the Macro Manager dialog.

Press the F10 key to step through the next line of code. While you are walking
through the code, you can view the Output window to see any output from your
Debug.Print lines. You can also view the current values in your variables through the
Local Variables tab.

Using Break Points

In addition to stepping through your code, you can set specific points where you
want the code to stop running so you can check out the Output or Local Variables
windows. Clicking on the grey area to the left of the line number row will create a
break point. A break point is represented as a red dot. Any line containing a break
point will also be highlighted in red. When Revit encounters a break point when
running the code, it will stop executing the code. Pressing F10 will step through your
code or press F5 to continue running the remainder of the macro.

Page 9 of 12
Commenting Your Code
One of the most critical practices to follow when writing code is to add comments
as you are writing your code. These comments should serve as a reminder for what
the code does and why its structured in that particular way.

Each language has its own syntax for writing comments. Comments are identified in
VB.NET by an apostrophe at the beginning of the line. SharpDevelop highlights all
comments in green.

Comments can also be used to block code from running. Say you are testing some
alternate approaches to a specific part of the macro. You can comment out
parts of the code that you do not want to run. If you have three options for the
code, comment out two and run the macro with one of the options. Commenting
out can also be used to test very specific parts of your macro. If you are getting
errors from one section of the macro, comment out everything else, build the
macro and step through it. This focused approach will save you a lot of time while
troubleshooting.

Exceptions
Face it, your code is not going to be perfect. Even if your code compiles without an
error, it can still crash or throw an exception when you run it. This is simply the nature
of coding. If you get an error, use the methods listed above to systematically work
through your code to identify the problem. This can seem like finding a needle in a
haystack when you are first starting out but as you code more and more macros,
you will get better at identifying problems in your code.

Page 10 of 12
Another Macro
Our first macro was useful for illustrating the process for creating a macro but lets
take what we just learned and put it to use on a macro that is more useful.

The following code deletes unused views in the current model file. If a view is not on
a sheet, it is deleted. Note this macro does not work with dependent views.
To test out your new macro coding skills, create a new macro and type the
following code:

Page 11 of 12
After typing the code, go to Build > Build Solution to compile it. You may get an
error or two, thats normal. Use the steps outlined in the troubleshooting section
above and try to resolve the errors. Check for typos in your code thats what
usually gets me! Once the code builds successfully, switch over to Revit and run the
macro.

Conclusion
Learning to write macros and automate Revit will drastically improve your
efficiency. A well-written macro can do more in five minutes than a regular user
can accomplish in one hour. Learning to program takes time and patience. Start
small and work systematically. Youll be on your way to macro mastery in no time!

Additional Resources
Want to learn more about writing your own macros? Check out these resources for
more information.

Blogs
ArchSmarter http://archsmarter.com
The Building Coder - http://thebuildingcoder.typepad.com/
Boost Your BIM - http://boostyourbim.wordpress.com/

Online Forums
Augi - http://forums.augi.com/forumdisplay.php?218-Revit-API

Online Courses
Mastering Revit Macros http://archsmarter.com/go/mrm

Books
Autodesk Revit 2013 Customization with .Net How-to by Don Rudder

Page 12 of 12