winapp-identity

When to use

Use this skill when:

• 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.

Prerequisites

1. appxmanifest.xml in your project — from winapp init or winapp manifest generate
2. 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 ./appxmanifest.xml

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

1. Reads appxmanifest.xml — extracts identity, capabilities, and assets
2. Creates a sparse package layout in a temp directory
3. Appends .debug to the package name (unless --keep-identity) to avoid conflicts
4. 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

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

Tips

• You must re-run create-debug-identity after any changes to appxmanifest.xml or image assets
• The debug identity persists across reboots until explicitly removed
• To remove: Get-AppxPackage *yourapp.debug* | Remove-AppxPackage
• 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	--with-alias keeps stdin/stdout in 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 — it simulates a real MSIX install with full identity, capabilities, and file associations:

winapp run .\build\output          # GUI apps
winapp run .\build\output --with-alias   # console apps (preserves stdin/stdout)

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; add --with-alias for console apps
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 stale registration	winapp unregister	Removes dev packages for the current project (auto-detects from manifest)

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.

Related skills

• Need a manifest? See winapp-manifest to generate appxmanifest.xml
• 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
"appxmanifest.xml 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

Command Reference

winapp create-debug-identity

Enable package identity for debugging without creating full MSIX. Required for testing Windows APIs (push notifications, share target, etc.) during development. Example: winapp create-debug-identity ./myapp.exe. Requires Package.appxmanifest in current directory or passed via --manifest. Re-run after changing the manifest or Assets/.

Arguments

Argument	Required	Description
<entrypoint>	No	Path to the .exe that will need to run with identity, or entrypoint script.

Options

Option	Description	Default
--keep-identity	Keep the package identity from the manifest as-is, without appending '.debug' to the package name and application ID.	(none)
--manifest	Path to the Package.appxmanifest or appxmanifest.xml	(none)
--no-install	Do not install the package after creation.	(none)