Orleans — Distributed Virtual Actor Framework for .NET

Introduction

Orleans is a framework for building distributed applications without managing the complexities of concurrency, state, and failover directly. Originally developed at Microsoft Research and battle-tested in Azure services, it uses a virtual actor model where grains are automatically instantiated, placed, and managed across a cluster.

What Orleans Does

• Implements the virtual actor pattern where grains are addressable, single-threaded units of state and logic
• Automatically manages grain activation, deactivation, and placement across cluster nodes
• Provides transparent persistence with pluggable storage providers (Azure, AWS, ADO.NET, Redis)
• Handles cluster membership, failure detection, and grain directory via built-in protocols
• Supports timers, reminders, and streaming for event-driven and scheduled workloads

Architecture Overview

An Orleans cluster consists of silo processes that host grains. Each grain has a stable identity and is activated on demand — the runtime handles placement decisions and load balancing. Grains communicate through asynchronous messages with turn-based concurrency, eliminating locks. A grain directory (distributed hash table) maps grain IDs to silo locations. State persistence is pluggable: grains checkpoint to external stores and recover on reactivation. The streaming subsystem supports persistent and in-memory streams.

Self-Hosting & Configuration

• Add Orleans NuGet packages and configure a silo with UseOrleans in the host builder
• Choose a clustering provider: Azure Table, SQL Server, Redis, or in-memory for development
• Configure grain storage providers (Azure Blob, DynamoDB, ADO.NET, or custom)
• Set up the dashboard package for real-time monitoring of grains and silos
• Deploy as standard .NET applications on Kubernetes, VMs, or Azure App Service

Key Features

• Turn-based concurrency eliminates locks — each grain processes one message at a time
• Virtual actors are never explicitly created or destroyed, simplifying lifecycle management
• Built-in persistence means grains survive failures and cluster restarts
• Grain timers and reminders enable reliable delayed and periodic execution
• Streaming APIs support pub/sub with backpressure across grain boundaries

Comparison with Similar Tools

• Akka.NET — Requires explicit actor lifecycle management; Orleans auto-manages virtual actors
• Dapr — Runtime-agnostic sidecar model; Orleans is deeply integrated into .NET
• Service Fabric — Full platform with actor support; Orleans is a focused, portable actor framework
• Proto.Actor — Lightweight actor library; Orleans provides richer built-in persistence and clustering
• Temporal — Focuses on durable workflows; Orleans covers broader actor-based distributed patterns

FAQ

Q: What scale can Orleans handle? A: Orleans powers production systems at Microsoft handling millions of concurrent actors across large clusters.

Q: Do I need Azure to run Orleans? A: No. Orleans runs anywhere .NET runs. Azure, AWS, on-premises, and Kubernetes are all supported.

Q: How does grain state persist across failures? A: Grains write state to external storage providers. On reactivation, the runtime restores the last persisted state.

Q: Can Orleans grains call each other? A: Yes. Grains call other grains by their typed interface and ID, and the runtime routes the call across the cluster transparently.

Sources

• https://github.com/dotnet/orleans
• https://learn.microsoft.com/dotnet/orleans/