The Building Coder

Migrating a Built-in Category and Other Things

Here is a category related issue that appeared when migrating from the Revit 2013 to the Revit 2014 API, plus a several other typical simple little Revit API questions from the last day or two:

• Migrating the room separation lines built-in category
• Storage of RGB colour values for materials
• Updating a DXF link
• Retrieving truss family elements
• Retrieving stair stringer data
• Storing custom data

Migrating the Room Separation Lines Built-in Category

Question: I get the following error while migrating my C# code from Revit 2013 to Revit 2014:

• 'Autodesk.Revit.DB.BuiltInCategory' does not contain a definition for 'OST_AreaSeparationLines'

It is caused by the following line of code:

  ICollection<Element> collection
    = collector.OfCategory(
        BuiltInCategory.OST_AreaSeparationLines )
      .ToElements();

Do you have any solution to suggest?

Answer: The easiest way to fix this kind of issue is to look at an element that has this category using RevitLookup in Revit 2013, and then load the same model and see what category it has in Revit 2014.

Response: That worked!

It seems to be called OST_RoomSeparationLines now.

Problem solved.

Storage of RGB Colour Values for Materials

Question: I looked at a material element 'Color' parameter value today. This parameter values comes back as an integer.

It appears to me to have the red and blue values reversed.

When looking at the 'Site – Earth' material in the rac_advanced_sample_project included with Revit, the Color property on the material class returns material.Color.Red=97, material.Color.Green=75 and material.Color.Blue=62, which is also what the Revit GUI shows in 'Manage Materials'. I checked on an online colour generator web site and it looks the same as in the Revit GUI, a dirty brown colour.

However, the integer number that comes back from the 'Color' parameter on the material element is 4082529, which when converted to RGB values using online converters, comes back as Red=62, Green=75 and Blue=97, which is a bluish colour. The Red and Blue values appear to be reversed.

I would have expected the integer 6376254 to be returned for this colour instead.

Can you explain this, please?

Answer: Yes, easily.

This is actually working as expected.

Revit uses the Windows convention of storing colours as an RGB COLORREF value in a DWORD (32 bit integer) that specifies "The low-order byte contains a value for the relative intensity of red; the second byte contains a value for green; and the third byte contains a value for blue".

In other words it is (A)BGR and not (A)RGB.

This corresponds to the value of the integer returned from a Color parameter.

Updating a DXF Link

Question: I have created a DXF link DXF using the following code:

  DWGImportOptions opt = new DWGImportOptions();
  ElementId linkId;
 
  if( doc.Link( "C:\\tmp\\test.dxf",
    opt, doc.ActiveView, out linkId ) )
  {
    Element e = doc.GetElement( linkId );
    ImportInstance i = e as ImportInstance;
  }

Later, the DXF is modified by an external application.

Is it possible to programmatically force Revit to reload the link?

I think I could also delete the ImportInstance and create a new one, but I don't how to get the proper DWGImportOptions and DXF file path from the existing ImportInstance.

Answer: Yes, this can easily be achieved. You can use the RevitLinkType.Unload method to unload it first, and then call RevitLinkType.Reload to reload the updated DXF file.

The imported DXF file has the type of CADLinkType. Just as you say, you could also delete the link and import it again.

You can find the imported DXF ImportInstance's original path by calling the ExternalFileReference.GetPath method, and the ExternalFileUtils.GetExternalRefernce method will return the ImportInstance's ExternalFileReference object.

Retrieving Truss Family Elements

Question: How can I retrieve a truss element family instance?

Answer: This is a very basic question, answered many times over in the Revit API getting started material.

I recommend that you take a look at that material, work through the 'My First Revit Plugin' and DevTV tutorials, install the Revit SDK, RevitLookup, RvtSamples, and then answer that question for yourself.

I'll just give you one little additional hint to help get you started:

Every access to a Revit database element is achieved using a filtered element collector.

To retrieve all truss family instances, you could use something like this:

  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .OfClass( typeof( FamilyInstance ) )
      .OfCategory( BuiltInCategory.OST_Truss );
 
  foreach( Element e in collector )
  {
    // e is a truss family instance
  }

Retrieval of Stair Stringer Data

Question: I want to access the values of the stair stringer height and thickness properties on a stair element. How can I achieve this, please?

I tried using the built-in parameters STAIRS_ATTR_STRINGER_THICKNESS and STAIRS_ATTR_STRINGER_HEIGTH, but the value being returned is null. I am also unable to get the family symbol of the stair element.

Answer: The two parameters that you are trying to access are stored on the stair type, not the stair itself.

The stair type is represented by the ElementType class, not FamilySymbol.

You can access the stair type and the two desired paramaters like this:

  Document doc = stair.Document;
 
  ElementId id = stair.GetTypeId();
 
  ElementType type = doc.get_Element( id )
    as ElementType;
 
  Parameter pThick = type.get_Parameter(
    BuiltInParameter.STAIRS_ATTR_STRINGER_THICKNESS );
 
  Parameter pHeight = type.get_Parameter(
    BuiltInParameter.STAIRS_ATTR_STRINGER_HEIGHT );
 
  double thick = pThick.AsDouble();
  double height = pHeight.AsDouble();

Storing Custom Data

Response: I need more than just the path. I would like to retrieve other DWGImportOptions parameters as well. Is it possible to get them somehow?

Answer: I don't think there is any way to retrieve all the ImportInstance's DWGImportOptions.

Since the DXF file was imported by your own code, you can easily work around that gap by storing the DWGImportOptions property values of interest in the ImportInstance object.

You can use extensible storage (wiki, category) to store custom data on Revit elements.

When you use this, you can later read back the settings from the extensible storage data.

Changing a Family Parameter from Type to Instance

Here is a short and simple question that just cropped up and required some digging around until my colleague Phil Xia came up with the right answer:

Question: Is it possible to change the type of a family parameter programmatically?

This is possible in the family editor.

I only see the IsInstance property, though, and it is read-only.

I could achieve the same effect by deleting the parameter and creating a new one. Obviously that would require updating all the existing values, though, if there are any, to change from the old parameter to the new one. I don't really see this as an option. Besides, the parameter could be referenced from other parameters.

Seeing that this is possible from within the family editor, I actually don’t see any need for this property to be read-only.

I don't think changing a family parameter from type to instance and vice versa should not be so hard.

Is there some other method that allows me to achieve this?

Answer: Yes, sure, you are lucky, and so are we all: the following two FamilyManager methods set the given family parameter to instance or type:

• MakeInstance – Set the family parameter as an instance parameter.
• MakeType – Set the family parameter as a type parameter.

I hope this will save you from repeating the same digging all over again :-)

Many thanks to Phil for explicitly pointing this out!

Parameter DisplayUnitType, Bretagne and Decompilers

After looking at several performance enhancement possibilities last week, e.g. the sweep family performance enhancement and LoadFamily and collector iteration performance, here is another exciting and pretty sophisticated exploration of internal Revit API implementation details by Victor Chekalin that can be used to achieve a significant speed improvement when accessing large numbers of parameters and checking their DisplayUnitType property.

Brittany

Before getting to that, though, here is an update on my current whereabouts.

Yesterday I spent travelling to Brest and Le Conquet (Konk Leon in Breton) for a meeting with my European DevTech colleagues.

This is the western-most point of northern France, home of my boss Cyrille, and my first visit to the Bretagne.

The weather is exciting and challenging, and the views spectacular.

A quick rainfall in the east and simultaneous glorious evening sunlight from the west produced a beautiful double rainbow.

We have a meeting room in a converted chapel with a view straight out onto the Atlantic.

Parameter DisplayUnitType Enhancement and Research

Back to the DisplayUnitType enhancement, here is the description of the research leading up to it in Victor's own words:

Now I'm working with the element parameters again and I need to get all parameters of a lot of elements in the project including their DisplayUnitType.

