Stateless 3.0 - A State Machine library for .NET Core

State Machines and business processes that describe a series of states seem like they'll be easy to code but you'll eventually regret trying to do it yourself. Sure, you'll start with a boolean, then two, then you'll need to manage three states and there will be an invalid state to avoid then you'll just consider quitting all together. ;)

"Stateless" is a simple library for creating state machines in C# code. It's recently been updated to support .NET Core 1.0. They achieved this not by targeting .NET Core but by writing to the .NET Standard. Just like API levels in Android abstract away the many underlying versions of Android, .NET Standard is a set of APIs that all .NET platforms have to implement. Even better, the folks who wrote Stateless 3.0 targeted .NET Standard 1.0, which is the broadest and most compatible standard - it basically works everywhere and is portable across the .NET Framework on Windows, .NET Core on Windows, Mac, and LInux, as well as Windows Store apps and all phones.

Sure, there's Windows Workflow, but it may be overkill for some projects. In Nicholas Blumhardt's words:

...over time, the logic that decided which actions were allowed in each state, and what the state resulting from an action should be, grew into a tangle of if and switch. Inspired by Simple State Machine, I eventually refactored this out into a little state machine class that was configured declaratively: in this state, allow this trigger, transition to this other state, and so-on.

You can use state machines for anything. You can certainly describe high-level business state machines, but you can also easily model IoT device state, user interfaces, and more.

Even better, Stateless also serialize your state machine to a standard text-based "DOT Graph" format that can then be generated into an SVG or PNG like this with http://www.webgraphviz.com. It's super nice to be able to visualize state machines at runtime.

Modeling a Simple State Machine with Stateless

Let's look at a few code examples. You start by describing some finite states as an enum, and some finite "triggers" that cause a state to change. Like a switch could have On and Off as states and Toggle as a trigger.

A more useful example is the Bug Tracker included in the Stateless source on GitHub. To start with here are the states of a Bug and the Triggers that cause state to change:

enum State { Open, Assigned, Deferred, Resolved, Closed }

enum Trigger { Assign, Defer, Resolve, Close }

You then have your initial state, define your StateMachine, and if you like, you can pass Parameters when a state is trigger. For example, if a Bug is triggered with Assign you can pass in "Scott" so the bug goes into the Assigned state - assigned to Scott.

State _state = State.Open;

StateMachine<State, Trigger> _machine;

StateMachine<State, Trigger>.TriggerWithParameters<string> _assignTrigger;



string _title;

string _assignee;

Then, in this example, the Bug constructor describes the state machine using a fluent interface that reads rather nicely.

public Bug(string title)

{

    _title = title;



    _machine = new StateMachine<State, Trigger>(() => _state, s => _state = s);



    _assignTrigger = _machine.SetTriggerParameters<string>(Trigger.Assign);



    _machine.Configure(State.Open)

        .Permit(Trigger.Assign, State.Assigned);



    _machine.Configure(State.Assigned)

        .SubstateOf(State.Open)

        .OnEntryFrom(_assignTrigger, assignee => OnAssigned(assignee))

        .PermitReentry(Trigger.Assign)

        .Permit(Trigger.Close, State.Closed)

        .Permit(Trigger.Defer, State.Deferred)

        .OnExit(() => OnDeassigned());



    _machine.Configure(State.Deferred)

        .OnEntry(() => _assignee = null)

        .Permit(Trigger.Assign, State.Assigned);

}

For example, when the State is Open, it can be Assigned. But as this is written (you can change it) you can't close a Bug that is Open but not Assigned. Make sense?

When the Bug is Assigned, you can Close it, Defer it, or Assign it again. That's PermitReentry(). Also, notice that Assigned is a Substate of Open.

You can have events that are fired as states change. Those events can take actions as you like.

void OnAssigned(string assignee)

{

    if (_assignee != null && assignee != _assignee)

        SendEmailToAssignee("Don't forget to help the new employee.");



    _assignee = assignee;

    SendEmailToAssignee("You own it.");

}



void OnDeassigned()

{

    SendEmailToAssignee("You're off the hook.");

}



void SendEmailToAssignee(string message)

{

    Console.WriteLine("{0}, RE {1}: {2}", _assignee, _title, message);

}

With a nice State Machine library like Stateless you can quickly model states that you'd ordinarily do with a "big ol' switch statement."

What have you used for state machines like this in your projects?

Sponsor: Big thanks to Telerik! They recently published a comprehensive whitepaper on The State of C#, discussing the history of C#, what’s new in C# 7 and whether C# is still a viable language. Check it out!