The Building Coder

AU and Automated Testing

AU has been as exciting as ever, with lots of fascinating news and good meetings and discussions with developers and colleagues that I never get to meet except here. Here are some quick facts and photos.

I visited two great classes yesterday on the Revit API by Harry Mattison and Scott Conover, who both work with the internal development of the Revit API and really know what they are talking about:

• CP214-2 Creating and Analyzing New Conceptual Massing Geometry With the Autodesk® Revit® API
• CP222-3 Analyze Geometry of Buildings Using the Autodesk® Revit® API

I am very much looking forward to presenting some of the contents of these classes in upcoming posts.

Meanwhile, here is a great idea from Saikat Bhattacharya on how to automatically trigger automated testing, or perform any other action on a regular basis or at a specified time.

Question: Is there a way to call an add-in application from the command line? We would like to create and run an automated test for our export tool. This should run during the night, to provide the results the next morning.

Answer: We have looked at this and related issues several times in the past:

• Driving Revit from outside
• Accessing Revit from a modeless dialogue
• Programmatically triggering a command
• Journal file replay

Besides this, another workaround that comes to mind is to make use of the Revit auto-save mechanism. You could set up an external application which registers a DocumentSaving event handler. In this event handler, you could check to see if the system time is beyond midnight. In that case you can implement the functionality to export the data from your active Revit model. Revit can perform an auto-save of the model based on any interval you choose. Every time it does so, this mechanism will check the system time and run your custom export logic accordingly. I hope this helps.

Thank you Saikat for this brilliant idea to add to our growing arsenal of Revit automation tools!

AU Begins

I left the desert and the climbing in Red Rock and entered the air conditioned world of conference land. My first task Monday morning was the one I found most challenging, the recording session for my virtual class on the Revit Family API,

• CP9118-1 The New Autodesk Revit Family API: Everything is Relative

It was definitely an interesting experience, with an assistant fussing around to set things up and then sitting in a completely darkened room with several technicians managing the recording equipment, in a sphere of blinding lights directed at me and almost total blackness all around...

It went very well, in any case, and I was able to relax for the ADN conference during the rest of the day, although it did mean that I unfortunately missed the morning sessions of that.

The first broadcast of the Revit Family API is scheduled for this afternoon in just a couple of hour's time. I will be available online to chat and answer questions live in the question and answer session being held in parallel with the broadcast.

A second broadcast is scheduled for tomorrow evening. I would love to chat with you and answer your questions during either one of these two broadcast sessions.

For a live meeting, one place that I will certainly be is the classroom session I am presenting on the Revit MEP API,

• CP308-2 All Systems Go in the New Autodesk Revit MEP API

Another good place to meet me here at the conference is the AU booth. I will pass by there regularly and definitely be spending time there on Wednesday around 12:30 and 19:30.

Sunday before the Storm

The last hours before the conference I spent enjoying a nice, peaceful, sunny Sunday walking, reading and climbing a little bit in Red Rock, once again in the Black Corridor. I had one quick climb on a top rope with Chris and Daniela on Burros Don't Gamble 5.10c, and two climbs with Hannah and Jason, semi leading with the quickdraws already placed, on Vagabonds 5.10a and Burros Might Fly 5.10b.

Jess very friendlily sent me some photos from our climbs together on Friday:

Here I am in the beginning of a route that was too hard for me and I was unable to complete. But I was able to get down again safely the same way I went up:

And finally, here we are having a beer together after the successful day, Karl, Gary, Fritz, Ellis, and Jess, the crazy guys from Dallas, Texas, and me at the end, maybe a bit crazy as well:

AU Virtual free for ADN Members

Kean Walmsley just announced that a free Premier Pass to Autodesk University virtual is available for members of the Autodesk Developer Network.

Please join us there. We are presenting at both AUv and the non-virtual AU:

• Kean's F# sessions.
• AutoCAD-related AU and AUv sessions.
• The Revit Family and MEP APIs.

I am looking forward to seeing or hearing from you in the next couple of days!

Product Support Subscription Videos

I mentioned the Revit 2010 Subscription Pack last week, and Matt Mason highlighted the model review add-in included with it and its little API, which is just one example of all the good stuff in there. Autodesk Product Support has now published a series of  'deeper dive' subscription pack videos which cover the subscription pack features and functionality and provide you with a deeper understanding of their use as well as anticipating and answering potential questions.

Autodesk University Extension

As already mentioned, I submitted the material for my AU sessions last week, and one of them is a virtual class which will be broadcast live worldwide for those who cannot attend AU in Las Vegas in person. Another option for people not travelling to Las Vegas besides getting the $99 Premier Pass to AU Virtual is provided by the Autodesk University Extension, which is a collection of over 100 completely free training events, held in 35 countries and hosted by over 90 Authorized Training Center sites. Here is a comparison grid showing the difference between AU Extension and AU Virtual.

Now I need to practice my sessions a bit and prepare for a dry run to ensure that I have everything down pat. And also recuperate from the severe cold and bad throat that I have been suffering through for the past week. But better go through it now than later, of course, when I am travelling and presenting!

If you are interested in AutoCAD as well as Revit, Kean just published a list of the AutoCAD-related AU classes held by the DevTech team, both physical and virtual.

Model Review

We recently mentioned the subscription pack for Revit 2010. In addition to the product update itself, the subscription page for Autodesk Revit Architecture 2010 includes some new applications to complement Revit workflows to:

• Validate the accuracy of building information models against pre-determined standards.
• Import and export data between a Revit project and an external database.
• Facilitate the creation of 3D models from 2D digital photographs.

These areas are obviously of great interest for developers as well. The first of these points is addressed by the model review plug-in, which includes a small API for developers or customers to hook into to specify their own rules and standards to be checked. Matt Mason of Avatech Solutions, who is one of the original Model Review developers, now kindly wrote a summary of its functionality:

Introduction

Autodesk Revit^® Model Review is a new add-in product available to Autodesk subscription customers via the Revit 2010 Subscription Advantage Pack. Model Review provides the capability to configure and run checks against Revit projects or families and provide a report of whether the checks have passed or failed. Model Review provides 35 different kinds of checks, within the areas of:

• Modelling for Energy Analysis
• Revit Family consistency and standards
• Firm or Project-based Revit Standards
• GSA Spatial Program Validation

Here is a sample screen snapshot:

The Checking Platform

Model Review is not just a configurable set of checks provided by Autodesk – it is also a platform for developers to write their own checks and plug them in to the checking process. This could be desirable if BIM administrators want to check for issues which are not possible to check with the "out-of-the-box" Model Review checks, either because the check has not yet been implemented, or because it is too specialized to ever exist in the base product.

Creating a plug-in enables a developer who understands the Revit API to write a simple extension which leverages the Model Review platform for configuring, running, and reporting check results. These "plug-in" checks can be added to built-in checks to create the complete set of checks required by a particular firm or project.

Developers implement a few methods defining how the check should be configured, executed, reported – and optionally corrected. The check is then made available and can be run by Revit users as any other check in Model Review.

For your convenience, here is a direct link to a copy of the plug-in developer guide.

An Example

For example, one firm inquired about checking for whether a door’s Fire Rating was less than its host wall’s Fire Rating. This was made even more challenging because the Fire Rating field is text-based rather than a number, so the value might contain a string like "2 hours" instead of just numbers. Still, it is a fairly simple function to write within C# or VB.NET and the Revit API. A variation of this check is provided as a sample in the Model Review installation folder along with the developer guide.

Note: While Model Review is available for either Revit 2009 or 2010 products, the plug-in capability is only available in the 2010 version.

Revit API Forums

As you have seen in the past year and more, I am more than happy to answer any questions I can on the Revit API submitted in comments to this blog. Sometimes, however, questions are submitted that I really cannot answer. In many cases, there are other forums which are very suitable alternative places for either asking such questions or starting a thread or discussion on a specific topic.

I occasionally also receive emails with questions. In many cases, I will ask the sender to have a look at some of the blog posts and submit their questions as comments to those, so that other developers can respond as well.

And obviously, before you ask any questions at all, you can often save yourself and others some unnecessary effort by searching existing resources for answers. An efficient tool for finding answers on Revit API programming topics is Rod Howarth's global online Revit API help described in this previous post.

Here are some examples:

Question: I have some questions about sending and receiving keyboard input in Revit. I tried to reserve some keys in my plug-in, but haven't found any delegate to handle keystrokes. Unfortunately as a student I haven't got ADN subscription and I don't know anybody to ask... I hope you'll give me some tips... I found some resolution of this problem but it still isn't a good idea.

Answer: This is a question that is a bit too vague for me to say anything about directly. Instead of sending it to me by email, can I ask you to have a look at some of the blog posts dealing with these kinds of issues? If anything remains unclear and you have a specific question, please post it as a comment to the relevant post.

If you are looking for more general background information and a discussion among your peers, there are lots of people to ask out there, an unlimited number.

For instance, you can open a thread on AUGI, the Autodesk Users Group International. AUGI provides a large number of dedicated forums for discussions on topics such as Revit, with numerous subtopics including the Revit API, and also lots of international forums.

You can also initiate a discussion in one of the Autodesk discussion groups, for instance on the topic of Revit Architecture or the Revit API.

Here is a comment by Vincent providing an example of the kind of query that I cannot really answer at all, since it does not have to do with the API itself:

Question: Can you recommend a consultant in the Los Angeles area that understands the basics of the API? I would really like to work with someone for a day or two. Again, I'm learning C# programming and I feel adding source code and code regions are probably pretty easy to do once I gain a better understanding of the basics.

Answer: The short answer is no, sorry. I'm in Switzerland, in Europe. Some of the people I talk with may or may not be in your area, but I really don't know.

I completely agree with your assessment that it is not hard to make use of the API once you have gone through the getting started material. Still, for more complex issues, a bit of professional guidance can be invaluable.

You might be able to find someone in the ADN member database. Or you might post a query to the Revit API discussion group under http://discussion.autodesk.com > Revit Architecture > Revit API, or to AUGI, either in a specific forum e.g. under Revit or the Revit API, or possibly searching the AUGI web site globally for Los Angeles or something.

Autodesk Developer Network

At this point, I should not forget to mention my real work, which is providing developer support as part of the AEC workgroup of the DevTech team for ADN, the Autodesk Developer Network. The Autodesk Developer Network is a program providing professional support to programmers writing add-in applications for Autodesk software. One advantage of being an ADN member is that you can ask question on the Autodesk APIs and are guaranteed an answer within a certain time span, three days for standard and 24 hours for professional members. Here are some other of the program benefits:

• Access to almost all Autodesk software and SDK’s, including early access to Beta software
• Members-only website with thousands of technical articles
• Unlimited technical support
• Product direction through conferences
• Marketing benefits
• Exposure on autodesk.com
• Promotional opportunities
• 1 to 3 free API training classes

You don’t have to be a commercial software developer to join ADN.

And there is yet another level of even higher guidance available: if your needs go beyond simple generic support for the standard Autodesk APIs, you can also ask ADN or the Autodesk Consulting group for mentoring or custom development services.

Revit 2010 Subscription Pack

The Autodesk Subscription Advantage Packs have been released, including ones for Autodesk Revit Architecture, MEP and Structure 2010. English versions are now available for download on Subscription Center.

ADN members also have access to the subscription center by going to the ADN home page and selecting Autodesk Subscription Center. The subscription pack is also available directly from the ADN Revit download page. Look there for the Autodesk Revit 2010 September/October update.

The Revit 2010 subscription packs provide the same minor fixes and enhancements and the web update 2 plus significant additional new features.

The subscription pack also includes some API enhancements and is therefore accompanied by an updated SDK as well, which we explore below. First let's look at the updated product and documentation:

• Product and Documentation
• Revit API Enhancements

Product and Documentation

Since there are three different flavours of the subscription pack for Architecture, MEP and Structure, and each of these has its own 'what's new' documentation and is available both for 32 and 64 bit operating systems, the whole release adds up to this list of nine files:

• autodesk_revit_architecture_2010_subscription_update_x64_enu.exe (exe - 98730 Kb)
• autodesk_revit_architecture_2010_subscription_update_x86_enu.exe (exe - 72037 Kb)
• whatsnew_architectureq3.pdf (pdf - 2778 Kb)
• autodesk_revit_mep_2010_subscription_update_x64_enu.exe (exe - 98727 Kb)
• autodesk_revit_mep_2010_subscription_update_x86_enu.exe (exe - 72035 Kb)
• whatsnew_mepq3.pdf (pdf - 2789 Kb)
• autodesk_revit_structure_2010_subscription_update_x64_enu.exe (exe - 98734 Kb)
• autodesk_revit_structure_2010_subscription_update_x86_enu.exe (exe - 72042 Kb)
• whatsnew_structureq3.pdf (pdf - 1654 Kb)

All changes in the web update are also provided in the subscription release, so it is a true superset of the former.

Analogously to the web update, the three separate what's new documents list the enhancements provided both by the subscription pack products and the updated API.

