The Building Coder

Managing SDK Samples

As mentioned in the previous post, the Revit SDK samples provide the biggest knowledge base on how to solve any specific programming task in Revit. The API documentation RevitAPI.chm lists the available classes and their properties and methods, and the API diagram in 'Revit API Diagram.dwf' shows their class hierarchy, but there is no information there about how they work together to provide specific functionality. The getting started document 'Getting Started Revit API 2009.doc' does provide some background information about the Revit API. A Revit API user manual explaining in more depth how to solve specific tasks is available from ADN. Since this document has not yet been completed and added to the standard SDK documentation, I am appending a copy of it here as a Word doc file for 2009 and here in PDF format for 2008.

And anyway, as every programmer knows, the only completely trustworthy source of information on any API is source code. So let's return to the samples, which provide exactly that.

To examine any sample in depth, we need to compile and load it. Compiling it involves loading the source code into the development environment and creating the executable binary code, the .NET class assembly. Loading it incurs making certain changes to the Revit.ini file, which is located in the same directory as Revit.exe. Both of these steps are well documented in 'Getting Started Revit API 2009.doc', and also explained and demonstrated in the Revit API DevTV presentation.

However, with over one hundred samples to explore, it would be a rather onerous task to perform these steps manually and individually for each sample, one at a time. Actually, it is even impossible to add all the samples to the Revit Tools > External Tools menu, because it cannot host more than about fifty entries at once.

Luckily, additional tools are included in the Revit SDK which help us address each of these two steps easily for all samples in one fell swoop: a Visual Studio solution file SDKSamples2009.sln is provided which allows us to compile all samples in one go. In addition, it provides a good base for debugging and searching the entire source code. Secondly, one of the samples provided, RvtSamples, is an external application which creates a hierarchical menu substructure within the Revit menu enabling us to load any one of the other samples. As an external application, it also needs to be added to the Revit.ini file to inform Revit to load it, but requires only a couple of lines instead of hundreds.

Finally, one useful resource providing an overview over all Revit SDK samples is the read-me file SamplesReadMe.htm, which was added in the Revit 2009 release. Whereas each individual sample has its own read-me file with detailed information and instructions on the sample, the global read-me file provides an overview and classification in several different ways: by skill level, release version, and category, such as database access, new object creation, geometry. This can be used to decide where to start looking for the material of most interest to you.

The Revit SDK Contents

The Revit SDK or Software Developer Kit is included in every Revit product installation CD. You can search the installation for a file named *sdk*.zip. In Revit 2009, it is named 'Revit 2009 SDK.zip' and located in a subdirectory 'Utilities\Common\Software Development Kit'. It can also be downloaded from the public Revit developer center which can be reached via www.autodesk.com > Communities > Developers > Products & Technologies > Revit Architecture and Revit Structure, or from the members-only ADN web site .

The contents of the Revit SDK are basically for documentation purposes only. All that is really needed to allow a Revit plug-in to run is the Revit API .NET assembly RevitAPI.dll, which is always present in every Revit installation and located in the Program subfolder, the same place as Revit.exe itself. Additionally, you need a development environment to compile your plug-in. The standard development environment we normally use is Microsoft Visual Studio. You can also use the free Visual Studio express version with reduced functionality, or any other .NET development environment. Alternatively, in Revit 2009, you can use the Visual Studio Tools for Application or VSTA environment which is included with the Revit product instead of compiling an external .NET plug-in assembly.

Let us look at the contents of the Revit SDK in more detail. Here are the documents present in the top level directory

• Read Me First.doc
• Getting Started Revit API 2009.doc
• Add-On Applications and Non-Power Users.doc
• Revit API Diagram.dwf
• Revit SDK License.rtf
• Revit VSTA User Manual.pdf
• RevitAPI.chm

'Read Me First.doc' provides a brief overview over the SDK contents and is the first place to start exploring. The next step is 'Getting Started Revit API 2009.doc', which explains the basic paradigms and architecture, how to create a Revit plug-in, and many further details. A graphical overview of the API class hierarchy is provided by 'Revit API Diagram.dwf'. The license is provided in a separate file, and a detailed user manual for VSTA, the Visual Studio Tools for Applications, which can be used to create macros inside of Revit instead of loading them as external plug-ins separately compiled in an external development environment.

The main help file is RevitAPI.chm, which lists all the classes provided in the API and their properties and methods. It does not do much to explain how these classes work together to solve specific programming tasks. For that, the best source of information is the collection of samples, which we will discuss in detail later.

There are two more documents to mention in this context, even though they are not present in the standard SDK release:

• Guide to placing Family Instances with the API.doc
• Revit_2008_api_user_manual.pdf

The guide to placing family instances is a recent addition to the Revit SDK update. Unfortunately, it did not make it into the Revit 2009 web update 1 in June 2008, so it will be added to the next version of the SDK. Currently, it is available from the ADN web site in the Revit knowledgebase or in the updated version of the Revit SDK web update 1 which was posted to ADN after the public release of the Revit product web update 1. For non-ADN members, I have also added a copy of it right here for 2009 and here for 2008.

