winapp-manifest

When to use

Use this skill when:

• Creating Package.appxmanifest for a project that doesn't have one yet
• Generating app icon assets from a single source image
• Understanding manifest structure for package identity and capabilities

Prerequisites

• winapp CLI installed
• Optional: a source image (PNG or SVG, at least 400x400 pixels) for custom app icons

Key concepts

Package.appxmanifest is the key prerequisite for most winapp commands — it's more important than winapp.yaml. It declares:

• Package identity — name, publisher, version
• App entry point — which executable to launch
• Capabilities — what the app can access (internet, file system, etc.)
• Visual assets — icons for Start menu, taskbar, installers
• Extensions — share target, startup tasks, file associations, etc.

Two manifest templates:

• packaged (default) — for full MSIX distribution
• sparse — for desktop apps that need package identity without full MSIX containment (uses AllowExternalContent)

winapp init also generates a manifest as part of full project setup. Use winapp manifest generate when you only need the manifest without SDK setup or winapp.yaml.

Usage

Generate a new manifest

# Defaults — uses current folder name, current user as publisher
winapp manifest generate
 
# Into a specific directory
winapp manifest generate ./my-project
 
# Customize identity
winapp manifest generate --package-name "MyApp" --publisher

Output:

• Package.appxmanifest — the manifest file
• Assets/ — default app icons in required sizes (Square44x44Logo, Square150x150Logo, Wide310x150Logo, etc.)

Update app icons from a source image

The source image should be at least 400x400 pixels (PNG or SVG recommended). The command reads the manifest to determine which asset sizes are needed and generates:

• 5 scale variants per asset (100%, 125%, 150%, 200%, 400%)
• 14 plated + 14 unplated targetsize variants for the app icon (44x44)
• app.ico — multi-resolution ICO file for shell integration. If an existing .ico file is present in the assets directory, it is replaced in-place (preserving the original filename)
• With --light-image: light theme variants using the correct MRT qualifiers per asset type

Add an execution alias

Execution aliases let users launch the app by typing its name in a terminal (e.g. myapp).

This adds a uap5:AppExecutionAlias extension to the manifest. If the alias already exists, the command reports it and exits successfully.

When combined with winapp run --with-alias or the WinAppRunUseExecutionAlias MSBuild property, this enables apps to run in the current terminal with inherited stdin/stdout/stderr instead of opening a new window.

Manifest structure overview

A typical Package.appxmanifest looks like:

Key fields to edit:

• Identity.Name — unique package name (no spaces)
• Identity.Publisher — must match your certificate exactly
• Application.Executable — your app's exe filename
• Capabilities — add capabilities as needed (internetClient, broadFileSystemAccess, etc.)

Tips

• Always ensure Identity.Publisher matches your signing certificate — use winapp cert generate --manifest to auto-match
• The sparse template adds uap10:AllowExternalContent="true" for apps that need identity but run outside the MSIX container
• You can manually edit Package.appxmanifest after generation — it's a standard XML file
• Image assets must match the paths referenced in the manifest — update-assets handles this automatically
• For logos, transparent PNGs or SVGs work best. SVG source images are rendered as vectors directly at each target size, producing pixel-perfect results. Use a square image for best results across all sizes.
• $targetnametoken$ placeholder: When winapp manifest generate creates Package.appxmanifest, it sets Application.Executable to $targetnametoken$.exe by default. This is a valid placeholder that gets automatically resolved by winapp package --executable <name> at packaging time — you rarely need to override it during manifest generation. If --executable is provided to winapp manifest generate, winapp reads FileVersionInfo from the actual exe to auto-fill package name, description, publisher, and extract an icon, so the exe must already exist on disk.

Related skills

• After generating a manifest, see winapp-signing for certificate setup and winapp-package to create the MSIX installer
• Not sure which command to use? See winapp-troubleshoot for a command selection flowchart

Troubleshooting

Command Reference

winapp manifest generate

Create Package.appxmanifest without full project setup. Use when you only need a manifest and image assets (no SDKs, no certificate). For full setup, use 'init' instead. Templates: 'packaged' (full MSIX), 'sparse' (desktop app needing Windows APIs).

Arguments

Options

winapp manifest update-assets

Generate new assets for images referenced in a Package.appxmanifest from a single source image. Source image should be at least 400x400 pixels.

Arguments

Options

winapp manifest add-alias

Add an execution alias (uap5:AppExecutionAlias) to a Package.appxmanifest. This allows launching the packaged app from the command line by typing the alias name. By default, the alias is inferred from the Executable attribute (e.g. $targetnametoken$.exe becomes $targetnametoken$.exe alias).

Options