The problem is that not all parameters have a display unit type. If I try to retrieve a display unit type for a parameter where it does not exist, an Autodesk.Revit.Exceptions.InvalidOperationException is thrown. Unfortunately, there is no direct way to determine beforehand whether a parameter has a DisplayUnitType defined or not, i.e. whether the call will succeed or fail.

The most obvious way would be to wrap the code where I retrieve the display unit type in a try... catch block. But throwing and catching an exception is a very expensive operation and greatly reduces the performance – exceptions should be exceptional.

I decided to go deeper and looked at the RevitAPI.dll using dotPeek – free .NET decompiler.

At first I went to the DisplayUnitType property of the Parameter class.

public DisplayUnitType DisplayUnitType
{
  get
  {
    Definition definition = this.Definition;
    ParamTypeSpec paramTypeSpec1;
    if ((ParamTypeEnum) *(int*)
      definition.getParamTypeSpec(&paramTypeSpec1)
      != (ParamTypeEnum) 15)
    {
      throw new Autodesk.Revit.Exceptions
        .InvalidOperationException(new FunctionId(
          "n:\\build\\2013_ship_x64_inst_20120221_2030\\source\\api\\revitapi\\objects\\parameters\\APIParameter.cpp",
          581, "Autodesk::Revit::DB::Parameter::DisplayUnitType::get"),
          string.Empty);
    }
    else
    {
      ParamTypeSpec paramTypeSpec2;
      return (DisplayUnitType)
        \u003CModule\u003E.FormatOptions\u002EgetDisplayUnits(
          \u003CModule\u003E.AUnits\u002EgetFormatOptions(
            \u003CModule\u003E.ADocument\u002EgetAUnits(
              (ADocument*) *(long*) this.m_pCDA),
                (UnitType.Enum) *(int*) ((IntPtr)
                definition.getParamTypeSpec(&paramTypeSpec2) + 8L)));
    }
  }
}

The most interesting thing here is 'if ((ParamTypeEnum) *(int*) definition.getParamTypeSpec(&paramTypeSpec1) != (ParamTypeEnum) 15)'. The first idea is to call this method via reflection. But getParamTypeSpec is an internal unsafe method. Unfortunately, I don't know how to use reflector with pointers and internal structures. So, I decided to go another way.

The next step is to look at the ParameterType property of the Definition class.

public override ParameterType ParameterType
{
  get
  {
    REVIT_MAINTAIN_STATE revitMaintainState;
    \u003CModule\u003E.REVIT_MAINTAIN_STATE\u002E\u007Bctor\u007D(
      &revitMaintainState);
 
    ParameterType parameterType;
    try
    {
      ParamDef* paramDefPtr = this.m_pParamDef;
      ParamTypeSpec paramTypeSpec;
      \u003CModule\u003E.paramDefToParamType(
        &paramTypeSpec, paramDefPtr);
      switch (^(int&) @paramTypeSpec)
      {
      case 1:
        parameterType = ParameterType.Text;
        break;
      case 6:
        parameterType = ParameterType.URL;
        break;
      case 9:
        parameterType = ParameterType.YesNo;
        break;
      case 11:
        parameterType = ParameterType.Integer;
        break;
      case 13:
        parameterType = ParameterType.Material;
        break;
      case 14:
        parameterType = ParameterType.FamilyType;
        break;
      case 15:
        switch (^(int&) ((IntPtr) &paramTypeSpec + 8))
        {
        case 0:
          parameterType = ParameterType.Length;
          break;
        case 1:
          parameterType = ParameterType.Area;
          break;
        case 2:
          parameterType = ParameterType.Volume;
          break;
        case 3:
          parameterType = ParameterType.Angle;
          break;
        case 4:
          parameterType = ParameterType.Number;
          break;
        case 26:
          parameterType = ParameterType.Force;
          break;
        case 27:
          parameterType = ParameterType.LinearForce;
          break;
        case 28:
          parameterType = ParameterType.AreaForce;
          break;
        case 29:
          parameterType = ParameterType.Moment;
          break;
        default:
          parameterType = (ParameterType) (
            ^(int&) ((IntPtr) &paramTypeSpec + 8) + 100);
          break;
        }
      case 16:
        parameterType = ParameterType.NumberOfPoles;
        break;
      case 24:
        parameterType = ParameterType.FixtureUnit;
        break;
      case 30:
        parameterType = ParameterType.LoadClassification;
        break;
      default:
        parameterType = ParameterType.Invalid;
        break;
      }
    }
    __fault
    {
      \u003CModule\u003E.___CxxCallUnwindDtor(
        (__FnPtr<void (void*)>) __methodptr(REVIT_MAINTAIN_STATE\u002E\u007Bdtor\u007D),
          (void*) &revitMaintainState);
    }
    \u003CModule\u003E.REVIT_MAINTAIN_STATE\u002E\u007Bdtor\u007D(
      &revitMaintainState);
    return parameterType;
    }
  }
}

Here we can see that a parameter will have a DisplayUnitType only if the ParameterType is Length, Area, etc.. So we can just check if the ParameterType is one of the Length, Area, etc. ones. If so, its parameter has a DisplayUnitType, otherwise not.

It is necessary to pay attention to the line

  default:
    parameterType = (ParameterType) (
      ^(int&) ((IntPtr) &paramTypeSpec + 8) + 100);
    break;

Looking at the ParameterType enumeration suggests that every parameter type whose integer value is greater than 100 belongs to paramTypeSpec = 15.

As a result, I created the following extension method for the Parameter class:

public static class ParameterExtensions
{
  public static bool HasDisplayUnitType(
    this Parameter parameter )
  {
    var parameterType =
        parameter.Definition.ParameterType;
 
    switch( parameterType )
    {
      case ParameterType.Length:
      case ParameterType.Area:
      case ParameterType.Volume:
      case ParameterType.Angle:
      case ParameterType.Number:
      case ParameterType.Force:
      case ParameterType.LinearForce:
      case ParameterType.AreaForce:
      case ParameterType.Moment:
        return true;
    }
 
    /* At the reflector I can see the following code
          default:
            parameterType = (ParameterType) 
              (^(int&) ((IntPtr) &paramTypeSpec 
              + 8) + 100);
            break;
        looking at the ParameterType enumeration 
        suggests that every parameter type whose 
        integer value is greater than 100 belongs 
        to paramTypeSpec = 15
    */
    return 100 < (int) parameterType;
  }
}

Comparison Benchmarking

To wrap this up, here is a little benchmark comparing the two methods.

The first one exercises the try... catch block:

  Reference r;
 
  try
  {
    r = uidoc.Selection.PickObject(
      ObjectType.Element );
  }
  catch( OperationCanceledException )
  {
    message = "Cancelled";
    return Result.Cancelled;
  }
 
  var e = doc.GetElement( r.ElementId );
 
  Stopwatch sw = Stopwatch.StartNew();
 
  foreach( Parameter parameter in e.Parameters )
  {
    try
    {
      DisplayUnitType dut =
          parameter.DisplayUnitType;
 
      Debug.Print( dut.ToString() );
    }
    catch( Autodesk.Revit.Exceptions
      .InvalidOperationException )
    {
    }
  }
  sw.Stop();
 
  TaskDialog.Show( "Benchmark result",
    sw.Elapsed.ToString() );

Pick an element. The result is 0.41 seconds.

Second measurement, with my new method:

  Reference r;
 
  try
  {
    r = uidoc.Selection.PickObject(
      ObjectType.Element );
  }
  catch( OperationCanceledException )
  {
 
    message = "Canceled";
    return Result.Cancelled;
  }
 
  var e = doc.GetElement( r.ElementId );
 
  Stopwatch sw = Stopwatch.StartNew();
 
  foreach( Parameter parameter in e.Parameters )
  {
    if( parameter.HasDisplayUnitType() )
    {
      DisplayUnitType dut =
          parameter.DisplayUnitType;
 
      Debug.Print( dut.ToString() );
    }
  }
  sw.Stop();
 
  TaskDialog.Show( "Benchmark result",
    sw.Elapsed.ToString() );

The result is 0.029 seconds for the same element!

