Orleans scenarios and use cases

Orleans supports applications with many independently addressable entities whose state and work partition by identity. A grain owns the behavior and state for one entity, and the runtime manages its activation, placement, routing, and turn-based execution.

Choose grains according to identity, state ownership, concurrency, and call patterns. Combine them with databases, queues, stream processors, and compute services according to each workload.

Signals that Orleans is a strong fit

Consider Orleans when several of these statements describe the application:

• Domain entities have stable identities, such as a player, device, account, order, room, tenant, or session.
• Each entity owns state or coordinates work over time.
• Requests for one entity benefit from serialized, turn-based execution.
• The workload contains many entities and can distribute traffic across their keys.
• Entities need timers, reminders, streams, persistence, or calls to other entities.
• Callers use a stable logical identity while the runtime resolves the entity’s current host.
• The application is already a distributed .NET service, or is expected to grow into one.

Scalability comes from grain boundaries, key distribution, call patterns, storage, and external dependencies. Partition popular entities across multiple keys to distribute their work.

Common scenarios

AI agents and conversational sessions

An AI agent session is a natural grain identity. A session grain can own conversation state, model and tool configuration, pending work, and coordination with other agents or services. Orleans activates sessions on demand, removes idle activations, routes each request to the current activation, and processes turns one at a time by default. This provides lifecycle management and serializes concurrent session updates.

Model inference and tool calls are typically asynchronous external operations. A grain can await them efficiently, use response streaming to return generated tokens or progress during one live invocation, and use timers, reminders, or durable jobs to schedule later work. A stream provider with retention and replay capabilities, or durable storage, can retain output for reconnection and later consumption.

After membership converges following a silo failure, a later request can reactivate the session on a healthy silo, and grain persistence restores state written to durable storage. Explicit durability points, idempotent tool calls, bounded retries, and reconciliation preserve application-level outcomes across failures.

Fraud protection, risk, and low-latency decisioning

Fraud protection, financial services, actuarial systems, and regulated online gaming often make decisions from rapidly changing state. A grain can maintain low-latency soft state: reconstructible in-memory working data derived from durable records, event streams, market feeds, or model outputs. Turn-based execution keeps each entity’s updates and decisions ordered.

Account, payment instrument, merchant, policy, portfolio, market, and gaming-event grains can track recent activity, risk signals, limits, exposure, and current odds. Grain calls coordinate decisions across related entities, while streams distribute changing inputs and outputs. Durable stores and event logs retain the authoritative history used to rebuild working state and support audit.

The same pattern supports real-time pricing, auctions, inventory allocation, recommendations, and other decisions which combine an entity’s current context with incoming events. Parallel compute and data platforms can produce models or large analytical results which grains apply during online decisioning.

The Stocks sample demonstrates per-symbol temporary caching and periodic updates. The Bank Account transactions sample demonstrates coordinated state changes across accounts.

Internet of Things and digital twins

Internet of Things (IoT) devices, vehicles, sensors, industrial assets, robots, buildings, and edge gateways have stable identities and evolving state. A grain per asset can maintain last-known state, apply commands in order, manage configuration, evaluate local rules, and coordinate periodic or scheduled work. Grain identity lets callers address each asset directly while Orleans resolves its current host, and persistence restores explicitly written state after reactivation.

Grains can consume selected telemetry events and own the stateful behavior of each asset. Brokers, time-series stores, and stream-processing systems provide high-volume ingestion, long-term retention, fleet-wide analytics, and model training for the surrounding telemetry pipeline.

The GPS Tracker sample models IoT devices as grains and integrates Orleans with ASP.NET Core SignalR.

Monitoring, resource governance, and job orchestration

Servers, services, containers, clusters, tenants, quotas, jobs, and hardware resources map naturally to grains. A resource grain can combine heartbeats, health signals, desired configuration, capacity, reservations, and remediation state. Timers detect stale health reports, reminders trigger recurring checks, and durable jobs schedule one-time follow-up actions.

Job grains can own submission state, dependencies, retries, progress, and completion. Resource grains can own hardware availability and allocation. Partitioned scheduler grains match jobs to eligible resources, and external workers execute assigned work and report status through grain calls or streams. Stable grain identities let operators and automation address the same job or resource throughout its lifecycle.

