The Building Coder

Extrusion Analyser and Plan View Boundaries

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I looked at using the ExtrusionAnalyzer to create a plan view boundary profile for the furniture and equipment family instances and implemented a utility method SortCurvesContiguous to sort and re-orient the curves it returns into a closed contiguous loop.

I did not yet display the code driving the extrusion analyser, though, or discuss my experiences with that.

Those are the topics of today's post:

• Using the ExtrusionAnalyzer class
• Handling ExtrusionAnalyzer failures
• Testing the ExporterIFCUtils ValidateCurveLoops method
• First conclusion and capitulation
• Reimplementation with a Boolean union
• Conclusion, next steps and download
• New Revit Add-ins

Using the ExtrusionAnalyzer Class

Using the extrusion analyser is simple:

1. Retrieve and traverse the element geometry:

/// <summary>
/// Retrieve all plan view boundary loops from 
/// all solids of given element.
/// </summary>
JtLoops GetPlanViewBoundaryLoopsMultiple(
  Element e,
  ref int nFailures )
{
  Autodesk.Revit.Creation.Application creapp
    = e.Document.Application.Create;
 
  JtLoops loops = new JtLoops( 1 );
 
  Options opt = new Options();
 
  GeometryElement geo = e.get_Geometry( opt );
 
  if( null != geo )
  {
    Document doc = e.Document;
 
    if( e is FamilyInstance )
    {
      geo = geo.GetTransformed(
        Transform.Identity );
    }
 
    foreach( GeometryObject obj in geo )
    {
      AddLoops( creapp, loops, obj, ref nFailures );
    }
  }
  return loops;
}

2. For each solid, instantiate an ExtrusionAnalyzer, retrieve and process its resulting output curves:

/// <summary>
/// Add all plan view boundary loops from 
/// given solid to the list of loops.
/// The creation application argument is used to
/// reverse the extrusion analyser output curves
/// in case they are badly oriented.
/// </summary>
/// <returns>Number of loops added</returns>
int AddLoops(
  Autodesk.Revit.Creation.Application creapp,
  JtLoops loops,
  GeometryObject obj )
{
  int nAdded = 0;
 
  Solid solid = obj as Solid;
 
  if( null != solid
    && 0 < solid.Faces.Size )
  {
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    ExtrusionAnalyzer extrusionAnalyzer = null;
 
    extrusionAnalyzer = ExtrusionAnalyzer.Create(
      solid, plane, XYZ.BasisZ );
 
    Face face = extrusionAnalyzer
      .GetExtrusionBase();
 
    foreach( EdgeArray a in face.EdgeLoops )
    {
      int nEdges = a.Size;
 
      List<Curve> curves
        = new List<Curve>( nEdges );
 
      XYZ p0 = null; // loop start point
      XYZ p; // edge start point
      XYZ q = null; // edge end point
 
      foreach( Edge e in a )
      {
        Curve curve = e.AsCurve();
 
        if( _debug_output )
        {
          p = curve.get_EndPoint( 0 );
          q = curve.get_EndPoint( 1 );
          Debug.Print( "{0} --> {1}",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        curves.Add( curve );
      }
 
      CurveUtils.SortCurvesContiguous(
        creapp, curves, _debug_output );
 
      q = null;
 
      JtLoop loop = new JtLoop( nEdges );
 
      foreach( Curve curve in curves )
      {
        // Todo: handle non-linear curve.
        // Especially: if two long lines have a 
        // short arc in between them, skip the arc
        // and extend both lines.
 
        p = curve.get_EndPoint( 0 );
 
        loop.Add( new Point2dInt( p ) );
 
        Debug.Assert( null == q
          || q.IsAlmostEqualTo( p, 1e-05 ),
          string.Format(
            "expected last endpoint to equal current start point, not distance {0}",
            (null == q ? 0 : p.DistanceTo( q ))  ) );
 
        q = curve.get_EndPoint( 1 );
 
        if( _debug_output )
        {
          Debug.Print( "{0} --> {1}",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        if( null == p0 )
        {
          p0 = p; // save loop start point
        }
      }
      Debug.Assert( q.IsAlmostEqualTo( p0, 1e-05 ),
        string.Format(
          "expected last endpoint to equal current start point, not distance {0}",
          p0.DistanceTo( q ) ) );
 
      loops.Add( loop );
 
      ++nAdded;
    }
  }
  return nAdded;
}

Handling ExtrusionAnalyzer Failures

The desk solids are processed perfectly well by the extrusion analyser, but two of the chair solids produce failures. This is the standard Revit content 'Furniture Chair - Office' returning invalid solids.

Since I don't (yet?) know how to detect beforehand whether a solid will cause a failure or not, the only option I see is to encapsulate the extrusion analyser implementation in an exception handler. I also added code to report how many failures occur:

  ExtrusionAnalyzer extrusionAnalyzer = null;
 
  try
  {
    extrusionAnalyzer = ExtrusionAnalyzer.Create(
      solid, plane, XYZ.BasisZ );
  }
  catch( Autodesk.Revit.Exceptions
    .InvalidOperationException )
  {
    ++nExtrusionAnalysisFailures;
    return nAdded;
  }
 
  Face face = extrusionAnalyzer
    .GetExtrusionBase();

Testing the ExporterIFCUtils ValidateCurveLoops Method

Rudolf Honke added a very valid suggestion to my SortCurvesContiguous implementation: You may have a look at ExporterIFCUtils.ValidateCurveLoops method. RevitApi.chm says: "Does validity checks on a list of curve loops to ensure that they are all co-planar, closed, and properly oriented." I have never tested this method, but perhaps it prevents you from inventing the wheel another time...

I like that suggestion a lot and am interested to find out how useful this method might be.

It takes a list of curve loops and returns a new list of curve loops "properly oriented, if possible. If not, the return contains no loops."

I added code to test this method, passing in to it the output produced by the extrusion analyser:

  // Test ValidateCurveLoops
 
  CurveLoop loopIfc = new CurveLoop();
 
  foreach( Edge e in a )
  {
    Curve curve = e.AsCurve();
 
    if( _debug_output )
    {
      p = curve.get_EndPoint( 0 );
      q = curve.get_EndPoint( 1 );
      Debug.Print( "{0} --> {1}",
        Util.PointString( p ),
        Util.PointString( q ) );
    }
 
    curves.Add( curve );
 
    // Throws an exception saying "This curve 
    // will make the loop not contiguous. 
    // Parameter name: pCurve"
 
    loopIfc.Append( curve );
  }
 
  // We never reach this point:
 
  List<CurveLoop> loopsIfc
    = new List<CurveLoop>( 1 );
 
  loopsIfc.Add( loopIfc );
 
  IList<CurveLoop> loopsIfcOut = ExporterIFCUtils
    .ValidateCurveLoops( loopsIfc, XYZ.BasisZ );

Unfortunately, the CurveLoop Append method throws an exception saying "This curve will make the loop not contiguous. Parameter name: pCurve".

It obviously expects contiguous curves to be passed in and can therefore not be used to re-orient curves if they are oriented the wrong way.

So much for that suggestion. You got my hopes up there, Rudolf, but no luck this time.

First Conclusion and Capitulation

My first (erroneous) conclusion for the extrusion analyser was simple: the output I receive for a plan view is much too complex for my use.

I was expecting it to return the simplest possible contour to represent the shadow cast by the solid passed in. The results include lots of extraneous loops that do not contribute to the shadow of the object.

Oops.

Since I am passing in the multiple solids from the desk and the chair to the extrusion analyser one by one, individually, it is obviously returning a plan view boundary outline for each one of the solids, individually, as well.

At first glance I thought that this result is much too complicated for me to handle, since all I want is one single boundary for the whole object.

For a moment, I gave up on the whole idea of using the extrusion analyser and decided to switch to a 2D plan view instead, and ask for the view-specific family instance representation in that view. For the desk, that would simply give me the desired rectangular outline.

Capitulation.

Then I switched on my brain for a second again and realised the obvious fact that individual solids will generate individual outlines.

I decided to give the extrusion analyser another go, unite all the solids into one single one, then pass that in to a single call of the extrusion analyser.

Reimplementation with a Boolean Union

'Gesagt, getan', as the Germans say, 'No sooner said than done', 'a word and a blow'.

I united all the desk solids, passed the resulting union in to the extrusion analyser, and it produces a single closed loop.

I united all the chair solids, passed the resulting union in to the extrusion analyser, and it produces one single failure.

Oh no!

The individual chair solids causing a failure when passed in individually also cause a failure when united with the unproblematic ones.

Next idea:

• Extract the family instance solids from the geometry one by one.
• Test each solid by passing it in to the extrusion analyser on its own.
• If it causes a failure, discard it.
• If it does not, unite it with the others.
• Pass in the union of all non-failing solids to the extrusion analyser.
• Retrieve the resulting curves.
• Sort and re-orient the curves to form a contiguous closed loop.
• Convert the closed loop data to my integer-based 2D format.

Here is the final code for achieving this:

/// <summary>
/// Retrieve all plan view boundary loops from 
/// all solids of given element united together.
/// </summary>
JtLoops GetPlanViewBoundaryLoops(
  Element e,
  ref int nFailures )
{
  Autodesk.Revit.Creation.Application creapp
    = e.Document.Application.Create;
 
  JtLoops loops = new JtLoops( 1 );
 
  Options opt = new Options();
 
  GeometryElement geo = e.get_Geometry( opt );
 
  if( null != geo )
  {
    Document doc = e.Document;
 
    if( e is FamilyInstance )
    {
      geo = geo.GetTransformed(
        Transform.Identity );
    }
 
    Solid union = null;
 
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    foreach( GeometryObject obj in geo )
    {
      Solid solid = obj as Solid;
 
      if( null != solid
        && 0 < solid.Faces.Size )
      {
        // Some solids, e.g. in the standard 
        // content 'Furniture Chair - Office' 
        // cause an extrusion analyser failure,
        // so skip adding those.
 
        try
        {
          ExtrusionAnalyzer extrusionAnalyzer
            = ExtrusionAnalyzer.Create(
              solid, plane, XYZ.BasisZ );
        }
        catch( Autodesk.Revit.Exceptions
          .InvalidOperationException )
        {
          solid = null;
          ++nFailures;
        }
 
        if( null != solid )
        {
          if( null == union )
          {
            union = solid;
          }
          else
          {
            union = BooleanOperationsUtils
              .ExecuteBooleanOperation( union, solid,
                BooleanOperationsType.Union );
          }
        }
      }
    }
    AddLoops( creapp, loops, union, ref nFailures );
  }
  return loops;
}

This is the current result for my simple sample model (copy the text to see the truncated lines in full):

Room Rooms <212639 Room 1> has 2 loops:
  0: (2753,3087), (-4446,3087), (-4446,587), (-746,587), (-746,-1212), (2753,-1212)
  1: (298,-112), (298,587), (1698,587), (1698,-112)
FamilyInstance Furniture Desk <212646 1525 x 762mm> has 1 loop:
  0: (664,2561), (664,1761), (2227,1761), (2227,2561), (2056,2561), (2056,2580), (1954,2580), (1954,2561), (937,2561), (937,2580), (836,2580), (836,2561)
FamilyInstance Furniture Desk <212801 1525 x 762mm> has 1 loop:
  0: (-1200,2561), (-1200,1761), (362,1761), (362,2561), (191,2561), (191,2580), (89,2580), (89,2561), (-927,2561), (-927,2580), (-1028,2580), (-1028,2561)
FamilyInstance Furniture Desk <213000 1525 x 762mm> has 1 loop:
  0: (-4135,2561), (-4135,1761), (-2572,1761), (-2572,2561), (-2743,2561), (-2743,2580), (-2845,2580), (-2845,2561), (-3862,2561), (-3862,2580), (-3963,2580), (-3963,2561)
FamilyInstance Furniture Chair - Office <214027 Office Chair>: 2 extrusion analyser failures
FamilyInstance Furniture Chair - Office <214027 Office Chair> has 1 loop:
  0: (-3581,1142), (-3581,1162), (-3561,1162), (-3561,1502), (-3581,1502), (-3581,1542), (-3561,1542), (-3561,1577), (-3021,1577), (-3021,1542), (-3001,1542), (-3001,1502), (-3021,1502), (-3021,1162), (-3001,1162), (-3001,1142), (-3021,1142), (-3021,1108), (-3561,1108), (-3561,1142)
FamilyInstance Furniture Chair - Office <214138 Office Chair>: 2 extrusion analyser failures
FamilyInstance Furniture Chair - Office <214138 Office Chair> has 1 loop:
  0: (-636,1142), (-636,1162), (-616,1162), (-616,1502), (-636,1502), (-636,1542), (-616,1542), (-616,1577), (-76,1577), (-76,1542), (-56,1542), (-56,1502), (-76,1502), (-76,1162), (-56,1162), (-56,1142), (-76,1142), (-76,1108), (-616,1108), (-616,1142)
FamilyInstance Furniture Chair - Office <214409 Office Chair>: 2 extrusion analyser failures
FamilyInstance Furniture Chair - Office <214409 Office Chair> has 1 loop:
  0: (1263,1142), (1263,1162), (1283,1162), (1283,1502), (1263,1502), (1263,1542), (1283,1542), (1283,1577), (1823,1577), (1823,1542), (1843,1542), (1843,1502), (1823,1502), (1823,1162), (1843,1162), (1843,1142), (1823,1142), (1823,1108), (1283,1108), (1283,1142)

I have not really checked the validity of these loops yet.

The chairs have arcs in them, so maybe they have to be as complex as they appear.

The desk should actually be just one single simple rectangle, so maybe there is a possibility to clean up its loop, e.g. reduce the 12 vertices to just four, e.g. by identifying collinear segments or something.

I'll look at that in more detail anon.

As you can see, this is all very experimental work in progress.

I hope you can get some use out of it anyway, and am excited to see where this will lead me.

Conclusion, Next Steps and Download

It works so far, and I will still have hope of using this for my final project implementation.

The next step is to test the validity of the loops I retrieve. As said, the end goal is:

• Upload the boundary loop and other data to the cloud.
• Visualise and manipulate the loops in the room layout editor.

Alternatively, I could first implement a visualisation tool in .NET for local use and testing. I have had that on my list for a long time anyway.

Anyway, here is GetFurnitureLoops.zip containing the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

New Revit Add-ins

Before closing, here are some new Revit add-ins pointed out by developers that have been active here on the blog:

Israel Rodriguez of icubY released his mYbox add-in providing an easy way to integrate families that are on our portal directly inside Revit, AutoCAD and SketchUp, and includes a WPF client using the Revit API to instantiate the families (video). The content is mainly in Brazilian Portuguese.

Fernando Malard of ofcdesk points out his ofctools, providing advanced maintenance commands to optimise and streamline work, e.g. creating, editing or deleting large numbers of elements.

Failure Rollback

I am in full blast preparing and updating material for the Revit API training in Munich starting the day after tomorrow, as well as the upcoming AEC DevCamp conference and another event that I have not even mentioned here yet:

Revit 2013 API Webcast

We will be holding a webcast on the Revit 2013 API on May 17, Ascension Day (register). A list of all the ADN DevTech training opportunities is provided by the Training Course Schedule, entering "Revit API" as the course topic. I'll write something about the webcast topics anon.

Another important piece of news from the ADN team is the launch of a new series of blogs:

ADN DevBlogs

The Autodesk Developer Network ADN team started the launch of a series of new blogs, marking a significant shift from material that's only available to ADN members, like technical solutions known as DevNotes on the ADN extranet, to creating material that's publicly available to everyone. The first two are up and running now:

• AutoCAD DevBlog
• Infrastructure Modeling DevBlog

More ADN DevBlogs for AEC, Manufacturing and Media & Entertainment will coming soon. For more information, please refer to Stephen Preston's welcome post.

Back to the nuts and bolts of the Revit API, here is a case brought up and eventually solved by Mario Guttman of Perkins+Will:

Roll Back Failure Suppressing all Messages, both Warnings and Errors

Question: I am trying to implement a failure handler that will silently respond to all warnings. I am happy to roll back the transaction or delete the elements but I can't seem to get rid of the dialogue box with failures other than warnings.

Answer: I figured it out.

In case anyone is interested, I needed an additional statement in the FailureHandler class:

  return FailureProcessingResult
    .ProceedWithRollBack;

I also needed another statement with the transaction start:

  failureHandlingOptions
    .SetClearAfterRollback( true );

Here is a more complete description and solution:

I'm running a program that creates a lot of new Revit elements. The process may fail in the middle for some reason. I don't want the user to have to respond to a dialogue each time; I just want the program to keep going with the next element.

Specifically, if it is a warning, I want to ignore it, and if it is any other kind of error, I want to cancel creating that element and continue with the next one.

I do want to record the errors so I can inform the user at the end about what problems were encountered.

I looked at your posting on the Failure API about how to handle failure messages, and also the Revit 2012 API Developer Guide and sample code, but didn't quite find what I was looking for.

I finally figured it out and thought you might like to share this:

To begin with, you need to create a FailureHandler class; mine looks like this:

public class FailureHandler : IFailuresPreprocessor
{
  public string ErrorMessage { set; get; }
  public string ErrorSeverity { set; get; }
 
  public FailureHandler()
  {
    ErrorMessage = "";
    ErrorSeverity = "";
  }
 
  public FailureProcessingResult PreprocessFailures( 
    FailuresAccessor failuresAccessor )
  {
    IList<FailureMessageAccessor> failureMessages 
      = failuresAccessor.GetFailureMessages();
 
    foreach( FailureMessageAccessor 
      failureMessageAccessor in failureMessages )
    {
      // We're just deleting all of the warning level 
      // failures and rolling back any others
 
      FailureDefinitionId id = failureMessageAccessor
        .GetFailureDefinitionId();
 
      try
      {
        ErrorMessage = failureMessageAccessor
          .GetDescriptionText();
      }
      catch
      {
        ErrorMessage = "Unknown Error";
      }
 
      try
      {
        FailureSeverity failureSeverity 
          = failureMessageAccessor.GetSeverity();
 
        ErrorSeverity = failureSeverity.ToString();
 
        if( failureSeverity == FailureSeverity.Warning )
        {
          failuresAccessor.DeleteWarning( 
            failureMessageAccessor );
        }
        else
        {
          return FailureProcessingResult
            .ProceedWithRollBack;
        }
      }
      catch 
      {
      }
    }
    return FailureProcessingResult.Continue;
  }
}

Then, in the body of the main program you need something like:

  Transaction transaction = new Transaction( doc );
 
  FailureHandlingOptions failureHandlingOptions 
    = transaction.GetFailureHandlingOptions();
 
  FailureHandler failureHandler 
    = new FailureHandler();
 
  failureHandlingOptions.SetFailuresPreprocessor( 
    failureHandler );
 
  failureHandlingOptions.SetClearAfterRollback( 
    true );
 
  transaction.SetFailureHandlingOptions( 
    failureHandlingOptions );
 
  transaction.Start( "Transaction Name" );
 
  // Do something here that causes the error
 
  transaction.Commit();
 
  // The following is just illustrative. 
  // In reality we would collect the errors 
  // to show later.
 
  if( failureHandler.ErrorMessage != "" )
  {
    System.Windows.Forms.MessageBox.Show( 
      failureHandler.ErrorSeverity + " || "
      + failureHandler.ErrorMessage );
  }

Many thanks to Mario for all his research and friendly sharing!

Determine Revit Demo Mode

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

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

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

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

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

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

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

Here is the test method I created:

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

This is the external command Execute mainline code:

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

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

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

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

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

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

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

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

The Performance Adviser API

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

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

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

Accessing Performance Adviser Rules

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

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

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

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

Executing a Performance Adviser Rule

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

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

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

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

Defining a Custom Rule

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

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

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

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

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

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

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

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

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

Many thanks to Saikat for this helpful overview!

Lock the Model, e.g. Prevent Deletion

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

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

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

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

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

So here is the first query that came up:

Lock Down Part of the Model

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

How can I use the API to lock these elements?

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

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

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

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

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

Prevent Deletion of Elements

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Entry Points to Point Clouds in Revit

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

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

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

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

Failure API Take Two

Before I get into today's topic, let me lament a bit about my Wednesday morning.

Travel Woes

I am flying to Las Vegas today in order to have time for last-minute AU preparations and acclimatise properly there. For reasons unknown to me, my travel agent (who shall remain unnamed here in public) booked me a flight leaving at seven in the morning from Switzerland to London, and a continuation from London to Las Vegas with an eight hour wait in between. I have a brother in London, so we arranged to meet, making the wait quite a tolerable affair.

Be that as it may, I tried to check in online to my British Airways flight yesterday morning. The system asked me to enter all my data, which took ten or fifteen minutes the first time around, then went ahead and processed my entry for a while, only to return with an error message saying something went wrong, and please to try later. So I did. Three times, in fact, with a couple of hours in between each attempt, to no avail. Rather frustrating, of course, since I had to re-enter all my data for each attempt. Snafu...

This morning at the airport, I checked in, everything seemed in order, but there was a problem in the very last step, printing the boarding pass. It turned out to be the US ESTA. Since i visited the US in June and the ESTA is valid for two years, I assumed that would not be a problem. I updated my passport in the meantime, though, and now I apparently need a new ESTA. Snafu...

They asked me to go to an Internet point next door and reapply for the new ESTA, which I did. The machine accepted coins only; I bought ten minutes of time, filled in the form, everything complete, and reached the validation step just before the ten minutes were up. The machine would not accept my next coin. Result: start again from scratch. Snafu...

The second time around I was much faster, completed the form in five minutes, and was told by the system that I could either pay immediately or within seven days' time. I was in deep stress by now, afraid of missing my flight, so I thought "ok, I'll do it when I arrive, within seven days", and went back to check in. Same problem. Apparently, payment is required within seven days, but also before departure. And the latter was not mentioned. By now, of course, the flight was closed. Snafu...

The next step in the list of bungles is the fact that my unnamed travel agent had booked me on this early flight at seven in the morning, with the continuation three in the afternoon. I wonder why they did that? Anyway, it turns out there is another flight at lunch time that serves just as well, and I am now rebooked for that. And successfully checked in as well, I am pleased to say.

BA was kind enough to let me enter the lounge, which provides Internet access, so I can went my frustration here. Thank you for that, at least.

Summary:

• The British Airways online check-in system should have told me what the problem was.
• I should have thought of checking my ESTA validity.
• The Internet machine should have accepted my second coin.
• The ESTA processing form should have said payment is required before departure.
• The travel agent should have booked the later flight; really, I wonder why they did not?
• Thank God they didn't!

Anyway, I think I can leave that topic now, to return to the Revit API. I already gave a brief introduction to the Revit 2011 Failure API and the ErrorHandling SDK Sample which demonstrates its use.

By the way, maybe the story above just illustrates my real-world failure API taking control of the snafu?

One of the most common uses of this API is to disable undesired warning and error messages. Previously, one way to achieve this was to use an older and simpler approach based on the DialogBoxShowing event. The Failure API provides a much more powerful and complete solution, as we showed in the discussions on editing elements inside groups and suppressing an unwanted dialogue.

Now Joe Ye of Autodesk Beijing wrote the following more extensive introduction to the Failure API, including several interesting examples:

Failure Posting and Handling API

Revit posts failure messages which may report either a warning or an error when there are issues in the model. For example, when two walls partially overlap, Revit displays the following warning message:

Revit 2011 exposes the Failure API for posting and handling these kinds of failures. Failure posting APIs can be used to define and register new custom failures. Custom failures can be posted in your own plug-ins. Failure handling APIs can delete or resolve Revit failures when an operation on the model has been submitted. You can do something to the model during the handling process. If failures are handled by the failure handling API, users might not see the warning or error dialogs at all as if everything goes well. In fact, these failures are handled by your application.

Failure Posting

The failure posting API is easy to use. A new failure definition can be registered in the OnStartup method of an external application, and then the failure severity and resolution type can be set. Here is the code showing the registration of a warning. Once custom failings have been registered, they can be posted in your program. Here is a code fragment to register a custom failure:

public Result OnStartup( UIControlledApplication a )
{
  // Create failure definition Ids
 
  m_idWarning = new FailureDefinitionId( new Guid( 
    "0C3F66B5-3E26-4d24-A228-7A8358C76D39" ) );
 
  // Create failure definition and add resolution
 
  m_fdWarning 
    = FailureDefinition.CreateFailureDefinition( 
      m_idWarning, FailureSeverity.Warning, 
      "I am the warning." );
 
  m_fdWarning.AddResolutionType( 
    FailureResolutionType.MoveElements, 
    "MoveElements", typeof( DeleteElements ) );
 
  return Result.Succeeded;
}

The Document.PostFailure method is used to notify the document of a problem.

Here is a code fragment to post a custom failure:

  transaction.Start();
 
  FailureMessage fm 
    = new FailureMessage( m_idWarning );
 
  m_doc.PostFailure( fm );
 
  transaction.Commit();

Failures will be validated and possibly resolved at the end of the transaction.

Failure Handling

Normally posted failures are processed by Revit's standard failure resolution UI at the end of transaction. The user is presented information and options in the UI to deal with the failures. Besides, if operations on the document require some special treatment for certain errors (or even all possible errors), you can customize automatic failure resolution.

Revit may detect failures at the end of any transaction. When it does so, it starts to handle the failures in repeated cycles. Each cycle of failure processing includes three steps:

• Failure pre-processing (IFailuresProcessor)
• Failure processing event (FailureProcessing event)
• Final processing (IFailureProcessor)

These steps are called one by one in a cycle. Each of these three steps can control what happens and whether to continue to the next step by returning different FailureProcessingResults. Corresponding with these three steps, there are two interfaces and an event to implement failure handling. If you know the transaction, IFailuresPreprocessor can be used. To handle all possible errors, you can use the FailuresProcessing event. Finally, the IFailuresProcessor interface offers the ability to completely replace the standard failure processing.

Implement IFailuresPreprocessor interface and its method PreprocessFailures to handle failures. Register and define an event handler to handle all failures. Implement IFailureProcessor interface and its ProcessFailures method to implement final failure handling.

In each step, we can delete elements, delete a warning, and resolve or post a failure. All actions that can be taken are wrapped in the FailuresAccessor class.

Handling a Warning

Here is a sample showing how to handle a warning posted by deleting the last instance of a linked Revit model. The following warning message is displayed to the user if no failure handling mechanism has been added:

Revit users can manually click one of the three buttons to respond to the warning and dismiss the dialog. Instead, we will use failure handling APIs to mimic the manual click. First we use an event to handle the warning.

You can define the event handler and register to the FailuresProcessing event in an external command like this:

public class RegisterFailureEvent : IExternalCommand
{
  public Result Execute( 
    ExternalCommandData commandData,
    ref string messages, 
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    Document doc = app.ActiveUIDocument.Document;
 
    app.Application.FailuresProcessing 
      += new EventHandler<FailuresProcessingEventArgs>( 
        OnFailuresProcessing );
 
    return Result.Succeeded;
  }
 
  /// <summary>
  /// Define event handler.
  /// </summary>
  private void OnFailuresProcessing( 
    object sender, 
    FailuresProcessingEventArgs e )
  {
    FailuresAccessor failuresAccessor 
      = e.GetFailuresAccessor();
 
    String transactionName 
      = failuresAccessor.GetTransactionName();
 
    IList<FailureMessageAccessor> fmas 
      = failuresAccessor.GetFailureMessages();
 
    if( fmas.Count == 0 )
    {
      // FailureProcessingResult.Continue is to let 
      // the failure cycle continue next step.
 
      e.SetProcessingResult( 
        FailureProcessingResult.Continue );
 
      return;
    }
 
    // If manually delete an element, the 
    // transaction name is 'Delete Selection'
    // if the failure is caused by deleting element.
 
    if( transactionName.Equals( "Delete Selection" ) )
    {
      foreach( FailureMessageAccessor fma in fmas )
      {
        // the following line mimics clicking the 
        // 'Remove Link' button to resolve 
        // the failure.             
 
        failuresAccessor.ResolveFailure( fma );
 
        // the following line mimics clicking the 
        // 'Ok' button by just deleting the warning.
 
        //failuresAccessor.DeleteWarning(fma);         
      }
      e.SetProcessingResult( 
        FailureProcessingResult.ProceedWithCommit );
 
      return;
    }
 
    e.SetProcessingResult( FailureProcessingResult.Continue );
  }
}

The code in the event handler above shows two options to handle the warning. The uncommented one resolves the warning, so that both the linked model and the linked file are removed. If you comment the line saying 'failuresAccessor.ResolveFailure(fma)' and uncomment the 'failuresAccessor.DeleteWarning(fma)' one, the linked model is removed and the linked file remains.

Steps to use the failure handling above:

1. Build the code in a project, and create an add-in manifest file to load it into Revit.
2. Start Revit and create a new document.
3. Run the external command to register the event handler.
4. In the current Revit document, import a Revit model.
5. Delete the linked model using Revit's 'Delete' command.
6. You will see the expected result.

Pre-processing a Warning

Now we will talk about how to pre-process warning. To use the IFailuresPreprocessor interface to handle failures, we need to register the interface derived class to transaction. Then the derived interface class will be triggered when the failure is posted.

[TransactionAttribute( TransactionMode.Manual )]
[RegenerationAttribute( RegenerationOption.Manual )]
public class FailureHandle : IExternalCommand
{
  public Result Execute( 
    ExternalCommandData commandData, 
    ref string messages, 
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    Document doc = app.ActiveUIDocument.Document;
 
    Transaction trans = new Transaction( 
      doc, "DeleteLinkedModel" );
 
    trans.Start();
 
    FailureHandlingOptions options 
      = trans.GetFailureHandlingOptions();
 
    MyPreProcessor preproccessor 
      = new MyPreProcessor();
 
    options.SetFailuresPreprocessor( preproccessor );
    trans.SetFailureHandlingOptions( options );
 
    Selection sel = app.ActiveUIDocument.Selection;
 
    Reference ref1 = sel.PickObject( ObjectType.Element, 
      "Please pick a linked model instance" );
 
    Element elem = ref1.Element;
 
    doc.Delete( elem );
 
    trans.Commit();
 
    return Result.Succeeded;
  }
}
 
/// <summary>
/// Define a failure preprossor to handle failure
/// </summary>
public class MyPreProcessor : IFailuresPreprocessor
{
  FailureProcessingResult 
    IFailuresPreprocessor.PreprocessFailures( 
      FailuresAccessor failuresAccessor )
  {
    String transactionName 
      = failuresAccessor.GetTransactionName();
 
    IList<FailureMessageAccessor> fmas 
      = failuresAccessor.GetFailureMessages();
 
    if( fmas.Count == 0 )
    {
      return FailureProcessingResult.Continue;
    }
 
    // We already know the transaction name.
 
    if( transactionName.Equals( "DeleteLinkedModel" ) )
    {
      foreach( FailureMessageAccessor fma in fmas )
      {
        // ResolveFailure mimics clicking 
        // 'Remove Link' button             .
 
        failuresAccessor.ResolveFailure( fma );
 
        // DeleteWarning mimics clicking 'Ok' button.
        //failuresAccessor.DeleteWarning( fma );         
      }
 
      return FailureProcessingResult
        .ProceedWithCommit;
    }
    return FailureProcessingResult.Continue;
  }
}

Failure pre-processing can only be used for the failures caused by actions in your transaction. In the sample, we delete the linked model by picking it and then delete it in our transaction. The core code to handle the failure is the same as the event method above.

Further Reading

This article is a general introduction to the failure posting and handing mechanism. More resources are provided in the Revit 2011 SDK. The sample project ErrorHandling shows more Failure API functionality. A detailed description of the Failure API is provided in Chapter 26 of the Developer Guide in the Revit 2011 SDK. For a reference to all relevant classes and methods, please refer to the Revit API help file RevitAPI.chm.

Many thanks to Joe for the useful overview and samples!

Suppress Unwanted Dialogue

I am posting this in advance from Pattaya before leaving laptop-less for Cambodia, so that you have a little something for the duration of my absence.

Before I left on vacation, we had several queries on suppressing unwanted dialogues, and we also looked at this issue in some depth discussing editing elements inside groups. Here are some further examples of the questions and solutions we found:

Question: I am importing a DWG containing AutoCAD solids into a Revit document. The DWG imports just fine but we always get a dialogue stating that "Some ACIS objects could not be imported. To import them, use AutoCAD to convert them into polymesh objects and reimport." Oddly, when launching the same process manually in the Revit user interface, we get the same successful end result without any dialogue. Is there a way to suppress the unwanted dialogue?

Answer: As mentioned in the last post, there are several different possible ways to suppress unwanted dialogues in Revit 2011.

1. The old method that was already available in Revit 2010 was to use the DialogBoxShowing event, which can be used to dismiss a dialogue programmatically.
2. The Revit 2011 API also includes a comprehensive failure processing API, which can be do much more than the DialogBoxShowing event.
3. If all else fails and you just want to get rid of the dialogue box by any means, you can also use the Windows API to detect when it is displayed and dismiss it using my dialogue clicker application to suppress it.

Question: I used the following code to suppress a dialogue box that appears when reloading modified families:

void myDialogBoxShowing(
  object sender,
  DialogBoxShowingEventArgs e )
{
  TaskDialogShowingEventArgs e1
    = e as TaskDialogShowingEventArgs;
 
  if( e1 != null )
  {
    if( e1.DialogId.Equals(
      "TaskDialog_Family_Already_Exists" ) )
    {
      e1.OverrideResult(
        ( int ) TaskDialogResult.CommandLink1 ); // 1001
    }
  }
}

How can I suppress this dialogue box that is displayed when I delete a linked RVT file?

Answer: I would suggest using the Failure API to suppress that dialogue.

Response: Thanks you for your quick reply. It works fine and is easier to control.

I still have to figure out how to override with another option instead of the default one, in case of a warning dialogue box with more than one button. In my case, I want to pick "Remove Link" instead of "OK". Here is the code:

public class WarningSwallower 
  : IFailuresPreprocessor
{
  public FailureProcessingResult 
    PreprocessFailures( FailuresAccessor a )
  {
    IList<FailureMessageAccessor> failures 
      = a.GetFailureMessages();
 
    foreach( FailureMessageAccessor f in failures )
    {
      //if (f.GetSeverity().ToString() == "Warning")
      //a.DeleteWarning(f);
 
      FailureDefinitionId id 
        = f.GetFailureDefinitionId();
 
      if( id == BuiltInFailures.LinkFailures
        .DeleteLinkSymbolPrompt )
      {
        // only default option being choosen, 
        // not good enough!
        a.DeleteWarning( f ); 
      }
    }
    return FailureProcessingResult.Continue;
  }
}

Is there a way within the Failure API to suppress the warning and specifying a non-default option?

The closest possibility I see is to set the FailureResolutionType. I tried that, but it does not work.

Answer: Could you please try to use the ResolveFailure method to mimic clicking the 'Remove Link' button? Here is a code snippet showing how to resolve a failure, excerpted from the Revit 2011 SDK ErrorHandling sample:

public FailureProcessingResult ProcessFailures( 
  FailuresAccessor failuresAccessor )
{
  IList<FailureMessageAccessor> fmas 
    = failuresAccessor.GetFailureMessages();
 
  if( fmas.Count == 0 )
  {
    return FailureProcessingResult.Continue;
  }
 
  String transactionName 
    = failuresAccessor.GetTransactionName();
 
  if( transactionName.Equals( 
    "Error_FailuresProcessor" ) )
  {
    foreach( FailureMessageAccessor fma in fmas )
    {
      FailureDefinitionId id 
        = fma.GetFailureDefinitionId();
 
      if( id == Command.m_idError )
      {
        failuresAccessor.ResolveFailure( fma );
      }
    }
    return FailureProcessingResult
      .ProceedWithCommit;
  }
  else
  {
    return FailureProcessingResult.Continue;
  }
}

Response: I just tested using the ResolveFailure method, and it still seems not to be working, i.e. the dialogue box is still showing up using this code:

public FailureProcessingResult PreprocessFailures( 
  FailuresAccessor a )
{
  IList<FailureMessageAccessor> failures 
    = a.GetFailureMessages();
 
  foreach( FailureMessageAccessor f in failures )
  {
    FailureDefinitionId id 
      = f.GetFailureDefinitionId();
 
    if( id == BuiltInFailures.LinkFailures
      .DeleteLinkSymbolPrompt )
    {
      // only default option being choosen, 
      // not good enough!
      //a.DeleteWarning(f); 
 
      // cannot suppress dialogue box
      a.ResolveFailure( f ); 
    }
  }
  return FailureProcessingResult.Continue;
}

DeleteWarning is working, the only problem is that it only uses the default OK option. Certainly there must be a way to specify another option when deleting a warning?

Answer: Please try to use a class derived from IFailureProcessor, and implement its ResolveFailure method appropriately.

If all else fails, a workaround would be to delete the remaining RVT model link via the API after you dismiss the warning using the default option.

Correction: Aleksey Moiseyev very friendlily pointed out that the ResolveFailure method shown above is still not working, i.e. the dialogue box is still showing up using the code shown.

The method should be returning the FailureProcessingResult ProceedWithCommit, not Continue. The latter allows the error dialog to appear as usual, whereas the former suppresses it.

Thank you very much, Aleksey, for pointing this out, and sorry for the erroneous original post!