DEV Community: yohan

Analyzing Caliburn.Micro — Part 4

yohan — Sat, 31 Oct 2026 08:22:34 +0000

Picking up from earlier posts, we continue introducing Convention in Caliburn.Micro (CM).

Preface

This Caliburn.Micro series has already covered several posts. For a third-party application framework, an exhaustive walk-through of every detail is not the top priority—grasping the overall design quickly and accurately matters more. Caliburn.Micro includes many features: Action and Convention, which we have already introduced, plus Coroutine, EventAggregator (weak events), and more. Many of those are icing on the cake; EventAggregator, for example, is also covered in frameworks like Prism. CM’s core ideas are Action and Convention. This article follows that main line in detail.

The CM Main Line

Caliburn.Micro positions itself as a lightweight MVVM framework. In MVVM, the View and ViewModel are associated through DataContext; the View passes operations to the ViewModel via Binding and Command, and refreshes automatically when bound properties in the ViewModel change. This table compares Caliburn.Micro with a typical MVVM framework:

Feature	Typical MVVM framework	Caliburn.Micro
Automatically associate View and ViewModel (via the View’s DataContext)	Not supported	Supported, via NameTransformer
Command	Supported; Command is recommended	Not supported; Action is the alternative
Binding	Supported; Binding is recommended	Supported; Convention can be used as an alternative
Validation, StringFormat, Converter, UpdateSourceTrigger	Supported through Binding’s corresponding mechanisms	Supported; Convention can be used as an alternative

A simple side-by-side example:

Typical MVVM framework:

<Button Command="{Binding Path=ChangeNameCommand}"/>

<TextBox Text="{Binding Path=UserName}"/>

Using Caliburn.Micro:

<Button x:Name="ChangeName"/>

<TextBox x:Name="UserName"/>

The corresponding ViewModel:

With Caliburn.Micro you only set the Name of the Button and TextBox so that it matches the corresponding property and method names on the ViewModel; CM sets up the binding and the Button method invocation automatically.

That is intentional in CM’s design: make View–ViewModel interaction simpler. Set the right names and let CM do the rest.

Command vs Action

WPF defines a Command mechanism. The interface is ICommand, with Execute and CanExecute methods, and CommandParameter is available as the call argument. The Command pattern decouples the object that initiates an operation from the object that handles it—a sound idea in WPF, though the concrete implementation still has some shortcomings.

Some WPF controls expose a Command property that lets you plug in an ICommand for a specific operation. Command triggering is based on Routed Events; for example, a Button triggers Command execution on OnClick. WPF implements Command on many controls such as Button, but coverage is incomplete—controls like ComboBox have no Command.

A Command can respond to only one Routed Event, and for built-in controls that response is hard-wired (Click). WPF does provide CommandBindings on controls so you can attach multiple Commands, but the syntax is verbose and support for the MVVM pattern is weak. To support MVVM better, Blend introduced TriggerAction as a simpler way to attach Commands:

<Button>
      <i:Interaction.Triggers>
          <i:EventTrigger EventName="Click">
              <i:ExecuteCommandAction TargetCommand="LoginCommand"/>
          </i:EventTrigger>
      </i:Interaction.Triggers>
</Button>

Here the Command’s trigger is the Click event; when it fires, the corresponding ViewModel’s LoginCommand runs.

CM’s Action is based on Blend’s TriggerAction. Its ActionMessage inherits from TriggerAction<FrameworkElement>. The difference is that it does not call a Command on the ViewModel; instead it uses reflection to look up the corresponding method on the ViewModel and invoke it.

Action and Convention

For convenience, a CM Action need not name a method explicitly; it matches properties and methods on the ViewModel using the control’s Name. For how Action is used in practice, see the first article. We are discussing framework design, and designs do not appear out of thin air. ActionMessage was introduced to replace Command—let’s look at the problems that follow:

CM’s Action design is deliberately foolproof: you only design the control’s Name and smart matching takes care of the rest. Because this is a “smart” mode, that intelligence is a control point. Which control properties should be smart-bound, how to keep that intelligence smart enough, and ensuring that using it does not break existing design patterns—all matter.
Command and Binding are two of WPF’s highlights. After adopting CM the code is leaner, but Command and Binding seem to disappear. How do you preserve features such as Command’s CanExecute, and Binding’s Validation, StringFormat, Converter, and so on?
Complexity versus flexibility. A feature-rich framework with oceans of code is intimidating; a lean framework that lacks extensibility is unsatisfying. Striking that balance is also a challenge.

To address these issues, CM introduces the concept of Convention.

ElementConvention