One of the user interface enhancements which is new in the subscription release pack is the keyboard shortcut feature, which might prove extremely useful to application developers:

Keyboard Shortcuts

The subscription release of Revit provides an easy-to-use interface for managing keyboard shortcuts for Revit tools. With this interface, you can

• Add keyboard shortcuts. You can assign multiple shortcuts for each Revit tool.
• Remove keyboard shortcuts.
• Import keyboard shortcuts from another user. Also use this function to migrate shortcuts from a previous release.
• Export keyboard shortcuts to share them with other users, or to use the resulting file in a spreadsheet program, where you can sort, organize, and print a list of shortcuts for quick reference.

I received feedback from a developer who was driving a Revit 2009 add-in and its external commands using Windows messages. When the Revit 2010 user interface moved to the ribbon paradigm, this approach no longer worked and he was unable to support the new version. The new keyboard shortcuts effectively resolve this problem and external commands can now be launched programmatically. This leads us back to the API enhancements:

Revit API Enhancements

The subscription pack includes enhancements to the Revit API and an updated SDK. There are now separate versions of the SDK for the web update and the subscription releases, which are both available from the public Revit developer site and also from the members-only ADN pages:

• Revit 2010 SDK Update Release 2 (exe - 82402 Kb) (ADN)
• Revit 2010 SDK Subscription Release (exe - 82464 Kb) (ADN)

The new API functionality is described in the file 'Revit Platform API Changes and Additions.doc'. The help file RevitAPI.chm file also reflects these changes. The subscription release has the same changes as the web update, plus additional APIs.

Revit SDK Differences

I analysed the differences between the initial release of the Revit SDK and the two new updated versions provided with the web update 2 and the subscription pack:

• revit2010sdksubscriptionreleasepack.exe – 84,443,139 bytes
• revit2010sdkupdaterelease2.exe – 84,380,018 bytes

The two SDKs are identical, except for three files:

• Read me first.doc – minimal changes.
• Revit platform API changes and additions.doc – significant informative differences.
• RevitAPI.chm – different.

The changes and additions document calls out the improvements made.

We already discussed the web update 2 API enhancements, e.g.

• Rename and replace a family parameter.
• Extract GUID from a parameter.
• Improved stability of DocumentOpened event.

The subscription pack release includes these as well as the following:

• Export model to IFC.
• Floor slope and elevation.
• NewTruss() in Revit Architecture.
• Export - 24-bit colour option in export to AutoCAD file formats.
• Validation in ElectricalSystem properties.
• SuspendUpdating applies to Parameter.Set.

The sample applications provided in the updates are virtually identical to the ones in the original release of the SDK.

Regarding the SDK backward compatibility, the same applies as for the web update 2:

Both the web update 2 release and the subscription pack provide a few new API calls. The API is compatible between all versions as long as the new calls are not accessed. You need ensure that the user has installed and is using the subscription release before using any of the new calls.

SuspendUpdating applies to Parameter.Set and Plug-in Backward Compatibility

In the subscription pack release of the Revit SDK, the SuspendUpdating class has a new constructor which will cause Parameter.Set not to update the entire building model every time a single parameter on an individual element is modified. This affects all instance parameters defined in families, when the parameter value is modified on the inserted family instances. We have seen speed improvements where a processing time of 5 minutes is reduced to 15 seconds to change 100 parameters on one single element, and the effect is probably similar when changing a single parameter on 100 different elements.

An application taking advantage of the new functionality will be incompatible with the initial release of Revit 2010 and will only compile with the newer API. An application created for the initial release of Revit 2010 will obviously still run, but will not be able to take advantage of this enhancement. You might be able to build an application which will both run on the initial version and also take advantage of the new functionality by using reflection to check at runtime whether the new API call is available at all. You could also query the build number to decide whether to use reflection to try to find the new method.

AU 2009

These days I am pretty occupied with the preparation of my sessions for Autodesk University 2009:

• CP308-2 All Systems Go in the New Autodesk Revit MEP API
• CP9118-1 The New Autodesk Revit Family API: Everything is Relative

The Family API one is a virtual class which requires special preparation, since it is being recorded and broadcast worldwide for Virtual Autodesk University. As Rick Graham pointed out, virtual AU was created for those who are not able to make it to Las Vegas in person, and is free for subscription customers.

Here are links to the standard class catalogue and the virtual classes.

I would love to see you in person in the classroom session, or chat with you live during one of the virtual ones.

Revit 2010 Web Update 2

