Request

Response

    Working with design instancing

    Design instancing lets you define a piece of geometry and model hierarchy once, then place multiple instances of it throughout your model without duplicating the underlying data. This is the same concept as a block in AutoCAD, a family type in Revit, or a reusable sub-assembly or part in a manufacturing tool.

    Why design instancing exists

    Most authoring tools already give designers this pattern natively: define a door once, place it 40 times, and edit the definition once to update every placement. Without a matching concept on the exchange side, a connector that syncs each placement as independent geometry loses that relationship — the exchange ends up 40 times larger than necessary, and there’s no way for a consuming application to tell that the 40 doors share a definition.

    IElementDataModel exposes design instancing as a first-class part of the data model. You promote one element’s geometry and hierarchy into a reusable design, then wire other elements to that design instead of giving them their own geometry. The exchange stores the geometry once; every instance carries only a reference to it.

    Create a design reference

    You never author a design in the abstract. You build the first real occurrence, give it geometry, and promote it. GetOrCreateDesignRef turns that occurrence’s content into a definition the rest of the model can share. The element you promote isn’t scaffolding — it stays in the model as the first instance.

    Pass the element that already carries geometry, a display name, and a stable sourceId from your authoring application. That id is how you refer back to the design later, including from parts of your connector that run independently of the code that created it.

    // The first real door. It carries the geometry that becomes the design.
    var door1 = elementDataModel.AddElement("door-001", "Door-001");
    var doorGeometry = ElementDataModel.CreateFileGeometry(@"C:\designs\standard-door.stp", GeometryFormat.Step);
    elementDataModel.SetElementGeometry(door1, new List<IElementGeometry> { doorGeometry });
    
    // Promote it into a reusable design, keyed by a stable source id you control.
    var doorDesign = elementDataModel.GetOrCreateDesignRef(door1, "StandardDoor", "door-standard-900mm");
    

    GetOrCreateDesignRef is idempotent: call it again later with the same sourceId — for example, from a different part of your connector, or on a second pass over the model — and it returns the existing design instead of throwing or creating a duplicate. The element and name arguments are ignored on that second call. This removes the need to maintain your own “have I created this design yet?” lookup across your connector.

    Instantiate a design

    Use InstantiateDesignBySourceId to wire an existing design into another element by its stable source id:

    var door2 = elementDataModel.AddElement("door-002", "Door-002");
    elementDataModel.InstantiateDesignBySourceId("door-standard-900mm", door2);
    
    var door3 = elementDataModel.AddElement("door-003", "Door-003");
    elementDataModel.InstantiateDesignBySourceId("door-standard-900mm", door3);
    

    InstantiateDesignBySourceId throws InvalidOperationException if no design with that source id exists yet — call GetOrCreateDesignRef first. It’s idempotent per element: calling it again for an element that’s already wired to that design is a no-op rather than an error, so you don’t need to track which elements you’ve already instantiated in a given pass.

    Position and orient each instance independently through the element’s own Transformation, set when you call AddElement. Matrix4d has no factory methods, so write the 4x4 out in row-major order with the offset in the last column:

    var door4 = elementDataModel.AddElement(
        "door-004",
        "Door-004",
        transformation: new Transformation
        {
            // Row-major M11..M44. M14, M24, and M34 hold the translation.
            Matrix = new Matrix4d(
                1, 0, 0, 10,
                0, 1, 0, 0,
                0, 0, 1, 0,
                0, 0, 0, 1)
        });
    elementDataModel.InstantiateDesignBySourceId("door-standard-900mm", door4);
    
    Show More

    Query designs and instances

    GetDesignRefs enumerates every design reference defined in the model:

    foreach (var design in elementDataModel.GetDesignRefs())
    {
        Console.WriteLine($"{design.Name} ({design.SourceId})");
    }
    

    To find every element that instantiates a specific design, use GetDesignInstancesBySourceId or GetDesignInstancesByName:

    var instances = elementDataModel.GetDesignInstancesBySourceId("door-standard-900mm");
    foreach (var element in instances)
    {
        Console.WriteLine($"Instance: {element.Name}");
    }
    

    Note: Source ids are unique by construction; design names aren’t guaranteed to be. Prefer GetDesignInstancesBySourceId when you need a reliable lookup.

    On any element, the read-only Design property returns a design object whether or not the element carries a design, so a null check on Design itself tells you nothing. Use IDesign.IsDesignReference as the reliable check — it returns true only for an authored, reusable design reference:

    if (door2.Design.IsDesignReference == true)
    {
        Console.WriteLine($"{door2.Name} instantiates design '{door2.Design.Name}'");
    }
    

    Caution: Test IsDesignReference before you read any other member. Reading Name or SourceId on an element that carries no design throws NullReferenceException. IsDesignReference is the only member that handles that case, returning null when it cannot determine the answer — so compare against true rather than treating the value as a plain bool.

    Nested designs

    A design can contain occurrences of another design — the same block-within-a-block pattern as an AutoCAD block containing another block, or a Revit family that nests a shared sub-component.

    Because a design is only ever a promoted occurrence, you build a four-legged chair the way you’d build it by hand: place the first leg, promote it into a Leg design, then place three more legs as occurrences of that design. Once the chair is complete, promote the whole chair.

    public void BuildChairs(IElementDataModel elementDataModel)
    {
        // Chair 1 — the first real chair. It carries the seat geometry; the legs go inside it.
        var chair = elementDataModel.AddElement(
            "chair-001", "Chair 1", transformation: Translation(0, 0, 0));
    
        elementDataModel.SetElementGeometry(chair, new List<IElementGeometry>
        {
            ElementDataModel.CreateFileGeometry(@"C:\designs\seat.stp", GeometryFormat.Step)
        });
    
        // Leg 1 — the first real leg, placed inside Chair 1. Promoting it defines the Leg design.
        var leg1 = elementDataModel.AddElement(
            "chair-leg-1", "Leg 1", parent: chair, transformation: Translation(0, 0, 0));
    
        elementDataModel.SetElementGeometry(leg1, new List<IElementGeometry>
        {
            ElementDataModel.CreateFileGeometry(@"C:\designs\leg.stp", GeometryFormat.Step)
        });
    
        elementDataModel.GetOrCreateDesignRef(leg1, "Leg", "leg-tapered");
    
        // Legs 2 to 4 — three more occurrences of the same design, each at its own position.
        // Each occurrence's transform is relative to the Chair design that contains it.
        var leg2 = elementDataModel.AddElement(
            "chair-leg-2", "Leg 2", parent: chair, transformation: Translation(0.4, 0, 0));
        elementDataModel.InstantiateDesignBySourceId("leg-tapered", leg2);
    
        var leg3 = elementDataModel.AddElement(
            "chair-leg-3", "Leg 3", parent: chair, transformation: Translation(0, 0.4, 0));
        elementDataModel.InstantiateDesignBySourceId("leg-tapered", leg3);
    
        var leg4 = elementDataModel.AddElement(
            "chair-leg-4", "Leg 4", parent: chair, transformation: Translation(0.4, 0.4, 0));
        elementDataModel.InstantiateDesignBySourceId("leg-tapered", leg4);
    
        // Chair 1 is complete: a seat plus four legs. Promoting it turns that whole
        // assembly into the Chair design, nested Leg occurrences included.
        elementDataModel.GetOrCreateDesignRef(chair, "Chair", "chair-standard");
    
        // Chairs 2 and 3 — two more occurrences of the Chair design.
        var chair2 = elementDataModel.AddElement(
            "chair-002", "Chair 2", transformation: Translation(1.5, 0, 0));
        elementDataModel.InstantiateDesignBySourceId("chair-standard", chair2);
    
        var chair3 = elementDataModel.AddElement(
            "chair-003", "Chair 3", transformation: Translation(3.0, 0, 0));
        elementDataModel.InstantiateDesignBySourceId("chair-standard", chair3);
    }
    
    /// <summary>Builds a pure translation. Matrix4d has no factory methods, so the 4x4 is
    /// written out: row-major, with the offset in the last column (M14, M24, M34).</summary>
    private static Transformation Translation(double x, double y, double z) =>
        new Transformation
        {
            Matrix = new Matrix4d(1, 0, 0, x,  0, 1, 0, y,  0, 0, 1, z,  0, 0, 0, 1)
        };
    
    Show More

    Because the four Leg occurrences live inside the shared Chair design rather than inside any individual chair, all three chairs resolve to the same underlying leg geometry. Rendering three chairs does not triple the leg data, and editing the leg design once updates every chair.

    Load designs and instances into a host application

    Reading an exchange that uses design instancing is a task in its own right, with rules that don’t come up while authoring: which element list to walk, how to rebuild the sharing using your host application’s definitions and instances, and where each transform belongs. Load design instances into a host application covers it, using the chair model above.

    Use cases

    • Repeated building components — window, door, and column families that appear dozens or hundreds of times across a building model, each placed at a different transformation.
    • Manufacturing sub-assemblies — a bolt, bracket, or fastener design referenced by every assembly that uses it, so a change to the part definition propagates everywhere it’s used.
    • Nested components — a hinge or handle design nested inside a door design, itself instantiated many times, without duplicating either level of geometry.

    See also