For how View and ViewModel are matched automatically, see the previous post. Here we focus on ElementConvention. In short, it was introduced to handle the “intelligence” problem: it is the description of how a Convention is processed for a concrete type. We saw earlier that with

<TextBox x:Name="UserName"/>

CM automatically binds the TextBox’s Text to the ViewModel’s UserName property. CM does two things here: first, based on the control type (TextBox), it decides which property of the control to bind; second, it uses the control’s name for smart matching. We will discuss the second point later; for now, see how CM handles different control types.

CM uses ElementConvention as the type description for Convention processing. CM provides the static ConventionManager class that lets you manipulate ElementConventions. ElementConvention looks like this:

public class ElementConvention
{
    public Type ElementType;
    public string ParameterProperty;
    public Func<DependencyObject, DependencyProperty> GetBindableProperty;
    public Func<System.Windows.Interactivity.TriggerBase> CreateTrigger;
}

For a TextBox, ElementType is its type (TextBox), ParameterProperty is the property it targets (Text), GetBindableProperty is a Func that returns TextProperty for a TextBox, and CreateTrigger returns the trigger event (TextChanged).

ConventionManager provides default handling descriptions for several types in its static functions, for example:

AddElementConvention<ButtonBase>(ButtonBase.ContentProperty, "DataContext", "Click");
AddElementConvention<TextBox>(TextBox.TextProperty, "Text", "TextChanged");
AddElementConvention<TextBlock>(TextBlock.TextProperty, "Text", "DataContextChanged");

You can call ConventionManager’s AddElementConvention method to register a new type or change an existing ElementConvention.

Convention

Having covered the Convention handling description (ElementConvention), let’s talk about the Convention process itself.

The whole Convention process starts with binding View and ViewModel:

Manually or automatically, CM calls ViewModelBinder’s Bind method (passing the corresponding View and ViewModel). CM uses View.GetApplyConventions(View) to decide whether to apply Convention on that View. If you do not want CM’s Convention features, set the attached property View.SetApplyConventions to False on the View, or set the global flag ViewModelBinder.ApplyConventionsByDefault to False to disable Convention.
Convention is enabled by default. CM walks the View’s VisualTree and collects every named control.
Convention is applied to those named controls. There are two kinds: ActionConvention and PropertyConvention. Action means method invocation; Property means property binding.
If, when calling AddElementConvention, the last argument supplied a trigger event name (Click, TextChanged, and so on), that control type can have an ActionConvention. CM matches the control’s name against all public method names on the ViewModel; if there is a match, ActionConvention is applied. For the earlier Button → ChangeName example, the method matches the corresponding ViewModel method, and the trigger is the Click event registered by AddElementConvention: <Button x:Name="ChangeName" />
If, when calling AddElementConvention, the second argument supplied a property name, PropertyConvention applies to that control type. The method is similar: match the control’s name against all public property names on the ViewModel and, if there is a match, set up the binding.

Validation, StringFormat, Converter…

If a control gets PropertyConvention, CM has set up the property binding for us automatically. How do Validation, StringFormat, Converter, and the rest of Binding’s features fit in?

ConventionManager provides SetBinding to perform PropertyConvention. Here is its code:

public static Func<Type, string, PropertyInfo, FrameworkElement, ElementConvention, bool> SetBinding =
    (viewModelType, path, property, element, convention) => {
        var bindableProperty = convention.GetBindableProperty(element);
        if(bindableProperty == null || HasBinding(element, bindableProperty))
            return false;

        var binding = new Binding(path);

        ApplyBindingMode(binding, property);
        ApplyValueConverter(binding, bindableProperty, property);
        ApplyStringFormat(binding, convention, property);
        ApplyValidation(binding, viewModelType, property);
        ApplyUpdateSourceTrigger(bindableProperty, element, binding, property);

        BindingOperations.SetBinding(element, bindableProperty, binding);

        return true;
    };

ApplyBindingMode, ApplyValueConverter, and the rest are all Funcs you can replace with your own processing; the defaults are quite simple. In other words, the property bindings CM sets up for us are the most basic ones. CM’s PropertyConvention handling is deliberately simple. If you have already set Text="{Binding Path=ChangeName}" on the property by hand, CM ignores that property. PropertyConvention only produces the most basic property binding; if you want smarter bindings, replace these Funcs with your own logic. This is also an overall CM design idea: do smart things to simplify the program, but make those operations optional, do only what is necessary, and leave room for customization.

Conclusion

The greatest success of CM’s design is its simplicity and flexibility. It works well alongside other frameworks and can be integrated into existing code with relative ease. If you already have your own framework, try integrating CM. I will not go into CM’s remaining features here. Questions and comments are welcome—I also hope to exchange ideas with more friends. Thank you.

