The Building Coder

Transactions, Sub-Transactions and Transaction Groups

Here is a recent query from a developer that led to a nice succinct overview of transactions, sub-transactions and transaction groups by Arnošt Löbel.

This makes a change from the recent rash of monster posts. The last ten posts were all rather overwhelming in size, and hopefully impressive in content as well. From Aril 16 until 29, I posted a total of 26228 words, 245504 bytes.

So let's keep this one short, sweet and to the point.

Question: When should I use a transaction group with transactions versus transaction with sub-transactions?

At first glance, it looks as if both can achieve the same result, but there must be some kind of difference, mustn't there?

Answer: This question is actually covered at large in the API documentation for the respective classes. Of course, you could write a whole book about the detailed usage of transaction phases (i.e. Transaction, Transaction groups, Sub-Transaction), if you wanted to, but the documentation already covers all the really necessary information.

Here is a brief summary:

• A transaction is a phase that is needed to make modifications to a model. A transaction is undoable. Once committed, it appears on the undo/redo menu, where the end user can make it undone or later redone. Transactions cannot be nested, for only one client can modify the model at any given time.
• A sub-transaction marks a phase within an open transaction. It is to control (if a control is needed) a set of modifications done in a transaction, meaning that the modification enclosed in a sub-transaction can be rolled back as if they have not happened. In a sense, it allows an application to go back to a certain point (the start of the sub-transaction) in a sequence of model changes. Sub-transactions can be nested. A sub-transaction cannot be undone/redone once committed.
• A transaction group can control a set of transactions in the sense that even transaction that have already been successfully submitted can be rolled back if they were committed while inside an open transaction group. This give an application a way of undoing past transaction if some other transactions later (but still within the group) do not go as well as expected. For example, if three transactions are required (for whatever reason) to achieve something, and it is necessary to commit all three for the changes to make sense, the transactions could be controlled by a group. If the second or the third transaction fails, the whole group can be rolled back. Transaction groups can be nested, but they cannot be undone/redone, i.e. there is no trace of them in the undo/redo menu for the end user to see.

The temporary transaction trick touch-up describes a scenario using a transaction group to enable a transaction to be committed, so the model is updated and the new state can be queried, and still enabling the whole action can be undone afterwards.

For more information on the transaction framework, please refer to Arnošt's Autodesk University presentation CP3426 Core Frameworks in the Revit API.

Response: Thank you! I use the temporary transaction trick quite a lot, so I'll definitely start using transaction groups now as well.

Export Wall Parts Individually to DXF

I am back from my vacation. It was a wonderful break, and I feel ready and happy to get back to grips with everyday life and work again.

A query from a colleague caught up with me already on the way back, on exporting a whole bunch of selected wall panel parts to individual DXF files. That gave me something nice and interesting to fiddle with during the nightly train ride up from Napoli to Milano and led to the following issues:

• Exporting individual compound wall gyp wallboard parts
• Handling and dismissing a warning message
• Adding support for both pre- and post- part selection
• Handling temporary transactions and regeneration

Before getting to that, though, here are a few final notes on my last vacation day in Napoli.

Last Day in Napoli

I had some wonderful pastry in the Gran Bar Riviera pasticceria on the Riviera di Chiaia. Incidentally, an old palazzo partially collapsed there last week, just a few hundred meters away from where I was staying.

Further, I took a pair of old shoes to Gabriele, an extremely sweet and happy 86 years old shoemaker in the Spanish quarter. He repaired them and they look better than new now. He also invited us to coffee and told me his life story. If you ever need a pair of shoes fixed, be sure to look him up in Vico Lungo del Gelso, 108, I-80134 Napoli :-)

Two final parting pictures capturing some of the decrepit charm of Naples...

Anyway, now I am back at work now again, and we return to the Revit API and my nocturnal dabbling on the train.

Exporting Individual Compound Wall Gyp Wallboard Parts

This query came in from my colleague William Spier, MEP & Design to Fabrication SME at Autodesk (YouTube, Revit Family Jewels). He says:

Question: I would like to customise two pretty easy things.

The scenario is a compound wall on which I divide the gyp wallboard into standard (4’x8’) sheet size parts. I need to export each of those sheets/parts to DXF format, but even though I have divided them into parts, Revit still groups them and exports them as one single DXF file – not as separate ones, like I need. The only way around this is to isolate each part one at a time and export each one individually, which is WAY too laborious.

So I need to customize the export process so that:

1. Each part exports as a separate part, even though I globally selected them.
2. Each part exports named by its own unique code/identifier – whatever coding keeps each one distinct in the parts schedule.

Here is a snapshot from a simple sample project:

Answer: A first search for related API methods turn up the following potentially useful items:

• Document.Export( string, string, ICollection<ElementId>, DXFExportOptions )
• View.IsolateElementTemporary( ElementId )
• Part.ParentDividedElementId property (obsolete)
• Part.GetSourceElementOriginalCategoryIds method (obsolete)
• Part.GetSourceElementIds method

Skipping the obsolete ones, it turns out to be really easy to implement a first working version that I packaged in an external command named ExportWallboard.

I first check that a valid document is provided and a 3D view is active that we can use for isolating and exporting each part:

  if( null == doc )
  {
    ErrorMsg( "Please run this command in a valid"
      + " Revit project document." );
    return Result.Failed;
  }
 
  View view = doc.ActiveView;
 
  if( null == view || !( view is View3D ) )
  {
    ErrorMsg( "Please run this command in a valid"
      + " 3D view." );
    return Result.Failed;
  }
 
  // Define the list of views to export, 
  // including only the current 3D view
 
  List<ElementId> viewIds = new List<ElementId>( 1 );
  viewIds.Add( view.Id );

Basically, all that is required is to follow the steps suggested above:

• Isolate each part
• Define the DXF filename
• Call the export method

  Element e = doc.GetElement( id );
 
  Debug.Assert( e is Part,
    "expected parts only" );
 
  Part part = e as Part;
 
  ICollection<LinkElementId> lids
    = part.GetSourceElementIds();
 
  Debug.Assert( 1 == lids.Count,
    "unexpected multiple part source elements." );
 
  LinkElementId lid = lids.First<LinkElementId>();
  ElementId hostId = lid.HostElementId;
  ElementId linkedId = lid.LinkedElementId;
  ElementId parentId = hostId;
  ElementId partId = e.Id;
 
  filename = string.Format( "{0}_{1}",
    parentId, partId );
 
  view.IsolateElementTemporary( partId );
 
  doc.Export( _folder, filename, viewIds, opt );

The IsolateElementTemporary method requires a transaction, so even though the whole operation is theoretically read-only, we still need to specify manual transaction mode for this command. We encapsulate the isolate and export method in a transaction that is later rolled back, so the model ends up unchanged after all.

Handling and Dismissing a Warning Message

However, a complication arises:

Calling the Export method with an isolated element in the current view displays a task dialogue warning message:

I repeatedly discussed how to automatically handle messages like this in the past, e.g. to detach a workset.

To be notified of this message, we subscribe to the DialogShowing event:

  uiapp.DialogBoxShowing
    += new EventHandler<DialogBoxShowingEventArgs>(
      OnDialogBoxShowing );

Do not forget to unsubscribe afterwards. In this case, we can do so at the end of the command.

To ensure that the unsubscription is performed whatever happens, regardless of any potential errors, I encapsulate the whole operation in a try statement and unsubscribe in its 'finally' clause.

  try
  {
    // Register event handler for 
    // "TaskDialog_Really_Print_Or_Export_Temp_View_Modes" 
    // dialogue
 
    uiapp.DialogBoxShowing
      += new EventHandler<DialogBoxShowingEventArgs>(
        OnDialogBoxShowing );
 
    DXFExportOptions opt = new DXFExportOptions();
 
    string filename;
 
    using( Transaction tx = new Transaction( doc ) )
    {
      tx.Start( "Transaction Name" );
 
      foreach( ElementId id in ids )
      {
        Element e = doc.GetElement( id );
 
        // . . .
 
        view.IsolateElementTemporary( partId );
 
        doc.Export( _folder, filename, viewIds, opt );
      }
 
      // We do not commit the transaction, because
      // we do not want any modifications saved.
      // The transaction is only created and started
      // because it is required by the
      // IsolateElementTemporary method.
      // Since the transaction is not committed, 
      // the changes are automatically discarded.
 
      //tx.Commit();
    }
  }
  finally
  {
    uiapp.DialogBoxShowing
      -= new EventHandler<DialogBoxShowingEventArgs>(
        OnDialogBoxShowing );
  }
  return Result.Succeeded;

Initially, I did not yet know exactly which dialogue id to use to identify this specific message. I therefore first implemented a dummy DialogBoxShowing event handler, triggered the event, and determined the dialogue id to use by re-running the command and looking at the event handler argument in the debugger.

As it turns out, the required dialogue id in our case is "TaskDialog_Really_Print_Or_Export_Temp_View_Modes". We wish to retain the temporary isolate mode and export, i.e. select the second command link option. Therefore, the final dialogue box showing event handler implementation becomes:

void OnDialogBoxShowing(
  object sender,
  DialogBoxShowingEventArgs e )
{
  TaskDialogShowingEventArgs e2
    = e as TaskDialogShowingEventArgs;
 
  if( null != e2 && e2.DialogId.Equals(
    "TaskDialog_Really_Print_Or_Export_Temp_View_Modes" ) )
  {
    e.OverrideResult(
      (int)TaskDialogResult.CommandLink2 );
  }
}

