The Building Coder

Title Block of Sheet

Here is a question that crops up now and then in different variations, on how to access the title block information of a sheet:

Question: My drawing list routine exports various sheet view information to a spreadsheet. I would like to include the name of the title block family that is associated with the view. What is the best way to find it? Do I need to loop through family instances, and do a reverse lookup?

My snooping tool freaks out whenever I select a title block family from the list of family instances, so I don't know if the host of that family instance will tie it to the specific sheet view?

Answer: If your version of RvtMgdDbg fails to display some information that you are interested in, I suggest you debug it and fix the problem, e.g. start it in the debugger and add an exception handler to the offending code.

I am confused by your statement 'name of the title block family that is associated with the view'. Do you mean sheet instead of view? In general, each sheet has a title block associated with it, and then hosts multiple views.

To see which title block is added when I add a new sheet to the model, I use a technique to track all new elements added. This technique uses the Revit API introduction labs Lab 2-1 element lister. I create a file containing a list of all elements in the BIM before and after adding the sheet and then compare them. Here is the result, in this case the list of elements created by adding a new sheet to the project:

C:\tmp\ >diff RevitElementsBeforeSheet.txt RevitElementsAfterSheet.txt
2581a2582,2595
> Id=137766; Class=ViewSheet; Category=Sheets; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a26
> Id=137767; Class=Element; Category=?; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a27
> Id=137768; Class=Element; Category=Viewports; Name=Title w Line; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a28
> Id=137769; Class=Element; Category=?; Name=A101 - Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a29
> Id=137770; Class=Element; Category=Work Plane Grid; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2a
> Id=137771; Class=SketchPlane; Category=?; Name=Unnamed; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2b
> Id=137772; Class=FamilyInstance; Category=Title Blocks; Name=A0 metric; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2c
> Id=137773; Class=View; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2d
> Id=137774; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2e
> Id=137775; Class=Element; Category=Viewports; Name=Title w Line; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a2f
> Id=137776; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a30
> Id=137777; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a31
> Id=137778; Class=Element; Category=?; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a32
> Id=137779; Class=Element; Category=Schedule Graphics; Name=; UniqueId=7e3fda1f-b209-4185-9037-575bba9df262-00021a33

If these lines are truncated in the browser view, you can copy and paste them to an editor to see the full text.

From this you can see that the new sheet has the element id 137766, and the associated title block is a FamilyInstance with id 137772.

Once the new elements have been identified, the Revit API introduction labs built-in parameter checker can be used to explore their data. In the Revit user interface, I can select the sheet via Modify > Element ID > Select by ID > 137766 > OK and then invoke the built-in parameter checker to explore its parameters.

Looking at the sheet parameters sorted by type and going through all parameters whose value is an element id, I see that there is no reference to 137772, so the sheet does not have a parameter explicitly specifying the title block by its element id, as one might have hoped.

Looking at the title block parameters yields better results, among others the family that you are asking for and the sheet number:

ELEM_FAMILY_AND_TYPE_PARAM  
  Family and Type  
  ElementId 28295   
  Title Blocks 'A0 metric'

SHEET_NUMBER                
  Sheet Number     
  String            
  A101

This means that although we have not found a pointer from the sheet to the title block, we have found information about the inverse relationship from the title block to the sheet. We can therefore use the relationship inverter algorithm to identify the title block from the sheet, if needed.

I also had an idea for another, completely different approach: I tried deleting the sheet again after it had been added and checked the resulting list of elements after that operation:

C:\tmp\ >diff 
  RevitElementsAfterSheetDelete.txt 
  RevitElementsBeforeSheet.txt

Files are identical.

Happily, as it turns out, the new list of elements is exactly the same as it was before the sheet was added. This means that the deletion of the sheet caused the associated title block to be deleted as well. This means that we can probably make use of the doc.Delete method to detect dependent elements. Using that approach, you delete the sheet inside a transaction, save the list of element ids returned by the doc.Delete method, and abort the transaction to undo the deletion operation. The list of ids will then include element ids of both the sheet and the associated title block.

I hope this resolves your issue twice over.

Title Block Modification

By the way, Ricardo Cardial raised a related question on how to modify the text labels defined in the title block, which we will partially repeat here in order to ensure that these useful ideas do not get lost:

Question: How can we change the information of the scale label shown in title blocks? When we have two different scales on the sheet, the value is 'As indicated'. I would like to change that, for instance to translate it to French or Italian.

Answer: Look at the original comment for the full answer, which consists of two parts. They can be summarised like this:

• Read the data through the built-in parameter SHEET_SCALE with the display name 'Scale'. It is a string-valued parameter and is unfortunately marked as read-only.
• Modify the family file used to define the title block of the sheet.

Room Occupancy

Shifali asked a question on reading and writing the room occupancy:

Question: We get the document from ExternalCommandData object's Application and the project information in document. We need to store the construction type of the current document or project file. Moreover, we get the Room elements of the document but we need to store the occupancy type of each room for applying the International Building Code for compliance reports of the project.

We also need access to the BuildingConstruction and BuildingType in the document ProjectInformation.gbXMLSettings.

Answer: I started by looking at the room occupancy issue, and found that this is actually very simple and straightforward and has been covered in numerous previous posts dealing with the exploration of element parameters. Still, since this is a very typical and recurring issue, I will happily revisit it.

I started up Revit and created a new model with a room or two. Left clicking one of these, and selecting Element Properties... I see the parameter that I presume you are looking for listed as Occupancy under the Identity Data heading. So that is where to find this data in the user interface. I entered an arbitrary string value there in order to start exploring how to access the same data programmatically.

Next, I start up RvtMgdDbg (for 2010) and use that to look at the room element parameters through the API via Add-Ins > RvtMgdDbg > Snoop Current Selection... > Parameters > Occupancy. It shows the same string I just entered, so I seem to have found the required data. Since I would like to access it language independently, I need to determine the built-in parameter enumeration value for this parameter, if one exists. If I don't care about that, I can use the language dependent parameter name "Occupancy" to identify the data. The built-in parameter can be determined by using the Built-in Enums Snoop or Built-in Enums Map buttons in RvtMgdDbg, which show me that the built-in parameter I am looking for is ROOM_OCCUPANCY.

I can also look at the element parameters and see the associated built-in parameters using the Revit API introduction labs built-in parameter checker.

Both of these tools show me that the parameter is string valued and read-write, so there should be no problem modifying it.

I implemented a new Building Coder sample command CmdSetRoomOccupancy to demonstrate making use of this to read and write the parameter and do nothing else. For experienced Revit developers, this is a rather trivial command, since all it does is read and write the value of a single element parameter. Still, it should be useful to point people to in the future who raise this frequently asked question. The command retrieves either the currently selected rooms or all rooms in the model if nothing has been preselected using my GetSelectedElementsOrAll utility method. For each room, its occupancy parameter is read and incremented. This is achieved using the BumpStringSuffix helper method.

