Skip to content
PreciSim
source-guide

Adding a page

Add a device debug page from scratch and walk the full MVVM convention.

This chapter walks the MVVM conventions through one real task: adding a "nozzle vacuum debug" page. One page = one View + one ViewModel. Two files, no more.

1. ViewModel

// 07.PreciSim.App/ViewModels/VacuumDebugViewModel.cs
public sealed partial class VacuumDebugViewModel : PageViewModel
{
    private readonly DeviceService _devices;
    private readonly IPermissionGuard _guard;
 
    [ObservableProperty] private bool _vacuumOn;
    [ObservableProperty] private string _message = "";
 
    public VacuumDebugViewModel(DeviceService devices, IPermissionGuard guard)
    {
        ArgumentNullException.ThrowIfNull(devices);
        ArgumentNullException.ThrowIfNull(guard);
        _devices = devices;
        _guard = guard;
    }
 
    public override string Title => "Vacuum debug";
 
    public override string NavGroup => "Debug";    // sidebar group; order in MainViewModel.NavGroupOrder
 
    [RelayCommand]
    private async Task ToggleVacuumAsync(CancellationToken ct)
    {
        _guard.Demand(UserRole.Engineer);          // permission is checked at the command entry, not on the button
        await _devices.Devices.Io.WriteAsync("VacuumValve", !VacuumOn);
        VacuumOn = !VacuumOn;
    }
 
    public override Task OnActivatedAsync()        // page brought to front; OnDeactivatedAsync when it leaves
        => RefreshAsync();
}

Key points:

  • Derive from PageViewModel, implement Title, and override NavGroup to put it in one of the sidebar groups (Run / Manual / Vision / Calibration / Settings / Records);
  • There are no "virtual-device only" pages: the HMI does not know whether it is talking to the virtual device or a real machine. The stage view, fault injection and truth comparison live in the virtual device engine's own console;
  • Use [ObservableProperty] / [RelayCommand] from CommunityToolkit.Mvvm; never hand-write INotifyPropertyChanged;
  • A ViewModel never news up a device and never holds business logic — devices come through DeviceService, logic lives in the service layer;
  • Public types and members need XML comments: TreatWarningsAsErrors is on, so a missing one fails the build.

2. View

<!-- 07.PreciSim.App/Views/VacuumDebugView.xaml -->
<UserControl x:Class="PreciSim.App.Views.VacuumDebugView"
             xmlns:vm="clr-namespace:PreciSim.App.ViewModels"
             d:DataContext="{d:DesignInstance vm:VacuumDebugViewModel}">
  <StackPanel Margin="16">
    <ToggleButton Content="Vacuum"
                  IsChecked="{Binding VacuumOn, Mode=OneWay}"
                  Command="{Binding ToggleVacuumCommand}" />
    <TextBlock Text="{Binding Message}" />
  </StackPanel>
</UserControl>

Key points:

  • Standard {Binding} only — no binding DSL; code-behind contains InitializeComponent() and nothing else;
  • Font sizes and weights come from the keys in Themes/Shell.xaml (UiFontSizeTitle / UiFontSize / UiFontSizeSmall / UiFontSizeCaption; use the PageTitle style for page titles and Readout for large numbers); never write a literal font size in XAML. Colours always use theme keys (Bg2 / Fg / Accent …) — the dark and light colour dictionaries share the same key names;
  • Standalone windows (as opposed to pages) always derive from AppWindow. The dark title bar is custom-drawn in one place — do not write your own WindowChrome.

3. Registration

// 07.PreciSim.App/App.xaml.cs — DI
sc.AddSingleton<VacuumDebugViewModel>();
<!-- 07.PreciSim.App/App.xaml — ViewModel to View mapping -->
<DataTemplate DataType="{x:Type vm:VacuumDebugViewModel}">
    <v:VacuumDebugView />
</DataTemplate>
// 07.PreciSim.App/ViewModels/MainViewModel.cs — one more constructor parameter, then add it to the page list
public MainViewModel(..., VacuumDebugViewModel vacuum)
{
    foreach (var p in new PageViewModel[] { dashboard, jog, io, vacuum, /* … */ }) Pages.Add(p);
}

The sidebar groups pages by NavGroup automatically; there is no separate registry.

4. Navigation (there is no top menu)

The sidebar is the only navigation: there is no top menu bar and no greyed-out "coming later" items. Exit / switch user / about live in the user menu at the top right of the title bar; calibration wizards are opened from the "Run wizard" buttons on the Calibration view page.

5. UI text

UI text is currently Chinese string literals in the source, with no resource files — this HMI is single-language. Making it multilingual is a separate piece of work; do not build half of it into a page along the way.

6. Run the smoke test

dotnet build PreciSim.sln -c Release
dotnet run --project src/07.PreciSim.App -- --smoke --shot

--smoke loads every page, the login window and each calibration wizard in turn; --shot also saves a PNG of each window to out/ui/. XAML that compiles and bindings that do not throw do not mean it looks right — scanning the screenshots is far faster than clicking through.

Checklist

  • No MessageBox in the ViewModel (dialogs go through IShellDialogService)
  • No devices constructed inside the ViewModel
  • View code-behind contains only InitializeComponent()
  • No literal font sizes in XAML
  • XML comments on every public member (Release build fails otherwise)
  • --smoke --shot run, screenshots reviewed
Last updated: Sep 23, 2026
Was this page helpful?