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

Error	Fix
Developer Mode not enabled	Settings → System → For developers → On
CS0234/CS0246 missing type	Add using or dotnet add package
NETSDK1136 platform required	BuildAndRun.ps1 handles this automatically
XLS0414 XAML type not found	Add xmlns declaration
XDG0062 binding path missing	Check x:Bind property exists on ViewModel
Blank window after launch	x:Bind defaults to OneTime — add Mode=OneWay
App silently exits	Use winapp run, never run the .exe directly
App crashes with opaque 0x8000FFFF / E_FAIL	Run under --debug-output (BuildAndRun.ps1 default) — WinUI stowed-exception triage surfaces the real XAML error + symbolicated native stack. -Symbols optional, not required
XAML compiler crashes silently	Remove any PresentationCore.dll / System.Windows references
MSB3073 / XamlCompiler.exe ... exited with code 1, no .xaml named	Old WindowsAppSDK XAML-compiler bug — update Microsoft.WindowsAppSDK NuGet to latest (≥ 2.1.3, or ≥ 1.8 on the 1.x line)
0x80073CF6 package install failed	Run winapp init, check manifest publisher matches cert
0x8007000B bad image format	Wrong platform target — use x64 or ARM64, not AnyCPU

Prerequisites

Requirement	Minimum	Recommended (fresh installs)	Install command
Windows 10 v1903+	—	—	—
Developer Mode	enabled	enabled	Settings → Advanced → Developer Mode → On
.NET SDK	8.0	10.0	winget install Microsoft.DotNet.SDK.10
winapp CLI	0.3	latest	winget install Microsoft.WinAppCLI
WinUI templates	any	latest	dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates

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