The first web update of Revit 2010 (build 20090612_2115) was already released earlier this year. Now the web update 2 for Revit 2010 (build 20090914_1845) including new fixes and minor enhancements has been published and can be downloaded from the public Revit product pages:

• Revit Architecture > Product Download
• Revit Structure > Product Download
• Revit MEP > Product Download

The update is also available from the ADN Revit download page. Look there for the Autodesk Revit 2010 September/October update.

The update is accompanied by an updated SDK as well. Here is an overview of the material:

• Product and Documentation
• The Revit SDK

Product and Documentation

Since there are three different flavours of the update for Architecture, MEP and Structure, and each of these has its own 'what's new' documentation and is available both for 32 and 64 bit operating systems, the whole release adds up to this list of nine files:

• autodesk_revit_architecture_2010-x86_update_2.exe (exe - 69643 Kb)
• autodesk_revit_architecture_2010-x64_update_2.exe (exe - 96330 Kb)
• rac2010_update2_list.docx (docx - 42 Kb)
• autodesk_revit_mep_2010-x86_update_2.exe (exe - 69641 Kb)
• autodesk_revit_mep_2010-x64_update_2.exe (exe - 96327 Kb)
• rme2010_update2_list.docx (docx - 30 Kb)
• autodesk_revit_structure_2010-x86_update_2.exe (exe - 69647 Kb)
• autodesk_revit_structure_2010-x64_update_2.exe (exe - 96333 Kb)
• rst2010_update2_list.docx (docx - 42 Kb)

The three separate 'update 2 list' documents discuss the enhancements made both to the product and API.

The only API enhancement listed for update 2 is improved stability when subscribing to a DocumentOpened event. We return to that issue below in the discussion of the updated SDK.

The Revit SDK

The Revit SDK has also been updated for the web update. Normally, the SDK is included in the product installation files. Its default location in the temporary installation folder on my machine is

• C:/Autodesk/RAC_2010_English_Win_32bit/support/SDK/RevitSDK.exe

This however is not valid for the updated SDK. To obtain that, you need to download it from the public Revit developer page. Look for Revit 2010 SDK (Update 2, Sept 15, 2009), a 82402 Kb EXE file. It is also available from the members-only Revit software download page on the ADN web site, where it is posted as Revit 2010 SDK Update Release 2.

The new API functionality is described in the file 'Revit Platform API Changes and Additions.doc', namely:

Changes to the Revit API since the initial release of Autodesk Revit 2010

Rename and replace a family parameter

The method

• FamilyManager.RenameParameter()

allows you to rename a Family parameter.

The overloaded methods

• FamilyManager.ReplaceParameter()

allow you to replace a Family parameter with a new shared parameter, or a shared parameter with a new Family parameter.

Extract GUID from a Parameter

The new properties

• Parameter.IsShared
• Parameter.GUID

identify if a given parameter is a shared parameter, and if it is, extract its GUID.

The help file RevitAPI.chm file also reflects these changes.

Revit SDK Differences

I ran a file comparison to analyse the differences between the initial release of the Revit SDK and the updated one and found them to be virtually identical, except for three files:

• read me first.doc – minimal changes.
• revit platform api changes and additions.doc – the new functionality listed above.
• revitapi.chm – different.

The sample applications provided in the updates are also identical to the ones in the original release of the SDK with a very few minute modifications.

SDK Backward Compatibility

Question: I installed Revit 2010 together with the original SDK. When installing, the web update was automatically picked up, downloaded and installed as well.

My question is: would this updated SDK work with my Revit 2010 as such? Do I need to install anything on top of it, i.e. one of the web update 2 or subscription pack releases?

Answer: The web update 2 release is simply an update, so the accompanying SDK will work for both that and the initial release. There are a few new APIs that will work only on the update, but as long as you are not using those, it should be compatible between these versions. You need to ensure that the update has been installed before making calls to any of the new API methods.

See the 'Revit Platform API changes and Additions.doc' document for details of the new APIs for each SDK. This information is also provided in the RevitAPI.chm file in the 'What's New' topic.

DocumentOpened Event Stability

Question: I defined a DocumentOpened event handler and added it in my OnStartUp function:

application.DocumentOpened 
  += new EventHandler(
    application_DocumentOpened );

Once I do so, however, Revit crashes when I open a document with linked documents, even in an empty project, and even if the application_DocumentOpened function is empty too! Is this a known issue?

Answer: This issue is resolved by the improved stability of this API in the web update 2.