The Blog of Ian Mercer.

Building a better .NET State Machine

[Note: Updated version on Nuget has slightly different API, see latest blog post.]

There are several state machine implementations for .NET out there but, sadly, none of them met all of the requirements I have for a state machine. These are:-

  1. Well written using encapsulation and other good practices
  2. Able to be easily serialized to disk
  3. Able to handle temporal events easily (After ... At ... Every ...)
  4. Serialized form must expose a property saying when it next needs to be fetched from disk to run
  5. Implements hierarchical states with entry and exit actions

So I built one, and have made the source code available on Nuget so you can add it to any project easily without any extra DLLs.

Look for "AboditStateMachine" on Nuget to download it. The download includes a sample state machine documented to show off some of its capabilities.

Defining states is easy, just give them a name and specify their parent state if any:-

public static readonly State UnVerified = 
    AddState("UnVerified");
public static readonly State Verified = 
    AddState("Verified");

States are hierarchical. If you are in state VerifiedRecently you are also in its parent state Verified.

public static readonly State VerifiedRecently = 
   AddState("Verified recently", parent: Verified); 

public static readonly State VerifiedAWhileAgo = 
   AddState("Verified a while ago", parent: Verified);

You can use any type that's IEquatable as an Event type or you can use the provided Event class:

private static Event eUserVerifiedEmail = 
    new Event("User verified email"); 
private static Event eScheduledCheck = 
    new Event("Scheduled Check"); 
private static Event eBeenHereAWhile = 
    new Event("Been here a while");

The state machine itself is specified in a static constructor so it runs just once no matter how many instances of the state machine you create.

Each method is provided with an instance of the state machine m as well as the state s and the event e as appropriate:

static DemoStatemachine() 
{ 
    UnVerified
    .OnEnter((m, s, e) => {
       // States can execute code when they are entered or when they are left
       // In this case we start a timer to bug the user until they confirm their email 
       m.Every(new TimeSpan(hours: 10, minutes:0, seconds:0), eScheduledCheck);

       // You can also set a reminder to happen at a specific time, or after a given
       // interval just once
       m.At(new DateTime(DateTime.Now.Year+1, 1, 1), eScheduledCheck); 
       m.After(new TimeSpan(hours: 24, minutes: 0, seconds: 0), eScheduledCheck);
    }) 

// All necessary timing information is serialized with the state machine
// The serialized state machine also exposes a property showing when it 
// next needs to be woken up 
// External code will need to call the Tick(utc) method at that time to trigger
// the next temporal event

    .When(eScheduledCheck, (m, s, e) => 
    { 
       // Send a message to the user asking them to verify their email
       Trace.WriteLine("Send verify email message");
       // We return the current state 's' rather than 'UnVerified' in case 
       // we are in a child state of 'Unverified' 
       // This makes it easy to handle hierarchical states and to either change
       // to a different state or stay in the same state 
       return s; })

    .When(eUserVerifiedEmail, (m, s, e) => 
    {
       Trace.WriteLine("The user has verified their email address, we are done (almost)");
       // Kill the scheduled check event, we no longer need it
       m.CancelScheduledEvent(eScheduledCheck); 
       // Start a timer for one last transition 
       m.After(new TimeSpan(hours:24, minutes:0, seconds:0), eBeenHereAWhile); 
       return VerifiedRecently; 
    });

    VerifiedRecently
    .When(eBeenHereAWhile, (m, s, e) =>
    {
       Trace.WriteLine("User has now been a member for over 24 hours");
       Trace.WriteLine("Give them additional priviledges for example");
       // No need to cancel the 'eBeenHereAWhile' event because it wasn't auto-repeating
       //m.CancelScheduledEvent(eBeenHereAWhile); 
       return VerifiedAWhileAgo; 
    });

    Verified
    .OnEnter((m, s, e) => 
    {
        Trace.WriteLine("The user is now fully verified"); 
    });

    VerifiedAWhileAgo.OnEnter((m, s, e) =>
    { 
        Trace.WriteLine("The user has been verified for over 24 hours"); 
    });

}

With your state machine defined you can now create instances of it, trigger events on them, serialize them to disk, fetch them back, carry on eventing on them, ...

DemoStatemachine demoStateMachine = 
    new DemoStatemachine(DemoStatemachine.UnVerified);

// At the time specified in demoStateMachine.NextTimedEventAt you reload
// the state machine from disk and call 
demoStateMachine.Tick(DateTime.UtcNow);

// When the user verifies their email address you call ...
demoStateMachine.VerifiesEmail();

// At any other time you can examine the current state, or
// act on the state changed event, ...

I hope you find this new state machine implementation useful, and if you have any feedback, do please send it my way.

Related Stories

My love/hate relationship with Stackoverflow

Stackoverflow is a terrific source of information but can also be infuriating.

Ian Mercer
Ian Mercer

Xamarin Forms Application For Home Automation

Building a Xamarin Forms application to control my home automation system

Ian Mercer
Ian Mercer

JSON Patch - a C# implementation

Ian Mercer
Ian Mercer

Websites should stop using passwords for login!

A slightly radical idea to eliminate passwords from many of the websites you use just occasionally