Analyzing Caliburn.Micro — Part 3

yohan — Sat, 31 Oct 2026 08:21:07 +0000

Following on from the previous post, which briefly introduced Caliburn.Micro (CM) Action, this article continues with the next CM feature: Convention.

What Is a Convention?

Convention is often translated as “pact” or “agreement”—a shared rule of conduct that all parties, having reached consensus, follow. In CM, Convention is mainly used for pairing and matching. That pairing primarily means pairing the View with the ViewModel. As mentioned earlier, CM is based on the MVVM pattern. In MVVM (Model-View-ViewModel), the Model holds the data and is relatively fixed; the relationship between View and ViewModel is more fluid. Let’s briefly introduce that.

View-First or ViewModel-First?

In MVVM, the ViewModel’s job is to hold the View’s state and encapsulate the Model’s data. The ViewModel evolved from the PresentationModel pattern, and it does not store every piece of View state—only state that might be modified. WPF mainly contributed two technologies that made the ViewModel practical:

Data binding. WPF provides data binding: the View binds to the ViewModel and uses the ViewModel as its DataContext. When View state stored in the ViewModel changes, the View refreshes automatically.
Command. WPF provides ICommand so that when the user operates the View, the operation is passed to the ViewModel through a Command.

The View’s two main jobs—displaying data and manipulating data—are abstracted out, and View state lives in the ViewModel. Because of data binding, the View associates with the ViewModel through DataContext, and the two are loosely coupled. That is the beauty of the MVVM pattern. Back to the topic of this article: how do View and ViewModel find each other? View-First or ViewModel-First?

ViewModel-First

In general, ViewModel-First is recommended. Design the ViewModel first, then generate the corresponding View with a DataTemplate. The benefit is that the View can be swapped at any time, and unit tests can mock a View. The CM framework provides ViewLocator to locate the View for a given ViewModel, with methods as follows:

public static Func<object, DependencyObject, object, UIElement> LocateForModel
public static Func<Type, DependencyObject, object, UIElement> LocateForModelType

CM makes heavy use of Func overrides for polymorphism. LocateForModel and LocateForModelType take a ViewModel instance or type respectively and return the corresponding View. Those names are a bit weak—GetCorrespondingView would be clearer.

How does locating the View from the ViewModel work? It takes two steps. First, find the View’s Type from the ViewModel. Second, create the View with reflection via Activator.CreateInstance(Type type).

To operate on the View from the ViewModel more conveniently, CM provides IViewAware so a ViewModel can cache the corresponding View. The IViewAware interface is defined as follows:

public interface IViewAware
{
    void AttachView(object view, object context = null);
    object GetView(object context = null);
    event EventHandler<ViewAttachedEventArgs> ViewAttached;
}

ViewAware is the default implementation of IViewAware. When the ViewModel and View are bound together, IViewAware’s AttachView is called. You can override OnViewAttached to process the View—for example, register View events (be careful of strong references). When the View is loaded into the visual tree, ViewAware.OnViewLoaded is called; you can walk the View’s visual tree there.

When When ViewLocator calls LocateForModel, it first checks whether the ViewModel implements IViewAware and has already cached a View. If so, it returns the cached View instead of creating a new one. That brings us back to step one: how to find the View’s Type from the ViewModel.

NameTransformer

CM uses NameTransformer to infer possible View types with regular expressions. The implementation works like this:

NameTransformer defines ReplacePattern (the replacement rule), ReplaceValue (the replacement value), and GlobalFilterPattern (a filter rule); the inference is done with regular expressions. For example, set ReplacePattern to ViewModel$ and ReplaceValue to View. This rule means: replace the trailing ViewModel part of the string with View. If the ViewModel type passed in is Illusion.ViewModels.ShellViewModel, the returned type after replacement is Illusion.ViewModels.ShellView.

ViewLocator ships with five default rules:

Strip a trailing View.
Replace a trailing ViewModel with View.
Replace a trailing PageViewModel with Page.
Replace Illusion.ViewModels.ShellViewModel with Illusion.Views.ShellView (replace ViewModels → Views, ShellViewModel → ShellView).
Replace Illusion.ViewModels.ShellPageViewModel with Illusion.Views.ShellPage (same idea as above).

For real projects, if you follow CM’s recommended naming—Illusion.ViewModels.ShellViewModel → Illusion.Views.ShellView—CM will find the corresponding View automatically. If you separate View and ViewModel and do not follow those naming conventions, you must add corresponding rules to ViewLocator’s NameTransformer so it can find the View type.

