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
IElementDataModeland theIElementthat 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:
- Stamp an identifier you control. Pass a
sourceIdwhen you create the geometry, typically the identifier the host application already uses for that body. - Look up the SDK’s identifier. Call
GetGeometryMetaDataByIdwith yoursourceId. It returns metadata, including theUniqueId, without downloading any geometry data. - Apply the change. Pass that
UniqueIdtoUpdateElementGeometryorDeleteElementGeometry, 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
| Method | What it does | Returns |
|---|---|---|
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.
| Property | Who sets it | What 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
}
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
nullforelementtargets 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}");
}
}
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);
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);
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:
| Geometry | After first sync | After UpdateElementGeometry | After 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.
GetGeometryMetaDataByIdreturns an empty sequence rather than throwing, andUpdateElementGeometryreturnsfalsefor 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
SourceIdisn’t required to be unique, so decide up front what your connector does when the lookup returns more than one geometry. - Prefer resolving
UniqueIdfromSourceIdwhen starting a new session. AUniqueIdremains 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 do | Use |
|---|---|
| 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.
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.
| Condition | Result |
|---|---|
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
UniqueIdis the match key.SourceIdis for lookup only. Matching on an identifier you control isn’t supported, because connector identifiers aren’t guaranteed to be unique.UniqueIdis 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 ownSourceId.- Not-found is not an error. Update and delete return
false; the metadata lookup returns an empty sequence. IElementGeometry.Idis gone.UniqueIdreplaces it, and code that readsIdno 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 anyIdvalue kept from an earlier release as meaningless rather than as something to convert.GetGeometryMetaDataByIddoesn’t download. It walks the in-memory model, so it’s safe to call in a loop.- No migration required. Existing code that calls
SetElementGeometrycontinues 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
- Creating geometry — build the geometry you pass to these methods
- Update an exchange container — sync your changes to a new revision
- Design instancing — how designs come to be shared, and why that affects targeted updates
- Geometry parameters — attach parameters to the geometry you create
- Migration guide — required only if your connector implements
IElementGeometryitself - Changelog — the full list of members added with this feature