The Building Coder

The Champions Roundtable at AU

Tuesday we held a DevLab at AU successfully exploring and resolving a bunch of interesting issues. I hope to get around to documenting and sharing some of them soon, before being overwhelmed by other new exciting stuff. The most pressing priority first, though: sharing the notes from the Revit API roundtable session.

My first session at AU was a very pleasant, comfortable and fun one, being a roundtable providing a free-for-all exchange of questions, views and feedback between the audience and a bunch of Autodesk employees. The Autodesk side included developers creating the Revit API, ADN developer supporters supporting people in making use of it, and consultants who actually use it themselves. The audience was you guys.

We tried to keep the questions and answers short and to the point, and I tried to take notes of everything said. They are provided below, only very slightly edited for readability, and possibly cryptic for those of you who did not attend the session. I wish you some enjoyable head-scratching trying to decipher what we actually meant.

Before we dive into the notes, here are its AU catalogue entry and a very few slides listing the goal of this meeting and the panellists answering the questions:

CP4109 – Revit API Round Table: Meet the Champions

Class Summary

• Interact with a panel of Autodesk Revit API experts
• Ask questions and discuss topics of your choice
• Get to know the people who shape the APIs you work with better
• Explain your views, ideas and problems directly face to face

Learning Objectives

At the end of this class, you will have

• Interacted with a panel of Autodesk Revit API experts
• Asked questions and discussed topics of your choice
• Got to know the people who shape the APIs you work with better
• Explained your views, ideas and problems directly face to face

Panellists

• Arnošt Löbel, Revit Developer
• Augusto Gonçalves, ADN
• Jeremy Tammik, ADN
• Miroslav Schonauer, Consulting
• Saikat Bhattacharya, ADN
• Steven Mycynek, Revit API Engineer

Learning More

• Revit Developer Center: DevTV and My First Plugin Introduction, SDK, Samples, API Help
• Developer Guide and Online Help
• API trainings, webcasts and archives > Revit API
• Discussion groups > Revit Architecture > Revit API
• API training classes
• ADN AEC DevBlog
• The Building Coder Revit API Blog
• ADN and ADN Open, The Autodesk Developer Network
• DevHelp Online for ADN members

Almost Unedited Notes from the Session

Here are my session notes in a rough and almost verbatim Q&A format:

What is coming up in future versions? We cannot talk about that here. Please join ADN for more info, sign an NDA agreement.

Why are you guys using Macs? No Autodesk or Revit-specific reason.

What are some common themes or requests for API app development? Hard to say, depends on company; high level: getting data from Revit, enterprise wide integration, setting up a BIM enterprise structure, company specific needs...

How can I effectively run a batch operation to open successive work shared Revit files and run an external command on them? Keep track of the processes; expect to handle failure and recovery. What do you want to achieve? You can use journaling, but not recommended. Open file, close file. No problem in theory. We are not leaking any memory. Managed stuff gets garbage collected eventually. To launch command automatically, install an external application and register for the OnDocumentOpenend event. Lots of communication pipelines available, various messaging mechanisms. What do you want to achieve? Export data to SQL, for example. One app doing this in a batch process, download file from Revit server. Ensure that the app provides feedback on what it is doing, log the events, be able to study log file. Maybe 1000 files process well and one of them fails. Saikat created a plug-in of the month which batch processes RVT files to upgrade them to a newer version doing SaveAs; it also logs all events and writes to text file. You can also look at the progress notification introduced in Revit 2013, that provides more feedback

General organisation of elements inside Revit: family dictates behaviour, categories, etc. this limits some things, pretty strict structure. Will this change? No, not significantly. We can take this as feedback.

External RealDWG application creates 3D drawing using Revit API? Develop Revit external application which queries external data source, query it regularly to write feedback... Revit threading model does not allow for directly attaching, need to use some kind of messaging model. An external program cannot directly access the Revit API.

AutoCAD provides the command console allowing data access without GUI... is anything similar coming for Revit? That would be a nice enhancement. Originally there was no API for Revit, it was highly user focused, and the thought was it would never need an API.

It is currently not possible to access the Revit database without opening Revit. What is the reason for that? You are always opening an application to access its complex internal data structures. It may be happening in the background, invisibly. We should be able to provide some kind of RealDWG-like access sometime in the future to RVT as well.

We would like to parametrically change the model to run different energy simulations on it; changing one parameter affects many other ones, creating a new model to export, but I do not want to see the changes, just change the model without visual feedback. How can this be achieved? The Revit model is parametric, you cannot even query it without regeneration, and it is in an invalid state until regeneration, e.g. transaction committed, half-baked until then. You can open documents in the background, then they are not visualised. Call OpenDocumentFile, it opens in the database but not in the UI. Later we added OpenAndActivate, which does both. Regeneration is smart. Revit updates only the minimal set requiring it. If you regenerate twice in a row, the second call does nothing.

Do I need to commit the transaction to ensure the model is correctly updated? Technically yes, but sometimes no. Sometimes the transaction needs to be committed to propagate the changes fully, sometimes simply regenerating is sufficient.

The API is great at customising the ribbon, but a more important aspect of Revit is its parameters, and there is little help there for users. Is there any way to improve this? We looked at putting a real API around parameters. Talk with the product managers, they need to balance requirements. Parameters could definitely be easier to use.

Managing large numbers of large Revit project files, it is difficult to keep everything up to date. Some people create a new local file every day, even update the central file. How stable is the program? Do I need to do anything to protect my model? We only create small test models. Some people create huge files. Stability is getting better all the time; regression tests improve all the time. Best practices improve. Most Revit problems have to do with not following best practice. The Revit API and every add-in always needs to respect best practice, not fight it. Completely different from other CAD systems. Big investment, understand the product and best practice.

Managing Revit server effectively? What are the best practices? It may be ok to update users every year, but painful to do so for servers, it is painful to update servers every year like Revit users. Is Revit server on the same release cycle as the Revit product? What would the alternative be? The file format should not change every release.

Can we edit a group in the API? No, you have to ungroup and regroup. There are some blog posts on this. If multiple instances of the group exist, you have to replace all the instances.

The dynamic updater framework can display a missing updater warning. Can I suppress that? There is an option to suppress that screen. When you register the updater you can set it as optional, so the end user is not bothered by the message if it is missing. Before that option appeared, you could just open the file without the updater, choose to ignore the missing updater, and save the file before sending it to someone else. Now you can control it as the updater implementer.

Some families have options for how they look in different views. Can I make other categories do the thing? Some families will only allow plan view. Can you achieve this from the UI? No. In that case you cannot do it programmatically either. Now I have to go and tag every damper in the section. The aim is to provide API access to everything available in the UI.

Issues with shared families. A family with no instances placed creates an instance of its geometry even if it is not placed. If an instance is placed which conflicts with the geometry, it can cause a 'cannot make type' error. How can this be worked around? This is a regeneration issue. Query noted.

How can I check what Revit is doing? Use the progress notification, which tells you all the sub-steps happening during transactions. You might have to do some primitive benchmarking.

Are processes that occur during regen behind the scenes documented in the journal file? Some stuff is, it is up to the individual programmer. They can check a journal coming back from a customer. The content may be cryptic and does not explain. Sometimes debugging significantly impacts performance, of course.

When I open a transaction on a work shared model, should I verify that all elements can be modified before committing the transaction? I don't think you can check whether an individual element is modifiable. There was a plan, maybe, for that. This kind of feature has been requested. Currently the transaction will be rolled back. Actually you can check this somehow, maybe.

DesignScript is now integrated in AutoCAD. Are there any plans for providing this in Revit as well? We would like to create parametric masses. DesignScript looks as if it is open enough to be integrated into Revit. No new language integration is simple, but it looks as if it might fit and be useful.