Ian Mercer
Ian Mercer

Dynamically building 'Or' Expressions in LINQ

How to create a LINQ expression that logically ORs together a set of predicates

Ian Mercer
Ian Mercer

VariableWithHistory - making persistence invisible, making history visible

A novel approach to adding history to variables in a programming language

Ian Mercer
Ian Mercer

Neo4j Meetup in Seattle - some observations

Some observations from a meetup in Seattle on graph databases and Neo4j

Ian Mercer
Ian Mercer

Updated Release of the Abodit State Machine

A hierarchical state machine for .NET

Ian Mercer
Ian Mercer

My first programme [sic]

At the risk of looking seriously old, here's something found on a paper tape

Ian Mercer
Ian Mercer

The Internet of Dogs

Connecting our dog into the home automation

Ian Mercer
Ian Mercer

A simple state machine in C#

State machines are useful in many contexts but especially for home automation

Ian Mercer
Ian Mercer

Convert a property getter to a setter

Ian Mercer
Ian Mercer

MongoDB Map-Reduce - Hints and Tips

Ian Mercer
Ian Mercer

Weather Forecasting for Home Automation

Ian Mercer
Ian Mercer

Lengthening short Urls in C#

Ian Mercer
Ian Mercer

Why don't you trust your build system?

Ian Mercer
Ian Mercer

ASP.NET MVC SEO - Solution Part 1

Ian Mercer
Ian Mercer

Elliott 803 - An Early Computer

Ian Mercer
Ian Mercer

Building sitemap.xml for SEO ASP.NET MVC

Ian Mercer
Ian Mercer

Continuous Integration -> Continuous Deployment

What is "quality" in terms of a released software product or website?

Ian Mercer
Ian Mercer

Making a bootable Windows 7 USB Memory Stick

Here's how I made a bootable USB memory stick for Windows 7

Ian Mercer
Ian Mercer

Tip: getting the index in a foreeach statement

A tip on using LINQ's Select expression with an index

Ian Mercer
Ian Mercer

SQL Server - error: 18456, severity: 14, state: 38 - Incorrect Login

A rant about developers using the same message for different errors

Ian Mercer
Ian Mercer

WCF and the SYSTEM account

Namespace reservations and http.sys, my, oh my!

Ian Mercer
Ian Mercer

404 errors on IIS6 with ASP.NET 4 Beta 2

Ian Mercer
Ian Mercer

Mixed mode assembly errors after upgrade to .NET 4 Beta 2

Fixing this error was fairly simple

Ian Mercer
Ian Mercer

The EntityContainer name could not be determined

How to fix the exception "the entitycontainer" name could not be determined

Ian Mercer
Ian Mercer

Shortened URLs should be treated like a Codec ...

Expanding URLs would help users decide whether or not to click a link

Ian Mercer
Ian Mercer

Tagging File Systems

Isn't it time we stopped knowing which drive our file is on?

Ian Mercer
Ian Mercer

A great site for developing and testing regular expressions

Just a link to a site I found useful

Ian Mercer
Ian Mercer

Introducing Jigsaw menus

A novel UI for menus that combines a breadcrumb and a menu in one visual metaphor

Ian Mercer
Ian Mercer

Entity Framework in .NET 4

Ian Mercer
Ian Mercer

Fix for IE's overflow:hidden problem

Ian Mercer
Ian Mercer

A better Tail program for Windows

A comparison of tail programs for Windows

Ian Mercer
Ian Mercer

Measuring website browser performance

Found this great resource on website performance

Ian Mercer
Ian Mercer

Amazon Instance vs Dedicated Server comparison

Some benchmark performance for Amazon vs a dedicated server

Ian Mercer
Ian Mercer

System.Data.EntitySqlException

Hints for dealing with this exception

Ian Mercer
Ian Mercer

Agile Software Development is Like Sailing

You cannot tack too often when sailing or you get nowhere. Agile is a bit like that.

Ian Mercer
Ian Mercer

Exception Handling using Exception.Data

My latest article on CodeProject covers the lesser known Exception.Data property

Ian Mercer
Ian Mercer

Javascript error reporting

Sending client-side errors back to a server for analysis

Ian Mercer
Ian Mercer

AntiVirus Software is the Worst Software!

When your anti-virus software starts stealing your personal data, it's time to remove it!

Ian Mercer
Ian Mercer

ASP.NET Custom Validation

How to solve a problem encountered with custom validation in ASP.NET

Ian Mercer
Ian Mercer

Optimization Advice

Some advice on software optimization

Ian Mercer
Ian Mercer

Linq's missing link

LinqKit came in handy back in 2009

Ian Mercer
Ian Mercer

Google Chart API

Ian Mercer
Ian Mercer

Cache optimized scanning of pairwise combinations of values

Using space-filling curves to optimize caching

Ian Mercer
Ian Mercer

Threading and User Interfaces

A rant about how few software programs get threading right

Ian Mercer
Ian Mercer

Take out the trash!

Why Windows shutdown takes so long

Ian Mercer
Ian Mercer

Dell upgrades - a pricey way to go

Ian Mercer
Ian Mercer

Programming mostly C#

Ian's advice on programming

Ian Mercer
Ian Mercer