The Building Coder

Load Your Own External Command on the Fly

How to reload an external Revit command without having to restart the Revit session has been a subject of discussion many times in the past, e.g. in reloading an add-in for debug without restart, which lists four possibilities:

• Set up Visual Studio to efficiently load the desired project and the debugee, use the standard cycle hitting F5 to start debugging, and stop debugging when you need to make code changes.
• Use the RevitRubyShell or RevitPythonShell to work interactively with the Revit API on the command line.
• Use the SharpDevelop IDE, temporarily converting the debugee source code to a macro.
• Use the AddInManager.

Revit 2014 adds some new twists to the scenario by the introduction of the MacroManager API, which enables programmatic listing, creating, removing, editing, debugging, and running of macros, and the option to load an add-in mid-session without restarting Revit. Unfortunately, there is no option to unload an add-in, once loaded.

The difficulty is that the AppDomain into which the add-in is loaded locks the add-in DLL, preventing any further changes to it.

One could create a new individual AppDomain for each add-in to work around that.

Another option is to not load the add-in from a DLL at all, but stream in the source code using reflection instead.

Here is an example of the latter approach in VB by David Rock and Yamin Tengono of BSE – Building Services Engineers. David says:

I am running my commands from the ribbon with the following function:

Public Shared Sub InvokeRevitCommand( _
  ByVal strCommandName As String,
  ByVal commandData As Object,
  ByRef message As String,
  ByVal elements As Object,
  ByVal fullPathDllName As String)
 
  ' Load the assembly into a byte array. 
  ' This way it WON'T lock the dll to disk.
 
  Dim assemblyBytes As Byte() = File.ReadAllBytes(
    fullPathDllName)
 
  Dim objAssembly As Assembly = Assembly.Load(
    assemblyBytes)
 
  ' Walk through each type in the assembly.
 
  For Each objType As Type In objAssembly.GetTypes()

    ' Pick up a class.

    If objType.IsClass Then
      If objType.Name.ToLower = strCommandName.ToLower Then
 
        Dim ibaseObject As Object = Activator.CreateInstance(objType)
 
        Dim arguments As Object() = New Object() {
          commandData, message, elements}
 
        Dim result As Object
 
        result = objType.InvokeMember(
          "Execute",
          BindingFlags.[Default] Or BindingFlags.InvokeMethod,
          Nothing, ibaseObject, arguments)
 
        Exit For
      End If
    End If
  Next
End Sub

This way I can re-build the DLL without exiting Revit and my sometimes quite large Revit projects.

I have over 100 Revit commands now and most are loaded via this dynamic method. This makes it super easy to update them on the fly.

Very many thanks to David and Yamin for developing and sharing this effective solution!

Filter for Family Instances in a Room

I wish you a Good Friday.

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I need to determine the boundary loop polygons to represent the furniture and equipment family instances for manipulation on the mobile device.

Before I can start extracting their geometry, I need to access the objects themselves, i.e. determine which family instances are contained in the selected room.

As always, we use a filtered element collector to access the Revit database elements.

I try to apply as many quick filters as possible first, and then potentially refine the results adding slow filters and possibly even additional tests in .NET using LINQ or explicit coding.

In this case, I came up with the following sequence of filter tests which seems to fit my needs:

• Not ElementType
• View independent
• Family instance
• Bounding box intersects outline of the room's bounding box

The first two may or may not be superfluous, actually, but they do no harm either.

For the last test, I query the room bounding box, convert it to an Outline, and use that to set up a BoundingBoxIntersectsFilter. It might be possible to implement something stricter than this, or use a BoundingBoxContainsPointFilter instead.

Currently, the category and other properties are not checked at all. Once I know more exactly what kind of family instances I need, I would add those.

All of these are quick filters.

Since the room bounding box may be much larger than the room itself, for instance for an irregularly shaped or long, narrow, diagonal one, I definitely need to post-process the results with a more precise containment test. It could be purely geometric, e.g. using the point in polygon containment algorithm as in the room in area predicate, or based on other data.

I chose to implement this by checking the family instance Room property. This test could probably also be moved into a filter, e.g. a parameter filter, which would significantly improve its efficiency by avoiding marshaling the data from internal Revit to the external .NET space before checking and potentially rejecting it. See below for further considerations on using this property.

The method currently looks like this:

/// <summary>
/// Return the element ids of all furniture and 
/// equipment family instances contained in the 
/// given room.
/// </summary>
List<Element> GetFurniture( Room room )
{
  BoundingBoxXYZ bb = room.get_BoundingBox( null );
 
  Outline outline = new Outline( bb.Min, bb.Max );
 
  BoundingBoxIntersectsFilter filter
    = new BoundingBoxIntersectsFilter( outline );
 
  Document doc = room.Document;
 
  // Todo: add category filters and other
  // properties to narrow down the results
 
  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .WhereElementIsViewIndependent()
      .OfClass( typeof( FamilyInstance ) )
      .WherePasses( filter );
 
  int roomid = room.Id.IntegerValue;
 
  List<Element> a = new List<Element>();
 
  foreach( FamilyInstance fi in collector )
  {
    if( fi.Room.Id.IntegerValue.Equals( roomid ) )
    {
      a.Add( fi );
    }
  }
  return a;
}

Family Instance Room Property Considerations

For the final test whether the family instance lies inside the selected room, I simply use the FamilyInstance.Room property.

I am aware that there may be some issues with the Room property and its phase dependency, and Patrick Rosendahl implemented a more reliable DetermineRoom method to find a containing room for a given element under all circumstances. In a complex model, I might have to add such enhancements to my approach.

Considerations Processing a Complete Model

Another issue is that the filter I present above searches for the family instances on a room by room basis.

This is fine as long as I am just looking at one single room.

If I wished to process all rooms of an entire large model, I would definitely approach this completely differently. For instance, I might select all family instances of interest in the entire model, determine the containing room for each one of them, and then invert that relationship to obtain a list of instances for each room.

Determining Purgeable Elements

A question that crops up from time to time and is rather hard to answer exactly and exhaustively is on purgeable elements:

Question: What is the best way to get all of the elements that can be purged? I can use WhereElementIsElementType filter to return all types, and WhereElementISNotElementType to return instances, but comparing the two lists does not leave me with the purgeable result. I could compare individual lists of types (i.e. family symbol and family instance), but that seems prone to error. Is there any good way to get this information out of the model?

Answer: Yes, the Revit API does not currently provide any direct method to determine this.

Let's see what can be done about it anyway already.

When you say "all of the elements that can be purged", that can be a pretty huge task.

I would suggest breaking that down into individual sub-tasks for different types of purgeable elements, which will require pretty different handling.

For example, I implemented a method DeleteUnnamedNonHostingReferencePlanes to find and delete all reference planes not hosting any elements.

An explicit reference to the term purge is used in the post on removing unused text note types.

One way to determine whether a certain element A is required by another one B is to delete A and check the return value of the Delete method, which provides a list of deleted element ids. In some cases, B is deleted as well, and its element id is included the resulting list of deleted element ids. This is used by the object relationship analyser (VB).

The deletion can be made temporary by encapsulating it in a transaction that is later rolled back. Here is a discussion of the temporary transaction trick including a list of numerous usage examples, and later touched up slightly.

Unfortunately, of course, this method becomes extremely slow in a large model with each deletion taking place in its own transaction and then rolled back. Wrapping it all in one single transaction will essentially deleting the entire model, which causes other problems is also not very useful, so this idea may not really be very feasible for the task at hand.

When you do have access to a one-way relationship between two classes of objects, e.g. pointers from doors, windows and openings hosted in walls to their respective wall host elements, you can easily invert the relationship to determine the list of hosted object for each host. This is demonstrated in my discussion of the relationship inverter in one of the very first blog posts.

Taking a look at family types only, which is a small subset of the potentially purgeable elements, a similar one-way relationship as the one between hosted objects and their hosts is defined between non-element types and types, since the former provide a property named GetTypeId pointing to the type. You could make use of this in a similar manner to find all unused types as follows:

1. Determine all non-type elements using WhereElementISNotElementType
2. Iterate over all non-type elements. Determine the element id of each one, and build a dictionary D of the inverse relationship, mapping type element id to a list or the elements using that type.
3. Use WhereElementIsElementType to determine all element types. Iterate over them. For each type, check D to see how many elements are referencing it. If D has no entry for this type, it is not being used and can be deleted.

There is no guarantee that this will really work, though, since there may be any number of exceptional situations that need to be handled differently on a case-by-case base.

You can try it out, though, see whether you corrupt the database in any way, test thoroughly, possibly add handling of all special cases that you encounter, and maybe achieve your goal in the long run.

Unfortunately, there is currently no API access to the list of objects or categories searched by the built-in purge functionality, and the logic used for it is non-trivial.

Definitely, a number of special cases need to be handled, and there are some things that cannot be determined using the method described above.

For example, there are no instance placements of materials, so you have to search through instances placed in the model and for each element determine whether the material is used by it or not. This also leaves out materials that are set for type parameters on types that have not been used but are loaded into the model.

LoadFamily and Collector Iteration Performance

Since we are into the topic of family loading performance anyway, after yesterdays discussion on efficient sweep creation, here is another interesting discussion with some useful family loading and symbol filtering benchmarking results and observations by Thomas Jarzyna and an in-depth analysis of the effects of converting a filtered element collector to a .NET collection by Scott Conover:

Question: I need to load some family symbols into my project. I have a lot of different families and even more symbols, so to keep the projects small and clean I would prefer to load family symbols on demand only.

Therefore, whenever an instance of a family is to be created, I need to check first whether the family symbol is already loaded.

I can see two possible approaches to achieve this:

• Check whether the family symbol already exist by iterating through the database using a filtered element collector searching for family name and family symbol name.
• Not checking anything, and just always calling LoadFamilySymbol. It runs fine even if the family symbol is already loaded. One negative side effect of this approach is the "one time conversion" dialogue popping up for older families every time.

Which approach is better from a performance centred point of view, please?

Is there any other possible approach?

Answer: Both of your two approaches sound feasible.

I also find the "one time conversion" dialogue rather irritating and would not want my users to see it, especially not repeatedly.

If that is a serious problem for you, you could implement a system to ensure that it never occurs more than once. For instance, you could create different sub-directories for the different Revit versions of the same family, and check whether an updated version has already been generated before loading an older one.

However, I would expect the use of the filtered element collector to be much (very much!) more efficient.

However^2, it really depends on so many factors that it is impossible to say for sure.

The only way to really answer this with certainty for your particular system, workflow needs, and installation situation is to benchmark the different options.

I described a simple benchmarking system that I would use in a Revit add-in in lack of anything more sophisticated.

I cannot think of any other approach offhand.

The thought of calling LoadFamily without even checking beforehand actually never occurred to me :-)

Here are two different implementation examples checking whether a family has already been loaded, and loading it otherwise, for

• Creating and inserting an extrusion family
• Structural concrete setout points

I hope they fulfil your needs.

Response: Thank you for the answer.

I was hoping for a simple standard best practice, but I see it's not as easy as that.

In the meantime, I've done a little bit of benchmarking myself. Just basic, using a stopwatch:

And you are right, depending on the quantity of different Types (FamilySymbols) these approaches differ significantly.

For a scenario of creating 2000 family instances from one family (see attached sheet), this is my conclusion:

• If you expect less than a dozen different family symbols to load, just load them once via "LoadFamilySymbol" and don't care about iterating the element collection for the already loaded family symbols.
• Otherwise, iterating and finding the loaded family symbols first is better.
• Of course, this depends on the complexity of the family types and the environment (hardware & current load).
• A large number of different families is not considered yet.

I also noted the following interesting fact while iterating for "known" family symbols:

  var collector = new FilteredElementCollector( doc );

  IEnumerable<FamilySymbol> familySymbols = collector
    .OfClass( typeof( FamilySymbol ) )
    .ToElements()
    .OfType<FamilySymbol>();

The additional call to the ToElements method makes the search using the collector slightly less effective (some milliseconds slower) compared to:

  IEnumerable<FamilySymbol> familySymbols = collector
    .OfClass( typeof( FamilySymbol ) )
    .OfType<FamilySymbol>();

But in the long term, iterating over the family symbols is much faster when ToElements is called first.

For the 2000 instances it takes 14 seconds without ToElements vs. 9 seconds with.

I guess this has to do with the caching provided by possible multiple enumerations of IEnumerable.

What do you think?

Thank you, till next time.

