Microsoft Orleans: A Comprehensive Guide from Beginner to Advanced

This is a structured English summary of a long Chinese tutorial titled "Orleans: From Beginner to Master" posted on zhichai.net. The original is a full course-style guide with extensive C# code samples.

Key points

• What Orleans is: Microsoft Orleans is a cross-platform .NET framework for distributed, scalable applications based on the Virtual Actor model. It is battle-tested in production by Xbox Live, Halo 4/5, Skype, Azure IoT, Azure Digital Twins, and PlayFab.
• Framework comparison: Compared with Akka.NET and Proto.Actor, Orleans uses virtual actors (automatic lifecycle management vs. manual), has the best memory efficiency and cloud-native support, and a gentler learning curve.

Core architecture

• Cluster: a set of cooperating Silos providing horizontal scaling, high availability, and load balancing; clients connect via a Gateway.
• Silo: runtime container hosting grains, handling activation/deactivation, message routing, persistence, and failure detection.
• Grain: the core virtual-actor abstraction with a unique key, state, and interface-defined behavior. Key types include IGrainWithGuidKey, IGrainWithIntegerKey, IGrainWithStringKey, and compound-key variants.

Quick start

Install Microsoft.Orleans.Server, Microsoft.Orleans.Client, Microsoft.Orleans.Sdk, and optionally Microsoft.Orleans.Analyzers. A minimal app defines a grain interface (IGrainWithStringKey), implements it, configures the silo via builder.Host.UseOrleans(...) with UseLocalhostClustering() and memory storage, and exposes it through an ASP.NET Core endpoint. Standalone clients use ClientBuilder with Connect().

Grain details

• Lifecycle: Created → Activating (OnActivateAsync) → Active → Deactivating (OnDeactivateAsync) → Deactivated.
• Grains call each other via GrainFactory.GetGrain<T>().
• Grains are non-reentrant by default; [Reentrant] and [AlwaysInterleave] allow interleaved execution with thread-safety caveats.
• [StatelessWorker] enables multiple activations per silo for stateless, compute-heavy workloads.
• Versioning is supported via the [Version] attribute.

State persistence

• Recommended approach: IPersistentState<T> with [PersistentState("profile", "store")] constructor injection and WriteStateAsync().
• Providers: Memory (dev), Azure Table/Blob, Azure Cosmos, Redis, SQL Server/PostgreSQL (ADO.NET), DynamoDB.
• Legacy pattern: inherit from Grain<TState> with [StorageProvider].

Streams, timers, and reminders

• Streams implement pub/sub with providers for Azure Queue, memory streams, and Event Hubs; consumers use explicit SubscribeAsync or [ImplicitStreamSubscription] attributes.
• Grain Timers: non-persistent, high-frequency, in-memory (new RegisterGrainTimer API with GrainTimerCreationOptions).
• Reminders: persistent, minute-level, survive deactivation; require a reminder store (e.g., Azure Table) and IRemindable.

Distributed transactions

• Enable with UseTransactions() and transactional storage; use [Transaction(TransactionOption.Join)] and ITransactionalState<T> with PerformRead/PerformUpdate; execute cross-grain transactions via ITransactionClient.RunTransaction.

Advanced features

• Observer pattern (IGrainObserver, CreateObjectReference) for pushing notifications to clients.
• Placement strategies: Random (default historically), ActivationCountBased, ResourceOptimized (Orleans 9.x default, with configurable CPU/memory weights), PreferLocal, and custom strategies.
• Custom grain directory via UseAdoNetGrainDirectory.
• RequestContext for propagating metadata (trace IDs, user IDs).
• IAsyncEnumerable support for async streams from grains.
• POCO grains: implement IGrainBase without inheriting Grain.

Other sections

The full guide also covers ASP.NET Core integration, testing strategies, production deployment, and a best-practices/pitfall guide, plus appendices. Code samples in the original post are preserved in the source Chinese article.