Skip to content

docs: add opt-in unpackaged WinUI run guidance #185

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Nikola Metulev (nmetulev) wants to merge 1 commit into
base: staging
Choose a base branch
from
Open

docs: add opt-in unpackaged WinUI run guidance #185

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 20 additions & 2 deletions plugins/winui/agent-plugin/skills/winui-dev-workflow/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<WindowsPackageType>None</WindowsPackageType>` 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.
Expand All @@ -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` |
Expand All @@ -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 `<WindowsPackageType>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)
3 changes: 2 additions & 1 deletion plugins/winui/agent-plugin/skills/winui-wpf-migration/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,8 @@ Delete custom `ObservableObject`/`RelayCommand`/`DelegateCommand`. Use Community
### Critical Rules

- ❌ NEVER reference `PresentationCore`, `PresentationFramework`, or `System.Windows.Controls` assemblies
- ❌ NEVER add `<UseWPF>true</UseWPF>` or `<WindowsPackageType>None</WindowsPackageType>`
- ❌ NEVER add `<UseWPF>true</UseWPF>`
- ❌ 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
Expand Down
Loading