Answer: Thank you for your very interesting results and observations, and congratulations on your first benchmarking results! They are already very interesting.

A call to ToElements definitely costs some performance, since it allocates an entirely new generic .NET collection and copies all the elements across from the Revit filtered element collector, as I mentioned discussing FindElement and collector optimisation.

I am surprised and interested (and was initially a little disappointed) to hear that the subsequent iteration over the .NET collection is measurably faster than the Revit collector, though.

Yes, the speed improvement is probably indeed related to the explanation you point to. In this case, the Revit element collector may be storing the elements in 'Revit memory' and eating cycles when marshalling them across to '.NET memory'. This marshalling effort may need to be performed anew on each repetition of the iteration.

Ah yes, with that explanation, I am perfectly happy with this observation, and not disappointed at all.

Thank you for these illuminating results.

Scott adds: I would expect the total time spent in FilteredElementCollector.ToElements and subsequent iteration to be longer than direct iteration of FilteredElementCollector, regardless of the number of elements that pass the filter.

Of course, once ToElements has run and you store the managed handles, iteration of this collection should be fast – you are not going back to the document to find the elements again or filter them or wrap them in managed handles.

If you are doing more than one iteration of a given filter criteria, the first one will always be faster than the second – because of the extra time taken to create the Elements collection. The other activities – traversing the database, applying and evaluating the filter, wrapping the elements that pass into managed code – happen on both.

If you know you need to have the same filtered set of elements more than once, saving them in the collection should be faster for the second and subsequent iterations. This assumes that you know the document hasn’t changed where there are new elements that pass the filter (or some of them are deleted). The second iteration over the managed collection should be faster than re-traversing the document. This is a pretty specialized approach. The other reasons for converting FilteredElementCollector to a collection (you want to store a list of elements or ids for later, you need such a list as input to another method, you want to delete anything you find, etc.) still apply.

If you are running multiple loops on the collector with no changes in between, the second will be consistently faster. Optimally, you might want to unroll the loop to just do everything in one shot.

The first might be faster than the second if the collector is returning a really large number of elements.

Mostly, you want to get a set of things once and just do things to it once. Normally, only certain specialized applications such as multiple data extractions or multiple permutations for design studies might require retrieval of the exact same data and then doing things to it repeatedly in the same code sequence.

Let’s use made up concrete numbers.

• It takes 100 ms to process the model and find elements that pass the filters, and to wrap each element into the API object.
• It takes 5 ms to build the .NET collection returned by ToElements.
• It takes 1 ms to traverse a .NET IEnumerable<Element>, which could be either the Revit collector or the .NET collection.

So with one group of elements processed once:

• With collection: 100 + 5 + 1 = 106 ms.
• Without collection: 100 + 1 = 101 ms.

With the same exact group of elements processed 10 times in the same code (where we know there is no chance new elements were added or elements deleted that we care about):

• With collection obtained once: 100 + 5 + 10 * 1 = 116 ms.
• Without collection: 100 * 10 + 10 * 1 = 1010 ms.

Make sense?

The key thing to understand is that FilteredElementCollector caches nothing (except the filters applied to it, of course). Caching data needed for multiple things will be better – always – but premature if there’s no need to have such a cache at all.

Note that the built-in collections on Document (.WallTypes, etc.) – which are becoming obsolete in future versions – use FilteredElementCollector as their base; there is no caching done there either, and no real advantage to them other than saving the coding effort of building the collector and filters.

Sweep Family Performance Enhancement

Now I am back at work again, enjoying the queries coming in from developers, postponing other important things such as my own long-term class and presentation preparations etc. Addicted to helping, that's me.

Anyway, here is a piece of doubly good news, in that the developers mentioned below did a good job of helping themselves, in addition to achieving a radical speed improvement from 40 hours down to 3 minutes, i.e. just 0.125% of the original time, to programmatically generate some Revit families.

Question: The problem was initially reported by Hu Zhao in a recent comment:

I have 80,000 elements to generate, now I use sweep; do you know which is faster of sweep and extrusion? Which can offer a better performance for the computer?

It took 40 hours for the sweep operations.

Is it possible to accelerate this?

In Rhino script, only 10 minutes is enough for this operation.

Hu's colleague and Revit API blogger David Tan clarifies:

Zhao's scenario is to create about 80,000 sweeps in Revit in one shot. Per his test, it will take about 20 hours, while his workmate can achieve it in Rhino within 10 minutes. Zhao expects that Revit could do faster.

As Zhao's test was done in an open family document (with UIDocument), I tried to use in-memory document but it still take about 18 hours to draw all 80K sweeps.

Zhao noticed that although all the drawing work is done in a single transaction, it seems that Revit tries to regenerate the document after there are sweeps created already automatically. We did set the RegenerationOption to be Manual. We say it because we saw Revit progress bar in the bottom-left corner indicates it.

Our questions:

1. Can we prohibit Revit's automatic regeneration?
2. More straightly, do we have any approach to get the job done faster?

Thanks a lot! And Happy Chinese Snake Year!

Answer: There may be a stray regeneration happening in sweep creation.

If you can demonstrate that (with a sample that creates something less than 80,000 sweeps, please :-), please provide a reproducible case for further analysis.

It is also worth asking what the use case is for 80,000 sweeps in one family. Are you possibly modelling things so detailed that that a building model with multiple instances of this will have performance problems?

Maybe you could add an image of what you are creating to motivate the development team by helping them understand.

Response: Here is an image showing what we are trying to achieve:

Each sweep corresponds to a single wooden roof in the image.

Here is also Hu Zhao's source code. We used an in-memory document and added a StopWatch to measure the time consumed.

The source code implements an external command in Program.cs. It will pop up a window and let you select a XML file, which contains creation data of all the sweeps. You can find the XML file along with the .sln file. To make things simple, I only put 2000+ sweeps creation data in the XML file.

Finally I want to share the good news from Hu Zhao. He resolved the performance problem by splitting all sweeps into 24 families and then combining them together. It only takes 3 minutes now. Of course, the cost is the reduced granularity; the model now no longer has individual roofs with embedded family instances. But as he is OK with it, we can say we have found the solution.

Hu added the following more detailed project description:

I am now working in a project plan team for the design of Arch_Tec_Lab in ETH Zürich (youtube link).

The parametric roof is generated in Rhino by my colleague, and the wooden beams will be assembled by robotic arms.

Before I joined this team, they imported the roof (including roof wooden structure) in DWG format, which did not display correctly in some plan and section views. In 3D view, it led to Revit crash because of too many triangle meshes in this imported format.

So I wrote a plugin to import the wooden beams (around 80k) of the roof.

We choose XML to exchange the position information, and I choose sweep instead of extrusion to generate each beam.

For now, the roof structure is divided into 7 parts of XML, which generates 7 families. It took me about 20 hours by using 3 dell precision computers.

Because the roof will be modified several times in the following days, I am now searching for a way to reduce the generation time.

I found that the speed of sweep is slower when the amount increased, and the regeneration that I cannot avoid is especially slow when the amount is above 1500.

Yesterday I found a way to accelerate the generation greatly.

I did like this: divided each 1 part into 24 pieces sections with the mark in XML, then generate each section into single family, and then combine them into a major family. These actions are all made by the plugin.

This is much more quicker.

Let me introduce our project once again.

The Arch_Tec_Lab is a role model project of department of Architecture, ETH Zürich. The team includes most important professors in the Institute of Technology in Architecture. The project aims to realize the BIM control in the life circle. Now we are using Revit to an extremely detail, and we enjoy the cloud rendering in Autodesk 360, except we wish it would also support animation rendering. Now we are working on the construction drawings in Revit.

In Switzerland, few architects use Autodesk products, because of the majority of the MAC users. But we want build a model for the architects and the students in department.

Many thanks to David and Hu for their research and sharing this remarkable performance enhancement!

Addendum: For completeness' sake, here is the slow source code and the complete fast solution. Hu clarifies: the code we posted yesterday is the slow version. The 'slow source code' shows how it works. The 'complete fast solution' is the quicker version.

There are 8 parts to generate. I finished all the work above in 20 hours using 3 computers, and now I can generate the smallest part in 3 minutes. Actually, the bigger part took about 6 hours by the slow method, and now takes about 50 minutes.

The time depends on how many parts I separate. I never test all the 80000 sweeps in one run, maybe it will cost one month ~:D – because the speed runs slower when time goes.

ToElementIds Performance

Conversion of a filtered element collector to an explicit .NET collection of elements or element ids is always costly and mostly avoidable and unnecessary.

Before getting to the details of that issue, here is another quick snapshot from our travels to the West European developer conferences. As you either know or might guess, one of the main topics of these is cloud and mobile development, e.g. looking at topics such as the BIM 360 Glue REST API and SDK and my hands-on exploration of how to access and use it via Python.

Funnily enough, the lighting in the Paris Charles de Gaulle airport is designed along a cloud scheme, so here is very low quality picture of us almost touching the clouds at the airport gate preparing to board the flight to Milano:

Ora siamo arrivati in Milano per un'altra conferenza di sviluppatori.

Returning to the Revit API, I recently mentioned a couple of FindElement and collector optimisations.

One of them is the fact that the conversion from a filtered element collector to a .NET collection is costly and should be avoided if possible.

Here is another observation related to that, brought up by Guy Robinson and answered by Scott Conover of the Revit API development team:

Question: I sometimes use the ToElementIds method, e.g. like this:

  var fc = new FilteredElementCollector( doc )
    .OfSomething()
    .ToElementIds();
 
  foreach( var elemId in fc )
  {
    var element = doc.GetElement( elemId );
  }

I noticed that this is about 25% slower than accessing the elements directly as follows:

  var fc = new FilteredElementCollector( doc )
    .OfSomething();
 
  foreach (var elem in fc)
  {
      var element = elem;
  }

I am wondering why the ToElementIds approach is so much slower?

Shouldn't the two approaches be equivalent?

Is there any good reason to use ToElementIds at all?

Not surprisingly, this ~25% slower figure has been the same on my tests ever since I started comparing in Revit 2012.

Answer: This is not unexpected.

ToElementIds and ToElements allocate a new concrete .NET collection containing the elements passing the filter. Then it returns this allocated collection to you, which involves a conversion from a native level collection to a managed object. This will take extra time as compared to a direct iteration.

Why might you use the ToElementIds variants? Well, you might need a concrete collection to store in memory. Or you might need a collection to pass as input to an API method like Delete – which you should definitely not call from the middle of a foreach iteration unless you like unexpected behaviour. This provides a shortcut to building this allocation.

For any sort of operation of the type "I want to read properties of each passing element" you can skip ToElements and the extra collection allocation.

Thank you Scott for these insights!

For one example of how this can be achieved, look at the aforementioned FindElement and collector optimisations. There are lots of other examples in many of The Building Coder discussions, since I consciously and consistently avoid this conversion whenever possible, i.e. almost always.

Porting an AutoCAD Application

AutoCAD and Revit are very different animals, as we already pointed out a couple of times in the past.

Exaggerating just a little, you might say that Revit manages a BIM and ensures its consistency at all times, so there are no exceptions to anything ever, meaning nothing can be overridden. Moreover, almost all Revit geometry is parametrically driven, so there is no way to tweak the model geometry either, except of course by changing the official parameter values.

This is obviously a challenge to developers with existing AutoCAD applications. Here is another example of some typical considerations of an application developer with an existing full-blown AutoCAD application, wondering whether there is any way to start supporting Revit as well:

Question: We have customers using our software and asking if we could port our AutoCAD.NET application to Revit.

In our current implementation, we override line functionality to display special walls. We need to modify subcomponents individually, manipulate grip points, split them, add more components, etc.

Intersections between walls affect neighbouring walls and their subcomponents.

We have therefore currently overridden grip points, snap points, graphics, properties, a custom ribbon is regenerated then an object is selected and so on.

Is it possible to implement something similar with Revit? I guess we probably need to customize the functionality of some wall type? What is best place to start if this is possible?

Answer: I am afraid that the answer is definitely not that you can simply port your existing application.

The Revit API is completely different from the AutoCAD one.

More than this, the entire underlying principles, workflows and paradigms are utterly different and almost beyond comparison.

In fact, one of the biggest stumbling blocks to learning the Revit API is being caught up in preconceptions coming from AutoCAD or other non-BIM APIs.

In Revit, almost all the functionality you list above cannot be overridden, because Revit manages a building information model, BIM, and ensures that it remains consistent at all times.

The proper approach in Revit would probably be to define an appropriate family and family types.

