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, implementTitle, and overrideNavGroupto 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]fromCommunityToolkit.Mvvm; never hand-writeINotifyPropertyChanged; - 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:
TreatWarningsAsErrorsis 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 containsInitializeComponent()and nothing else; - Font sizes and weights come from the keys in
Themes/Shell.xaml(UiFontSizeTitle/UiFontSize/UiFontSizeSmall/UiFontSizeCaption; use thePageTitlestyle for page titles andReadoutfor 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 ownWindowChrome.
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
MessageBoxin the ViewModel (dialogs go throughIShellDialogService) - 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 --shotrun, screenshots reviewed