Revit API 2012: Create Custom Performance Advisor Rule (IPerformanceAdviserRule)

Revit API 2012 provides a new Performance Advisor Rule API with which we can access to all the existing native Revit peformance advisor rules, execuate any of them, and create our own ones when necessary and hook them up into the system.

In this article, let us how to create a new performance advisor rule, wall too short monitor, and hook it up into the performance advisor system. Here we go.

#region Namespaces

using System;
using System.Text;
using System.Linq;
using System.Xml;
using System.Reflection;
using System.ComponentModel;
using System.Collections;
using System.Collections.Generic;
using System.Windows;
using System.Windows.Media.Imaging;
using System.Windows.Forms;
using System.IO;

using Autodesk.Revit.ApplicationServices;
using Autodesk.Revit.Attributes;

using Autodesk.Revit.DB;
using Autodesk.Revit.DB.Events;
using Autodesk.Revit.DB.Architecture;
using Autodesk.Revit.DB.Structure;
using Autodesk.Revit.DB.Mechanical;
using Autodesk.Revit.DB.Electrical;
using Autodesk.Revit.DB.Plumbing;

using Autodesk.Revit.UI;
using Autodesk.Revit.UI.Selection;
using Autodesk.Revit.UI.Events;

using Autodesk.Revit.Collections;
using Autodesk.Revit.Exceptions;
using Autodesk.Revit.Utility;

using RvtApplication = Autodesk.Revit.ApplicationServices.Application;
using RvtDocument = Autodesk.Revit.DB.Document;

#endregion

namespace RevitAddinCS1
{
    public class WallTooShortMonitor : IPerformanceAdviserRule
    {
        private List<ElementId> mShortWallIds;

        public static PerformanceAdviserRuleId RuleId = new PerformanceAdviserRuleId(new Guid("71B923D4-17A6-4BE4-861A-3A26146EF3F0"));
        public static FailureDefinitionId FailureDefId = new FailureDefinitionId(new Guid("E8C577B9-17A6-4924-B7F1-150FC2D7CF59"));

        public WallTooShortMonitor()
        {
            mShortWallIds = new List<ElementId>();
            FailureDefinition.CreateFailureDefinition(FailureDefId, FailureSeverity.Warning, "Some walls are too short (less than one foot).");
        }

        public void InitCheck(RvtDocument document)
        {
            mShortWallIds.Clear();
        }

        public void ExecuteElementCheck(RvtDocument document, Element element)
        {
            if (element is Wall)
            {
                Parameter p = (element as Wall).get_Parameter(BuiltInParameter.CURVE_ELEM_LENGTH);
                if (p.AsDouble() < 1.0)
                {
                    mShortWallIds.Add(element.Id);
                }
            }
        }

        public void FinalizeCheck(RvtDocument document)
        {
            if (mShortWallIds != null && mShortWallIds.Count > 0)
            {
                FailureMessage fm = new FailureMessage(FailureDefId);
                fm.SetFailingElements(mShortWallIds);
                PerformanceAdviser.GetPerformanceAdviser().PostWarning(fm);
            }
        }

        public bool WillCheckElements()
        {
            return true;
        }

        public ElementFilter GetElementFilter(RvtDocument document)
        {
            return new ElementClassFilter(typeof(Wall));
        }
       
        public string GetDescription()
        {
            return "Wall Too Short (less than one foot)";
        }

        public string GetName()
        {
            return "WallTooShortMonitor";
        }
    }
}

public Result OnStartup(UIControlledApplication uiApp)
{
    try
    {
        PerformanceAdviser.GetPerformanceAdviser().AddRule(WallTooShortMonitor.RuleId, new WallTooShortMonitor());

        return Result.Succeeded;
    }
    catch (Exception ex)
    {
        MessageBox.Show( ex.ToString() );
        return Result.Failed;
    }
}

public Result OnShutdown(UIControlledApplication uiApp)
{
    try
    {
        PerformanceAdviser.GetPerformanceAdviser().DeleteRule(WallTooShortMonitor.RuleId);

        return Result.Succeeded;
    }
    catch (Exception ex)
    {
        MessageBox.Show(ex.ToString());
        return Result.Failed;
    }
}

Some highlights will be more helpful, I believe.

• The custom performance advisor rule (PerformanceAdviserRule) needs to be derived from the IPerformanceAdviserRule interface.
• Some methods need to be implemented. They are InitCheck(), ExecuteElementCheck(), FinalizeCheck(), WillCheckElements(), GetElementFilter(),GetDescription(), GetName().
• The InitCheck() is to initialize the rule or check.
• The ExecuteElementCheck() is to execute the rule check and caches the problematic element for late processing.
• The FinalizeCheck() is to post failure messages to deal with the problematic elements.
• The WillCheckElements() is to indicate whether elements will be involved in the rule checking.
• The GetElementFilter() is to tell the performance advisor system what element filter that the custom performance advisor rule (PerformanceAdviserRule) applies.
• The GetDescription() is to assign a description for the custom performance advisor rule (PerformanceAdviserRule).
• The GetName() is to give a name for the custom performance advisor rule (PerformanceAdviserRule).
• An element list instead of a single element had better be create to hold possible problematic elements since they may have many rather than single. The element list is generally cleared up in the InitCheck(), populated in the ExecuteElementCheck() and posted to the FailureMessage system in the FinalizeCheck()
• A public static member PerformanceAdviserRuleId is created for convenience.
• A public static member FailureDefinitionId is also created for convenience.
• A FailureDefinition is created from the FailureDefinitionId using the static method FailureDefinition.CreateFailureDefinition() when the custom performance advisor rule is constructed. It is not necessary to cache it into any local variables.
• The FailureDefinition.CreateFailureDefinition() static method serves both to create the FailureDefinition and to hook it up into the failure definition system. Naming the method as CreateAndRegisterFailureDefinition() is apparently better.
• The FailureDefinition.CreateFailureDefinition() call for the specific FailureDefinitionId can be anywhere in the application startup implementation.
• However, if it is called outside there, e.g in the InitCheck() of the advisor rule itself, an exception will come up saying “Autodesk.Revit.Exceptions.ExternalApplicationException: FailureDefinitionRegistry is already locked. Creation of FailureDefinitions is allowed only during application startup.”
• The PerformanceAdviser.GetPerformanceAdviser().AddRule() call is to hook up the custom rule into the system when the application starts up.
• The PerformanceAdviser.GetPerformanceAdviser().AddRule() call is to hook up the custom rule into the system when the application starts up.
• The PerformanceAdviser.GetPerformanceAdviser().DeleteRule() call is to unregister the custom rule when the application shuts down.

That is it for today. We will demonstrate how to run the custom performance advisor rule and how it behaves romorrow.

Revit Addin Wizard (RevitAddinWizard) provides a Performance Advisor Rule Creator to help implement custom performance advisor rules automatically and quickly. RevitAddinWizard can be downloaded from the Download link at the bottom of the blog index page.