I am not at all a product expert, though, so I cannot advise you at all about how best to implement your specific model in Revit. You need to consult with application engineers and product experts about that, and above all understand the existing Revit functionality in depth before you even start considering creating an add-in application, which may easily end up reproducing or even fighting against the recommended Revit paradigms and workflows.

What I can tell you with a hundred percent certainty is that your existing AutoCAD application cannot simply be ported to Revit, and that your best approach will almost certainly require reconsidering the whole implementation from scratch.

What I can also say with conviction is that it will probably be well worth your while in the long run to start learning and understanding the Revit BIM concepts and researching how a useful add-in for that domain might look, to enable you to start work on a BIM-compatible implementation, in which you will certainly be able to reuse a lot of your existing know-how and continue supporting your customers as they gradually migrate to BIM usage.

If you have customers knowledgeable in Revit who are interested in cooperating with you to drive such a project, I would take that opportunity with great gratitude if I were you.

Best place to start? Learn the product functionality, and do your best to forget AutoCAD for a moment.

Response: Thank you for a great answer!

I think at this point we have to stick with AutoCAD due the limitations or the concept of Revit. The main interest of our customer in using Revit was using IFC for integration with thermal calculation applications.

Of course Revit would also save us having to implement a number of additional objects like openings, roofs etc. that are not available in AutoCAD.

I believe we will continue implementing the functionality on top of AutoCAD but still continue to research Revit at the same time. Perhaps at some point we could implement some kind of separate editor for our model, maybe using a WPF dialogue user interface that plays with normal walls in Revit. If I read the API documentation correctly, we can still store additional info to wall objects.

Answer: Your approach sounds very feasible and sensible to me.

Implementing additional functionality in a separate WPF dialogue interacting with Revit would work fine.

Please be aware that you can also maintain your existing AutoCAD functionality and access that in the background, invisibly to the user, from your Revit add-in.

For example, you can read the relevant data from the Revit model, process it in the background using your existing application, and display useful results in your own WPF dialogue in a way that supports an efficient Revit workflow. That might enable you to achieve a near perfect solution with little effort.

And yes, absolutely, you can store any additional data you like on walls and any other elements using the extensible storage functionality.

Importing SAT into Revit

People now and then ask about programmatically importing a SAT file into Revit.

You can export a SAT file using the API and import an SAT file from the user interface, simply by going through Insert > Import > Import CAD > ACIS SAT Files.

However, the Revit API Import methods only take options for DGN, DWG/DXF, gbXML, and images.

One obvious workaround is to implement an intermediate step to generate a DWG file from the SAT one.

This can be achieved either using RealDwg or AutoCAD itself, if it happens to be installed on the same machine.

In either case, the description of implementing ACISIN and ACISOUT in .NET might come in handy to achieve this.

ElementTransformUtils and Family Instance Creation May Force Regeneration

If you are facing performance problems generating or manipulation largish models, please be aware that you need to watch out a bit with the ElementTransformUtils class. Some of its methods contain built-in regeneration at the end, which is executed regardless of your other regeneration actions. Family instance creation can also force regeneration at times. As always, some research and lots of benchmarking is advisable.

AU Registration Savings End October 14

The end is near!

Oct 14 is the last chance to save $500 on the Autodesk University 2012 registration.

Prepare thyself and register now.

Hope to see you there!

FindElement and Collector Optimisation

As I recently mentioned, Mikako Harada published a very nice article on programmatically adjusting beam cutback.

It was followed it up by a description of some commonly used helper methods to find certain named elements and family symbols in a project. One of them is FindElement, implemented as follows in that post:

  public static Element FindElement(
    Document doc,
    Type targetType,
    string targetName )
  {
    // Get the elements of the given class 
 
    FilteredElementCollector collector 
      = new FilteredElementCollector( doc );
 
    collector.WherePasses( 
      new ElementClassFilter( targetType ) );
 
    // Parse the collection for the 
    // given name using LINQ query.
 
    IEnumerable<Element> targetElems =
      from element in collector
      where element.Name.Equals( targetName )
      select element;
 
    IList<Element> elems = targetElems.ToList();
 
    if( elems.Count > 0 )
    {
      // We should have only one with the given name.
 
      return elems[0];
    }
 
    // Cannot find it.
 
    return null;
  }

It is important to be aware that this method can be optimised further in some aspects and should not be used indiscriminately.

Here are some points I would like to highlight:

1. Language dependence: should be avoided if possible.
2. Speed: could be improved by using a parameter filter instead of LINQ.
3. Conversion from a filtered element collector to .NET collections can often be avoided.

I avoid using the helper methods in this form wherever I can if performance is a factor. When is it not?

It is not always possible to avoid the language dependence. In any case, it is definitely important to be aware of the issue.

In detail:

1. Language dependence: if there is any way to identify the target element except by name, it is normally preferable to do so.
2. Speed: using a parameter filter to find a name may be complicated by the fact that different Revit element types store their names in different parameter values. The LINQ query can mostly be replaced by a parameter filter, though, which normally halves the execution time, since the marshalling of all the non-target data from internal Revit memory to external .NET and LINQ space is eliminated.
3. A filtered element collector is already iterable, so the conversion to an IEnumerable<Element> and to IList<Element> is often unnecessary. If all filtering can be achieved using filtered element collector functionality, the instantiation of additional lists and consequent duplication and copying of all contained data members can be completely avoided. This is obviously especially important for large collections.

I mentioned performance hints such as these numerous times in the past between the lines. Maybe the time is ripe now to bring them up as a topic of their own.

Mikako underlines that the main intention of the helper method above is to make it as easy as possible for the reader to copy and paste these code snippets to quickly run the test command instead of having to download, explore and install the whole ADN training material zip file, and performance is a completely secondary consideration.

If performance becomes a bottleneck, each developer needs examine it and implement her own optimised version. Accessing a wall type, for example, does not require this kind of filtering from the whole element list.

Collector Optimisation

While we are on the topic of efficient coding, here is another snippet of typical add-in code presenting a surprising number of opportunities for improvement in a very few lines.

It retrieves all family symbols in the document, uses them to find door families, and processes each one in turn:

  FilteredElementCollector collector 
    = new FilteredElementCollector( doc );
 
  FilteredElementIterator itor = collector
    .OfClass( typeof( FamilySymbol ) )
    .GetElementIterator();
 
  itor.Reset();
 
  while( itor.MoveNext() )
  {
    FamilySymbol symbol = itor.Current
      as Autodesk.Revit.DB.FamilySymbol;
 
    // Determine family category
 
    Category cat = symbol.Category;
 
    // Process family if doors category
 
    if( cat != null )
    {
      if( cat.Name == "Doors" )
      {
        Family family = symbol.Family;
 
        // Process reference to doors family
      }
    }
  }

Can you spot three possibilities for improvement, either a more succinct formulation, performance enhancement, or both? And manage not to peek?

Here are the ones I found, which is not to say that there are no others:

• The code can be significantly shortened by using foreach directly on the collector instead of explicitly setting up and using an iterator.
• You should avoid explicit string comparison when you can, both for reasons of performance and language independence, e.g. use the built-in category for doors instead of the category name, which might be localised.
• In this case, you could let the collector handle the category selection for you, making the code significantly more efficient.

Applying these suggestions produces this instead:

  FilteredElementCollector collector
  = new FilteredElementCollector( doc )
    .OfCategory( BuiltInCategory.OST_Doors )
    .OfClass( typeof( FamilySymbol ) );
 
  foreach( FamilySymbol symbol in collector )
  {
    Family family = symbol.Family;
 
    // Process reference to doors family
  }

Shorter, more readable, and more performant.

Since each family can contain more than one symbol, you should obviously keep track of the families already processed and skip those when looping over the symbols.

FamilyParameter IsShared Property

A long time ago, we discussed a workaround to access the shared family parameter GUID using reflection, more specifically (and obviously) .NET Reflection. If you are new to this, here is an in-depth Code Project article on Reflection in .NET.

Now Victor Chekalin, or Виктор Чекалин, ran into this issue as well and presents a much improved solution.

Here is the background and our discussion on this:

Question: Why does the FamilyParameter class have no IsShared Property, like the Parameter class does? I need to get list of all FamilyParameters and all their properties, including GUID.

Now, if I call the GUID property on a FamilyParameter that is not shared, Revit throws an InvalidOperationException. The only way I can check whether the FamilyParameter is shared or not is try to get GUID property and handle the exception if it is not shared.

This is a problem, because intercepting the exception takes a lot of time, and if a family has a lot of FamilyParameters, the program freezes significantly.

Why did the API developers implement this odd behaviour and not add an IsShared property to the FamilyParameter? Alternatively, they could just return null if the FamilyParameter is not shared.

Answer: Sorry about that.

These properties can be accessed using .NET Reflection.

Response: Yes, that looks as if it would help me.

I looked at RevitAPI.dll using Reflector and find it harder still to understand why the API developers didn't add the IsShared property to the FamilyParameter class. It is just a wrapper for the Parameter class, and it would just take one or two lines of code, e.g.

  public bool IsShared
  {
    get { return getParameter().IsShared; }
  }

Re-examining your post, though, maybe I understand after all: the GUID and IsShared properties were only added to the Parameter class in the Revit 2011 API. I guess that it was simply an oversight and they forgot add the new properties to the FamilyParameters as well. Maybe I'm wrong.

I hope this property is added in the future versions of the Revit API. As I can see from the post comments, I am not the only one wanting to see an IsShared property.

Implementing a FamilyParameter IsShared Extension Method

Based on your sample in the post, I wrote a simple extension method:

  public static bool IsShared( 
    this FamilyParameter familyParameter )
  {
    MethodInfo mi = familyParameter
      .GetType()
      .GetMethod( "getParameter", 
        BindingFlags.Instance 
        | BindingFlags.NonPublic );
 
    if( null == mi )
    {
      throw new InvalidOperationException( 
        "Could not find getParameter method" );
    }
 
    var parameter = mi.Invoke( familyParameter, 
      new object[] { } ) as Parameter;
 
    return parameter.IsShared;
  }

I used the internal getParameter method instead the m_Parameter field, because it is not recommended to use fields from other classes. Also, the getParameter method is used in most of the code that I saw in Reflector, not the m_Parameter field.

Using the FamilyParameter IsShared Extension Method

The use of the new method is completely obvious:

  foreach( FamilyParameter fp in mgr.Parameters )
  {
    if( fp.IsShared() )
    {
      familyTypeParameter.Guid = fp.GUID;
    }
  }

It works much faster than triggering and catching the exception, e.g.

  try { var guid = parameter.GUID; } 
  catch() {}

Thank you again for reminding me about reflection.

Answer: Many thanks to you, Victor, for your analysis, clean implementation, and sharing this with us!

Here is an updated version 2013.0.99.2 of The Building Coder samples including the extension method and a test call to it in the CmdFamilyParamGuid external command.

Exporting Parameter Data to Excel, and Re-importing

Did you observe the international talk like a pirate holiday yesterday?

I did not, I'm sorry to say. I only became aware of it this morning trying to find some reason why it was so quiet yesterday. Aaarrr!

Anyway, here is an update of an age-old sample application, originally created by Miroslav Schonauer for the very first Revit API training classes after the first introduction of the Revit API back in the Revit 2008 timeframe.

Miro put together a whole collection of useful samples, which survived time and changes extraordinarily well and made it through to become the Xtra Revit API training labs.

I received several queries lately on how to export data to Excel, with various follow-up options such as later including data from linked files as well, and enabling a re-import of modified data.

The FireRating SDK Sample

Actually, talking about re-importing the exported data, a simple example of this has been around all along as well. The FireRating SDK sample demonstrates:

• Creating and populating a new shared parameter in the model.
• Exporting all its values to Excel.
• Importing modified data back in from Excel to update the Revit model.

I mentioned this important sample a number of times, ever since the early beginnings of the blog, often to demonstrate how to add a shared parameter to various element types in the model:

• Adding a shared parameter to a DWG file.
• Defining a new parameter.
• Adding a shared parameter to an RFA file.
• Model group shared parameter.
• Parameter access and scheduling.

One very special use of this sample was in the special 100^th anniversary description of utilizing Revit API resources to get a beginner up to speed and running.

Because of its importance, this sample also made its way into the Revit API Xtra training labs in the shape of three commands corresponding to the steps listed above:

• Lab4_3_1_CreateAndBindSharedParam
• Lab4_3_2_ExportSharedParamToExcel
• Lab4_3_3_ImportSharedParamFromExcel

