GettingStartedwiththeRevitAPI.doc

Autodesk Revit 2012 API – Getting Started

Table of Contents
Overview 2
What Can I Do With the Autodesk Revit API? 2
What You Will Need to Get Started 2
Understanding Autodesk Revit 2
Installation of the Autodesk Revit API 3
Development Requirements 3
Using the Autodesk Revit API 3
Autodesk Revit SDK and Online Help 3
Documentation Conventions 4
What can you do with the Autodesk Revit API? 4
Deployment Options 4
1. External commands 4
2. External applications 4
3. REX addins 5
Registration of add-ins 5
External Commands 7
The IExternalCommand Interface 7
Parameters 7
Return Value 7
Remarks 8
Using an Autodesk Revit API External Command 8
External Command Object Lifetime 8
External Applications 8
The IExternalApplication Interface 9
Parameters 9
Return Value 9
External Application Object Lifetime 9
Compatibility of API applications with 64-bit Revit 9
Debugging Your Application in MS Visual Studio 2010 9
The Revit Unit System 10
Storing and accessing Custom Data for Applications 11
Appendix 1 – Glossary of Autodesk Revit terms 12
Appendix 2 - FAQ 12
General: 12
Autodesk Revit Structure: 14
Overview
Autodesk Revit Architecture 2012, Autodesk Revit Structure 2012 and Autodesk Revit MEP 2012 offer an API designed to allow power users and external application developers to integrate their applications with Autodesk Revit. The APIs for each of these three products are very similar and will be jointly referred to as the Autodesk Revit 2012 API or Autodesk Revit API. It is strongly recommended that you become familiar with Autodesk Revit Architecture, Structure or MEP and its features before attempting to use the Autodesk Revit API. Training can be found through the Autodesk Developer Network (ADN).

What Can I Do With the Autodesk Revit API?
The following are general areas where the API is suitable:
· Creating add-ins to automate repetitive tasks in the Autodesk Revit user interface
· Enforcing project design standards by checking for errors automatically
· Extracting project data for analysis and to generate reports
· Importing external data to create new elements or parameter values
· Integrating other applications, including analysis applications, into Autodesk Revit products
· Creating Autodesk Revit project documentation automatically