Adding Support for both Pre- and Post- Part Selection

In the initial implementation, I just went ahead and used the pre-selected set of parts defined by the user before launching the external command, accessible via the uidoc.Selection.Elements collection.

However, it is much more user friendly to also support post-selection. For that case, it is also useful to implement a selection filter to simplify easy mass selection of the parts.

In order to handle the elements identically regardless of whether they were pre- or post-selected, I convert the selection set to a list of element ids in both cases.

For the pre-selection, I iterate over the pre-selected elements and test each one as follows:

  // Iterate over all pre-selected parts
 
  List<ElementId> ids = null;
 
  Selection sel = uidoc.Selection;
 
  if( 0 < sel.Elements.Size )
  {
    foreach( Element e in sel.Elements )
    {
      if( !( e is Part ) )
      {
        ErrorMsg( "Please pre-select only gyp wallboard"
          + " parts before running this command." );
        return Result.Failed;
      }
 
      Part part = e as Part;
 
      ICollection<LinkElementId> lids
        = part.GetSourceElementIds();
 
      if( 1 != lids.Count )
      {
        ErrorMsg( "Gyp wallboard parts has multiple"
          + " source elements." );
        return Result.Failed;
      }
 
      LinkElementId lid = lids.First<LinkElementId>();
      ElementId hostId = lid.HostElementId;
      ElementId linkedId = lid.LinkedElementId;
      ElementId parentId = hostId;
      ElementId partId = e.Id;
 
      // Determine parent category
 
      Element parent = doc.GetElement( parentId );
      Category cat = parent.Category;
 
      ICollection<ElementId> cids
        = part.GetSourceElementOriginalCategoryIds();
 
      if( 1 != cids.Count )
      {
        ErrorMsg( "Gyp wallboard parts has multiple"
          + " source element categories." );
        return Result.Failed;
      }
 
      ElementId cid = cids.First<ElementId>();
 
      //cat = doc.GetElement( id ) as Category;
 
      // Expected parent category is OST_Walls
 
      BuiltInCategory bic
        = (BuiltInCategory)cid.IntegerValue;
 
      if( BuiltInCategory.OST_Walls != bic )
      {
        ErrorMsg( "Pleqase pre-select only "
          + " gyp wallboard parts." );
        return Result.Failed;
      }
 
      if( null == ids )
      {
        ids = new List<ElementId>( 1 );
      }
 
      ids.Add( partId );
    }
 
    if( null == ids )
    {
      ErrorMsg( "Please pre-select only gyp wallboard"
        + " parts before running this command." );
      return Result.Failed;
    }
  }

The category of the source elements can be determined using the Part.GetSourceElementOriginalCategoryIds method, which unsurprisingly turns out to be OST_Walls.

I use that to check the part source element category like this in the final selection filter implementation:

class WallPartSelectionFilter : ISelectionFilter
{
  public bool AllowElement( Element e )
  {
    bool rc = false;
 
    Part part = e as Part;
 
    if( null != part )
    {
      ICollection<ElementId> cids
        = part.GetSourceElementOriginalCategoryIds();
 
      if( 1 == cids.Count )
      {
        ElementId cid = cids.First<ElementId>();
 
        BuiltInCategory bic
          = (BuiltInCategory)cid.IntegerValue;
 
        rc = ( BuiltInCategory.OST_Walls == bic );
      }
    }
    return rc;
  }
 
  public bool AllowReference( Reference r, XYZ p )
  {
    return true;
  }
}

For the post-selection, the selection filter ensures that no inappropriate parts can be selected, so no additional scan is required to test the references returned by the PickObjects method.

I can use a generic LINQ method to convert the collection of resulting references to the list of element ids:

  // If no parts were pre-selected, 
  // prompt for post-selection
 
  if( null == ids )
  {
    IList<Reference> refs = null;
 
    try
    {
      refs = sel.PickObjects( ObjectType.Element,
        new WallPartSelectionFilter(),
        "Please select wall parts." );
    }
    catch( Autodesk.Revit.Exceptions
      .OperationCanceledException )
    {
      return Result.Cancelled;
    }
    ids = new List<ElementId>(
      refs.Select<Reference, ElementId>(
        r => r.ElementId ) );
  }

Here is ExportWallboard03.zip including the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

There are obviously still some implementation details to iron out.

Handling Temporary Transactions and Regeneration

Luckily, I took a closer look at the generated DXF output files before letting this command loose on humanity.

To my horror, I discovered that all files generated except the first one contain no geometry.

As it turns out, there is an issue with the regeneration and view settings in my original implementation.

After quite a bit of experimentation, I found out that I can successfully generate the individual files if I add the following steps:

• Add code to switch off the first temporary isolation before applying the next one.
• Commit the transaction to temporaily isolate each part before calling Export.
• This requires encapsulating all the temporary transactions in a group and rolling back the entire group instead of the individual transactions, as described for the temporary transaction trick touchup.
• Separate the code to switch off the last temporary isolation and applying the new one into separate transactions.

The resulting loop exporting all the parts ends up looking like this:

  using( TransactionGroup txg = new TransactionGroup( doc ) )
  {
    txg.Start( "Export Wall Parts" );
 
    foreach( ElementId id in ids )
    {
      Element e = doc.GetElement( id );
 
      Debug.Assert( e is Part,
        "expected parts only" );
 
      Part part = e as Part;
 
      ICollection<LinkElementId> lids
        = part.GetSourceElementIds();
 
      Debug.Assert( 1 == lids.Count,
        "unexpected multiple part source elements." );
 
      LinkElementId lid = lids.First<LinkElementId>();
      ElementId hostId = lid.HostElementId;
      ElementId linkedId = lid.LinkedElementId;
      ElementId parentId = hostId;
      ElementId partId = e.Id;
 
      filename = string.Format( "{0}_{1}",
        parentId, partId );
 
      if( view.IsTemporaryHideIsolateActive() )
      {
        using( Transaction tx = new Transaction( doc ) )
        {
          tx.Start( "Disable Temporary Isolate" );
 
          view.DisableTemporaryViewMode(
            TemporaryViewMode.TemporaryHideIsolate );
 
          tx.Commit();
        }
 
        Debug.Assert( !view.IsTemporaryHideIsolateActive(),
          "expected to turn off temporary hide/isolate" );
      }
 
      using( Transaction tx = new Transaction( doc ) )
      {
        tx.Start( "Export Wall Part "
          + partId.ToString() );
 
        view.IsolateElementTemporary( partId ); // requires transaction
 
        //doc.Regenerate(); // this is insufficient
 
        tx.Commit();
      }
 
      doc.Export( _folder, filename, viewIds, opt );
 
      // We do not commit the transaction group, 
      // because no modifications should be saved.
      // The transaction group is only created and 
      // started to encapsulate the transactions 
      // required by the IsolateElementTemporary 
      // method. Since the transaction group is not 
      // committed, the changes are automatically 
      // discarded.
 
      //txg.Commit();
    }
  }

Here is ExportWallboard04.zip including the source code, Visual Studio solution and add-in manifest of the updated version.

I certainly expect more implementation details to crop up that need ironing out.

For instance, I could imagine adding some code to delete the PCP files that are generated together with the DXF output. Or is there any reason to keep them?

I can also imagine that the part identification needs improving. Currently, the command simply uses the part and its source element ids. Maybe the part unique id would be better, or the parent element id needs checking, or is unnecessary snd can be completely removed.

Anyway, for a first stab, this implementation now looks pretty good to me.

Extra Transaction or Regeneration Required

Whenever your add-in modifies the model in any way and you wish to query the Revit database, you need to pay careful attention to ensure that you do not retrieve stale or invalid data.

If anything unexpected whatsoever happens, one of the first things to consider is the possible need for a document regeneration or additional separate transactions between steps.

These kinds of issues arise frequently.

I discussed adding an extra transaction to modify beam parameters and add openings to it and to create an opening in a slab.

Sometimes a simple document regeneration is also sufficient, e.g. to set the width of a newly created TextNote.

Here are two more typical examples:

• Extra transaction required after loading tag
• Extra regeneration required to populate materials

Extra Transaction Required After Loading Tag

Here is an issue raised by Max, Maciej Szlek, who already contributed code to help distinguish MEP fitting shapes:

Question: I have a duct system and want to attach my tag to its elements, using the code to set a tag type. I tried something like this:

  doc.LoadFamilySymbol(
    [my_tag_family.rfa],
    [type_name],
    out tagType);

  IndependentTag tag = doc.Create.NewTag(
    doc.ActiveView,
    element,
    true,
    TagMode.TM_ADDBY_CATEGORY,
    TagOrientation.Horizontal,
    XYZ.Zero);

  tag.ChangeTypeId(tagType.Id);

This code works fine in some projects, whereas in others Revit throws an InvalidOperationException saying that there is no tag available in the call to the NewTag method. The behaviour seems to vary between different projects and on different elements.

How can that be?

Answer: Have you tried either regenerating the document or placing the tag symbol loading and the tag creation calls in separate transaction, committed individually?

Response: Problem solved. As it turns out, the Revit project needs to have some suitable tag type loaded before calling NewTag. Your transaction hint was very helpful. My earlier code was not enough as it stands. It actually requires separate transactions to load the tag type and add a new tag if there was no other tag loaded before. I did not previously know what Revit meant by 'there is no tag available'.

