Request

Response

    Resolve an element’s render style

    When a connector loads an exchange, it needs to decide what color to apply to each element. As of SDK v8.0.0, an element can carry a render style at two levels: on the geometry, and directly on the element instance. This guide shows you how to read both and resolve the effective style with a single consistent rule.

    What you’ll learn

    • Where instance-level and geometry-level render styles come from
    • How to read IElement.RenderStyle (new in v8.0.0)
    • How to apply the recommended precedence rule
    • How to handle elements with no render style at all

    Before you begin

    • You’re on SDK v8.0.0 or later. Earlier versions do not expose IElement.RenderStyle.
    • You’re on the read/consumer side of an exchange — for example, inside an element loop after WaitForElementDataModelAsync or GetElementGeometriesByElementsAsync.

    Why two levels?

    Authoring applications attach color in different places:

    SourceWhere the style livesExample
    Geometry-level IElementGeometry.RenderStyle A STEP file with a default material
    Instance-level IElement.RenderStyle (new) Inventor, when a per-instance body color is applied

    Without instance-level access, a per-instance override applied in the authoring tool was silently dropped, and the loaded exchange rendered the geometry color instead. IElement.RenderStyle makes that override visible.

    Resolve the effective render style

    Apply this rule: instance override first, then geometry.

    RenderStyle GetEffectiveRenderStyle(IElement element, IElementGeometry geometry)
    {
        return element.RenderStyle ?? geometry?.RenderStyle;
    }
    

    In a consumer loop:

    foreach (var element in elements)
    {
        var geometries = await dataModel.GetElementGeometriesByElementsAsync(new[] { element });
        var geometry   = geometries.FirstOrDefault();
    
        var style = element.RenderStyle ?? geometry?.RenderStyle;
        if (style != null)
        {
            ApplyColor(target, style.RGBA, style.Transparency);
        }
        else
        {
            ApplyDefaultColor(target);
        }
    }
    
    Show More

    Important: Most elements will not have an instance-level override. IElement.RenderStyle returns null when no override is set — always null-check.

    Read render style properties

    A non-null RenderStyle exposes the name, color, and transparency:

    var style = element.RenderStyle;
    if (style != null)
    {
        string name         = style.Name;
        RGBA   rgba         = style.RGBA;          // R, G, B, A (0–255)
        double transparency = style.Transparency;  // 0.0 = opaque, 1.0 = transparent
    }
    

    For details on color and transparency semantics, see Controlling Geometry Opacity.

    When to use which level

    Connector behaviorWhat to do
    Renders elements with their own color or material Apply the precedence rule above.
    Reads only IElementGeometry.RenderStyle today Add the element.RenderStyle ?? fallback in the same place.
    Doesn't render colors or materials No action — you can ignore the new property.

    Important points

    • Read-only. There is no setter. Producers continue to attach render styles the same way they do today.
    • Returns null when not set. Always null-check before using.
    • Independent of geometry-level style. The two values are not auto-merged. The connector decides precedence; the recommendation is instance over geometry.
    • Cached on first access. The first read resolves the underlying schema graph; subsequent reads are cheap.
    • No migration required. Existing code that reads only IElementGeometry.RenderStyle continues to work unchanged.

    Troubleshooting

    Loaded element shows the wrong color

    Cause: The connector reads only IElementGeometry.RenderStyle, and the authoring tool applied an instance-level override.

    Solution: Add the precedence rule shown above so the instance override wins:

    var style = element.RenderStyle ?? geometry?.RenderStyle;
    

    Every BRep body loads as opaque white

    Cause: The producing connector attached a STEP or IFC file whose exporter discarded the original color and transparency. The style translated from the file wins over the render style the connector supplied, so the incorrect file style is what reaches consumers. This is a producer-side problem — no change on the read side fixes it.

    Solution: In the producing connector, set AllowUserRenderStyleOverride on GeometryConfiguration so the connector-supplied style replaces the translated one, then republish the exchange.

    IElement.RenderStyle doesn’t compile

    Cause: The project references an SDK earlier than v8.0.0.

    Solution: Update the Autodesk.DataExchange package to v8.0.0 or later.

    Same element looks different in two viewers

    Cause: One viewer applies the instance-level override; the other reads only geometry-level color.

    Solution: Apply the precedence rule consistently in every place the connector reads a render style.

    Next steps