winapp-identity

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:

Running packaged worktrees side by side — opt into winapp run --unique-identity
The exe is separate from your app code — e.g., Electron apps where electron.exe is in node_modules, not your build output
Testing sparse package behavior specifically — AllowExternalContent, TrustedLaunch, etc.
Registering identity without copying files — create-debug-identity leaves the exe in place

Prefer winapp run for most frameworks. If your exe is inside your build output folder (.NET, C++, Rust, Flutter, Tauri), use winapp run <build-output> instead — it registers a full loose layout package and launches the app, simulating an MSIX install. Use create-debug-identity only when winapp run doesn't fit your scenario.

Parallel packaged worktrees

winapp run . --unique-identity --no-launch --json
winapp unregister .

Use this only when the user wants copies of an app to stay registered side by side. Pass the same input for every run, and the same project, .cs, or folder for cleanup (for a solution, the project it ran). Read names from the returned Identity and aliases instead of guessing them. Never resolve a registration conflict by removing another checkout's package.

Check the unique identity reference for supported packages and limits. For guest execution, also use winapp-sandbox.

Prerequisites

For the sparse create-debug-identity workflow below:

Package.appxmanifest in your project — from winapp init or winapp manifest generate
Built executable — the .exe your app runs from

What is package identity?

Windows package identity enables your app to use restricted APIs and OS integration features:

Push notifications (WNS)
Background tasks
Share target / share source
App startup tasks
Taskbar pinning
Windows AI APIs (Phi Silica, OCR, etc.)
File type associations registered properly in Settings

A standard .exe (from dotnet build, cmake, etc.) does not have identity. create-debug-identity registers a sparse package with Windows — the exe stays in its original location and Windows associates identity with it via Add-AppxPackage -ExternalLocation. This is different from winapp run, which copies files into a loose layout package.

Usage

Basic usage

# Register sparse package for your exe (manifest auto-detected from current dir)
winapp create-debug-identity ./bin/Release/myapp.exe

# Specify manifest location
winapp create-debug-identity ./bin/Release/myapp.exe --manifest ./Package.appxmanifest

Keep the original package identity

# By default, '.debug' is appended to the package name to avoid conflicts with
# an installed MSIX version. Use --keep-identity to keep the manifest identity as-is.
winapp create-debug-identity ./myapp.exe --keep-identity

Generate without installing

# Create the sparse package layout but don't register it with Windows
winapp create-debug-identity ./myapp.exe --no-install

What the command does

Reads Package.appxmanifest — extracts identity, capabilities, and assets
Creates a sparse package layout in a temp directory
Appends .debug to the package name (unless --keep-identity) to avoid conflicts
Registers with Windows via Add-AppxPackage -ExternalLocation — makes your exe "identity-aware"

After running, launch your exe normally — Windows will recognize it as having package identity.

Recommended workflow

Setup — winapp init . --use-defaults (creates Package.appxmanifest)
Generate development certificate — winapp cert generate
Build your app
Register identity — winapp create-debug-identity ./bin/myapp.exe
Run your app — identity-requiring APIs now work
Re-run step 4 whenever you change Package.appxmanifest or Assets/

Tips

You must re-run create-debug-identity (or winapp run) after any changes to Package.appxmanifest or image assets; both read them only when they register the package
The debug identity persists across reboots until explicitly removed
To remove this sparse registration: winapp unregister --manifest .\Package.appxmanifest
If you have both a debug identity and an installed MSIX, they may conflict — use --keep-identity carefully
For Electron apps, use npx winapp node add-electron-debug-identity instead (handles Electron-specific paths)

Debugging: `winapp run` vs `create-debug-identity`

	`winapp run`	`create-debug-identity`
What it registers	Full loose layout package (entire folder)	Sparse package (single exe)
How the app launches	Launched by winapp (AUMID activation or execution alias)	You launch the exe yourself (command line, IDE, etc.)
Simulates MSIX install	Yes — closest to production behavior	No — sparse identity only
Files stay in place	Copied to an AppX layout directory	Yes — exe stays at its original path
Debugger-friendly	Attach to PID after launch, or use `--no-launch` then launch via alias	Launch directly from your IDE's debugger — the exe has identity regardless
Console app support	Launched through an execution alias automatically, so stdin/stdout stay in this terminal	Run exe directly in terminal
Best for	Most frameworks (.NET, C++, Rust, Flutter, Tauri)	Electron, or when you need full IDE debugger control (F5 startup debugging)