After ViewLocator resolves the View type, what it actually has is a string. CM still needs to turn that string into a real Type via an Assembly. CM does not scan every assembly in the AppDomain; it keeps an AssemblySource that holds the set of assemblies to search. You can override BootStrapper.SelectAssemblies to return the assemblies in scope, or call AssemblySource’s Add / AddRange methods to add more assemblies.

For example, if you use DirectoryCatalog to watch plugins and the corresponding View types live in plugins, you must add the plugin assemblies to AssemblySource—otherwise ViewLocator cannot find the View. In View–ViewModel matching, CM’s design provides some implementations and room for extension, but it is not fully automatic; you still need project-specific customization.

Of course, you can skip smart matching altogether, create View and ViewModel by hand, and bind them with ViewModelBinder’s Bind method.

View-First

In the WP7 environment, View-First is recommended: locate the ViewModel from the View, then bind them together. The implementation and matching rules are the same as ViewModel-First and are omitted here.

Action Convention

In the Action covered in the previous article, we wrote markup like:

<Button cm:Message.Attach="[Event MouseEnter] = [Action Show('Enter')];
                           [Event MouseLeave] = [Action Show('Leave')]" />

That is Action Convention: CM turns the string after Attach into the corresponding Actions. There is not much room for extension here, so I will not go into detail.

Property Convention

This is one of the powerful parts of CM, and the details—including ElementConvention—are quite interesting. I’ll save them for the next post. ^_^

Analyzing Caliburn.Micro — Illusion = Caliburn.Micro + MEF

yohan — Sat, 31 Oct 2026 08:11:01 +0000

Introduction

I am preparing to use Caliburn.Micro together with MEF to build an IDE-like framework similar to VS2010. It should support plugin development, configurable menus and toolbars, and features such as Options, multi-language support, and theming. On the one hand this is a way to consolidate technical experience; on the other it can serve as a guide for friends new to WPF or interested in Caliburn.Micro.

I could not think of a great name, so the project is called Illusion—I hope it is not an illusion.

The starting point of the project is not complicated: use MEF for plugin development, DirectoryCatalog for plugin discovery, and Export/Import to build menus, toolbars, and so on. Caliburn.Micro is an open-source framework based on the MVVM pattern. Its code is concise without being simplistic, and it is a sharp tool for enterprise application development.

Implementation

The project layout looks like this:

The Illusion project is the core framework. Illusion.Demo is the EXE project that uses Illusion. The AddIns folder holds several plugin projects. The solution uses the mature open-source AvalonDock for docking windows.

The running program:

The project introduces two concepts: Part and Screen. As shown above, child items of the menu and toolbar are called Parts; docked windows such as Project are called Screens.

Configuration

The code to add a menu item looks like this:

[MenuPart(BaseMenu = WorkbenchName.WindowPart, PreviousMenu = WorkbenchName.CloseDocumentsPart)]
public class ResetLayoutPart : MenuPart
{
    public ResetLayoutPart()
        : base(WorkbenchName.ResetLayoutPart)
    {
        Icon = "Icons.16x16.CopyIcon";
    }

    public override void Execute()
    {
        base.Execute();
    }
}

The MenuPart attribute on the first line inherits from ExportAttribute and is equivalent to [Export(typeof(IMenuPart))]. BaseMenu and PreviousMenu specify the parent item and the preceding menu item of ResetLayoutPart, which together determine where the menu item appears. When the menu is clicked, Execute is called—put the menu’s action code there. You can override CanExecute to decide whether the menu is enabled, and set the IsVisible property to control visibility.

Often the same item appears both in a menu and on a toolbar. To avoid duplicate code, a MenuToolPart class is defined so that a Part can serve as both a menu item and a toolbar button.

Adding a Screen is similar to adding a Part and is omitted here.

Other Notes

You can add plugin projects that export Parts, Screens, and so on.

At runtime, DirectoryCatalog watches the AddIns directory and imports all plugins.

Other features—Options, multi-language, theming, etc.—are left to the code and are not described one by one here.

Chatter

The Illusion project has been written on and off for over a week. Turning ideas into code is one thing; after the passion fades comes emptiness. Working behind closed doors takes patience. Over the years I have written a lot of code in my spare time and then left it to gather dust.

I am uploading the code so we can discuss it. If you are interested in this area, feel free to contact me. I am not attaching any restrictive license; corrections are welcome, and so is taking whatever is useful. If it truly helps you, please leave a comment or give it a thumbs-up. As the saying goes in the jianghu:

Be a brother—be decent.

Download the Illusion code from here. It uses System.Windows.Interactivity and requires Expression Blend 4 or later.

Analyzing Caliburn.Micro — Part 2

yohan — Sat, 31 Oct 2026 08:09:50 +0000

Following on from the previous post, which briefly introduced Caliburn.Micro (CM), this article digs into CM and looks at its most interesting feature: Action.

