Getting Started

Zero-friction integration between .NET Aspire and Microsoft Orleans for ADO.NET storage backends. Automatically provisions Orleans database schemas and wires up clustering, grain persistence, and reminders from Aspire configuration — no manual SQL scripts or connection string plumbing required.

• GitHub Repository

Packages

Package	NuGet
Aspire AppHost
Orleans Silo
Orleans Client

Features

• Automatic schema provisioning — Orleans clustering, persistence, and reminder tables are created automatically when the database becomes ready
• Zero connection string plumbing — connection strings and ADO.NET invariants are resolved from Aspire configuration
• Multi-database support — PostgreSQL, SQL Server, and MySQL are auto-detected from the Aspire resource
• Feature selection — choose which Orleans features to provision (clustering, persistence, reminders) via flags
• Multiple grain storage providers — configure named grain storage providers pointing to different databases

Supported Databases

Database	Provider
PostgreSQL	Npgsql
SQL Server	Microsoft.Data.SqlClient
MySQL	MySqlConnector

Quick Start

1. Install packages into your projects

   • AppHost:
   • Silo:
   • Client:

2. Configure the Aspire AppHost

   using Shiny.Aspire.Orleans.Hosting;
   
   var builder = DistributedApplication.CreateBuilder(args);
   
   var db = builder.AddPostgres("pg")
       .AddDatabase("orleans-db");
   
   var orleans = builder.AddOrleans("cluster")
       .WithClustering(db)
       .WithGrainStorage("Default", db)
       .WithReminders(db)
       .WithDatabaseSetup(db); // creates all Orleans tables automatically
   
   builder.AddProject<Projects.MySilo>("silo")
       .WithReference(orleans)
       .WaitFor(db);
   
   builder.AddProject<Projects.MyApi>("api")
       .WithReference(orleans.AsClient())
       .WaitFor(db);
   
   builder.Build().Run();

3. Configure the Orleans Silo

   using Shiny.Aspire.Orleans.Server;
   
   var builder = WebApplication.CreateBuilder(args);
   builder.UseOrleansWithAdoNet();
   var app = builder.Build();
   app.Run();

4. Configure the Orleans Client

   using Shiny.Aspire.Orleans.Client;
   
   var builder = WebApplication.CreateBuilder(args);
   builder.UseOrleansClientWithAdoNet();
   var app = builder.Build();
   
   app.MapGet("/counter/{name}", async (string name, IClusterClient client) =>
   {
       var grain = client.GetGrain<ICounterGrain>(name);
       var count = await grain.GetCount();
       return Results.Ok(new { name, count });
   });
   
   app.Run();

AI Coding Assistant

An AI skill is available for Shiny Aspire Orleans to help configure AppHost, Silo, and Client projects directly in your IDE.

Claude Code

claude plugin add github:shinyorg/skills

GitHub Copilot — Copy the shiny-aspire skill file into your repository’s custom instructions.

Requirements

• .NET 10
• .NET Aspire 13.1+
• Microsoft Orleans 10.0+