AGENT SKILL

winapp-troubleshoot

Diagnose Windows app packaging, signing, install, identity, and SDK errors: untrusted or mismatched certificates, Add-AppxPackage and 0x80073CFx install failures, no package identity, C++/WinRT headers not generated. Use when an MSIX won't install or build, or an error code appears.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1.4k
Forks
96

01 前言 Front Matter

name
winapp-troubleshoot
description
Diagnose Windows app packaging, signing, install, identity, and SDK errors: untrusted or mismatched certificates, Add-AppxPackage and 0x80073CFx install failures, no package identity, C++/WinRT headers not generated. Use when an MSIX won't install or build, or an error code appears.

03 SKILL.md 正文

If you can't run winapp yourself (no shell, or the command is denied), give the user the exact winapp command(s) for their project instead of only describing the steps.

When to use

Use this skill when:

  • Diagnosing errors from winapp CLI commands
  • Choosing the right command for a task
  • Understanding prerequisites — what each command needs and what it produces

Common errors & solutions

For slow WinUI layout or scrolling, use the winapp-performance skill. ETW performance capture is separate from debugger output and crash analysis.

Error Cause Solution
"winapp.yaml not found" Running restore or update without config Run winapp init first, or cd to the directory containing winapp.yaml
"Package.appxmanifest not found" Running package, create-debug-identity, or cert generate --manifest Run winapp init or winapp manifest generate first, or pass --manifest <path>
"Publisher mismatch" Certificate publisher ≠ manifest publisher Regenerate cert: winapp cert generate --manifest, or edit Package.appxmanifest Identity.Publisher to match
"Access denied" / "elevation required" cert install without admin Run terminal as Administrator for winapp cert install
"Package installation failed" Cert not trusted, or stale package registration For a certificate error, winapp cert install ./devcert.pfx (admin). For registration conflicts, see the rows below rather than deleting packages by name
"Certificate not trusted" Dev cert not installed on machine winapp cert install ./devcert.pfx (admin)
"Build tools not found" First run, tools not yet downloaded Run winapp update to download tools; ensure internet access
"Failed to add package identity" Stale debug identity or untrusted cert Run winapp unregister with your app's input (or --manifest for create-debug-identity); install a certificate only if the error asks for it
"Certificate file already exists" devcert.pfx already present Use winapp cert generate --if-exists overwrite or --if-exists skip
"Manifest already exists" Package.appxmanifest already present Use winapp manifest generate --if-exists overwrite or edit manifest directly
run / create-debug-identity registration error 0x800704EC Developer Mode is disabled Enable it in Settings → Privacy & security → For developers, or Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Name AllowDevelopmentWithoutDevLicense -Value 1, then retry
Two worktrees of the same app keep replacing each other's registration Both copies share one package identity Run each with winapp run . --unique-identity (supported packaged apps) so each gets its own identity and app data
run / create-debug-identity registration error 0x80073CFB Package already registered with a conflicting identity Run winapp unregister with your app's input, then retry. Use --force only if you are sure the same-named package registered elsewhere is yours
App's Start menu entry launches nothing, silently Package still registered after its files were deleted Run winapp unregister --prune to remove every dev registration whose files are gone
run reports access denied or a file in use during a rebuild Permissions or a file held open; access denied alone does not identify a lock owner Check the reported paths and permissions. winapp run closes a copy of the app running from the same layout before replacing its files; close any other process holding the file and retry.
"winapp can't write the API index" / "can't install the Microsoft Store Developer CLI" %USERPROFILE%\.winapp isn't writable (for example, an agent sandbox) Set WINAPP_CLI_CACHE_DIRECTORY to a writable folder, such as one inside the project, and retry. Other commands keep working without it

For --unique-identity errors about unsupported extensions or resources, see unique identity for parallel checkouts. Run without the flag instead of working around the check.

Command selection guide

