From d1226689a0889e4c04349825740983cd118a7a90 Mon Sep 17 00:00:00 2001 From: Nikola Metulev <711864+nmetulev@users.noreply.github.com> Date: Fri, 18 Sep 2026 17:48:44 -0700 Subject: [PATCH] docs: add opt-in unpackaged WinUI run guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 2 ++ .../skills/winui-dev-workflow/SKILL.md | 22 +++++++++++++++++-- .../skills/winui-wpf-migration/SKILL.md | 3 ++- 3 files changed, 24 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0932e953..d9bacba9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,8 @@ The `version-bump` and `changelog-entry` CI jobs enforce this. ### Added +- Added opt-in unpackaged WinUI run guidance and package-identity troubleshooting. + ### Changed ### Fixed diff --git a/plugins/winui/agent-plugin/skills/winui-dev-workflow/SKILL.md b/plugins/winui/agent-plugin/skills/winui-dev-workflow/SKILL.md index bf745f0a..bb19d272 100644 --- a/plugins/winui/agent-plugin/skills/winui-dev-workflow/SKILL.md +++ b/plugins/winui/agent-plugin/skills/winui-dev-workflow/SKILL.md @@ -66,6 +66,22 @@ The wrapper accepts the same `.csproj`, `.sln`/`.slnx`, directory, and `--projec **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. +### Run Unpackaged (Opt-In Only) + +**Packaged is the default.** Use unpackaged only when the user asks or for targeted debugging, not as a routine workaround. + +Set `None` in the `.csproj`, keep `Package.appxmanifest`, then run (use `arm64` when appropriate): + +```powershell +winapp run .\MyApp.csproj --arch x64 --debug-output +``` + +Framework-dependent apps still need the Windows App Runtime. Package-identity-dependent APIs can fail at startup; see `0x80073D54` below. + +For Sandbox (CLI support required), replace `--debug-output` with `--on sandbox`; unpackaged debug capture is unavailable. Reproduce locally only with user approval. + +After temporary debugging, restore the original packaging setting and verify the packaged run. + ### 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. @@ -80,8 +96,9 @@ For WinUI apps, `--debug-output` (the wrapper default) runs a **stowed-exception | 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 silently exits | Use `winapp run . --debug-output`, not the .exe directly; see the Sandbox limitation above | | 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 | +| `0x80073D54` / "The process has no package identity" | A package-dependent API (e.g., `Windows.Storage.ApplicationData.Current`) needs adaptation for unpackaged use; otherwise restore packaged mode | | 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` | @@ -102,10 +119,11 @@ If `winapp`/`dotnet` is missing or too old, or Developer Mode is off, **do not i ### Critical Rules - ❌ NEVER run the packaged .exe directly — always use project-mode `winapp run` or `BuildAndRun.ps1` -- ❌ NEVER add `None` to work around launch issues +- ❌ NEVER switch to unpackaged outside the [opt-in workflow](#run-unpackaged-opt-in-only) - ❌ 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` +- [Windows App SDK deployment guide for unpackaged apps](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/deploy-unpackaged-apps) diff --git a/plugins/winui/agent-plugin/skills/winui-wpf-migration/SKILL.md b/plugins/winui/agent-plugin/skills/winui-wpf-migration/SKILL.md index 0769b87c..2f8cddbd 100644 --- a/plugins/winui/agent-plugin/skills/winui-wpf-migration/SKILL.md +++ b/plugins/winui/agent-plugin/skills/winui-wpf-migration/SKILL.md @@ -75,7 +75,8 @@ Delete custom `ObservableObject`/`RelayCommand`/`DelegateCommand`. Use Community ### Critical Rules - ❌ NEVER reference `PresentationCore`, `PresentationFramework`, or `System.Windows.Controls` assemblies -- ❌ NEVER add `true` or `None` +- ❌ NEVER add `true` +- ❌ NEVER switch to unpackaged outside the [opt-in workflow](../winui-dev-workflow/SKILL.md#run-unpackaged-opt-in-only) - ❌ NEVER delete `Package.appxmanifest` - ❌ NEVER overwrite `App.xaml` / `App.xaml.cs` — merge WPF code into the WinUI 3 boilerplate - ✅ Always use `winapp run` to launch — never run the .exe directly