BumpStringSuffix increments the numerical suffix of a given string. If the string already ends in a sequence of digits representing a number, it returns a string with the number incremented by one. Otherwise, it returns the original string with a suffix "1" appended. In case the original string is null, "1" is returned:

static char[] _digits = null;

static string BumpStringSuffix( string s )
{
  if( null == s || 0 == s.Length )
  {
    return "1";
  }
  if( null == _digits )
  {
    _digits = new char[] {
      '0', '1', '2', '3', '4', 
      '5', '6', '7', '8', '9'
    };
  }
  int n = s.Length;
  string t = s.TrimEnd( _digits );
  if( t.Length == n )
  {
    t += "1";
  }
  else
  {
    n = t.Length;
    n = int.Parse( s.Substring( n ) );
    ++n;
    t += n.ToString();
  }
  return t;
}

Here is the method BumpOccupancy which makes use of BumpStringSuffix to increment the room occupancy parameter on a given room element. It reads the value of the element ROOM_OCCUPANCY parameter. If it ends in a number, it increments that number, otherwise it appends "1":

static void BumpOccupancy( Element e )
{
  Parameter p = e.get_Parameter( 
    BuiltInParameter.ROOM_OCCUPANCY );
 
  if( null == p )
  {
    Debug.Print(
      "{0} has no room occupancy parameter.",
      Util.ElementDescription( e ) );
  }
  else
  {
    string occupancy = p.AsString();
 
    string newOccupancy = BumpStringSuffix( 
      occupancy );
 
    p.Set( newOccupancy );
  }
}

Now we can apply the BumpOccupancy method to all or the currently selected rooms in the model. Here is the entire code of our external command Execute method which does so:

public CmdResult Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  Application app = commandData.Application;
  Document doc = app.ActiveDocument;
 
  List<Element> rooms = new List<Element>();
  if( !Util.GetSelectedElementsOrAll(
    rooms, doc, typeof( Room ) ) )
  {
    Selection sel = doc.Selection;
    message = ( 0 < sel.Elements.Size )
      ? "Please select some room elements."
      : "No room elements found.";
    return CmdResult.Failed;
  }
  foreach( Room room in rooms )
  {
    BumpOccupancy( room );
  }
  return CmdResult.Succeeded;
}

Here is version 1.1.0.54 of the complete Building Coder sample source code and Visual Studio solution including the new command.

So, I would hope that this amply answers the question on accessing and modifying the room occupancy, and also serves as a model for further simple parameter setting explorations.

Turning to look at the BuildingConstruction and BuildingType values in the ProjectInformation gbXMLSettings, I once again resort to RvtMgdDbg. I select Add-Ins > RvtMgdDbg > Snoop Db... > ProjectInfo > Project Information 69280 > gbXML Settings ... and crash. Well, first a message was displayed saying that this is only available in Revit MEP.

Ok, I restarted in Revit MEP and navigated through the same path down to the gbXML settings, which I can enter and explore this time. I see the building construction and building type properties. The former is an object, the latter displays a value kOffice.

Actually, I also see en entry for the gbXMLParamElem in the root directory of the RvtMgdDbg database snoop:

The element id shows me that this is the same object as the one stored in the project information.

So obviously there is no problem accessing this data either. gbXMLParamElem is one of the classes defined by the Revit API and can be accessed using the standard Revit element filters, for instance. The desired properties are both members of this class:

• BuildingConstruction returns the Project Information Building Construction object.
• BuildingType gets or sets the Project Information Building Type.

Obfuscation Tools

We already explained the need for and basics of obfuscation, and yet developers I meet are often still surprised to discover how easy it is to decompile their .NET application and obtain the original source code back from the released .NET assembly DLL. We can add new information on this topic and present details on some available tools now, because Greg Wesner of Autodesk kindly agreed to share his personal experience and research results using obfuscation with Revit applications:

First of all, here is a list of most of the available obfuscators with some additional background information and further links.

I gave up on Dotfuscator because I was having problems obfuscating things for Revit and their interface was not very good. You have to exclude from obfuscation any methods that external apps call into or access. This would include entry points like IExternalCommand and IExternalApplication methods. Virtually any DLL can be obfuscated to the point where it will not run.

I now use {smartassembly} which is working quite well for me. It’s in the medium price range of the tools out there. It does a fairly good job of drilling into the dependencies itself and determining what can and cannot be obfuscated. Setting up the various options in these tools will make all the difference.

To be honest, what really sold me on {smartassembly} was the fact that their trial software was a fully functional installation of their product. You just can’t ship what you obfuscate until you pay for it. Dotfuscator and another one I tried from Rustemsoft called Skater were both limited versions of their software, so it was very difficult to determine how effective they would be. Skater in particular did not do a very good job of string mangling and the result was barely different from the code. If you are going to provide an evaluation copy, is it really a good idea to limit it to the point that it is unimpressive?

Here are some cool features in {smartassembly} beyond obfuscation:

1. It can merge in dependent DLLs or embed them. Merging them will improve performance, embedding them just makes it more convenient, because your deliverable can be just one file.
2. It will prune code that will never get executed. Actually, I find this to be a nice analysis tool for applications that are developed over long periods of time – I’m amazed at how much code I write that I eventually end up abandoning.
3. It will add confusing metadata to the DLL so that .NET Reflector and MS IL Disassembler cannot view it. This is a huge advantage because now you need hacking tools even to see what methods are exposed, and this provides a level of protection for even those methods that you could not obfuscate.
4. It will sign your assembly with a strong name after obfuscation.
5. It has some memory optimizations that can improve memory usage, which I have not tested.

My approach in setting up my projects was to enable all the security features I could to make it as safe as possible. Then obfuscate the DLL and load and test it. As I mentioned, {smartassembly} does a fairly good job of realizing that some methods are entry points for the DLL and it cannot mangle those signatures. A couple of times I ended up with an obfuscated DLL that would not run. So from there I went back in and began disabling features. I start by excluding whole classes from obfuscation. Once I find the class or classes that cannot be mangled, I try drilling down to see if there are just some particular methods that need to be excluded. This is all I have really needed to do to get it working for me.

I also considered .NET Reactor. The price is really competitive and it has the added feature of creating time bombed versions of your software. But a review I read said it had difficulty with complex applications.

I would have liked more time to evaluate this to determine if it would have worked for me. I highly recommend trying out more than one of these tools before making a decision.

Obviously, these are just unofficial personal opinions, like everything else stated in this blog.

Shared Parameter Visibility

Here is an interesting question and a workaround for a problem accessing the visibility property on shared parameters, raised by Jon Smith of Construction Industry Solutions COINS:

Question: We need to be able to tell if a parameter is visible or invisible, so we can honour that setting in our own interface and not display it if set to invisible. We try to do this as follows:

ExternalDefinition externalDef 
  = param.Definition as ExternalDefinition;

if( externalDef == null || externalDef.Visible )
{
  // show the parameter
}

However, all definitions returned by this method for any parameter whatsoever are InternalDefinition, including for shared parameters that have been marked as invisible. The InternalDefinition does not have the Visible property exposed.

