Revit2011 API – What’s in a name?

As Jeremy noted Revit 2011 API has had a major refactoring of the namespaces as well as splitting into 2 assemblies. Before I start talking about the lovely new functionality in this release I want to discuss the implications of this change. In many ways this is the most significant aspect of the Revit2011 API.

Why have they done this? It’s a huge job and you wouldn’t do it by choice. Related to this is the move away from a relatively unique API in VSTA which used proxies and AppDomains to implement the compile/run/recompile cycle VSTA allows. VSTA now has exactly the same API as the standard API, and some magic for the reload cycle in VSTA. This will make the use of common code libraries in VSTA straightforward and no doubt lower the workload for the API team.

The basis for the namespace changes is a move by the Factory to using semi-automatic code generation tools to generate the .NET API. Simplistically what this means is the .NET API is as close as we get to a view of the source code. The .NET API’s essentially mirror those used internally for the base Revit application. A classic example of this is the renaming of the Symbol class to ElementType. In .NET {some name}Type naming is usually reserved for enum’s. Yet ElementType is a class in the new API as this is what it’s named in the unmanaged world. For experienced .NET developers and those new to the Revit API a casual parse of the API may be a bit confusing in places but on the whole the new structure of the API and the namespaces is logical.

The move to code generation tools is very significant for a number of reasons (in no particular order):

• It’s both enlightening and instructive to see how they have designed API’s internally.
• It means the API team should have more time to implement new features rather than fighting the transition between the unmanaged and managed worlds. Testing should be easier. No excuses for missing functionality in the API now ;-) ;-) (Not true as explained below)
• We automatically get a significantly more powerful API. Namely in direct support for Revit transactions ,failures and exception handling API’s. This does mean we can’t avoid implementing transactions at the very least. For beginners it’s yet another thing to understand but luckily the API is both powerful and easy to understand.
• Implementation of new base functionality via the API, is relatively straightforward. 2 good examples of this are the new sheetholder API and reporting parameters. Reporting parameters will be widely used and having API support from day one is fantastic. Robert has a good introduction to them here.
• More generics and better support for .NET language features in VSTA and the base API.

Given these code generation tools are semi-automatic, for the average punter and API developers I believe it gives us pointers to some of the internal struggles the Factory may be having with the Revit codebase. We’ve all had long standing requests for improvements in stairs, addition of groups, worksets schedules etc in the API as examples. So as we move into future releases of the API, excluding lack of resources if a feature isn’t added in the API we can hazard a guess as to why:

• The internal API could be a bit of a mess and doesn’t map well to the .NET world. In this case it’s reasonable to assume the internal API’s are on the todo list for a rework.
• There is major changes in the base application planned and exposing the current API is undesirable.

Undoubtedly this release has been a massive amount of work for the API team and I’m sure they’re well overdue for a holiday. Moving on to future releases though should make their job easier and each new release even more impressive for 3rd party developers. Exciting times!!!

Just to finish, for those with a reasonable sized legacy codebase and developers in general, the namespace changes are a walk in the park for Resharper. So if you’re serious about developing I can strongly recommend Resharper . At the moment if you buy V4.5 you get an upgrade to V5 for free. It’s an essential tool for me and has made moving to Revit2011 a walk in the park.