Running CM

Download Caliburn.Micro, open Template, and copy Caliburn_Micro_WPF.zip to %userprofile%\Documents\Visual Studio 2010\Templates\ProjectTemplates\Visual C#\Windows. Create a new project in Visual Studio 2010, choose Visual C# — Windows, and you will see the Caliburn.Micro template. Create a new project named CaliburnMicroWPF1 as follows:

The Framework folder contains the Caliburn.Micro source code. ShellView is the main window; ShellViewModel is the DataContext of ShellView. This is a standard View–ViewModel pattern. AppBootstrapper is the startup loader and lets you configure how CM is loaded.

Bootstrapper

The Bootstrapper constructor looks like this:

public Bootstrapper()
{
    if (IsInDesignMode)
        StartDesignTime();
    else StartRuntime();
}

You can override StartDesignTime to provide design-time data for Blend and similar tools. At runtime, StartRuntime is called:

protected virtual void StartRuntime()
{
    Execute.InitializeWithDispatcher();
    AssemblySource.Instance.AddRange(SelectAssemblies());

    Application = Application.Current;
    PrepareApplication();

    Configure();
    IoC.GetInstance = GetInstance;
    IoC.GetAllInstances = GetAllInstances;
    IoC.BuildUp = BuildUp;
}

You can override PrepareApplication to listen to Application events, or override Configure to set up an IOC (Inversion of Control) container. The three static IoC fields at the end are especially interesting:

public static class IoC
{
    public static Func<Type, string, object> GetInstance;
    public static Func<Type, IEnumerable<object>> GetAllInstances;
    public static Action<object> BuildUp;

    public static T Get<T>()
    {
        return (T)GetInstance(typeof(T), null);
    }

    public static T Get<T>(string key)
    {
        return (T)GetInstance(typeof(T), key);
    }
}

IoC is a static class that provides IOC support; its Get methods look up a registered instance by type. A common approach is to define IoC as a virtual base class and let subclasses override Get with their own logic. The IoC class instead achieves polymorphism through three static Func fields. The AppBootstrapper uses MEF as the default IOC implementation. You can override Bootstrapper to use another IOC container such as Unity.

MEF

MEF (Managed Extensibility Framework) was formally introduced into the .NET Framework after .NET 4.0. By attaching simple Export and Import attributes that describe the “consumer” and “provider” relationships between components, MEF dynamically discovers and composes components under the hood. MEF makes it much easier to develop plugin-based application systems. This article is not a detailed MEF guide; as the default IoC implementation, Caliburn.Micro simply uses MEF.

Here we only adopt MEF by default—specifically, we use its CompositionContainer as the IoC container. CM itself has no hard dependency on MEF. Let’s keep our eyes on CM and step into Caliburn.Micro starting from the simplest possible application.

The First Application

Add a Button to ShellView, drag ActionMessage onto the Button from Blend — Assets, and set the Trigger’s EventName to Click. Switch to ShellViewModel and add a Show method:

public void Show()
{
    MessageBox.Show("Hello");
}

Back in ShellView, set the ActionMessage’s MethodName to Show, as shown below:

When the program runs and you click the Button, the Show method is invoked.

That is the simplest possible ActionMessage usage. Let’s walk through what happens.

Put simply, clicking the Button executes the method. The most primitive approach would be to put Click="HandleBtnClick" in the Button’s XAML and handle the event in code-behind. Later, as MVVM became popular, you would set ShellViewModel as the DataContext of ShellView, provide an ICommand—ShowCommand—in ShellViewModel, and bind the Button with Command="{Binding ShowCommand}".

ActionMessage does two things here:

Match by name and automatically set ShellViewModel as the DataContext of ShellView.
Use reflection to look up the method by name and invoke it.

The design is straightforward. The first step—name matching—is a distinctive CM Convention that automatically pairs XXViewModel with XXView. The second step looks up the MethodInfo named Show on the XXViewModel found earlier and invokes it via reflection.

ActionMessage

The design of ActionMessage is not complex. It inherits from TriggerAction<FrameworkElement> and can therefore act on a FrameworkElement. At runtime the TriggerAction is attached to its corresponding FrameworkElement. ActionMessage has two important properties: MethodName and Parameters. The former is the name of the method to execute; the latter is a collection of parameters to pass in. MethodName has already been introduced above—let’s look at how Parameters works.

The simplest usage is to change the ViewModel’s Show() method to Show(string message) and pass the argument through Parameters:

<cm:ActionMessage MethodName="Show">
    <cm:Parameter Value="woo~"/>
</cm:ActionMessage>

