SiLA2.StateMachine 10.2.3

SiLA2.StateMachine

A state machine module for orchestrating multi-step SiLA2 lab automation workflows. Built on the Stateless library, it provides a fluent API for defining workflows with automatic retry policies, OpenTelemetry tracing, and dependency injection support.

Features

• Fluent Builder API: Define states, transitions, and actions with method chaining
• Async Entry/Exit Actions: Execute SiLA2 service calls on state transitions
• Workflow Context: Thread-safe data sharing between workflow steps
• Retry Policies: Configurable retry with constant or exponential backoff
• Auto-Advance: Automatic state progression via completion triggers
• Progress Events: Subscribe to workflow state changes and errors
• OpenTelemetry: Built-in tracing via ActivitySource
• DOT Graph Export: Visualize state machines with Graphviz

Installation

dotnet add package SiLA2.StateMachine

Platform Compatibility

This package multi-targets net10.0 and netstandard2.0, allowing it to be used from both modern .NET and legacy .NET Framework projects.

Quick Start

using SiLA2.StateMachine;
using SiLA2.StateMachine.Models;

// Define states and triggers
enum State { Idle, Processing, Done, Error }
enum Trigger { Start, Complete, Fault }

// Build workflow
var workflow = new SilaWorkflowBuilder<State, Trigger>()
    .StartIn(State.Idle)
    .Permit(State.Idle, Trigger.Start, State.Processing)
    .Permit(State.Processing, Trigger.Complete, State.Done)
    .Permit(State.Processing, Trigger.Fault, State.Error)
    .InState(State.Processing)
        .OnEntry(async (ctx, sp, ct) =>
        {
            // Call SiLA2 services here
            ctx.Set("result", 42);
        })
        .OnCompleted(Trigger.Complete)
        .OnError(Trigger.Fault, maxRetries: 3, retryDelayMs: 1000)
    .Build();

// Run workflow
await workflow.FireAsync(Trigger.Start);

Console.WriteLine($"State: {workflow.CurrentState}");  // Done
Console.WriteLine($"Result: {workflow.Context.Get<int>("result")}");  // 42

Core Concepts

States and Triggers

States and triggers are defined as enums (or structs). The workflow transitions between states when triggers are fired.

enum AssayState { Idle, Aspirating, Dispensing, Incubating, Measuring, Done, Error }
enum AssayTrigger { Start, AspirateComplete, DispenseComplete, IncubateComplete, MeasureComplete, Fault }

Workflow Builder

Use the fluent builder to configure states, transitions, and actions:

var workflow = new SilaWorkflowBuilder<AssayState, AssayTrigger>()
    .StartIn(AssayState.Idle)

    // Define transitions
    .Permit(AssayState.Idle, AssayTrigger.Start, AssayState.Aspirating)
    .Permit(AssayState.Aspirating, AssayTrigger.AspirateComplete, AssayState.Dispensing)

    // Configure state behavior
    .InState(AssayState.Aspirating)
        .WithDescription("Aspirate sample from source plate")
        .OnEntry(async (ctx, sp, ct) =>
        {
            var liquidHandler = sp.GetRequiredService<ILiquidHandlerClient>();
            await liquidHandler.AspirateAsync(100.0, ct);
            ctx.Set("aspiratedVolume", 100.0);
        })
        .OnCompleted(AssayTrigger.AspirateComplete)
        .OnError(AssayTrigger.Fault, maxRetries: 2, retryDelayMs: 1000)

    .Build(services, logger);

Workflow Context

The IWorkflowContext is a thread-safe data bag for passing values between states:

// In state A
ctx.Set("temperature", 37.5);
ctx.Set("sampleId", "SAMPLE-001");

// In state B
var temp = ctx.Get<double>("temperature");
if (ctx.TryGet<string>("sampleId", out var id))
{
    Console.WriteLine($"Processing {id}");
}

Error Policies

Configure retry behavior for transient failures:

.InState(State.Measuring)
    .OnEntry(async (ctx, sp, ct) => { /* may fail */ })
    .OnError(Trigger.Fault, WorkflowErrorPolicy.ExponentialBackoff(
        maxRetries: 5,
        initialDelay: TimeSpan.FromSeconds(1),
        multiplier: 2.0))

Progress Events

Subscribe to workflow progress:

workflow.ProgressChanged += (sender, progress) =>
{
    Console.WriteLine($"{progress.FromState} → {progress.ToState}");
    if (progress.Exception != null)
        Console.WriteLine($"Error: {progress.Exception.Message}");
};

ASP.NET Core Integration

// Program.cs
using SiLA2.StateMachine.Extensions;

builder.Services.AddSilaStateMachine();

// Or register a pre-configured workflow
builder.Services.AddSilaWorkflow<AssayState, AssayTrigger>(builder =>
{
    builder
        .StartIn(AssayState.Idle)
        .Permit(AssayState.Idle, AssayTrigger.Start, AssayState.Processing)
        // ... configure workflow
});

// In a controller or service
public class AssayController
{
    private readonly SilaWorkflowBuilder<AssayState, AssayTrigger> _builder;
    private readonly IServiceProvider _services;
    private readonly ILogger<AssayController> _logger;

    public AssayController(
        SilaWorkflowBuilder<AssayState, AssayTrigger> builder,
        IServiceProvider services,
        ILogger<AssayController> logger)
    {
        _builder = builder;
        _services = services;
        _logger = logger;
    }

    public async Task<IActionResult> RunAssay()
    {
        var workflow = _builder.Build(_services, _logger);
        await workflow.FireAsync(AssayTrigger.Start);
        return Ok(new { Status = workflow.Status, State = workflow.CurrentState });
    }
}

OpenTelemetry Integration

The library emits traces via System.Diagnostics.ActivitySource:

// Subscribe to workflow traces
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddSource("SiLA2.StateMachine");  // Activity source name
    });

Traced activities:

• Workflow.Run - Full workflow execution
• Workflow.Fire - Individual trigger firing
• Workflow.StateEntry - State entry action execution (with retry attempts)

Advanced Patterns

Hierarchical States

.SubstateOf(State.Processing, State.Running)

Conditional Transitions

.PermitIf(State.Idle, Trigger.Start, State.FastPath,
    () => _config.UseFastPath, "Fast path enabled")
.PermitIf(State.Idle, Trigger.Start, State.SlowPath,
    () => !_config.UseFastPath, "Slow path enabled")

DOT Graph Export

Generate Graphviz diagrams:

var dotGraph = workflow.ToDotGraph();
File.WriteAllText("workflow.dot", dotGraph);
// Render with: dot -Tpng workflow.dot -o workflow.png

Builder Methods

Workflow Status

Working Example

See the complete plate assay workflow example:

Path: src/Examples/WorkflowOrchestration/

dotnet run --project src/Examples/WorkflowOrchestration/SiLA2.StateMachine.Example.csproj

This example demonstrates:

• Multi-step lab workflow (Discover → Aspirate → Dispense → Incubate → Measure → Report)
• Service discovery simulation
• Context data passing between states
• Retry policies for transient failures
• Progress event handling
• Serilog logging integration

Troubleshooting

Related Packages

• SiLA2.Client - Server discovery and gRPC channel management
• SiLA2.Core - Core server implementation
• SiLA2.AspNetCore - ASP.NET Core integration

License

MIT License - See LICENSE file for details.