The Revit API user manual is a work in progress and is also planned to be included in the standard SDK at some future point in time. Currently, the draft version is available from the ADN web site Revit 2008 Samples and Documents page. Again, here is a copy of it for non-ADN members.

In addition to the documents listed above, the SDK root folder also includes the following subdirectories:

• API Changes
• Add-in Manager
• Revit Structure
• VSTA Samples
• Samples

API Changes lists the changes between the current and the previous version of the API and is useful for migrating existing applications. The changes are documented in an xml file Added.xml and displayed through an XSLT generated view. XSLT stands for XSL Transformation or eXtensible Stylesheet Language Transformation. An XSL style sheet transforms the XML data into a specific view in the browser.

The Add-in Manager is a utility application for loading and managing plug-ins and is accompanied by its own documentation.

A set of additional documentation is provided specifically for Revit Structure in an own folder. Some VSTA samples are provided.

Finally, we have the largest component of the SDK by far, the SDK samples. The SDK samples provide over a hundred real live examples of how the API classes work together to solve specific programming tasks, ranging from the very simple to pretty complex.

Getting Started with the Revit API

The Autodesk Developer Center includes a good overview over the basic resources available for getting started with the Revit API, or Application Programming Interface.

You will also find this page by searching for the keywords "revit devtv". The DevTV Introduction to Revit Programming is a self-paced video tutorial demonstrating how to get started developing with Revit. This page also points to the public Revit API discussion group and the possibility to join ADN, as well as providing links for downloading the SDK or Software Developers Kit, which is also included in every Revit product installation.

Happily, from Revit 2009 onwards, absolutely everything you need to get started with the Revit API is included with the basic Revit product. If you want to write a professional application, you will additionally need a .NET development environment. However, for exploring the API and creating macros, the built-in VSTA or Visual Studio Tools for Applications editor can be used.

The DevTV recording is based on Revit 2008. The principles remain the same in Revit 2009, except that element access has been tremendously speeded up by the implementation of filtered access.

We made a recording of the Revit 2009 API webcast that we held in May 2008. It is available from the public Developer Center course schedule (look for Revit API and the Download link) as well as from the ADN web page. It covers more or less the same material as the DevTV recording, and additionally discusses the filtering features added in the 2009 API. The recording material also includes the presentation itself and the source code of the individual sample commands or labs.

Introduction to DevTech

I'm very pleased to be part of a great team at Autodesk: DevTech, the Developer Technical Services team. Our focus is on providing high quality services to members of ADN, the Autodesk Developer Network. Aside from providing technical support for programming-related questions, we also write technical solutions, which we call DevNotes, present at technical conferences, provide API training and mentoring, i.e. short-term consulting, and liaise regularly with our engineering teams.

The team is spread around the world, so we have groups in the Americas, China, Europe, India, and Japan, split into 'virtual' workgroups for the architectural, mechanical, basic platform and media & entertainment products. I am a member of the architectural or AEC workgroup.

Everyone in the team is a programming expert focusing on multiple products and wearing many hats. We believe very strongly that providing hands-on support is a great way to develop strong technical skills that are of use in other parts of our job, so everyone in the team is involved in answering questions from our ADN members.

You'll hopefully get to know other members of the AEC DevTech team as time goes on, when some of the tips and techniques they use (and discover) as part of their respective jobs appear to be of general interest.

Welcome

Welcome to The Building Coder, a blog dedicated to programmers working with the Revit API. My name is Jeremy Tammik and I work in the DevTech team, Autodesk's Developer Technical Services. We provide technical services to members of ADN, the Autodesk Developer Network. This includes programming support, consulting, training and evangelism. I'll be using this blog to share technical information about the use of the Revit API, i.e. its Application Programming Interface. I am part of the AEC workgroup in DevTech, and many of these posts will be contributed by my colleagues.

A little about myself: I studied mathematics and physics at Marburg University in Germany, then worked as a programmer using C on early GUI and multitasking projects, before the existence of Windows. I joined Autodesk in 1988 and provided developer support, consulting, and evangelism for AutoCAD in Europe before the inception of ADN, working my way through the Lisp, C and C++ APIs AutoLISP, ADS, and ObjectARX as they came along. At that point, I left Autodesk and worked on a large HVAC application, initially based on AutoCAD and later AutoCAD Architecture, finally acquired by Autodesk and now integrated into AutoCAD MEP. I rejoined Autodesk in 2005 and learned both the mechanical products such as Inventor and AutoCAD Mechanical and the new architectural ones such as Revit in developer support as well as consulting capacities.

If you have suggestions for interesting topics to cover in this blog, please feel free to contact me at jeremy.tammik@autodesk.com. Neither my blog nor my email account should be considered channels for receiving support, however, and I make no guarantees that we will be able to address topics that are proposed. But please do feel free to drop me a line.