What are the most prominent issues you run across, the most common things that pops up? Install RevitLookup, explore the model. Driving from external process, use Idling event. Daily requests: multithreading, 100% API coverage of worksharing functionality, integration and speed. When we get several similar requests, we blog about them, either on The Building Coder or the ADN AEC DevBlog. Why do you ask this, actually? Just for sharing and discussing here together. Also we keep receiving recurring issues. It helps to know the real good solution. Another common issue: how to get data from Revit and export to Excel or Access, and reimport. It is easy, but customers face many challenges, lots of countrification needs. People coming from other CAD systems and used to the sketch plane modelling and create feature are a bit surprised by Revit family editor and constraints and dimensions etc. It is possible to create a dimensioned family and make it parametric through the API. That is not intuitive, that is a challenge. Take a few steps back, look at how Revit does things, and then reproduce that relationship programmatically. Revit is not mechanical engineering. Understand the UI first, and then move on to API.

Do you follow the Autodesk discussion forums? Yes.

Can I use formulas to establish parametric relations between different families, e.g. if I want the width of family A to be driven by the height of family B? Good question, not currently supported.

Can I access the document warnings? There is the failure API, but no access to the warnings. There are ways to get rid of failures. Install the failure processor at application level. You get called when transaction ends and if there are failures your processor is called and you can decide how to handle them. I get a model and it has 300 warnings in it. Can I get that list? The failure processor does not give you that list? No, probably not. If you go to look at warnings in Revit, you can export that list to a text file. It would be nice to be able to fix warnings such as the 'line off axis', provide tools and options to fix this, or an option to leave it as it is.

Every column I touch is part of a phase and design option. Currently the phase mapping is not part of the Revit API. I run into problems trying to match phases when they differ between linked and host model. We have a link API in 2013 and a list of additions, I think something more will be coming in that area. The goal for the API is to provide 100% access to all end user features. Right now all new features are automatically exposed to the API as well.

C# versus VB? It all goes to the same place. It all compiles to IL and can be decompiled as well.

Dispose is inherited through the class hierarchy from APIObject. Do we need to dispose of all the objects we use? It is probably good practice. It happens eventually through the GC. We have scoped objects, everything with a start and an end, e.g. transaction. If you dispose that, it is automatically ended. The easiest way is to use a 'using' block. You must call Commit, Rollback or Dispose. APIObject is only a very thin wrapper. Dispose does not actually do anything. If you need to clean up memory and access a lot of data from Revit, you may want to call Dispose yourself in between loop iterations, e.g. If you do not call Dispose, Revit will hold on to the object even if GC is called. If you call Dispose, then we let go. When the command ends, everything is disposed. Revit elements can have an unpredictable lifetime. It is always safer to hold on to an element id rather than an element. Native pointers are invalidated. You can test whether an element is invalid. You can modify an element, then delete it, undo the deletion, and the element pointer will go from valid to null and back to valid again. You do not have to refetch the element, actually, Revit handles its validity. The API creates a managed wrapper around the native pointer.

Error reporting. When a user has an error and we do not have all the info. Is there a central file location where more error reporting is available? Beside the journal there is something worksharing related log file, extension 'slog', monitoring activity between local and central, meant for programmers, not customers, that might provide some hints. Same folder as central file.

Insight into eTransmit? Visit Arnošt's AU session on Wednesday.

Unique id? Working with linked files, the unique id can actually be the same for different files. Looking for a view n a linked file, the view in link and host has the same unique id. Element id yes, of course, they only work within the session, and might change due to worksharing session, but unique id should be stable and unique. If you see a duplicate unique id, please report it to us.

What are the coolest projects you have seen? The ruby scripting plugin and its installer. ZoomToAwesome, which basically consists of one single line of code.

A plugin can bring down Revit. This should not happen. Revit builds in protection in the external command framework that should shield Revit and the end user from all misbehaviour. Dynamic updaters as well. App can cause exception within exception, very hard to protect against. We make it as robust as possible, and still try to open up wide and give you all the options. Example: call a command, do something bad, invalid geometry, try to commit transaction, failure handling, try to resolve, you have a failure resolver, this causes another exception, things can get really bad. A point about add-ins, which is a limitation of .NET and Windows: if your add-in uses COM interop and dereferences an invalid pointer, we cannot protect against that. Unsafe code and p/invoke cannot be protected completely.

Reload the keynotes text file from the API. Not supported, sorry.

Building is data. Can we tap into that without dB link? Direct query?

Thank you for a very interesting discussion with numerous insights on both sides! Have fun using the Revit API!

Updater Queues Multi-Transaction Operation for Idling

I recently pointed out that certain operations require multiple transactions to complete.

The dynamic model updater framework DMU, on the other hand, takes complete control over the transaction handling, making it impossible to incorporate such a multi-transaction operation.

The updater framework is designed to enable an add-in to incorporate its own additional behaviour into a running transaction to react to changes in the model. The advantage is that the entire operation including the custom add-in behaviour is encapsulated in one single transaction. This comes at a price, as said: the add-in has no control whatsoever over the transaction management. It thus also obviously cannot add additional transactions into the process.

Let me present a powerful and generic workaround to this limitation, suggested by Rudolf Honke.

He ran into this issue when trying to group elements in an updater, for instance for his dynamic insulation and dynamic arrangement of elements on a terrain surface tools. The dynamic insulation group behaves almost like a custom entity in AutoCAD:

The element arrangement on terrain can be used to place trees, lampposts, and other objects to follow a curve and update automatically to changes in the curve:

The narration for these two videos is in German, by Mr Honke himself. The dynamic insulation tool is also available in an English version, but that has not yet been uploaded.

Both of these tools generate and handle groups of elements and react dynamically to later changes of the model.

The reaction makes use of the DMU; there is no other choice. However, the entire update operation requires ungrouping, modifying and regrouping of elements and cannot be achieved within the single transaction provided.

Additional transactions in the IUpdater would be required to handle this gracefully.

In lack of this, here is Rudolf's workaround:

1. In the updater, save a list of elements requiring update.
2. Subscribe to the Idling event.
3. In the Idling event handler, call the standard add-in command that has no restrictions on its transaction handling.
4. In the command, process the queued up elements and clear the list.
5. Unsubscribe from Idling.

In the actual implementation, the elements obviously maintain some data about their relationships, so the modification of an element can easily discover which other elements are affected.

Here are a few more details and several reasons why this is necessary:

• The insulation tool needs to both delete and create new DetailCurves. It also needs to create a new HermiteSpline which is not a DetailCurve at all, by the way. By the way, accessing its ElementId during the insulation creation process requires a (temporary) DocumentChanged event, which is another topic that we will not explore any deeper here. To avoid ForbiddenForDynamicUpdateExceptions, the creation is placed in a completely new transaction.
• The dynamic fence and arranging-items-on-terrain tools require creation of new FamilyInstances, which should be avoided in the IUpdater context, as stated in the Revit API help file RevitAPI.chm.
• The error handling needs to be able to use FailureHandlingOptions, which again means that the add-in has to have full access to the transaction itself.

The IUpdater context is fine for just setting parameters, but these tools need more than that, e.g. deleting elements, creating new ones, adding extensible storage data to handle the element connection logic, handling Failures, etc.

I recently ran into a different case where a developer was trying to make use of the InstanceVoidCutUtils class to insert a void on a modified wall within the updater Execute method. This caused Revit to display an error message saying "Third party updater Xyz has experienced a problem and its action had to be canceled." Removing the one single line triggering the void generation from the updater enables to operation to complete, but the void is still missing, of course. That seems to me like a prime use case for Rudolf's approach as well.

DocumentChanged versus Dynamic Model Updater