It also seems, from looking in the Visual Studio watch window, that the base Definition class does contain a visible property (whose value is correct), but it is internal and not exposed:

Answer: Yes, there is a known issue accessing the definition class of a shared parameter. The Parameter.Definition property on a shared parameter erroneously returns an InternalDefinition, even though it actually should be returning an ExternalDefinition. This issue is being looked into and will be resolved soon. It may be possible to implement a workaround to get the proper external definition through the sequence Application.OpenSharedParameterFile > DefinitionFile > DefinitionGroup > ExternalDefinition.

Happily, if Visual Studio is able to display the visibility property that you are interested in, then you should also be able to access it from your application source code using .NET reflection.

Response: Excellent - thanks for the information on the issue with the Parameter.Definition property, and thanks for pointing me towards using reflection. We have created the following function that solves the problem for the current release:

 
public static bool isParameterVisible( Parameter p )
{
  bool bParameterIsVisible = true;
 
  try
  {
    BindingFlags flags 
      = BindingFlags.Instance 
      | BindingFlags.FlattenHierarchy 
      | BindingFlags.Public 
      | BindingFlags.NonPublic 
      | BindingFlags.InvokeMethod;
 
    Type t = typeof( Definition );

    object result = t.InvokeMember( 
      "get_Visible", flags, null, p.Definition, null );
 
    if( null != result && result is Boolean )
    {
      bParameterIsVisible = (Boolean) result;
    }
  }
  catch( System.Exception )
  {
    // in case of any problems, assume parameter is visible
  }
  return bParameterIsVisible;
}

Many thanks to Jon for this cool little workaround!

Library Paths

Here is a question posted by Edgar on how to modify the application options library paths:

Question: I'm having trouble updating the Revit options for library paths. I'm not sure what I'm missing to update back to the database.

Answer: Since the library paths managed by the LibraryPaths property on the Autodesk.Revit.Options.Application class is a StringStringMap, this question is mostly on how to extract, add and modify data in such a collection.

A StringStringMap is simply a dictionary mapping a set of keys to a corresponding set of values. In this case, both the key and the value data type is string.

To begin with, here is a little utility method to list the contents of a StringStringMap and print out an explanatory header beforehand:

 
void PrintMap( StringStringMap map, string description )
{
  Debug.Print( "\n{0}:\n", description );
 
  StringStringMapIterator it = map.ForwardIterator();
 
  while( it.MoveNext() )
  {
    Debug.Print( "{0} -> {1}", it.Key, it.Current );
  }
}

We use a forward iterator to iterate over the contents, consisting of key-value pairs. The keys and values are printed out one by one. Their data is read from the iterator Key and Current properties, respectively.

To add a new key and value pair to the string map, you can use the Insert method. Modification of an existing value can be accomplished using set_Item.

I implemented a new Building Coder sample external command CmdLibraryPaths to test and demonstrate this. Here is the code of its Execute method:

Application app = commandData.Application;
 
StringStringMap map = app.Options.LibraryPaths;
 
PrintMap( map, "Initial application options library paths" );
 
string key = "ImperialTestCreate";
string value = @"C:\Documents and Settings\All Users\Application Data\Autodesk\RAC 2010\Imperial Library\Detail Components";
 
map.Insert( key, value );
 
PrintMap( map, "After adding 'ImperialTestCreate' key" );
 
map.set_Item( key, @"C:\Temp" );
 
PrintMap( map, "After modifying 'ImperialTestCreate' key" );
 
return CmdResult.Succeeded;

Launching this command will produce the following output in the Visual Studio debug output window:

Initial application options library paths:

Metric Library -> C:\Program Files\Autodesk Revit Architecture 2010\Program\Metric Library
Metric Detail Library -> C:\Program Files\Autodesk Revit Architecture 2010\Program\Metric Library\Detail Components

After adding 'ImperialTestCreate' key:

ImperialTestCreate -> C:\Documents and Settings\All Users\Application Data\Autodesk\RAC 2010\Imperial Library\Detail Components
Metric Library -> C:\Program Files\Autodesk Revit Architecture 2010\Program\Metric Library
Metric Detail Library -> C:\Program Files\Autodesk Revit Architecture 2010\Program\Metric Library\Detail Components

After modifying 'ImperialTestCreate' key:

ImperialTestCreate -> C:\Temp
Metric Library -> C:\Program Files\Autodesk Revit Architecture 2010\Program\Metric Library
Metric Detail Library -> C:\Program Files\Autodesk Revit Architecture 2010\Program\Metric Library\Detail Components

Truncated lines can be seen in full by copy and pasting into an editor.

Once I got this far, I started trying to see the results of my changes in the Revit user interface. The library paths are displayed by clicking on the big R button, the main menu button on the upper left of the Revit application window, and then selecting Options > File Locations > Places...

To my surprise, I saw no changes. I first thought that we added and modified a new key 'ImperialTestCreate' which is ignored by Revit. So I added a modification to one of the pre-existing Revit keys, and set the value of 'Metric Detail Library' to 'C:\Temp' as well. I still saw no changes.

It then dawned upon me that the statement 'map = app.Options.LibraryPaths' copies the current application options library paths into my own private StringStringMap instance stored in my local variable 'map'. All the changes I made are in my own local copy. To have any effect in Revit, I need to write back the changes into the Revit application object data, for instance using a statement such as 'app.Options.LibraryPaths = map'. After doing so, both the updated existing key as well as the new one added by me is displayed as expected in the user interface:

The updated code of the Execute method now looks like this:

Application app = commandData.Application;
 
StringStringMap map = app.Options.LibraryPaths;
 
PrintMap( map, "Initial application options library paths" );
 
string key = "ImperialTestCreate";
string value = @"C:\Documents and Settings\All Users\Application Data\Autodesk\RAC 2010\Imperial Library\Detail Components";
 
map.Insert( key, value );
 
PrintMap( map, "After adding 'ImperialTestCreate' key" );
 
map.set_Item( key, @"C:\Temp" );
 
PrintMap( map, "After modifying 'ImperialTestCreate' key" );
 
map.set_Item( "Metric Detail Library", @"C:\Temp" );
 
PrintMap( map, "After modifying 'Metric Detail Library' key" );
 
app.Options.LibraryPaths = map;
 
return CmdResult.Succeeded;

Here is version 1.1.0.45 of the complete Building Coder sample source code and Visual Studio solution including the new command.

Response: This works perfectly, thank you for the thorough explanation. Also, Thank you for the goodies!

Fixing RvtMgdDbg for MEP Connectors

Still working on preparations for the MEP webcast mentioned last week, I notice that RvtMgdDbg is having trouble displaying the connectors on electrical components, throwing an exception saying

Angle is available only for connectors of DomainHavc and DomainPiping.

The method I describe here to fix this problem can be used by anyone who runs into a problem with RvtMgdDbg. It is not limited to the case of MEP connectors, and intended more as an example and a how-to on how to fix RvtMgdDbg to display specific information that you are interested in.