Furthermore, I was initially using automatic transaction mode for this command, thinking that would free me from worrying about any transaction handling myself at all. I now learned that the automatic transaction mode does not enclose each action in a separate transaction, but wraps all executed functions in the whole external command into one single one. In this case, such an approach is not usable at all.

Thank you for a very useful API lesson :))

Answer: Yes, I already mentioned that automatic transaction mode is unofficially deprecated, and manual mode is recommended for all cases nowadays. Automatic transaction mode is considered obsolete.

Arnošt Löbel's AU class on Core Frameworks in the Revit API provides more details on this topic.

Many thanks to Max for raising this issue and verifying that the solution works!

Extra Regeneration Required to Populate Materials

One of the issues we took a look at during the DevLab at AU last Tuesday was the list of materials attached to a newly duplicated symbol.

At first glance, it appeared that a duplicated family symbol had zero entries in its list of materials, whereas the original symbols material list was correctly populated.

On further exploration, we discovered that this is another case of retrieving stale data after a model modification.

The behaviour is easily rectified by a call to regenerate the model after the symbol duplication.

Here is the final implementation of the external command implementing to test the issue. It expects a structural steel column to be pre-selected, which is a family instance whose associated symbol has exactly one entry in its materials list. We duplicate the symbol. This requires defining a new name. To simplify repeated testing, we generate a new name by simply appending the clock tick counter to the original one. Directly after the call to Duplicate, the new symbol's material list has zero entries, which makes no sense for this kind of symbol. A call to Regenerate fixes that:

[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
    Selection sel = uidoc.Selection;
    FamilyInstance inst = null;
 
    if( 1 == sel.Elements.Size )
    {
      foreach( Element e in sel.Elements )
      {
        inst = e as FamilyInstance;
 
        break;
      }
    }
 
    if( null == inst )
    {
      message = "Please select one "
        + "single structural column";
 
      return Result.Failed;
    }
 
    using( Transaction tx 
      = new Transaction( doc ) )
    {
      tx.Start( "Duplicate Symbol" );
 
      FamilySymbol symbol = inst.Symbol;
 
      string name = symbol.Name 
        + DateTime.Now.Ticks.ToString();
 
      int nMaterialsBefore 
        = symbol.Materials.Size;
 
      symbol = inst.Symbol.Duplicate( name ) 
        as FamilySymbol;
 
      // The model is in a temporary state that does 
      // not make sense. Regenerate to clean this up.
 
      int nMaterialsAfter 
        = symbol.Materials.Size;
 
      doc.Regenerate();
 
      nMaterialsAfter = symbol.Materials.Size;
 
      Debug.Assert( 
        nMaterialsAfter.Equals( nMaterialsBefore ),
        "why does the material get lost, please?" );
 
      tx.Commit();
    }
    return Result.Succeeded;
  }
}

For completeness' sake, here is DuplicatedSymbolLosesMaterial.zip containing the complete source code, Visual Studio solution and add-in manifest of this little test command.

AU Classes on Python, UI, Server and Framework APIs

Thursday was another very full and fruitful day at AU. I gave my third and last class, the most exciting one in my eyes, on some UI and integration aspects. I was unable to attend Iffat May's class introducing Python and using it in Revit and Vasari via RevitPythonShell, but I love her material so much I am including it anyway. Adam Nagy presented a class addressing cloud and mobile development and the Revit Server API. Finally, Arnošt Löbel provided a peek behind the scenes and into the depths of the fundamental frameworks underlying the Revit API.

Here they are in chronological order:

1. CP3837-L Scripting with RevitPythonShell in Vasari by Iffat May.
2. CP4107 Let's Face It: New Revit 2013 User Interface API Functionality by Jeremy Tammik.
3. CP3093 My First Cloud/Mobile App with Revit Server by Adam Nagy.
4. CP3426 Core Frameworks in the Revit API by Arnošt Löbel.

I am including the class materials below, for your and my own convenience, and also to ensure that all this juicy stuff really is picked up and returned by Internet search engines.

1. CP3837-L RevitPythonShell in Vasari

Iffat provides an entire introductory tutorial to the Python programming language, and then shows how to apply it to solve a number of useful tasks in Revit and Vasari. She makes use of Daren Thomas' Revit Python shell, originally implemented for Revit 2010, then for Vasari, Revit 2012 and Vasari 2.1, and now available for Revit 2013.

RevitPythonShell introduces interactive scripting ability to Revit and Project Vasari. Designers now have the ability to interactively design and manipulate Revit elements using algorithms and computational logic. The class explores the Python structures, variables, data types, and flow control, and shows how to use them to create scripts to control Revit elements dynamically.

• Handout
• Presentation
• Sample code and models

2. CP4107 Revit 2013 User Interface API

This class takes a deeper look at the new user interface and add-in integration functionality provided by the Autodesk Revit 2013 API. It covers 2013 features including Options dialogue custom extensions using WPF components, subscription to Revit progress bar notifications, embedding and controlling a Revit view inside an add-in dialogue for preview purposes, the new drag and drop API, and the UIView. This class is complementary to and expands on CP3272, a Snapshot of the Revit UI API:

• Document management and View API
• Revit progress bar notifications
• Options dialogue WPF custom extensions
• Embedding and controlling a Revit view
• UIView and Windows coordinates
• Drag and drop

From my point of view, one of the most exciting new features provided by the Revit 2013 UI API is the possibility to correlate between Windows screen device coordinates and Revit model coordinates provided by the UIView class, which I used to examine and implement my own Revit tooltip, which also makes use of the new ReferenceIntersector class and Idling event. This has never previously been possible. Now you can do anything you like using the Windows API and connect that intelligently with the underlying Revit model.

• Handout
• Presentation
• Sample code

3. CP3093 Cloud/Mobile App with Revit Server

This class has two objectives: to introduce you to the Revit Server REST API and to introduce you to cloud and mobile programming.

Autodesk Revit Server is a server-based file storage system that we can use to store Revit files. It has a public API that uses simple HTTP known as REST (or Representational State Transfer). REST is a "style" for designing network applications, and it is used to communicate between the server and a client machine. REST is simple, yet powerful enough. You can use it from anywhere where HTTP programming is available: from a desktop, a mobile device or a server-side application. In this class, we discuss what REST is, using the context of Revit Server.

We then go one step further and show you how to create your own REST service in .NET. We implement it as a notification system in the cloud and demonstrate with an Apple iPad/iPhone application in Apple iOS. At the end of this class, you will be able to:

• Use HTTP requests to interact with a REST API
• Programmatically access and modify data available on Revit Server
• Create basic iOS applications in Xcode
• Create a basic REST service in .NET
• Use Apple Push Notification

Here is the detailed handout document:

• Handout

4. CP3426 Core Frameworks in the Revit API

A good understanding of core frameworks in the Revit API is a prerequisite for developing well behaved Revit add-ins. Among the most important ones, the following frameworks play key roles in most applications:

• External applications, commands, and events
• Transactions phases
• Regeneration and transaction modes
• Updaters and other call-backs
• Scoped objects and element validity

These concepts have been around for many releases, yet there are still facts about them that may not be completely understood. This class summarizes the necessary basics, and also sheds some light on the behaviour that is normally hidden 'under the hood'. Knowledge acquired during this class will help Revit developers to build more efficient, safer, and robust applications.

• Paper
• Presentation

By the time you read this, I will be sitting in the plane heading back to Europe.

Take care, and walk in beauty.

Temporary Transaction Trick Touchup

I mentioned a number of uses of the temporary transaction trick a few days back.

Autodesk's own Revit API transaction expert Arnošt Löbel has a very important point to add to that discussion:

The procedure as described is not always going to work.

First of all, you need to regenerate manually before retrieving any modified geometry; even that is not always guaranteed to give you the accurate and proper geometry.

Many times you will need to actually commit the 'temporary' transaction, since that is the only way to guarantee that all changes propagate though the model.

In order to undo the temporary transaction, you need to enclose it within a transaction group and roll back that group at the end. It goes as follows:

1. Start a transaction group.
2. Start a transaction
3. Make changes.
4. Commit the transaction
5. Retrieve changed geometry
6. Roll back the transaction group

Unfortunately, all too many are unaware of the fact that it is safe to read a model only after regeneration, and sometimes only after committing the open transaction. This is not only related to the 'temporary transaction' trick, it is simply a matter of fact: one should query model geometry only between transactions, or at least after regeneration (and auto-joining, if appropriate).

Many thanks to Arnošt for this important enhancement!

Cloud Based Team Foundation Service

We have seen how Git and Github can simplify global source code management and sharing, and Victor demonstrates one aspect of this by regularly providing his samples such as the Revit external access demo via that platform.

As you obviously know, Autodesk is also driving hard and moving fast towards providing innovative and empowering cloud-based solutions, e.g. Autodesk 360, PLM 360 and BIM 360 Glue.

Now Microsoft joined the club, announcing its own cloud-based software project management platform, e.g. for Visual Studio, the Team Foundation Service.

You can sign up for a free preview account right away, if you are interested.

Rotating Annotation Symbol

Saikat Bhattacharya discusses using the AnnotationSymbol.Location.Rotate and ElementTransformUtils.RotateElement methods to rotate an annotation symbol, and presents a sample code snippet implementing it.

The Temporary Transaction Trick for Gross Slab Data

Last week I provided an updated version of the CmdSlabBoundary external command to determine a floor slab boundary.

Here is a follow-up to that issue:

Question: The solution provided to retrieve the slab boundary works fine for me if no openings are cut out.