Here is an interesting little overview and comparison of possibilities to react efficiently to the addition of certain elements to the database. Two easy ways to achieve this are by subscribing to the unspecific DocumentChanged event, or by registering a more specific DMU dynamic model updater. If you subscribe to an event or register an updater, it is also important to keep in mind to unsubscribe or unregister when you are done with it.

We discussed both of these repeatedly in the past, e.g. when looking at preventing element deletion and avoiding Idling.

In this case, the aim is to display a message box to the user when a new elevation view is added.

Subscribe to DocumentChanged to React to Elevation View Creation

It is easy to detect when a specific element is added, such as a new elevation view, for instance by subscribing to the DocumentChanged event. This can be done either in the OnStartup method of an external application or from an external command. In either case, you should pay attention to also unsubscribe from the event when it is no longer needed, for instance on application shutdown, at the end of the command, or from some other place.

In order to test the behaviour simply from within the standard framework of The Building Coder sample collection, I implemented a simple external command CmdElevationWatcher subscribing to the event. The event handler receives a DocumentChangedEventArgs instance providing three separate collections of ids of added, deleted and modified elements. We pass in the list of added ids to the FindElevationView method, which returns the first elevation view in the given element id collection if one exists, causing a message box listing it to be displayed.

Here is the entire code of this external command implementation:

/// <summary>
/// React to elevation view creation subscribing to DocumentChanged event
/// </summary>
[Transaction( TransactionMode.ReadOnly )]
class CmdElevationWatcher : IExternalCommand
{
  /// <summary>
  /// Return the first elevation view found in the 
  /// given element id collection or null.
  /// </summary>
  static View FindElevationView(
    Document doc,
    ICollection<ElementId> ids )
  {
    View view = null;
 
    foreach( ElementId id in ids )
    {
      view = doc.GetElement( id ) as View;
 
      if( null != view
        && ViewType.Elevation == view.ViewType )
      {
        break;
      }
 
      view = null;
    }
    return view;
  }
 
  /// <summary>
  /// DocumentChanged event handler
  /// </summary>
  static void OnDocumentChanged(
    object sender,
    DocumentChangedEventArgs e )
  {
    Document doc = e.GetDocument();
 
    View view = FindElevationView( 
      doc, e.GetAddedElementIds() );
 
    if( null != view )
    {
      string msg = string.Format( 
        "You just created an "
        + "elevation view '{0}'. Are you "
        + "sure you want to do that? "
        + "(Elevations don't show hidden line "
        + "detail, which makes them unsuitable "
        + "for core wall elevations etc.)", 
        view.Name );
 
      TaskDialog.Show( "ElevationChecker", msg );
    }
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    Application app = uiapp.Application;
 
    // Subscribe to DocumentChanged event
 
    app.DocumentChanged
      += new EventHandler<DocumentChangedEventArgs>(
        OnDocumentChanged );
 
    return Result.Succeeded;
  }
}

After this command has been executed, the event is subscribed to. Any subsequent elevation view insertion results in the message box being displayed, for instance when I duplicate the East elevation view:

This approach has two significant disadvantages:

1. It reacts erroneously when a family is loaded.
2. Its performance is suboptimal.

1. When a family is loaded into a project, its views are also inserted with it. This insertion currently triggers a DocumentChanged event on the elevation views as well. For instance, if I load the standard rectangular column 'family M_Rectangular Column.rfa', a similar message appears:

This is unintentional and potentially confusing.

2. The performance is not optimal, since DocumentChanged reacts to each and every modification of the document. Furthermore, every single added element needs to be examined to check whether it is an elevation view.

Both of these disadvantages can easily be avoided by using the dynamic model update mechanism DMU instead.

Install Dynamic Model Updater to React to Elevation View Creation

As said, the dynamic model updater mechanism can easily be used to determine that specific elements have been added to the database, and it avoids the DocumentChanged event disadvantages mentioned above, since it reacts only to certain well-defined modifications on a certain well-defined set of elements used to set up the updater trigger.

First we need to implement our updater class to display a message if an elevation view is added:

/// <summary>
/// Updater notifying user if an 
/// elevation view was added.
/// </summary>
public class ElevationWatcherUpdater : IUpdater
{
  static AddInId _appId;
  static UpdaterId _updaterId;
 
  public ElevationWatcherUpdater( AddInId id )
  {
    _appId = id;
 
    _updaterId = new UpdaterId( _appId, new Guid(
      "fafbf6b2-4c06-42d4-97c1-d1b4eb593eff" ) );
  }
 
  public void Execute( UpdaterData data )
  {
    Document doc = data.GetDocument();
    Application app = doc.Application;
    foreach( ElementId id in 
      data.GetAddedElementIds() )
    {
      View view = doc.GetElement( id ) as View;
 
      if( null != view 
        && ViewType.Elevation == view.ViewType )
      {
        TaskDialog.Show( "ElevationWatcher Updater",
          string.Format( "New elevation view '{0}'",
            view.Name ) );
      }
    }
  }
 
  public string GetAdditionalInformation() 
  { 
    return "The Building Coder, "
      + "http://thebuildingcoder.typepad.com"; 
  }
 
  public ChangePriority GetChangePriority() 
  { 
    return ChangePriority.FloorsRoofsStructuralWalls; 
  }
 
  public UpdaterId GetUpdaterId() 
  { 
    return _updaterId; 
  }
 
  public string GetUpdaterName() 
  {
    return "ElevationWatcherUpdater";
  }
}

With this in place, we can implement a second external test command CmdElevationWatcherUpdater to instantiate and register our updater and define a trigger for it. The trigger reacts only to the creation of new view elements:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  Application app = uiapp.Application;
 
  // Register updater to react to view creation
 
  ElevationWatcherUpdater updater 
    = new ElevationWatcherUpdater(
      app.ActiveAddInId );
 
  UpdaterRegistry.RegisterUpdater( updater );
 
  ElementCategoryFilter f
    = new ElementCategoryFilter(
      BuiltInCategory.OST_Views );
 
  UpdaterRegistry.AddTrigger(
    updater.GetUpdaterId(), f,
    Element.GetChangeTypeElementAddition() );
 
  return Result.Succeeded;
}

After this command has been executed once, the updater is registered and its trigger installed. Like before, any subsequent elevation view insertion results in its message box being displayed, for instance when I again duplicate the East elevation view:

Unsubscribe from Event and Unregister Updater

Before letting this loose on the general public, I thought I would be a good citizen for the nonce and clean up after myself.

To do so, I modified both command implementations so that each call to the command toggles the event subscription or updater registration on and off.

In both cases, this was very easily achieved. I simply implemented a static member variable to hold the event handler delegate or the updater and initialised it to null. It looks like this for the DocumentChanged event handler:

  /// <summary>
  /// Keep a reference to the handler, so we know 
  /// whether we have already registered and need 
  /// to unregister or vice versa.
  /// </summary>
  static EventHandler<DocumentChangedEventArgs> 
    _handler = null;

It is even simpler for the updater:

  /// <summary>
  /// Keep a reference to the updater, so we know 
  /// whether we have already registered and need 
  /// to unregister or vice versa.
  /// </summary>
  static ElevationWatcherUpdater _updater = null;

Each time the command is run, it either subscribes/registers and sets the reference if it was null previously, or unsubscribes/unregisters and nulls it in the other case. Here is the relevant updated code snippet for the DocumentChanged event:

  if( null == _handler )
  {
    _handler
      = new EventHandler<DocumentChangedEventArgs>(
        OnDocumentChanged );
 
    // Subscribe to DocumentChanged event
 
    app.DocumentChanged += _handler;
  }
  else
  {
    app.DocumentChanged -= _handler;
    _handler = null;
  }

Here is the corresponding code for DMU:

  if( null == _updater )
  {
    _updater = new ElevationWatcherUpdater(
      app.ActiveAddInId );
 
    // Register updater to react to view creation
 
    UpdaterRegistry.RegisterUpdater( _updater );
 
    ElementCategoryFilter f
      = new ElementCategoryFilter(
        BuiltInCategory.OST_Views );
 
    UpdaterRegistry.AddTrigger(
      _updater.GetUpdaterId(), f,
      Element.GetChangeTypeElementAddition() );
  }
  else
  {
    UpdaterRegistry.UnregisterUpdater( 
      _updater.GetUpdaterId() );
 
    _updater = null;
  }

Here is version 2013.0.99.0 of The Building Coder samples including the two new commands.

I hope you find this comparison useful, appreciate how simple both of these mechanisms are to use, and understand the advantages offered by the DMU.

Addendum: As Victor very correctly points out below, I omitted highlighting the main difference between the DocumentChanged event and the DMU mechanism, since we have discussed it several times in the past:

The DocumentChanged event is not raised until after the transaction causing it has been closed, so the changes made cannot be cancelled. If elements were deleted, they are gone by the time you receive the notification; all you receive from the event handler argument is their element ids, and you cannot even find out what type they were. The updater is called within the same transaction as the modification causing it, providing much more control.

Avoid Idling

The advice to 'avoid Idling' may sound rather puritanical and a bit on the workaholic side, but I pay it special heed since it comes from Arnošt Löbel, Sr. Principal Engineer in the Revit development team, our resident Revit Idling expert, who already provided many (or almost all?) important insights in this and other related areas:

• Transaction responsibility
• Regeneration option best practices
• Asynchronous API calls and Idling
• AutoJoinElements
• Closing the active document and why not to
• Modeless door lister flaws
• Warning addendum on switching views
• External application attributes
• Extensible storage vendor id
• Modeless best practices
• Warning on using undocumented ElementId relationships

Arnošt also presented a class on the Idling event at Autodesk University 2011, CP5381, on asynchronous interactions and managing modeless UI, which would be well worth a blog post all on its own.

Arnošt clarifies that he is absolutely not against the Idling event, in general. The arguments below are only about using or not using Idling in one specific pattern – reacting to modifications of the model when both external well as internal data (in the model) could be changed in effect of the initial modification. In such situations he does not recommend utilizing the Idling event, because it does not support the pattern well.

There are, of course, situations where Idling is very much in place and some scenarios when it is quite necessary, such as interaction with modeless dialogues and multithreaded add-ins.

With that out of the way, here is an interesting conversation with a number of new important hints between Arnošt and Joe Offord of Enclos on the pros and cons of

• DMU, the dynamic model update mechanism,
• DCE, the DocumentChanged event, and
• IE, the Idling event.

Question: I have a process that is monitoring certain elements in a model via the DocumentChanged event. If I decide I need to perform a transaction on some of those elements I am storing the Document object via DocumentChangedEventArgs.GetDocument, along with some ElementIds, in a customized list that the Idling Event will process later. I then subscribe to the Idling Event.

When the Idling Event triggers I retrieve the same document object from my list and perform transactions with it.

Is this a safe way of transferring elements between the DocumentChanged and Idling Events? After attending Arnošt's class at AU I'm not 100% this transfer is "thread-safe". If this isn't safe what would be a better way to define document-specific tasks for the Idling event to process? I understand the DocumentChanged event does not me to make changes inside that event.

Answer: You present a design pattern that is not easy to solve or give a simple resolution for. First of all, we need to know whether your approach is correct.

We have two patterns for applications to react model changes:

1. DMU – used when model changes trigger other changes in the same model
   1. The document is modifiable, naturally
   2. The changes are all within the document (the actions as well as the reactions)
   3. You do not need to know about Undo and Redo because Revit handles it automatically
2. DocumentChanged – used when model changes trigger changes to external data
   1. The document is not modifiable
   2. The applied changes are made to external or non-model data
   3. You need to know about Undo and Redo, because Revit does not manage the external data

You seem to be merging those two patterns. As mentioned above, we need to determine whether this is necessary at all.

My recommendations and answers:

• I, personally, do not recommend the DocumentChanged + Idling event, because – quite simply, it is not what Idling is for.
• Is it a safe solution? Well, more appropriate question would be: Can it be implemented safely? The answer would be a yes; it can be implemented safely, but one needs to take into an account a lot of other things besides looking for DocumentChanged. When you have a gap between two calls into the API, you need to be aware of everything that can happen between those two times:
  • Document may be closed
  • Document may be saved, saved as, synced to central, reloaded latest, etc.
• Besides all those other things that may happen between two events, it is indeed safe to rely on data gathered during the last DocumentChanged until the next Idling, because it is guaranteed that no other change has been done to the model (except the work-sharing operations mentioned above). To be absolutely certain about elements, always use Unique Ids over regular Ids. Unique Ids are guaranteed to works across work-sharing operations, regular Ids are not.
• My preference is to do without the Idling event. I think that if I were challenged by the problem your customer is facing, I would try to implement it with DMU and DCh event only:
  • I would modify my external data on DCh even only
  • I would modify the model during DMU only
  • I would give a lot of thoughts to synchronize those two well

If I know more about the customer's project, I may be able to give more specific advices. Why do they need transactions if their tool is for is maintaining a live link between Revit elements and an external database, for example?

Response: Thank you for the feedback. Let me try and further explain the problem I'm facing.

In Revit, I'm using a specific generic annotation family to track and quantify my objects in the model. We have an external database that stores all their properties. The annotation family has custom instance text parameters. In the external database, instances are tracked by their name and their host View name. I do not want to go through reasons why we use an annotation symbol rather than modelling each object but I can assure you this is the most efficient method for us.

Via the API I've created an interface that allows the user to pick an object from the database and have it drawn on a Revit view as an AnnotationSymbol. The parameters are automatically filled out via the API. I then have a routine that counts up all the object AnnotationSymbol instances in a particular view and manually draws them in a schedule using lines and text (as a Group: this is required because Revit will not create Schedules from Generic Annotations). At the same time, all the instances of that object are uploaded to the external database.

Now, my goal is to have any changes to the model automatically sync with the external database. When a Document opens it collects all the existing annotation family instances and stores them in a global list using their ElementIds. I have setup the DocumentChanged event set to track whether new instances of the annotation family have been created or previous instances have been deleted (by comparing the deleted ids). I would prefer to track the elements via UniqueId but DocumentChanged only lists deleted elements via ElementId. If a change is flagged, I then subscribe to the IdlingEvent and store the Document HashCode and ElementId of the affected host View in global variables.

When IdlingEvent triggers I first verify the global variable of the Document is still open by comparing the stored HashCode with the open Document HashCodes. If I find a match, I then verify the ElementId is still a View element in the document. If both are ok I then collect all the family annotation instances in the view, verify their parameters match what the external database is showing, sync the elements with the external database, and redraw the schedule on the sheet.

Hopefully this is making some sense. To recap, I need to do the following:

1. Verify the parameters in the AnnotationSymbol specified match the properties set in the external database.
2. Verify additions and deletions of the AnnotationSymbol instances are tracked "live" with the external database.
3. Keep the report and schedule on each view current with number of AnnotationSymbols on the view.

I realize this cannot always maintain a truly fool-proof connection with the external database so I also have an External Command that basically does the same thing that the Idling Event does.

I welcome any suggestions to deal with unique problem.

Answer: I still think that the DMU+DCE combinations is a superior solution to using IE+DCE.

Here is how it should work:

• On DMU, look for added and deleted glass annotations. If there are any, sync with the database and update the schedule in the model as needed
• On DCE, only do something if the operation was Undone, or Redone, or GroupRolledBack. Ignore the other operations. When there is a change in added or deleted glass annotations, update the database but do not change the model (because it is being taken care of automatically by Revit)
• There will be no need for having global variables storing the document and/or view

