Orleans Journaling overview

Orleans Journaling is an experimental persistence model that records mutations to durable values and collections in an ordered per-grain journal. When a grain activates, Orleans replays that journal to reconstruct its in-memory state. A single write can persist changes from multiple durable states owned by the grain.

Programming model

Application code uses IDurableStateManager to declare named durable states during construction or synchronous activation setup and acknowledge their writes. The standard manager enrolls itself in the lifecycle during grain-bound construction, before resolution returns, so declared state recovers before application activation and requests. This works with an ordinary Grain, an application-owned grain base, or a reusable activation-scoped feature. DurableGrain remains a convenience base exposing the same application manager and a protected write helper. Keyed injection and programmatic access resolve the same named state object.

Orleans currently provides:

IDurableValue<T>
IDurableDictionary<T, U>
IDurableList<T>
IDurableQueue<T>
IDurableSet<T>
IDurableTaskCompletionSource<T>
IPersistentState<T> backed by the grain’s journal

Declare states with GetOrAddState or the typed DurableStateManagerExtensions helpers before initialization. After recovery, calls resolve existing states and application methods can use their contents. A request to create a missing state after initialization fails immediately.

Mutations update the activation’s in-memory state and add encoded operations to its pending journal buffer. Await WriteStateAsync at the application durability point. The returned task completes after the storage provider acknowledges the append or snapshot replacement.

Prepare fallible work in operation-local data and stage mutations once they are safe to commit. Interleaved calls share the pending journal. A failed journal operation fences the manager and requests grain deactivation; a fresh activation reconstructs the durable outcome before processing resumes.

Each named state has a stable stream identity within the grain journal. Keep those names stable across deployments so recovery can bind stored operations to the intended state.

Journal lifecycle

Resolving the grain-scoped manager enrolls it in the lifecycle. Constructor injection and shared setup register states before lifecycle startup.
During the setup-state stage, Orleans reads the journal in order and replays each state stream before application activation and requests.
Grain code synchronously mutates durable values and collections during a grain turn.
WriteStateAsync gathers pending operations for the manager and submits one atomic journal append or replacement to storage.
The storage provider can request compaction when its configured size or row threshold is reached. The next write creates a snapshot of the current durable states and atomically replaces the journal.
A later activation replays the latest snapshot and subsequent operations to restore the same durable state.

Registering a provider makes the services available; activations which resolve the manager trigger per-grain journal I/O. For the detailed guarantees and caller-owned manager lifetimes, see Runtime behavior and consistency.

Journal formats

JSON Lines is the default write format. Each line contains a state stream identifier and one encoded operation. Configure source-generated JsonSerializerContext metadata for journaled key, value, and state types when using trimming or Native AOT.

The earlier Orleans binary format remains registered so deployments can read existing data. Providers store the journal format key with the journal. When the configured write format differs from the stored format, recovery uses the stored reader and the next write snapshots the journal in the configured format.

See Configure Journaling for format and migration guidance.

Journaling and Event Sourcing

Orleans offers two separate journal-oriented programming models:

Model	Application state model	Persistence coordination
Orleans Journaling	Mutable durable values and collections composed with a grain or feature through `IDurableStateManager`	One per-grain journal managed by `Microsoft.Orleans.Journaling`
Orleans Event Sourcing	Application-defined events applied to `JournaledGrain<TState, TEvent>`	Log-consistency providers confirm, persist, and synchronize events

Choose Journaling when evaluating operation-based persistence for built-in mutable state structures. Choose Event Sourcing when domain events, event history, and the supported log-consistency programming model are application requirements.