Luckily, RvtMgdDbg is provided in source code format, and everybody can debug it and fix problems for themselves as they see fit. In my case, I debugged the RvtMgdDbg code and traced the problem to the implementation of the overloaded method Stream( ArrayList data, Connector connector ) in the module Snoop > CollectorExts > CollectorExtMEP.cs. The fix is to add an exception handler to the offending property. In this case, the original code simply went ahead and blindly accessed the Angle property:

data.Add( new Snoop.Data.Double( "Angle", connector.Angle ) );

As the exception message says, this access is prohibited unless the connector is defined for the HVAC or piping domain. I therefore added a check to test the connector domain before accessing it, and the updated code now reads:

if( Domain.DomainHvac == connector.Domain 
  || Domain.DomainPiping == connector.Domain )
{
  data.Add( new Snoop.Data.Double( "Angle", 
    connector.Angle ) );
}

That solves that little problem.

Another way to handle this would be to simply encapsulate the offending line of code into its own individual little exception handler, but that would add considerable unnecessary execution overhead. Remember, an exception should be used only for unexpected, exceptional circumstances. If a property is expected to fail under certain circumstances, then these should be caught using traditional and more effective means.

Unfortunately, there are quite a few more properties on the connector class which are similarly limited and throw exceptions if called under invalid circumstances, so the method Stream(ArrayList data, Connector connector) could use quite a few additional corrections. For instance, the Radius property may only be queried in the case of a connector with a round cross section.

Since there are so many properties and I do not want to add individual checks for each of them, I have actually resorted to adding the individual exception handlers I mentioned above to each property for the time being, simply in order to use RvtMgdDbg for electrical connectors right away with no further ado.

I encapsulated each line of code accessing a property into an exception handler using the Visual Studio regular expression replacement feature, searching for a regular expression like this:

{data\.Add.*, connector\.}{[^\.\)]*}{[\)\.].*}\n

The replacement code looks like this:

try\n{\n\1\2\3\n}\ncatch\n{\nDebug.Print( "\2: "+ex.Message );\n}\n

Visual Studio automatically adds the proper indenting for me if I cut out the generated code and then paste it right back into the same place again.

For example, here is the unprotected call to access the AssignedDuctFlowConfiguration property:

  data.Add( new Snoop.Data.String( 
    "Duct flow configuration type", 
    connector.AssignedDuctFlowConfiguration.ToString() ) );