Like I said, the IE+DCE can be used, in theory, but:

• It is less natural an implementation and more complex too
• There is a lot more the application needs to look for
  • There is no guarantee Idling would be raised after DCE and before a document is saved or closed
  • Therefore subscribing to DocumentSaving, DocumentSavingAs and DocumentClosing
  • Event with those additional events it is not guaranteed a document would be always in sync with the external database when it is saved
• It is much less efficient, especially with a lot of undos and redos, because the external application must do what Revit would have otherwise done automatically and far more efficiently.
• The Idling event, though it looks like a viable solution in many cases, it is a good approach in a few specific scenarios, mostly involving modeless dialogues and work threads. Beside these very specific scenarios, there is always a better way – more efficient, more practical, and easier too.

Again, the rule for this and similar patterns is rather simple:

1. If you need to react to a changes in a model by making other changes to it, use DMU
2. If you need to react to changes in a model by making changes in an external database, use DCE
3. If you need both, you use both DMU and DCE, but you still follow the above tactic

Response: Although I really like the intent of DMU, I still see some major limitations of it in 2012:

1. Inability to create new transactions inside the DMU
2. Inability to create group elements inside the DMU
3. DMU does not get called for rolled-backed or redone transactions (check me on this one)

Because of these limitations, I ended up using the (DCE+DMU)+IE for optimum performance. The DCE and DMU events tracked changes to the model and called upon the IE when required. The DCE tracks changes to AnnotationSymbols and DMU tracks changes to a specific View parameter. The IE provided me the ultimate freedom to create transactions as I wish. I understand there is a risk for things to change after DCE and before the IE. Although the window for change is small, each programmer should decide how they want to deal with that risk.

Answer: I beg to disagree about the notion of DMU 'limitations'. Those listed above are not limitations, since DMU was designed exactly that way. No one is supposed to need a transaction and/or group inside a DMU, unless DMU is misused. Also, DMU does not need to be called at the event of Undo and Redo – if someone appears to need it, that someone does not use DMU correctly or is not clear on what the purpose of DMU is. I can only repeat what I wrote previously:

DMU – is for changes to the model in effect of other changes in the same model. All the changes will be and should be inside one transaction, because they are – obviously – related, which also mean that if one change is undone, the other (initial) changes need to be undone too. In another way – DMU is an extension of Revits regeneration, the last regeneration that always happens at the end of every transaction.

DCE – is for changes to external data reacting to modifications to the model. No transactions are needed here and the model is not supposed to be touched.

I agree that IE gives the ultimate freedom; I disagree that the freedom should be utilized in this particular case, but I also made it clear that it was 'I' who would not use IE if 'I' was the one solving this particular problem. I do not want to tell users what they have to do – they should have the freedom to do whatever they desire. I just provide an explanation for why one solution is more favourable than the other. IE has very limited use when it is efficient and useful – beyond that recommended use it becomes not so efficient and troublesome to maintain.

Extraneous Undo Entries

There is one more thing I do not 'like' about the Idling event, or – more precisely – about transactions created in the Idling event handler, when it is used outside of the recommended patterns (modeless dialogue, work threading, etc.). The transaction may come as a surprise to the unaware end user. The user pauses for a while, maybe leave her desk to get a cup of coffee, and when she returns there may be three new transactions on the undo stack. If I was her, I would most likely not like it. In contrast to that, changes made during DMU are expected – they are part of the action that is currently going on. There may not be transactions during DCE, so no surprises there. And if Idling is used to implement commands in a modeless dialogue, the user would not be surprised by an eventual transaction. In API programming it is not always about what way appears to be helpful to the programmer – it is about the end user. Revit addition should be made to best follow the natural flow of things. At least in my opinion.

Response: Yes I agree IE isn't the prettiest solution to most problems. The "mystery" transaction(s) created by the IE do affect the natural flow of the program. I tried my utmost to keep the IE duration as minimal as possible. I also took particular care to ensure I only created one transaction during the IE update. I'm sure the user would be shocked to see multiple phantom transactions created repeatedly.

My earlier use of the word "limitation" with regards to the DMU was probably misguided. For my particular work-flow, in my opinion, the DMU was simply not versatile enough. I needed to create groups on the fly and this is simply not permitted inside the DMU. I forgot to mention I also tried creating new families (in place of the groups) and load them into the project during the DMU but again, this is not permitted. I think this was the only thing that prevented me from using DMU+DCE without the IE.

Answer: Regarding your statement "only created one transaction during the IE update. I'm sure the user would be shocked to see multiple phantom transactions created repeatedly":

I did not even mean that one application would create multiple transactions in one single Idling event. But if more add-ins were written this way, and if the users happened to have, say 10 of them, there may be 10 or more transactions during one Idling, and a lot more in one coffee break (with Revit left unattended). It is because one change could lead to another (in a different add-in), which may lead back and trigger yet another change or changes in the original add-in, and so on. Everything would be tied together so tightly so it could be quite a mystery to the end user to figure the course of changes. And when the user decided to undo just some of the involuntary transactions and if the synchronization between Idling and DCE in the individual add-ins is not written perfectly and robust, the hell may as well open for the user (and her document) ;-) I am kidding, of course, but the fact remains that such situations happen in the real world and it is very hard to maintain. That is why I always recommend keeping transaction short and the changes atomic. Splitting one change into one-transaction-now and another transaction-later is almost always opening the door for troubles.

Again, this is my recommendation only.

Response: I think we all prefer Revit not open a gateway to hell but it's nice to know it has that much power! :)

Lock the Model, e.g. Prevent Deletion

I recently discussed two common and interesting issues with developers which ended up being easily resolved:

• Locking the state of certain programmatically generated parts of the model to prevent the user from messing them up.
• Simpler still, prevent deletion of certain elements.

Both of these issues can be efficiently addressed using the Failure API. It allows us to

• Define our own failure conditions.
• Post pre-defined or custom failures.
• Handle failures, e.g. suppress unwanted messages or completely replace the standard failure processing.

The Revit SDK includes the ErrorHandling sample to demonstrate all of these features, and we later returned to this topic to discuss various failure API aspects in more depth.

So here is the first query that came up:

Lock Down Part of the Model

Question: I am creating certain AssemblyInstance elements in the model programmatically and would like to prevent the user from being able to modify these.

How can I use the API to lock these elements?

It should be impossible to disassemble them and edit or remove elements. How can I achieve this?

Answer: This can be achieved using the Failure API. Section 26.1.1 'Defining and registering a failure' in the developer guide shows how you can define a new failure. If you maintain a cache keeping track of the original state of all your assembly instances, you can define a failure that is triggered when anything is changed in any assembly instance.

The failure API is linked with the Dynamic Model Update framework DMU.

The simpler DocumentChanged event is not cancellable, unfortunately, or you could simply use that.

Below, I demonstrate the detailed implementation steps for the simpler task of simply preventing deletion of certain elements, which does not require keeping track of their previous state.

Prevent Deletion of Elements

Question: How do I prevent the deletion of an element? I tried to use DocumentChanged and IUpdater, but both of those seem to be "after the fact" type interfaces.

Answer: As said, DocumentChanged is indeed after the fact.

The IUpdater is on the right track. It is part of the Dynamic Model Update framework DMU and ties in with the failure API, which enables you to easily achieve what you need.

To prove it, I implemented a small sample application PreventDeletion. It implements three things:

• An external command allowing the user to specify which elements to protect from deletion.
• A class DeletionUpdater derived from IUpdater which prevents deletion of selected elements.
• An external application to register the updater and its trigger.