This model supports fleet health monitoring, automated remediation, quota enforcement, workload placement, batch and build farms, and orchestration across specialized hardware. Heterogeneous silos and placement filtering also direct Orleans grain workloads to hosts with specific capabilities.

Multiplayer and online games

Players, game sessions, rooms, parties, matches, tournaments, and leaderboards have natural identities and typically own mutable state. Grains can serialize operations for each entity, coordinate interactions through grain calls, and notify connected clients through observers or streams.

Use Orleans for authoritative game and social state, matchmaking coordination, presence, progression, and session lifecycle. Real-time simulation, rendering, and other CPU-intensive loops can run in specialized compute services while grains coordinate durable and interactive state.

See the Adventure game explanation and the maintained Presence Service sample.

Commerce, reservations, and customer services

Shopping carts, orders, accounts, reservations, subscriptions, and customer profiles often have clear ownership boundaries and rules which must hold for one key. A grain can keep those rules with the state they protect, persist changes deliberately, and use reminders or durable jobs for later work.

Per-user grains can maintain preferences, session context, entitlements, notification state, quotas, and recent interactions for responsive personalization. Recommendation and search services can provide ranked results which the grain combines with current user and business state.

Orleans supports distributed ACID transactions for operations spanning supported transactional state across multiple entities. Idempotent commands, explicit coordination, and reconciliation support workflows whose consistency model permits independent state transitions.

See the Shopping Cart sample and Orleans transactions.

Collaboration, social applications, and live sessions

Rooms, channels, documents, users, social profiles, and sessions can be independently addressed and can retain behavior between client requests. Grain observers fit transient callbacks to connected clients, while Orleans streams fit multicast event flows and subscriptions whose guarantees depend on the selected provider.

Brokers and storage systems provide durable message retention, competing consumers, large broadcast fan-out, and analytics over full event histories. Grains apply per-entity state and behavior to selected events and coordinate live interactions.

The Chat Room sample combines a grain per channel with Orleans streams. The Chirper sample models a social network with user grains, persistence, and observers.

Per-entity orchestration

Long-lived processes such as a bot conversation, user workflow, subscription, or scheduled campaign can map to grains when each instance has an identity and progresses independently. Grain state records progress, grain calls express coordination, and timers, reminders, or durable jobs trigger later work.

Orleans expresses programmatic, per-entity orchestration in grain code. Workflow engines provide visual process authoring, human approval queues, and queryable audit histories, and can integrate with grains which own domain state.

Choose the architecture by workload

Match the primary workload to the architecture designed for its execution and state model:

• Stateless request processing or straightforward CRUD. An ASP.NET Core service backed by a database provides request handling, coordination, and durability.
• A few large CPU-bound or data-parallel jobs. Parallel compute, batch, or job-processing tools distribute substantial computation. Grain turns remain short and asynchronous.
• Bulk analytics, ETL, or declarative stream processing. Databases and data-flow engines are designed for scans, joins, windows, and shared transformations across large data sets.
• One globally coordinated resource or a permanently hot key. Domain partitioning distributes the work, while systems specialized for single-resource coordination manage a centralized access pattern.
• Shared-memory or hard real-time processing. A local concurrent runtime provides shared-memory access, and a hard real-time platform provides deterministic scheduling and bounded latency.
• A work queue with competing consumers. A competing-consumer queue assigns each item to one worker. Orleans streams deliver each item to every subscription on a logical stream.

Orleans commonly owns the stateful entity subsystem alongside HTTP APIs, databases, caches, brokers, compute workers, and analytics systems.

Evaluate the model against the workload

Before committing to a design, identify candidate grain keys and test the busiest paths:

1. Define which entity owns each invariant and operation.
2. Estimate the number of active keys and the traffic distribution between them.
3. Look for hot keys, global coordinators, chatty call chains, and large messages.
4. Decide what state must survive failure and when writes must complete.
5. Define retry, idempotency, timeout, and recovery behavior for each external operation.
6. Load test a representative key distribution and the production provider types.

For the programming model’s benefits and tradeoffs, see Why Orleans. For design and operational guidance, see Orleans best practices and the production-readiness checklist.