When Show executes, the woo~ argument is passed in. Parameters can also carry multiple arguments; if no matching method is found, an exception is thrown. CM extends the Parameter Value as well:

Value supports binding, so you can write Value="{Binding ElementName=XX, Path=XX}".
CM provides a MessageBinder class to parse messages. You can use $eventArgs to pass the method’s arg, $source to pass the bound UI element, $dataContext to pass the corresponding DataContext, and so on. You can extend MessageBinder.SpecialValues to add more parsing rules; by default all special tokens start with $.

Message.Attach

The ActionMessage markup above was written as:

<Button>
    <i:Interaction.Triggers>
        <i:EventTrigger EventName="Click">
            <cm:ActionMessage MethodName="Show">
                <cm:Parameter Value="woo~"/>
            </cm:ActionMessage>
        </i:EventTrigger>
    </i:Interaction.Triggers>
</Button>

With the help of Blend’s Interaction, this wires the routed event Click to an ActionMessage. CM offers a more powerful Attach feature that lets you rewrite the code as:

<Button cm:Message.Attach="[Event Click] = [Action Show('woo~')]">

Message.Attach is an attached property defined by CM. CM parses the value of this property to generate the corresponding Action. To make parsing easier, CM defines a small syntax. For example, [Event Click] = [Action Show('woo~')] means: when the routed event Click occurs, execute the Show method with the argument woo~.

Special characters: square brackets [] denote an object; [Event Click] has a first parameter that says the object kind is Event and a second that names it Click; the equals sign = connects the Event to the ActionMessage; parentheses () hold the arguments. Semicolons separate multiple Event/ActionMessage pairs:

<Button cm:Message.Attach="[Event MouseEnter] = [Action Show('Enter')];
                           [Event MouseLeave] = [Action Show('Leave')]" />

This declares two Event/ActionMessage pairs.

When passing arguments inside parentheses you can use more than plain strings—you can also use bindings:

<TextBlock x:Name="txtBlock" Text="woo~"/>
<Button cm:Message.Attach="[Event Click] = [Action Show(txtBlock.Text)]">

Digging into Action

We have been talking about ActionMessage throughout; here is a detailed look at CM’s Action mechanism.

In short, Action means: when event A occurs, execute method C on object B.

ActionMessage inherits from TriggerAction<FrameworkElement>; TriggerAction comes from Blend’s Interactivity. When event A fires, ActionMessage’s Invoke method is called. Blend’s TriggerBase is not the focus of this article—only note that Blend guarantees the “event A” step.
When the ActionMessage is created, the MethodName property identifies method C. So the key to the whole ActionMessage is how to find object B.

The Caliburn.Micro framework is based on MVVM; if MVVM holds no interest for you, feel free to ignore Caliburn.Micro. In MVVM (Model-View-ViewModel), operations on the View are passed to the VM through Commands. Object B here is the ViewModel. CM represents the target object B as Target; by default, Target equals the control’s DataContext. CM provides the Action.Target attached property to set Target explicitly:

<ListBox x:Name="lstBox"  SelectionMode="Extended">
    <ListBoxItem>123</ListBoxItem>
    <ListBoxItem>123</ListBoxItem>
    <ListBoxItem>123</ListBoxItem>
</ListBox>
<Button cm:Action.Target="{Binding ElementName=lstBox}" Focusable="False"
        cm:Message.Attach="[Event Click] = [Action SelectAll]">

This sets the Action’s Target to the ListBox; when the Button is clicked, the ListBox’s SelectAll method is called.

Here cm:Action.Target is equivalent to DataContext="{Binding …}": when Target is set, CM also sets the control’s DataContext. Sometimes you do not want to change the control’s DataContext. For that, Action provides TargetWithoutContext, which sets Target without syncing the control’s DataContext.

During Action execution, ActionMessage supplies an ActionExecutionContext as the execution context. That context is mainly used by another important feature—coroutines—and will not be covered in detail here.

Summary

This article introduced CM’s Action mechanism. Action is a highlight of the CM design: concise and powerful. Around Action, CM also provides other features such as coroutines. I hope everyone will grasp Action solidly as the starting point for working with CM.

CODESYS AI Practice — Unit Testing

yohan — Sat, 31 Oct 2026 07:59:57 +0000

Environment: CODESYS V3.5 SP17 | SoftMotion Win 64 | Windows + PowerShell 5.1

The previous post, CODESYS AI Practice — Online Connection, downloaded the program into the soft PLC so we could start/stop it and read/write variables.

This post lets AI write unit tests for CODESYS.

The goal is a one-sentence ask: the AI writes the unit tests itself, imports the project, produces a red/green report, and so on. The approach also supports regression and other standard unit-testing scenarios.