Is the app a single .cs file (.NET file-based app)?
├─ Yes → winapp run <file>.cs  (builds it and generates the manifest for you)
└─ No → Does the project have a Package.appxmanifest?
   ├─ No → Do you want full setup (manifest + config + optional SDKs)?
   │       ├─ Yes → winapp init (adds Windows platform files to existing project)
   │       └─ No, just a manifest → winapp manifest generate
   └─ Yes
      ├─ Has winapp.yaml, cloned/pulled but .winapp/ folder missing?
      │  └─ winapp restore
      ├─ Want newer SDK versions?
      │  └─ winapp update
      ├─ Need a dev certificate?
      │  └─ winapp cert generate (then winapp cert install for trust)
      ├─ Need package identity for debugging? (see [Debugging Guide](https://github.com/microsoft/WinAppCli/blob/main/docs/debugging.md))
      │  ├─ Exe is in your build output folder? (most frameworks)
      │  │  └─ winapp run <build-output-dir>
      │  └─ Exe is separate from app code? (Electron, sparse testing)
      │     └─ winapp create-debug-identity <exe>
      ├─ Ready to create MSIX installer?
      │  └─ winapp package <build-output> --cert ./devcert.pfx
      ├─ Need to sign an existing file?
      │  └─ winapp sign <file> <cert>
      ├─ Need to update app icons?
      │  └─ winapp manifest update-assets ./logo.png
      ├─ Need to run SDK tools directly?
      │  └─ winapp tool <toolname> <args>
      ├─ Need to publish to Microsoft Store?
      │  └─ winapp store <args> (passthrough to Store Developer CLI)
      └─ Need the .winapp directory path for build scripts?
         └─ winapp get-winapp-path (or --global for shared cache)

Important notes:

  • winapp init adds files to an existing project — it does not create a new project
  • The key prerequisite for most commands is Package.appxmanifest, not winapp.yaml
  • winapp.yaml is only needed for SDK version management (restore/update)
  • Projects with NuGet package references (e.g., .csproj referencing Microsoft.Windows.SDK.BuildTools) can use winapp commands without winapp.yaml
  • For Electron projects, use the npm package (npm install --save-dev @microsoft/winappcli) which includes Node.js-specific commands under npx winapp node

Debugging approach quick reference

Goal Command Key detail
Run with identity (most common) winapp run .\build\Debug Registers loose layout + launches; a console app gets an execution alias automatically
Attach debugger to running app winapp run .\build\Debug → attach to PID Misses startup code
Register identity, launch manually winapp run .\build\Debug --no-launch Launch via start shell:AppsFolder\<AUMID> or execution alias — not the exe directly
F5 startup debugging (IDE launches exe) winapp create-debug-identity .\bin\myapp.exe Exe has identity regardless of how it's launched; best for debugging activation/startup code
Capture OutputDebugString + crash dump winapp run .\build\Debug --debug-output On crash, writes minidump and shows exception type, message, and faulting methods. Blocks other debuggers — use --no-launch if you need VS Code/WinDbg
Run and auto-clean winapp run .\build\Debug --unregister-on-exit Unregisters the dev package after the app exits
Launch and detach (CI) winapp run .\build\Debug --detach Returns immediately after launch; use --json to get PID for scripting
Clean up this app's registration winapp unregister . Pass the same input as run; works with or without --unique-identity
Start menu entry does nothing when clicked winapp unregister --prune The package is registered but its files were deleted, so activation silently fails. Prune removes every dev registration whose files are gone

Visual Studio users: If you have a packaging project, VS already handles identity and debugging from F5 — you likely don't need winapp for debugging. These workflows are for VS Code, terminal, and frameworks VS doesn't natively package.

For full details, see the Debugging Guide.

Prerequisites & state matrix

Command Requires Creates/Modifies
init Existing project (any framework) winapp.yaml, .winapp/, Package.appxmanifest, Assets/, .gitignore update
restore winapp.yaml .winapp/packages/, generated projections
update winapp.yaml Updates versions in winapp.yaml, reinstalls packages
manifest generate Nothing Package.appxmanifest, Assets/
manifest update-assets Package.appxmanifest + source image Regenerates Assets/ icons
cert generate Nothing (or Package.appxmanifest for publisher) devcert.pfx
cert install Certificate file + admin Machine certificate store
create-debug-identity Package.appxmanifest + exe + trusted cert Registers sparse package with Windows
run Build output folder + Package.appxmanifest; or a .csproj/.vcxproj/.sln (C++ needs Visual Studio or Build Tools with the C++ workload); or a .cs file-based app (no manifest needed — one is generated) Registers loose layout package, launches app
unregister The same input passed to run (.cs, .csproj/.vcxproj, or folder), or --manifest Removes the development registration that run or create-debug-identity created
package Build output + Package.appxmanifest .msix file
sign File + certificate Signed file (in-place)
create-external-catalog Directory with executables CodeIntegrityExternal.cat
tool <name> Nothing (auto-downloads tools) Runs SDK tool directly
store Nothing (auto-downloads Store CLI) Passthrough to Microsoft Store Developer CLI
get-winapp-path Nothing Prints .winapp directory path

Debugging tips

  • Add --verbose (or -v) to any command for detailed output
  • Add --quiet (or -q) to suppress progress messages (useful in CI/CD)
  • Run winapp --cli-schema to get the full JSON schema of all commands and options
  • Run any command with --help for its specific usage information
  • Use winapp get-winapp-path to find where packages are stored locally
  • Use winapp get-winapp-path --global to find the shared cache location

Getting more help

Related skills

  • Setup & init: winapp-setup — adding Windows support to a project
  • Manifest: winapp-manifest — creating and editing Package.appxmanifest
  • Signing: winapp-signing — certificate generation and management
  • Packaging: winapp-package — creating MSIX installers
  • Identity: winapp-identity — enabling package identity for Windows APIs
  • Frameworks: winapp-frameworks — framework-specific guidance (Electron, .NET, C++, Rust, Flutter, Tauri)
  • MAUI: winapp-maui — packaging/signing .NET MAUI Windows apps and resolving the resizetizer manifest

CLI reference

Run winapp <command> --help for current command options, or winapp --cli-schema for the complete machine-readable command schema.

04 同仓库更多 Skills

microsoft
microsoft/winappCli

winui-wpf-migration

Migrate or port a WPF app to WinUI 3: namespaces (System.Windows to Microsoft.UI.Xaml), control mapping (DataGrid, WrapPanel, TabControl), Dispatcher to DispatcherQueue, imaging, MVVM with CommunityToolkit.Mvvm, ThemeResource. Use when converting WPF code or fixing migration build errors.

★ 1.4k
microsoft
microsoft/winappCli

winui-ui-testing

Write and run automated UI tests for Windows desktop apps (WinUI 3, WPF, WinForms, Win32) with the winapp ui harness: one batch script, assertions, input, file pickers, dialogs, screenshots, locally or in Windows Sandbox. Use when asked for UI tests or to verify a feature end to end.

设计师测试与质量
★ 1.4k
microsoft
microsoft/winappCli

winui-setup

Install and verify WinUI 3 prerequisites — .NET SDK 8.0.100+, WinApp CLI 0.7+, and Developer Mode; identify additional Native AOT and Windows Sandbox requirements. Use when the user asks to set up or repair the toolchain, or when another WinUI skill finds a missing or outdated prerequisite.

开发工程师
★ 1.4k
microsoft
microsoft/winappCli

winui-packaging

MSIX packaging, signing, and Microsoft Store publishing for WinUI 3 apps with WinApp CLI 0.7+: project packaging, Native AOT, certificates, self-contained deployment, CI/CD. Use when releasing or publishing a WinUI app. Not for WPF, WinForms, or Electron apps that only reference the Windows App SDK.

运维与部署
★ 1.4k
microsoft
microsoft/winappCli

winui-dev-workflow

Create, build, run, and fix build errors in WinUI 3 apps (C# or C++) with WinApp CLI 0.7+: winapp new, winapp run, Native AOT, crash diagnosis. Use for a new WinUI app or a WinUI project that fails to build or crashes. Not for WPF, WinForms, or Electron apps that only reference the Windows App SDK.

★ 1.4k
microsoft
microsoft/winappCli

winui-design

Read before writing or changing WinUI 3 XAML: choosing controls, pages and navigation, layout, Fluent Design, theming, accessibility, x:Bind, real samples, and checking that APIs exist with winapp find-api. Not for WPF or WinForms UI, even if the app uses the Windows App SDK.

设计师内容创作者视觉设计写作与文案
★ 1.4k