I have a situation where my slabs are cut by openings, however, and I need to retrieve the original uncut gross slab boundary.

Here is an example with two slabs A and B and an opening cutting out part of both of them:

The solution provided retrieves the cut out net slab boundary:

How can I obtain the following original gross uncut slab boundary?

Answer: One way to obtain the unmodified geometry of the slab is to use the temporary transaction trick to temporarily eliminate all openings and other elements affecting its shape.

This technique was used to determine gross material quantities of floors, walls and roofs in the material quantities sample from Scott Conover's Autodesk University 2009 class on analysing building geometry, which was later add to the Revit SDK as the MaterialQuantities sample.

It shows how the transaction handling for the temporary operation can be simply and cleanly encapsulated.

It analyses the material quantities of walls, floors, and roofs, and outputs the result to Excel by implementing the following steps:

1. Collect all roof elements
2. Iterate through each material found in each roof element
3. Find the net volume and area of the material
4. Store the material quantities
5. Write the results to the output file
6. Find the gross material quantities
   1. Start a new transaction
   2. Delete the elements that cut the host (doors, windows, openings)
   3. Find the volume and area for each material
   4. Store the material quantities
   5. Write the results to the output file
   6. Rollback the transaction
7. Repeat the above steps for walls and floors
8. Open the output file in Microsoft Excel

To determine the boundary lines of the floor slab with all opening removed, you could proceed in the same fashion as described in step 6 for obtaining the gross material quantities.

Temporarily delete then openings in a separate transaction, retrieve the original slab geometry, and abort the transaction to restore the original state.

This technique is easy to implement. We reused this method for many different purposes a number of times, e.g.

• Determine host reference
• Material quantity extraction
• Unmodified element geometry
• Object relationships (VB)
• Retrieve all model elements via a temporary 3D view
• Access to sketch and sketch plane
• Retrieve unjoined wall geometry
• Retrieving detailed wall layer geometry
• Unit conversion and display string formatting
• Determine Revit demo mode

Addendum: Arnošt Löbel pointed out that this will not always work. Some modifications require the transaction to be committed before they take full effect. The workaround for that is to enclose it within a transaction group and roll back the group at the end.

Apphack @ AU

Do you have an interesting AutoCAD app you would like to publish?

Will you attend Autodesk University 2012 and would you like to win an attractive prize?

If so, take a look at the APPHACK @ AU Hackathon:

The official rules list some great prizes. Unfortunately, they also restrict the participation to AutoCAD apps, so Revit add-ins are not permissible.

Kean Walmsley provides a a few more details.

Wall Footing Relationship Revisited

In the far distant past, I looked at various ways to programmatically determine relationships between associated objects (also in VB), including references between a host object and its hosted dependent elements, e.g. determining the relationship between a wall and its footing.

That was back in the year 2009, using Revit 2010.

A few things have changed and been added since then, but the more things change, the more they stay the same, don't they?

Anyway, this very question was raised again:

Question: Is there a way to obtain a reference to a wall footing from the wall attached to it?

Answer: Yes, sure, there are several different possibilities to achieve this.

You could start off by determining the bottom face of the wall.

Using that, you could set up an ElementIntersectsSolidFilter for a filtered element collector to retrieve all foundation elements touching or intersecting that face, as described for retrieving all touching beams. You would obviously want to apply as many quick filters as possible before taking recourse to the slow geometric filtering, e.g. check for level, category, type, etc. first.

Another way to determine adjacency of Revit BIM elements is to make use of the ray casting functionality provided by the FindReferencesByDirection method, FindReferencesWithContextByDirection method and the ReferenceIntersector class, e.g. cast a ray downwards from the wall and detect the first foundation hit by it.

Last but not least, another way to determine relationships between associated objects such as a wall and its footing is to temporarily delete the host object, causing the dependent objects to be deleted as well. The deleted element ids can be determined, and the whole operation undone to leave the model unchanged.

I described this principle several times, e.g. looking at object relationships (in VB), and specifically determining the wall footing of a given wall.

I cannot tell off-hand which of these methods is most useful and efficient in your specific case, although I would be very interested in seeing the results of some comparisons and benchmarks evaluating this.

Anyway, I note that The Building Coder sample command CmdWallFooting implementing the latter approach is pretty much out of date, having been simply flat ported across several Revit API releases in the past few years.

I therefore updated it for and tested it with Revit 2013, and can now confirm that it still works.

Here is the updated implementation:

[Transaction( TransactionMode.Manual )]
class CmdWallFooting : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    UIDocument uidoc = app.ActiveUIDocument;
    Document doc = uidoc.Document;
 
    Wall wall = Util.SelectSingleElementOfType(
      uidoc, typeof( Wall ), "a wall", false ) 
        as Wall;
 
    if ( null == wall )
    {
      message 
        = "Please select a single wall element.";
 
      return Result.Failed;
    }
 
    ICollection<ElementId> delIds = null;
 
    using( Transaction t = new Transaction( doc ) )
    {
      try
      {
        t.Start( "Temporary Wall Deletion" );
 
        delIds = doc.Delete( wall );
 
        t.RollBack();
      }
      catch ( Exception ex )
      {
        message = "Deletion failed: " + ex.Message;
        t.RollBack();
      }
    }
 
    ContFooting footing = null;
 
    foreach ( ElementId id in delIds )
    {
      footing = doc.GetElement( id ) as ContFooting;
 
      if( null != footing )
      {
        break;
      }
    }
 
    string s = Util.ElementDescription( wall );
 
    Util.InfoMsg( ( null == footing )
      ? string.Format( "No footing found for {0}.", s )
      : string.Format( "{0} has {1}.", s,
        Util.ElementDescription( footing ) ) );
 
    return Result.Succeeded;
  }
}

I ran this command on a minimal sample model containing just one structural wall with its footing:

The command reports the expected relationship:

It says:

Wall Walls <164432 Generic - 200mm> has 
ContFooting Structural Foundations <164470 
Retaining Footing - 300 x 600 x 300>.

Here is version 2013.0.99.3 of The Building Coder samples including the updated CmdWallFooting external command.

Create Dimension between Two Lines

Another one of those recurring questions: how to create dimensioning.

I took the opportunity to highlight how to search the samples, find a solution, and apply a correction to RevitLookup yourself.

You have the code.

May the Force be with you.

Question: I tried to create detail drawings programmatically using the ItemFactoryBase NewDimension method.

I am creating detail lines in the drafting view based the on the geometry wall elements and would like to use Revit dimensioning to insert measurements into the detail drawings.

How do I obtain the reference for the detail lines of a drafting view to be able to call the NewDimension method?

I am sure that this is possible, since I can create dimension lines in a drafting view using the dimension line commands on the Annotate ribbon.

Answer: Whenever you are faced with a question like this, please always begin by studying the three main official sources of information:

• The Revit API help file RevitAPI.chm.
• The online wikihelp Revit API Developer's Guide.
• The Revit SDK sample source code.

Normally, when researching an issue like this myself, I perform a global search across the entire project in the SDKSamples2013.sln solution.

This time, happily, I extended it to the entire samples directory instead, including RevitLookup. To tell the truth, I even searched my whole hard disk for all C# files containing NewDimension, because there were not that many in total.

This turned up the following hits in the Revit SDK folder (copy and paste to an editor to see the truncated lines):

C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1255):               //        m_revitApp.ActiveUIDocument.Document.Create.NewDimension(dimension.View, line, dimension.References, dimension.DimensionType);
C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1470):            m_revitApp.ActiveUIDocument.Document.Create.NewDimension(m_revitApp.ActiveUIDocument.Document.ActiveView,
C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1475):            m_revitApp.ActiveUIDocument.Document.FamilyCreate.NewDimension(m_revitApp.ActiveUIDocument.Document.ActiveView,
C:\...\SDK\RevitLookup\CS\Utils\Elements.cs(272):            Dimension dimensionClone = app.ActiveUIDocument.Document.Create.NewDimension(dimension.View, line, dimension.References);
C:\...\SDK\Samples\CreateDimensions\CS\Command.cs(213):                    Dimension newDimension = doc.Create.NewDimension(
C:\...\SDK\Samples\CreateDimensions\CS\Command1.cs(219):                    Dimension newDimension = doc.Create.NewDimension(
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(31):    /// The class allows users to create dimension using Document.FamilyCreate.NewDimension() function
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(91):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(125):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(160):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);

The very first of those, in the RevitLookup test framework, looks like it should answer your question right away:

  XYZ location1 = GeomUtils.kOrigin;
  XYZ location2 = new XYZ( 20.0, 0.0, 0.0 );
  XYZ location3 = new XYZ( 0.0, 20.0, 0.0 );
  XYZ location4 = new XYZ( 20.0, 20.0, 0.0 );
 
  Curve curve1 = m_revitApp.Application.Create
    .NewLine( location1, location2, true );
 
  Curve curve2 = m_revitApp.Application.Create
    .NewLine( location3, location4, true );
 
  DetailCurve dCurve1 = null;
  DetailCurve dCurve2 = null;
 
  if( !doc.IsFamilyDocument )
  {
    dCurve1 = doc.Create.NewDetailCurve(
      doc.ActiveView, curve1 );
 
    dCurve2 = doc.Create.NewDetailCurve(
      doc.ActiveView, curve2 );
  }
  else
  {
    if( null != doc.OwnerFamily
      && null != doc.OwnerFamily.FamilyCategory )
    {
      if( !doc.OwnerFamily.FamilyCategory.Name
        .Contains( "Detail" ) )
      {
        MessageBox.Show(
          "Please make sure you open a detail based family template.",
          "RevitLookup", MessageBoxButtons.OK,
          MessageBoxIcon.Information );
 
        return;
      }
    }
    dCurve1 = doc.FamilyCreate.NewDetailCurve(
      doc.ActiveView, curve1 );
 
    dCurve2 = doc.FamilyCreate.NewDetailCurve(
      doc.ActiveView, curve2 );
  }
 
  Line line = m_revitApp.Application.Create.NewLine(
    location2, location4, true );
 
  ReferenceArray refArray = new ReferenceArray();
 
  refArray.Append( dCurve1.GeometryCurve.Reference );
  refArray.Append( dCurve2.GeometryCurve.Reference );
 
  if( !doc.IsFamilyDocument )
  {
    doc.Create.NewDimension( 
      doc.ActiveView, line, refArray );
  }
  else
  {
    doc.FamilyCreate.NewDimension( 
      doc.ActiveView, line, refArray );
  }

I tried running this sample command by selecting the ribbon tab Add-Ins > Revit Lookup > Test Framework... > Object Hierarchy > APIObject > Element > Dimension > OK.

That calls the DimensionHardWired method to do the job.

Unfortunately, it throws an exception saying "Attempt to modify the model outside of transaction".

I fixed it by adding the following lines right at the beginning of the method:

  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "DimensionHardWired" );

Obviously, I need to commit the transaction and close the using statement at the end again:

    tx.Commit();
  }

