By Naveen Kumar
Extensible Storage (ES) is one of the most powerful features in the Revit API. It lets developers attach custom structured data to elements in ways normal parameters can’t. But how does this custom data behave inside a real-world worksharing environment? What about performance, conflicts with other add-ins, or version upgrades? And can this data make its way into the Autodesk Viewer?
This guide breaks down all those questions in a simple, practical way.
How Does Extensible Storage Behave When Synchronizing with the Central Model? Is It Similar to Normal Parameters?
Extensible Storage lets you attach custom data, called Entities, directly to Revit elements.
When you add, change, or delete an Entity, Revit attempts to borrow the element for editing. If you don’t have permission, you’ll receive an error asking you to request access.
When you sync with the central model, all your changes to Entities are pushed to the central model.
Other users who reload the latest changes will receive these updated Entities.
In short, working with Entities behaves just like modifying any other element parameter or attribute in a worksharing environment.
Best Practices for Extensible Storage Size & Performance
Size Limits – No strict maximum size, but keep data small. Larger data = slower save, sync, and open times.
Performance – Many elements with Extensible Storage can slow down the model.
Data Structure – Avoid storing one huge JSON string in a single field. Instead, use multiple fields, arrays, or maps of primitive types for faster access.
ElementId Fields – You can store ElementIds (single, array, or map). Revit will automatically update them when elements are copied or deleted, but this adds processing overhead.
Keep IDs Reasonable – Too many ElementIds in an entity can cause performance issues. For example, having arrays with thousands of ElementIds per entity can significantly slow the model when Revit parses them.
Avoiding Conflicts with Other Add-ins
Two schemas conflict if they share the same GUID but differ in any of the following:
- Number of fields
- Field definitions
- Schema name
- VendorId
- Application GUID
- Read/Write access levels
Why This Happens?
- Schemas are stored in Revit’s memory, not in the document.
Opening a model with a different definition for the same GUID triggers a conflict. - In Worksharing, syncing or opening the central model in the same session can also cause conflicts.
Common Mistakes:
- Copying sample code but keeping the same GUID while changing the schema definition.
- Changing a schema’s fields but not updating its GUID.
How to Safely Update a Schema?
- Assign a new GUID.
- Add, remove, or change fields as needed.
- Update your read/write logic:
* Read from the old schema first, then the new one.
* Write to the new schema, then delete the old one when appropriate. - Avoid moving data between schemas during events like DocumentOpened or DocumentSaved—this can cause worksharing borrow issues. Revit will automatically borrow elements, leading users to encounter permission errors. Only modify elements exactly when needed.
What Happens During Revit Version Upgrades?
The good news: Extensible Storage survives model upgrades between major Revit versions.
However, keep in mind:
- Schema conflicts can still occur if Revit loads a model whose schema GUID matches one already in memory with a different definition.
- Autodesk does not guarantee that the Extensible Storage API will remain unchanged in future releases. They may expand or improve it.
So: expect general stability, but design your add-in with future changes in mind.
Is Extensible Storage Included in SVF Conversion or Exposed in Parameter APIs?
Short answer: No.
Extensible Storage is not included when converting a Revit file to SVF (the format used by Autodesk Viewer).
Why?
- Extensible Storage is private to your add-in.
- The conversion pipeline does not load add-ins, so it cannot access your schema.
- For security and technical reasons, Autodesk does not allow add-ins to run during conversion.
This means:
- Your ES data will not appear in the Forge Viewer / APS Viewer.
- It’s also not exposed through the standard parameter APIs.
If you rely on this data in the Viewer, you must export it separately (e.g., JSON sidecar file or custom metadata service).
Conclusion
Extensible Storage is a powerful and flexible tool in the Revit API, but it comes with its own set of considerations:
- Behaves like normal element edits in worksharing
- Must be kept small for performance
- Schema GUIDs must be managed carefully to avoid conflicts
- Is generally stable across Revit versions
- Is not included in Autodesk Viewer conversions
Used correctly, it can open up possibilities well beyond standard parameters—just be mindful of how, when, and where you store your data.
Leave a Reply