Of course, the importance of shared parameters for add-in was greatly diminished by the introduction of extensible storage.

Parameter Export to Excel Considerations

Anyway, back to the subject at hand.

The external command Lab4_2_ExportParametersToExcel in the ADN Xtra labs implements exporting all parameter data of all Revit elements to Excel. 'All' is relative, though...

It bases the selection of parameters on the standard Revit API Element.Parameters property. An attempt is made to export the values of the parameters returned in this collection, and others are ignored. Many elements do have other parameters associated with them as well, as demonstrated by BipChecker, the built-in parameter explorer. They could easily be added to the export as well, of course.

Furthermore, there are of course a multitude of other important data items not stored in parameters that might be interesting to export and potentially modify and re-import as well. It might be worthwhile checking whether RDBLink does anything like that... RDBLink was originally part of the Revit 2008, 2009 and 2010 SDKs, then matured into a subscription pack product.

The choice of Excel as an export target is not mine, nor would it normally be so. Due to popular demand, though, this command makes use of the Excel COM interface and .NET Interop to access that. It launches or attaches to a running instance of Excel and makes it visible, so you can see the work sheets and parameters being added one by one. It might be faster to make Excel invisible, and faster still to use some other library to generate the XLS file without direct access to Excel, and faster still choosing some completely different file format such as SLK, CSV, or, heaven forbid, TXT.

The command selects all elements in the entire model, both types (e.g. family symbols) and non-type elements. Each element is identified in the export by its element id, and a flag is added to tell whether it is a type or not.

The original implementation exported only model elements. Support for all elements was implemented by creating a union of two complementary filtered element collectors, which is easily possible and normally not recommended.

The elements are sorted by category, and elements with no valid category are ignored. The elements are sorted into a dictionary of separate containers for each category.

The category names are used to create individual work sheets in a new Excel work book.

The category names need some massaging to confirm with the Excel work sheet naming conventions; the name must:

• Not be blank.
• Not exceed 31 characters.
• Not contain any of the following characters:   :   \   /   ?   *   [   or   ].

In the original implementation, the entire parameter access was encapsulated in a try-catch exception handler. Many elements returned null, though, triggering and exception and slowing down the process enormously. Every exception handler is resource intensive and will significantly slow down execution and consume resources. An exception handler should be designed to handle unexpected, exceptional cases only; exceptions should be exceptional. Adding a preceding check for a null parameter before actually trying to access it speeded things up significantly. Maybe the exception handler can be removed completely?

As said, the elements are identified in the resulting Excel data by their element id. This is not a very safe method of identifying elements, because the element id may change, e.g. by work sharing operations. It would be safer to use the UniqueId instead.

When the new work book is set up, Excel automatically adds a couple of work sheets to it. The number of default work sheets added can be defined in the Excel application settings. I initially implemented code to remove the unneeded work sheets, but later commented it out to simply let them be. They don't really hurt.

For each category, all the elements are examined to determine what parameters they contain. A column is added to the work sheet for each parameter, and a header is set up listing the parameter name. We iterate over the elements in that category and add a row listing their element id, type flag, and parameter values for each.

Parameter Export to Excel Implementation

Let's summarise the steps:

• Collect all elements and sort them by category.
• Attach to or launch Excel and create a new work book.
• Loop through all the categories and set up a work sheet for each.
• Determine all parameters for the given category and create the work sheet header listing them.
• Iterate over each elements of the category and export its element id, type flag and parameter values.
• Report the results.

Here is the code implementing this as a read-only external command:

/// <summary>
/// Export all parameters for each model 
/// element to Excel, one sheet per category.
/// </summary>
[Transaction( TransactionMode.ReadOnly )]
public class Lab4_2_ExportParametersToExcel 
  : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    Document doc = app.ActiveUIDocument.Document;
 
    // Extract and group the data from Revit in a 
    // dictionary, where the key is the category 
    // name and the value is a list of elements.
 
    Stopwatch sw = Stopwatch.StartNew();
 
    Dictionary<string, List<Element>> sortedElements 
      = new Dictionary<string, List<Element>>();
 
    // Iterate over all elements, both symbols and 
    // model elements, and them in the dictionary.
 
    ElementFilter f = new LogicalOrFilter(
      new ElementIsElementTypeFilter( false ), 
      new ElementIsElementTypeFilter( true ) );
 
    FilteredElementCollector collector
      = new FilteredElementCollector( doc )
        .WherePasses( f );
 
    string name;
 
    foreach( Element e in collector )
    {
      Category category = e.Category;
 
      if( null != category )
      {
        name = category.Name;
 
        // If this category was not yet encountered,
        // add it and create a new container for its
        // elements.
 
        if( !sortedElements.ContainsKey( name ) )
        {
          sortedElements.Add( name, 
            new List<Element>() );
        }
        sortedElements[name].Add( e );
      }
    }
 
    // Launch or access Excel via COM Interop:
 
    X.Application excel = new X.Application();
 
    if( null == excel )
    {
      LabUtils.ErrorMsg( 
        "Failed to get or start Excel." );
 
      return Result.Failed;
    }
    excel.Visible = true;
 
    X.Workbook workbook = excel.Workbooks.Add( 
      Missing.Value );
 
    X.Worksheet worksheet;
 
    // We cannot delete all work sheets, 
    // Excel requires at least one.
    //
    //while( 1 < workbook.Sheets.Count ) 
    //{
    //  worksheet = workbook.Sheets.get_Item(1) as X.Worksheet;
    //  worksheet.Delete();
    //}
 
    // Loop through all collected categories and 
    // create a worksheet for each except the first.
    // We sort the categories and work trough them 
    // from the end, since the worksheet added last 
    // shows up first in the Excel tab.
 
    List<string> keys = new List<string>( 
      sortedElements.Keys );
 
    keys.Sort();
    keys.Reverse();
 
    bool first = true;
 
    int nElements = 0;
    int nCategories = keys.Count;
 
    foreach( string categoryName in keys )
    {
      List<Element> elementSet 
        = sortedElements[categoryName];
 
      // Create and name the worksheet
 
      if( first )
      {
        worksheet = workbook.Sheets.get_Item( 1 ) 
          as X.Worksheet;
 
        first = false;
      }
      else
      {
        worksheet = excel.Worksheets.Add( 
          Missing.Value, Missing.Value, 
          Missing.Value, Missing.Value ) 
          as X.Worksheet;
      }
 
      name = ( 31 < categoryName.Length )
        ? categoryName.Substring( 0, 31 )
        : categoryName;
 
      name = name
        .Replace( ':', '_' )
        .Replace( '/', '_' );
 
      worksheet.Name = name;
 
      // Determine the names of all parameters 
      // defined for the elements in this set.
 
      List<string> paramNames = new List<string>();
 
      foreach( Element e in elementSet )
      {
        ParameterSet parameters = e.Parameters;
 
        foreach( Parameter parameter in parameters )
        {
          name = parameter.Definition.Name;
 
          if( !paramNames.Contains( name ) )
          {
            paramNames.Add( name );
          }
        }
      }
      paramNames.Sort();
 
      // Add the header row in bold.
 
      worksheet.Cells[1, 1] = "ID";
      worksheet.Cells[1, 2] = "IsType";
 
      int column = 3;
 
      foreach( string paramName in paramNames )
      {
        worksheet.Cells[1, column] = paramName;
        ++column;
      }
      var range = worksheet.get_Range( "A1", "Z1" );
 
      range.Font.Bold = true;
      range.EntireColumn.AutoFit();
 
      int row = 2;
 
      foreach( Element e in elementSet )
      {
        // First column is the element id,
        // second a flag indicating type (symbol)
        // or not, both displayed as an integer.
 
        worksheet.Cells[row, 1] = e.Id.IntegerValue;
 
        worksheet.Cells[row, 2] = (e is ElementType) 
          ? 1 
          : 0;
 
        column = 3;
 
        string paramValue;
 
        foreach( string paramName in paramNames )
        {
          paramValue = "*NA*";
 
          Parameter p = e.get_Parameter( paramName );
 
          if( null != p )
          {
            //try
            //{
              paramValue 
                = LabUtils.GetParameterValue( p );
            //}
            //catch( Exception ex )
            //{
            //  Debug.Print( ex.Message );
            //}
          }
 
          worksheet.Cells[row, column++] 
            = paramValue;
        } // column
 
        ++nElements;
        ++row;
 
      } // row
 
    } // category == worksheet
 
 
    sw.Stop();
 
    TaskDialog.Show( "Parameter Export",
      string.Format(
        "{0} categories and a total "
        + "of {1} elements exported "
        + "in {2:F2} seconds.",
        nCategories, nElements,
        sw.Elapsed.TotalSeconds ) );
 
    return Result.Succeeded;
  }
}

I ran the command on the basic architectural sample model rac_basic_sample_project.rvt. It takes about two minutes to complete, produces this XLS file output containing 124 work sheets, and displays the following message on terminating:

The timing is not very relevant, since I was doing other things at the same time on the machine.

Here is adn_labs_2013_2012-09-19.zip containing the complete source code, Visual Studio solution and RvtSamples include file of the ADN training labs with the updated Lab4_2_ExportParametersToExcel external command.

DocumentChanged versus Dynamic Model Updater

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

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

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

Subscribe to DocumentChanged to React to Elevation View Creation

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

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

Here is the entire code of this external command implementation:

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

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

This approach has two significant disadvantages:

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

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

This is unintentional and potentially confusing.

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

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

Install Dynamic Model Updater to React to Elevation View Creation

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

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

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

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

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

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

Unsubscribe from Event and Unregister Updater

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

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

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

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

It is even simpler for the updater:

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

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

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

Here is the corresponding code for DMU:

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

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

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

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

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

Family Usage Filtered Element Collector Performance

Since all access to the Revit database and its elements takes place through the filtered element collectors, it is extremely important to make efficient use of them. We have not looked at that topic for quite a while now. Here is an issue that recently cropped up which illustrates some interesting points.

I presented a filtered element sample for creating an XML family usage report which iterates over all the loaded families and launches a new filter for each of them looking for its instances.

If you are only interested in families of certain categories, and furthermore only in ones that actually have instances in the model, then the approach presented there will almost certainly turn out to be inefficient in a large model.

That leads to the following query:

Question: I tried to get a list of families which have instance in the model (not all families), but the performance is very bad if the model has loaded hundreds of family types.

Here is the VB.NET code (copy and paste to an editor to see the truncated lines in full):

Sub GetFamilyType(ByVal mydoc As Document)
  Dim collector As New Autodesk.Revit.DB.FilteredElementCollector(mydoc)
  Dim collection As ICollection(Of Autodesk.Revit.DB.Element) = collector.OfClass(GetType(DB.Family)).ToElements()
  ' Get all families belong to a Category of current document                 
  Dim families As List(Of Family)
  Dim category As DB.Category = Nothing
  'Dim familylist As New Dictionary(Of String, Family)
  Dim familyTypeCategoryList As New Dictionary(Of String, List(Of Family)) 'Family list with Family Instance in the current model
  Dim categoryList As New Dictionary(Of String, Category) 'Category list with Family Instance in the current mode
  For Each family As DB.Family In collection
    category = Nothing
    If family.Symbols.Size > 0 Then
      Dim symbols As FamilySymbolSetIterator = family.Symbols.ForwardIterator()
      symbols.Reset()
      Dim symbol As Autodesk.Revit.DB.FamilySymbol = Nothing
      While symbols.MoveNext()
        symbol = TryCast(symbols.Current, Autodesk.Revit.DB.FamilySymbol)
        '-------------------------
        'Bad performance with following code when the model has hundreds of family types
        'Anyway to improve it?  
        '-------------------------
        'Find the symbol of which at least a Family instance exists    
        Dim filter As New DB.FamilyInstanceFilter(mydoc, symbol.Id)
        collector = New Autodesk.Revit.DB.FilteredElementCollector(mydoc)
        Dim familyInstances As ICollection(Of DB.Element) = collector.WherePasses(filter).ToElements()
        If familyInstances.Count > 0 Then
          'All symbols of a family are in the same category, different family might in then same category
          category = symbol.Category
          Exit While
        End If
      End While
      If category IsNot Nothing Then
        If familyTypeCategoryList.ContainsKey(category.Name) Then
          familyTypeCategoryList.Item(category.Name).Add(family)
        Else
          families = New List(Of DB.Family)
          families.Add(family)
          familyTypeCategoryList.Add(category.Name, families)
          categoryList.Add(category.Name, category)
        End If
      End If
    End If
  Next