When to use which

Default to winapp run for most development — normal identity mode simulates a real MSIX install with full identity, capabilities, and file associations:

winapp run .\build\output          # GUI and console apps alike; a console app
                                   # gets an execution alias automatically

Use create-debug-identity when:

Debugging startup code — your IDE launches + debugs the exe directly; identity is attached from the first instruction
Exe is separate from build output — e.g., Electron where electron.exe is in node_modules/
Testing sparse package behavior — AllowExternalContent, TrustedLaunch

winapp create-debug-identity .\bin\Debug\myapp.exe
# Now launch any way you like — F5, terminal, script — the exe has identity

Common debugging scenarios

Scenario	Command	Notes
Just run with identity	`winapp run .\build\Debug`	Simplest workflow; a console app gets an execution alias automatically
Attach debugger to running app	`winapp run .\build\Debug`, then attach to PID	Misses startup code
Register identity, launch via AUMID	`winapp run .\build\Debug --no-launch`	Launch with `start shell:AppsFolder\<AUMID>` or the execution alias (not the exe directly)
F5 startup debugging	`winapp create-debug-identity .\bin\myapp.exe`	IDE controls process from first instruction; best for debugging activation/startup code
Capture debug output	`winapp run .\build\Debug --debug-output`	Captures `OutputDebugString`; on crash, writes minidump and analyzes managed exceptions automatically. Blocks other debuggers (one debugger per process)
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 project, `.cs`, or folder as `run` (for a solution, the project it ran); works with or without `--unique-identity`

Using Visual Studio with a packaging project? VS already handles identity, AUMID activation, and debugger attachment from F5. These workflows are most useful for VS Code, terminal-based development, and frameworks VS doesn't natively package (Rust, Flutter, Tauri, Electron, C++).

For full details including IDE setup examples, see the Debugging Guide.

Production sparse packaging (`init --sparse` / `pack` / `embed-identity`)

create-debug-identity is for developer-time debugging (requires Developer Mode, registers a raw manifest). For production — shipping identity to an app distributed by an existing installer (Inno Setup, WiX, NSIS) — use the sparse packaging workflow, which produces a signed identity-only .msix:

# 1. Create the sparse identity manifest for your exe (skips SDK install)
winapp init --exe ./bin/Release/MyApp.exe --sparse --use-defaults

# 2. Build and sign the identity-only .msix (just the manifest, no binaries)
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx

# 3. Embed the <msix> identity element into the exe's fusion manifest
winapp embed-identity ./bin/Release/MyApp.exe

Then your installer registers the package against the install directory: Add-AppxPackage -Path MyApp.identity.msix -ExternalLocation <install-dir>.

Assets are resolved from the external (install) location at runtime, not bundled into the .msix. winapp embed-identity also supports an XML mode (winapp embed-identity ./app.manifest) for updating a checked-in side-by-side manifest. See the Sparse Packaging Guide and the sparse-app sample.

Related skills

Need a manifest? See winapp-manifest to generate Package.appxmanifest
Need a certificate? See winapp-signing — a trusted cert is required for identity registration
Ready for full MSIX distribution? See winapp-package to create an installer
Having issues? See winapp-troubleshoot for common error solutions

Troubleshooting

Error	Cause	Solution
"Package.appxmanifest not found"	No manifest in current directory	Run `winapp init` or `winapp manifest generate`, or pass `--manifest`
"Failed to add package identity"	Previous registration stale or cert untrusted	Run `winapp unregister` to remove stale packages, then `winapp cert install ./devcert.pfx` (admin)
"Access denied"	Cert not trusted or permission issue	Run `winapp cert install ./devcert.pfx` as admin
APIs still fail after registration	App launched before registration completed	Close app, re-run `create-debug-identity`, then relaunch

CLI reference

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