Revit Extensible Storage

Revit Extensible Storage

Extensible Storage keeps add-in data inside the .rvt file. A Schema describes the shape, an Entity holds the values, and any Element carries one entity per schema. The layout below mirrors EF Core: a schema definition plays the part of an entity configuration, a context plays the part of a DbContext, and a plain class carries the values.

Nice3point.Revit.Extensions wraps the entity read and write pair as SaveEntity/LoadEntity on Element, and the schema filter as WithExtensibleStorage on the collector.

When to use

• Storing add-in data that has no parameter equivalent, per document or per element.
• Adding a field to a schema that already shipped, or reading data written by an earlier version.
• Finding the elements that carry the add-in data.

When not to use

• The user must see or edit the value in the Revit UI — model it as a project or shared parameter.
• The payload runs past a few kB per element or a few MB per file — keep it in an external database and store only the key.

Workflow

Step 1: Lay out the subject

The data class, the schema definition, and the context change in one edit.

ProjectData/
  ProjectData.cs // the values
  ProjectDataConfiguration.cs // the schema definition
  ProjectDataContext.cs // access to the stored values

Step 2: Describe the data as a plain class

namespace RevitAddIn.ProjectData;

public sealed class ProjectData
{
    public string Number { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;
    public double GrossArea { get; set; }
}

Step 3: Build the schema once per session

Schema.Lookup returns the schema already registered in the session, and Finish throws once that identity exists.

using Autodesk.Revit.DB.ExtensibleStorage;

namespace RevitAddIn.ProjectData;

public static class ProjectDataConfiguration
{
    public const string Number = "Number";
    public const string Name = "Name";
    public const string GrossArea = "GrossArea";

    public static readonly Guid Identity = new("0E73AF93-E7F3-42E6-9BA5-AFC1CA23D42B");

    public static Schema Create()
    {
        var schema = Schema.Lookup(Identity);
        if (schema is not null) return schema;

        var builder = new SchemaBuilder(Identity);
        builder.SetSchemaName("AcmeProjectData");
        builder.SetDocumentation("Project data owned by the Acme add-in");
        builder.SetVendorId("ACME");
        builder.SetReadAccessLevel(AccessLevel.Public);
        builder.SetWriteAccessLevel(AccessLevel.Vendor);

        builder.AddSimpleField(Number, typeof(string));
        builder.AddSimpleField(Name, typeof(string));
        builder.AddSimpleField(GrossArea, typeof(double)).SetSpec(SpecTypeId.Area);

        return builder.Finish();
    }
}

A double, float, XYZ, or UV field declares its spec with SetSpec, and every read and write of it passes a compatible unit. Schema and field names must read as C++ identifiers — ASCII letters, digits after the first character, and underscore. Build the schema when the data is first touched, not during add-in startup. Registering a schema at startup slows document open and save.

Step 4: Wrap the carrier in a context

A document-wide record belongs on a DataStorage element, an invisible element that exists to hold entities. One DataStorage element carries one subject. In a workshared model, editing a subject borrows only the storage element of that subject. Data that describes a single element belongs on that element instead — take it as a constructor argument and skip the lookup.

Reads need no transaction, writes do. The caller owns the transaction; the context opens none of its own.

using Autodesk.Revit.DB.ExtensibleStorage;

namespace RevitAddIn.ProjectData;

public sealed class ProjectDataContext
{
    private const string StorageName = "Acme Project Data";

    private readonly Document _document;
    private readonly Schema _schema;

    public ProjectDataContext(Document document)
    {
        _document = document;
        _schema = ProjectDataConfiguration.Create();
    }

    public ProjectData Load()
    {
        var storage = FindStorage();
        if (storage is null) return new ProjectData();

        return new ProjectData
        {
            Number = storage.LoadEntity<string>(_schema, ProjectDataConfiguration.Number) ?? string.Empty,
            Name = storage.LoadEntity<string>(_schema, ProjectDataConfiguration.Name) ?? string.Empty,
            GrossArea = storage.LoadEntity<double>(_schema, ProjectDataConfiguration.GrossArea, UnitTypeId.SquareMeters)
        };
    }

    public void Save(ProjectData data)
    {
        var storage = FindStorage();
        if (storage is null)
        {
            storage = DataStorage.Create(_document);
            storage.Name = StorageName;
        }

        storage.SaveEntity(_schema, data.Number, ProjectDataConfiguration.Number);
        storage.SaveEntity(_schema, data.Name, ProjectDataConfiguration.Name);
        storage.SaveEntity(_schema, data.GrossArea, ProjectDataConfiguration.GrossArea, UnitTypeId.SquareMeters);
    }

    private DataStorage? FindStorage()
    {
        return (DataStorage?) _document.CollectElements()
            .OfClass<DataStorage>()
            .WithExtensibleStorage(_schema.GUID)
            .FirstOrDefault();
    }
}

SaveEntity returns false when the schema has no such field, and LoadEntity returns the default when the field is missing or nothing was written yet.

The context is bound to a Document. Create one per document, and keep it out of a static field and out of a singleton registration.

Step 5: Drive it from the caller

using var transaction = new Transaction(document, "Save project data");
transaction.Start();

var context = new ProjectDataContext(document);
context.Save(data);

transaction.Commit();

Step 6: Query the elements that carry the data

WithExtensibleStorage applies an ExtensibleStorageFilter, a quick filter that rejects elements before they expand into memory.

var annotated = document.CollectElements()
    .WithExtensibleStorage(ProjectDataConfiguration.Identity)
    .ToElements();

Step 7: Remove the data when the feature is uninstalled

element.DeleteEntity(schema); // returns false when the element held nothing
document.EraseSchemaAndAllEntities(schema); // every entity in the document

Both need an open transaction and write access to the schema. The erased schema stays registered in memory for the rest of the session.

Step 8: Verify the round trip

Save, close the document, reopen it, and read the values back. Data that survives only inside one session was never written to the file.

Validation

• The data class, the schema definition, and the context of one subject sit together.
• The schema is looked up before it is built, and the build happens on first use.
• Every double, float, XYZ, and UV field declares a spec, and every read and write of one passes a compatible unit.
• Writes run inside a transaction the caller owns; the context adds no transaction of its own.
• The context is created per document and held by no static field.
• Elements carrying data are found with WithExtensibleStorage, not by loading everything and probing GetEntity.
• Values read back after a document reopen match what was written.

Common Pitfalls

References

• references/schema-fields.md — Load when: the schema needs a numeric, array, map, or nested-entity field, or a value comes back with the wrong type or unit.
• references/schema-lifecycle.md — Load when: evolving a shipped schema, resolving a GUID conflict, choosing an access level, or storing data in a workshared model.