Now is successfully completes with the following result:

You can also look at two The Building Coder samples creating wall dimensioning, either by iterating over the wall faces to pick the two suitable ones, or using FindReferencesByDirection to shoot a ray and find them directly.

They both retrieve the geometry references from the wall faces, and not from a simple detail line, though.

All together, this should provide more than enough to solve your issue.

Accessing the Path of a Family Document from the Family Instance

Before closing, here is pointer to a cool discovery by Saikat Bhattacharya: if you try to find the family document of a family instance and go through the path family instance > family symbol > family > document, you end up at the document containing the family instance. If you are actually after the family document defining the instance, you need to go through the EditFamily method instead. More details on accessing the path of a family document from an instance.

Disposal of Revit API Objects

KR raised a very valid and important question in the discussion of exporting parameters to Excel:

Question: It would be great if you could clarify in broad terms when to dispose of Revit API objects.

You underline the importance of disposing of Transaction objects.

Many objects in the Revit API implement IDisposable, for example FilteredElementCollector, DB.Document, etc.

If I create a new FilteredElementCollector within the confines of Revit API, e.g. in an external command, Idling event handler, external event etc., do I still have to dispose of this object?

The rule of thumb in the .NET world is: 'Always dispose of all objects implementing IDisposable that you instantiated'.

Answer by Arnošt Löbel: You are absolutely correct – it is advisable to explicitly dispose every disposable object, either by calling its Dispose method, deleting it (in C++), or scoping it in a 'using' block. However, it is not absolutely necessary in the managed environment, and there should normally be no harm if you do not do so. The Garbage Collector (GC, for short) will collect the abandoned objects and everything should be just fine, memory-wise.

It might be a little problematic to depend only on the GC if there is 'something' that must be done by the object destructor or finaliser, and that 'something' is timely essential, meaning it should happen is some semi-predetermined time rather than randomly when the GC is triggered. That is why, in my opinion, it is generally recommended to explicitly dispose of all disposable objects. Again, it is not over-important for all objects; I would not bother with filtered element collectors, for example.

Transactions (and T-Groups, S-Transaction, Edit Modes, etc.), are different. While it is no more (nor less) important to dispose of them explicitly and in a timely fashion, it is imperative that they are properly 'finished'. The 'finishing' may mean something different to each of these objects; for example – it might be either Committing or Rolling Back for transactions. This 'finishing' is in fact the part that 'must' be done soon enough, most importantly before the API client (external command, event, etc.) terminates. Since the 'finishing' procedure is automatically invoked from the object destructor, the disposing action indirectly 'finishes' the object as well. This is the reason why it is important to scope transactions in a 'using' block; because 'using' does not let the object leave the scope without disposing (and finishing) it, even in the case of exceptions.

Let me repeat this in yet other words: if your application can guarantee that Commit or RollBack is always called for all transactions that have been Started, it is not necessary to dispose the transaction objects, either explicitly (dispose, delete) or implicitly (using). However, the nice thing about 'using' blocks is that they automatically guarantee this.

Creating an Opening

Here is a question that we have looked at in the distant past, brought up again and reinforced by Jon Mirtschin of Geometry Gym, working on BIM and model exchange with Rhino, Grasshopper et al:

Question: Sorry to bother you, but trying to get a quick answer to this problem. If you happen to have 5 minutes to help, it will be greatly appreciated.

I've attached a sample Revit project. It simply creates a polyline curve array and slab outline, and then attempts to add an internal opening. This is a simplification from my IFC importer. When I run it, I get an error message about a circular reference.

Can you please advise what is wrong and how to fix? I've tried searching samples and online help to no avail.

Answer: Okey-doke, five minutes.

• Countdown starting at 9:45:34.70.
• I read the mail and stored your attachment: 9:47:09.20;
• Created a repository for your issue and unzipped: 9:48:12.65;
• Started up Visual Studio to look at your project: 9:49:02.60;
• Updated references to be able to compile: 9:49:55.64;
• Bumped .NET framework version to 4.0: 9:50:33.15;
• Fixed post-build event... or no, I'll just ignore that error: 9:51:21.87;

Sorry for being so literal, I just can't help it, and I even think it is fun :-)

Well, this looks like an interesting issue.

Before I dig any further, have you looked at the suggestions on creating a hole in a floor? They include exploring the NewOpenings and ShaftHolePuncher SDK samples.

Do those SDK samples work for you?

In additional to that very old post, here is another half-old one which raises another interesting and important point for you to explore: an extra transaction may be required after creating the slab and before punching a hole through it.

Please try that out as well.

I expect a full report including answers to every single one of the questions above, ok?

Thank you!

P.S.: 9:57:42.51 :-)

Response:

Well, at least you have a great stop watch. Most the time I'm too scared to even glance at the clock on the wall. I actually should also ask you to report your Revit start up time; I can probably allow a minute reduction for your great computers vs. my poor laptop ;-)

Ok, good news. You are correct about the transaction. It was one of the things I had in the back of my mind but hadn't checked yet. Thanks for pointing it out.

Adding the manual transactions and setting a commit and start before adding the opening profile worked. Note that when I went back to my real project, it has tiers of commands, so I was getting an exception to start a new transaction within the outer program command transaction. I added a call to the doc.Regenerate method instead, and that resolved this issue, so problem solved.

I did look at the examples you mention, and will be using them. In this case, the IFC data is presenting an outer and inner profile curves, so the nominated method is the best for this situation.

I don't know if I've answered every single one of your questions, but I'm close.

Here is my amended source code. Now I'm off to implement the change in my real project.

Please feel free to blog about this, I have read through most of your blog several times now and to me it is an invaluable resource. I would like to contribute in any small way.

Here is a sample image of a basic test:

This is an IFC generated from an Archicad model and now opened in Revit. I already had the wall openings working, and now slabs are there too. There are some more impressive and real world projects behind this.

Answer: For the stopwatch, I use the Windows command console time command, i.e. an old MS-DOS command :-)

C:\a\doc\revit\blog\ > time
The current time is: 10:43:48.29
Enter the new time:

My computer is pretty old and decrepit, actually. I am up for renewal soon :-)

Thank you for the appreciation and nice example!

Read-only and Automatic Transaction Modes

We have been discussing transactions and their disposal quite a bit recently, with lots of interesting input from Guy Robinson and Arnošt Löbel.

They just submitted comments on EditFamily requiring a non-modifiable document which highlight another issue in this area worthwhile promoting to a post of its own to ensure that you take notice:

Guy says: ... maybe it's time to recommend using the Manual transaction mode only and the removal of Automatic mode. This would pave the way for removing the transaction and regeneration attributes all together.

Jeremy says: I personally never use automatic transaction mode, but I do use both the manual and read-only ones.

It would actually be interesting to know the exact difference between an external command using read-only mode and one using manual without opening any transactions.

Arnošt says: I believe I said it publicly before, but probably not on this blog yet:

First of all, Automatic Transaction Mode is considered obsolete, and we (Autodesk.Revit) do not recommend using it for new external applications. It only exists to ensure compatibility with older applications. The Automatic mode has many limitations (for what an external command can or cannot do), while it has virtually no benefits whatsoever. It is likely it will go away in some future release of Revit.

Read-Only transaction mode does two things (well, it's one thing, really, but I'll split it):

• For one, the command using it cannot have any transactions and may not call any methods that modify a document, directly or indirectly, or even temporarily.
• Secondly, while this external command is being executed, nobody else is allowed to modify the document or have a transaction either; that includes Revit itself, but also applies to other applications that might be invoked through events (for example).

All this basically guarantees that during the entire execution of the external command the current models all remain unmodified.

Guy sums up enthusiastically: Yes, I've been a manual transaction person for a long time.

For various reasons, this enjoyable and thought provoking discussion has accelerated a process I have been slowly going through since the R13 alpha's. The richness of the R13 API effected a rethink, and issues such as transactions/exceptions, which I'll admit I hadn't changed my approach to for a very long time, are triggering more fundamental changes in attitude to the API.

