2. Installation

Installation

Stateflows is distributed as NuGet packages. Install the core package in an ASP.NET Core application:

dotnet add package Stateflows

Register Stateflows services, a runtime, and one or more behavior definitions with the host's dependency-injection container. This introductory example explicitly enables the transitional Legacy runtime included in the core package:

using Stateflows;
using Stateflows.Common;
using Stateflows.StateMachines;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddStateflows(stateflows => stateflows
    .AddLegacyRuntime()
    .AddStateMachines(machines => machines
        .AddStateMachine("Document", machine => machine
            .AddInitialState("New", state => state
                .AddTransition<Confirm>("Confirmed"))
            .AddState("Confirmed"))));

var app = builder.Build();
app.MapPost("/documents/{id}/confirm", async (
    string id,
    IStateMachineLocator locator) =>
{
    if (!locator.TryLocateStateMachine(new StateMachineId("Document", id), out var document))
    {
        return Results.NotFound();
    }

    var result = await document.SendAsync(new Confirm());
    return result.Status == EventStatus.Consumed
        ? Results.Ok(new { result.Status })
        : Results.Problem($"Document confirmation failed: {result.Status}.");
});
app.Run();

public sealed record Confirm;

This host registers a State Machine, locates an instance, and sends Confirm from an endpoint. It is not a distributed-host or production-persistence configuration. The Legacy runtime is a temporary, in-process implementation scheduled for removal; new deployments should configure Orleans, which is intended to be the remaining runtime. After starting the application, post to /documents/document-42/confirm using its listening URL. A successfully consumed event moves that instance from New to Confirmed; a repeated Confirm is no longer accepted by this definition.

See State Machines, Activities, Actions, and Entities for complete behavior contracts. The custom endpoint above is ordinary ASP.NET Core; generated endpoints are a separate extension.

Runtime requirement

Every Stateflows host must configure exactly one runtime; registering behavior definitions alone is not sufficient. AddStateflows configures Stateflows services and definitions but does not select or start a runtime.

The core package currently includes the transitional Legacy runtime. Enable it explicitly with AddLegacyRuntime() as in the introductory example. It runs in-process and is scheduled for removal. For new applications, use the Orleans runtime instead: install Stateflows.Runtimes.Orleans, configure Orleans storage and reminders, and call AddStateflowsRuntime() on the silo builder. Do not configure both runtimes in the same host. See Runtimes and Orleans Runtime.

Optional packages

Install only the packages required by the application:

Package	Use
Stateflows.Testing	Test Stateflows behaviors and their parts.

Other optional integrations are listed in Extensions. HTTP APIs are provided by the Minimal APIs extension; no separate legacy HTTP transport packages are listed here.