The Building Coder

Here are some suggestions on getting started with the Revit API:

• Before getting started
• Getting started material
• How to research to find a Revit API solution

First of all, before getting started, learn the Revit product from an end user point of view. Understand the optimal workflow and best practices. If you do not, the API will be hard to understand and not make much sense.

It is also useful to learn the basic of programming in general, and of the language you choose for addressing the Revit .NAT API specifically.

A good understanding of event-driven programming is very helpful, since the Revit API is entirely event driven.

Once you have that under the hood, determine an optimal end user workflow for the task that you intend to address with your add-in.

Any step that cannot be solved through the user interface can almost certainly not be automated either.

After that, it is time to start exploring the programming environment.

The Revit SDK or Software Development Kit includes API documentation and samples. You can download it from the Autodesk Revit Developer Center.

The most important piece of documentation is the Revit API help file RevitAPI.chm listing all classes, properties and methods. That information is also available online at www.revitapidocs.com.

Another very important piece of documentation is the Revit API Developers Guide included in the Revit product help.

The most effective way to get started learning and programming with the Revit API, including installation and use of the SDK, is to work through the step-by-step instructions provided by the DevTV and My First Revit Plugin video tutorials.

Next, you can dive in deeper still by working through the self-documenting ADN Revit API Training Labs. They consist of a series of hands-on lab exercises in both C# and VB.NET accompanied by detailed step-by-step training instruction documents.

If you are in a hurry and want to skip everything else, you can just check out the hello world walkthroughs in the developer guide.

The section on Add-In Integration presents detailed information on all you need to know about installing an add-in.

Here is an overview of the the rich collection of getting started material currently available:

• The Revit Developer Center
• Definitely your first port of call
• Work through the DevTV and My First Revit Plugin tutorials
• Download the Revit SDK including documentation and samples
• Install the Revit API help file RevitAPI.chm as a desktop shortcut and keep at hand at all times, or refer to the online Revit API documentation at www.revitapidocs.com
• Install the SDK samples solution SDKSamples.sln for global source code searches
• Install the RvtSamples external application to launch and debug the SDK samples
• For more in-depth training, work through the ADN Revit API Training Labs, also included in The Building Coder AdnRevitApiLabsXtra
• The Revit API Developer Guide
• Go to the Revit 2024 Online Help (2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015) > Revit Developers Guide
• The Revit SDK provides the basic Revit API help file documentation in RevitAPI.chm, also available online at www.revitapidocs.com
• The Revit API Developer Guide provides in-depth explanations
• The My First Revit Plug-in tutorial
• The archi+lab explanation how to create your own tab and buttons in Revit
• The DevTV Introduction to the Revit 2015 API
• The Visual Studio Revit add-in wizards
• Getting started
• Before getting started
• Revit API basic books and tutorials, starter kit and programming for beginners
• How to research to find a Revit API solution
• Intimate Revit database exploration with the Python Shell
• Getting started with the Revit API (late 2013)
• Getting started with the Revit 2013 API
• Getting started with the Revit 2012 API
• Preparing for a hands-on Revit API training
• Chinese Book on the Revit API
• Table of Contents

Reproducible Test Case

The best and clearest way to describe an API problem is normally by providing a non-confidential reproducible test case including a minimal sample macro embedded in a minimal project file to run it in and detailed step-by-step instructions specifying exactly what you are trying to achieve, the behaviour you observe, the difference between the two and how to reproduce the issue to analyse it in the debugger:

• A short exact description of what you are trying to achieve.
• The behaviour you observe versus what you expect, and why this is a problem.
• A complete yet minimal Revit sample model to run a test in.
• A complete yet minimal macro embedded in the sample model or Visual Studio solution with add-in manifest that can be compiled, loaded, run and debugged with a single click to analyse its behaviour live in the sample model.
• Detailed step-by-step instructions for reproducing the issue, e.g. which element to pick, what command to launch etc.

The purpose of this is both to enable us to reproduce and analyse the problem and to verify that it really has been resolved.

Another even more beneficial aspect for all involved is that creating a minimal reproducible case like this often leads you to discover for yourself what you were doing wrong, and the issue becomes moot.

P.S. Here is an additional clarification on the importance of a minimal reproducible case directly from the development team for a specific case: With the new info it does indeed look as if we need to explore this issue in more depth. However, I doubt it is on the managed side. Unfortunately, even if it does not look like it, we really need a sample to reproduce. Unless the problem occurs every time no matter what geometry is and what happens to the element the face was taken from, it is practically impossible for us to test it (I mean, in a reasonable time). We do not necessarily need your code – I can write the code myself – but we need a workflow to reproduce, and the workflow needs to be quite detailed; like – create this wall, of this type and this position and length, at this level; put this specific window there at this exact location; etc. Let me put it this way: if I receive a case from our QA team and the description does not specify each click exactly to get to the point of failure, no matter how trivial the commands are, I cannot take the case and return it to the reporter. Naturally I always try my best to deduce the actual scenario, but I can only do so much. So, please, if you can give us something very detailed and specific it will benefit both of us. Thank you.

P.P.S. If your add-in is too large or complex: I would love to dive in and try to help you debug this, but I am sorry to say I do not have the time. You will have to continue exploring it yourself. All I can suggest is to keep at it. One approach to debugging a problem like this is: (i) Simplify it down to something absolutely trivial and stupid that is guaranteed to work – dumb it down. (ii) Once that is working, add the required complications one by one until it either works completely or fails. Once you have determined the exact point of failure, you can narrow that down further and create a minimal reproducible case: With the minimal reproducible case in hand, I can either take a look myself of pass it on to the Revit development team for further analysis.

P.P.P.S. In order to simplify installation and debugging for the development team, the preferred method to submit your sample code snippet is to include it as a macro embedded in a minimal RVT document.

License

Copyright (c) 2008-2026 Jeremy Tammik. All material provided by The Building Coder is licensed under the MIT License.

Disclaimer

Please note I provide no guarantee whatsoever that anything published on this blog is useful or even legal. Some of the projects discussed here make use of experimental or risky workarounds not covered by the officially supported usage recommended by Autodesk. They are by no means production-level solutions and should not be used as is for production use. If you make any use of anything here, you are doing so at your own risk.

All Posts

Complete chronological listing of all 2,080+ blog posts: