5.4.2.4.3. Internal Transition

Internal Transition

Internal Transition is the way to consume an Event within State without changing current State.

Internal Transitions are not causing State to exit and enter again - if their Guard evaluates to true, their Effect is executed and that completes Event consumption.

Internal Transition consist of:

• Source State,
• 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, Internal Transition is represented by textual description within the boundary of State:

stateDiagram-v2
SomeState : Trigger [Guard] / Effect

Loading

Equivalent Stateflows notation of Internal Transition:

Lambda style

Definition fragment (inside the builder callback):

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

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 MyInternalTransition : ITransitionGuard<Trigger>, ITransitionEffect<Trigger>
    {
        public Task<bool> GuardAsync(Trigger @event)
        {
            /* bool-returning logic here */
            return Task.FromResult(true);
        }

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

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddState<SomeState>(b => b
        .AddInternalTransition<Trigger, MyInternalTransition>()
    )

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

Class can be used as Internal 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.

Note: interfaces for typed versions of regular Transitions and Internal Transitions are the same.

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

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

    public class SomeState : IState
    { }

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

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

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddState<SomeState>(b => b
        .AddInternalTransition<Trigger>(b => b
            .AddGuard<MyInternalGuard>()
            .AddEffect<MyInternalEffect>()
        )
    )

This technique enables reusing of Internal 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 to access the source state context.

Generic Transitions

If Internal Transition logic does not rely on Trigger Event data and is suitable to be reused in other Transitions, Internal 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.