Choosing an approach

Unit testing in CODESYS is not a new problem. Existing solutions fall into a few families:

Approach	What it tests	Simulation / real hardware	Cost
Host-side pytest driving read/write	Black-box interface	Either	Assertions sit far from the field; timing is nondeterministic
Matiec offline compile checks	Pure logic	No runtime connection	Does not cover axis control or online state
CoUnit / UniTest (library into the PLC)	White-box	Either	Requires installing a library; most community libraries are unmaintained
CODESYS Test Manager (3S)	White-box	Either	Commercial; often limited in OEM environments
Hand-rolled ST asserts + host collection	White-box	Either	You maintain the protocol; PLC side has zero dependencies

I settled on: assertions live with the logic; no PLC-side dependencies; host gets a unified result stream; design modeled on xunit.

How it works

Test code is ordinary ST. It compiles and downloads with the application. Assertions and the logic under test run in the same cycle over the same variables. The host only starts a round and reads results back.

A single round:

The suite is attached to a cyclic task via PRG_Tests.
Each case runs as Setup → assertions → TearDown.
Assertions write results into the case table in GVL_Test.
When all suites finish, a done flag is set.
The host polls the done flag, reads counts and cases, and generates a report.

xunit mapping

suite → an FB_<Unit>_Test function block
test → a Test_* method on the suite
assert → calls such as ass.AssertEquals_* / AssertTrue
fixture → Setup / TearDown plus the suite's VAR

Capabilities

Capability	Notes
Test organization	suite / test / assert / fixture
Assertions	Numeric, boolean, integer; `Skip` supported
Run targets	SoftMotion / Control Win, simulation and real hardware
Results	Text report, JUnit XML, exit codes
Continuous runs	Reset + read-back; multi-round runs
Targeting	`g_sFilter` for one suite; `g_sFirstFailure` for first failure
Dependencies	Zero on the PLC side; host reuses codesys-connect / codesys-sync

Caveats

Project, CODESYS, and run-target versions must match.
SoftMotion Win V3 x64 device type is 4102/0000 0004.
run only logs in; call download to load new logic.
PRG_Tests must sit on a cyclic task and g_uiSuitesTotal must match the suite count.
One Assert records one case.
Prefer incremental asserts on multi-round runs.
Never commit passwords; use -UserFile or environment variables.

CODESYS AI Practice — Online Connection

yohan — Sat, 31 Oct 2026 07:58:46 +0000

Environment: CODESYS V3.5 SP17 | SoftMotion Win 64 | Windows + PowerShell 5.1

The previous post, CODESYS AI Practice — Project Sync, solved “project ⇄ text ⇄ AI”, but the program still only lived in the project.

This post continues: let AI download the program to a soft PLC, start and stop it, and read and write variables.

Goal

One sentence: give AI an online channel into the controller.

Architecture

The path is: AI → Script Engine → soft PLC.

The AI plans actions. The script engine (IronPython inside CODESYS) executes them against the runtime. The soft PLC runs the application.

Capabilities

Step	What it does
Connect	Open an online session
Download	Load the compiled application
Start / Stop	Control run state
Read / Write	Access live variables

Notes

Download is a separate step from run
Variable paths follow the controller’s naming (GVL / program scope)
Simulation mode works without physical hardware

This is the online closed loop for the host/controller series.

CODESYS AI Practice — Import/Export Files

yohan — Sat, 31 Oct 2026 07:48:06 +0000

In CODESYS v3, code lives inside the project — a binary file. AI cannot open or edit it.

In the AI era we need a way for AI to operate on the files inside the project.

Goal

Close the loop: project ⇄ text ⇄ AI.

Export POUs to text, let the AI edit them, import them back into the project.

Constraints

CODESYS must stay the source of truth for the project structure
Import must not corrupt an existing project
Prefer a small, scriptable tool over a heavy IDE plugin

Approach

Export selected POUs (declaration + implementation) to plain text files
Edit the text (AI or human)
Import: backup, compare, write back, save

Creating or deleting POUs is not supported in this pass — only updating existing ones.

Import pipeline

Import does four things before touching the live project:

Backup — snapshot first
Compare — diff bodies
Write back — set POU code
Save — persist the project

Notes

Update only: creating or deleting POUs is not supported in this version
Declarations and implementations are paired per POU
After import, rebuild in CODESYS to verify

Repository and tooling details follow the same codesys-sync / codesys-connect series used elsewhere on this blog.

CODESYS AI Practice — Project Sync

yohan — Sat, 31 Oct 2026 07:47:06 +0000

Environment: CODESYS V3.5 SP17 / SP22 | Windows + PowerShell 5.1

