dotnet-orleans

Microsoft Orleans

Trigger On

• building or reviewing .NET code that uses Microsoft.Orleans.*, Grain, IGrainWith*, UseOrleans, UseOrleansClient, IGrainFactory, or Orleans silo/client builders
• modeling high-cardinality stateful entities such as users, carts, devices, rooms, orders, digital twins, sessions, or collaborative documents
• choosing between grains, streams, reminders, stateless workers, persistence providers, placement strategies, 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

Workflow

1. Decide whether Orleans is the right abstraction. Use it when the system has many loosely coupled interactive entities which 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.
2. Model grain boundaries around business identity, not around controllers, tables, or arbitrary CRUD slices. Prefer one grain per user, cart, device, room, order, or other durable entity.
3. Keep grain APIs coarse-grained and fully asynchronous. Avoid .Result, .Wait(), blocking I/O, lock-based coordination, or long chatty call chains between grains.
4. Use current Orleans state patterns. Prefer constructor-injected IPersistentState<TState> with named states and named providers. Treat Grain<TState> as legacy unless you are constrained by existing code.
5. Pick the right runtime primitive deliberately:
   • use standard grains for stateful request/response logic
   • use [StatelessWorker] for pure stateless fan-out or compute helpers
   • use Orleans streams for decoupled event flow and pub/sub
   • use RegisterGrainTimer for activation-local periodic work
   • use reminders for durable low-frequency wakeups which must survive deactivation or restarts
6. Choose hosting intentionally. Use UseOrleans for silos and UseOrleansClient for separate clients. In Aspire, declare the Orleans resource in AppHost, wire clustering/storage/reminders there, and use .AsClient() for frontend-only consumers.
7. Configure providers with production realism. In-memory storage, reminders, and stream providers are for development or tests only. Prefer managed identity and DefaultAzureCredential for Azure-backed providers when possible.
8. Treat placement and activation movement as optimization tools, not defaults to cargo-cult. Start with the current runtime defaults and only add custom placement, rebalancing, or repartitioning when measurement shows a real locality or load problem.
9. Make the cluster observable. Add logging, OpenTelemetry, health checks, and dashboard access deliberately. If you expose the Orleans Dashboard, secure it with ASP.NET Core authorization and treat it as an operational surface.
10. Test the cluster behavior you actually depend on. Prefer InProcessTestCluster for new tests, add multi-silo coverage when placement, reminders, persistence, or failover behavior matters, and benchmark hot grains before claiming the design scales.