5.4.2.4.1. Transition

Regular Transition

Transition (sometimes referred to as Regular Transition) is the way to move from one State to another, by this changing stable configuration of State Machine.

Regular Transition consist of:

• Trigger, an Event which causes Transition to happen,
• Source State or Pseudostate,
• Target State or Pseudostate,
• Guard, a predicate logic (that returns boolean value) that is evaluated in order to check if Transition can happen or not,
• Effect, logic that is executed when Transition is happening.

Definition

In UML, Transition is represented by an arrow that connects two States or Pseudostates:

stateDiagram-v2
SomeState --> AnotherState : TriggerEvent

Loading

If there is any logic within Transition, it is described textually using following special characters:

stateDiagram-v2
SomeState --> AnotherState : TriggerEvent<br/>[Guard]<br/>/Effect

Loading

Equivalent Stateflows notation of Transition:

Lambda style

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddState("SomeState", b => b
        .AddTransition<TriggerEvent>("AnotherState", b => b
            .AddGuard(async c => true /* bool-returning logic here */)
            .AddEffect(c => Task.CompletedTask) 
        )
    )
    .AddState("AnotherState")

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

Typed style

    public class SomeState : IState
    { }

    public class AnotherState : IState
    { }

    public class TriggerEvent
    { }

    public class TriggerEventTransition : ITransitionGuard<TriggerEvent>, ITransitionEffect<TriggerEvent>
    {
        public Task<bool> GuardAsync(TriggerEvent @event)
        {
            /* bool-returning logic here */
            return Task.FromResult(true);
        }

        public Task EffectAsync(TriggerEvent @event)
        {
            return Task.CompletedTask;
        }
    }

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddState<SomeState>(b => b
        .AddTransition<TriggerEvent, TriggerEventTransition, AnotherState>()
    )
    .AddState<AnotherState>()

Using typed style here means that States and Transitions are classes that is referenced in typed overloads of Add* methods in State Machine definition.

Note: AddTransition<>() method accepts several type parameters. Regardless the overload variant, the order of those parameters is always the same: Trigger > Transition class > Target State / Pseudostate class.

Class can be used as Transition if it implements at least one interface from ITransition*<TEvent> family:

• ITransition<TEvent> - simply represents Transition,
• ITransitionGuard<TEvent> - represents Transition with Guard logic implemented as GuardAsync() method,
• ITransitionEffect<TEvent> - represents Transition with Effect logic implemented as EffectAsync() method,
• ITransitionDefinition<TEvent> - represents Transition with additional Build() method that allows to extend its definition, for example to define Guards and Effects in Transition class.

All interfaces are contravariant in TEvent type parameter, which allows to reuse Transition logic for multiple Trigger Event types sharing common ancestor or interface.

The typed overload automatically attaches all implemented guard/effect contracts. Prefer a combined transition class when the same guard and effect always belong together, instead of repeating AddGuard<T>() and AddEffect<T>() at each registration. Guard and effect hooks are activated separately; do not rely on instance fields to transfer data between them.

Transition logic may also be split into several classes when the parts are independently reusable, like in the example:

    public class SomeState : IState
    { }

    public class AnotherState : IState
    { }

    public class TriggerEvent
    { }

    public class TriggerEventGuard : ITransitionGuard<TriggerEvent>
    {
        public Task<bool> GuardAsync(TriggerEvent @event)
        {
            /* bool-returning logic here */
            return Task.FromResult(true);
        }
    }

    public class TriggerEventEffect : ITransitionEffect<TriggerEvent>
    {
        public Task EffectAsync(TriggerEvent @event)
        {
            return Task.CompletedTask;
        }
    }

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddState<SomeState>(b => b
        .AddTransition<TriggerEvent, AnotherState>(b => b
            .AddGuard<TriggerEventGuard>()
            .AddEffect<TriggerEventEffect>()
        )
    )
    .AddState<AnotherState>()

This technique enables reusing of Transition's logic.

Transition classes can constructor-inject ITransitionContext, IStateMachineContext, common behavior/execution contexts, and application services. They cannot inject a current IStateContext; use ITransitionContext.Source / .Target to access the source and target state context.

Generic Transitions

If Transition logic does not rely on Trigger Event data and is suitable to be reused in other Transitions, Transition classes may be created by implementing at least one interface from ITransition* family:

• ITransitionGuard - represents Transition with Guard logic implemented as GuardAsync() method,
• ITransitionEffect - represents Transition with Effect logic implemented as EffectAsync() method,
• ITransitionDefinition - represents Transition with additional Build() method that allows to extend its definition, for example to define Guards and Effects in Transition class.

Such classes are called Generic Transitions and may be used to declare all types of Transitions.