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

Keep the original package identity

Generate without installing

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:

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

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:

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.