Google Cloud Firestore grain persistence

Install the Microsoft.Orleans.Persistence.Firestore package and configure a named provider with AddFirestoreGrainStorage:

siloBuilder.AddFirestoreGrainStorage(
    "profiles",
    options =>
    {
        options.ProjectId = projectId;
        options.RootCollectionName = "Orleans";
        options.EmulatorHost = emulatorHost;
        options.DeleteStateOnClear = true;
    });

The ProjectId identifies the Google Cloud project, RootCollectionName selects the provider’s top-level collection, and EmulatorHost redirects requests to a local emulator. For database creation, authentication, IAM, clustering, reminders, and emulator setup, see Google Cloud Firestore providers.

Clear behavior

DeleteStateOnClear controls how ClearStateAsync handles a record:

• false, the default, keeps an empty document and advances its ETag.
• true deletes the document.

Both modes use optimistic concurrency. A stale write or clear fails with InconsistentStateException instead of overwriting a newer record.

Serialization and record size

The provider serializes each state record into one Firestore document. The serialized payload, document name, and metadata must fit within the Firestore document-size limit. Test production-shaped state after serialization rather than relying only on in-memory object size.

Set GrainStorageSerializer to customize the stored representation. Changing serializers doesn’t rewrite existing documents, so the replacement must read the previous representation or be accompanied by a migration.

Sample

The Google Cloud Firestore sample configures persistence together with Firestore clustering, reminders, and the grain directory. Run it once to write state and run it again to observe the persisted counter.