3.1. Orleans Runtime

Orleans Runtime

Every Stateflows host must configure a runtime; registering services and behavior definitions alone is not sufficient. Stateflows.Runtimes.Orleans is the supported distributed runtime for Microsoft Orleans silos and is the recommended choice for new applications. The core package still contains a transitional in-process Legacy runtime, but it is scheduled for removal; Orleans is intended to be the only runtime thereafter. Configure exactly one runtime per host. State Machines, Activities, Actions, and Entities use the same Orleans grain contract; a behavior instance is addressed by its tenant and BehaviorId, so applications do not generate a separate Orleans grain type for every behavior definition.

Register behavior definitions and the runtime

Install Stateflows.Runtimes.Orleans, register definitions with builder.Services.AddStateflows(...), and add the runtime to the Orleans silo builder with AddStateflowsRuntime(). Do not call AddLegacyRuntime() in this host:

using Orleans.Hosting;
using Stateflows;
using Stateflows.StateMachines;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddStateflows(stateflows => stateflows
    .AddStateMachines(machines => machines
        .AddStateMachine<Order>()));

builder.Host.UseOrleans(silo => silo
    .UseLocalhostClustering()
    .AddMemoryGrainStorageAsDefault()
    .UseInMemoryReminderService()
    .AddStateflowsRuntime());

using var host = builder.Build();
await host.RunAsync();

The Orleans package is published as Stateflows.Runtimes.Orleans and provides the silo integration. The application still registers behavior definitions through the usual Stateflows builders. Configure a cluster, Orleans grain storage, and an Orleans reminder service as required by your deployment; the in-memory providers above are suitable only for development or tests.

Storage and reminders

Behavior state is owned by its Orleans behavior grain. The runtime does not use a separate Stateflows storage provider to hydrate or dehydrate behavior contexts. Persistent state is stored using Orleans grain storage and includes behavior context, pending time events, event receipts and publication outbox, notification history/subscriptions/deliveries, and the behavior instance index.

The runtime requires both an Orleans grain storage provider and a reminder service/table. If AddStateflowsRuntime is called without a StorageProviderName, it uses Orleans' default grain storage provider. To select a named provider, register that Orleans provider and set the exact name in runtime options:

builder.UseOrleans(silo => silo
    .AddAdoNetGrainStorage("workflow-storage", options =>
    {
        options.Invariant = "Microsoft.Data.SqlClient";
        options.ConnectionString = connectionString;
    })
    .UseAdoNetReminderService(options =>
    {
        options.Invariant = "Microsoft.Data.SqlClient";
        options.ConnectionString = connectionString;
    })
    .AddStateflowsRuntime(options =>
        options.StorageProviderName = "workflow-storage"));

Reminder storage is configured through Orleans separately from StorageProviderName. An explicit storage provider name must be nonempty and is not silently replaced with the default. Configure storage and reminders before starting the silo; runtime configuration validation reports missing providers during startup. Keep provider selection consistent across silos. Switching providers or renaming persisted state does not migrate existing records.

Use durable storage and a durable reminder table in production. The memory providers lose their data when their silo shuts down. For safe failover, use a grain storage provider that supports ETag-based concurrency, so an activation from a failed silo cannot overwrite state committed by its replacement.

Transactions

AddStateflowsRuntime() enables Orleans transactions. Ordinary behavior events start independent transactions, including single-behavior calls. To include another behavior in the sender's transaction, pass the JoinTransaction header:

var result = await inventory.SendAsync(new ReserveInventory(orderId),
    new Dictionary<string, EventHeader>
    {
        [nameof(JoinTransaction)] = new JoinTransaction()
    });

The header also applies to requests and related-entity operations. Entity mutation, projection and field operations are independent by default; joining is opt-in. A joined request can read earlier tentative writes in the same transaction. Joining without an ambient sender transaction fails explicitly.

