Home › WPF / WinUI (Windows desktop) › WPF and WinUI desktop Copilot instructions

WPF and WinUI desktop Copilot instructions

Copilot instructions for Windows desktop apps in WPF or WinUI 3: MVVM with CommunityToolkit.Mvvm, async commands, DI hosting, binding, threading, and tests.

GitHub CopilotWPF / WinUI (Windows desktop)

Copy copilot-instructions.md

How to use

Save this as .github/copilot-instructions.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# Copilot instructions — WPF / WinUI 3 desktop app

## Commands
`dotnet build` · `dotnet test` · run the app project with `dotnet run --project src/<App>` (WinUI packaged apps may need Visual Studio; say if you couldn't run it).

## Architecture
- MVVM with `CommunityToolkit.Mvvm`: view models are `partial` classes deriving from `ObservableObject`, using `[ObservableProperty]` for bindable state and `[RelayCommand]` (async methods become `AsyncRelayCommand`) for actions.
- Views contain layout and bindings only. Code-behind is limited to view concerns (focus, animations); no business logic, service calls or data access there.
- Services (data, navigation, dialogs, settings) are interfaces registered in a `Microsoft.Extensions.Hosting` host at startup and injected into view models. No static service locators or singletons accessed directly.
- Navigation and dialogs go through services so view models stay testable without UI.

## Binding and UI
- WinUI: prefer `x:Bind` (compiled, typed) with `Mode=OneWay`/`TwoWay` set explicitly; default `x:Bind` is OneTime. WPF: `{Binding}` with a typed `d:DataContext` for designer support.
- Strings in resources (`.resw` for WinUI, `.resx` for WPF) for localization; no hardcoded user-facing text.
- Styles and colors in resource dictionaries; respect theme resources (light/dark/high contrast). Set `AutomationProperties.Name` on icon-only buttons.

## Threading
- Never block the UI thread: no `.Result`, `.Wait()` or synchronous IO in view models. Use `async`/`await` end to end with cancellation tokens for long operations.
- Update bound collections and properties on the UI thread (`DispatcherQueue.TryEnqueue` in WinUI, `Dispatcher.InvokeAsync` in WPF) when work completes on a background thread.
- Show progress/busy state via a bindable property; disable commands while running (`CanExecute`).

## Tests
Unit-test view models with mocked services (xUnit/NUnit + the repo's mocking library): property change notifications, command `CanExecute`, and error handling.