You may say that 0.41 seconds is not so much, and users will not notice the difference between 0.41 seconds and 0.028. Of course the difference is not huge if you work with only one element. But note that the exception handling code works 15 times slower, repeatedly, ever single time it is called!

If you retrieve parameters for 100 elements, it takes 41 seconds using try... catch instead of just 3 seconds with my new method.

I hope this enhancement will be useful for other developers as well.

Many thanks to Victor for his very professional analysis and valuable result!

The best of luck to you in your new job, Victor, and congratulations on that achievement!

IL Decompilation

I talked about Reflector way back in the early days of the blog. It since became commercial.

Victor mentions using dotPeek for his explorations above.

When I brought this up with my colleagues, Adam added that he uses the ILSpy .NET Decompiler and is perfectly happy with that as well.

Units and RevitLookup

Here is a typical question from a Revit API newbie that prompts me to reiterate some important basic beginner information on units and the RevitLookup tool for exploring the Revit database:

Question: How can I retrieve the length and mass units from a Revit document?

Answer: The internal Revit database length unit is always imperial feet.

That cannot be changed, so there is you answer for that.

Similarly, the internal database unit for weight is kg, as far as I know.

Revit Database Units

In fact, most internal Revit database units except length are SI units, and length is handled differently.

The user interface can display other units, set up just as the user prefers. They can also be modified programmatically, as demonstrated by the ProjectUnit SDK sample.

You can determine any internal database unit by setting the value of a given parameter using it on some Revit element to a specific number, e.g. 1.0, in the user interface.

You can then use RevitLookup to examine the parameter's resulting underlying database value.

The quotient between the user display and the underlying database values provides a factor that you can use to convert between user display and internal database units and enables you to determine what the internal database unit actually is.

This topic has been discussed exhaustively on The Building Coder blog. In fact, one of the very first posts ever is still perfectly valid. It deals with and covers all the fundamental facts of units.

We presented a unit conversion tool and updated it for Revit 2011 and 2013.

Many other aspects of this topic are collected in The Building Coder units category.

RevitLookup

I mentioned RevitLookup above. This is one of the most important tools, both for developers and end users, that you absolutely must be aware of.

It was formerly named RvtMgdDbg. This detailed description still calls it so.

Here are step-by-step installation instructions for Revit 2011 that pretty much still apply. There is even a video demonstrating the installation for Revit 2013.

RevitLookup is included in the Revit SDK available from the Revit Developer Center, which also includes all the other important material for getting started with the Revit API. Here is also an updated version with a corrected add-in manifest file to simplify the installation.

I hope that fully answers your question and helps you get started successfully.

Content Localisation

How to manage families and content creation is a crucial topic for a large number of Revit add-ins.

Brian Johnson, technical specialist on structural engineering solutions at Autodesk in Austin, Texas, discusses how to efficiently address some important aspects of this below.

First, however, let me wish everybody a Happy New Year of the Snake!

A year for reflection, planning and searching answers. A good time for shrewd dealings, political affairs and coups d'état. People will be more likely to scheme and ponder over matters before acting on them. An auspicious year for commerce and industry.

Let's hope so, indeed, and return to the issue of content localisation:

Content Localisation

Question: We have a large number of library items that we would like to work with in Revit, and they are used in many different countries and languages.

How can we manage this efficiently, please?

We would like to avoid duplicating any of the content, of course.

The differences include things like product name, description, part code, cost, and many other properties.

As far as I see, a Revit family cannot hold different values for a single property such as the item description.

What are your advice and the best practice for creating and maintaining a Revit family library for thousands of items and numerous languages?

Answer: Just as you say, Revit is not equipped to localise parameter names and types nor family names themselves.

Some level of automation will probably help significantly to solve or at least simplify this task.

A proof-of-concept for generating content from data and organizing content can be found in the Content Generator Extension available from the Autodesk Subscription centre. Note that all the Revit Extensions are bundled into a single download:

The content generator is intended for structural content from around the world using the section and material libraries (XML files) that also form the libraries for Robot Structural Analysis Professional and AutoCAD Structural Detailing:

I describe some of the inner workings of the Content Generator on pages 7-9 in the hand-out of my Autodesk University 2012 course SE3904 – Linking Revit Structure and Robot Structural Analysis: Beyond the Basics. For your convenience as a valued reader of The Building Coder, here is a direct download link.

I suggest installing the Extensions and trying it out. Your version of this might pull country specific data from your libraries/databases and generate a specific element for a specific language.

When considering creating your own custom families, my suggestion is to create the content with the best-suited family. If you use a specialised category like Structural Framing, you will get built-in parameters and behaviours that you may or may not want. The Generic Model set of family templates is the most basic and may be the most appropriate. I suggest populating the Identity Data and creating Shared Parameters for each family type and use those to filter, sort, and group the Schedule views in Revit.

As always, it is of utmost importance to discuss your plans with some of your Revit users and to get some training on how things are done in the typical workflows in Revit. This will help you understand what can be done with Revit out-of-the-box and what parts might use more automation.

Thank you, Brian, for the valuable advice!

MEP Family Editor Part Type Classes

While we are talking about content creation, here is another MEP specific question on the different classes of fitting types:

Question: I would like to know the definition for some of the part types of the fittings in the family editor.

Simple classes of fitting types like cap, cross, elbow, multiport, tap, transition, tee and union is clear, but I am uncertain about the more complex and less clear-cut parts.

Could you please clarify the following?

1. What is the difference between wye and pants?
2. Lateral tee and lateral cross are probably tees with an angle other than 90 degrees. They can also be rounded. Is this correct?
3. Offset is probably a kind of S-bend. Is this correct? Are eccentric transitions also included in this group?

Answer: Sure:

1. What is the difference between wye and pants?

It is no difference between creating wye and pants families. We just choose a part type that is close to the family name, which will makes sense if users check the part type.

Examples for wye:

Examples for pants:

2. Lateral tee and lateral cross are probably tees with an angle other than 90 degrees. They can also be rounded. Is this correct?

Again, lateral tee and lateral cross are used when the family name has similar words. The rule for using 'Lateral tee', 'Lateral cross' and 'Wye' is that the branch angle will be fixed when using the family in the project, so if the branch pipe has a different angle with the fitting, an elbow will be automatically added. If the part type is 'tee' or 'cross', the fitting will have a flexible angle branch itself.

Examples for lateral tee:

Example for lateral cross:

Lateral tee and lateral cross are also used as part types for pipe fittings, so they can be round as well.

3. Offset is probably a kind of S-bend. Is this correct? Are eccentric transitions also included in this group?

Examples for offset:

An eccentric transition should use the 'Transition' part type.

Parameters versus Properties

In his comment on reading material asset data, Alexander Buschmann points out that this same information can be accessed without retrieving, reading and converting the data directly from the undocumented built-in parameters.

Instead and more comfortably, you can use the following official properties on the appropriate classes:

  Material material = null;
 
  foreach( Material mat in e.Materials )
  {
    material = mat;
    break;
  }
  PropertySetElement pse = doc.GetElement(
    material.StructuralAssetId )
      as PropertySetElement;
 
  StructuralAsset asset = pse.GetStructuralAsset();
 
  double a = asset.WoodBendingStrength;
  double b = asset.WoodParallelCompressionStrength;
  double c = asset.WoodParallelShearStrength;
  double d = asset.WoodPerpendicularCompressionStrength;
  double f = asset.WoodPerpendicularShearStrength;

  // ... and lots of other properties ...

Even though a large and growing number of properties are available through this approach, the "Tension Parallel to Grain" one is actually currently not included in these, so you will indeed still have to use the direct parameter access anyway in this particular case.

Going through parameters is more generic, and most properties available on the classes are also available via parameters.

Parameters can also be used to define a parameter filter for a filtered element collector, so it is always useful to know that they are there and what they mean.

To discover the existence and use of specific parameters, you can use RevitLookup and BipChecker to explore a simple model. Modify the model interactively through the user interface and observe the effect on the parameters to discover their use and meaning.

He also adds:

For convenience, we use extension methods in our code to do this kind of thing, e.g.

public static class ElementExtensions
{
  public static Material material( this Element e )
  {
    foreach( Material m in e.Materials )
    {
      return m;
    }
    return null;
  }
}

If this class part of an imported namespace, it can be called as:

  Material material2 = e.material();

The compiler will translate that to this:

  Material material3
    = ElementExtensions.material( e );

It is mostly just convenience, but it also improves the readability of the code, since the entire loop above collapses into just this one single property call.

Many thanks to Alexander for pointing this out!

Here are some pointers to other extension methods that we discussed in the past:

• Scale a curve
• GetPolygon extension methods
• C# and .NET little wonders
• Top faces of sloped wall
• Unit conversion and display string formatting
• Materials collection and filtering
• RevitRubyShell implementation and installer
• Room in area predicate via point in polygon test
• FamilyParameter IsShared property

Show Viewport Extension Line or Label

Alexander also pointed out some other useful parameter to be aware of on the ViewType class in his comment on changing the viewport type, and my colleague Joe Ye just ran into a case dealing with the very same issue:

Question: We can change the length of the view title line:

For that we have to go to edit type and check the show extension line toggle:

It is possible to achieve this using the API?

Answer: Yes, you can set that check box via the API as well. Here is the process:

1. Get the view type object.
2. Get the parameter that represents the "Show Extension Line".
3. Change the parameter value.

Here is an example of performing these three steps:

  ElementId typeId = viewport.GetTypeId();
 
  ViewType viewtype = doc.GetElement( typeId )
    as ViewType;
 
  Parameter withLine = viewtype.get_Parameter(
    BuiltInParameter
      .VIEWPORT_ATTR_SHOW_EXTENSION_LINE );
 
  withLine.Set( 0 ); // No Line
  withLine.Set( 1 ); // Has Line

Alexander also points out that the built-in parameter VIEWPORT_ATTR_SHOW_LABEL affects the view label in a similar manner.

Change Element Workset

We discussed reading the workset of an element, either using the built-in parameter ELEM_PARTITION_PARAM or, more easily, the dedicated document GetWorksetId method.

This is actually another example of the possibility to choose your data access method by using either a dedicated property or a parameter, as we recently explored to achieve changing the viewport type.

Although the Revit API provides a dedicated property to read an element workset, it does not do so for changing it, which begs the question:

Question: The Element.WorksetId property is read-only.

I would like to change an element's workset to other one, though.

Is this possible?

Answer: You can change the element's workset via the built-in parameter ELEM_PARTITION_PARAM.

Here is a code snippet to show how to retrieve all workset ids and set each one to a given element in turn:

  Reference r = uidoc.Selection.PickObject( ObjectType.Element );
  Element e = doc.GetElement( r.ElementId );
 
  if( e == null )
    return;
 
  WorksetId wid = e.WorksetId;
 
  TaskDialog.Show( "Workset id", wid.ToString() );
 
  Parameter wsparam = e.get_Parameter(
    BuiltInParameter.ELEM_PARTITION_PARAM );
 
  if( wsparam == null )
    return;
 
  // Find all user worksets 
 
  FilteredWorksetCollector worksets
    = new FilteredWorksetCollector( doc )
      .OfKind( WorksetKind.UserWorkset );
 
  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "Change workset id" );
 
    foreach( Workset ws in worksets )
    {
      wsparam.Set( ws.Id.IntegerValue );
    }
 
    tx.Commit();
  }
  wid = e.WorksetId;
 
  TaskDialog.Show( "worksetid", wid.ToString() );

Many thanks to Phil Xia for this hint!

Read Material Asset Parameter

Even though it is still January, the days are already getting a little bit lighter, the sun has broken through now and then, sets half an hour later, some birds are starting to tweet around, and one can imagine spring coming...

Meanwhile, in the Revit API, accessing materials tends to be tricky, so here is one little sample that hopefully helps clarify by demonstrating how to read a parameter value from a PropertySetElement attached to a physical material asset.

Question: I'd like to know if there's an API to access the parameter called "Tension parallel to grain" in a wood material structural asset. The specific material I'm looking at is Softwood, Lumber and is present in a default new structural project.

There is a built-in parameter called PHY_MATERIAL_PARAM_TENSION_PARALLEL but that doesn't work. The RevitLookup tool does not list the parameter, even though it is shown in the Revit GUI.

The "Tension Parallel to Grain" parameter contains a Strength value, which is a double.

To access this through the GUI:

• Start a new model in Revit
• Go to Manage > Materials
• Scroll to a material that belongs to the wood category and contains a Structural Asset. In a new model, you can scroll to Softwood, Lumber.
• Select the Structural Asset (Physical Aspect).
• Expand the Strength section and you'll see the parameter.

The parameter is attached to the StructuralAsset element.

Here is the Softwood, Lumber material listed and selected in the material browser:

Selecting it and navigating to its physical aspect shows the tension parallel to grain value:

How can I access that data programmatically, please?

Answer: You can access this parameter using the PropertySetElement.

Assuming softwood is assigned to a selected element, the following code achieves this, including extracting the single selected element from the current document selection set:

public Result ReadMaterialParam( UIDocument uidoc )
{
  Document doc = uidoc.Document;
 
  Element e = null;
 
  Selection sel = uidoc.Selection;
 
  if( 1 == sel.Elements.Size )
  {
    foreach( Element e2 in sel.Elements )
    {
      e = e2;
    }
  }
 
  if( null == e )
  {
    TaskDialog.Show( "Error",
      "Please select one single element." );
 
    return Result.Failed;
  }
 
  Parameter paramMaterial = e.get_Parameter(
    BuiltInParameter.STRUCTURAL_MATERIAL_PARAM );
 
  Material material = doc.GetElement(
    paramMaterial.AsElementId() ) as Material;
 
  PropertySetElement property = doc.GetElement(
    material.StructuralAssetId ) as PropertySetElement;
 
  Parameter paramTensionParallel
    = property.get_Parameter( BuiltInParameter
      .PHY_MATERIAL_PARAM_TENSION_PARALLEL );
 
  TaskDialog.Show(
    "PHY_MATERIAL_PARAM_TENSION_PARALLEL",
    paramTensionParallel.AsValueString() );
 
  return Result.Succeeded;
}

This value cannot be read directly from the StructuralAsset properties.

To test run it, you can

• Create a new structural model.
• Insert a structural element, e.g. a beam, by loading the structural framing family and selecting the symbol "Dimension Lumber" 38x64.
• Assign "Softwood Lumber" to it via Properties > Structural Material > ...

Selecting the beam and launching the command calling the ReadMaterialParam method displays the following message on my system:

Duplicate Built-in Parameter Values and BipChecker Update

BipChecker is a tool that I would recommend every Revit developer to install, just like RevitLookup. It simply lists the values of all parameter data stored on a selected element.

Similar access is also offered within RevitLookup by the option Parameters > Built-in Enums Snoop... BipChecker offers much more functionality, though, and is a really powerful Revit database exploration and debugging tool.

The built-in parameter checker has been part of the ADN sample labs for ages now, and the original version is still provided in the Xtra materials. The time has come to finally remove it from there, though.

First, since I find it useful on its own, I extracted it into a separate add-in and baptised it BipChecker.

Secondly, Victor Chekalin enhanced it by implementing grouping of the long list by parameter group, data type, built-in versus standard Parameters collection, read-write, or none.

This tool always suffered one serious problem, though, due to repetitions in the definitions and assignment of some of the built-in parameter enumeration integer values.

Victor now tracked down and fixed that issue as well.

Here is his explanation:

Now I work closely with Materials and use our BiP checker. I noticed two strange things when I check material parameters using BiP Checker. The first one, the material cost stored as BuiltInParameter.DOOR_COST. The second one – some parameters appear twice or even triple:

I researched this and found the reason.

To iterate all built-in parameters, we used the Enum.GetValues method:

  var allParameters = Enum.GetValues(
    typeof ( BuiltInParameter ) );

This makes use of the integer values of the Enum. If different Enum values have the same integer value the GetValues method doesn’t work properly.

For example, BuiltInParameter.ALL_MODEL_COST and BuiltInParameter.DOOR_COST both have the integer value -1001205:

• DOOR_FIRE_RATING = -1001206
• ALL_MODEL_COST = -1001205
• DOOR_COST = -1001205
• ALL_MODEL_MARK = -1001203

In this case, BiPChecker shows DOOR_COST twice and doesn’t show ALL_MODEL_COST parameter at all.

The Solution

Use Enum.GetValues and Enum.TryParse instead of Enum.GetValues to get the BuiltInParameter value, and use the BuiltInParameter name from Enum.GetValues. This requires the .NET framework 4.

Now it looks much better:

Here is BipChecker05.zip containing the full source code, Visual Studio solution and add-in manifest of the updated BipChecker version 2013.0.5.0.

С уважением from Чекалин Виктор.

Many thanks to Victor for his research and important enhancement!

To wrap it up, here is a snapshot listing all built-in parameters on a wall with no grouping enabled, so that the results can be sorted across all groups by any desired criterion:

Changing Viewport Type

Here is a question on setting the type of an element by using the built-in ELEM_FAMILY_AND_TYPE_PARAM parameter value, explored by Bettina Zimmermann of NTI Cadcenter A/S:

Question: I'm inserting viewports on sheets and I'd like to change the viewport type to my own defined type.

How can I this programmatically?

By default, the API call creates a new viewport with type "Title w Line". I'd like to change that to e.g. my own type "Test".

Here is my own self-defined viewport type "Test":

I created it manually by pressing Duplicate.

The API method to create viewports does not support any viewport type parameter:

  Autodesk.Revit.DB.Viewport.Create(
    Document, viewSheet.Id, View.Id, zero )

I hope the viewport type can be changed in some other way.

Answer: When dealing with views and viewports, one of the first places to take a look is Steve Mycynek's AU class CP3133 Using the Revit Schedule and View APIs, which demonstrates just about everything you can do with the Revit View API.

Further, I would suggest that you explore the elements of interest in depth using RevitLookup.

The Element.GetTypeId method may provide read access to the data you seek. Unfortunately, of course, it is read-only. Maybe you can find some parameter that also provides access to this data?

Response: I did indeed find a parameter, well hidden in an unexpected location.

My first thought when searching for it is that the viewport is a system family, just like a wall, and walls allow you to change their type by setting wall.WallType = newWallType.

Walls also expect a type argument when a new wall is created:

  DB.Wall.Create( Document, Line, WallType.Id,
    Level.Id, 11, 0, False, IsStructural );

However, as said, the Viewport Create method does not take any type argument:

  Autodesk.Revit.DB.Viewport.Create(
    Document, viewSheet.Id, View.Id, zero );

In spite of this, the parameter I found that I can use for this is BuiltInParameter.ELEM_FAMILY_AND_TYPE_PARAM.

I created a VB.NET sample add-in ChangeViewPortType to demonstrate its use. Here is how to use it:

• Set a sheet view active with two viewports on it – could be two floor plans on a sheet.
• Change one of the viewports to another type – see below.
• Select both viewports and run sample project – the last selected viewport will be changed to have the same type as the first.

Here is a sheet with a viewport.

The default type of a newly created viewport is 'Title w Line'; I made a new type called 'Test' that has no 'Title' and 'Extension Line'. 'Title' and 'Extension Line' is the circle with a line and some text:

I made the type by clicking 'Edit Type' and duplicate.

Many thanks to Bettina for her exploration and thorough documentation!

Addendum: As pointed out below by Alexander Buschmann, the Revit API also provides the more user-friendly Element.ChangeTypeId method to directly change the type of any element having a type, with no need to go through the parameter to access it. Thanks, Alexander, for adding that!

Revit 2013 Unit Conversion Utility

Here is a Revit 2013 update of the Revit 2011 unit conversion utility, originally posted and described for Revit 2010, by Harry Mattison.

In his own words:

I was looking at the great unit conversion utility and created a new version upgraded to Revit 2013 that I thought you readers might enjoy.

I ran into one issue that required a code enhancement to catch an exception thrown by many parameters, such as HVAC_Temperature, HVAC_Slope, etc.

The rest of the code handles error conditions nicely, so I was surprised to see these uncaught exceptions.

I solved it by adding a try/catch statement around the existing call to AddParameter in frmUnitConversions.cs:

  if( null == _Parameter )
  {
    // Create a new parameter
 
    try
    {
      _Parameter
        = _DbDocument.FamilyManager.AddParameter(
          parameterTypeToCreate.ToString(),
          BuiltInParameterGroup.INVALID,
          parameterTypeToCreate,
          false );
    }
    catch( Exception ex )
    {
      TaskDialog.Show( "Error",
        "Cannot create parameter '"
        + parameterTypeToCreate.ToString()
        + "' with parameter type '"
        + parameterTypeToCreate
        + "' because of exception\n"
        + ex.Message.ToString() );
 
      return;
    }
  }

I think I figured out what is causing this and thought it would be interesting to share with your blog readers:

I am creating family parameters from a shared parameter file. Some parameters have types that are not supported in the version of Revit that I am currently using, which is Revit Architecture.

I created this function to detect the situation:

  public static bool canGetFormatOptions(
    Document doc,
    FamilyParameter familyParameter )
  {
    try
    {
      UnitType parameterUnitType
        = ConvertParameterTypeToUnitType(
          familyParameter.Definition.ParameterType );
 
      doc.ProjectUnit.get_FormatOptions(
        parameterUnitType );
 
      return true;
    }
    catch
    {
      return false;
    }
  }

I use it like this:

  if( !canGetFormatOptions(
    famDoc, familyParameter ) )
  {
    TaskDialog.Show( "Error",
      "Cannot set parameter value.\nUnit Type "
      + ConvertParameterTypeToUnitType(
        familyParameter.Definition.ParameterType )
      + " is not supported in Revit "
      + famDoc.Application.Product.ToString() );
  }

Take care.

The updated code is provided above.

Many thanks to Harry for this update with his enhancement and analysis!

Set Detail Curve Visibility

Mostly, the Revit API limits an add-in to pretty high-level operations, encapsulating and protecting the parametric BIM from reckless modifications. For the nonce, here is a little bit of nitty-gritty bit manipulation anyway, in a utility method provided by Scott Conover:

Question: Why is there no DetailCurve.SetVisibility method exposed, similar to ModelCurves.SetVisibility?

The UI has this functionality, and I would find very good use for it in reinforcement detailing.

I want to programmatically create a detail family representing a certain rebar shape. The family instance should reflect the visibility states, single line in coarse, double line in fine.

Answer: The ModelCurve.SetVisibility method taking a FamilyElementVisibility argument is available for visibility of curve elements in families when the families are placed. Similarly we have a SymbolicCurve.SetVisibility method. Detail curves don't have the exact same functionality in the UI. Generally, detail curves are visible only in a single view in which they are placed. The access you describe is partially enabled for detail families, however.

Here is a workaround to access this functionality: the visibility settings for the curve are stored in the integer GEOM_VISIBILITY_PARAM built-in parameter as bit flags. You can therefore request the desired display by setting the appropriate bits in that parameter value.

The SetFamilyVisibility method presented below turns off the modes you do not want for visibility. It can be called either from an external command or a macro.

It makes use of a simple selection filter to restrict the user selection to detail curves:

class DetailCurveSelectionFilter : ISelectionFilter
{
  public bool AllowElement( Element e )
  {
    CurveElementFilter filter
      = new CurveElementFilter(
        CurveElementType.DetailCurve );
 
    return filter.PassesFilter( e );
  }
 
  public bool AllowReference( Reference r, XYZ p )
  {
    return false;
  }
}

Here is the method implementation itself:

public void SetFamilyVisibility( UIDocument uidoc )
{
  Document doc = uidoc.Document;
 
  Reference r = uidoc.Selection.PickObject(
    ObjectType.Element,
    new DetailCurveSelectionFilter(),
    "Select detail curve" );
 
  Element elem = doc.GetElement( r );
 
  Parameter visParam = elem.get_Parameter(
    BuiltInParameter.GEOM_VISIBILITY_PARAM );
 
  int vis = visParam.AsInteger();
 
  using( Transaction t = new Transaction( doc ) )
  {
    t.Start( "Set curve visibility" );
 
    // Turn off the bit corresponding
    // to the unwanted modes
 
    vis = vis & ~( 1 << 13 ); // Coarse
    //vis = vis & ~(1 << 14); // Medium
    //vis = vis & ~(1 << 15); // Fine
 
    visParam.Set( vis );
 
    t.Commit();
  }
}

Remember that all three modes cannot be turned off simultaneously – a posted error will result.

Here is SetDetailCurveVisibility.zip containing the complete source code, Visual Studio solution and add-in manifest for an external command implementation of this.

Many thanks to Scott for this tricky hint!

Beam Bottom Endpoint

Here is a nice little example illustrating different approaches to find the end point of the bottom centre line of an inclined beam.

Question: I am trying to find the coordinates of the end points of the bottom centre line of an inclined beam. Depending on the beam angle, these coordinates will change.

Here is a 3D view of the kind of situation I am looking at:

The front view looks like this with the beam end points marked in orange. The desired bottom line end points are marked by red points within the circled areas:

I am currently using the following code to retrieve the beam location line start and end points:

  LocationCurve location = beam.Location as LocationCurve;
  Curve c = location.Curve;
  XYZ p = c.get_EndPoint( 0 );
  XYZ q = c.get_EndPoint( 1 );

Answer: There are an infinite number of ways to achieve this. Here are three to start with, in order of increasing purely personal preference:

• Face iteration and project
• Parameter values and trigonometry
• Perpendicular vector

Face Iteration and Project

One way to approach this is to use the beam solid faces and projection methods provided by the Revit geometry API to calculate the desired points.

You can determine the bottom face of the beam by querying the beam for its solid, iterating over its faces, and searching for the face whose normal vector has a minimal Z value, i.e. points downward the most. I provided source code samples implementing this for the bottom and top faces of a wall.

You can then project the beam location line end points onto that face using the Face.Project method to obtain the desired bottom line end points.

Parameter Values and Trigonometry

A second solution is based on querying some of the beam parameter values and using a little bit of trigonometry.

It calculates the sides of the right angle triangle using the beam direction vector, vertical delta and insertion value and returns the beam bottom coordinate as follows in C#:

void GetBeamInsertionAndVertDelta(
  Element beam,
  double sideLength,
  out double beamInsertion,
  out double beamVertDelta )
{
  // sideLength is beam height. 
  // If there is any other element like plate to 
  // be attached to beam bottom then 
  // sideLength = beam height + plate thickness
 
  beamInsertion = 0.0;
  beamVertDelta = 0.0;
 
  if( null != beam && _eps < Math.Abs( sideLength ) )
  {
    Parameter cutLength = beam.get_Parameter(
      BuiltInParameter.STRUCTURAL_FRAME_CUT_LENGTH );
 
    Parameter stOffset = beam.get_Parameter(
      BuiltInParameter.STRUCTURAL_BEAM_END0_ELEVATION );
 
    Parameter endOffset = beam.get_Parameter(
      BuiltInParameter.STRUCTURAL_BEAM_END1_ELEVATION );
 
    double hypotenuse = cutLength.AsDouble();
 
    double side = Math.Abs( stOffset.AsDouble() 
      - endOffset.AsDouble() );
 
    double angle = Math.Acos( side / hypotenuse );
 
    beamInsertion = ( sideLength / Math.Tan( angle ) );
    beamVertDelta = ( sideLength / Math.Sin( angle ) );
  }
}

Perpendicular Vector

The simplest solution may possibly be to avoid using the beam geometry as well as the tan and sin functions and just calculate straight away based on the beam location line.

You can determine the vector perpendicular to the beam location line and pointing downward as much as possible, i.e. lying in the plane P defined by the (non-vertical!) location line and the global Z axis.

Let's say the beam location line top two endpoints are stored in 'p' and 'q'. To determine the bottom points, we just need to know the height 'h' of the beam cross section and calculate a vector 'v' of length 'h' pointing downward and perpendicular to the beam location line. The desired points are given by p + v and q + v.

I used a similar calculation to determine the wall width or thickness vector 'w' to display the wall compound layers, except that it is horizontal, i.e. has a zero Z component, instead of lying in the plane P, with a minimal (negative) Z component.

Something like this untested snippet should do the job, given the beam location curve start point 'p', end point 'q' and height 'h' as defined above:

  XYZ u = q - p;
  XYZ w = XYZ.BasisZ.Cross( u );
  XYZ v = h * w.Cross( u ).Normalized;

As said, the desired points are then given by p + v and q + v.

Determine Hosted Family Host Type

On a different topic, in his latest AEC DevBlog post, Saikat Bhattacharya explains how you can determine the base host type of a hosted family via the Host parameter on the family document owner family property, which stores the following integer values corresponding to the FamilyHostingBehavior enumeration:

0. None
1. Wall
2. Floor
3. Ceiling
4. Roof
5. Face

The parameter value is zero, i.e. None, for families created using line and pattern based templates, so their host type cannot be determined using this method.

Note that if you have a face-based family instance, you can query its Host and HostFace properties to retrieve the host element and a reference to the hosting face, respectively.

Two more interesting methods to explore in this context are the FamilyCanConvertToFaceHostBased and ConvertFamilyToFaceHostBased methods provided by the FamilyUtils class.

Detach Workset and TaskDialog Command Link Order

Here is a neat and simple solution using the DialogBoxShowing event to detach and discard worksets by Erik Eriksson of White Arkitketer AB, who already provided a useful workaround to synchronize with central using SendKeys in combination with the Idling and DocumentSynchronizedWithCentral events.

Here is the issue:

Question: We have a need to detach project files without worksets.

For instance, it would be great to just have an option to detach and discard worksets.

Why do we need this?

This would be useful for our in-house tools to diagnose project files. For this to work, we need to have the project files without worksets, because we delete different types of elements and check the file size before and afterwards. To determine a correct file size, we need to compact the files after every operation. This cannot be done programmatically, but, for non-workshared files, it is performed automatically each time the project file is saved.

Currently, we execute the detach and discard operation manually. However, with big projects containing many files, it would be nice to do less of these things manually.

Answer: The API currently does not provide this functionality directly.

However, the Revit 2013 API added some new document handling and worksharing changes which may help. Here is the description from the What's New section in the Revit API help file RevitAPI.chm:

Worksharing properties

The information required to identify a workshared file on the central or local locations has changed due to changes to RevitServer. As a result, the members

• Application.GetRevitServerNetworkHosts
• Application.CurrentRevitServerAccelerator
• Document.WorksharingCentralFilename

replace the properties

• Application.CentralServerName
• Application.LocalServerName
• Document.GetWorksharingCentralModelPath

The new members:

• Application.GetWorksharingCentralGUID(ServerPath serverModelPath)
• Document.WorksharingCentralGUID

provide read access to the worksharing central GUID of the given server-based model. This is applicable only to workshared models saved in Revit 2013 or later.

New overloads for Application.OpenDocumentFile and UIApplication.OpenAndActivateDocument

The new overloads support parameters OpenOptions and OpenOptionsForUI, respectively, to specify how a Revit document should be opened. Both options classes currently offer the ability to detach the opened document from central if applicable.

• The OpenOptions.DetachFromCentralOption property can be set to the default DoNotDetach or to DetachAndPreserve.
• The OpenOptionsForUI.DetachFromCentralOption property can be set to the default DoNotDetach, DetachAndPreserveWorksets or DetachAndPrompt.