Behavior context, receipts and deferred delivery intent commit atomically across joined behaviors. Application execution failure returns Failed. A joined child's failure aborts the root even if its caller ignores the result: the root returns Aborted, unless the root itself fails, in which case Failed takes precedence. Known infrastructure aborts return Aborted; uncertain outcomes propagate Orleans transaction exceptions. Failed index or reminder-registration prerequisites throw StateflowsInfrastructureException, retaining the underlying cause. These errors are not application Failed results, even if a parent ignores a joined failure; the root's own application failure still takes precedence. Do not treat an exception as proof that nothing committed. The runtime does not automatically replay transactions. The Minimal API extension maps Aborted to HTTP 409.

Behavior state uses Orleans ITransactionalState. SQL Server configuration above uses Orleans' built-in bridge from IGrainStorage to transactional storage; the provider must supply real ETags. Orleans recommends that bridge for development, not as its most efficient production transactional store, and may remove it in a future release. Evaluate its performance and support risk for production. This changes the persisted behavior-state record format; existing nontransactional records are not migrated automatically.

Indexes and reminders are reconciled from committed state. Wakeups are registered before committing delivery/scheduling obligations; harmless orphan wakeups can remain after an abort and are cleaned up later. Notifications sent immediately and external side effects are not rolled back. Deferred publications and staged sends leave the outbox only after commit.

Orleans imposes a transaction timeout (approximately ten seconds in the currently used ITransactionClient implementation without a debugger). Keep ordinary atomic handlers short; the Stateflows checkpoint barrier timeout is a separate limit.

Active Activity streams cannot join a distributed transaction, and stream admission cannot carry JoinTransaction. Streaming remains live and nontransactional: ordinary calls interacting with a live network cannot roll back concurrent firings. Durable snapshots and publication metadata still use short independent transactions. New stream admission is rejected while a joined outcome is awaiting reconciliation.

Behavior hosting, tenant identity, and startup

Each behavior grain is identified by tenant plus BehaviorId. Different silos may register different behavior classes, but definitions must be fixed before the silo starts; adding or changing definitions at runtime is not supported. Behavior code is not distributed by Orleans runtime registration: each silo must deploy compatible assemblies, dependencies, and event/response types for any behavior definitions it hosts.

Default instances are initialized for configured tenants when their hosting silo starts. Orleans hosting does not automatically dispatch the shared Startup event and does not use startup-triggered context scanning or startup indexes. The Startup event remains available for explicit use; legacy startup-index data is unused by this runtime.

The IStateflowsStorage bridge is intentionally grain-scoped: reading or writing behavior contexts outside their owning behavior grain is unsupported. For discovery, use GetAllContextIdsAsync and then interact with each behavior by sending events or requests, rather than trying to retrieve its in-memory context.

Cluster discovery and placement

Silos advertise the behavior classes and definition versions they host. Each silo discovers the capabilities of active silos asynchronously and refreshes them periodically. Locators can therefore take a short time to discover newly started remote definitions; discovery is eventually consistent, and failed capability reads are retried.

Orleans placement is filtered so behavior activations land only on silos that host that behavior class. During rolling upgrades, silos that host every registered definition version are preferred, allowing existing instances to run their persisted version while new instances use the newest version. If no silo hosts every version, the runtime logs an incompatible-deployment warning and places on silos hosting the newest version. If a persisted version is not registered on the selected silo, that activation fails explicitly instead of running under a different version.

When a lazy state read detects an unsupported persisted version, the call fails without executing that definition and the runtime asks Orleans to re-evaluate placement through migration. A later call can succeed when a compatible silo becomes available; the failed event is not automatically replayed.

When no active silo is known to host a behavior class, sends fail with an error indicating that no eligible silo hosts the behavior. Its persisted state is left intact; the behavior can become available again when a hosting silo returns. Remote behavior discovery does not verify that same-named definitions with the same version have compatible code or schemas.

Scheduling, notifications, and resource limits

Stateflows time events use Orleans reminders; behavior state does not need to be periodically scanned by a separate Stateflows scheduler. Retryable notification delivery also uses Orleans-backed state and reminders.

Notification publication defaults to Retain = false and TTL 0: no notification history or persistent subscription retry queue is created, and current subscribers receive one delivery attempt. Retain = true stores only the latest retained notification of each type and supersedes its previous pending retries. TTL 0 keeps that value indefinitely; positive TTL expires it. Nonretained notifications with positive TTL keep all unexpired history for subscription retries and timestamp-based requests, but are not returned by requests without a timestamp.

