Extending BIM Design Value Using the Revit Api
An application programming interface (API) allows users and developers to extend the capabilities of an existing application by writing a program or script that adds new functionality to the software. The Autodesk Revit API allows programmers to change elements in the Building Information Model (BIM) directly or to access the data to perform specialized tasks.
Power users and software developers are taking advantage of the Revit API to create their own custom tools. By using the Revit API, they are able to enhance Revit’s power to improve work- flows and create better building designs faster. This article will introduce readers to the Revit API and present some of the ways that developers and dabblers alike can use it to supercharge Revit.
A WORK IN PROGRESS
The Revit API is still relatively "young", especially compared to AutoCAD with its more than 25-year history of APIs and customizations. Autodesk officially introduced the Revit API in Revit 8, just over four years ago. Since then, it has steadily expanded and improved. While there are still significant limitations, the API has now reached a point where it is quite useful for solving a wide variety of problems. The key is to understand the strengths and weaknesses of the API and whether it presents a good fit for your particular need.
Some functions which are a good fit for the API today include:
• data extraction and import
• geometry extraction
• property manipulation
• building analysis
• basic design automation and configuration
• simple family creation and management
• automated export and printing
Some functions that still need refining today, but will no doubt be better supported in future releases include:
• interactive (pick and place) applications
• larger-scale design automation
• batch automation
PROGRAMMING: VSTA VERSUS VISUAL STUDIO
Autodesk offers two ways to learn how to program with Revit. Developers can choose between different programming environments: Microsoft Visual Studio or Microsoft Visual Studio Tools for Applications (VSTA).
For people already familiar with programming AutoCAD, the Visual Studio approach is similar to programming AutoCAD.NET or ObjectARX, in which commands are built separately, compiled, and then tested inside the CAD system.
Programming using VSTA is conceptually similar to Visual Ba- sic for Applications (VBA), where developers work inside of the CAD system and build projects to embed into a Revit document or to keep in a separate project file.
Figure 1: Manage Ribbon Tab - Macros Panel - VSTA Tools (Macro Manager & Macro Security)
The good news is that the debate about whether to use VSTA or Visual Studio is rarely about the "power" of a particular approach, which was often the case when working with AutoCAD. Weighing the benefits of VSTA or Visual Studio is more dependent on the specific project objectives—specifically, deployment issues and who will be doing the development. Both use the same languages (Visual Basic.NET or C#) and the API is almost identical. However, Visual Studio has approximately ten percent more capabilities in Revit than VSTA.
Figure 2: The Add-Ins Ribbon
In terms of cost, VSTA is free and included in the Revit install in Revit 2010 products). The free "Express" version of Visual Studio has enough capability – with a few limitations. Progressively more powerful versions come with higher price tags. The biggest benefit of Visual Studio is that it is easier to develop applications with secure source code. In VSTA, the source code tends to be visible to anyone interested. There are also different approaches to deployment of applications in the VSTA versus Visual Studio approaches. For the serious developer, Visual Studio also provides access to a next-generation user interface, database integration, and other tools.
Using VSTA, all "macros" are accessible on the "Manage" ribbon under "Macro Manager". Using Visual Studio, the developer defines "Commands" which are available on the "Add-Ins" ribbon under "External Commands." Visual Studio also allows programmers to define "Applications" to run when Revit starts up, as well as to further enhance the user interface, including making simple Ribbon Bar Panels. While VSTA is a good way to "dip a toe" into the Revit API, the more serious programmer will want to use Visual Studio. (See Figures 1 and 2)
LOOKING AT VISUAL BASIC CODE
The sample source code below (Figure 3) shows an example of what programming with the Revit API is like, including scanning the Revit project for certain elements (rooms), then interacting with the rooms. In this case, it shows how to read information, such as the perimeter, or write information, such as the Room Floor Finish. (See Figure 2)
CONFIGURING REVIT FOR ADD-INS
Do-it-yourself programmers who create Add-Ins that perform a useful function can modify the REVIT.INI file to tell Revit where to look for the new Add-In. An example is Avatech’s Door Mark Update add-in, which automates door mark updates when changes inevitably occur.
To add a simple command to Revit, users can add or update the [External Commands] section of their INI file (Figure 3).
Figure 3: Programming with Revit API Using Visual Basic
The "ECCount" setting (Figure 4) describes how many External Commands are in the INI file. Then programmers need to de- fine the following four lines (Figure 5) for each command (where <num> indicates the number of each command):
Figure 4: Updating the External Command Section of Revit’s INI File
External Applications are similar to External Commands, but instead of encapsulating a new Revit command (which runs on a document), the External Application works with the Revit application in general. It can be used for mundane purposes like setting up a customized user interface (with custom commands, menus, and toolbars)—or for more interesting purposes like keeping track of different events within Revit.
Figure 5: Explaining each line of information that you need to add.
Configuring Revit to work with External Applications is similar to External Commands, but in a different section within the Revit.INI file.
EACount, as seen in Figure 6, refers to the number of External Applications and each application must have a ClassName and an Assembly Path.
Figure 6: Configuring Revit to Work with External Applications
The Revit Software Development Kit (SDK) download, avail- able free from Autodesk, contains a tool called the "Revit Add-in Manager" that automates the process of loading Add-Ins to the Revit.INI file. Commercial developers create install programs that modify the Revit.INI file automatically, so this process is not usually necessary for commercial software. Finally, more advanced firms may keep a centralized copy of the REVIT.INI file that is deployed to each machine in an automated fashion.
LEARNING THE API
Anyone can download the free Revit SDK from (http://usa.autodesk.com/adsk/servlet/index?siteID=123112&id=2484975)
The SDK provides good documentation, beginning with the "Help" file. It also includes a "Getting Started Guide," as well as a more in-depth "Developer Guide." Autodesk has also posted a video training class on the SDK page titled "DevTV: Introduction to Revit Programming." Finally, there are discussion boards on both the AUGI and Autodesk sites specifically targeting Revit development topics.
The Revit API has now reached a stage of maturity where it can significantly improve how firms leverage Revit. As Building Information Modeling continues to enter the mainstream, the early adopters of the Revit API will have even greater advantages over their competitors. For those who have previously performed customizations in AutoCAD, perhaps now is the time to look at the Revit API.
