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