winapp-identity

name: winapp-identity description: Enable Windows package identity for desktop apps to access Windows APIs like push notifications, background tasks, share target, and startup tasks. Use when adding Windows notifications, background tasks, or other identity-requiring Windows features to a desktop app. version: 0.3.2

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.

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

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 or appxmanifest.xml in current directory or passed via --manifest. Re-run after changing the manifest or Assets/.

Arguments

Options