Library / SDK
dotnet-state-machine/stateless avatar
dotnet-state-machine/stateless

Stateless: a C# state machine library for .NET code

A simple library for creating state machines in C# code

6,291 stars804 forksC#NOASSERTION

At a glance

What is it?
Stateless builds state machines and lightweight state machine-based workflows directly in C#. This review covers the configuration API, external state storage, hierarchical states, and where the library stops being the right tool.
Who is it for?
Adopt Stateless when your transitions are known at compile time and you want them expressed in C# rather than a DSL or a database table. Do not adopt it for long-running, persisted, multi-service orchestration; the library holds no scheduler and no durable store.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly C#, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • dotnet-state-machine/stateless6,291 ★ · +28
Star history
Repository2026-09-232026-11-15
dotnet-state-machine/stateless6.3k6.3k

28 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What problem Stateless solves, and who it is for

The README frames the library as a way to "Create state machines and lightweight state machine-based workflows directly in .NET code". That phrasing matters. This is not a workflow engine that owns a database and a scheduler. It is a class you construct in your own process, configure with states and triggers, and then call Fire on. The problem it addresses is the tangle of boolean flags and switch statements that appears when an object has a lifecycle: a phone call that moves between off hook, ringing, connected and on hold, or a bug report that moves between open, assigned and closed.

The intended audience is a .NET developer who already knows the state diagram and wants it in the codebase, reviewable in a pull request, rather than in a diagramming tool or a BPMN engine. The repository ships five worked examples under example/: AlarmExample, BugTrackerExample, JsonExample, OnOffExample and TelephoneCallExample. That spread is a fair signal of scope. These are object lifecycles inside one application, not distributed sagas.

A secondary audience is anyone who needs to inspect a machine at runtime. The README lists introspection as a feature and points at StateMachine.PermittedTriggers and StateMachine.GetInfo(), which lets a UI enable or disable controls based on what the current state actually allows.

How the C# state machine is configured and fired

The mechanism is a fluent configuration API over a generic StateMachine<TState, TTrigger> instance. You pass the initial state to the constructor, then call Configure once per state. Each Configure call returns a configuration object on which Permit, PermitIf, OnEntry, OnExit, InternalTransition and SubstateOf are chained. The README's opening example builds a phone call machine starting in State.OffHook and permits Trigger.CallDialled into State.Ringing.

Firing is a single call. That is the whole data flow: your code holds the machine, the machine holds the current state, and Fire moves it. There is no event loop and no background thread in the documented design.

Two details shape how you write handlers. Entry and exit actions can take a Transition parameter describing trigger, source and destination, so a single handler can log or audit without you capturing extra variables. And guard clauses are evaluated every time a trigger fires. The README is explicit that guards should therefore be side effect free, and that guards within a state must be mutually exclusive.

Parameterised triggers add typed payloads. SetTriggerParameters<string>(Trigger.Assign) returns a trigger object you later pass to Fire with the value, and OnEntryFrom(assignTrigger, email => OnAssigned(email)) receives it. Trigger parameters can also be used to dynamically select the destination state with PermitDynamic().

Hierarchical states and why IsInState differs from State

Substates are declared with SubstateOf. In the README's example, State.OnHold is configured as a substate of State.Connected, so an on-hold call is still a connected call. The consequence is a deliberate split between two accessors. StateMachine.State reports the precise current state, while IsInState(State) takes substates into account. If the machine is in OnHold, IsInState(State.Connected) evaluates to true.

This is where hierarchical states earn their place. Because OnHold is nested inside Connected, moving between the two does not re-run the entry and exit actions attached to Connected. The README states that StartCallTimer() and StopCallTimer() are not called repeatedly when the call moves between Connected and OnHold. If you had modelled those as sibling states, you would need guard logic to suppress the timer calls yourself.

The trade-off is that IsInState and State can disagree, and code that reads the wrong one will behave incorrectly in ways that are easy to miss. A check written as state == State.Connected will be false while the call is on hold. Use IsInState for questions of the form "is this thing still connected" and State for exact reporting.

Initial transitions are the rougher edge of this feature. A substate can be marked with InitialTransition so that entering the superstate automatically enters the substate. But the README admits that Stateless does not know when it is "started", which makes a traditional initial transition impossible to handle directly. The documented workaround is a dummy initial state whose OnActivate fires the first trigger, which is functional but visibly a workaround.

Installing Stateless and firing your first trigger

The README links the NuGet package under the name stateless, and the repository is a standard .NET solution (Stateless.sln) with sources under src/ and tests under test/. The package is the installation path. Add it to a project with the .NET CLI:

bash
dotnet add package stateless

Once referenced, the smallest useful machine needs an enum of states, an enum of triggers, and a constructor call. The README's own example is the phone call, so start there and trim it:

csharp
var phoneCall = new StateMachine<State, Trigger>(State.OffHook);

phoneCall.Configure(State.OffHook)
    .Permit(Trigger.CallDialled, State.Ringing);

phoneCall.Fire(Trigger.CallDialled);

After the Fire call, phoneCall.State should read State.Ringing. If you fire a trigger that the current state does not permit, the library throws rather than silently ignoring it, which is the behaviour you want during development.

To see what is legal before you call Fire, read the permitted triggers:

csharp
foreach (var trigger in phoneCall.PermittedTriggers)
{
    Console.WriteLine(trigger);
}

That loop prints the triggers the current state will accept, which is the basis for enabling buttons in a UI. For a visual check of the configuration, the README lists export to DOT graph and export to mermaid graph as extensions, so the same machine can be rendered for review.