End Sub

Is there a quick filter to retrieve only the families having instances in the model?

Answer: There are a few ways that this can be improved directly, and there are also some alternative approaches which may or may not improve performance, and which you would have to test yourself in your own environment using your real world models.

Remember to always benchmark your add-in performance.

One thing that I note which will cost you some unnecessary time is the conversion of collectors to collections, for instance:

  Dim collection As ICollection(
      Of Autodesk.Revit.DB.Element)
    = collector.OfClass(GetType(DB.Family))
      .ToElements()

There is no need for this conversion; you can iterate over the collector itself directly, so there is no reason to create a collection, which requires memory allocation and a conversion overhead.

Eliminating the conversion to collections will only have a small impact, though. Try it out; benchmark this and let me know the result, please.

Much more significantly, you are first collecting all the families in the model, and then launching a separate new filter for each in a loop to find all of its potential instances.

For each of the families, if any instance is found, you retrieve its category and check whether it is one of the categories of interest to you.

If not, or no instances were found, the family is skipped and all the effort spent on that family so far was wasted.

I would suggest a completely different algorithm:

1. Define the list of categories of interest to you.
2. Implement one single family instance filter for all of these categories.
3. Iterate over the result and determine which families they belong to, or which symbols they use.
4. If you use these families or symbols (or their names) as dictionary keys, you will create the desired list.
5. The dictionary value for each can be something minimal, like a count of all the family instances of each type, or larger, like a list of all the instance element ids.

The first two steps are illustrated in several places on the blog, for instance in the examples to retrieve MEP elements, connectors, and structural elements.

I'm sure the remaining steps are demonstrated somewhere as well.

You can also look at the numerous other filtered element collector samples.

The XML family usage report shows how to iterate specifically over families, which may however not help much in your case, since it looks at all families, regardless of their categories and whether they have any instances in the model.

It is thus similar to your original approach.

Actually, looking at your code, I think it may be based on that very post :-)

I hope this solves the problem for you... I think it will, actually.

Response: Thank you for your suggestion. Step 1 does not apply to our case since we don't know the categories until after we filter the family instances in the model.

Here is the code that we ended up with:

Public Shared Sub CreateFamilyTreeTest( _
  ByVal myDoc As Document)

  Dim collector As New FilteredElementCollector(myDoc)
  collector.WhereElementIsNotElementType()

  Dim familyInstances = From elem In collector _
    Where elem.Category IsNot Nothing _
    And TypeOf elem Is FamilyInstance()

  Dim familySymbols = From elem In collector _
    Join sb In familyInstances _
    On elem.UniqueId Equals CType(sb.ObjectType,
      FamilySymbol).Family.UniqueId _
    Where TypeOf elem Is Family Select elem

  familySymbols = familySymbols.Distinct()

  Dim mapCatToFam As _
    New Dictionary(Of String, List(Of Family))

  Dim categoryList As _
    New Dictionary(Of String, Category)

  Dim families As List(Of Family)
  Dim category As Category
  Dim symbol As FamilySymbol

  For Each family As Family In familySymbols
    If family.Symbols.Size > 0 Then
      symbol = family.Symbols(0)
      category = symbol.Category
      If mapCatToFam.ContainsKey(category.Name) Then
        mapCatToFam.Item(category.Name).Add(family)
      Else
        families = New List(Of Family)
        families.Add(family)
        mapCatToFam.Add(category.Name, families)
        categoryList.Add(category.Name, category)
      End If
    End If
  Next
End Sub

It uses LINQ to improve the performance and takes about 10 seconds compared to the original 3-5 minutes.

Addendum: Guy Robinson suggested below making use of the .NET generic GroupBy method to simplify this further as follows:

public static void CreateFamilyTreeTest(
  Document myDoc )
{
  IEnumerable<Element> familiesCollector =
    new FilteredElementCollector( myDoc )
      .OfClass( typeof( FamilyInstance ) )
      .WhereElementIsNotElementType()
      .Cast<FamilyInstance>()
      // (family, familyInstances):
      .GroupBy( fi => fi.Symbol.Family )
      .Select( f => f.Key );
 
  var mapCatToFam = new Dictionary<string,
    List<Element>>();
 
  var categoryList = new Dictionary<string,
    Category>();
 
  foreach( var f in familiesCollector )
  {
    var catName = f.Category.Name;
 
    if( mapCatToFam.ContainsKey( catName ) )
    {
      mapCatToFam[catName].Add( f );
    }
    else
    {
      mapCatToFam.Add( catName,
        new List<Element> { f } );
 
      categoryList.Add( catName,
        f.Category );
    }
  }
}

If you are interested in some background on the GroupBy method and an encouragement to use it whenever possible, here is a short introduction and tutorial.

Class Property Initialiser

As one thing leads to another, I wondered about the missing pair of parenthesis in the new List initialiser above, and asked Guy about that.

Guy responds: When using collection initialisers the parentheses () are optional. The code will compile and run both with and without them.

So 'new List<Element> { f, f };' is the same as writing:

  var list = new List<Element>();
  list.Add( f );
  list.Add( f );

You can also use initialisers for class properties. So say I have a class like this:

  public class Klass
  {
    public int Prop1 { get; set; }
    public string Prop2 { get; set; }
  }

A new instance of that class can be initialised like this:

  var klass = new Klass
  {
    Prop1 = 23,
    Prop2 = "some string"
  };

Saves a bit of typing ;-)

Many thanks to Guy for all his interesting hints and explanations!

The Performance Adviser API

Unbelievable as it may seem, there are still a number of new areas of functionality added in the Revit 2012 API that we have not even got around to covering here yet at all. One of these is the performance adviser. Here is an article on that by my colleague Saikat Bhattacharya from the ADN AEC newsletter.

The Performance Adviser API added in Revit 2012 allows developers to execute a set of built-in or custom rules against a given model, and to display a warning dialog about the elements that fail to satisfy the rules. You can use this feature to flag the user about possible performance degradations, and to create your own rules that could be run on a model to check for adherence to certain design guidelines. For example, you may want to signal the user where walls may be overlapping.

This article provides an overview and discusses how to access performance adviser rules, execute rules, and define custom rules.

Accessing Performance Adviser Rules

The performance adviser rules are a set of application-wide rules. To work with performance adviser rules, we use an application-wide, singleton class called PerformanceAdviser. This class is a registry of all the performance checking rules as well as an engine to execute the rules. You can access the singleton PerformanceAdviser instance using a PerformanceAdviser.GetPerformanceAdviser static method.

Once we have access to the PerformanceAdviser object, we can use the GetAllRuleIds method to obtain a list of rule IDs registered in the application. We can then iterate through each rule ID and get the rule information for the corresponding rule ID, using the methods, such as GetRuleName and GetRuleDescription.

The following command illustrates how to list all the registered performance adviser:

/// <summary>
/// List all registered performance adviser rules
/// </summary>
[Transaction( TransactionMode.Manual )]
public class ListPerformanceAdviserRules 
  : IExternalCommand
{
  public Autodesk.Revit.UI.Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    // Get access to Performance Adviser object
 
    PerformanceAdviser adviser 
      = PerformanceAdviser.GetPerformanceAdviser();
 
    // Access the rules
 
    IList<PerformanceAdviserRuleId> ruleIds 
      = adviser.GetAllRuleIds();
 
    String ruleInfo = String.Empty;
 
    // Loop through each rule Id and get rule name and description
 
    foreach( PerformanceAdviserRuleId ruleId 
      in ruleIds )
    {
      ruleInfo += "\n" + adviser.GetRuleName( ruleId )
        + " : " + adviser.GetRuleDescription( ruleId );
    }
 
    TaskDialog.Show( "Existing Rules Info", ruleInfo );
 
    return Result.Succeeded;
  }
}

Executing a Performance Adviser Rule

Once you know the ids of rules that you are interested in, you can use the PerformanceAdviser.ExecuteRules method to execute the given rules. This method takes a document and a set of rule ids as input arguments. It returns a list of FailureMessages, which we can iterate through and display, for instance, in a standard Revit warning dialog using Document.PostFailure method.

For an introductory discussion about Failure Posting and Handling, please refer to this introduction, its follow-up, and the ADN AEC Customization Newsletter – BIM Edition – Winter 2011.

The following command shows a simple example of executing the overlapping walls performance adviser rule:

/// <summary>
/// Execute overlapping walls? 
/// performance adviser rule.
/// </summary>
[Transaction( TransactionMode.Manual )]
public class ExecutePerformanceRule : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    Document doc = commandData.Application
      .ActiveUIDocument.Document;
 
    // Access the Performance Adviser object
 
    PerformanceAdviser adviser 
      = PerformanceAdviser.GetPerformanceAdviser();
 
    // List all the rules
 
    IList<PerformanceAdviserRuleId> ruleIds = adviser.GetAllRuleIds();
 
    // Create an empty list for 
    // the rules to be executed
 
    IList<PerformanceAdviserRuleId> rulesIdsToExecute =
      new List<PerformanceAdviserRuleId>();
 
    // Iterate through each
 
    foreach( PerformanceAdviserRuleId ruleId in ruleIds )
    {
      if( adviser.GetRuleName( ruleId ).Equals( "Overlapping walls" ) )
      {
        rulesIdsToExecute.Add( ruleId );
        break;
      }
    }
 
    // Now we need to post the results
 
    IList<FailureMessage> failureMessages =
      adviser.ExecuteRules( doc, rulesIdsToExecute );
 
    foreach( FailureMessage fm in failureMessages )
    {
      Transaction trans = new Transaction( doc );
      trans.Start( "Failure Reporting" );
      doc.PostFailure( fm );
      trans.Commit();
    }
 
    return Result.Succeeded;
  }
}

Defining a Custom Rule

Now, the most powerful part of this API is that we define custom adviser rules. To create our own, we define a class implementing an interface called IPerformanceAdviserRule. Your custom adviser class then needs to define the following methods:

• GetName – returns the name of this rule.
• GetDescription – provides the description of this custom rule.
• InitCheck – performs the initialization work before running the rule. For example, it could be a task like clearing a collection of elements that we will be storing elements that fail the rule execution test.
• WillCheckElements – sets whether the rule will iterate through elements or not.
• GetElementFilter – provides the element filter which can help narrow down the type or category of elements that a certain rule is expected to work with.
• ExecuteElementCheck – This method contains most of the implementation steps for a given rule. It examines the element passed to it (which is filtered by the GetElementFilter) and checks for all elements that fail the criteria laid by the rule.
• FinalizeCheck – This method gets called by the PerformanceAdviser after all the elements in a document matching the element filter in the GetElementFilter method have been checked by the ExecuteElementCheck method. This method usually will contain the code to check if there are elements which fail the rule test and if there are, the names of the elements are listed along with the standard warning failure message.

The code below shows an example of a custom performance adviser rule, which provides warnings if there are clashes between ducts in a Revit model:

// A custom performance adviser rule class.
// This rule provides a warning if the model 
// contains ducts which clash each other.  
 
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
using Autodesk.Revit.UI;
using Autodesk.Revit.DB;
using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB.Mechanical;
using System.Diagnostics;
 
