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 makes Newtonsoft storage enforce the type allow-list, changes RPC telemetry keys, and requires custom grain-context activators to apply configurators before construction. Prefer generated/allowed types over permissive JSON and update affected tests, dashboards, and activators together. 10.3.1 services analyzer contract identities and documents placement hints.

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.

Workflow

1. Inspect the solution, Orleans version, hosting topology, grain interfaces, providers, and tests.
2. Identify domain identities and invariants. Prefer many independent, bounded entities over global coordinator grains.
3. Choose state, communication, and time-based work from the tables below.
4. Keep default non-reentrant scheduling and placement until a measured requirement justifies a change.
5. Configure providers independently and test the failure model the design depends on.

Choose the State Owner

Grain State Versus a Database

Use grain state for bounded current state and per-identity invariants. Use a database/read model for joins, search, reporting, bulk work, history, shared access, or an external system of record. When using both, define one authority per field and recovery rules.

Never query or mutate another grain's persistence record behind the grain, or expose provider storage as the public query model merely because it uses SQL/Cosmos/Redis. Before using transactions, try one bounded grain owner; use a saga for external effects or long waits. Read references/persistence-api.md for the full boundary.

Choose Communication

Prefer a direct call unless decoupling is a requirement. Do not use a stream merely to avoid calling a known target. Do not use broadcast channels for commands, money movement, audit events, or anything that must be replayed. Do not use observers as a durable event bus.

When adding retries, make side effects idempotent. Default Orleans calls are at-most-once only while neither the runtime nor application retries. Retried calls can arrive more than once, and Orleans does not durably deduplicate them for the application.

Choose Time-Based and Background Work

Timer, Reminder, or Durable Job

Timer means “while this activation lives”; reminder means “wake this grain on a durable recurring schedule”; Durable Job means “invoke this target once around a future time, at least once.” Reminders persist definitions but miss ticks while the cluster is down. Durable Job handlers must be idempotent, and current alpha.1 packages are an explicit architecture risk.

BackgroundService means one loop per host replica, not one loop per cluster. Use a well-known grain or external lease/leader for one logical collector.

Read references/scheduling-and-services.md before implementing timers, reminders, Durable Jobs, hosted/startup tasks, silo lifecycle participants, or grain services.

Choose Execution and Scaling

Turn-based execution is single-threaded, not magically race-free. Reentrancy allows another turn to run while the first awaits; any state observed before the await can be stale afterward. Avoid blocking calls, .Result, .Wait(), thread-affine work, and unbounded CPU loops on the grain scheduler.

Hosting and Provider Boundaries

Keep concerns separate: clustering discovers silos; the grain directory locates activations; grain/reminder/transaction/job storage persist different records; stream providers carry events while PubSubStore tracks subscriptions; serialization defines wire and persistence compatibility.

In-memory clustering, storage, reminders, streams, Durable Jobs, and journaling are development/test choices unless loss is explicitly acceptable. Configure production providers, credentials, TLS/networking, server GC, graceful shutdown, and health/readiness for the deployment target. In Aspire, declare backing resources in AppHost and register the keyed clients expected by Orleans providers.

Contract and API Rules

• Keep grain interfaces coarse-grained and asynchronous: Task, Task<T>, ValueTask<T>, or supported IAsyncEnumerable<T>.
• Cancellation is cooperative, not proof that work did not finish.
• Use [GenerateSerializer] and stable [Id(N)] values on messages/state. Use [Alias] for durable type identity and [Immutable] only for genuinely immutable values.
• Never reuse removed field IDs; write state explicitly and propagate storage failures.
• Bound external calls and use idempotency plus a saga/outbox when state writes and external effects must be reconciled.

Validate the Chosen Guarantees

• Grain boundaries follow business identity and avoid hot global coordinators.
• State is bounded, and the grain-state-versus-database choice is explicit.
• Every time primitive matches activation, recurrence, durability, and delivery requirements.
• Durable Job handlers/retried commands are idempotent; reminders tolerate missed ticks.
• Broadcast channels, observers, and one-way calls carry only loss-tolerant signals.
• Provider-backed tests prove delivery, ordering, replay, and failover claims.
• Reentrancy tests cover state across await; transactions use transactional storage, [Reentrant], and PerformRead/PerformUpdate.
• Hosted services are reviewed for per-replica duplication.
• Production uses persistent providers, multi-silo tests, and observability wherever the guarantee depends on them.

Load References

Open only the references needed for the selected primitive:

• references/official-docs-index.md — official documentation map
• references/scheduling-and-services.md — scheduled/background/runtime work
• references/grains.md and references/grain-api.md — grain design and APIs
• references/persistence-api.md — state, databases, Journaling, event sourcing, transactions
• references/streaming-api.md — streams, broadcast, observers, response streams
• references/serialization-api.md — serialization and versioning
• references/hosting.md and references/configuration-api.md — hosting, providers, operations
• references/implementation.md and references/testing-patterns.md — runtime and tests
• references/patterns.md, references/anti-patterns.md, and references/examples.md — patterns and samples

Prefer Learn for stable APIs. For Durable Jobs and Orleans.Journaling, use version-tagged package READMEs/public API because Learn does not yet cover them fully.