Microsoft Orleans

Trigger On

building or reviewing .NET code that uses Microsoft.Orleans.*, Grain, IGrainWith*, UseOrleans, UseOrleansClient, IGrainFactory, JournaledGrain, ITransactionalState, or Orleans silo/client builders
testing Orleans code with InProcessTestCluster, Aspire.Hosting.Testing, WebApplicationFactory, or shared AppHost fixtures
modeling high-cardinality stateful entities such as users, carts, devices, rooms, orders, digital twins, sessions, or collaborative documents
choosing between grains, streams, broadcast channels, reminders, stateless workers, persistence providers, placement strategies, transactions, event sourcing, and external client/frontend topologies
deploying or operating Orleans with Redis, Azure Storage, Cosmos DB, ADO.NET, .NET Aspire, Kubernetes, Azure Container Apps, or built-in/dashboard observability
designing grain serialization contracts, versioning grain interfaces, configuring custom placement, or implementing grain call filters and interceptors

Workflow

Decide whether Orleans fits. Use it when the system has many loosely coupled interactive entities that can each stay small and single-threaded. Do not force Orleans onto shared-memory workloads, long batch jobs, or systems dominated by constant global coordination.
Model grain boundaries around business identity. Prefer one grain per user, cart, device, room, order, or other durable entity. Never create unique grains per request — use [StatelessWorker] for stateless fan-out. Grain identity types:
- IGrainWithGuidKey — globally unique entities
- IGrainWithIntegerKey — relational DB integration
- IGrainWithStringKey — flexible string keys
- IGrainWithGuidCompoundKey / IGrainWithIntegerCompoundKey — composite identity with extension string
Design coarse-grained async APIs. All grain interface methods must return Task, Task<T>, or ValueTask<T>. Use IAsyncEnumerable<T> for streaming responses. Avoid .Result, .Wait(), blocking I/O, lock-based coordination. Use Task.WhenAll for parallel cross-grain calls. Apply [ResponseTimeout("00:00:05")] on interface methods when needed.
Choose the right state pattern:
- IPersistentState<TState> with [PersistentState("name", "provider")] for named persistent state (preferred)
- Multiple named states per grain for different storage providers
- JournaledGrain<TState, TEvent> for event-sourced grains
- ITransactionalState<TState> for ACID transactions across grains
- Grain<TState> is legacy — use only when constrained by existing code
Pick the right runtime primitive deliberately:
- Standard grains for stateful request/response logic
- [StatelessWorker] for pure stateless fan-out or compute helpers
- Orleans streams for decoupled event flow and pub/sub with [ImplicitStreamSubscription]
- Broadcast channels for fire-and-forget fan-out with [ImplicitChannelSubscription]
- RegisterGrainTimer for activation-local periodic work (non-durable)
- Reminders via IRemindable for durable low-frequency wakeups
- Observers via IGrainObserver and ObserverManager<T> for one-way push notifications
Configure serialization correctly:
- [GenerateSerializer] on all state and message types
- [Id(N)] on each serialized member for stable identification
- [Alias("name")] for safe type renaming
- [Immutable] to skip copy overhead on immutable types
- Use surrogates (IConverter<TOriginal, TSurrogate>) for types you don't own
Handle reentrancy and scheduling deliberately:
- Default is non-reentrant single-threaded execution (safe but deadlock-prone with circular calls)
- [Reentrant] on grain class for full interleaving
- [AlwaysInterleave] on interface method for specific method interleaving
- [ReadOnly] for concurrent read-only methods
- RequestContext.AllowCallChainReentrancy() for scoped reentrancy
- Native CancellationToken support (last parameter, optional default)
Choose hosting intentionally.
- UseOrleans for silos, UseOrleansClient for separate clients
- Co-hosted client runs in same process (reduced latency, no extra serialization)
- In Aspire, declare Orleans resource in AppHost, wire clustering/storage/reminders there, use .AsClient() for frontend-only consumers
- In Aspire-backed tests, resolve Orleans backing-resource connection strings from the distributed app and feed them into the test host instead of duplicating local settings
- Prefer TokenCredential with DefaultAzureCredential for Azure-backed providers
Configure providers with production realism.
- In-memory storage, reminders, and stream providers are dev/test only
- Persistence: Redis, Azure Table/Blob, Cosmos DB, ADO.NET, DynamoDB
- Reminders: Azure Table, Redis, Cosmos DB, ADO.NET
- Clustering: Azure Table, Redis, Cosmos DB, ADO.NET, Consul, Kubernetes
- Streams: Azure Event Hubs, Azure Queue, Memory (dev only)
Treat placement as an optimization tool, not a default to cargo-cult.
- ResourceOptimizedPlacement is default since 9.2 (CPU, memory, activation count weighted)
- RandomPlacement, PreferLocalPlacement, HashBasedPlacement, ActivationCountBasedPlacement
- SiloRoleBasedPlacement for role-targeted placement
- Custom placement via IPlacementDirector + PlacementStrategy + PlacementAttribute
- Placement filtering (9.0+) for zone-aware and hardware-affinity placement
- Activation repartitioning and rebalancing are experimental
Make the cluster observable.
- Standard Microsoft.Extensions.Logging
- System.Diagnostics.Metrics with meter "Microsoft.Orleans"
- OpenTelemetry export via AddOtlpExporter + AddMeter("Microsoft.Orleans")
- Distributed tracing via AddActivityPropagation() with sources "Microsoft.Orleans.Runtime" and "Microsoft.Orleans.Application"
- Orleans Dashboard for operational visibility (secure with ASP.NET Core auth)
- Health checks for cluster readiness
Test the cluster behavior you actually depend on.