All three components are extremely simple. Let's start with the external command. It maintains a list of protected element ids and implements an externally accessible IsProtected method:

  static List<ElementId> _protectedIds 
    = new List<ElementId>();
 
  static public bool IsProtected( ElementId id )
  {
    return _protectedIds.Contains( id );
  }

The command itself asks the user to select elements to protect and adds their ids to the list:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
 
  IList<Reference> refs = null;
 
  try
  {
    Selection sel = uidoc.Selection;
 
    refs = sel.PickObjects( ObjectType.Element, 
      "Please pick elements to prevent from deletion. " );
  }
  catch( OperationCanceledException )
  {
    return Result.Cancelled;
  }
 
  if( null != refs && 0 < refs.Count )
  {
    foreach( Reference r in refs )
    {
      ElementId id = r.ElementId;
 
      if( !_protectedIds.Contains( id ) )
      {
        _protectedIds.Add( id );
      }
    }
    int n = refs.Count;
 
    TaskDialog.Show( Caption, string.Format(
      "{0} new element{1} selected and protected "
      + " from deletion, {2} in total.",
      n, ( 1 == n ? "" : "s" ), 
      _protectedIds.Count ) );
  }
  return Result.Succeeded;
}

The deletion updater is just as simple. The only tricky thing about it is that it defines a custom failure definition in its constructor. The severity of the failure is specified as error, so the user really cannot ignore it, which will prevent the elements from being deleted. Whatever action that caused the deletion will have to be undone:

public DeletionUpdater( AddInId addInId )
{
  _appId = addInId;
 
  _updaterId = new UpdaterId( _appId, new Guid( 
    "6f453eba-4b9a-40df-b637-eb72a9ebf008" ) );
 
  _failureId = new FailureDefinitionId(
    new Guid( "33ba8315-e031-493f-af92-4f417b6ccf70" ) );
 
  FailureDefinition failureDefinition
    = FailureDefinition.CreateFailureDefinition(
      _failureId, FailureSeverity.Error,
      "PreventDeletion: sorry, this element cannot be deleted." );
}

The updater Execute method simply checks whether any of the deleted element ids are protected from deletion and posts the failure if that is the case:

public void Execute( UpdaterData data )
{
  Document doc = data.GetDocument();
  Application app = doc.Application;
  foreach( ElementId id in data.GetDeletedElementIds() )
  {
    if( Command.IsProtected( id ) )
    {
      FailureMessage failureMessage 
        = new FailureMessage( _failureId );
 
      failureMessage.SetFailingElement(id);
      doc.PostFailure(failureMessage);
    }
  }
}

In the external application, all we have to do is register the updater and its trigger in the start-up method:

public Result OnStartup( UIControlledApplication a )
{
  DeletionUpdater deletionUpdater 
    = new DeletionUpdater( a.ActiveAddInId );
 
  UpdaterRegistry.RegisterUpdater( 
    deletionUpdater );
 
  ElementClassFilter filter 
    = new ElementClassFilter( 
      typeof( Wall ) );
 
  UpdaterRegistry.AddTrigger( 
    deletionUpdater.GetUpdaterId(), filter, 
    Element.GetChangeTypeElementDeletion() );
 
  return Result.Succeeded;
}

If I specify that an element is protected from deletion using the command above and then try to delete it anyway, the standard Revit error message is displayed:

If this message should not be seen by the user, you can easily use the failure handling functionality mentioned above to suppress it.

Here is PreventDeletion.zip including the complete source code and Visual Studio solution of this command.

Finally, my first personal use of the failure API :-)

Entry Points to Point Clouds in Revit

Here is a short note on a non-API-related issue, an overview of some introductory material on point clouds in Revit from a user point of view:

Question: I am interested in retrofit projects and would like to understand better what I can do in Revit using point clouds. Where should I start, please?

Answer: Here are a couple of starting points for you:

• There are videos on the AutodeskBuilding youtube channel, where the overview video is probably the best place to start.
• An interesting web site to look at is eBIM, of a company in the UK that built an entire business model around as-built BIM authoring in Revit.
• The very nice data set to understand the point cloud integration is provided by the Revit model and point cloud of the 210 King office in Toronto.

Structural Dynamic Model Update Sample

I am away again on the next leg of my extensive vacations this summer, travelling a bit further afield this time. After one night in a plane and another night in a bus I find myself on the island of Ko Tao in Thailand, where I completed my first open sea water dive in the Japanese Garden with Boris of Alvaro Diving.

Since I will be away for the whole month of August, I decided to take the computer with me this time. I have a couple of interesting questions lined up that I have been wanting to discuss for quite a while now, and hope to finally get around to doing that now.

Here is the first one, a neat sample of using the dynamic model update features in the context of Revit Structure created by and presented at the recent AEC DevCamp in Boston by Saikat Bhattacharya.

It causes all concrete beam rebars in the model to automatically resize every time the beam geometry changes.

Here is Saikat's description:

Dynamic Model Update Sample in the Structural Context

This sample was written to illustrate one of the many possible uses of the new platform API feature called Dynamic Model Update (DMU) in a Structural context in Revit Structure. For more on the basics of on DMU and how to use this new mechanism, we can refer to the chapter 25 (page 283) of the Revit API Developers Guide PDF document located in the SDK. It causes concrete beam rebars (included in the attached project) to automatically resize every time the beam geometry changes.

This sample creates a new ribbon in the Analyze tab with two radio group button which can be used to enable the alignment functionality in the sample to be active or not. If the alignment option is on (or active), every resize of the beam in the model resizes the rebars in the beam to perfectly align it between the two opposite faces of the beam.

This sample uses the IExternalApplication’s OnStartup event to create a ribbon with two radio buttons on the Analyze tab. It also registers the updater class and adds triggers to it. The trigger is set to work with implicit set of elements which are of Structural Framing category (beams) which is specified using an ElementCategoryFilter and is set to work with change of scope, specifically change in Geometry of the elements (beams).

The sample implements two external commands called UIDynamicModelUpdateOn and UIDynamicModelUpdateOff which are executed when users click on the radio group buttons in the ribbon panel in the analyze tab. These commands internally just set a local variable which stores whether the alignment of the rebars functionality is activated or not.

The sample also contains an Updater class called RebarUpdater which implements the IUpdater interface. This interface requires implementing certain methods to return the updater Id, updater name, additional (auxiliary) information and the execute method which gets informed of the change of scope (geometry) of the elements (beams). This Execute method is called when there is a change of geometry of the beam in the given set up in RebarUpdater class. In this Execute method, the code gets access to all the modified beams using the data.GetModifiedElementIds and then iterates through each beam. It uses the new element iteration API to create a collection of all the rebars and calculates the beam line of each beam. This beam line helps provide the start and end point of the beam which is the extent to which the rebars would be stretched or compressed to. Following this, the sample moves the rebar to one end of the beam using the doc.Move method and passing in a translational vector which is based on the beam and rebar start points. After the rebar has been moved, the beam line needs to be recalculated again and using the length from the beam line, we can set the corresponding length parameter of the rebar to get it in sync with the new length of the beam. In the included RVT file, the rebar parameter *B* refers to the length of the rebar which is used to set the new length.

The intention of the sample is to show how the new Dynamic Model Update API can be used in a structural context inside Revit Structure. This sample assumes you are using only one beam which has single or multiple rebars contained in it and needs to be extensively tested and modified to work with broader types of beams and rebars.

Here is the entire code:

[Transaction( TransactionMode.Automatic )]
[Regeneration( RegenerationOption.Manual )]
public class AlignRebar : IExternalApplication
{
  /// <summary>
  /// On shutdown, unregister the updater
  /// </summary>
  public Result OnShutdown( UIControlledApplication a )
  {
    RebarUpdater updater
      = new RebarUpdater( a.ActiveAddInId );
 
    UpdaterRegistry.UnregisterUpdater(
      updater.GetUpdaterId() );
 
    return Result.Succeeded;
  }
 
