C# and WinUI

The code is right when it builds with zero warnings, launches without a CRASH line, and the app does what the story says. For how it should look, call the Skill tool with windows-design. For copyable XAML, read ../../design/windows-design/patterns.md.

Threads

WinUI has one UI thread per window. Every control and every object bound to a control lives on it.

• await in an event handler returns to the UI thread on its own. Inside Task.Run you are on a pool thread: never touch a control there.
• async void only for event handlers. Everything else returns Task.
• Keep the DispatcherQueue of the window (window.DispatcherQueue) for code that runs outside a page.
• A crash on a background thread kills the app with no CRASH line from UnhandledException. Catch and log in every Task.Run body you start and forget, and run every background path once after changing it.

State

• Models are partial class X : ObservableObject with [ObservableProperty] public partial string Title { get; set; } (CommunityToolkit.Mvvm 8.4 and C# 14). Initialize partial properties in the constructor: they cannot have initializers.
• [NotifyPropertyChangedFor(nameof(DisplayTitle))] for computed properties.
• Lists bind to an ObservableCollection<T>. Rebuild it in place (Clear, Add), never assign a new collection to a bound property.
• x:Bind is compiled and checked, so prefer it over {Binding}. Its default mode is OneTime: write Mode=OneWay for anything that changes and Mode=TwoWay for inputs, and UpdateSourceTrigger=PropertyChanged on a TextBox that saves as you type.
• After changing the object a page binds through (Model.Selection), call Bindings.Update() if the binding path starts above the changed object.
• JSON goes through source generation: add each saved type to AppJson ([JsonSerializable(typeof(T))]) and pass AppJson.Default.T. Reflection JSON breaks under NativeAOT and trimming (IL2026, IL3050).
• Small preferences go in Prefs (JSON next to the database). Unpackaged apps have no ApplicationData.Current.LocalSettings: it throws. Secrets go in the Windows Credential Locker (PasswordVault) or DPAPI (ProtectedData), never in the JSON.
• A property set to the value it already has fires no change. Fill lists in the constructor too, not only in OnXChanged.

SQLite

• One SqliteConnection per app, opened once, WAL mode, in <App>.Core.
• Schema changes are new steps in ItemStore.Migrations, keyed by PRAGMA user_version. Never edit a step that shipped. A new column has a DEFAULT, so old files keep loading.
• Every row has a Guid id. Never use the row number or list index as an identity.
• APP_STORE overrides the path, and the app refuses test modes unless it points into %TEMP%. Tests never touch %LOCALAPPDATA%\<App>\<App>.db.
• Undo: keep the deleted model in memory and save it back. SQLite has no undo of its own across commits.
• Several processes on one file (a CLI, a second instance): send commands to the running app instead (agent-cli), so the file keeps one writer.

Commands and keys

• Every command is a button or menu item with a KeyboardAccelerator. The accelerator works wherever focus is in the window.
• Keys that also mean something while typing (Delete, Backspace, arrows, Enter, plain letters) are scoped: ScopeOwner="{x:Bind List}", and set args.Handled = true in Invoked.
• Flyout and context menu items are not in the visual tree: they get no DataContext. Pass the row with Tag="{x:Bind}".

Names that collide

Window, Page, Frame, Layout, Path, Rectangle, Grid, Color, Colors, Thickness, Point, Size, and Application all exist in WinUI namespaces. Do not name your own types after them. Path collides with System.IO.Path as soon as a file imports Microsoft.UI.Xaml.Shapes: write System.IO.Path. Task collides with System.Threading.Tasks.Task: name a to-do Todo or TaskItem.

Namespaces collide too, and worse. C# looks for a name in the enclosing namespaces before the using lines. A namespace MyApp.Features.Windows makes Windows.Foundation mean MyApp.Features.Windows.Foundation in every sibling namespace (CS0234); MyApp.Features.Clipboard hides the WinRT Clipboard class; Colors and Launcher do the same. Each feature compiles alone, and the break shows only when two are merged. Never name a namespace segment Windows, Microsoft, System, or after a type you call (Clipboard, Colors, Launcher): use Snapping, ClipboardHistory, Palette, AppLauncher.

Win32 interop

WinUI covers windows, pages, and controls. Win32 is still the answer for:

• The window handle: WinRT.Interop.WindowNative.GetWindowHandle(window).
• Pickers and dialogs from WinRT (FileOpenPicker, FolderPicker): WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd), or they throw.
• DPI: GetDpiForWindow. AppWindow sizes are physical pixels; XAML is in epx. The template's WindowBehavior scales between them.
• Global hotkeys, the tray icon, hooks, other apps' windows: call the Skill tool with os-integrations.

Declare calls with [LibraryImport] in one Win32.cs, with AllowUnsafeBlocks on. Keep every P/Invoke in that file. Callbacks (window procedures, hooks, EnumDisplayMonitors) are [UnmanagedCallersOnly] static methods passed as &Method; catch every exception inside them, because one that escapes ends the process. Keep unsafe to the block that takes the address: a class marked unsafe cannot await anywhere (CS4004).

UI built in code

Building controls in C# is fine, with three traps:

• Theme brushes. Application.Current.Resources["TextFillColorSecondaryBrush"] returns the brush for the app's theme, not the theme of the element it lands in. A panel or page set to dark (RequestedTheme, Settings' theme choice, snapshot mode) then shows light text on dark or dark on dark. Give code-built elements a Style from XAML whose setters use {ThemeResource ...}, or build the part as a XAML UserControl.
• Measuring before the window shows. Measure on code-built content before it is in a shown window gets heights wrong (templates are not applied yet). Size a panel to its content after the first layout: in SizeChanged, or one DispatcherQueue turn after showing it.
• Property order in initializers. new TextBox { Text = s, AcceptsReturn = true } keeps only the first line of s: Text is set while AcceptsReturn is still false. Set AcceptsReturn (and TextWrapping) first.

Events fire when code sets a value, not only when a person does: ToggleSwitch.Toggled runs when you set IsOn to show the current state, and TextBox.TextChanged runs later, after Text is set. Guard handlers with a _loading flag while a page fills itself, and in a self-test call the search or filter function directly instead of waiting for TextChanged.

Glyphs in source

Segoe Fluent Icons glyphs are private-use characters that show as nothing in an editor or a diff. Write them as code points: char.ConvertFromUtf32(0xE734) in C#,  in XAML. Never paste the character itself.

Build and launch errors

Fix the first error first. Later errors often come from it.

Done when the app builds with zero warnings, the self-test passes, and the story's acceptance checks pass.