namespace BuildingCoder
{
  public class DuctClashDetection 
    : IPerformanceAdviserRule
  {
    private FailureDefinition m_warning;
    private FailureDefinitionId m_warningId;
    private List<ElementId> m_ClashingDucts;
 
    /// <summary>
    /// DuctClashDetection Constructor
    /// </summary>
    public DuctClashDetection()
    {
      // Create failure message
 
      m_warningId = new FailureDefinitionId(
        new Guid( "AACC9C09-7956-4B36-9D27-FF8A64544C31" ) );
 
      m_warning = FailureDefinition.CreateFailureDefinition(
        m_warningId, FailureSeverity.Warning,
        "Some ducts clash with each other" );
    }
 
    /// <summary>
    /// This method does most of the work of the 
    /// IPerformanceAdviserRule implementation. 
    /// It is called by PerformanceAdviser and 
    /// examines the element passed to it 
    /// (which was previously filtered by the filter 
    /// returned by GetElementFilter).  This method 
    /// is checking for all elements that intersect 
    /// with current duct and adds them to the list 
    /// of elements.
    /// </summary>
    public void ExecuteElementCheck(
      Document document,
      Element element )
    {
      // For each of the elements, check if there is 
      // any intersection with the specific element 
      // being passed on via the method signature
 
      FilteredElementCollector collector 
        = new FilteredElementCollector( document );
 
      // Use the Elements Intersection Filter to get elements
      // that intersect with the specified element
 
      ElementIntersectsElementFilter elementFilter =
        new ElementIntersectsElementFilter( element, false );
 
      collector.WherePasses( elementFilter );
 
      // Exclude the element in the intersection
 
      List<ElementId> excludes = new List<ElementId>();
      excludes.Add( element.Id );
      collector.Excluding( excludes );
 
      // Save the intersecting ducts
 
      foreach( Element elem in collector )
      {
        m_ClashingDucts.Add( elem.Id );
      }
    }
 
    // The rule ID for this rule;
 
    public PerformanceAdviserRuleId Id =
      new PerformanceAdviserRuleId(
        new Guid( "C00CEF6D-2C4B-402C-9AED-160DFA1785BE" ) );
 
    /// <summary>
    /// This method is called by PerformanceAdviser 
    /// after all elements in document matching the 
    /// ElementFilter from GetElementFilter() are 
    /// checked by ExecuteElementCheck(). It checks to 
    /// see if there are any ducts in the 
    /// m_ClashingDucts list. If so, it iterates 
    /// through that list and reports the failures.
    /// </summary>
    public void FinalizeCheck( Document document )
    {
      try
      {
        // If no ducts clash
 
        if( m_ClashingDucts.Count == 0 )
        {
          Debug.WriteLine(
            "No clashing ducts. Test passed." );
        }
        else
        {
          // Pass the element IDs of the clashing ducts to the revit
          // failure reporting APIs.
 
          FailureMessage fm =
            new FailureMessage( m_warningId );
 
          fm.SetFailingElements( m_ClashingDucts );
 
          Transaction failureReportingTransaction =
            new Transaction( document );
 
          failureReportingTransaction.Start( 
            "Failure reporting" );
 
          PerformanceAdviser.GetPerformanceAdviser()
            .PostWarning( fm );
 
          failureReportingTransaction.Commit();
 
          m_ClashingDucts.Clear();
        }
      }
      catch( System.Exception ex )
      {
        TaskDialog.Show( "Oops!", ex.Message );
      }
    }
 
    /// <summary>
    /// Return rule description.
    /// </summary>
    public string GetDescription()
    {
      return "Detects clash between ducts";
    }
 
    /// <summary>
    /// Provide the filter to focus on elements 
    /// that this rule should be focused on.
    /// </summary>
    public ElementFilter GetElementFilter( 
      Document document )
    {
      return new ElementClassFilter( typeof( Duct ) );
    }
 
    /// <summary>
    /// Return name of rule.
    /// </summary>
    public string GetName()
    {
      return "Duct Clash Detection";
    }
 
    /// <summary>
    /// Perform initial/preliminary work 
    /// before executing the tests.
    /// </summary>
    public void InitCheck( Document document )
    {
      if( m_ClashingDucts == null )
        m_ClashingDucts = new List<ElementId>();
      else
        m_ClashingDucts.Clear();
 
      return;
    }
 
    /// <summary>
    /// Return true if this rule will iterate 
    /// through elements and check them, 
    /// else return false.
    /// </summary>
    public bool WillCheckElements()
    {
      return true;
    }
  }
}

Once we have defined a class for our custom rule, our next step is to register the rule. You can do this by calling PerformanceAdvisor.AddRule. This is done at the start-up of Revit using the OnStartup event of IExternalApplication.

Similarly, we can unregister the Performance Adviser rule at the OnShutdown event. The following code shows an example of how the custom rule is registered and unregistered:

[Transaction( TransactionMode.Manual )]
public class AddPerformanceRule : IExternalApplication
{
  public DuctClashDetection ductClashDetect;
 
  /// <summary>
  /// Unregister the custom rule.
  /// </summary>
  public Result OnShutdown( 
    UIControlledApplication application )
  {
    PerformanceAdviser adviser 
      = PerformanceAdviser.GetPerformanceAdviser();
 
    adviser.DeleteRule( ductClashDetect.Id );
 
    return Result.Succeeded;
  }
 
  /// <summary>
  /// Register the custom rule.
  /// </summary>
  public Result OnStartup( 
    UIControlledApplication application )
  {
    PerformanceAdviser adviser 
      = PerformanceAdviser.GetPerformanceAdviser();
 
    ductClashDetect = new DuctClashDetection();
 
    adviser.AddRule( ductClashDetect.Id, ductClashDetect );
 
    return Result.Succeeded;
  }
}

Once the custom rule has been added, we can execute it in the same way as the predefined rules. Using the code used in this article against a given set of clashing ducts, this new API can report the clash results as shown below:

In this article, we have shown you that the performance adviser API provides the ability to define custom rules, execute them, and report potentially problematic results via the failure message APIs. The Revit SDK PerformanceAdviserControl sample shows more comprehensive examples of this API. It presents a list of rules for the users to select and execute. Please refer to the sample for more details.

Many thanks to Saikat for this helpful overview!

Timer Code for Benchmarking

Two topics today:

• Benchmarking add-ins
• Hands-on training

Benchmarking Add-ins

Just like most programming issues, many Revit API tasks can be achieved in numerous different ways. The optimal approach often depends on your individual needs. The only way to find out which one that may be is to test it. In order to test it effectively, you need to measure the results. One of the most important aspects is often the time required, the execution performance. Measuring a short duration of time precisely makes use of a timer. The .NET framework provides several timer classes for this purpose. Here is a related question that just came up on this topic:

Question: How can I add a timer to my Revit 2012 C# code to find out how much time it takes to execute the whole command? Is there a way to add a form to show total time taken to run the command? I am not quite sure how to wrap the timer class around Revit code.

Answer: The Building Coder samples include several examples of benchmarking both entire commands and individual function calls or sections of code.

They define the JtTimer class, which is one possible wrapper for the .NET Stopwatch class that you may find useful. Besides the Stopwatch wrapper, it also implements a TimeRegistry for keeping track of and summing up the results a number of different Stopwatch instances:

• Performance profiling
• Collector benchmark
• Parameter filter benchmark
• Filtered element collectors
• Level filter benchmark
• Purging text note types
• The Stopwatch class
• XML family usage report
• Type filter benchmark

Hands-on Revit API Trainings

If you are interested in face-to-face hands-on training in the Revit API, you should take a regular look at the ADN Training Course Schedule and enter "Revit API" as the course name. Here is the short course description.

The next scheduled class that I will be conducting is taking place in Munich, Germany, starting April 25^th (register).

If you are interested in participating in a class, you will benefit enormously by preparing appropriately. The material we provide for that can also be used just as well to efficiently learn the basics of the Revit API for yourself all on your own.

Yet Another Modeless Update

Here is a rather exciting post for me that I spent quite some time on in the past few days.

I recently published an updated version for Revit 2012 of my Revit 2011 modeless loose connector navigator and fixed some flaws pointed out repeatedly by Arnošt Löbel at the same time.

Please refer to the original post for a full description of the application, since here I am focusing only on the modeless interaction with the Idling event.

The main fix I implemented was to instantiate an external application in addition to the original external command, and ensure that I subscribe only once to the Idling event, not every time the command is called.

I actually thought I had understood all the important aspect of modeless interaction with Revit, but was soon to discover how mistaken I was at the time. Maybe there are some important lessons to be learned from the following analysis for you as well?

When writing a later note about the basics of interacting with Revit from an external context, I noticed a few other flaws remaining to be fixed as well.

Most pertinently, like any other call-back, Idling costs time and should be used sparingly.

I was of course already aware of this, but still, it prompted me to rethink and revisit my code once again, and subscribe to the Idling event only while the modeless form is actually being displayed.

The relevant changes that I ended up with in my first attempt were the following:

1. In the external application, do not subscribe to Idling on start-up, just keep a static pointer to the UIControlledApplication instance.
2. In the external command, subscribe to the form Load and FormClosing events.
3. In the form Load and FormClosing events, subscribe to and unsubscribe from the Idling event.

In my naivety, that seemed like a clean and pretty optimal solution to me, and also not overly complex.

Here are some lines of code illustrating this, first subscribing to the form events from the external command Execute method:

  LooseConnectorNavigator navigator
    = new LooseConnectorNavigator(
      data,
      new SetElementId( SetPendingElementId ) );
 
  navigator.Load += new EventHandler( 
    navigator_Load );
 
  navigator.FormClosing 
    += new FormClosingEventHandler( 
      navigator_FormClosing );
 
  navigator.Show( _hWndRevit );

Within the form events, I subscribe to and unsubscribe from the application events:

/// <summary>
/// The application subscribes to the Idling event
/// when the modeless loose connector navigator is
/// displayed.
/// </summary>
void navigator_Load( object sender, EventArgs e )
{
  App.UIControlledApplication.Idling
    += new EventHandler<IdlingEventArgs>( OnIdling );
}
 
/// <summary>
/// The application unsubscribes from the Idling 
/// event as soon as the modeless loose connector 
/// navigator is closed.
/// </summary>
void navigator_FormClosing(
  object sender,
  FormClosingEventArgs e )
{
  App.UIControlledApplication.Idling
    -= new EventHandler<IdlingEventArgs>( OnIdling );
}

Don't do this!

Here is the explanation why.

Luckily, I asked Arnošt for his opinion again, and he replied:

1. Static pointer to the UIControlledApplication instance: I do not think you need the pointer until your external command is called to be executed, if you need it at all (I do not think you do).
2. Subscribe to the form events: you need to subscribe to Idling from the external command Execution method. I do not care about the form events – those are all yours; do whatever you want in them except calling Revit API.
3. Subscribe to and unsubscribe from the Idling event in the form events: you cannot subscribe to or unsubscribe from Revit events from your internal form events. They mean nothing to Revit. You can only make the subscription when Revit calls your app – that is from OnStartup, command.Execute, event handlers (Revit event handlers), etc.

If I am correctly guessing what your goal is, the following should be the workflow:

• Do nothing in OnStartup
• From your Command.Execute subscribe to Idling. The handler should be a method of your external application. Set up an internal Boolean to flag (in the app) that you have done this.
• When the end user clicks a command (a control, I assume) in your dialog:
  • Set an internal variable (let's call it requestId) indicating that it happened.
  • Disable the controls in your dialog including the one the user just clicked (Cancel should still be available though).
• In every OnIdling call, check:
  • If the dialog is no longer visible:
    • Unsubscribe from Idling.
    • Reset the Boolean flag you set in Command.Execute so you know you are not subscribed anymore (this could be done by other means, of course; I am just showing one possible way).
  • If the dialog is still visible:
    • If your requestId is not set, do nothing.
    • If your requestId has been set:
      • Make Revit to do what the user requested.
      • Clear the requestId variable.
      • Enable the controls in your dialog again.
• From OnShutdown you should unsubscribe from Idling if you are still listening to it, and I think you should close your dialog if it has not been closed by the end user yet. I believe it is just a nice thing to do and I would implement it that way.

That feedback was quite a shock to me and took a while to digest.

It also led me to raise a couple of supplementary questions:

Question: Why do you think that I do not need the pointer to the UIControlledApplication instance?

Because I can use the Application property passed in by the command data instead?

Yes, that would simplify things a bit.

Answer: Yes, that is what I meant. You do need to set it in OnStartup, because you get it later again in your Command.Execute and in the OnIdling as well (if you need it there).

Question: Ah yes, I see the difference between subscribing to the Idling event from within the command and within the form Load event. That is something I should improve. I made a mistake there. And you are saying that I cannot even unsubscribe from Idling from the form events?

Answer: No, you cannot. Your form events are completely unattached from Revit. They happen on a different thread. They are like any other methods running on a different thread (not the main thread on which Revit calls out). I believe I've seen this mistake made several times. I also mentioned some of these flaws after looking at the modeless door lister.

Question: This all seems a bit strange and extreme to me. I mean, these are application events, and the application is there forever, as long as the session is active. I understand that officially I cannot touch the Revit API outside of the specified Revit call-back notifications, but still...

Answer: Yes, but not our application (Revit). It is your application – except for the time Revit explicitly calls it, it does not have anything to do in it (and that is mutual).

Question: I was under the assumption that subscribing to an event does not make use of the Revit API. I thought it uses pure .NET functionality and that the application object is available for me to attach an event handler to it, with no use of the Revit API at all.

Answer: That is not correct. All public events have their corresponding framework internally in Revit. In order to subscribe or unsubscribe, something needs to be modified somewhere in Revit, which means allocations/reallocations are likely to be made. That is not going to be safe in a multithreaded environment (I mean, not that it couldn't be in theory, but it might be not in Revit, currently).

Question: Initially I did not see the point of the additional complexity and strict separation between the form and Revit events that you require in your suggestion. After working through these answers of yours, I reread you suggested new algorithm, and it makes complete sense.

Answer: Yes, it does sound a bit complex when you read it first, but like you learned, it is not as complex once you take time to think about it and especially once you start using it that way. I believe the complexity is just due to the multi-threading nature, which is what any modeless interaction is essentially based upon.

Question: I still do not understand the importance of unsubscribing in OnShutdown, since Revit will shut down anyway at that point. Is that for future-proofing, for some future situation in which possibly the add-in may be shut down but the Revit session remains active?

Answer: It is really not critical, but I consider it a nice thing to do and we do log unsubscribed events in journals. You can look at it this way: while it is not essentially important to close all your open files (and other resources) in your application (Windows will close them when the process get killed), an application is considered well behaved if it does close everything, and I always do so.

Question: Does it makes any difference subscribing to the Idling event from the UIApplication class that I obtain from the Execute command data, or using a static variable initialised from the OnStartup UIControlledApplication instead?

Answer: It does matter from where you subscribe and it does not matter if you use UIApplication or UIControlledApplication. Those two application objects share the event repository internally, so subscribing through one is technically identical to subscribing through the other one. In your particular case, I recommended subscribing from your command, because that is when you start needing it, actually; you did not need it in OnStartup yet.

You should not need to store a pointer (a tracking handle in .NET, to be exact) to the application object (to neither one), because it should always be available to you when you are actually permitted to use it – you get it, directly or indirectly, in OnStartup, in command.execute, in Events, in updaters, etc; there is no need to store it anywhere. If you think it simplifies you code, you can keep the UIControlledApplication variable that you initialised in OnStartup, but my implementation would be different (of course, all programmers have different habits, it does not mean that one is better). I would pass the application as an argument to ShowForm, although it seems you do not need to call Subscribe from ShowForm. It looks like you can call Subscribe from your Execute after ShowForm returned success. I would pass the application object to both Subscribe and Unsubscribe as an argument. (It is simply my preferred way of using arguments over having global variables.)

Question: I will follow every single piece of your advice, except passing the arguments to the subscribe methods. I also almost fanatically try to avoid global variables wherever possible. I tried my very best to do that here as well, but it requires me to call two static methods on the App class instead of one from the command Execute method, and to create at least three different overloads of the Subscribe and Unsubscribe methods taking either UIApplication or UIControlledApplication arguments. It also forces the application Subscribe method called from the command to be public instead of private. All in all, that turns out to be just too much.

Answer: Your code is good. I did not realize the need for overloading Unsubscribe – I think you have a point there.

In the end, I improved my implementation to follow Arnošt's advice as follows:

• Moved the OnIdling handler from the external command to the external application.
• Moved the pending element id handling to the external application too.
• Implemented a static singleton LooseConnectorNavigator instance.
• Implemented a static Show method to initialise it in the LooseConnectorNavigator class.
• Subscribe to the FormClosing event to set it to null when the modeless form is closed.
• Implemented a static IsShowing predicate in the LooseConnectorNavigator class to check whether the modeless form is displayed.
• Subscribe to the Idling event from the external command Execute method.
• Unsubscribe from the Idling event in the OnIdling event if the modeless dialog has been closed.
• Ensure that I am unsubscribed from the Idling event and the modeless form is closed in the application OnShutdown handler.

Once this is done, there is actually no reason any longer for the command to communicate with the modeless form anymore. It is better to limit the knowledge of and connection between the various classes as much as possible, so I removed all references of the modeless form from the command class to the application class. This means that I also:

• Moved the static Revit window handle variable and its initialisation to the external application and its OnStartup method.
• Implemented three methods in the application class to show the modeless form, subscribe to and unsubscribe from the Idling event.

The OnStartup method also stores a pointer to the UIControlledApplication instance in a static variable, so that the UIApplication instance does not need to be passed in from the external command when needed:

#region Revit window handle
/// <summary>
/// Revit application window handle, used
/// as parent for modeless dialogue.
/// </summary>
static JtWindowHandle _hWndRevit = null;
#endregion // Revit window handle
 
static UIControlledApplication _a;
 
public Result OnStartup( UIControlledApplication a )
{
  ProductType pt = a.ControlledApplication.Product;
 
  if( ProductType.MEP == pt )
  {
    #region Revit window handle
    // Set up IWin32Window instance encapsulating 
    // main Revit application window handle:
 
    Process process = Process.GetCurrentProcess();
 
    IntPtr h = process.MainWindowHandle;
 
    _hWndRevit = new JtWindowHandle( h );
    #endregion // Revit window handle
 
    _a = a;
 
    return Result.Succeeded;
  }
  else
  {
    return Result.Cancelled;
  }
}

The external command implementation is vastly simplified and disconnected from both the modeless form and the Idling event handling. It no longer even worries about the Revit window handle needed to display the form properly associated with the Revit main window. All it does now is call one single static method ShowForm on the application class before terminating to pass in the current data to display in the form:

  // Cleaned up all the complexity and encapsulated
  // it in one single call to the external application:
 
  App.ShowForm( data );
 
  return Result.Succeeded;

The ShowForm method handles and hides all the complexities of managing the form and the subscription to the Idling event:

public static void ShowForm( 
  SortableBindingList<ConnectorData> data )
{
  LooseConnectorNavigator.Show( data,
    new SetElementId( SetPendingElementId ),
    _hWndRevit );
 
  Subscribe();
}

The methods to subscribe and unsubscribe can even remain private to the application class and ensure that we only subscribe once:

/// <summary>
/// Keep track of our subscription status.
/// </summary>
static bool _subscribing = false;
 
/// <summary>
/// Subscribe to the Idling event if not yet already done.
/// </summary>
static void Subscribe()
{
  if( !_subscribing )
  {
    _a.Idling 
      += new EventHandler<IdlingEventArgs>(
        OnIdling );
 
    _subscribing = true;
  }
}
 
/// <summary>
/// Unsubscribe from the Idling event 
/// if we are currently subscribed.
/// </summary>
static void Unsubscribe()
{
  if( _subscribing )
  {
    _a.Idling 
      -= new EventHandler<IdlingEventArgs>(
        OnIdling );
 
    _subscribing = false;
  }
}

Except for the additional check to unsubscribe from the Idling event if the modeless form has been closed, the Idling event handler is unchanged from the previous implementation:

/// <summary>
/// Revit Idling event handler.
/// Whenever the user has selected an element to 
/// zoom to in the modeless dialogue, the pending
/// element id is set. The event handler picks it
/// up and zooms to it. We are not modifying the
/// Revit document, so it seems we can get away 
/// with not starting a transaction.
/// </summary>
public static void OnIdling(
  object sender,
  IdlingEventArgs ea )
{
  if( !LooseConnectorNavigator.IsShowing )
  {
    Unsubscribe();
  }
 
  int id = _pending_element_id;
 
  if( 0 != id )
  {
    // Support both 2011, where sender is an 
    // Application instance, and 2012, where 
    // it is a UIApplication instance:
 
    UIApplication uiapp
      = sender is UIApplication
        ? sender as UIApplication
        : new UIApplication(
          sender as Application );
 
    UIDocument uidoc
      = uiapp.ActiveUIDocument;
 
    Document doc
      = uidoc.Document;
 
    ElementId eid = new ElementId( id );
    Element e = doc.get_Element( eid );
 
    Debug.Print(
      "Element id {0} requested --> {1}",
      id, new ElementData( e, doc ) );
 
    // Look, mom, no transaction required!
 
    uidoc.Selection.Elements.Clear();
    uidoc.Selection.Elements.Add( e );
    uidoc.ShowElements( e );
 
    _pending_element_id = 0;
  }
}

Finally, in the OnShutdown method, we make sure that we both close the modeless form, if it is open, and unsubscribe from the Idling event, if we are subscribed:

public Result OnShutdown( UIControlledApplication a )
{
  LooseConnectorNavigator.Shutdown();
 
  Unsubscribe();
 
  return Result.Succeeded;
}

The code itself did not change that much from my original implementation. Most of these changes just involved juggling existing snippets around to satisfy the recommendations listed above, and adding some trivial logic.

As far as I can tell, it all still works, and it feels better than ever before :-)

I think this has been nagging at me subconsciously ever since I did not dive in deep into the door lister flaws highlighted by Arnošt, so it is a real relief to have it finally sorted out now.

For comparison purposes, here are two separate downloads, loose_connectors_9.zip containing the flawed version 2012.0.0.9 from my initial attempt before receiving and finally understanding the additional advice, and loose_connectors_11.zip containing the fixed and hopefully final version 2012.0.0.11. Don't mix them up, please!

Changing the Type of Many Instances

Did you ever run into a performance problem changing the type of a large number of family instances?

Well, is you use the Element Symbol property or ChangeTypeId method to change them one by one, such as we did to set the type of a tag, elbow fitting or cable tray, that may trigger a regeneration within Revit for each call, even if you are using manual regeneration mode and not explicitly asking for a regeneration yourself. Changing a family instance type requires subsequent regeneration.

Bad news.

But hey, wait, there is good news as well!

You may not have noticed another overload of the Element.ChangeTypeId method.

The second overload is static, does not operate on only specific single element instance, and instead takes a whole collection of element instances to operate on.

And the good news is that that overload changes the type of all elements in the given set at once, with only one regeneration at the end.

Give it a whirl and let us know whether it helps.

Addendum: As Rudolf Honke points out, you can use the method Element.IsValidType taking the same three arguments Document, ICollection elementIds, ElementId typeId to check beforehand whether all elements can accept the new element type. Thank you, Rudolf!

Extensible Storage Features

Here is a nice hot topic to start off the week. We already talked about the new Revit 2012 API EStorage or extensible storage functionality and presented example code to store a map or dictionary in it.

Here are a few other interesting notes and issues related to this which have cropped up, contributed and pointed out by Steven Mycynek:

1. Intended use of EStorage.
2. Handling large amounts of data in EStorage.
3. EStorage is self-documenting.
4. EStorage is object-oriented in two ways.
5. Read/Write permissions.
6. Modification of EStorage data on an element type.
7. Handling of ElementId data in EStorage.
8. Retrieving elements with a specific schema entity.
9. Checking for a valid entity on an element.
10. One entity per element.
11. Schemata remain in memory.

The automatic translation of element ids is one of the absolute highlights of this new technology that I was previously not aware of.

1. Intended Use of EStorage

Question: When should I use EStorage versus the existing technique of storing my data in text form in an XML-based hidden shared parameter?

Answer: EStorage is for storing a lot of complex bits of data that you want to organize into a class-like structure, complete with units, documentation, etc. If you already have an XML file that does all of that already, and you don't find using a single hidden shared parameter to be a burden, you might want to go ahead and keep using it. On the other hand, if you didn't already have an XML schema in place and had a huge variety of data you didn't want to convert to a text representation, I'd recommend starting out with EStorage.

2. Handling Large Amounts of Data in EStorage

Question: I am thinking of storing a large amount of data on a number of BIM elements. What approach would you recommend?

Answer: The intended and recommended use of EStorage does not include storing huge amounts of data in the model. For instance, we have seen issues with developers trying to store very heavy analysis data in hundreds of MB spread across thousands of elements, all loaded at start-up. Such usage will degrade performance. If you store large amounts of data across thousands of elements, do not expect an instant load time.

If you wish to store a large amount of data on individual elements, this should not be a problem. For instance, storing something like a .png file on a wall element is no issue at all, whereas it would be an issue to store a dozen .png files on every wall element and extract all of them at once, even if you only need the data for one at a given time.

One of the strengths of EStorage is its handling of arrays of objects or sub-entities and different schemas in general rather than one large segment of data that needs to be read in its entirety and deserialized all at once. I recommend taking advantage of this and only loading what you actually need for a given task. For small loads of data, this might not seem necessary, but when you get into many MB of data, it makes a difference.

3. EStorage is Self-documenting

When you create a schema, you are creating documentation. Be sure to fill out the documentation strings for each field – they will help you in your development process and others when they use your schema. What's more, since you can look up a schema by Guid, if you want to share a document with a schema with someone else, all they need is the Guid to look it up and read your structure and documentation comments. This might be a good opportunity to either use the SchemaWrapperTools included with the ExtensibleStorageManager SDK sample (or a simpler, similar tool) to print out a schema's field definitions and documentation strings from a single GUID input.

4. EStorage is Object-oriented in Two Ways

Not only is a given schema entity structured into named fields, but each entity is placed on elements relative to the data itself, as opposed to one large blob that you must read in its entirety to unpack. This goes along with what the recommendation above about not reading all storage at start-up. Since you can choose which elements to process, you have the opportunity to only load what you need an automatically have an association between data and a specific element – shared parameters can't do this.

5. Read/Write Permissions

This is another area that goes beyond shared parameters. While your schema definition is public, you can restrict who reads and writes schema data based to a specific vendor or a specific application from that vendor.

6. Modification of EStorage Data on an Element Type

Question: When transferring types from one project to another using Transfer Project Standards, it only copies across types that are different. If you change a parameter on a wall type that exists in both projects, then it gives you the option of copying over "new" types or overwriting existing types. However, if the parameters are unchanged but the schema data is different, it treats the wall types as identical, so does not give the option of copying over the wall type.

Are element types with different EStorage data attached to them treated as the same or not?

Answer: Any parameter based change, hidden or not, will trigger a new type to be recognized. EStorage, however, is not a parameter-based transaction, so those rules don't apply. Therefore, element types with differing EStorage attached to them are still treated as the same in this case.

7. Handling of ElementId Data in EStorage

Question: What happens to element ids stored in EStorage?

Answer: When you store an ElementId using EStorage and that ElementId gets remapped because the element is deleted or updated, e.g. because of a worksharing update, your stored ElementId is also automatically remapped to the new ElementId value. This is one strong advantage for using EStorage over text or raw numbers to store ElementIds – the tracking for element updates is handled automatically, so you can be sure that your ElementIds will remain valid. If the element is deleted, your ElementId will be set to ElementId.InvalidElementId.

8. Retrieving Elements with a Specific Schema Entity

Question: How can I retrieve all elements that have data from a certain schema attached to them? Optimally, I think that should be a filtered element collector option.

Answer: Right now, you must do a manual iteration of all elements. There may be a project to add a filter as you describe in the future, but we make no promises about any future features whatsoever.

9. Checking for a Valid Entity on an Element

Question: If I register a schema and then select an element that has no entity for that schema attached to it, I would expect the following call to return null:

  Entity ent = e.GetEntity( schema );

It does not. Instead, it returns a valid entity pointing to a null schema. To handle this, I expanded my check to this:

  if( null == ent || null == ent.Schema ) ...

Answer: Use the Entity.IsValid method to check to see if the entity you received from GetEntity actually has data of a given schema.

10. One Entity per Element

Question: Is only one entity per schema possible per Revit element?

Answer: Yes and no. There is no way to have more than one entity of a given schema per element via the GetEntity/SetEntity operations. However, you could always create another schema with more than one sub-entities of a given schema type, including array fields and map fields.

11. Schemata Remain in Memory

Question: Is it true that once a schema has been loaded into Revit memory, it never disappears again until the session ends?

Answer: That is true. A schema is available per use on the session level, even if a new document is created. Entities are associated with specific documents.

Many thanks to Steve for all of these tips!

No Multithreading in Revit

I repeatedly hear from developers asking whether multithreading can be used in conjunction with the Revit API. The short answer is no.

To our surprise, we just noticed that the Truss SDK sample does demonstrate a use of multithreading. That is an oversight and you should not rely on this working properly.

Here is the considered statement of Scott Conover, Software Development Manager of the Revit API, on the current state of multithreading and Revit:

"Revit's internals make use of multiprocessing in only a few select isolated locations. None of these locations currently encompass the code in the Revit API, or any part of it. Thus Autodesk does not recommend making any calls to the Revit API from within simultaneously executing parallel threads. It may be that some part of the Revit API is isolated enough to be able to execute successfully from within such threading code in a test environment; this should not be taken to be a guarantee that the same source code will function for any model or situation, or that a future change in Revit will not cause this code to cease to function."

I hope this clarifies the situation.

Truss SDK Sample Enhancement

The Truss SDK sample contains the following code and comments:

  // get all the beam types
  // because GetBeamTypes() takes a long
  // time, so call it in a new thread
 
  Thread newThread = new Thread(
    new ThreadStart( GetBeamTypes ) );
 
  newThread.Start();

Here, GetBeamTypes is using the Revit API methods FilteredElementCollector and parameter access methods.

As said, this is not supported; Revit API access is required to be single threaded. It is an interesting side note that it apparently works, but this cannot be relied on and this code should definitely not be reused.

Actually, the sample would be faster if it made use of more of the FilteredElementCollector capabilities. The implementation of this sample predated the introduction of filtered element collectors in Revit 2011:

  m_beamTypes = from elem in
    new FilteredElementCollector( doc )
      .OfClass(typeof(FamilySymbol))
      .ToElements()
    let type = elem as FamilySymbol
    where type != null 
      && type.Category != null  
      && type.Category.Name == "Structural Framing"
    select type;

A better implementation might be:

  m_beamTypes 
    = from elem in new FilteredElementCollector( 
          m_activeDocument.Document )
        .OfClass( typeof( FamilySymbol ) )
        .OfCategory( BuiltInCategory.OST_StructuralFraming )
      let type = elem as FamilySymbol
      select type; 

This uses a quick category filter and avoids calling ToElements, which is unnecessary, as the filtered element collector itself is already an IEnumerable.

Other examples of using multithreading in perfectly valid ways in conjunction with the Revit API are provided by the APIAppStartup splash window and the AnalysisVisualizationFramework MultithreadedCalculation Revit SDK samples, where the separate threads do not make calls into Revit.

Loading Only Selected Family Types

As you probably know, the Revit API provides two methods to load family types, also known as symbols: LoadFamilySymbol, which loads an individual type, and LoadFamily, which loads the entire family and all the types it defines. Use of the latter method can be quite time consuming and wasteful, especially if you only require a few of the types included.

In the past we also discussed a couple of other issues on handling family types, such as creating a new family type using the Duplicate method and unloading an unused type.

Erez van Leeuwen of Nordined voiced the interesting request of how to avoid the overhead of calling LoadFamily and loading all its types by presenting a list of the types to the user and asking her which ones are actually required, to which Saikat Bhattacharya came up with the following solution:

Question: Revit provides multiple ways of loading a family. The two 'Load Families' options displayed in the Revit ribbon are

• Home > Component > Load Family
• Insert > Load Family

The first one loads a family and places an instance of it, and the second one only loads the family. If the chosen family has a TXT file associated with it containing different types, Revit shows a popup window where you can select the types you want to load.

Using the API to load a family, I can choose between the LoadFamily and LoadFamilySymbol methods. Is there any other function I can use to load a family and have Revit pop up the dialog to choose which types I want loaded?

If this does not exist, can you tell me if there is a way to read which types exist within a family?

Answer: There Revit API does not provide any method which will pop up a dialogue listing the types contained in a family.

You could load the entire family using the LoadFamily method and then use the Family.Symbols method to list all the types defined in it. The Revit API help file RevitAPI.chm does in fact include a code snippet showing how to iterate through all the symbols in a loaded family:

public void GetInfoForSymbols( Family family )
{
  StringBuilder message = new StringBuilder( 
    "Selected element's family name is : " 
    + family.Name );
 
  if( family.Symbols.IsEmpty )
  {
    message.AppendLine( 
      "Contains no family symbols." );
  }
  else
  {
    message.AppendLine( 
      "The family symbols contained"
      + " in this family are : " );
 
    // Get family symbols contained in this family
 
    foreach( FamilySymbol sym in family.Symbols )
    {
      // Get family symbol name
 
      message.AppendLine( "\nName: " + sym.Name );
 
      foreach( Material material in sym.Materials )
      {
        message.AppendLine( 
          "\tMaterial: " + material.Name );
      }
    }
  }
  TaskDialog.Show( "Revit", message.ToString() );
}

The problem is, of course, that this loads the entire family and all its symbols up front. Doing this for all the families needed will cause the Revit project to grow and become bigger very fast.

Access to and iteration over all the family symbols without permanently loading the entire family into the project file can be achieved using the power of transactions in the Revit API.

You can load a family within a transaction, read through its symbols, and then roll back the transaction to undo the loading of the family. During this process, the names of the symbols contained in the loaded family can be extracted and saved. Subsequently, a new transaction can be used to call the LoadFamilySymbol method to load a specific symbol based on the names retrieved in the previous step. The following code snippet illustrates this approach and is quite simple and self-explanatory:

  string filename = @"C:\Documents and Settings"
    + "\All Users\Application Data\Autodesk"
    + "\RAC 2011\Metric Library\Columns"
    + "\M_Round Column.rfa";
 
  UIApplication app = commandData.Application;
  Document doc = app.ActiveUIDocument.Document;
 
  Transaction trans = new Transaction( 
    doc, "FakeLoading" );
 
  trans.Start();
 
  Family family = null;
  string symbName = String.Empty;
  int counter = 0;
  if( doc.LoadFamily( filename, out family ) )
  {
    foreach( FamilySymbol symb in family.Symbols )
    {
      TaskDialog.Show( "Symbol names", symb.Name );
      if( counter == 0 )
      {
        symbName = symb.Name;
      }
      counter++;
    }
  }
  trans.RollBack();
 
  Transaction transNew = new Transaction( 
    doc, "RealLoading" );
 
  transNew.Start();
 
  if( doc.LoadFamilySymbol( filename, symbName ) )
  {
    TaskDialog.Show( "Status", 
      "We managed to load only one desired symbol!" );
  }
  transNew.Commit();

Question: Of course, loading the whole family, rolling everything back and reloading the required types might considerably slow down the complete loading operation.

If the whole family is already being loaded, it might be faster to only unload or delete the unwanted types.

Is there a way to unload specific types? Within Revit I can just delete the unwanted types by pressing delete or I can purge them out. Can I do this via the API?

Answer: As mentioned above, to unload specific family types, you can simply delete them from the Revit document object.

If you want to unload more than one type, you can collect all the types that you wish to unload in an ElementSet or create an ICollection of their element ids and use one of the following overloads of the Document.Delete method:

• Delete(ElementSet)
• Delete(ICollection(Of ElementId))

While editing this, another thought crossed my mind:

The approach above is based on reading the family into the project in order to determine what types it contains. There may be another possible approach, of course, not loading the family into the project but opening the family file as a separate background document via the API and analysing that using its family manager object instead. You can iterate the types that way as well. I don't know whether there is also any need to handle a possibly associated TXT file, and how that would affect the list of types returned by the family manager, but it might be worth a try.

Performant Hardware

I spent all day yesterday in trains, which was unfortunate, since it was the most beautiful Sunday, and springtime is in full bloom. It also forced upon me some unfortunate comparisons of the Swiss and Italian train systems. Needless to say, I arrived later than expected.

Still, I ended up happily back in Verona, Italy, where I started seriously learning Italian two years ago, for a repeat visit to provide a Revit API training class to Steel & Graphics srl.

One funny thing about Verona is that it has almost exactly the same flag as Sweden, where I grew up:

It is also the city of Shakespeare's Romeo and Juliet. Maybe I can manage to get to Sirmione and the Sirmio peninsula today and complete the final training preparations there.

Meanwhile, here is a non-API related question affecting all Revit users from Augusto Gonçalves:

Question: To specify a new machine for Revit, what should I consider, i.e. spend more money on? Amount of memory? Speed of memory? Processor clock? Multi-processors? HD speed?

Answer: Anthony Hauck provides a very succinct answer:

In order, and dependent on how large the models you wish to edit are:

1. More RAM
2. Faster Processor
3. More Processers
4. Faster RAM
5. Faster HD

For a more complete and long-winded answer, you may want to peruse the Revit model performance technical note pointed out by Martin Schmid.

It has been around for quite a while now and includes some detailed software optimisation suggestions as well, which are well worth reading and understanding for add-in developers as well as end users, including:

• Revit Platform Model Optimization and Best Practices
  • Arrays
  • Constraints
  • Design Options
  • DWG Files
  • Family Creation
  • Importing & Linking
  • Modeling Economically
  • Project Templates
  • Railings
  • Raster Images
  • Stairs
  • Upgrading Linked Projects to a New Version of Revit
  • Views
  • Volumes - Rooms and Spaces
  • Worksets
  • Worksharing
• Revit Structure 2010 Software Optimization and Best Practices
• Revit MEP 2010 Software Optimization and Best Practices

Note that this document applies to Revit 2010, although I am assuming that most remains valid for Revit 2012 as well.