Client watches are volatile and independent of durable behavior subscriptions. Transactional publisher outbox handoff remains separate from notification retention. See notification retention and requests for details and examples.

AddResource(...).SetMaxConcurrentBehaviorExecutions(...) and SetResourceName(...) are enforced independently on each silo across the instances and behavior classes assigned to that resource. Executions awaiting another behavior retain their permit; awaited dependency chains should use separate resources or enough capacity to avoid permit exhaustion. Optional queue-length and wait-time limits can shed load before permit waiters accumulate.

An execution rejected by admission limits, or arriving while the silo is stopping, returns EventStatus.Overloaded. It is not executed, committed, or recorded as received, so a caller may retry. Reminder-driven work treats overload as retryable. On graceful shutdown, waiting executions are rejected and accepted execution, stream-pump persistence and transaction finalization drain before Orleans transaction services stop, even after execution permits have been released. Draining is bounded by the host's shutdown timeout. Abrupt process termination cannot drain in-flight work.

Activity streaming

Orleans Activities support ordinary run-to-completion events and nonblocking streamed token admission on the same activation-owned network. IActivityBehavior.StreamInputAsync sends TokensInput with the Stream header; Accepted acknowledges volatile admission rather than execution completion or durability. Other behavior types and the Legacy runtime do not support this mode.

Regular Activity transactions remain in inbox order and do not overlap. Stream admission can interleave with an executing regular event, and streamed work can keep running after that regular call returns. Token provenance governs transaction handoff and publication ownership; this is selective interleaving, not unrestricted actor guarantees for every branch.

During a busy stream, values and marking remain live and are persisted together at natural quiescence or a checkpoint, not after every input. Regular receipt/publication metadata can commit separately without making the entire network durable. Due time events can be delivered through the live session; new timer schedules remain volatile until checkpointed.

Configure the two streaming limits through runtime options:

silo.AddStateflowsRuntime(options =>
{
    options.MaxQueuedActivityStreamEvents = 128;
    options.ActivityStreamBarrierTimeout = TimeSpan.FromSeconds(30);
});

Option	Default	Meaning
MaxQueuedActivityStreamEvents	128	Maximum queued batches plus in-flight batch executions per Activity activation; must be greater than zero; not an end-to-end interleaved backlog limit
ActivityStreamBarrierTimeout	Timeout.InfiniteTimeSpan	Maximum wait for a checkpoint firing-boundary barrier; nonnegative or infinite

Admission slots and resource leases remain held until the admitted batch execution completes or queued work is discarded. A later arrival can transfer tokens into an existing interleaving invocation and finish its batch execution before those partitions complete, releasing its slot and lease. Neither this batch count nor parallel maxConcurrency caps the interleaved partition backlog, token payload sizes, retained marking, or buffered output. Use application-level outstanding-work accounting tied to explicit processing completion when an end-to-end bound is required; see stream admission limits.

Use durable grain storage for recovery; a live stream is not a durable queue, even when its admission succeeds.

Send ActivityCheckpoint, use activity.CheckpointAsync(), or attach the Checkpoint header to a regular call to persist a firing-boundary snapshot. Recovery resumes recorded ready firings and structural continuations rather than restoring .NET task stacks.

See Activity Streaming for the full concurrency, value, failure, and cancellation contract, and Activity Checkpoints for barrier ordering and recovery.

Observability

Stateflows.Extensions.OpenTelemetry integrates the runtime with OpenTelemetry. It exports per-resource behavior execution counts, durations, running and waiting gauges, as well as the Stateflows.Orleans meter for persistence, reminder, index, publication, discovery, and admission failures. Configure exporters through the application's OpenTelemetry setup. The waiting gauge counts work waiting for a local Stateflows resource permit; it is not Orleans mailbox depth, which should be monitored through Orleans' own metrics.

See the OpenTelemetry guide for instrumentation setup and the runtime source for Orleans-specific implementation details.