What You Will Need to Get Started
· A working understanding of Autodesk Revit Architecture, Autodesk Revit Structure or Autodesk Revit MEP 2012
· An installation of an Autodesk Revit-based product, including the Software Development Kit
· MS Visual Studio 2010 or MS Visual Studio 2010 Express Edition, or a full installation of Microsoft Visual Studio. If you plan to start with VSTA, you do not need to install any of these.
· Some experience in a .NET based development language (Autodesk Revit API examples are provided in C# and Visual Basic.NET.)
· 2 days of free time

Understanding Autodesk Revit
All Autodesk Revit-based products are Parametric Building Information Modeling (BIM) tools. Such a tool can be looked at as a CAD program that is used to build a 3D model rather than a set of individual drawing files. Autodesk Revit modeling is accomplished with real-world elements like columns, walls, doors and windows. The user can create views of the model, including plans, sections and callouts. All these views are directly generated from the 3D physical model so changes made in one view will automatically propagate through all other views. This process virtually eliminates the need to update multiple drawings and details when a change is made in the model.

The Autodesk Revit API is designed to reflect the same user interaction paradigms as the program’s Graphical User Interface. Therefore, the first step to understanding the API is to learn how to use the program. If you are an Autodesk Revit novice, we suggest you first start by going through the Tutorials which you can access through the program’s Help menu. You may also find it helpful to take a Training class from your local Autodesk reseller. This will help you quickly get up to speed with the program
Autodesk Resources:
·
·
·
·
·
Select = Autodesk Revit Building
Then Select = Autodesk Revit API

External Resources:
·
·
·
Installation of the Autodesk Revit API
The Autodesk Revit API is automatically installed with the default installation of the Autodesk Revit based product.
The Autodesk Revit API Software Development Kit is installed from the Tools and Utilities section of the Autodesk Revit installation DVD.

Development Requirements

The Autodesk Revit API requires the Microsoft .NET Framework v3.5. To edit and debug your API applications, you need an interactive development environment such as Microsoft Visual Studio 2008 or one of the MS Visual Studio Express Editions for C# or Visual Basic.NET. When developing with the Autodesk Revit API, ensure that your project references two DLLs: RevitAPI.dll and RevitAPIUI.dll contained in the Autodesk Revit Program directory.
Some programming skills are required to effectively use the API. If you are a beginner in programming, we strongly advise you to learn Microsoft Visual Studio 2008 and one of the compatible languages like C# or Visual Basic.NET. There are many good books and classes to get you started.
Resources:
Online resources
· Free Visual Studio –
·
·
·

Books:
· Code Complete, Second Edition, by Steve McConnell
· Software Project Survival Guide, by Steve McConnell
Using the Autodesk Revit API
Autodesk Revit SDK and Online Help
Get the Autodesk Revit SDK from ADN or the installation DVD. The Autodesk Revit 2012 SDK can be unpacked and installed from the Tools and Utilities option in the installation DVD. In the SDK, there are example files that will help you get a better understanding of the API and its use. Each example file has a sample revit.ini file with the information that you will need to edit and place into the revit.ini file located in your Autodesk Revit Program folder, which Autodesk Revit will access on launch.
· Unzip the SDK onto a local drive
· Read the Read Me First.doc in the SDK
RevitAPI.chm is the Autodesk Revit API reference documentation help file, included with the SDK package in the \Revit 2012 SDK\ folder.
Resources:
- Autodesk Developer Network home (ADN)
- Autodesk Revit development resources
– Autodesk product discussion groups
Select = Autodesk Revit Architecture
Then Select = Autodesk Revit API
- The Building Coder, an AND blog dedicated to Revit coding

Documentation Conventions
This document will contain names in namespace format, such as Autodesk.Revit.DB.Element
What can you do with the Autodesk Revit API?
Deployment Options
The Autodesk Revit API supports in-process DLLs only. This means that your API application will be compiled as a DLL loaded into the Autodesk Revit process.
The Autodesk Revit API supports single threaded access only. This means that your API application must perform all Autodesk Revit API calls in the main thread (which is called by the Autodesk Revit process at various API entry points), and your API application cannot maintain operations in other threads and expect them to be able to make calls to Autodesk Revit at any time.
There are two types of DLLs that you can create with the Autodesk Revit API:
1. External commands
The Autodesk Revit API enables you to add new commands to the user interface of Autodesk Revit. These commands will appear in the Add-ins tab under the ‘External Tools’ pulldown, as seen in Figure 1. Through the API, external tool commands have access to the Autodesk Revit database, as well as the currently selected elements.

Figure 1 - External Tool added to Revit

2. External applications
The Autodesk Revit API enables you to also add external applications. These applications are invoked during Autodesk Revit startup and shutdown. They can create new panels in the Add-ins tab, as seen in Figure 2. They can also register handlers that can react to events occurring in the Autodesk Revit user interface.

Figure 2 - New panels and controls added to Revit

3. REX addins
REX is an API framework that lets you build applications for Revit in .NET similar to classes that implement IExternalCommand. REX is meant to give you a more high-level development environment through built-in resources such as:
· Automatic dialog box creation and display
· Libraries to work with units and geometry
· Built-in command-based architecture to make menu and toolbar development easier.
· A standard mechanism for accessing a reference to the Revit application object.
· Automatic deployment and installation of addins for easy debugging.
Please see the “\Revit 2012 SDK\REX SDK\” folder for more details.

Registration of add-ins
The Revit API offers the ability to register API applications via a .addin manifest file.
Manifest files will be read automatically by Revit when they are places in one of two locations on a user's system:
· In a non-user specific location in "application data"
o For Windows XP - C:\Documents and Settings\All Users\Application Data\Autodesk\Revit\Addins\2012\
o For Vista/Windows 7 - C:\ProgramData\Autodesk\Revit\Addins\2012\
· In a user specific location in "application data"
o For Windows XP - C:\Documents and Settings\<user>\Application Data\Autodesk\Revit\Addins\2012\
o For Vista/Windows 7 - C:\Users\<user>\AppData\Roaming\Autodesk\Revit\Addins\2012\
All files named .addin in these locations will be read and processed by Revit during startup.
A basic file adding one ExternalCommand looks like this:
<?xml version="1.0" encoding="utf-16" standalone="no"?>
<RevitAddIns>
<AddIn Type="Command">
<Assembly>c:\MyProgram\MyProgram.dll</Assembly>
<AddInId>76eb700a-2c85-4888-a78d-31429ecae9ed</AddInId>
<FullClassName>Revit.Samples.SampleCommand</FullClassName>
<Text>Sample command</Text>
<VisibilityMode>NotVisibleInFamily</VisibilityMode>
<VisibilityMode>NotVisibleInMEP</VisibilityMode>
<AvailabilityClassName>Revit.Samples.SampleAccessibilityCheck </AvailabilityClassName>
</AddIn>
</RevitAddIns>

A basic file adding one ExternalApplication looks like this:
<?xml version="1.0" encoding="utf-16" standalone="no"?>
<RevitAddIns>
<AddIn Type="Application">
<Name>My sample application</Name>
<Assembly>c:\MyProgram\MyProgram.dll</Assembly>
<AddInId>604B1052-F742-4951-8576-C261D1993107</AddInId>
<FullClassName>Revit.Samples.SampleApplication</FullClassName>
</AddIn>
</RevitAddIns>
Multiple AddIn elements may be provided in a single manifest file.
The new mechanism currently offers the following XML tags:
Tag
Description
Assembly
The full path to the add-in assembly file. Required for all ExternalCommands and ExternalApplications.
FullClassName
The full name of the class in the assembly file which implements IExternalCommand or IExternalApplication. Required for all ExternalCommands and ExternalApplications.
AddInId
A GUID which represents the id of this particular application. AddInIds must be unique for a given session of Revit. Autodesk recommends you generate a unique GUID for each registered application or command. Required for all ExternalCommands and ExternalApplications. The property UIApplication.ActiveAddInId provides programmatic access to this value, if required.
Name
The name of application. Required; for ExternalApplications only.
Text
The name of the button. Optional; use this tag for ExternalCommands only. The default is "External Tool".
Description
Short description of the command, will be used as the button tooltip. Optional; use this tag for ExternalCommands only. The default is a tooltip with just the command text.
VisibilityMode
Provides the ability to specify if the command is visible in project documents, family documents, or no document at all. Also provides the ability to specify the discipline(s) where the command should be visible. Multiple values may be set for this option. Optional; use this tag for ExternalCommands only. The default is to display the command in all modes and disciplines, including when there is no active document. Previously written external commands which need to run against the active document should either be modified to ensure that the code deals with invocation of the command when there is no active document, or apply the NotVisibleWhenNoActiveDocument mode.
AvailabilityClassName
The full name of the class in the assembly file which implemented IExternalCommandAvailability. This class allows the command button to be selectively grayed out depending on context. Optional; use this tag for ExternalCommands only. The default is a command that is available whenever it is visible.
LargeImage
The path to the icon to use for the button in the External Tools pulldown menu. The icon should be 32 x 32 pixels for best results. Optional; use this tag for ExternalCommands only. The default is to show a button without an icon.
LongDescription
Long description of the command, will be used as part of the button's extended tooltip. This tooltip is shown when the mouse hovers over the command for a long amount of time. You can split the text of this option into multiple paragraphs by placing <p> tags around each paragraph. Optional; use this tag for ExternalCommands only. If neither of this property and TooltipImage are supplied, the button will not have an extended tooltip.
TooltipImage
The path to an image file to show as a part of the button extended tooltip, shown when the mouse hovers over the command for a longer amount of time. Optional; use this tag for ExternalCommands only. If neither of this property and TooltipImage are supplied, the button will not have an extended tooltip.
LanguageType
Localization setting for Text, Description, LargeImage, LongDescription, and TooltipImage of external tools buttons. Revit will load the resource values from the specified language resource dll. The value can be one of the eleven languages supported by Revit. If no LanguageType is specified, the language resource which the current session of Revit is using will be automatically loaded.

External Commands
· Implement support for a specific interface, in this case Autodesk.Revit.UI.IExternalCommand.
· Adds one or more entries to the Revit.ini file describing the external command.

Technicall