Welcome to part three of our quick start guide on getting started with the Revit API. In part two of this series, I shared some insight on how beginners can leverage Dynamo as an alternative to writing code. In this post, I’ll walk you through the more conventional method of using the Revit API to create a text note in your Revit project by writing only a few lines of C# code.

Prerequisites

This tutorial is really designed for the beginner coder, so you don’t need to be a seasoned software engineer to understand what we are going to cover in this post. It would definitely help to understand some basic object-oriented programming concepts, but even if you feel this tutorial might go over your head try to follow along anyway and see if you can learn a thing or two about writing code to tap into the Revit API.

The Revit API and C#

Revit macros currently support several programming languages: C#, VB.NET, Ruby, and Python. For this post, I’ll demonstrate how to use C# to develop a Revit macro, but there’s no reason you couldn’t follow along in your preferred language. If you go that route, obviously watch your syntax because it will be vastly different from my code snippets. The Revit API classes should be the main focus for this exercise.

Revit Macros

When getting started with the Revit API, I typically advise coders to learn using Revit Macros before diving in and developing a full blown Revit add-in. Developing a Revit add-in requires additional configurations and manifest files as well as an .addin file that is copied to the Revit add-ins folder. That means you’ll need to completely close Revit every time you need to test your add-in as you’ll need to overwrite the .addin file to test the newly compiled version. There are some methods that will allow you to reload an add-in without closing Revit, but they do require some additional configuration.

In contrast, using Revit Macros enables the developer to create a Macro within their current project. This provides a more streamlined workflow for coders who just want to dive in without complex configurations. A developer would simply need to open a Revit project, create a module and Macro and they can code, debug, and test on the fly without ever having to close Revit – unless they crash Revit of course!

Creating Your First Module and Macro

Launch Revit and start a new project. Once the project is open, navigate to the Manage tab and click on Macro Manager.

An empty Macro Manager window should open to the Project tab (the tab will display the filename of the current Revit project. Since there aren’t any modules created yet, the only option you have here is to create a module.

Click on the module button to create a new module.

In the Create a New Module window, name the module, choose C# as the language, and click the OK button.

Once you’re returned to the Macro Manager window, you’ll notice that it is now populated with the module that you had just created. From here, you’ll want to select that module and click the Macro button in the Create group.

From here you’ll give the new module a name. For this example, I’m calling it “HelloWorld”.

Congratulations, you just created your first Revit macro! Although maybe it isn’t quite time to celebrate, as the macro doesn’t do anything yet. With that being said,let’s start coding!

Revit API in SharpDevelop

When you created your first macro, you may have noticed that an application called SharpDevelop opened. This is Revit’s out-of-the-box integrated development environment (IDE), which is a fancy term for the application that allows you to edit code, build, and debug.

Note: if you need to open SharpDevelop to edit your Revit macros in the future, keep in mind that you can launch it from the Macro Manager and simply by selecting a macro and clicking the Edit button.

You’ll see that there is about 40 lines of code that is automatically generated by the macro manager. This includes the typical using statements that will allow you work with the Revit API.

For reference, below is the code that is automatically generated by the Macro Manager when you created the macro:

[code language="csharp"]
/*
 * Created by SharpDevelop.
 * User: Jay Merlan
 * Date: 3/13/2019
 * Time: 11:41 AM
 * 
 * To change this template use Tools | Options | Coding | Edit Standard Headers.
 */
using System;
using Autodesk.Revit.UI;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI.Selection;
using System.Collections.Generic;
using System.Linq;

namespace TestModule
{
    [Autodesk.Revit.Attributes.Transaction(Autodesk.Revit.Attributes.TransactionMode.Manual)]
    [Autodesk.Revit.DB.Macros.AddInId("DA944114-26AD-48FC-A3E1-03E0DC5AB50A")]
    public partial class ThisDocument
    {
        private void Module_Startup(object sender, EventArgs e)
        {

        }

        private void Module_Shutdown(object sender, EventArgs e)
        {

        }

        #region Revit Macros generated code
        private void InternalStartup()
        {
            this.Startup += new System.EventHandler(Module_Startup);
            this.Shutdown += new System.EventHandler(Module_Shutdown);
        }
        #endregion
        public void HelloWorld()
        {
        }
    }
}[/code]

Next Week: Just Add Code

Stay tuned for the final installment of the beginners guide to the Revit API where I’ll walk you through the code used to generate “Hello world!” as a text note in your Revit project.