Request

Response

    Update individual geometry

    Change one geometry on an element without disturbing the others. You can append a geometry, replace one in place, or delete one, and everything else on the element keeps the identity it already had.

    This matters when a host application edits part of an element. Say a wall carries two geometries, a solid body and a trim profile, and the user revises only the body. You want the exchange to record that single change. The older approach, SetElementGeometry, deletes every geometry on the element and recreates the list you pass, so the untouched trim comes back as a new object with a new identifier. Anything downstream that tracked that trim loses the thread, and each sync churns geometry that never actually changed.

    Targeted operations avoid that. The geometry you don’t mention is left exactly as it was.

    What you’ll learn

    • How a geometry is identified, and the difference between the two identifiers
    • How to find a geometry you created earlier
    • How to append, update, and delete a single geometry
    • How to apply several updates or deletions in one call
    • How to put the whole pattern together across two syncs
    • How these operations behave when a design is shared between elements

    Before you begin

    • You’re on the producer side of an exchange, holding an IElementDataModel and the IElement that owns the geometry.
    • You’ve read Creating geometry, because the targeted operations take geometry built by the same factory methods.

    How it works

    Identity is what makes a targeted change possible. Every geometry carries an identifier the SDK generates, and update and delete match on it. Because the SDK assigns that identifier, you don’t know it when you author the geometry, so the workflow has three steps:

    1. Stamp an identifier you control. Pass a sourceId when you create the geometry, typically the identifier the host application already uses for that body.
    2. Look up the SDK’s identifier. Call GetGeometryMetaDataById with your sourceId. It returns metadata, including the UniqueId, without downloading any geometry data.
    3. Apply the change. Pass that UniqueId to UpdateElementGeometry or DeleteElementGeometry, then sync the exchange.

    Appending is simpler and skips the lookup: AddElementGeometry takes new geometry straight from the factories.

    For a worked example of all three steps together, see Example: revise one geometry on a synced element.

    The methods at a glance

    MethodWhat it doesReturns
    GetGeometryMetaDataById Finds geometry by your SourceId and returns its UniqueId, without downloading geometry data Empty sequence when nothing matches
    AddElementGeometry Appends geometry, leaving existing geometry and identifiers untouched —
    UpdateElementGeometry Replaces one geometry in place, keeping its UniqueId false when the identifier isn't found
    DeleteElementGeometry Removes one geometry, leaving the others intact false when the identifier isn't found
    UpdateElementGeometries, DeleteElementGeometries Batch forms of update and delete A per-identifier map of what was applied

    The two identifiers

    Every geometry exposes two identifiers, and they do different jobs.

    PropertyWho sets itWhat it's for
    UniqueId The SDK The match key. Pass it to update and delete. It's stable across load and sync cycles for as long as the geometry exists.
    SourceId Your connector A lookup key you control. Pass it to GetGeometryMetaDataById to find geometry again. It never drives matching and may be empty.

    The distinction matters because you rarely know a UniqueId up front — the SDK generates it. The pattern is to stamp your own SourceId when you create the geometry, then use it later to look up the UniqueId you need.

    Set SourceId through the optional sourceId argument on any of the three geometry factories:

    var geometry = ElementDataModel.CreateFileGeometry(
        filePath: "wall.stp",
        format: GeometryFormat.Step,
        sourceId: "wall-body"
    );
    

    Leave sourceId out and the property is empty. Nothing is written, and update and delete still work, but you have to hold on to the UniqueId yourself.

    Find a geometry

    GetGeometryMetaDataById returns lightweight metadata for every geometry whose SourceId matches. It reads the in-memory model, so it does not download geometry data:

    var matches = dataModel.GetGeometryMetaDataById("wall-body", element);
    
    foreach (var metadata in matches)
    {
        string uniqueId = metadata.UniqueId;   // the key for update and delete
        string sourceId = metadata.SourceId;   // "wall-body"
        string name     = metadata.Name;
        GeometryType type = metadata.Type;     // BRep, Mesh, or Primitive
    }
    
    Show More

    GeometryMetaData is read-only and carries identity, name, and type — never the payload. To get the geometry itself, use GetElementGeometriesAsync.

    The lookup behaves this way:

    • No match returns an empty sequence rather than throwing.
    • Deleted geometry is excluded. You only ever see live geometry.
    • Passing null for element targets model-level geometry instead of a single element’s.
    var modelLevel = dataModel.GetGeometryMetaDataById("site-boundary", element: null);
    

    Reusing one SourceId across several geometries is allowed, and then the lookup returns all of them. The SDK doesn’t guess which one you meant, so keep your source identifiers unique if you want a single result.

    Append a geometry

    AddElementGeometry appends to the element and leaves the existing geometries — and their UniqueId values — untouched:

    var trim = ElementDataModel.CreateFileGeometry(
        filePath: "wall_trim.stp",
        format: GeometryFormat.Step,
        sourceId: "wall-trim"
    );
    
    dataModel.AddElementGeometry(element, new List<IElementGeometry> { trim });
    

    If the element has no geometry yet, the SDK creates the design that holds it. Passing an empty list does nothing at all: no geometry is added, no design is created, and no exception is thrown.

    Pass newly created geometry from a factory. Passing a geometry that already lives in the exchange, such as a handle you read back from GetElementGeometriesAsync, throws ArgumentException, because appending it would duplicate an identifier. Use UpdateElementGeometry when your intent is to replace something that already exists. The whole list is checked before anything is appended, so a bad entry fails without applying part of the batch.

    Update one geometry

    UpdateElementGeometry replaces a single geometry in place, matched by UniqueId. The identifier survives, and the other geometries on the element are left alone:

    var replacement = ElementDataModel.CreateFileGeometry(
        filePath: "wall_revised.stp",
        format: GeometryFormat.Step
    );
    
    bool updated = dataModel.UpdateElementGeometry(element, uniqueId, replacement);
    

    The return value tells you whether a geometry with that UniqueId was found. An unknown identifier returns false and changes nothing — it isn’t an error. To add geometry that isn’t there yet, use AddElementGeometry.

    The replacement doesn’t have to be the same kind of geometry as the original. Replacing a file-based body with a mesh works, and the UniqueId still holds:

    var mesh = ElementDataModel.CreateMeshGeometry(revisedMesh, "Wall Surface");
    
    bool updated = dataModel.UpdateElementGeometry(element, uniqueId, mesh);
    

    Delete one geometry

    DeleteElementGeometry removes a single geometry and leaves the rest intact:

    bool deleted = dataModel.DeleteElementGeometry(element, uniqueId);
    

    As with update, an unknown UniqueId returns false rather than throwing.

    Deleting and then re-adding the same geometry gives you a new UniqueId. The old identifier is not recycled, so any identifier you cached for that geometry is stale after a delete.

    Apply several changes in one call

    The batch forms take a group of identifiers and report what happened to each one. Both return a dictionary keyed by the UniqueId you supplied, where the value tells you whether that geometry was found and changed:

    var replacements = new Dictionary<string, IElementGeometry>
    {
        [wallBodyId] = ElementDataModel.CreateFileGeometry("wall_revised.stp", GeometryFormat.Step),
        [wallTrimId] = ElementDataModel.CreateFileGeometry("trim_revised.stp", GeometryFormat.Step)
    };
    
    IReadOnlyDictionary<string, bool> results = dataModel.UpdateElementGeometries(element, replacements);
    
    foreach (var result in results)
    {
        if (!result.Value)
        {
            logger.Warning($"No geometry found for {result.Key}");
        }
    }
    
    Show More

    Deletion takes a plain collection of identifiers, since there’s no per-key value to supply:

    IReadOnlyDictionary<string, bool> results =
        dataModel.DeleteElementGeometries(element, new[] { wallTrimId, obsoleteId });
    

    Unknown identifiers map to false without throwing, and an empty input is a no-op that returns an empty dictionary. If you pass the same identifier twice to DeleteElementGeometries, it appears once in the result.

    One caution: the batch methods validate each entry as they iterate, not up front. An invalid entry — an empty key, or a null replacement geometry — throws after the entries before it have already been applied. Validate your input before you call, or use the single-geometry methods when you need all-or-nothing behavior.

    Example: revise one geometry on a synced element

    This example follows a wall through two syncs. The wall carries two geometries: a solid body and a trim profile. In the second sync, only the body has changed.

    The connector here assigns one sourceId per geometry per element, so a lookup is expected to return at most one match. The SDK doesn’t enforce that, so the code checks the assumption instead of trusting it.

    First sync — author the geometry with your own identifiers. Give each geometry a sourceId that matches whatever the host application calls it. Without a SourceId, you’ll need to retain the SDK-generated UniqueId yourself.

    var body = ElementDataModel.CreateFileGeometry(
        filePath: bodyFilePath,
        format: GeometryFormat.Step,
        sourceId: "wall-4471-body"
    );
    
    var trim = ElementDataModel.CreateFileGeometry(
        filePath: trimFilePath,
        format: GeometryFormat.Step,
        sourceId: "wall-4471-trim"
    );
    
    dataModel.SetElementGeometry(wall, new List<IElementGeometry> { body, trim });
    
    await client.SyncExchangeDataAsync(exchangeIdentifier, dataModel);
    
    Show More

    Second sync — update only what changed. The host application reports that the body was edited. Look up the geometry by the sourceId you assigned, then replace that one geometry:

    var matches = dataModel.GetGeometryMetaDataById("wall-4471-body", wall).ToList();
    
    if (matches.Count > 1)
    {
        // Several geometries carry this SourceId, so the one-id-per-geometry
        // assumption was violated upstream. Report it rather than picking one.
        logger.Warning($"Expected one geometry for wall-4471-body, found {matches.Count}.");
        return;
    }
    
    var revisedBody = ElementDataModel.CreateFileGeometry(
        revisedBodyPath, GeometryFormat.Step, sourceId: "wall-4471-body");
    
    if (matches.Count == 0)
    {
        // The body isn't on this element yet, so append it instead of updating.
        dataModel.AddElementGeometry(wall, new List<IElementGeometry> { revisedBody });
    }
    else
    {
        bool updated = dataModel.UpdateElementGeometry(wall, matches[0].UniqueId, revisedBody);
        if (!updated)
        {
            logger.Warning($"Geometry {matches[0].UniqueId} was not found on wall 4471.");
        }
    }
    
    await client.SyncExchangeDataAsync(exchangeIdentifier, dataModel);
    
    Show More

    What the two approaches leave behind. The identifiers tell the story. Say the first sync produced geo-a1 for the body and geo-b2 for the trim:

    GeometryAfter first syncAfter UpdateElementGeometryAfter SetElementGeometry
    Body (revised) geo-a1 geo-a1 — same identifier, new data geo-c3 — deleted and recreated
    Trim (untouched) geo-b2 geo-b2 — not touched at all geo-d4 — deleted and recreated

    The targeted call changes exactly what you asked it to. The replace-all call gives both geometries new identifiers, including the trim nobody edited, so anything downstream holding geo-b2 can no longer resolve it and the sync uploads a trim that didn’t change.

    Three details make this pattern work in production:

    • Handle the not-found case. GetGeometryMetaDataById returns an empty sequence rather than throwing, and UpdateElementGeometry returns false for an unknown identifier. Both are ordinary outcomes on a first run, or after someone deleted the geometry, so branch on them instead of assuming a match.
    • Don’t assume a single match. A SourceId isn’t required to be unique, so decide up front what your connector does when the lookup returns more than one geometry.
    • Prefer resolving UniqueId from SourceId when starting a new session. A UniqueId remains stable while the geometry exists, but becomes stale if that geometry is deleted and recreated.

    Choose between replace-all and targeted operations

    What you want to doUse
    Rewrite the complete geometry list for an element SetElementGeometry
    Add geometry without disturbing what's there AddElementGeometry
    Change one geometry and keep its identifier UpdateElementGeometry
    Remove one geometry and keep the others DeleteElementGeometry
    Apply many updates or deletions together UpdateElementGeometries, DeleteElementGeometries

    SetElementGeometry is unchanged and still deletes and recreates. Reach for it when replacing everything is what you actually mean; reach for the targeted methods when you want identifiers to survive.

    Shared designs propagate

    Important: Updating or deleting geometry on an instanced design changes it for every element that references that design, not only the element you passed.

    Geometry lives on a design, and a design can be referenced by more than one element when a connector instances it deliberately. Propagation is what instancing means, so the SDK allows the change rather than blocking it. The call succeeds and reports success.

    The risk is doing this unintentionally. If your connector instances designs to deduplicate repeated geometry — the same window used a hundred times — then a targeted update to one window updates all hundred.

    To change a single instance, give that element its own design first. See Design instancing.

    Argument contract

    Exceptions are reserved for invalid input. A geometry that isn’t there is reported through the return value, not an exception.

    The sourceId rows below apply to the lookup argument on GetGeometryMetaDataById. The sourceId argument on the geometry factories is optional, and omitting it is not an error.

    ConditionResult
    element is null ArgumentNullException
    geometryList is null (append) ArgumentNullException
    newGeometry is null (update) ArgumentNullException
    geometriesByUniqueId or geometryUniqueIds is null ArgumentNullException
    geometryUniqueId is null or empty ArgumentException
    A batch key is null or empty, or a batch replacement geometry is null ArgumentException
    A geometry passed to AddElementGeometry is already in the exchange ArgumentException
    The sourceId passed to GetGeometryMetaDataById is null ArgumentNullException
    The sourceId passed to GetGeometryMetaDataById is empty ArgumentException
    UniqueId not found on the element false, or false for that key in a batch result
    Empty list, dictionary, or collection No-op

    Important points

    • UniqueId is the match key. SourceId is for lookup only. Matching on an identifier you control isn’t supported, because connector identifiers aren’t guaranteed to be unique.
    • UniqueId is stable while the geometry exists. An identifier you capture stays valid across load and sync cycles, so you can hold it and update the geometry later. It becomes stale only if that geometry is deleted, since a re-added geometry gets a new identifier. When you start a new session, prefer resolving the identifier from your own SourceId.
    • Not-found is not an error. Update and delete return false; the metadata lookup returns an empty sequence.
    • IElementGeometry.Id is gone. UniqueId replaces it, and code that reads Id no longer compiles. The old value was a GUID generated in memory on first access, unrelated to the stored geometry and different every session, so treat any Id value kept from an earlier release as meaningless rather than as something to convert.
    • GetGeometryMetaDataById doesn’t download. It walks the in-memory model, so it’s safe to call in a loop.
    • No migration required. Existing code that calls SetElementGeometry continues to work unchanged.

    Troubleshooting

    AddElementGeometry throws ArgumentException

    Cause: The geometry you passed is already in the exchange, usually because it came from GetElementGeometriesAsync rather than a factory method.

    Solution: Build new geometry with a factory to append it, or call UpdateElementGeometry with the existing geometry’s UniqueId to replace it.

    Update or delete returns false

    Cause: No geometry on that element carries the UniqueId you passed. Common reasons are a stale identifier cached from before a delete, an identifier belonging to a different element, or an element that has no geometry yet.

    Solution: Re-read the current identifier with GetGeometryMetaDataById, and confirm you’re passing the element that owns the geometry.

    GetGeometryMetaDataById returns nothing

    Cause: The geometry was created without a sourceId, or it was deleted, or the SourceId doesn’t match what you passed.

    Solution: Confirm that the geometry was created with the sourceId argument. Remember that the lookup returns live geometry only, and that string matching is exact.

    A change appears on elements you didn’t touch

    Cause: The element’s design is instanced, so the geometry is shared with every element referencing it.

    Solution: Give the element its own design before changing its geometry.

    Next steps