Getting started

So you’re facing some issues while trying to get started with C# for Revit . . . trust me, I’ve experienced the same frustrations too! I hope this post will help ease the frustration for those who have absolutely ZERO experience with C#. Lets get to it!

1. Download Visual Studio

For this tutorial, I’ll be using Visual Studio Community 2019. VS Community is a powerful IDE for developers and more importantly, its free! If you are using 2015 or 2017, don’t worry! It shouldn’t make much of a difference.

2. Configure Visual Studio installation

Depending on the Revit version you intend to develop plugins for, you will have to install respective supported .NET versions. Compiled from a number of information sources (Please feel free to correct me if I am wrong) :

• Revit 2014 : NET 4.0
• Revit 2015 / 2016 / 2017 : NET 4.5
• Revit 2018 : NET 4.5.2
• Revit 2019 : NET 4.7

For this tutorial, I will be using Revit 2019, hence, NET Framework 4.7 is required.

3. Create a new project

Create and configure your new project.

*Note: Use .NET Framework instead of .NET Standard

Name your project as desired, or use “MyFirstRevitPlugin” (as shown) if you wish to follow along the guide. Select .NET Framework 4.7 since we will be using Revit 2019. Then, Create the project!

Run Visual Studio Community 2019 → File → New → Project → Class Library (.NET Framework)

4. Add References

Welcome to the development environment, start by adding reference to Revit’s Application Programming Interface (API). The exposed API allows us, as developers, to access the features or data of Revit.

Add both “RevitAPI” and “RevitAPIUI” under Revit’s Program Files. The default installation directory is
“C:\Program Files\Autodesk\Revit 2019“.

Set Copy Local under Properties to False to disable copying of Revit API files to our application’s output folder (Proper housekeeping).

Right click “References“ under Solution Explorer → Add Reference → Browse → “C:\Program Files\Autodesk\Revit 2019 “ → Add “RevitAPI” & “RevitAPIUI” → Select “RevitAPI“ & “RevitAPIUI“ → Properties → Copy Local → False

5. Add Namespaces

When working on a C# project, the using keyword is a directive that tells the C# compiler to access the contents of the namespace or specified library assembly (.dll) from the code in this source file. Let’s add the following namespaces to our project:

using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;

The Public keyword suggests that the class should be accessible from other classes in this plug-in, as well in other that adds reference to the plug-in library assembly (.dll) containing this class. Class1 is the name of your class, you can modify it as desired, but lets not worry about that for now.

6. Implement IExternalCommand

Indicating “<Class Name>: IExternalCommand” after the class name tells ours class to implement an interface called IExternalCommand. Interfaces are used with classes in C# to define a “contract”, which is an agreement on what the class will provide to an application. Where, it is up us to define the properties and methods of the class. In simple words, Revit can recognize a class, that implements the IExternalCommand interface, as a command in Revit’s user interface.

Hover over IExternal Command → Implement interface

7. Execute Method

You’d notice that the Execute() method appears after implementing the interface. Which expects a Result to be returned, an enumeration containing Succeeded, Failed or Cancelled that determines if our action implemented in Revit have been successful, failed or cancelled respectively. At this point, assuming all went well with our code, we pass back Result.Succeeded.

The Transaction Attribute  declares the way that the transaction should work, which could be either Manual or Automatic. We wont worry about that for now, since I set it to Manual most of the time.

Add in the two lines of code demonstrated in the video below.

8. The classic “Hello World!”

We shall complete the plugin with a classic “Hello World!” demonstration using a TaskDialog popup.

Your final code should look similar or identical to this:

using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
 
namespace MyFirstRevitPlugin
{
    [TransactionAttribute(TransactionMode.Manual)]
    public class Class1 : IExternalCommand
    {
        public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
        {
            TaskDialog.Show("Title", "Hello World!");
 
            return Result.Succeeded;
        }
    }
}

9. Build your solution file!

Next, we will be doing some setup to enable Revit read our plugin. Build your Solution file, you should see the directory of your assembly file (.dll) in the Output window below. We will be using this directory later on.

Build → Build Solution

10. Create “.Addin” file

The Manifest or .Addin file consists of parameters required to setup the Revit plugin that we built.

Right click “MyFirstRevitPlugin” file → Add → New item → Application Manifest File → File name “MyFirstRevitPlugin.addin”

11. Configure “.Addin” file & Re-build

You should see a bunch of confusing words, but don’t worry. Simply wipe them out, and replace them with the xml code below.

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Command">
    <Name>MyFirstRevitPlugin</Name>
    <FullClassName>MyFirstRevitPlugin.Class1</FullClassName>
    <Text> Hello World Text </Text>
    <Description> Hello World Description</Description>
    <VisibilityMode>AlwaysVisible</VisibilityMode>
    <Assembly>
      C:\Users\junha\source\repos\MyFirstRevitPlugin\MyFirstRevitPlugin\bin\Debug\MyFirstRevitPlugin.dll
    </Assembly>
    <AddInId>502fe383-2648-4e98-adf8-5e6047f9dc34</AddInId>
    <VendorId>AECTechy</VendorId>
    <VendorDescription>AECTechy</VendorDescription>
  </AddIn>
</RevitAddIns>

Replace the <Assembly> portion with your directory output from Step 9. This will allow Revit to read your application directly from that directory. Set “Copy to Output Directory” property of the .Addin file to “Copy if newer”. This option tells Visual Studio to construct the latest .Addin file to the output directory.

12. Copy addin file to Revit addin directory

Finally, we have to tell Revit to read the manifest (.Addin) file when we fire up Revit. Revit reads manifest files from two directories, if you installed Revit with default folder location, the directories should be:

All users
C:\Program Files\Autodesk\Revit 2019\AddIns
Individual user
C:\Users\<Your User Name>\AppData\Roaming\Autodesk\Revit\Addins\2019

I don’t wanna mess with other user’s settings, so I shall go with the second option. Go to your solution file’s debug folder, copy the manifest file to the Revit’s addin directory. That’s it, you’re ready to run your plugin!

Go to directory from Step 9 → Copy “MyFirstRevitPlugin.addin”
→ Paste into ” C:\Users\<Your User Name>\AppData\Roaming\Autodesk\Revit\Addins\2019″

13. Run your first addin!

Congrats! You’ve completed your first Revit addin!

Run Revit 2019 → Load the Addin → Add-ins tab→ External tools → Run “Hello World!”

I hope this guide was helpful for you to kickstart Revit plugin development! You’d probably be required to know how to author changes in the model through the Revit API to build something useful. This is done through Transactions, a simple guide can be found here. Do take a look at other posts on Revit API as well, you might get lucky there too!

If you have any suggestions or queries, I’d love to hear from you! Drop me an email at han@aectechy.com. Happy coding!