Revit Extensions Authoring

Authoring a Revit Extension

Nice3point.Revit.Extensions is a public NuGet library of fluent extension methods over the Revit API. Each member wraps a raw Revit API call behind a type-safe, chainable, discoverable surface and adds ergonomics, never new behavior. This skill covers adding one extension the way the existing surface is built; it depends on the Revit API packages (Nice3point.Revit.Api.*).

When to use

• Adding a new extension method or property over a core Revit type, a *Utils static class, or a *Manager.
• Deciding the receiver type and whether an ElementId sibling overload is needed.
• Naming, attributes, XML docs, namespace placement, and #if version gating for a new member.

When not to use

• Changing, renaming, or deprecating an existing public member — that must preserve the API contract; use revit-extensions-backward-compat.
• Writing coverage for the new member — custom logic is exercised by the TUnit test project, and API wrappers and UI extensions are not tested.

Workflow

Step 1: Place the file and declare the flat namespace

Group one Revit type's extensions per <Type>Extensions.cs. Choose the folder by what the type is:

• core Autodesk.Revit.DB type (Element, Document, Category, Parameter) → project root.
• Revit *Utils static class → UtilsExtensions/<UtilsClass>Extensions.cs.
• Revit *Manager type → ManagersExtensions/<Manager>Extensions.cs.
• Ribbon / UI Framework helper → UIFrameworkExtensions/.
• non-public helper (reflection accessors, format utilities) → Internal/, never public.

Declare the flat file-scoped namespace namespace Nice3point.Revit.Extensions;, or namespace Nice3point.Revit.Extensions.UI; for types from RevitAPIUI. Namespaces with nesting like Autodesk.Revit.DB.Structure.StructuralSections declare base on the same policy Nice3point.Revit.Extensions.Structure.StructuralSections. Add // ReSharper disable once CheckNamespace above the namespace whenever the declared namespace does not match the file's folder — every subfolder file needs it; a root file already in the flat namespace does not.

using JetBrains.Annotations;

// ReSharper disable once CheckNamespace
namespace Nice3point.Revit.Extensions;

/// <summary>
///     Represent extension methods for the <see cref="Autodesk.Revit.DB.JoinGeometryUtils"/> class.
/// </summary>
[PublicAPI]
public static class JoinGeometryUtilsExtensions

Mark the public class [PublicAPI].

Step 2: Author members inside an extension(Type) block

Open one extension(Type receiver) block per receiver and put the receiver's XML doc on the block. Wrap the Revit API directly — call the underlying API and return its result; never reimplement the operation. Write full block bodies for methods; an expression-bodied property is fine for a read-only value.

/// <param name="element">The source element.</param>
extension(Element element)
{
    /// <summary>Creates clean joins between two elements that share a common face</summary>
    public Element JoinGeometry(Element secondElement)
    {
        JoinGeometryUtils.JoinGeometry(element.Document, element, secondElement);
        return element;
    }

    /// <summary>Determines whether two elements are joined</summary>
    /// <returns>True if the two elements are joined</returns>
    [Pure]
    public bool AreElementsJoined(Element secondElement)
    {
        return JoinGeometryUtils.AreElementsJoined(element.Document, element, secondElement);
    }
}

A static member of the wrapped API becomes a public static member in the block:

extension(FamilySymbol familySymbol)
{
    [Pure]
    public static ICollection<ElementId> GetProfileSymbols(Document document, ProfileFamilyUsage profileFamilyUsage, bool oneCurveLoopOnly)
    {
        return FamilyUtils.GetProfileSymbols(document, profileFamilyUsage, oneCurveLoopOnly);
    }
}

Step 3: Return the source object from mutation methods

A method that mutates and would otherwise return void returns the receiver; calls chain. Keep a meaningful return value when the API produces one (for example Copy returns the new ElementId collection).

extension(Element element)
{
    public Element Move(double deltaX = 0d, double deltaY = 0d, double deltaZ = 0d)
    {
        ElementTransformUtils.MoveElement(element.Document, element.Id, new XYZ(deltaX, deltaY, deltaZ));
        return element;
    }

    public Element Rotate(Line axis, double angle)
    {
        ElementTransformUtils.RotateElement(element.Document, element.Id, axis, angle);
        return element;
    }
}

Step 4: Add the ElementId sibling overload

When the method reaches the API through element.Document and element.Id, add a sibling on ElementId that takes an explicit Document. Keep the bare name when it stays unambiguous on ElementId; give it a descriptive, disambiguated name when the bare name would be too generic.

extension(Element element)
{
    public bool CanBeDeleted => DocumentValidation.CanDeleteElement(element.Document, element.Id);
}

extension(ElementId elementId)
{
    [Pure]
    public bool CanBeDeleted(Document document)
    {
        return DocumentValidation.CanDeleteElement(document, elementId);
    }
}

A generic name gets qualified: GlobalParameter.MoveUpOrder() has the sibling elementId.MoveGlobalParameterUpOrder(document), not elementId.MoveUpOrder(document).