winui-dev-workflow

Create or Open a Project

New app — scaffold with a template:

dotnet new winui-mvvm -n <AppName>
cd <AppName>

Creates an MVVM project with CommunityToolkit.Mvvm, TitleBar, MicaBackdrop, and Frame navigation. Do NOT mkdir first — -n creates the folder.

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

Use the BuildAndRun.ps1 script (included with this skill) — it handles everything:

.\BuildAndRun.ps1

Invoke the script with mode: "async". The script stays attached to the running app so a mode: "sync" call blocks your turn for the entire lifetime of the app. The output contains the PID of the running app once the app starts, which looks like this:

✅ <pkg> launched (PID: 12345)

What the script does automatically:

1. Checks Developer Mode is enabled (fails fast if not)
2. Finds the .csproj in the current directory
3. Auto-detects platform (x64 or ARM64)
4. Builds with dotnet build (or Visual Studio MSBuild if you pass -UseMSBuild)
5. Finds the build output folder
6. Launches with winapp run --debug-output

Options:

.\BuildAndRun.ps1                          # auto-find csproj, build, run (should use async invocation)
.\BuildAndRun.ps1 MyApp.csproj             # explicit project
.\BuildAndRun.ps1 -Detach                  # run in detached mode, no debug output or exceptions (safe to use mode: "sync")
.\BuildAndRun.ps1 -SkipRun                 # build only (safe to use mode: "sync")
.\BuildAndRun.ps1 -Symbols                 # build + run, adding --symbols (optional Symbol Server fallback)
.\BuildAndRun.ps1 /p:Configuration=Release # override defaults

If build fails: Read ALL errors, batch-fix them in one pass, then run BuildAndRun.ps1 again.

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 BuildAndRun.ps1 default) runs a stowed-exception triage on crash, surfacing the real WinUI/XAML error behind an opaque 0x8000FFFF / E_FAIL — plus a fully symbolicated native dispatch stack (symbols auto-download, so --debug-output alone is enough). The first crash also downloads debugger components and can take a few minutes — it looks like a hang but it's caching; point WINAPP_DBGTOOLS_DIR at an existing Debugging Tools for Windows install to skip it. Later runs use the cache.

Common Errors

Prerequisites

If any of these are missing when you try to access them — winapp or dotnet not recognized, the WinUI templates aren't installed, Developer Mode is off — do not try to install them yourself and do not try to work around it. Stop and tell the user the prerequisite is missing and ask them to run /winui-setup (a user-invoked skill that installs and verifies everything). Once they've finished, retry the failed command.

Critical Rules

• ❌ NEVER run the packaged .exe directly — always use 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, handles build + run automatically