orleans

name	orleans
description	Use when building distributed, stateful applications with Microsoft Orleans. Covers grain design, state persistence, streams, timers, reminders, clustering, and ASP.NET Core co-hosting for virtual actor workloads. USE FOR: distributed virtual actor systems, per-entity stateful services (IoT devices, user sessions, game objects), scalable real-time applications, grain-based event processing, geographically distributed stateful workloads DO NOT USE FOR: stateless HTTP APIs without actor patterns (use ASP.NET Core), simple background tasks (use IHostedService), Dapr actor model (use dapr), ML model training (use mlnet), serverless event processing (use azure-functions)
license	MIT
metadata	{"displayName":"Orleans","author":"Tyler-R-Kendrick","version":"1.0.0"}
compatibility	claude, copilot, cursor
references	[{"title":"Orleans Documentation","url":"https://learn.microsoft.com/dotnet/orleans"},{"title":"Orleans GitHub Repository","url":"https://github.com/dotnet/orleans"},{"title":"Microsoft.Orleans.Server NuGet Package","url":"https://www.nuget.org/packages/Microsoft.Orleans.Server"}]

Orleans

Overview

Microsoft Orleans is a framework for building distributed, scalable, stateful applications using the virtual actor model. Grains (virtual actors) are the fundamental units of computation and state, activated on demand and transparently distributed across a cluster of silos. Orleans handles grain placement, lifecycle, state persistence, and messaging, letting developers focus on business logic while achieving horizontal scalability.

NuGet Packages

dotnet add package Microsoft.Orleans.Server              # Silo (server-side)
dotnet add package Microsoft.Orleans.Client              # External client
dotnet add package Microsoft.Orleans.Sdk                 # Source generators
dotnet add package Microsoft.Orleans.Persistence.AdoNet  # SQL persistence
dotnet add package Microsoft.Orleans.Persistence.AzureStorage  # Azure Table/Blob
dotnet add package Microsoft.Orleans.Clustering.AzureStorage   # Azure clustering
dotnet add package Microsoft.Orleans.Streaming            # Stream providers

Silo Setup (Co-hosted with ASP.NET Core)

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseOrleans(silo =>
{
    if (builder.Environment.IsDevelopment())
    {
        silo.UseLocalhostClustering()
            .AddMemoryGrainStorage("default")
            .AddMemoryGrainStorage("urls");
    }
    else
    {
        silo.UseAzureStorageClustering(options =>
        {
            options.TableServiceClient = new TableServiceClient(
                builder.Configuration["Azure:StorageConnectionString"]);
        })
        .AddAzureTableGrainStorage("default", options =>
        {
            options.TableServiceClient = new TableServiceClient(
                builder.Configuration["Azure:StorageConnectionString"]);
        });
    }
});

var app = builder.Build();

app.MapGet("/shorten/{*path}", async (IGrainFactory grains, HttpRequest request, string path) =>
{
    var shortenedRouteSegment = request.Query[].ToString();
     grain = grains.GetGrain<IUrlShortenerGrain>(shortenedRouteSegment);
     url =  grain.GetUrlAsync();
     url    ? Results.Redirect(url) : Results.NotFound();
});

app.Run();