winui-dev-workflow

Create or Open a Project

New app — let WinApp CLI install/update the official templates and scaffold:

winapp new --name <AppName> --template winui-mvvm --template-version latest --use-defaults
cd <AppName>

Run winapp new --list to discover the currently installed template short names. Do not install the template pack separately and do not create the output directory first.

Existing app — read the .csproj to understand:

• <TargetFramework> (e.g., net10.0-windows10.0.26100.0)
• <PackageReference> versions (WindowsAppSDK, CommunityToolkit)
• Project structure and established patterns

Install Packages

dotnet add package <Name>

Never specify --version — omitting it gets the latest stable and avoids outdated API mismatches.

Build & Run

WinApp CLI 0.6+ builds a .csproj and launches it directly:

winapp run . --debug-output
winapp run .\MyApp.csproj -c Release --arch arm64

For normal development, prefer the included BuildAndRun.ps1 wrapper. It invokes project-mode winapp run, injects the bundled Microsoft.WindowsAppSDK.Analyzers, and turns on --debug-output by default:

.\BuildAndRun.ps1

Invoke attached runs with mode: "async". The command stays attached while the app is open, so a synchronous call blocks for the app's lifetime. The output contains the running app's PID.

The wrapper only adds repository-specific analyzer and debug defaults. WinApp CLI handles:

1. Project restore and build
2. Configuration, architecture, runtime, and framework selection
3. Packaged versus unpackaged detection
4. Build-output and executable discovery
5. Windows App Runtime setup
6. Package registration and launch

Options and forwarded WinApp arguments:

.\BuildAndRun.ps1                              # one top-level csproj; attached diagnostics
.\BuildAndRun.ps1 .\MyApp.csproj               # explicit project
.\BuildAndRun.ps1 .\MyApp.csproj -c Release    # forwarded to winapp run
.\BuildAndRun.ps1 .\MyApp.csproj --arch arm64  # forwarded to winapp run
.\BuildAndRun.ps1 . --detach --json             # return after launch; emit PID as JSON
.\BuildAndRun.ps1 . --symbols                   # add Symbol Server-backed native symbols
.\BuildAndRun.ps1 --args "--flag value"         # pass application arguments

The wrapper accepts the same .csproj, .sln/.slnx, directory, and --project inputs as winapp run.

If build fails: Read all errors, batch-fix them in one pass, then rerun the same command.

If the app crashes on launch: read_powershell the shell — first-chance exceptions appear in the output. See the crash-diagnosis section below for WinUI stowed-exception triage.

Diagnosing Crashes with winapp run

For WinUI apps, --debug-output (the wrapper default) runs a stowed-exception triage on crash, surfacing the real WinUI/XAML error behind an opaque 0x8000FFFF / E_FAIL. The first crash downloads debugger components and can take a few minutes; point WINAPP_DBGTOOLS_DIR at an existing Debugging Tools for Windows install for offline/locked-down environments. Add --symbols for richer native frames.

Common Errors

Prerequisites

If winapp/dotnet is missing or too old, or Developer Mode is off, do not install it ad hoc or work around it. Ask the user to run /winui-setup, then retry. winapp new manages the WinUI template pack itself.

Critical Rules

• ❌ NEVER run the packaged .exe directly — always use project-mode winapp run or BuildAndRun.ps1
• ❌ NEVER add <WindowsPackageType>None to work around launch issues
• ❌ NEVER delete Package.appxmanifest
• ❌ NEVER use AnyCPU — always x64 or ARM64

References

• BuildAndRun.ps1 — included with this skill; adds the bundled analyzer and diagnostic defaults to winapp run