5.4.2.2.1. State

Simple State

State (sometimes referred to as Simple State) represents stable configuration of State Machine.

A simple State consists of:

• Name, uniquely identifying State within State Machine,
• Parent State, if State is a substate of Composite State or Orthogonal State,
• OnEntry, logic that is executed when State is entered,
• OnExit, logic that is executed when State is exited,
• Set of outgoing Transitions.

Entry and exit actions

Use AddOnEntry and AddOnExit to attach asynchronous actions to a State's lifecycle. Entry logic runs when the State is entered; exit logic runs when it is exited. These callbacks are separate from transition effects, which run as part of a transition between states.

.AddState("Waiting", state => state
    .AddOnEntry(async context =>
        await audit.RecordEnteredAsync(context.CancellationToken))
    .AddOnExit(async context =>
        await audit.RecordExitedAsync(context.CancellationToken)))

The same callbacks can be implemented by typed IStateEntry and IStateExit elements. Composite and orthogonal states additionally support initialization and finalization callbacks; see Composite State.

A typed state can constructor-inject IStateContext, IStateMachineContext, and common behavior/execution contexts together with application services. Use IStateContext.Name for the registered identity instead of repeating a state-name literal. A shared base implementing IStateEntry can automate common stage updates or auditing for its derived states. Keep typed registrations and transition targets consistent; where a string is required, use State<TState>.Name unless the registration explicitly overrides that name. See Dependency Injection.

Definition

In UML, Simple State is represented by rounded rectangle:

stateDiagram-v2
SimpleState --> AnotherState

Loading

If there is any logic within State, it is described textually below State name:

stateDiagram-v2
SimpleState : entry / onEntry
SimpleState : exit / onExit
SimpleState --> AnotherState

Loading

Equivalent Stateflows notation of States:

Lambda style

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddState("SimpleState", b => b
        .AddOnEntry(c => Task.CompletedTask)
        .AddOnExit(c => Task.CompletedTask)
        .AddDefaultTransition("AnotherState")
    )
    .AddState("AnotherState")

Using lambda style here means that State is referred to by string name and each bit of State logic is implemented as lambda function passed as parameters to AddOn* methods in State definition.

Typed style

    public class SimpleState : IStateEntry, IStateExit
    {
        public async Task OnEntryAsync()
        {
            /* logic here */
        }

        public async Task OnExitAsync()
        {
            /* logic here */
        }
    }

    public class AnotherState : IState
    { }

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddState<SimpleState>(b => b
        .AddDefaultTransition<AnotherState>()
    )
    .AddState<AnotherState>()

Using typed style here means that State is a class that is referenced in typed overloads of Add* methods in State Machine definition.

Class can be used as State if it implements at least one interface from IState* family:

• IState - simply represents State,
• IStateEntry - represents State with OnEntry logic implemented as OnEntryAsync() method,
• IStateExit - represents State with OnExit logic implemented as OnExitAsync() method,
• IStateDefinition - represents State with additional Build() method that allows to extend its definition, for example to define Transitions within State class.

State logic may also be split into several classes like in the example:

    public class SimpleState : IState
    { }

    public class SimpleEntry : IStateEntry
    {
        public async Task OnEntryAsync()
        {
            /* logic here */
        }
    }

    public class SimpleExit : IStateExit
    {
        public async Task OnExitAsync()
        {
            /* logic here */
        }
    }

    public class AnotherState : IState
    { }

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddState<SimpleState>(b => b
        .AddOnEntry<SimpleEntry>()
        .AddOnExit<SimpleExit>()

        .AddDefaultTransition<AnotherState>()
    )
    .AddState<AnotherState>()

This technique enables reusing of State's logic, but there is an important concern of State identity to be considered.

State-scoped Values

State Machine states have their own internal key-value collection, separate from the Behavior-wide collection. Use context.State.Values in state actions to keep data with that State; transitions can inspect context.Source.Values and context.Target?.Values. State-scoped data is cleared on exit unless History is enabled for the containing region, in which case it is retained with the restorable configuration. See Behavior Values and State-Scoped Values.