InProcessTestCluster for new tests
Shared Aspire/AppHost fixtures for real HTTP, SignalR, SSE, or UI flows that must exercise the co-hosted Orleans topology
WebApplicationFactory<TEntryPoint> layered over a shared AppHost when tests need Host DI services, IGrainFactory, or direct grain/runtime access while keeping real infrastructure
Multi-silo coverage when placement, reminders, persistence, or failover matters
Benchmark hot grains before claiming the design scales
Use memory providers in test, real providers in integration tests

Architecture

flowchart LR
  A["Distributed requirement"] --> B{"Many independent<br/>interactive entities?"}
  B -->|No| C["Plain service / worker / ASP.NET Core"]
  B -->|Yes| D["Model one grain per business identity"]
  D --> E{"State pattern?"}
  E -->|"Persistent"| F["IPersistentState&lt;T&gt;"]
  E -->|"Event-sourced"| F2["JournaledGrain&lt;S,E&gt;"]
  E -->|"Transactional"| F3["ITransactionalState&lt;T&gt;"]
  E -->|"In-memory only"| G["Activation state"]
  D --> H{"Communication?"}
  H -->|"Pub/sub"| I["Orleans streams"]
  H -->|"Broadcast"| I2["Broadcast channels"]
  H -->|"Push to client"| I3["Observers"]
  H -->|"Request/response"| I4["Direct grain calls"]
  D --> J{"Periodic work?"}
  J -->|"Activation-local"| K["RegisterGrainTimer"]
  J -->|"Durable wakeups"| L["Reminders"]
  D --> M{"Client topology?"}
  M -->|"Separate process"| N["UseOrleansClient / .AsClient()"]
  M -->|"Same process"| O["Co-hosted silo+client"]
  F & F2 & F3 & G & I & I2 & I3 & I4 & K & L & N & O --> P["Serialization → Placement → Observability → Testing → Deploy"]

Deliver

a justified Orleans fit, or a clear rejection when the problem should stay as plain .NET code
grain boundaries, grain identities, and activation behavior aligned to the domain model
concrete choices for clustering, persistence, reminders, streams, placement, transactions, and hosting topology
serialization contracts with [GenerateSerializer], [Id], versioning via [Alias], and immutability annotations
an async-safe grain API surface with bounded state, proper reentrancy, and reduced hot-spot risk
an explicit testing and observability plan for local development and production
a test-harness choice that matches the assertion level: runtime-only, API/SignalR/UI, or direct Host DI/grain access

Validate

Orleans is being used for many loosely coupled entities, not as a generic distributed hammer
grain interfaces are coarse enough to avoid chatty cross-grain traffic
no grain code blocks threads or mixes sync-over-async with runtime calls
state is bounded, version-tolerant, and persisted only through intentional provider-backed writes
all state and message types use [GenerateSerializer] and [Id(N)] correctly
timers are not used where durable reminders are required; reminders are not used for high-frequency ticks
in-memory storage, reminders, and stream providers are confined to dev/test usage
Aspire projects register required keyed backing resources before UseOrleans() or UseOrleansClient()
reentrancy is handled deliberately — circular call patterns use [Reentrant], [AlwaysInterleave], or AllowCallChainReentrancy
transactional grains are marked [Reentrant] and use PerformRead/PerformUpdate
hot grains, global coordinators, and affinity-heavy grains are measured and justified
tests cover multi-silo behavior, persistence, and failover-sensitive logic when those behaviors matter
Aspire-backed tests reuse one shared AppHost fixture and do not boot the distributed topology inside individual tests
co-hosted Host tests do not start a redundant Orleans client unless external-client behavior is the thing under test
Host or API test factories resolve connection strings from the AppHost resource graph instead of copied local config
deployment uses production clustering, real providers, and proper GC configuration

Load References

Open only what you need. Each reference is topic-focused for token economy:

references/official-docs-index.md — full Orleans documentation map with direct links to the official Learn tree
references/grains.md — grain modeling, persistence, event sourcing, reminders, transactions, versioning links
references/grain-api.md — grain identity, placement, lifecycle, reentrancy, cancellation API details with code
references/persistence-api.md — IPersistentState API, provider configuration, event sourcing, transactions with code
references/streaming-api.md — streams, broadcast channels, observers, IAsyncEnumerable patterns with code
references/serialization-api.md — GenerateSerializer, Id, Alias, surrogates, copier, immutability details
references/hosting.md — clients, Aspire, configuration, observability, dashboard, deployment links
references/configuration-api.md — silo/client config, GC tuning, deployment targets, observability setup with code
references/implementation.md — runtime internals, testing, load balancing, messaging guarantees
references/testing-patterns.md — practical Orleans test harness selection with InProcessTestCluster, shared AppHost fixtures, WebApplicationFactory, SignalR, and Playwright
references/patterns.md — grain, persistence, streaming, coordination, and performance patterns with code
references/anti-patterns.md — blocking calls, unbounded state, chatty grains, bottlenecks, deadlocks with code
references/examples.md — quickstarts, samples browser entries, and official Orleans example hubs

Official sources:

orleans

Microsoft Orleans

Trigger On

Workflow

Architecture

Deliver

Validate

Load References

More from managedcode/dotnet-skills

dotnet

dotnet-aspnet-core

dotnet-entity-framework-core

dotnet-code-review

dotnet-architecture

dotnet-signalr