The result of executing the regular expression search and replace operation on that single line of code is to convert the unprotected property access to one encapsulated within its own exception handler. Here is the resulting protected AssignedDuctFlowConfiguration property access:

  try
  {
    data.Add( new Snoop.Data.String( 
      "Duct flow configuration type", 
      connector.AssignedDuctFlowConfiguration.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedDuctFlowConfiguration: " 
      + ex.Message );
  }

Here is the complete code of my modified version of the overloaded method Stream( ArrayList data, Connector connector ):

private void
Stream(ArrayList data, Connector connector)
{
  data.Add(new Snoop.Data.ClassSeparator(typeof(Connector)));
 
  try
  {
    data.Add( new Snoop.Data.Enumerable( "All refs", connector.AllRefs ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AllRefs: " + ex.Message );
  }
  if( Domain.DomainHvac == connector.Domain 
    || Domain.DomainPiping == connector.Domain )
  {
    data.Add( new Snoop.Data.Double( "Angle", connector.Angle ) );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Duct flow configuration type", connector.AssignedDuctFlowConfiguration.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedDuctFlowConfiguration: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Duct loss method type", connector.AssignedDuctLossMethod.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedDuctLossMethod: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned fixture units", connector.AssignedFixtureUnits ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedFixtureUnits: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned flow", connector.AssignedFlow ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedFlow: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Assigned flow direction", connector.AssignedFlowDirection.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedFlowDirection: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned flow factor", connector.AssignedFlowFactor ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedFlowFactor: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned K coefficient", connector.AssignedKCoefficient ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedKCoefficient: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned loss coefficient", connector.AssignedLossCoefficient ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedLossCoefficient: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Assigned pipe flow configuration", connector.AssignedPipeFlowConfiguration.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedPipeFlowConfiguration: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Assigned pipe loss method", connector.AssignedPipeLossMethod.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedPipeLossMethod: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Assigned pressure drop", connector.AssignedPressureDrop ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "AssignedPressureDrop: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Coefficient", connector.Coefficient ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Coefficient: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Object( "Connector manager", connector.ConnectorManager ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "ConnectorManager: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Connector type", connector.ConnectorType.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "ConnectorType: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Object( "Coordinate system", connector.CoordinateSystem ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "CoordinateSystem: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Demand", connector.Demand ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Demand: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Direction", connector.Direction.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Direction: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Domain", connector.Domain.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Domain: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Duct system type", connector.DuctSystemType.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "DuctSystemType: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Electrical system type", connector.ElectricalSystemType.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "ElectricalSystemType: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Flow", connector.Flow ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Flow: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Height", connector.Height ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Height: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Bool( "Is connected", connector.IsConnected ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "IsConnected: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Bool( "Is movable", connector.IsMovable ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "IsMovable: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Object( "MEP system", connector.MEPSystem ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "MEPSystem: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Xyz( "Origin", connector.Origin ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Origin: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Pipe system type", connector.PipeSystemType.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "PipeSystemType: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Pressure drop", connector.PressureDrop ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "PressureDrop: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Velocity pressure", connector.VelocityPressure ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "VelocityPressure: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Width", connector.Width ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Width: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Double( "Radius", connector.Radius ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Radius: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.String( "Shape", connector.Shape.ToString() ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Shape: " + ex.Message );
  }
  try
  {
    data.Add( new Snoop.Data.Object( "Owner", connector.Owner ) );
  }
  catch( System.NotSupportedException ex )
  {
    Debug.Print( "Owner: " + ex.Message );
  }
}

If you wish to examine the truncated overly long lines, you can copy and paste them to an editor.

Running the modified version of RvtMgdDbg and selecting an electrical connector produces the following list in the Visual Studio debug output window of all the properties that are throwing exceptions:

AssignedDuctFlowConfiguration: Assigned duct flow configuration is available only for connectors of DomainPiping.
AssignedDuctLossMethod: Assigned duct loss method is available only in connectors of DomainHvac.
AssignedFixtureUnits: Assigned fixture units available only for connectors of DomainPiping.
AssignedFlow: Assigned flow is available only for connectors of DomainHavc or DomainPiping.
AssignedFlowDirection: Assigned flow direction is available only for connectors of DomainHavc and DomainPiping.
AssignedFlowFactor: Assigned flow factor is available only for connectors of DomainPiping or DomainHvac.
AssignedKCoefficient: Assigned KCoefficient is available only for connectors of DomainPiping.
AssignedLossCoefficient: Assigned loss coefficient is available only for connectors of DomainHavc.
AssignedPipeFlowConfiguration: Assigned pipe flow configuration is available only for connectors of DomainPiping.
AssignedPipeLossMethod: Assigned pipe loss method is available only for connectors of DomainPiping.
AssignedPressureDrop: Assigned pressure drop is available only for connectors of DomainHavc and DomainPiping.
Coefficient: Coefficient is available only for connectors of DomainHavc and DomainPiping.
CoordinateSystem: Coordinate System is available only for connectors of PhysicalConn.
Demand: Demand is available only for connector of DomainPiping.
Direction: Direction is available only for connectors of DomainHvac and DoaminPiping.
DuctSystemType: Duct system type is available only for connectors of DomainHvac.
ElectricalSystemType: Electrical system type is available only for connectors of DomainElectrical.
Flow: Flow is available only for connectors of DomainHavc and DomainPiping.
Height: The shape of the connector is not rectangular.
IsConnected: Connection status is available only for connectors of PhysicalConn type.
Origin: Origin is available only for connectors of PhysicalConn type.
PipeSystemType: Pipe system type is available only for connectors of DomainPiping.
PressureDrop: Pressure drop is available only for connectors of DomainHavc and DomainPiping.
VelocityPressure: Velocity pressure is available only for connectors of DomainHavc and DomainPiping.
Width: The shape of the connector is not rectangular.
Radius: The shape of the connector is not round.

Again, copy and paste to an editor to see the complete truncated lines.

Since each exception caught by an invalid property access is caught individually and processing can continue with an attempt at the next property, the other desired result is that the property window is now successfully populated and displayed with the remaining properties that have not thrown an exception:

As pointed out above, this is only a partial and temporary fix. In the long run, the individual exception handlers should be replaced by if clauses, as done for the Angle property.

Service-Oriented Architecture

A reader contributed the following introduction to Service-Oriented Architecture SOA. Even without having dealt with this paradigm previously, the recommendations made are all quickly recognisable as good practice, simply based on experience and striving for reliability and maintainability. This contribution is intended as a lead-in to an upcoming article and example code dealing with a specific Revit API issue:

SOA provides an approach to writing code which has many benefits, not the least of which are promoting code reuse and making applying changes or fixes more effective.

It is very intuitive to write a class which has properties on it and then have your functions act on those property values. But how is a developer who is new to writing against the code supposed to know which properties need to be set before a function can be called? What if they miss setting a property? If they set a property to a value for use by a previous method call, but forgot to change it for the next method call, the later call would happily use the old (wrong) data by mistake.

The primary focus of SOA is to write small functions, each of which performs a very specific task, and each of which gets all of the data it needs via parameters passed into it. This allows the functions to be stateless. Web services, which are stateless, generally implement this technique by design.

The stateless approach allows each function to be written in such a manner that it has no idea what code is calling it; it makes no assumptions about the environment in which it operates. This ensures the function is as reusable as possible.

Part of this approach includes a lack of trust that the caller is sending valid data, so it requires each function to validate the parameters passed into it and throw an exception if a parameter has an invalid or missing value before attempting to do anything. This can help when debugging because it calls attention to a specific problem as soon as it is detected.

Another part of this approach forbids doing environment-specific things in your reusable code, such as the ever-tempting showing of a System.Windows.Forms.MessageBox, unless your reusable code requires that environment. If your class is itself a Form or Windows User Control, then showing a MessageBox may be acceptable. Otherwise you should throw an exception or return a string that contains the message for processing by the caller. For example, one caller may choose to show a MessageBox, another may choose to log the string to a file or system event log.

Typically SOA methods are grouped by similar functionality and housed in classes named for that general functionality. This helps promote reuse by providing a logical path for finding methods to do the work for you. This can be seen by some functions in the .NET Framework, such as:

  System.IO.File.Exists
  System.DateTime.DaysInMonth
  System.Reflection.Assembly.GetExecutingAssembly

A good 'smoke test' that your function is compatible with an SOA approach is to declare it 'static' (C#) or 'Shared' (VB.NET). For example:

  public static decimal CalculateArea(
    decimal length, 
    decimal width )

This will not only prevent your method from using any module-level variables, but will allow the caller to call your method without having to create an instance of your class first, as the above Framework examples do. Incidentally, decimal values are used in this example instead of doubles because decimal types never have rounding errors. Even a simple addition of double values induces a small rounding error, which can magnify quickly.

You may put a method like this in a class called 'Calculations' which might be housed in an assembly (DLL) called 'MathFunctions' and could readily be used by any number of your applications. Further, if a bug should be discovered someday, fixing it in the class would allow you to simply provide a new DLL to all of your existing applications, and they would all get the bug fix automatically.

There are environments where SOA doesn’t work very well. For example, some things that happen inside a Windows Form (or User Control) are much easier to do by maintaining state using module-level variables. As by definition the Form maintains state anyway, this is appropriate.

But following good SOA (and n-tier) practices, the code inside the Form should be as 'dumb' as possible, and call reusable functions whenever possible.

Writing code following an SOA approach can be a very different mindset, and may require some practice, but once you get into the habit you may be amazed at how much better and more robust your code will become.

Debug Geometric Form Creation

Here is a useful hint on debugging the generation of geometric shapes from Harry Mattison.

Question: I am trying to create multiple swept blends in a family document. The first call to FamilyCreate.NewSweptBlendForm() succeeds, but the second call is failing with the following exception:

Answer: For problems like this I suggest commenting out the code that creates the form so that the command creates only the lines being used to create the form. Then you can run the command, verify the geometry of the lines, and use the Revit UI to select them and push the Create Form button. If Create Form fails, then the bug probably has nothing to do with the API.

In this case, there are many overlapping line warnings:

I'd expect that you will get better results if the geometry forms closed loops without overlaps.

Finally, this will be easier to debug if the lines are created in the active document instead of a new document created in the external command that is not visible without saving and reopening the file. Thin Lines mode might also be helpful because the lines are quite short.

Thank you very much Harry for these valuable suggestions!

Porting the Building Coder Samples

Today is actually a bridging day here in Neuchâtel, following the Ascension Day holiday yesterday. I want to finish off a few urgent things before going on vacation for the next two weeks with my kids, so I am taking the opportunity to post this anyway.

I finally got around to porting the Building Coder sample code to the Revit 2010 API. I was leaving it in 2009 for as long as possible so as not to force anybody to update too early. On the other hand, I hope that this is not too late either, and that nobody has been waiting urgently for a 2010 port. Now, on this replacement machine I am working on, I no longer have Revit 2009 or Visual Studio 2005 installed, so I am forced to update in order to use the samples at all. Simply opening the solution file in Visual Studio 2008 and compiling fails, and we will discuss why and how to fix this. I actually expected the recompilation on 2010 to be completely trivial, but some issues did crop up which are worth mentioning.

Here is a list of the errors on simply opening the Visual Studio 2005 solution in Visual Studio 2008 and recompiling. For the sake of better readability, I removed the full path name of the source files. Copy to an editor to see the full line length:

------ Build started: Project: BuildingCoder, Configuration: Debug Any CPU ------
c:\WINDOWS\Microsoft.NET\Framework\v3.5\Csc.exe /noconfig /nowarn:1701,1702 /errorreport:prompt /warn:4 /define:DEBUG;TRACE /reference:"..\..\..\..\..\..\..\..\..\..\Program Files\Autodesk Revit Architecture 2010\Program\RevitAPI.dll" /reference:c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.dll /reference:c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Drawing.dll /reference:c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Windows.Forms.dll /debug+ /debug:full /optimize- /out:obj\Debug\BuildingCoder.dll /resource:obj\Debug\BuildingCoder.CmdLinkedFileElementsForm.resources /resource:obj\Debug\BuildingCoder.CmdWindowHandleForm.resources /target:library CmdAzimuth.cs CmdBoundingBox.cs CmdColumnRound.cs CmdLinkedFileElements.cs CmdLinkedFileElementsForm.cs CmdLinkedFileElementsForm.Designer.cs CmdListRailingTypes.cs CmdNestedInstanceGeo.cs CmdNewArea.cs CmdNewBeamTypeInstance.cs CmdNewColumnTypeInstance.cs CmdEditFloor.cs CmdFilterPerformance.cs CmdGetMaterials.cs CmdLinkedFiles.cs CmdListViews.cs CmdNewRailing.cs CmdOmniClassParams.cs CmdPlanTopology.cs CmdRoomWallAdjacency.cs CmdSlabBoundaryArea.cs CmdSlopedWall.cs CmdTransformedCoords.cs CmdWallLayerVolumes.cs CmdWallProfileArea.cs CmdListWalls.cs CmdRelationshipInverter.cs CmdSlabSides.cs CmdSlabBoundary.cs CmdWallDimensions.cs CmdWallLayers.cs CmdWallProfile.cs CmdWindowHandle.cs CmdWindowHandleForm.cs CmdWindowHandleForm.Designer.cs Creator.cs Properties\AssemblyInfo.cs Util.cs CmdWallNeighbours.cs
CmdWallNeighbours.cs(64,26): error CS0029: Cannot implicitly convert type 'Autodesk.Revit.ElementArray' to 'System.Collections.Generic.List'
CmdNewBeamTypeInstance.cs(83,14): error CS1502: The best overloaded method match for 'Autodesk.Revit.Document.LoadFamily(string, out Autodesk.Revit.Elements.Family)' has some invalid arguments
CmdNewBeamTypeInstance.cs(83,40): error CS1620: Argument '2' must be passed with the 'out' keyword
CmdNewColumnTypeInstance.cs(90,14): error CS1502: The best overloaded method match for 'Autodesk.Revit.Document.LoadFamily(string, out Autodesk.Revit.Elements.Family)' has some invalid arguments
CmdNewColumnTypeInstance.cs(90,40): error CS1620: Argument '2' must be passed with the 'out' keyword
CmdColumnRound.cs(35,44): error CS1061: 'Autodesk.Revit.Elements.Family' does not contain a definition for 'SolidForms' and no extension method 'SolidForms' accepting a first argument of type 'Autodesk.Revit.Elements.Family' could be found (are you missing a using directive or an assembly reference?)
CmdColumnRound.cs(39,35): error CS1061: 'Autodesk.Revit.Elements.Sketch' does not contain a definition for 'CurveLoop' and no extension method 'CurveLoop' accepting a first argument of type 'Autodesk.Revit.Elements.Sketch' could be found (are you missing a using directive or an assembly reference?)
CmdNestedInstanceGeo.cs(165,50): error CS1061: 'Autodesk.Revit.Elements.Family' does not contain a definition for 'Components' and no extension method 'Components' accepting a first argument of type 'Autodesk.Revit.Elements.Family' could be found (are you missing a using directive or an assembly reference?)

Compile complete -- 8 errors, 0 warnings
========== Build: 0 succeeded or up-to-date, 1 failed, 0 skipped ==========

The first error CS0029 is reporting that an 'Autodesk.Revit.ElementArray' cannot be converted to a generic list of elements in CmdWallNeighbours. This makes perfect sense, because get_ElementsAtJoin now returns an instance of the custom Revit API collection class ElementArray instead of a standard generic collection class provided by .NET. Therefore, we also have to modify the following iteration over the collection returned. Actually, the only change required is to replace the property Count by Size.

The next four errors are trivial to fix, CS1502 and CS1620 in CmdNewBeamTypeInstance and CmdNewColumnTypeInstance. They are all four caused by the second argument of one of the overloads of the LoadFamily method changing from a reference to an output argument, so the keyword 'ref' needs to be replaced by 'out'.

The two CS1061 errors in CmdColumnRound occur in the method IsColumnRound, which was written to demonstrate an approach that can only be used in the Revit 2009 API. The classes used have been removed in the Revit 2010 API, so this method can no longer be compiled. Since it is not used anyway, I can simply comment it out.

The only serious change is required to fix the error CS1061 in CmdNestedInstanceGeo. There we use the Revit 2009 API property FamilyInstance.Symbol.Family.Components to obtain the nested family instances within the top level family instance. This is what the original code looks like:

ElementSet components = inst.Symbol.Family.Components;
n = components.Size;

The Components property has been removed in the Revit 2010 API, since we can iterate through the elements of a family just like any other document. Here is a note about this from in the description of the family API in the What's New section of the RevitAPI.chm help file:

"New document methods - Document.LoadFamily and Document.EditFamily - are introduced to bring families from the Family Editor to the Project environment and vice versa. These methods can be used to examine the contents of the family in terms of its elements, parameters and types; as a result, the properties of Family which access the contents have been removed (Family.SolidForms, Family.VoidForms, Family.Components, Family.LoadedSymbols, Family.Others)."

Therefore, we have to port the code from the 2009 to the 2010 API. We can use doc.EditFamily to obtain a Document instance for the family document, and then work with its elements using the standard document element access methods as follows:

Document fdoc = doc.EditFamily( inst.Symbol.Family );

List<RvtElement> components = new List<RvtElement>();
fdoc.get_Elements( typeof( FamilyInstance ), components );
n = components.Count;

Here is version 1.1.0.32 of the complete Visual Studio 2008 solution of The Building Coder sample code. This is the first version for Revit 2010, and the first one using Visual Studio 2008 instead of 2005.

RvtSamples Conversion from 2009 to 2010

As you probably know by now, I use RvtSamples to load the external commands defined by the Revit SDK samples into Revit. I also use it to provide access to all my additional sample commands by making use of the include functionality I implemented, which is now part of the standard SDK distribution.

The format used in the text file RvtSamples.txt used to drive RvtSamples changed from Revit 2009 to 2010 in order to add support for the ribbon Add-Ins tab and button images.

For Revit 2009, RvtSamples expected four lines of information for each entry to specify a hierarchical menu item definition for an external command. The entry for the first Building Coder command looks like this:

/&ADN/&Bc/List Walls
List wall lengths and areas
C:\...\BuildingCoder.dll
BuildingCoder.CmdListWalls

This specifies that a menu entry ADN > Bc > List walls should be generated in the Revit menu system. Selecting it in the user interface launches the external command defined by the BuildingCoder.CmdListWalls class loaded from the specified assembly.

In Revit 2010, there is no longer a hierarchical menu system to install menu entries in. Instead, all external commands are located in the ribbon Add-Ins tab, either under the External Tools pull down button or in an additional pane defined by an external application. Optionally, buttons can be specified as well. Therefore, the new 2010 RvtSamples format for defining a similar entry uses seven lines which might look like this:

ADN Bc
List Walls
List wall lengths and areas
LargeImage:
Image:
C:\...\BuildingCoder.dll
BuildingCoder.CmdListWalls

I used regular expressions in the Visual Studio search and replace dialogue to convert from old format to the new one. I start the search and replace dialogue with Edit > Find and Replace > Quick Replace, and then enter the following regular search expression in 'Find what':

/&ADN/&Bc/{.*}\n{.*}\n

It specifies a line starting with "/&ADN/&Bc/" and followed by anything at all, which is tagged, followed by another line, whose contents are also tagged. The first tagged expression is the menu entry, the second is the description. I enter the following in 'Replace with':

ADN Bc\n\1\n\2\nLargeImage:\nImage:\n

That splits the menu entry text and description onto separate lines, followed by two additional lines for the optional large and small images.

Applying this search and replace action to the example shown above achieves the desired conversion, making it easy and comfortable to reliably convert the entire list of entries.

Nested Instance Geometry

This is in response to a query from Benson about the structure and geometry of nested family instances. In the answer, we also present some useful comparison operators which enable us to use Revit XYZ points and vectors as keys in generic .NET dictionaries, and sort them lexicographically, as well as utility functions for extracting and listing all the vertices of a solid. Here is the original query, slightly rephrased:

Question: I would like to obtain the internal hierarchy defined within a family instance, but its geometry only returns a flat list of solids.

For example: a top level family instance F includes one column C0, and two nested family instances F1 and F2. F1 includes two more columns C1 and C2, and F2 includes two further columns C3 and C4. The result I am trying to achieve is the geometry with the associated hierarchy:

  F
  }
  +-- C0
  }
  +-- F1
  }   }
  }   +-- C1
  }   }
  }   +-- C2
  }
  +-- F2
      }
      +-- C3
      }
      +-- C4