The previous post, CODESYS AI Practice — Import/Export Files, closed the “project ⇄ text ⇄ AI” loop, but it was still a code-editing-only tool. This post completes the picture by turning it into a tool that operates on the project itself — CRUD for project objects.

Same approach as before.

What “project sync” means here

Export project objects (POUs, DUTs, GVLs) to text
Edit text (AI)
Import back into the project with safety rails

The loop is the same: export → edit → import → sync.

Beyond code edit

Earlier import/export only rewrote existing code bodies. This version can:

Create new objects
Delete objects
Rename objects
Sync declarations with implementations

…while still treating the CODESYS project as the single source of truth.

Safety

Backup before write-back
Diff before apply
Save after successful import

Summary

Project sync makes the text side a full peer of the binary project: AI can change structure, not only bodies — with the same export/edit/import discipline as the earlier posts in this series.

CODESYS Applied Practice — Axes (Part 1)

yohan — Sat, 31 Oct 2026 07:39:52 +0000

Environment: CODESYS V3.5 SP22 | Target: CODESYS Control Win V3 x64 simulation

Overview

The previous lesson built a minimal host/controller loop: three axes that were hand-rolled — FB_SimAxis parsed commands and climbed position itself. The motion was real; the axes were fake.

This lesson meets a real axis.

What is an axis?

Start from motion control. In short: an axis is the motion counterpart of a control object — setpoints and status on one side, drive + motor + encoder on the other, bound by mapping.

MC function blocks

Motion control FBs share a common timing shape: execute edge, busy, done, error.

CiA 402

Drives speak a state machine: Not ready to switch on → Switch on disabled → Ready to switch on → Switched on → Operation enabled.

Three boundaries

Motion API (MC_*)
Axis object (state + setpoints)
Drive profile (CiA 402 / fieldbus)

Same program, swap the backend

Names stay fixed; the implementation can be simulated or real.

Summary

Logical axis vs physical axis
Mapping binds them
MC timing is consistent across FBs
CiA 402 is the drive language
Same program can run on sim or hardware

CODESYS Applied Practice — Host/Controller Closed Loop

yohan — Sat, 31 Oct 2026 07:38:57 +0000

This post closes a practical loop: a minimal host/controller setup you can actually run.

Goal

Host PC talks to a soft PLC (CODESYS Control Win). The application exposes axes and variables. The host starts, stops, and exchanges data.

Pieces

Piece	Role
Host PC	UI / scripts
CODESYS runtime	Soft PLC
Application	PLC_PRG + axes

Device setup

Create a standard project, add SoftMotion Win (or Control Win), define the program and axis objects, then compile and download.

Simulated axes

The sample uses FB_SimAxis: the block parses commands and ramps position. The motion is real in the program; the “axis” is simulated. Good enough to prove the host/controller loop before touching hardware.

What you get

Download and start from the host
Read/write variables
A base for the later CODESYS AI and axes posts

This is the closed loop the rest of the CODESYS series builds on.

CODESYS Features — EtherCAT Firmware Update

yohan — Sat, 31 Oct 2026 07:31:27 +0000

This post explains how to update EtherCAT slave firmware in a CODESYS system.

Firmware

EtherCAT stations split into masters (controllers) and slaves (drives, and so on). Update methods differ.

Kind	How	Who runs it
Master application (`.app`)	IDE download, or replace the boot application	CODESYS runtime
Slave firmware	FoE / vendor tools over EtherCAT	Master + slave

FoE upgrade states

Idle → FoE connect → Transfer firmware → Checksum verify → Reboot / apply.

Three-party sequence

Master/IDE, controller, and slave coordinate the transfer and restart.

Controller-side state machine

IDLE → PREPARE → TRANSFER → VALIDATE → APPLY.

Notes

Match firmware to the exact slave model
Keep the bus stable during transfer
Plan for reboot: axes will drop until the slave returns

CODESYS Features — Download and Startup

yohan — Sat, 31 Oct 2026 07:30:37 +0000

Building CODESYS applications means download and start are unavoidable. This post digs one layer inward and walks the chain from compile to run.

You can also download and update from the command line without opening the CODESYS IDE.

The run chain

Compile

After the IDE compiles, you get two files:

File	What it is
`.app`	The application image: compiled target code
`.crc`	A small checksum file

Login vs Download

Login opens the online connection, compares the application signature, and builds an online-change plan.

Download transfers the .app via the gateway protocol on port 1217, writes the image into the controller, and applies the restart policy.

Controller startup

Boot → Runtime services → Select boot application → Start (enter RUN).

IDE download vs manual update

IDE download is for the development loop. Manual update (copy .app/.crc, set boot entry, restart) is for production field updates.