In other words, the OpenOptions argument that you pass in to the OpenDocumentFile and OpenAndActivateDocument methods can now use the DetachFromCentral option to specify whether or not a workset-enabled document is detached from its central document.

Response: The new API functionality still does not provide the option of discarding the worksets.

I want the file to be a normal project file again.

OpenOptions holds the same options as OpenOptionsForUI (besides DetachAndPrompt). However, maybe I can catch that dialogue programmatically using the DialogBoxShowing event and override the result...

Success!

This is the code I used to fix it:

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

The full implementation of this method actually includes a few more statements taking care of other dialogue boxes, which I omitted here.

I checked the IsWorkshared property after opening the file, and it was set to false. This indicates that it is no longer workshared, which means that the operation to discard the worksets succeeded. When you discard worksets, the workshared central file goes back to being a normal non-workshared project file, just like what you obtain when starting from a normal project template.

One thing I do wonder about is whether CommandLink2 is always below CommandLink1 and above CommandLink3?

Answer: It would appear so, since the description of the TaskDialog.AddCommandLink method clearly states that "CommandLinks will always be shown in the dialog in the order of their ids".

Also, as always, keep in mind that there is no guarantee that this will continue working in future releases. The order of these options can change at any time, and the required functionality might even be added to the official API one of these days.

Congratulations on solving this, Erik, and thank you for sharing it and providing this helpful explanation!

Setting IndependentTag Label to Pick Up a Parameter Value

I'll wrap up with a quick pointer to another AEC DevBlog article by Saikat Bhattacharya on defining the label displayed by an IndependentTag. Unfortunately this does not seem to be possible programmatically. It can however easily be achieved using an appropriate template or tag family configuration.

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.

Group My Own Commands in the Ribbon

Here is an issue that has been presented numerous times in the past, and apparently needs to be highlighted again for newbies.

Question: I have implemented a Revit add-in which implements several commands.

Currently, I have added all my commands to the add-in manifest file, as recommended by various examples I found on the Internet. It works and they do indeed appear in the Add-Ins ribbon tab under the 'External Tools' pull-down menu.

The problem with this is that other commands from other companies' add-ins appear in the same place and are mixed up with mine.

Is there some possibility to group my own commands somehow?

I would like to have my commands separated from the other companies' ones.

For example, is it possible to add a parent category for my commands in the 'External Tools' category, or to group them in some other way, for instance by creating a special ribbon category other than 'External Tools'?

Answer: Yes, there are several simple ways to group your commands separately.

You can define your own panel in the Add-Ins tab using the CreateRibbonPanel method. This is the recommended approach.

If you really want, you can also define your own ribbon tab. However, this is not recommended.

The former approach is demonstrated by many examples. For instance, I implemented an absolutely minimal separate add-in tab providing one single button to demonstrate enabling ribbon items in zero document state.

The structural concrete setout point add-in is very slightly more complex, providing two buttons :-)

The ADN training material on the Revit UI includes an entire class on the topic of ribbon customisation which covers almost every possibility provided for creating your own ribbon items. You can either look at the Xtra version (recently updated) or the standard material from the Revit Developer Center.

Read the documentation explaining the ribbon UI exercise, "Revit Ui Lab1 - Ribbon.doc", provided separately for C# and VB in the subdirectories DocsCS and DocsVB of the 2_Revit_UI_API folder.

Sample source code is also provided separately for both C# and VB, respectively:

• 2_Revit_UI_API/SourceCS/1_Ribbon.cs
• 2_Revit_UI_API/SourceVB/1_Ribbon.vb

Read-Only Parameter Workaround

To add a little hint for more advanced Revit API users, another frequently asked question has to do with read-only parameters.

Developers would often like to add parameters that cannot be modified to a family definition. However, the Revit API currently does not provide any support for creating read-only parameters, unfortunately.

One way to make a parameter a little bit harder to modify anyway is to define its value via a formula instead of setting the value directly:

  FamilyParameter p 
    = famMgr.get_Parameter( name );

  if( null == p )
  {
    p = famMgr.AddParameter( name, 
      BuiltInParameterGroup.PG_GENERAL, 
      ParameterType.Text, false );
  }
 
  if( p.StorageType 
    == StorageType.String )
  {
    if( '\"' != val[0] )
    {
      val = "\"" + val + "\"";
    }
    famMgr.SetFormula( p, val );
  }

ADSK File Import and Phase of Room

I already had one look at loading an Inventor ADSK component using the OpenBuildingComponentDocument method.

Ishwar Nagwani of Autodesk Consulting now revisited this topic from a different perspective and explains:

I came across another tricky issue while developing Revit add-in to import an ADSK file. I looked at your previous post on this when I started looking for way to open ADSK file in Revit and it helped me lot.

The ADSK file is created in Inventor and then processed in Revit to create an RFA file. This is part of a bigger project which does lots of other stuff like adding shared parameters etc.

The ADSK file after importing contains two ImportInstances. One of these is the bounding box, the other is the main solid itself. The outer bounding box hides the geometry in elevation views. Here the bounding box which would be deleted is displayed in red:

These are the selected bounding box details displayed using RevitLookup:

I open the ADSK file using the OpenBuildingComponentDocument method and then delete the bounding box in a separate transaction.

The following method retrieves the ImportInstances and deletes the one representing the bounding box, identified by the fact that it only has exactly six faces:

/// <summary>
/// This method deletes the outer bounding box 
/// of an imported ADSK file in Revit. If this 
/// bounding box is not deleted, the elevation 
/// views cannot be seen. After importing an 
/// ADSK file the two ImportInstance objects 
/// are created in Revit, one for outer 
/// bounding box and the other for main solid.
/// </summary>
void DeleteOuterBox( Document doc )
{
  // Instantiate this once only:
 
  Options opt = doc.Application.Create
    .NewGeometryOptions();
 
  // This is probably not needed:
 
  //opt.ComputeReferences = true;
 
  // Search the elements of type ImportInstance;
  // there will be two in case of ADSK import:
 
  FilteredElementCollector collector 
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ImportInstance ) );
 
  ElementId idToDelete = null;
 
  foreach( Element e in collector )
  {
    ImportInstance inst = e as ImportInstance;
 
    if( inst != null )
    {
      // Get the Solid from ImportInstance
 
      GeometryElement geomElem 
        = inst.get_Geometry( opt );
 
      // GeometryElement.Objects is obsolete,
      // so use LINQ extension methods instead.
 
      //GeometryObjectArray geomObjArray 
      //  = geomElem.Objects;
 
      int n = geomElem.Count<GeometryObject>();
 
      if( 1 == n )
      {
        Solid solid = geomElem
          .First<GeometryObject>() as Solid;
 
        if( null != solid )
        {
          // The outer bounding box
          // has just 6 faces.
 
          if( solid.Faces.Size == 6 )
          {
            // Do not delete during iteration;
            // remember the id instead.
 
            //doc.Delete( e.Id );
 
            idToDelete = e.Id;
 
            break;
          }
        }
      }
 
      if( null != idToDelete )
      {
        doc.Delete( idToDelete );
      }
    }
  }
}

Many thanks to Ishwar for this nice example!

Determining the Phase of a Room

Here is another issue brought up and solved by Håkon Clausen, whose RevitRubyShell I recently waxed so enthusiastic about:

Question: How do I find which phase a room is in?

From the UI, the phase is uneditable and is the same phase as the view you created it in. Unfortunately, the room CreatedPhaseId and DemolishedPhaseId properties are not valid (-1, InvalidElementId) and the Room class provides no explicit phase access. I looked through your posts regarding phases, on phase dependent room properties and the family instance room phase. They do not help, as they only describe how to determine the phases on family instances, not on the room itself.

Answer: I solved it by reading the built-in parameter value for ROOM_PHASE_ID on the room element.

On an interesting side note, I needed the same information for Mechanical.Space objects, and this also worked by accessing the same built-in parameter ROOM_PHASE_ID, which is a little obscure, I think...

Thank you, Håkon, for raising and clarifying this.

The same credit also goes to Martino, who posted a comment to the same effect on the view and phase filtering discussion.