  /// <summary>
  /// On start up, add UI buttons, register 
  /// the updater and add triggers
  /// </summary>
  public Result OnStartup( UIControlledApplication a )
  {
    // Add the UI buttons on start up
    AddButtons( a );
 
    RebarUpdater updater = new RebarUpdater(
      a.ActiveAddInId );
 
    // Register the updater in the singleton 
    // UpdateRegistry class
    UpdaterRegistry.RegisterUpdater( updater );
 
    // Set the filter; in this case we 
    // shall work with beams specifically
    ElementCategoryFilter filter
      = new ElementCategoryFilter(
        BuiltInCategory.OST_StructuralFraming );
 
    // Add trigger 
    UpdaterRegistry.AddTrigger(
      updater.GetUpdaterId(), filter,
      Element.GetChangeTypeGeometry() );
 
    return Result.Succeeded;
  }
 
  /// <summary>
  /// Add UI buttons
  /// </summary>
  public void AddButtons( UIControlledApplication a )
  {
    // create a ribbon panel on the Analyze tab
    RibbonPanel panel = a.CreateRibbonPanel(
      Tab.Analyze, "RST Labs" );
 
    AddDmuCommandButtons( panel );
  }
 
 
  /// <summary>
  /// Control buttons for the Dynamic Model Update 
  /// </summary>
  public void AddDmuCommandButtons(
    RibbonPanel panel )
  {
    string path = GetType().Assembly.Location;
 
    string sDirectory
      = System.IO.Path.GetDirectoryName( path );
 
    // create toggle buttons for radio button group 
 
    ToggleButtonData toggleButtonData3 
      = new ToggleButtonData( 
        "RSTLabsDMUOff", "Align Off", path, 
        "RstAvfDmu.UIDynamicModelUpdateOff" );
 
    toggleButtonData3.LargeImage 
      = new BitmapImage( new Uri( sDirectory 
        + "\\Images\\" + "Families.ico" ) );
 
    ToggleButtonData toggleButtonData4 
      = new ToggleButtonData( 
        "RSTLabsDMUOn", "Align On", path, 
        "RstAvfDmu.UIDynamicModelUpdateOn" );
 
    toggleButtonData4.LargeImage 
      = new BitmapImage( new Uri( sDirectory 
        + "\\Images\\" + "Families.ico" ) );
 
    // make dyn update on/off radio button group 
 
    RadioButtonGroupData radioBtnGroupData2 = 
      new RadioButtonGroupData( "RebarAlign" );
 
    RadioButtonGroup radioBtnGroup2 
      = panel.AddItem( radioBtnGroupData2 ) 
        as RadioButtonGroup;
 
    radioBtnGroup2.AddItem( toggleButtonData3 );
    radioBtnGroup2.AddItem( toggleButtonData4 );
  }
}
 
public class RebarUpdater : IUpdater
{
  public static bool m_updateActive = false;
  AddInId addinID = null;
  UpdaterId updaterID = null;
 
  public RebarUpdater( AddInId id )
  {
    addinID = id;
    // UpdaterId that is used to register and 
    // unregister updaters and triggers
    updaterID = new UpdaterId( addinID, new Guid( 
      "63CDBB88-5CC4-4ac3-AD24-52DD435AAB25" ) );
  }
 
  /// <summary>
  /// Align rebar to updated beam 
  /// </summary>
  public void Execute( UpdaterData data )
  {
    if( m_updateActive == false ) { return; }
 
    // Get access to document object
    Document doc = data.GetDocument();
 
    try
    {
      // Loop through all the modified elements
      foreach( ElementId id in 
        data.GetModifiedElementIds() )
      {
        FamilyInstance beam = doc.get_Element( id ) 
          as FamilyInstance;
 
        // Create a filter to retrieve all rebars
        FilteredElementCollector rebars 
          = new FilteredElementCollector( doc );
 
        rebars.OfCategory( BuiltInCategory.OST_Rebar );
        rebars.OfClass( typeof( Rebar ) );
 
        foreach( Rebar rebar in rebars )
        {
          // Calculate the beam line
          XYZ beamStartPoint = new XYZ();
          XYZ beamEndPoint = new XYZ();
          Line line = CalculateBeamLine( beam );
 
          // Get the start and end point 
          if( null != line )
          {
            beamStartPoint = line.get_EndPoint( 0 );
            beamEndPoint = line.get_EndPoint( 1 );
          }
 
          // To align the rebar to the new beam's 
          // length, we split the tasks in two stages
          // Step 1: Move the rebar to align with one 
          // of the end of the beam
 
          // For this we first access the 
          // rebar line geometry
          Line rebarLine = rebar.Curves.get_Item( 0 ) 
            as Line;
 
          // Calculate the translation vector 
          // (the extent of the move)
          XYZ transVec = new XYZ( beamStartPoint.X 
            - rebarLine.get_EndPoint( 0 ).X, 0.0, 0.0 );
 
          // Perform the move 
          doc.Move( rebar, transVec );
 
          // This move causes the beam line to change 
          // and so recalculating the beam line
          line = CalculateBeamLine( beam );
 
          // Step 2: Set the new length of the rebar 
          // based on new beam length. For this, we 
          // can set the relevant parameter after 
          // checking at UI
          rebar.get_Parameter( "B" ).Set( 
            GetLength( line ) );
        }
      }
    }
    catch( Exception ex )
    {
      TaskDialog.Show( "Exception", ex.Message );
    }
  }
 
  // Calculate the beam line 
  private Line CalculateBeamLine( 
    FamilyInstance beam )
  {
    GeometryElement geoElement 
      = beam.get_Geometry( new Options() );
 
    if( null == geoElement 
      || 0 == geoElement.Objects.Size )
    {
      throw new Exception( 
        "Can't get the geometry of selected element." );
    }
 
    Line beamLine = null;
 
    foreach( GeometryObject geoObject 
      in geoElement.Objects )
    {
      // get the driving path and vector of the beam 
      beamLine = geoObject as Line;
 
      if( null != beamLine )
      {
        return beamLine;
      }
    }
    return null;
  }
 
  /// <summary>
  /// Return the length of the given line
  /// </summary>
  public static double GetLength( Line line )
  {
    XYZ v = line.get_EndPoint( 1 ) - line.get_EndPoint( 0 );
    return v.GetLength();
  }
 
  /// <summary>
  /// Return the auxiliary string
  /// </summary>
  public string GetAdditionalInformation()
  {
    return "Automatically align rebar to match beam";
  }
 
  /// <summary>
  /// Set the priority
  /// </summary>
  public ChangePriority GetChangePriority()
  {
    return ChangePriority.Rebar;
  }
 
  /// <summary>
  /// Return the updater Id
  /// </summary>
  public UpdaterId GetUpdaterId()
  {
    return updaterID;
  }
 
  /// <summary>
  /// Return the updater name
  /// </summary>
  public string GetUpdaterName()
  {
    return "Rebar alignment updater";
  }
}
 
[Transaction( TransactionMode.ReadOnly )]
[Regeneration( RegenerationOption.Manual )]
public class UIDynamicModelUpdateOff : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    RebarUpdater.m_updateActive = false;
    return Result.Succeeded;
  }
}
 
[Transaction( TransactionMode.ReadOnly )]
[Regeneration( RegenerationOption.Manual )]
public class UIDynamicModelUpdateOn : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    RebarUpdater.m_updateActive = true;
    return Result.Succeeded;
  }
}

The sample model included with the application includes two point loads, a rectangular concrete beam, and a rebar. Here are the selected point loads:

This is the beam itself:

These are the rebar elements:

On selecting and dragging the beam around, the add-in automatically updates the rebar to follow it:

Here is RstAvfDmu.zip including the complete source code and Visual Studio solution for this sample.

This solution actually includes another additional sample, which demonstrates a use of the analysis visualisation framework in a structural context, to simulate a visual display a load distribution. We might get around to presenting that in detail as well one of these days, or you can just go ahead and explore it for yourself.

Element Level Events

From my point of view, one of the most important enhancements to the Revit API is the availability of element level events. This allows an application to react to modifications to the database, including tracking changes to individual elements. The Revit 2011 API provides not just one but two separate mechanisms to subscribe to element level notification events:

• Elements changed event
• Dynamic model update

Elements Changed Event

The new Application.DocumentChanged event is raised after every transaction is committed, undone, or redone. This is a read-only event, designed to allow an application to keep external data synchronised with the Revit database state. To update the Revit database in response to changes in elements, use the Dynamic Model Update framework described below.

The event handler receives a DocumentChangedEventArgs instance as an input argument which provides information on the operation performed and the document and elements involved. Some of its most important properties and methods are therefore the following:

• Operation: the operation associated with this event.
• GetDocument: the document associated with this event.
• GetAddedElementIds: the set of elements newly added to the document.
• GetDeletedElementIds: the set of elements that were deleted.
• GetModifiedElementIds: the set of elements that were modified.
• GetTransactionNames: the names of the transactions associated with this event.

ChangesMonitor SDK Sample

The use of the elements changed event is demonstrated by the ChangesMonitor Revit SDK sample. It implements a data table to log all the changes made to the database, and a modeless dialogue ChangesInformationForm to display its contents. The main modules of the sample project are ChangesMoniotor.cs and ChangesInfoForm.cs:

• ChangesMoniotor.cs: This file contains a class ExternalApplication which implements the IExternalApplication interface and the sample entry point. It creates a modeless dialog to track the changed elements' information. This file also defines an external command class Command which inherits from the IExternalCommmand interface. Its function is to redisplay the information dialogue if it has been closed.
• ChangesInfoForm.cs: This file defines a ChangesInformationForm form class which displays the changed element information in a DataGridView in a modeless dialogue. The information includes the change type (Added, Deleted, and Modified), and the modified element id, name, category name, and document owning it.

The external application initialises these components and registers to the Application.DocumentChanged event in its OnStartup method like this:

public Result OnStartup(
  UIControlledApplication application )
{
  // initialize member variables.
 
  m_CtrlApp = application.ControlledApplication;
  m_ChangesInfoTable = CreateChangeInfoTable();
 
  m_InfoForm = new ChangesInformationForm( 
    ChangesInfoTable );
 
  // register the DocumentChanged event
 
  m_CtrlApp.DocumentChanged += new EventHandler<
    Autodesk.Revit.DB.Events.DocumentChangedEventArgs>( 
    CtrlApp_DocumentChanged );
 
  // show dialog
 
  m_InfoForm.Show();
 
  return Result.Succeeded;
}

Here is an example of the information that it collects and presents:

ChangesMonitor also implements an external command to redisplay the modeless dialogue, in case you closed it and want to reopen it again. By default, it is opened automatically on start-up.

Dynamic Model Update

As mentioned above, the Application.DocumentChanged event is a read-only event, so it does not support modifications to the Revit database as a reaction to the changes that triggered it. For that, you can make use of the much more powerful dynamic model update mechanism. This is what the What's New section in the Revit API help file has to say about the dynamic model update:

Dynamic model update offers the ability for a Revit API application to modify the Revit model as a reaction to changes happening in the model. This facility is offered through implementation of updaters. The updater interface offers the ability to implement a method that is informed of the scope of changes that triggered the update.

In order to 'subscribe' an updater to the right set of changes, the updater should be assigned one or more update triggers. Update triggers are combinations of 'Change Scope' and 'Change Type'. Change Scope may be either an explicit list of element ids in a document, or an implicit list of elements communicated via an ElementFilter. Change Type represents one of an available list of possible changes, including element addition, deletion, and modification of geometry, parameters, or any property of the element.

More detailed information on the dynamic model update capabilities are provided in the Developer Guide chapter 25.

One important thing to note is that this facility allows the application to perform its changes to react to the notification within the same transaction as the one that triggered the changes.

Since many different updaters may try to modify things which will trigger new updaters, the execution sequence is important. A facility for defining your execution priority is included in the system.

The use of the dynamic model update is demonstrated by two different SDK samples, DynamicModelUpdate and DistanceToSurfaces. The latter also demonstrates the new analysis visualization framework and is therefore located in the AnalysisVisualizationFramework subfolder. Both of these are implemented as external applications which set up their updater and trigger during the OnStartup or DocumentOpened events.

DynamicModelUpdate SDK Sample

The use of the dynamic model update is demonstrated by the DynamicModelUpdate Revit SDK sample. It is also implemented as an external application and designed to work in a specific included sample model AssociativeSection.rvt. It shows how you can use this mechanism to maintain the relative position between elements, in this case a window located in a wall and a section view positioned to display the cut through the window and the wall. This sample uses the hard-coded element id of the section view marker to update its position:

Here is the result of the section view displaying the window in the wall:

These are the detailed steps of the sample implementation:

1. During Revit start-up:
   1. Register the SectionUpdater class.
   2. Add a trigger so that the SectionUpdater class will be invoked for any geometry change to a window.
2. When the geometry of a window changes:
   1. Move the section marker (using the hard-coded element id for the sample model) to a new location based on the distance that the window moved in the X, Y, and Z directions, which are stored as parameters in the window family.
   2. Update the values of the window's X, Y, and Z parameters based on the location point of the window.

If the window is moved, the section view is updated to move with it, so that it continues to display the correct cut. Obviously, if the wall moves, the window will move with it, too, and that will again update the section location.

DistanceToSurfaces SDK Sample

The use of the dynamic model update is also demonstrated by the DistanceToSurfaces SDK sample, although it is primarily intended to highlight the new analysis visualization framework, which allows an application to display analysis results graphically by painting the surfaces of Revit elements. Once again, it is written to work in a specific sample model. The model includes a sphere object represented by a family instance, i.e. an insertion of the sphere.rfa family. It calculates and displays the distance from the sphere to all surfaces of all walls and mass elements in the model.

On start-up, the external application registers a DocumentOpened event handler. This in turn creates a trigger that will execute when walls, masses, and family instances in the project change. When this occurs, the application calculates the distance from the sphere to several points on each face. These distances are used as values for the analysis visualization display. Here are the individual steps in more detail:

1. On start-up, register a DocumentOpened event. When a document is opened:
   1. Check for the presence of the sphere family.
   2. Check for the presence of a 3D view named 'AVF'.
   3. Create a GetChangeTypeGeometry trigger that will activate when a wall, mass, or family instance changes.
2. When this trigger occurs:
   1. Find the XYZ location of the sphere.
   2. Get the existing spatial field manager object, or create one if one does not already exist.
   3. Create a face array containing every face of a wall or mass in the project, including in-place geometry.
   4. Calculate the distance between the sphere's origin and several points on each face.
   5. Display these distances as analysis results on the faces by updating the spatial field primitive.

This is what the initial DistanceToSurfaces.rvt sample model looks like:

If any one of the relevant elements is moved, the trigger reacts and the updater is called, which uses a filter to retrieve all walls and mass elements and the SpatialFieldManager to paint their faces depending on the distance to the sphere element:

Using Manage > Additional Settings > Analysis Display Styles, the analysis result colour mapping can either be set up to use ranges, as shown above, or a smooth gradient like this:

Developers have been clamouring for element level events ever since the first events were introduced in the Revit API, and even more so when the events were enhanced for the Revit 2010 API. In previous releases, only application and document level events were available. It will be very exciting to see what powerful new applications can be created to make use of this!