orleans

Microsoft Orleans

Start With Purpose

Do not begin with an Orleans API. First state:

1. the business identity that owns the behavior;
2. the invariant and what must survive activation or cluster failure;
3. the required consistency, query shape, acknowledgement, durability, replay, fan-out, and timing.

Then select the smallest Orleans primitive whose guarantees match those requirements. Reject Orleans when the problem is primarily shared-memory computation, a finite batch, relational querying, or global coordination with few independent entities.

Inspect package versions for version-sensitive work. Orleans 10.3.1 ships Microsoft.Orleans.DurableJobs* and Microsoft.Orleans.Journaling* as 10.3.1-alpha.1; treat them as experimental until that status changes.

Orleans 10.3 changes three upgrade boundaries: Newtonsoft storage now enforces the Orleans type allow-list, RPC telemetry keys changed, and custom grain-context activators must apply configurators before construction. Prefer generated/allowed types over global permissive JSON, and update persisted-state tests, dashboards, and custom activators together. The release also adds streaming, checkpoint, journal, transaction, file-storage, and System.Text.Json providers; select them by guarantees. 10.3.1 services analyzer contract identities.

The August 2026 overview highlights the built-in dashboard and stable Redis providers. Keep production telemetry explicit, and select Redis only when its guarantees match the workload.

Mental Model

• A grain is a virtual actor with stable identity, behavior, and optional state, not a process, row, DTO, controller, or background job.
• A grain reference is a location-transparent address. Getting a reference does not create a durable record or prove that an activation exists.
• An activation is an ephemeral in-memory execution instance. Orleans creates, places, moves, deactivates, and recreates it. Never equate activation lifetime with entity lifetime.
• A normal grain has at most one activation in the cluster by default and processes turns one at a time. This makes the grain a natural owner of per-identity invariants.
• A silo hosts activations. Silos form a cluster; external clients or a co-hosted IGrainFactory call grains.
• Calls are asynchronous messages even when they look like C# method calls. Network failure, timeout, serialization, retries, and duplicate side effects still matter.
• A grain can model a digital twin when its identity and behavior map to a real or domain entity; that is a use case, not every grain's definition.
• Orleans gives logical ownership and turn-based execution. It does not make external side effects transactional, turn arbitrary data into a queryable database, or provide exactly-once execution by default.