Here are my steps to create the family instances in this structure:

1. Run Revit 2009.
2. Select File > New > Family and open a metric template such as Metric Funiture.rft.
3. Delete all objects in the new family project, switch to 3D view.
4. Select File > Load from Library > Load Family and select an RFA file, with a column in it.
5. Now, we can find the column in the project browser panel > Families > Columns.
6. Select this column, right click on it, and select "Create Instance". Repeat step 6, so we now have two columns in the family project.
7. Save the project as myFamily1.rfa, then click File > Save As to save it again as myFamily2.rfa. Now, we have two family projects myFamily1.rfa and myFamily2.rfa.
8. Repeat steps 2, 3, and 4, this time selecting a column family, myFamily1, and myFamily2.
9. Create instances of the column, myFamily1, myFamily2 in the current family project like step 6.
10. Save the project as myFamily3.rfa.
11. Create a normal project, for instance named Project1.rvt, using File > New > Project.
12. Load myFamily3.rfa like step 4.
13. Add an instance of myFamily3 like step 6.

Now we have the structure shown above, with F represented by myFamily3, and F1 and F2 by myFamily1 and myFamily2 respectively.

Answer: The geometry of the top level family instance F does indeed just contain a flat list of solids. You can obtain some information about the hierarchical structure of the nested family instances by recursively exploring the family instance symbol family components. For a given family instance a, they are accessible through a.Symbol.Family.Components. These components include information about their location within the containing family. Using this information, you can build up the structure you seek.