I'd have to say compared to the R8 API I first played with a very long time ago, the speed, stability and functionality possible now is quite stunning. And thinking why these scoping and other changes could be happening is making me rather excited.

With Win8/WinRT/iOS/mobile etc., though, apart from keeping it all logically in my brain it all makes for exciting times as a programmer, even if there aren't enough hours in the day ;-)

Jeremy replies: Wow, yes, talking about cloud and mobile computing and enough hours in the day, have you looked at Kean's latest posts on creating a 3D Android viewer, calling a web-service from Unity, etc.?

Many thanks to Guy and Arnošt for this and all the other recent interesting discussions and insights!

Edit Family Requires No Transaction

I recently received a note from Matt Mason pointing out that the behaviour of the EditFamily method changed in Revit 2013, and a suggestion to highlight this fact. The suggestion is very valid, since his note was quickly followed up by a matching question by Woong Ki Sung on reloading a family, who ran into the very same issue:

Question: I am testing some code to edit family types in Revit 2013, and I have a transaction problem even though I set up manual transactions properly.

The code is very simple, so could you please check? In advance, thank for your help.

Here is the answer by Matt:

Answer: A quick note after I saw your recent post on upgrading add-ins.

I had an interesting case the other day: there is a new API requirement in 2013 that all transactions must be closed before calling EditFamily – it throws an exception to that effect.

I hadn't really focused on this before, and the add-in in question was actually still set up for Automatic mode – I had to convert my add-in to manual transaction mode so that I could control the transactions and close them all prior to calling EditFamily.

The remarks on the EditFamily method in the Revit 2013 API help file RevitAPI.chm now clearly state:

Gets the document of a loaded family to edit. This creates an independent copy of the family for editing. To apply the changes back to the family stored in the document, use the LoadFamily overload accepting IFamilyLoadOptions.

This method may not be called if the document is currently modifiable (has an open transaction) or is in a read-only state. The method may not be called during dynamic updates. To test the document's current status, check the values of IsModifiable and IsReadOnly properties.

Many thanks to Matt for pointing this out!

Using Using Automagically Disposes and Rolls Back

I talked about scoping and disposing of transactions last week, and received prompt and interesting comments from two competent and experienced Revit add-in developers, Danny Polkinhorn and Guy Robinson (your name has to end in 'y' to be really good – tongue in cheek).

Danny says: Should we also use Try...Catch blocks as well?

  using( Transaction trans 
    = new Transaction( doc ) )
  {
    try
    {
      trans.Start();
      //code here
      trans.Commit();
    }
    catch( Exception ex )
    {
      trans.RollBack();
      //exception code here
    }
  }

Do we need to roll back the transaction or does the Using block take care of that?

Guy replies: I'm with Danny here, prefer to gracefully fail so use this format:

  TransactionGroup group;
  try
  {
    using( group = new TransactionGroup( doc ) )
    {
      group.Start( "Some group" );
      // . . .
    }
  }
  catch( Exception )
  {
    if( group.HasStarted() && !group.HasEnded() )
    {
      group.RollBack();
    }
  }

As so often in the past, I leave the final verdict to Arnošt Löbel, who replies with a clear 'no' to the suggestion of adding an exception handler around the 'using' block, because, as implied by the title, it automatically disposes, rolls back, and even handles exceptions:

Answer: No, there is no need to explicitly roll back a transaction (or sub-transaction, transaction group) declared in a 'using' block. The destructor of the object will take of the rolling back when the object leaves the 'using' block.

However, it is still the responsibility of the programmer to commit the object properly. For example, using what Guy wrote:

  using( TransactionGroup group 
    = new TransactionGroup( doc ) )
  {
    group.Start( "Some group" );
 
    // do something here
 
    // need to commit explicitly to
    // avoid implicit rolling back
 
    group.Commit();  
  }

By the way: I always commit or rollback explicitly if it is under my control. I only rely on the destructor for exceptions. I believe it makes the code easier to comprehend.

The snippet above is equivalent to (but more elegant than) the following:

  TransactionGroup group
    = new TransactionGroup( doc );
 
  try
  {
    group.Start( "Some group" );
    // do something here
    group.Commit();
  }
  catch( Exception )
  {
    // this needs to be tested to 
    // avoid another potential exception
 
    if( group.HasStarted() )
    {
      group.RollBack();
    }
 
    // should re-throw if you do 
    // not know how to handle
 
    throw;  
  }

Adding a 'using' block around this try-catch (like Guy did) is completely unnecessary and worthless.

Again: If you always use 'using' for all scope object, you code will be more elegant, transparent and safer.

Scope and Dispose of Transactions

Arnošt Löbel added an important comment on the sample code that I published for refreshing a view:

It is for the best if all transaction objects are always properly scoped, e.g. within a C# 'using' block. This includes transactions, sub-transactions, transaction groups, and other scope-like objects such as StairsEditScope. Not doing so can yield some pretty weird situations when exceptions come into play.

In your example, proper scoping can be implemented by adding 'using' statements, which automatically dispose of the objects when they leave the scope, like this:

  using( TransactionGroup group 
    = new TransactionGroup( doc ) )
  {
    group.Start( "Muda a fachada" );
 
    using( Transaction tran 
      = new Transaction( doc ) )
    {
      tran.Start( "Step 1 " );
      Calcula_Padrao( doc, Paneis, 0.10 );
      tran.Commit();
 
      uidoc.RefreshActiveView();
 
      Thread.Sleep( 2000 );
 
      tran.Start( "Step 2 " );
      Calcula_Padrao( doc, Paneis, 0.4 );
      tran.Commit();
 
      uidoc.RefreshActiveView();
 
      Thread.Sleep( 2000 );
 
      tran.Start( "Step 3 " );
      Calcula_Padrao( doc, Paneis, 0.05 );
      tran.Commit();
 
      uidoc.RefreshActiveView();
 
      Thread.Sleep( 2000 );
 
      tran.Start( "Step 4 " );
      Calcula_Padrao( doc, Paneis, 0.4 );
      tran.Commit();
 
      uidoc.RefreshActiveView();
    }
    group.Assimilate();
  }

This is the safest way to guarantee that scoped objects are destroyed in the proper order. In this case, the transaction must be destroyed (and committed or rolled back) before the group is finished. If not, an exception will be thrown, and since it would be thrown during garbage collection, the consequences are hard to predict.

Here is FachadaCinetica2.zip containing an updated version of the kinetic facade sample command with proper scoping and including the complete Revit 2013 source code, Visual Studio solution and add-in manifest.

Oh, and by the way, the final result of the kinetic facade sample up and running can be viewed on Prof. José Luis Menegotto's Kinetics Architecture page for both AutoCAD and Revit.

Question: How is it if I have a normal external command and just start and commit a transaction within the command Execute method?

Does that require me to add a 'using' block around it as well, or does it get cleaned up properly by itself automatically?

Answer: Basically, the same rules apply. I recommend always scoping inside 'using' blocks.

Again, it makes no difference if no unhandled exceptions are thrown during your command, but if they are, it might trigger some harsh treatment from the API firewall:

• If you only have one transaction, which is still open: it will be rolled back and render your command unsuccessful (with a message to the user). If the GC destroys it before the API framework finds that it was left open (unlikely, but possible), it will still be rolled back, but there may be an extra error message in the journal.
• If you have more than one transaction in your command and an unhandled exception is thrown while your last transaction is still open, Revit will undo ALL your transactions; your command will be a complete failure.
• Things may get complicated with sub-transactions and a transaction group. Those may be nested, and Revit requires that the phases are closed in reverse order to how they were opened, meaning the inner-most phases must be closed first, while the outer-most (most likely a transaction group) must be closed last. Things can go wrong if the GC starts collecting those unfinished phases and finalises them out of order, which is perfectly possible. Revit will throw an exception when that happens, which is not going to be good if this is already happening in an exception. The framework always tries to resolve the situation as best it can, but I have heard of some unhappy endings (if I may say so).

In addition, the API may start providing more of these scope-like objects in the future, and it is better get into habit of scoping them properly in your C# and VB code, something provided automatically and for free in C++.

Determine Revit Demo Mode

Here is yet another interesting example of an apparent gap in the Revit API that can be easily filled using a little workaround.

We have seen numerous examples of performing a certain operation within a temporary transaction that is then rolled back to cancel it, such as to determine gross material quantities for an element with openings, a host reference and, more generally, all object relationships.

Here is an example of using a related but different approach: the trick consists in attempting to perform a certain operation and gracefully handling a specific expected failure condition, in ths case a specific exception being thrown, to determine whether Revit is running in demo mode:

Question: Is it possible to determine whether Revit runs in demo mode? I need this for two different reasons:

• It is a licensing issue, since read-only viewing should not occupy a license.
• Some add-in commands should be greyed out or hidden in the ribbon bar in demo mode.

Answer: You could try to save the model (after making a modification!) and then see if you get an InvalidLicenseException.

I implemented a little sample application TestDemoMode to test a simplified version of this idea.

