Cratis.Choreography.Storage.Sql 2.3.0

<div align="center"> <a href="https://www.cratis.io"> <img src="full-logo.png" alt="Cratis Choreography" width="480"> </a>

<h3 align="center">Cratis Choreography</h3>

<p align="center"> Cratis Choreography is the runtime for durable business processes on Microsoft Orleans — workflows, state machines and jobs that survive restarts, with pluggable storage and one-call silo hosting. <br /> <a href="https://www.cratis.io/choreography/"><strong>Explore the docs »</strong></a> <br /> <br /> <a href="#-getting-started">Getting Started</a>  ·  <a href="https://github.com/cratis/Choreography/issues/new?labels=bug">Report a Bug</a>  ·  <a href="https://github.com/cratis/Choreography/issues/new?labels=enhancement">Request a Feature</a>  ·  <a href="https://discord.gg/kt4AMpV8WV">Join the Discord</a> </p>

<p align="center"> <a href="https://discord.gg/kt4AMpV8WV"> <img src="https://img.shields.io/discord/1182595891576717413?label=Discord&logo=discord&color=7289da" alt="Discord"> </a> <a href="http://nuget.org/packages/cratis.choreography"> <img src="https://img.shields.io/nuget/v/Cratis.Choreography?logo=nuget" alt="NuGet"> </a> <a href="https://github.com/Cratis/Choreography/actions/workflows/dotnet-build.yml"> <img src="https://github.com/Cratis/Choreography/actions/workflows/dotnet-build.yml/badge.svg" alt=".NET Build"> </a> <a href="https://github.com/Cratis/Choreography/actions/workflows/publish.yml"> <img src="https://github.com/Cratis/Choreography/actions/workflows/publish.yml/badge.svg" alt="Publish"> </a> <a href="./LICENSE"> <img src="https://img.shields.io/badge/license-MIT-blue" alt="License"> </a> </p> </div>

Cratis Choreography runs long-lived, stateful behavior on Orleans so it survives restarts, deactivation and moves between silos. It holds a workflow engine that runs a business process defined as a graph of nodes, state machines (plain, and event-sourced through Chronicle), a durable job system for work that outlives a request, a storage API the job state persists through — with MongoDB, SQL and in-memory providers — and the silo hosting tooling that co-hosts Orleans next to an application in one call.

It is consolidated here from Chronicle (the job engine, the workers pattern, the serializers), Direct (the hosting knowledge) and Studio (the package-alignment guard) — so all three consume one canonical implementation instead of three diverging copies. The repository has no dependency on Chronicle; Chronicle is a consumer, like every other Cratis service.

For core values and principles, read our core values and principles.

✨ Key Features

🔀 Workflows and State Machines

↩️ Operation History and Undo/Redo

⚙️ Job System

🗄️ Pluggable Storage

🖥️ Silo Hosting

🩹 Startup Patching

🔧 Building Blocks

📦 Packages

🚀 Getting Started

You need the .NET 10 SDK and, for anything but the in-memory storage, a MongoDB server.

dotnet add package Cratis.Choreography
dotnet add package Cratis.Choreography.Storage.MongoDB

using Cratis.Choreography.Hosting;
using Cratis.Choreography.Setup;
using MongoDB.Driver;

var builder = WebApplication.CreateBuilder(args);

builder.AddCratisChoreography(new CratisChoreographyOptions
{
    ClusterId = "my-service",
    ServiceId = "my-service"
});

builder.Services.AddCratisChoreographyMongoDBJobsStorage(
    new MongoClient("mongodb://localhost:27017"));

var app = builder.Build();
app.Run();

Define a job and its steps — grains, discovered automatically, nothing to register:

public record ProvisionTenant(string TenantId, string[] Features) : IJobRequest;

public interface IProvisionTenant : IJob<ProvisionTenant>;

public class ProvisionTenantJob : Job<ProvisionTenant, JobState>, IProvisionTenant
{
    // Completed jobs remove themselves by default; keep this one queryable.
    protected override bool KeepAfterCompleted => true;

    protected override Task<IImmutableList<JobStepDetails>> PrepareSteps(ProvisionTenant request) =>
        Task.FromResult<IImmutableList<JobStepDetails>>(
            request.Features.Select(feature => new JobStepDetails(
                Type: typeof(IProvisionFeatureStep),
                Id: JobStepId.New(),
                Key: new JobStepKey(JobId, string.Empty, string.Empty),
                Request: feature,
                ResultType: typeof(string))).ToImmutableList());
}

Start it through the jobs manager — the two strings are the storage scope and namespace:

var manager = grainFactory.GetJobsManager("my-service", string.Empty);
var result = await manager.Start<IProvisionTenant, ProvisionTenant>(new(id, ["billing"]));

Starting returns as soon as the job exists. Stop the service mid-flight and start it again — the job picks itself back up. That is the point.

Read the full walkthrough in the getting-started guide.

🧪 Testing

The repository carries three spec tiers:

• Unit specs (Source/*/.Specs) — 76+ Orleans TestKit specs covering the job grain lifecycle, the throttle, the checkpoint debouncer, the serializers and the storage scope resolution.
• Integration specs (Integration/Jobs.Integration) — end-to-end against a real co-hosted silo and a real MongoDB: start a job, run its steps as real grains, persist the state. CI runs a MongoDB service container so these gate every pull request.
• Consumer suites — Chronicle's kernel spec suite (3,496 specs) runs against the package engine through its rip-out integration.

🤝 Support

Cratis is an open community, and we are glad to help users, teams evaluating the stack, and contributors.

👷 Contributing

If you want to jump into building this repository and possibly contributing, refer to contributing.

Prerequisites

• .NET 10 SDK
• Docker — the integration specs and the MongoDB spec suites run against containers

Build and test

dotnet build
dotnet test

The integration specs expect a MongoDB on localhost:27017 (or a running Docker daemon).

📄 License

Cratis Choreography is free software distributed under the MIT License.