I created the project as you suggest and analysed the geometry and symbol family components of the top level family instance F. I used a rectangular column, so each of the columns is a simple quadrilateral with six faces.

In the geometry of the top level family instance F, I see one instance object. The important properties of a geometry instance are its Symbol, SymbolGeometry, and Transform:

• Symbol, the symbol element that this object is referring to.
• SymbolGeometry, the geometric representation of the symbol.
• Transform, the affine transformation of the symbol into the instance coordinate space.

In my case, the symbol geometry contains six solids. One of these is empty, i.e. has no edges or faces, so I simply ignore that one. The remaining five represent the five different column instances visible in the project. These five different instances can be differentiated by the different face vertex coordinates.

To explore and compare complex geometry like that of a solid, it is important to have some powerful tools at your disposal to reduce the amount of detailed information you have to analyse and compare. In this case, in order to display the solids in an easily read fashion, I implemented a helper method named GetVertices to extract the vertices of a solid and store them in a sorted list in a XYZArray.

GetVertices iterates over all the faces of the given solid, triangulates each face, and iterates over the vertices of the resulting mesh. These are added into a container, which is designed to ensure that every vertex occurs once only. I implement this container by using a generic dictionary class and attaching an equality comparison class which ensures that almost equal points are regarded as being exactly equal, allowing for some fuzziness due to numerical imprecision. Here is the definition of my XyzEqualityComparer class:

class XyzEqualityComparer : IEqualityComparer<XYZ>
{
  public bool Equals( XYZ p, XYZ q )
  {
    return p.AlmostEqual( q );
  }
 
  public int GetHashCode( XYZ p )
  {
    return Util.PointString( p ).GetHashCode();
  }
}

The hash code calculation could certainly be optimised by avoiding the detour through a string representation, but this is the quickest and easiest solution that came to mind. I am not sure that it will work reliably under all circumstances, though. It is probably necessary to increase the precision in the string representation generated by PointString to match the precision used by the AlmostEqual method.

With this equality comparer, we can employ the standard .NET generic dictionary class using Revit XYZ points and vectors as dictionary keys.

In order to further facilitate the comparison of solids with each other, I sort their vertices before storing them into the array. The sorting process requires another fuzzy comparison routine, a Compare function which determines whether a given point is larger than, equal to, or smaller than another one, and correspondingly returns 1, 0 or -1. We define this comparison algorithm by comparing the X, Y and Z coordinates in the canonical order. If all three are almost equal, the two points are considered equal. Otherwise, the first pair of coordinates to differ is used to determine whether the first point is considered to be greater or smaller than the second. Here is the implementation of this comparison method:

const double _eps = 1.0e-9;
 
public static bool IsZero( double a )
{
  return _eps > Math.Abs( a );
}
 
public static bool IsEqual( double a, double b )
{
  return IsZero( b - a );
}
 
public static int Compare( double a, double b )
{
  return IsEqual( a, b ) ? 0 : ( a < b ? -1 : 1 );
}
 