Change Section View Type and Hide Cut Line

Leo raised a couple of questions on section view creation in his comment which Rudolf Honke very kindly answers thus:

1. Hide view: To hide the cutting line in a plan view, you can use this parameter:

  viewSection.get_Parameter( BuiltInParameter
    .SECTION_COARSER_SCALE_PULLDOWN_METRIC )
      .Set( 1 );

2. Generate section view: In Revit 2013, you can use the static method

  public static ViewSection CreateSection(
    Document document,
    ElementId viewFamilyTypeId,
    BoundingBoxXYZ sectionBox
  )

In Revit 2012, you can use document.Create.NewViewSection( BoundingBoxXYZ );

3. Change the type of a detail view: Each view has a view type, e.g. a section view symbol. These symbols have no category to help identify them, they are just generic ElementType instances. The types can be retrieved using their name, e.g. "Section" etc. Once you have a view symbol, you can change the view type by simply setting its type id:

  viewSection.ChangeTypeId( symbolSection.Id ); 

Since section symbols are identified by name, they are language dependent and there is no guarantee to find them at all, depending on the template being used.

Many thanks to Rudolf for these important hints!

Create a Pipe Cap

Happily mixing the different Revit versions, let me follow up my work on the Revit MEP 2013 API and the updated AdnRme sample by another MEP related topic.

Before getting to that, though, here is a brief heads-up for a new technology preview on Autodesk Labs:

BIM Coordinator

The effective organization of project data in shared or related coordinates is essential to effective collaboration across disciplines and good quality project information. BIM Coordinator for AutoCAD Civil 3D and Revit is a technology preview that assists project team members with building and site grids.

Here is a brief overview taken from the labs:

Building grids are generally selected based on the layout and shape of the building, usually using the lower left corner of the selected orientation as a reference point. Building grids are established by the lead designer of a project for use by all members of the building design team. This grid ensures that different disciplines' building designs use the same reference for purposes of building analyses, drawing production, and other tasks requiring coordinated building data.

Site grids are generally based on Northing and Easting coordinates. They are usually established for a region; although arbitrary grids can be established for a single project or site. For example, in the UK most sites are related to the Ordinance Survey (OS) grid. Site elevations (levels) are also based on an OS benchmark or other site/project benchmark.

BIM Coordinator automates the more error-prone manual steps in the coordination of site and building grids between the AutoCAD and Revit environments, currently for the 2012 versions. The tool specifies one common XYZ point and its orientation in the XY plane between the two coordinate systems. This reference point defines the relationship between the building and site grid.

Miroslav Schonauer will be explaining some background and sharing source code from this utility at the upcoming AEC DevCamp in Waltham June 6-7.

Create a Pipe Cap

Back to the Revit MEP API, I presented an example to create a pipe cap in Revit 2011 over a year ago.

Now Mick Kulik of Hydratec, Inc. discovered that the existing sample code did not work in his case, and worked together with Saikat Bhattacharya at the AutoCAD DevLab in San Rafael to fix this issue for Revit 2012.

Here is the original problem and its solution:

Question: Following the post about creating a pipe cap, I was not able to get a cap to connect to a pipe in Revit MEP 2012. The Error is "Line is too short". Is there a new way to connect caps to pipes in Revit MEP 2012?

Answer: Saikat came down to give us a hand last week at the AutoCAD DevLab in San Rafael. He had some sample code to attach caps to sloping pipes. I was able to massage his code to fit our needs, and have attached his CapAtStartOfPipe.zip containing the entire source code and Visual Studio solution implementing this command.

Saikat's code worked on all the cases we tested except when trying to connect the cap to a non-sloped vertical pipe, so I built in a case to handle it which worked for my test cases:

  // rotate the cap if necessary
 
  // rotate about Z first

  XYZ pipeHorizontalDirection 
    = new XYZ( dir.X, dir.Y, 0.0 ).Normalize();
 
  ConnectorSet c2 
    = fi.MEPModel.ConnectorManager.Connectors;
 
  Connector capConnector = null;
 
  foreach( Connector c in c2 )
  { 
    capConnector = c; 
  }
 
  XYZ connectorDirection 
    = -capConnector.CoordinateSystem.BasisZ;
 
  double zRotationAngle 
    = pipeHorizontalDirection.AngleTo( 
      connectorDirection );
 
  Transform trf = Transform.get_Rotation( 
    start, XYZ.BasisZ, zRotationAngle );
 
  XYZ testRotation = trf.OfVector( 
    connectorDirection ).Normalize();
 
  if( Math.Abs( testRotation.DotProduct( 
    pipeHorizontalDirection ) - 1 ) > 0.00001 )
  {
    zRotationAngle = -zRotationAngle;
  }
 
  Line axis = doc.Application.Create.NewLineBound( 
    start, start + XYZ.BasisZ );
 
  ElementTransformUtils.RotateElement( 
    doc, fi.Id, axis, zRotationAngle );
 
  // Need to rotate vertically?
 
  if( Math.Abs( dir.DotProduct( XYZ.BasisZ ) ) 
    > 0.000001 )
  {
    // if pipe is straight up and down, 
    // kludge it my way else
 
    if( dir.X == 0 && dir.Y == 0 && dir.Z != 0 )
    {
      XYZ yaxis = new XYZ( 0.0, 1.0, 0.0 );
 
      double rotationAngle = dir.AngleTo( yaxis );
 
      if( dir.Z == 1 )
      {
        rotationAngle = -rotationAngle;
      }
 
      axis = doc.Application.Create.NewLine( 
        start, yaxis, false );
 
      ElementTransformUtils.RotateElement( 
        doc, fi.Id, axis, rotationAngle );
    }
    else
    {
      #region sloped pipes
 
      double rotationAngle = dir.AngleTo( 
        pipeHorizontalDirection );
 
      XYZ normal = pipeHorizontalDirection
        .CrossProduct( XYZ.BasisZ );
 
      trf = Transform.get_Rotation( 
        start, normal, rotationAngle );
 
      testRotation = trf.OfVector( dir ).Normalize();
 
      if( Math.Abs( testRotation.DotProduct( 
        pipeHorizontalDirection ) - 1 ) < 0.00001 )
      {
        rotationAngle = -rotationAngle;
      }
 
      axis = doc.Application.Create.NewLineBound( 
        start, start + normal );
 
      ElementTransformUtils.RotateElement( 
        doc, fi.Id, axis, rotationAngle );
 
      #endregion
    }
  }
 
  doc.Regenerate();
 
  // pick connector on cap:
 
  ConnectorSet connectors 
    = fi.MEPModel.ConnectorManager.Connectors;
 
  Debug.Assert( 1 == connectors.Size, 
    "expected only one connector on pipe cap element" );
 
  Connector cap_end = null;
 
  foreach( Connector c in connectors )
  { 
    cap_end = c; 
  }
 
  // pick closest connector on pipe:
 
  connectors = pipe.ConnectorManager.Connectors;
 
  Connector pipe_end = null;
  double dist = double.MaxValue;
  foreach( Connector c in connectors )
  {
    XYZ p = c.Origin;
    double d = p.DistanceTo( start );
    if( d < dist )
    {
      dist = d;
      pipe_end = c;
    }
  }
  pipe_end.ConnectTo( cap_end );
 
  doc.Regenerate();
 
  // After ConnectTo, the cap size is double, so 
  // need to change the nominal radius to half.
 
  if( fi != null )
  {
    ConnectorSet pipeConnectors 
      = pipe.ConnectorManager.Connectors;
 
    Connector pipeEnd = null;
 
    foreach( Connector c in pipeConnectors )
    {
      pipeEnd = c;
    }
    double radius = pipeEnd.Radius;
 
    Parameter para = fi.get_Parameter( 
      "Nominal Radius" );
 
    if( para != null && !para.IsReadOnly )
    {
      para.Set( radius );
    }
  }

Here is a screen capture of the result of testing caps on a vertical pipe:

Many thanks to Saikat and Mick for providing this new sample!