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. Package.appxmanifest 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 ./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

1. Reads Package.appxmanifest — 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 Package.appxmanifest)
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 Package.appxmanifest or Assets/

Tips

• You must re-run create-debug-identity after any changes to Package.appxmanifest 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

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

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

CLI reference

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