public static int Compare( XYZ p, XYZ q )
{
  int diff = Compare( p.X, q.X );
  if( 0 == diff ) {
    diff = Compare( p.Y, q.Y );
    if( 0 == diff ) {
      diff = Compare( p.Z, q.Z );
    }
  }
  return diff;
}

With these two comparison helpers in place, I can implement my GetVertices helper method to extract a sorted list of solid vertices and store them in a sorted manner in a XYZArray like this:

static void GetVertices( XYZArray vertices, Solid s )
{
  Debug.Assert( 0 < s.Edges.Size,
    "expected a non-empty solid" );
 
  Dictionary<XYZ, int> a
    = new Dictionary<XYZ, int>(
      new XyzEqualityComparer() );
 
  foreach( Face f in s.Faces )
  {
    Mesh m = f.Triangulate();
    foreach( XYZ p in m.Vertices )
    {
      if( !a.ContainsKey( p ) )
      {
        a.Add( p, 1 );
      }
      else
      {
        ±±a[p];
      }
    }
  }
  List<XYZ> keys = new List<XYZ>( a.Keys );
 
  Debug.Assert( 8 == keys.Count,
    "expected eight vertices for a rectangular column" );
 
  keys.Sort( Util.Compare );
 
  foreach( XYZ p in keys )
  {
    Debug.Assert( 3 == a[p],
      "expected every vertex of solid to appear in exactly three faces" );
 
    vertices.Append( p );
  }
}

The two assertions checking the total number of vertices, 8, and the number of coincident vertices in each corner, 3, are only valid for this special case, where I am looking at quadrilateral columns. They will be removed in a future version, if I make use of this method for more general cases.

With this code in place, I can easily retrieve a sorted list of each of the solids' vertices for display and comparison purposes.

I used the code you provided in your original comment as a basis for a new command named CmdNestedInstanceGeo, specifically tailored to explore this situation. It first iterates over the solids contained in the top level family instance geometry and lists their vertices. It then explores the family instance components and lists their names and location points. Here is the code for the Execute methods that implements this:

Application app = commandData.Application;
Document doc = app.ActiveDocument;
 
List<RvtElement> a = new List<RvtElement>();
 
if( !Util.GetSelectedElementsOrAll( a, doc,
  typeof( FamilyInstance ) ) )
{
  Selection sel = doc.Selection;
  message = ( 0 < sel.Elements.Size )
    ? "Please select some family instances."
    : "No family instances found.";
  return CmdResult.Failed;
}
FamilyInstance inst = a[0] as FamilyInstance;
 
Options opts = app.Create.NewGeometryOptions();
GeoElement geoElement = inst.get_Geometry( opts );
 
GeometryObjectArray a1 = geoElement.Objects;
int n = a1.Size;
 
Debug.Print(
  "Family instance geometry has {0} geometry object{1}{2}",
  n, Util.PluralSuffix( n ), Util.DotOrColon( n ) );
 
int i = 0;
foreach( GeometryObject o1 in a1 )
{
  GeoInstance geoInstance = o1 as GeoInstance;
  if( null != geoInstance )
  {
    GeoElement symbolGeo = geoInstance.SymbolGeometry;
    GeometryObjectArray a2 = symbolGeo.Objects;

    foreach( GeometryObject o2 in a2 )
    {
      Solid s = o2 as Solid;
      if( null != s && 0 < s.Edges.Size )
      {
        XYZArray vertices = app.Create.NewXYZArray();
        GetVertices( vertices, s );
        n = vertices.Size;
 
        Debug.Print( "Solid {0} has {1} vertices{2} {3}",
          i++, n, Util.DotOrColon( n ),
          Util.PointArrayString( vertices ) );
      }
    }
  }
}
ElementSet components = inst.Symbol.Family.Components;
n = components.Size;
 
Debug.Print(
  "Family instance symbol family has {0} component{1}{2}",
  n, Util.PluralSuffix( n ), Util.DotOrColon( n ) );
 
foreach( RvtElement e in components )
{
  LocationPoint lp = e.Location as LocationPoint;
  Debug.Print( "{0} at {1}",
    Util.ElementDescription( e ),
    Util.PointString( lp.Point ) );
}
return CmdResult.Failed;

It accesses the one and only family instance in the file and stores it in 'inst'. It then iterates over its geometry, extracts the vertices from each solid, and lists them in the debug output window. Here is the result of that listing:

Family instance geometry has 1 geometry object:
Solid 0 has 8 vertices: (32.15,8.02,0), (32.15,8.02,13.12), (32.15,9.57,0), (32.15,9.57,13.12), (34.15,8.02,0), (34.15,8.02,13.12), (34.15,9.57,0), (34.15,9.57,13.12)
Solid 1 has 8 vertices: (28.24,3.23,0), (28.24,3.23,13.12), (28.24,4.79,0), (28.24,4.79,13.12), (30.24,3.23,0), (30.24,3.23,13.12), (30.24,4.79,0), (30.24,4.79,13.12)
Solid 2 has 8 vertices: (16,7.4,0), (16,7.4,13.12), (16,8.96,0), (16,8.96,13.12), (18,7.4,0), (18,7.4,13.12), (18,8.96,0), (18,8.96,13.12)
Solid 3 has 8 vertices: (12.08,2.61,0), (12.08,2.61,13.12), (12.08,4.17,0), (12.08,4.17,13.12), (14.09,2.61,0), (14.09,2.61,13.12), (14.09,4.17,0), (14.09,4.17,13.12)
Solid 4 has 8 vertices: (10.16,-4.19,0), (10.16,-4.19,13.12), (10.16,-2.19,0), (10.16,-2.19,13.12), (12.16,-4.19,0), (12.16,-4.19,13.12), (12.16,-2.19,0), (12.16,-2.19,13.12)

These lines are probably too long to be displayed in their entirety, but the main thing is to see that we have five identical solids which only differ from each other by a translation. You can see the full lines by copying and posting them into an editor.

The command next iterates over the family instance symbol family components, just like you suggested, and lists each one of these together with its location point:

Family instance symbol family has 3 components:
Columns M_Rectangular Column <2384 610 x 610mm> at (11.16,-3.19,0)
Furniture myFamily1 <3525 myFamily1> at (-2.48,2.65,0)
Furniture myFamily2 <4665 myFamily2> at (13.68,3.26,0)

As you can see, the column instance C0 and the two furniture family instances myFamily1 and myFamily2 are listed. Diving into myFamily1 in the debugger and again traversing into its family instance components, I see the two nested columns C1 and C2, and so on. We could enhance the code to traverse this structure recursively.

If you look at the location points of these instances and compare them with the offsets between the five solids, you can determine the correspondence between the internal nested structure and the detailed geometrical representation.

In this case, we defined our families extremely haphazardly, which makes it harder to understand the results. In a well designed family, I would expect both the structure and the locations of internal components to be less arbitrary.

I hope that this exploration helps you understand the structure, and provides some useful tools to explore it further.

Here is version 1.0.0.32 of the complete Visual Studio solution with the new command.