Getting Started with Revit Macros
Introduction
Let's face it, sometimes working in Autodesk® Revit® can be a chore. There are some tasks that are just plain boring, or repetitive, or both. Renaming sheets, renumbering rooms, changing family names are all necessary tasks, but they don't exactly make for exciting work, especially if you have to do it more than once.
Fortunately, Revit provides tools for automating these kinds of repetitive tasks. By writing macros, you can custom tailor Revit to the specifics of how you work. You can fine-tune your tools to do your work faster and more accurately.
What is a Macro?
A macro is a series of user-created commands and functions that are written using the Revit application programming interface (API) and created in SharpDevelop, an open-source integrated development environment (IDE) integrated into Revit. Macros are stored inside Revit project files and are run directly from Revit. Unlike macros in other applications, Revit macros cannot be recorded. You must write out all the code for your macros.
Choosing a Language
One of the great things about writing macros in Revit is that you can choose from four different languages to write your code. Since the Revit API is built on the Microsoft .Net framework 4.0, you can write macros in either the C#, Visual Basic .Net, Python, or Ruby programming languages. All these languages compile into the same intermediate language so you have full access to the Revit API regardless of the language you choose. You can build the exact same macro in terms of functionality using any of the supported languages. Choosing a language is largely a matter of personal preference and learning style.
The examples in this article are written using VB.Net, which is a great language for beginning programmers. It evolved out of Microsoft Basic and retains Basic's friendliness toward new programmers. VB.Net code is more forgiving that other languages and is easier to read and understand.
One additional benefit to learning to write macros in Revit is that you can put these new programming skills to use on other aspects of your job. Once you have an understanding of the language, you can write code for other applications or create websites or stand-alone applications. The benefits of learning to write code are vast and will pay you many dividends throughout your career.
The Revit 2014 SDK
To get started, you should first install the Revit 2014 SDK. The SDK (software development kit) contains help files and sample code that will assist you as you learn to program macros. The Revit 2014 SDK can be installed from the main page of the Revit installer or it can be downloaded from the Autodesk Developer Network website: http://usa.autodesk.com/adsk/servlet/index?id=2484975&siteID=123112.
The SDK will install on your hard drive and create the following folders and files. Take some time to review the files. The macro samples in particular are useful when you start creating your own macros.
Figure 1: The SDK folder
Your First Macro!
Ready to create your first macro? As you'll see, the process is very straightforward. Follow these steps and you'll be on your way to macro mastery.
1. Open the Macro Manager
In Revit 2014, create a new project file. Once you have created the file, open the Macro Manager by selecting the Manage ribbon and clicking the Macro Manager icon.
Figure 2: The Manage ribbon
Macros can reside either in the active project file or within the application. Macros saved within the project file can be used by any user who opens that file. Macros saved in the application are saved to the user's Revit configuration. These macros can be used on any model file, but only by the user who created the macro.
Figure 3: Macro Manager
2. Create a New Module
To create a macro, you must first create a new module. A module is simply a collection of macros. Each macro within the module must have a unique name and all the macros within the module must compile without errors.
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.” Choose VB.Net as the module's language then click OK to create the module.
Once Revit has created the module, SharpDevelop will launch in the background. SharpDevelop is the integrated development environment that's built into Revit for programming macros.
3. Create a New Macro
Now that we have a module, we'll create a macro to go in the module. Make Revit the active application and click the Macro button in the "Create" section of the Macro Manager dialog. In the Create a New Macro dialog, title your macro ""MyFirstMacro" and set the language to VB.Net. Click OK to create the macro.
Figure 4: Create macro
4. Write Your Macro
Back in the Macro Manager dialog, select "MyFirstMacro" from the list and click the "Edit" button. This will bring you to SharpDevelop. In the SharpDevelop code window, you'll see standard code that is automatically created. Scroll to the bottom of the screen and you will see the starting code for "MyFirstMacro."
Figure 5: Startup code
Your first macro is going to simply pop-up a message box in Revit. It only takes one line of code. Between "Public Sub MyFirstMacro()" and "End Sub", type the following:
TaskDialog.Show("My First Macro", "This is my first macro!")
5. Build Your Macro
Once you've typed the code, you're ready to build the macro. All macros must be built or compiled before Revit can run them. In the SharpDevelop pull-down menus, select “Build” then “Build Solution.”
Figure 6: Build Solution
Any errors in your code or warnings will be highlighted in the Error and Warnings window located at the bottom of the SharpDev interface. If you don't see the Errors window, click the “View” pull-down then select “Errors” from the list.
Figure 7: Errors window
If you have an error, double check your code and make sure your spelling and syntax are correct. The code window will list errors by their line number so they're generally easy to pinpoint.
6. Run the Macro
Revit will only run macros that have compiled without any errors. 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 for "MyFirstModule."
Figure 8: The Macro Manager dialog
Select "MyFirstMacro" then click the Run button. This will execute your macro. You should see the following on your screen:
Figure 9: My First Macro
You did it! You wrote and compiled your first macro. To take this further, you can modify the code to report something more useful. If you want the code to report the current file's filename, change the code to the following:
TaskDialog.Show("My First Macro", "The current filename is _" & Me.Document.Title)
The "Me.Document" object contains data pertaining to the current model file. For a variation, change "Me.Document.Title" to "Me.Document.ActiveView.ToString" to see the current project file's active view.
More Macros
Our first macro was useful for illustrating the process for creating a macro, but let's take what we just learned and put it to use on a macro that actually does something useful. Here's the scenario for the next macro: You're adding a new sheet into a sequence of sheets and you need to do some renumbering. You could just do this manually, but it's pretty tedious and you might miss a sheet in the process. Instead of doing it manually, let's write a macro that gets the current sheet's number and increments it by one automatically.
One of the first things we need to do when writing this macro is import the Microsoft.VisualBasic namespace. This will allow us to use certain Visual Basic functions, such as isNumeric. Since sheet numbers can contain letters, we need to test the last three digits of the sheet number to make sure it contains only numbers.
Figure 10: Imports statement
Any time we make a change to the model via code, we need to create a transaction. A transaction creates a lock on the model so no other changes can occur while your change is taking place. The transaction code is very straightforward. It must wrap around the code that is making the change to the model. If you try to run your macro without the transaction code, you'll get an error. Here's what the transaction code looks like:
Figure 11: Transaction code
Note that any line beginning with an apostrophe is a comment line. These types of lines are not compiled by SharpDevelop. Comment lines are used to describe the macro and to serve as a reminder for what the code does.
The flow of the sheet renumbering macro goes like this: The code starts by determining if the current view is a sheet. If it is, the code gets the last three digits of the sheet number. It checks if the last three numbers are really numbers. If they are, the code creates a new variable that is the last three numbers plus one. The code then creates a transaction and updates the current sheet's sheet number. As a last step, the macro alerts the user that the sheet number has been updated.
To test this yourself, create a new macro and type the following code:
Figure 12: Increment sheet code
Some variations of this macro would be to automatically renumber all the sheets in the project file instead of just the active sheet. Another option would be to renumber a specific, user-defined series of sheets, such as only the A2 or M5 sheets.
Another useful macro is one that converts model lines to walls. This macro shows you how to prompt the user for information and how to create Revit objects. The macro also uses element filtering, which is how the API collects objects of a certain type. Here's the code:
Figure 13: Walls from lines
The code starts by prompting the user to select a level object. The selected level will be the level onto which the new walls are created. The Me.Selection.PickObject command prompts the user and puts the selected level object in the curLevel variable. The code then creates a collection of all line elements in the project using the FilteredElementCollector. You can use FilteredElementCollectors to create selections of any object type in Revit. Once the lines are collected, the code loops through each line and checks if it is a model line. If it is, the code creates a transaction and uses the current line's geometry to create a new wall. Once the wall is created, the code commits the changes then moves on to the next line.
To expand this macro, you could have the code create different wall types for different line types. You could also program it to automatically create the walls on a specific layer rather than prompting the user for the level. A third variation could use a linked AutoCAD® drawing rather than model lines.
Going Further
So what other tasks can you automate with Revit? Pretty much anything you can think of! Good candidates for macro automation are tasks that are fairly standardized or require lots of data input. Some examples could include:
- Update all window family instances with manufacturing data from a spreadsheet.
- Check that all the doors in fire-rated walls are actually fire-rated doors.
- Insert components based on coordinate data in a spreadsheet.
- Rename all custom families with a specific prefix for your company before sharing the model.
- Automatically place specific view types on a sheet.
That's just a short list of tasks that could be automated. What tasks do you do on a regular basis that you would like to see automated? Could you write a macro that would do most, if not all, of the tedious work?
Conclusion
Learning to write macros in Revit can drastically improve your efficiency with the software. A well-written macro can complete a once tedious task with the click of a button. As your programming skills grow, so will your ability to do the seemingly impossible. Programming macros takes time and patience, but it's a rewarding endeavor. Don't be intimidated by the code. Just work systematically and take small steps and you'll be well on your way to macro mastery.
Additional Resources
In addition to the information provided in the Revit 2014 SDK, you can find many online resources for learning the Revit API. Here is a list of some websites and resources I've found to be helpful:
Blogs
Boost Your Bim – http://boostyourbim.wordpress.com/
The Building Coder – http://thebuildingcoder.typepad.com/
Spiderinnet – http://spiderinnet.typepad.com/blog/
The Proving Ground – http://wiki.theprovingground.org/revit-api
Online Forums
AUGI – http://forums.augi.com/forumdisplay.php?218-Revit-API
Online Courses
Learn to Program the Revit API – https://www.udemy.com/revitapi/
Books
Autodesk Revit 2013 Customization with .Net How-to by Don Rudder
Michael Kilkelly AIA is a principal at Space Command (www.spacecmd.com), an architecture and consulting firm in Middletown, Connecticut. Prior to founding Space Command in 2012, Michael was an associate at Gehry Partners in Los Angeles. Michael received his B.Arch from Norwich University in 1995 and his SMArchS from MIT in 1999. Michael writes about architecture and technology on his blog at www.archsmarter.com. You can contact Michael at michael@spacecmd.com.
