winui-dev-workflow
Build and run workflow for WinUI 3 apps with WinApp CLI 0.6+ — project creation with winapp new, project-mode winapp run, BuildAndRun.ps1 analyzer integration, crash diagnosis, and prerequisites. Use when creating, building, running, or fixing build errors in a WinUI 3 project.
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:
- Project restore and build
- Configuration, architecture, runtime, and framework selection
- Packaged versus unpackaged detection
- Build-output and executable discovery
- Windows App Runtime setup
- 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
| Error | Fix |
|---|---|
| Developer Mode not enabled | Settings → System → For developers → On |
| CS0234/CS0246 missing type | Add using or dotnet add package |
| NETSDK1136 platform required | Target a Windows TFM (for example net10.0-windows10.0.26100.0); use -f <windows-tfm> when the project already multi-targets |
| 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 is optional |
| 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 | Check the manifest publisher and Developer Mode; apps from winapp new need no separate winapp init |
| 0x80073CF9 / "Failed to reach state Staged" on a deeply nested project | For a packaged app, rerun with --output-appx-directory "$env:LOCALAPPDATA\winapp-layout\<app>-<config>-<arch>", or move the repo closer to the drive root. Keep the directory unique per configuration and architecture — a registered development package holds a live reference to it, so Debug and Release must not share one — and empty it before reuse so payload files dropped since the last build do not linger |
| 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.100 | 10.0 | winget install Microsoft.DotNet.SDK.10 |
| WinApp CLI | 0.6.0 | latest | /winui-setup |
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 runorBuildAndRun.ps1 - ❌ NEVER add
<WindowsPackageType>Noneto 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 towinapp run
microsoft/win-dev-skills · MIT · Revision f94bab12f67f
Be the first to comment
Share what worked or leave a question for the creator.