External state storage and the activation hooks

The default machine keeps its state in memory. For an ORM-mapped entity or a UI framework that requires state in a bindable property, the constructor accepts read and write delegates. The README's example passes () => myState.Value and s => myState.Value = s, after which the machine reads and writes through myState rather than a private field.

This is the design decision that makes Stateless embeddable, and it is also the source of the sharpest limitation. The external storage delegates read and write only the current state value. If you need to undo a half-applied transition, that is your code, not the library's.

Activation and deactivation are the intended hooks for that boundary. The README says to use Deactivate and Activate when you need to run code before storing the object state and when restoring it, and that activation should be called once before normal operation starts and once before state storage. The JsonExample in the example folder is the reference for the persisted case.

One caution follows from the guard design. Because guards run on every Fire and must be side effect free, do not put persistence calls or logging inside a guard. Put them in entry and exit actions, which are the documented place for that work.

Where Stateless is the wrong tool

Stateless assumes the transition graph is known when you write the code. If your states and transitions are configured by end users at runtime and change without a deployment, you are fighting the model. The fluent Configure calls are compile-time code.

The second boundary is durability and time. There is no scheduler, no timer, and no concept of a transition that should happen in three days if nobody acts. A machine that sits in memory waiting for an external event is fine; a workflow that must survive a process restart mid-transition is not what the README describes. The external storage delegates persist the current state value, not a queue of pending work.

The third boundary is distribution. The external storage delegates only read and write the state value, so coordinating two processes that share the same stored state is a job for your storage layer.

Finally, guard clauses carry a correctness obligation the library cannot enforce for you. The README states guards within a state must be mutually exclusive. Treat that as a constraint on your design, not a runtime safety net.

Stateless compared with Windows Workflow Foundation

The obvious alternative in the .NET world is Windows Workflow Foundation, which models long-running workflows with a runtime host, persistence participants, and activities composed into a tree. The difference in approach is where the definition lives. In Workflow Foundation the workflow is a declarative artifact that the runtime loads and executes, with bookmarks that can suspend for days and resume when an external signal arrives. In Stateless the machine is ordinary C# you instantiate, and the current state is a value you can hand to an ORM.

That makes Stateless far cheaper to reason about for an object lifecycle. There is no host, no persistence schema, and no activity library to learn. The cost is that you give up suspension, resumption and the tooling around long-running processes. If your requirement is "this approval must wait for a human for up to two weeks and survive a deployment", Workflow Foundation or a dedicated workflow engine addresses that and Stateless does not.

A lighter alternative worth naming is a hand-written switch over an enum. For a machine with three states and linear transitions, that is often clearer than pulling in a dependency. Stateless starts to pay for itself when you have substates, guards, entry and exit actions, and a need to introspect permitted triggers. Below that threshold it is ceremony.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-10-30. The default branch is dev, not main, so if you are reading the repository expecting a main branch, adjust. There is a CHANGELOG.md at the top level, a CONTRIBUTING.md, and a SECURITY.md, which is the documentation set you would want before depending on a library in production. The repository has no published GitHub releases, so consult CHANGELOG.md and the NuGet page for the version you intend to pin.

The licence is reported as NOASSERTION, which means the repository's LICENSE file does not match a standard identifier that the tooling recognised. Read LICENSE directly before adopting. This is not a legal opinion, and if the terms matter to your organisation, have someone qualified read the file rather than trusting the identifier.

Upgrade cost looks low by design. The public surface is a generic class plus a fluent configuration API, and the README's examples are stable across the features it documents. The risk is not API churn but behavioural assumptions in your own code: if you rely on guard ordering or on IsInState semantics, read the CHANGELOG entry for the version you are moving to.

Editorial conclusion

Adopt Stateless when your transitions are known at compile time and you want them expressed in C# rather than a DSL or a database table. Do not adopt it for long-running, persisted, multi-service orchestration; the library holds no scheduler and no durable store. Before committing, verify how you will persist state through the constructor's read and write delegates, and confirm that your guard clauses are mutually exclusive per state, since the README states multiple guards cannot be valid at the same time.

Frequently asked questions

What is Stateless in C# and what is it used for?

Stateless is a library for creating state machines and lightweight state machine-based workflows directly in .NET code. You configure states and triggers fluently and move between them by calling Fire, which suits object lifecycles such as a phone call or a bug report.

How do I install Stateless?

The README links the NuGet package under the name stateless, so it is added to a .NET project as a package reference. The repository itself is a standard solution with sources under src/ and tests under test/.

What is the difference between State and IsInState in Stateless?

StateMachine.State reports the precise current state, while IsInState takes substates into account. The README's example notes that if the machine is in OnHold, which is a substate of Connected, then IsInState(State.Connected) also evaluates to true.

Can Stateless store state outside the state machine?

Yes. The StateMachine constructor accepts function arguments used to read and write the state values, so the machine can use an ORM-tracked property or a bindable UI property instead of an internal field. The JsonExample in the example folder demonstrates this.

What are the rules for guard clauses in Stateless?

Guards are evaluated whenever a trigger is fired, so the README says they should be side effect free. It also states that guard clauses within a state must be mutually exclusive, and that substates can override transitions but cannot disallow transitions the superstate allows.

Official sources

  1. dotnet-state-machine/stateless on GitHub
  2. Issues
  3. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/dotnet-state-machine-stateless.svg)](https://hysenlabs.com/projects/dotnet-state-machine-stateless)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/dotnet-state-machine-stateless.svg)](https://hysenlabs.com/projects/dotnet-state-machine-stateless)

Was this useful?