# Orleans — Distributed Virtual Actor Framework for .NET

> Orleans is a cross-platform framework from Microsoft for building distributed, high-scale applications using the virtual actor model in .NET.

## Install

Save in your project root:

# Orleans — Distributed Virtual Actor Framework for .NET

## Quick Use
```bash
dotnet new console -n OrleansApp && cd OrleansApp
dotnet add package Microsoft.Orleans.Server
dotnet add package Microsoft.Orleans.Client

# Define a grain interface and implementation, then run:
dotnet run
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-5d069325
Author: AI Open Source