Orleans tutorials and samples

Use this page to choose the right kind of learning material:

• Quickstarts lead you through a focused task.
• Tutorials teach a capability step by step.
• Explanations describe how a complete application is modeled.
• Samples are maintained, buildable applications which you can inspect and run.

Start here

For the bare minimum application, start with Orleans Hello World. It hosts a silo and calls a grain from one process.

For a more typical project structure, Build your first Orleans app using separate grain contract, implementation, silo, and external-client projects.

Tutorials

Tutorial	What it teaches
Deploy an Orleans application to Azure Container Apps	Run, deploy, observe, and verify a multi-process Orleans application.
Test an Orleans application end to end	Progress from a first cluster test to reusable fixtures and topology changes.
Build and recover a streaming application	Follow events through a real provider and verify recovery from checkpoints.
Custom grain storage	Implement and register an IGrainStorage provider.
Deploy and scale on Azure	Deploy an Orleans app to Azure Container Apps and configure shared providers.

Explanations

Article	What it explains
Adventure game sample	How rooms, players, and objects map to grains and ordinary values.
Why Orleans	The benefits and tradeoffs of the virtual actor model.
Orleans architecture design principles	The design goals which shape Orleans APIs and runtime behavior.

Maintained samples

The samples directory contains the official Orleans samples. Its sample catalog is generated from the repository manifest and is validated together with the sample projects.

Fundamentals

Sample	Demonstrates
Hello World	A single-project silo, grain contract, implementation, reference, and call.
Adventure	Domain modeling with grains and a standalone client.
Chirper	Persistence, observers, and reentrant grains.
Simple Streaming	Stream producers, consumers, and subscriptions.

Web and application integration

Sample	Demonstrates
Shopping Cart	Blazor, persistence, and a multi-project application.
Blazor Server	A Blazor Server application backed by grains.
Blazor WebAssembly	A hosted WebAssembly client with an Orleans-backed server.
GPS Tracker	ASP.NET Core SignalR and IoT-style device updates.
Presence Service	Observers and cooperating grains in a gaming scenario.

State, scheduling, and messaging

Sample	Demonstrates
Bank Account	ACID transactions across stateful grains.
Journaled Todo List	Experimental Journaling APIs, Aspire, and durable journaled grain state.
Journaling with Azure Blob JSON	Experimental Journaling APIs with Azure Blob Storage.
Chat Room	A terminal chat application using Orleans Streams.
Stocks	Grain timers, HTTP calls, and temporary caching.

The Journaling samples use the experimental Microsoft.Orleans.Journaling package. They are separate from the supported Orleans Event Sourcing model.

Deployment and operations

Sample	Demonstrates
Azure Container Apps	A cluster, clients, dashboard, scaler, and Bicep deployment.
Azure App Service	A multi-instance Orleans application on App Service.
Transport Layer Security	Mutual TLS for Orleans network communication.
Voting	Kubernetes-oriented deployment and the Orleans Dashboard.

The repository catalog also includes F#, Visual Basic, games, custom stream adapters, and other focused examples.

Validate samples locally

After cloning the Orleans repository, run the sample validation script from the repository root:

pwsh ./samples/Validate-Samples.ps1

The script validates the gallery manifest and builds every project in samples/Samples.slnx. Cloud credentials are needed only to run samples which connect to cloud services, not to compile them.