Here is the test method I created:

  static bool IsDemoMode( Document doc )
  {
    Application app = doc.Application;
 
    try
    {
      Transaction tx = new Transaction( doc );
 
      tx.Start( "Modify Document" );
 
      SketchPlane sp 
        = new FilteredElementCollector( doc )
          .OfClass( typeof( SketchPlane ) )
          .FirstElement() as SketchPlane;
 
      Line line = app.Create.NewLineBound( 
        XYZ.Zero, XYZ.BasisX );
 
      ModelCurve mc = doc.Create.NewModelCurve(
        line, sp );
 
      tx.Commit();
 
      string filename = Path.GetTempFileName();
      File.Delete( filename );
 
      doc.SaveAs( filename );
      File.Delete( filename );
 
      tx.Start( "Unmodify Document" );
      doc.Delete( mc );
      tx.Commit();
 
      return false;
    }
    catch( InvalidLicenseException ex )
    {
      return true;
    }
  }

This is the external command Execute mainline code:

  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Document doc = uidoc.Document;
 
    bool rc = IsDemoMode( doc );
 
    string s = string.Format( 
      "This is {0}a Revit demo version.", 
      rc ? "" : "not " );
 
    TaskDialog.Show( "Test Demo Mode", s );
 
    return Result.Succeeded;
  }

I have not tested it for both cases, though, since I do not have a demo version handy.

I did run it in a non-demo version, which was correctly reported:

I have also not added any checks to determine whether the write and save attempt may be failing due to the document being read-only, disk full, or anything like that.

A much better approach would be to create a new document from scratch and attempt to save that.

Anyway, here is TestDemoMode.zip including the source code, add-in manifest and full Visual Studio solution of the simplified test command.

A full-blown implementation requires a number of additional considerations and lots of testing, of course. As said, the '1 new document' - '2 edit document' - '3 save as' strategy might be best. Hopefully all exceptions thrown during the first two steps will have to do with the licensing. Step three is less certain, since for instance the hard drive may be full.

Saving the current document is a really bad idea and might take a long time, without even thinking about detaching from central and keeping work-shares.

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! :)

Pick a Point in 3D

Today is the second day of AU for me, the first 'real' day of the conference. I woke up at two in the morning, got back to sleep again eventually, but gave up at five and thus had plenty of time for a final private dress rehearsal for my lecture on the extensible storage API later today. I needed that, since it is a couple of weeks since I submitted the material and all but forgot what it is about at all. Now I will be busy all the rest of the day running back and forth between the DevLab and my lecture.

On a completely different topic, here is a question on picking points in space that has already come up a few times:

Question: The Selection.PickPoint method is limited to selecting points on the active work plane. Is there any way to pick an arbitrary 3D point, regardless of work plane?

Answer: Just as you say, the PickPoint method only allows point selection in the current work plane. As stated by the Revit API help file RevitAPI.chm, the various overloads of PickPoint prompt the user to pick a point on the active sketch plane using optionally specified snap settings. The Revit API does not offer any other method to pick a point arbitrarily in 3D space.

So what if you need to pick a point somewhere in space that is not on the active work plane?

Well, if you know a plane on which the point needs to be selected, you can temporarily set the active work plane to that plane. This approach was actually already mentioned briefly in the discussion on snapping to individual points in a point cloud. You need a sketch plane in your document in order to set the active work plane, so you may want to encapsulate the entire operation in a dummy transaction in which to create a temporary sketch plane for that purpose.

I implemented a new external command CmdPickPoint3d in The Building Coder samples to demonstrate this by prompting the user to first select a face on an element and then pick a point on that face. The element face picked first is used to temporarily redefine the active work plane, on which the second point can be picked.

This is implemented by the method PickFaceSetWorkPlaneAndPickPoint:

bool PickFaceSetWorkPlaneAndPickPoint( 
  UIDocument uidoc,
  out XYZ point_in_3d )
{
  point_in_3d = null;
 
  Document doc = uidoc.Document;
 
  Reference r = uidoc.Selection.PickObject( 
    ObjectType.Face,
    "Please select a planar face to define work plane" );
 
  Element e = doc.get_Element( r.ElementId );
 
  if( null != e )
  {
    PlanarFace face 
      = e.GetGeometryObjectFromReference( r )
        as PlanarFace;
 
    if( face != null )
    {
      Plane plane = new Plane(
        face.Normal, face.Origin );
 
      Transaction t = new Transaction( doc );
 
      t.Start( "Temporarily set work plane"
        + " to pick point in 3D" );
 
      SketchPlane sp = doc.Create.NewSketchPlane(
        plane );
 
      uidoc.ActiveView.SketchPlane = sp;
      uidoc.ActiveView.ShowActiveWorkPlane();
 
      try
      {
        point_in_3d = uidoc.Selection.PickPoint(
          "Please pick a point on the plane"
          + " defined by the selected face" );
      }
      catch( OperationCanceledException )
      {
      }
 
      t.RollBack();
    }
  }
  return null != point_in_3d;
}

Note that as always, we need to encapsulate the call to PickPoint in an exception handler in order to gracefully take care of the use cancelling the selection operation.

PickFaceSetWorkPlaneAndPickPoint is driven by the following trivial Execute mainline:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
 
  XYZ point_in_3d;
 
  if( PickFaceSetWorkPlaneAndPickPoint( 
    uidoc, out point_in_3d ) )
  {
    TaskDialog.Show( "3D Point Selected",
      "3D point picked on the plane"
      + " defined by the selected face: "
      + Util.PointString( point_in_3d ) );
 
    return Result.Succeeded;
  }
  else
  {
    message = "3D point selection failed";
    return Result.Failed;
  }
}

Here are a couple of screen snapshots showing this command in action:

• Prompt the user to select a face on an element:

  
  

• Set the active work plane and prompt the user to pick a point on it:

  
  

• Report the result:

Here is version 2012.0.95.0 of The Building Coder samples including the new CmdPickPoint3d command.

Retrieving Detailed Wall Layer Geometry

We start off this week with a bang. I find the following topic especially exciting, for several reasons:

• It deals with geometry. I like that.
• It implements something that cannot be achieved out of the box. I like that.
• It makes use of the Revit 2012 parts functionality and the PartUtils class, which we never looked at in detail before. I like that.
• It uses a temporary transaction to make changes to the model to create and extract information that would otherwise not be available, and then discards the changes to the model. I like that.

I hope you like it too!

Starting off this week with something special is good in several ways, because I will be leaving for a ten-day vacation in southern Spain on Wednesday. I like that too, by the way. I hope this helps keep you occupied while I am gone :-)

Here goes:

It is easy to determine the wall layer locations and their corner points individually for unconnected walls, as I demonstrated by analysing and drawing model lines to represent the wall compound layers way back in 2008. Some additional information on working with wall layers was provided when discussing compound wall layer volumes and the core structural layer.

However, it is a bit harder to determine the exact wall layer corners for connected walls, where the join type affects the layer geometry, e.g. for 'abut' or 'miter'.

How can we obtain the wall layer corner points in plan view taking the wall join into account?

This is a pretty advanced question on detailed geometry access which was raised by Marcelo Quevedo of hsbSOFT.

Solving this task is not achievable using the functionality provided by the Revit API out of the box, but can be addressed by making use of two interesting tricks:

• Splitting the wall into parts, which automatically take the wall layers into account.
• Embedding the split into a temporary transaction so that it can be rolled back without affecting the model afterwards.

This provides a welcome first opportunity to present a practical use of the Revit 2012 parts functionality and the PartUtils class providing API access to it.

The technique of using a temporary transaction for geometry analysis purposes was originally suggested by Scott Conover of the Revit API development team and already mentioned several times here in the past, e.g. for gross material quantity extraction.

Question: I need to get the geometric information of the layers of a wall. Specifically, I need to retrieve the four corner points of a layer to know its position within the wall.

For example, if two walls are connected in a "Butt" type join, their layers are also connected using the same type join. I would like to obtain this geometry information about layers.

It would be very good if I can obtain the four points of a layer, or the two points. Here is an image explaining the problem:

I can see from the blog posts you listed above how to retrieve the layers of a wall. However, when two or more walls are joined, e.g. using abut, miter etc., also their layers are joined in the same fashion. I want to get the four points of each layer:

The four points are different depending on the wall join.

I looked into the Revit API help document, and I did find anything to access this information which is really necessary for us.

Could you please advise me how to achieve this?

Answer: The Revit API does not provide access to the geometrical information you seek out of the box. On the other hand, though, here is the good news:

You could try splitting the wall into parts. That will split it by layers. Then you can access the geometry of each part individually.

If you do so inside a temporary transaction that is rolled back afterwards, the model will remain unchanged.

Marcelo went ahead and implemented this, and the result works perfectly.

Here is a simple example of two walls with a compound internal layer structure:

Selecting the walls one at a time shows you that the individual wall layers have different lengths:

The arrangement of the wall layer corner points is non-trivial:

Marcelo's sample application GeometryPartsAnalyzer implements the suggestion above, determines the geometry of each wall layer by converting it into an individual temporary part, determines the bottom face of each part, and creates model line geometry to display it:

The implementation includes several useful utility classes:

• FaceExtractor
• ModelLineCreator
• WallSelectionFilter
• CmdGeometryParts

The FaceExtractor queries a Revit element for its geometry, finds its solid, and extracts and returns all its faces.

Marcelo's ModelLineCreator is a simplified version of the model curve creator I maintain in The Building Coder samples and last used to display model lines representing the top faces of all walls.

The WallSelectionFilter is a trivial selection filter to ensure that only walls can be selected.

CmdGeometryParts implements the external command. It makes use of the helper method GetBottomFacePoints to retrieve a list of points representing the bottom face of the given Revit element:

