State Machines and Wizard Components: A Clean Implementation Approach

by Joche Ojeda | Mar 2, 2025 | C#, System Theory

This past week, I have been working on a prototype for a wizard component. As you might know, in computer interfaces, wizard components (or multi-step forms) allow users to navigate through a finite number of steps or pages until they reach the end. Wizards are particularly useful because they don’t overwhelm users with too many choices at once, effectively minimizing the number of decisions a user needs to make at any specific moment.

The current prototype is created using XAF from DevExpress. If you follow this blog, you probably know that I’m a DevExpress MVP, and I wanted to use their tools to create this prototype.

I’ve built wizard components before, but mostly in a rush. Those previous implementations had the wizard logic hardcoded directly inside the UI components, with no separation between the UI and the underlying logic. While they worked, they were quite messy. This time, I wanted to take a more structured approach to creating a wizard component, so here are a few of my findings. Most of this might seem obvious, but sometimes it’s hard to see the forest for the trees when you’re sitting in front of the computer writing code.

Understanding the Core Concept: State Machines

To create an effective wizard component, you need to understand several underlying concepts. The idea of a wizard is actually rooted in system theory and computer science—it’s essentially an implementation of what’s called a state machine or finite state machine.

Theory of a State Machine

A state machine is the same as a finite state machine (FSM). Both terms refer to a computational model that describes a system existing in one of a finite number of states at any given time.

A state machine (or FSM) consists of:

• States: Distinct conditions the system can be in
• Transitions: Rules for moving between states
• Events/Inputs: Triggers that cause transitions
• Actions: Operations performed when entering/exiting states or during transitions

The term “finite” emphasizes that there’s a limited, countable number of possible states. This finite nature is crucial as it makes the system predictable and analyzable.

State machines come in several variants:

• Deterministic FSMs (one transition per input)
• Non-deterministic FSMs (multiple possible transitions per input)
• Mealy machines (outputs depend on state and input)
• Moore machines (outputs depend only on state)

They’re widely used in software development, hardware design, linguistics, and many other fields because they make complex behavior easier to visualize, implement, and debug. Common examples include traffic lights, UI workflows, network protocols, and parsers.

In practical usage, when someone refers to a “state machine,” they’re almost always talking about a finite state machine.

Implementing a Wizard State Machine

Here’s an implementation of a wizard state machine that separates the logic from the UI:

public class WizardStateMachineBase
{
    readonly List<WizardPage> _pages;
    int _currentIndex;

    public WizardStateMachineBase(IEnumerable<WizardPage> pages)
    {
        _pages = pages.OrderBy(p => p.Index).ToList();
        _currentIndex = 0;
    }

    public event EventHandler<StateTransitionEventArgs> StateTransition;

    public WizardPage CurrentPage => _pages[_currentIndex];

    public virtual bool MoveNext()
    {
        if (_currentIndex < _pages.Count - 1) { var args = new StateTransitionEventArgs(CurrentPage, _pages[_currentIndex + 1]); OnStateTransition(args); if (!args.Cancel) { _currentIndex++; return true; } } return false; } public virtual bool MovePrevious() { if (_currentIndex > 0)
        {
            var args = new StateTransitionEventArgs(CurrentPage, _pages[_currentIndex - 1]);
            OnStateTransition(args);

            if (!args.Cancel)
            {
                _currentIndex--;
                return true;
            }
        }
        return false;
    }

    protected virtual void OnStateTransition(StateTransitionEventArgs e)
    {
        StateTransition?.Invoke(this, e);
    }
}

public class StateTransitionEventArgs : EventArgs
{
    public WizardPage CurrentPage { get; }
    public WizardPage NextPage { get; }
    public bool Cancel { get; set; }

    public StateTransitionEventArgs(WizardPage currentPage, WizardPage nextPage)
    {
        CurrentPage = currentPage;
        NextPage = nextPage;
        Cancel = false;
    }
}

public class WizardPage
{
    public int Index { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public bool IsRequired { get; set; } = true;
    public bool IsCompleted { get; set; }
    
    // Additional properties specific to your wizard implementation
    public object Content { get; set; }
    
    public WizardPage(int index, string title)
    {
        Index = index;
        Title = title;
    }
    
    public virtual bool Validate()
    {
        // Default implementation assumes page is valid
        // Override this method in derived classes to provide specific validation logic
        return true;
    }
}

Benefits of This Approach

As you can see, by defining a state machine, you significantly narrow down the implementation possibilities. You solve the problem of “too many parts to consider” – questions like “How do I start?”, “How do I control the state?”, “Should the state be in the UI or a separate class?”, and so on. These problems can become really complicated, especially if you don’t centralize the state control.

This simple implementation of a wizard state machine shows how to centralize control of the component’s state. By separating the state management from the UI components, we create a cleaner, more maintainable architecture.

The WizardStateMachineBase class manages the collection of pages and handles navigation between them, while the StateTransitionEventArgs class provides a mechanism to cancel transitions if needed (for example, if validation fails). The newly added WizardPage class encapsulates all the information needed for each step in the wizard.

What’s Next?

The next step will be to control how the visual components react to the state of the machine – essentially connecting our state machine to the UI layer. This will include handling the display of the current page content, updating navigation buttons (previous/next/finish), and possibly showing progress indicators. I’ll cover this UI integration in my next post.

By following this pattern, you can create wizard interfaces that are not only user-friendly but also maintainable and extensible from a development perspective.

Source Code

egarim/WizardStateMachineTest

About US

YouTube

https://www.youtube.com/c/JocheOjedaXAFXAMARINC

Our sites

https://www.bitframeworks.com

https://www.xari.io

https://www.xafers.training

Let’s discuss your XAF Support needs together! This 1-hour call/zoom will give you the opportunity to define the roadblocks in your current XAF solution

Schedule a meeting with us on this link