public List<XYZ> GetBottomFacePoints( Element e )
{
  List<XYZ> resultingPts = new List<XYZ>();
 
  FaceExtractor faceExtractor 
    = new FaceExtractor( e );
 
  FaceArray faces = faceExtractor.Faces;
 
  if( faces.Size == 0 ) { return resultingPts; }
 
  foreach( Face face in faces )
  {
    PlanarFace pf = face as PlanarFace;
 
    if( pf == null ) { continue; }
 
    if( pf.Normal.IsAlmostEqualTo( -XYZ.BasisZ ) )
    {
      EdgeArrayArray edgeLoops = face.EdgeLoops;
 
      foreach( EdgeArray edgeArray in edgeLoops )
      {
        foreach( Edge edge in edgeArray )
        {
          List<XYZ> points 
            = edge.Tessellate() as List<XYZ>;
 
          resultingPts.AddRange( points );
        }
      }
    }
  }
  return resultingPts;
}

Here is the CmdGeometryParts mainline Execute method, which performs the following steps:

• Prompt the user to select the walls to process.
• Use the PartUtils class to check whether the selected walls can be split into parts.
• Start a temporary transaction for the part creation, so it can be rolled back later.
• Create the parts and regenerate the model so the part geometry becomes accessible.
• Extract the bottom faces of each part using the GetBottomFacePoints method.
• Roll back the temporary transaction to undo the splitting of walls into parts.
• Start a new transaction to create persistent model lines to display the part edges saved in the bottom face information.
• Create the model lines.
• Commit the second transaction.

Enjoy:

public Result Execute( 
  ExternalCommandData cmdData, 
  ref string msg, 
  ElementSet elems )
{
  Result result = Result.Failed;
 
  UIApplication uiApp = cmdData.Application;
  UIDocument uiDoc = uiApp.ActiveUIDocument;
  Document doc = uiDoc.Document;
 
  Transaction transaction = new Transaction( doc );
 
  try
  {
    string strMsg = "Select walls";
 
    ISelectionFilter filter 
      = new WallSelectionFilter();
 
    IList<Reference> walls 
      = uiDoc.Selection.PickObjects( 
        ObjectType.Element, filter, strMsg );
 
    if( walls.Count == 0 ) { return result; }
 
    List<ElementId> ids = new List<ElementId>();
 
    foreach( Reference reference in walls )
      ids.Add( reference.ElementId );
 
    if( !PartUtils.AreElementsValidForCreateParts(
      doc, ids ) )
    {
      return result;
    }
 
    transaction.Start( "parts" );
 
    // Split walls into parts
 
    PartUtils.CreateParts( doc, ids );
 
    // Regenerate document to get the part geometry
 
    doc.Regenerate();
 
    // Retrieve points from bottom faces of parts
 
    List<List<XYZ>> bottomFacesPts 
      = new List<List<XYZ>>();
 
    foreach( ElementId id in ids )
    {
      if( !PartUtils.HasAssociatedParts( doc, id ) )
      { 
        continue; 
      }
 
      ICollection<ElementId> partIds 
        = PartUtils.GetAssociatedParts( 
          doc, id, true, true );
 
      foreach( ElementId partId in partIds )
      {
        Element part = doc.get_Element( partId );
 
        bottomFacesPts.Add( 
          GetBottomFacePoints( part ) );
      }
    }
 
    // Do not affect the original state of walls
 
    transaction.RollBack();
 
    // Draw lines to show the bottom faces of parts
 
    transaction.Start();
 
    ModelLineCreator model 
      = new ModelLineCreator( doc );
 
    foreach( List<XYZ> bottomFacePts in 
      bottomFacesPts )
    {
      for( int i = 1; i < bottomFacePts.Count; ++i )
      {
        model.CreateLine( bottomFacePts[i - 1], 
          bottomFacePts[i], true );
      }
 
      if( bottomFacePts.Count > 3 )
      {
        model.CreateLine( bottomFacePts[0], 
          bottomFacePts[bottomFacePts.Count - 1], 
          true );
      }
    }
    transaction.Commit();
 
    result = Result.Succeeded;
  }
  catch( System.Exception e )
  {
    msg = e.Message;
    result = Result.Failed;
  }
  return result;
}

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

Many thanks to Marcelo for his exploration and nice implementation!

Activate a 3D View

Here is a simple question on making use of the ActiveView setter, which is new in Revit 2012:

Question: I heard that Revit 2012 exposes an API to change the active view.

I would like to change the active view to 3D with the Detail Level set to Fine and Visual Style set to Realistic.

Could you please show me the correct way to change the active view to the one I want?

Answer: I already discussed setting the visual style for a view, so we can make use of that here.

To answer the rest of your query, I created a little sample application for you which says (and does) it all.

It is short and sweet, so I can present it here in its entire glory; first, here is a helper method Get3dView to retrieve a suitable 3D view using a filtered element collector:

  /// <summary>
  /// Retrieve a suitable 3D view from document.
  /// </summary>
  View3D Get3dView( Document doc )
  {
    FilteredElementCollector collector
      = new FilteredElementCollector( doc )
        .OfClass( typeof( View3D ) );
 
    foreach( View3D v in collector )
    {
      Debug.Assert( null != v,
        "never expected a null view to be returned"
        + " from filtered element collector" );
 
      // Skip view template here because view 
      // templates are invisible in project 
      // browser
 
      if( !v.IsTemplate )
      {
        return v;
      }
    }
    return null;
  }

The external command Execute mainline makes use of this method to determine and activate the 3D view to use and set up the Detail Level and Visual Style parameters:

[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    UIDocument uidoc = uiapp.ActiveUIDocument;
    Application app = uiapp.Application;
    Document doc = uidoc.Document;
 
    // Find a suitable 3D view:
 
    View3D view = Get3dView( doc );
 
    if( null == view )
    {
      message = "Sorry, no suitable 3D view found";
 
      return Result.Failed;
    }
    else
    {
      // Must set view before starting the transaction,
      // otherwise an exception is thrown saying 
      // "Cannot change the active view of a modifiable 
      // document (with a transaction currently open)."
 
      uidoc.ActiveView = view;
 
      // Must start a transaction in order to set the 
      // parameters on the view:
 
      Transaction t = new Transaction( doc );
      t.Start( "Change to 3D view" );
 
      view.get_Parameter( BuiltInParameter
        .VIEW_DETAIL_LEVEL ).Set( 3 );
 
      view.get_Parameter( BuiltInParameter
        .MODEL_GRAPHICS_STYLE ).Set( 6 );
 
      t.Commit();
 
      return Result.Succeeded;
    }
  }
}

The one and only slightly tricky part is that writing to the ActiveView property to switch the view requires no transaction to be active, whereas setting the parameters does.

For completeness sake, here is ChangeTo3dView.zip containing the entire project, source code and add-in manifest file for this command.

Wall Joins and Geometry

Once again, here is an issue that shows how Revit keeps strict control over the BIM, and that the possibilities to override the built-in behaviour are intentionally limited:

Question: I have found the API method to AutoJoin elements, but I cannot seem to find any method that allows me to simply join two walls, as is possible in the Revit user interface. How can I achieve that?

Answer: Basically, as far as I understand Revit, it wants to take and keep full control over wall joins itself in order to ensure consistency of the BIM. The Document.AutoJoinElements method does nothing more than force the join to happen immediately. Note that the Revit API help file RevitAPI.chm adds the following remark to this method:

Forces the elements in the Revit document to automatically join to their neighbours where appropriate.

Use this method to force elements in the document to automatically join to their neighbours. Note that when a transaction is committed there is an automatic call to automatically join elements.

I discussed the AutoJoinElements method in some depth and added a list of questions and answers on its usage when it was temporarily not automatically called on closing a transaction, but that issue resolved way back by Revit 2011 Web Update 1.

So regardless of whether or not you call this method, the walls will be joined as Revit sees fit when the transaction is closed.

In the special case of walls, though, there is a limited amount of control left over to the user. Maybe that is exactly what you are referring to? This control is also accessible programmatically through the following new methods introduced in the Revit 2012 API:

Allow and disallow wall end joins

The new methods

• WallUtils.DisallowWallJoinAtEnd()
• WallUtils.AllowWallJoinAtEnd()
• WallUtils.IsWallJoinAllowedAtEnd()

provide access to the setting for whether or not joining is allowed at a particular end of the wall. If joins exist at the end of a wall and joins are disallowed, the walls will become disjoint. If joins are disallowed for the end of the wall, and then the setting is toggled to allow the joins, the wall will automatically join to its neighbours if there are any.

I think that is probably what you want, and also all you can on this context.

In addition, you have the following members on the LocationCurve class:

• ElementsAtJoin retrieves all elements joining to the end of this element's location curve or changes the order of elements participation in the end join with this location curve's end.
• JoinType gets or changes the type of the join at the specified end.

In the user interface, you can also join multiple parallel walls to simulate a single layered wall. This option is currently not available in the API, though.

Question: I am interested in analysing the wall geometry and wish to retrieve the original unjoined geometry of the wall. However, everything that is accessible through the API is modified by the joins to the neighbouring walls. How can I access the original geometry of the unjoined wall, as it is displayed in the user interface on selecting it?

Answer: One possible approach is to determine the neighbouring joined walls at the ends using ElementsAtJoin, temporarily disallow wall joins in a separate transaction, retrieve the unjoined wall geometry, and abort the transaction to restore the original state. This same technique was also used to determine the gross material quantities of walls by temporarily removing all openings from them. That sample is now available in the MaterialQuantities SDK sample. It shows that the transaction handling for the temporary operation can be simply and cleanly encapsulated.