microsoft/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-name "CN=Contoso" --version "2.0.0.0"

# Set entry point and description
winapp manifest generate --executable myapp.exe --description "My awesome app"

# Generate a sparse manifest (for desktop apps needing identity without full MSIX)
winapp manifest generate --template sparse

# Overwrite existing manifest
winapp manifest generate --if-exists overwrite

Output:

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

Update app icons from a source image

# Generate all required icon sizes from one source image
winapp manifest update-assets ./my-logo.png

# SVG source images produce the best quality at all sizes
winapp manifest update-assets ./my-logo.svg

# Specify manifest location (if not in current directory)
winapp manifest update-assets ./my-logo.png --manifest ./path/to/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets ./my-logo.png --light-image ./my-logo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets ./my-logo.png --light-image ./my-logo.png

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

# Add alias inferred from the Executable attribute in the manifest
winapp manifest add-alias

# Specify the alias name explicitly
winapp manifest add-alias --name myapp

# Target a specific manifest file
winapp manifest add-alias --manifest ./path/to/Package.appxmanifest

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:

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
         xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
         xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities">
  <Identity Name="MyApp" Publisher="CN=MyPublisher" Version="1.0.0.0" />
  <Properties>
    <DisplayName>My App</DisplayName>
    <PublisherDisplayName>My Publisher</PublisherDisplayName>
    <Logo>Assets\StoreLogo.png</Logo>
  </Properties>
  <Resources>
    <Resource Language="en-us" />
  </Resources>
  <Applications>
    <Application Id="App" Executable="myapp.exe" EntryPoint="Windows.FullTrustApplication">
      <uap:VisualElements DisplayName="My App" Description="My Application"
        Square150x150Logo="Assets\Square150x150Logo.png"
        Square44x44Logo="Assets\Square44x44Logo.png" BackgroundColor="transparent" />
    </Application>
  </Applications>
  <Capabilities>
    <rescap:Capability Name="runFullTrust" />
  </Capabilities>
</Package>

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 a <uap10:AllowExternalContent>true</uap10:AllowExternalContent> element (under <Properties>) 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

| Error | Cause | Solution | |-------|-------|----------| | "Manifest already exists" | Package.appxmanifest present | Use --if-exists overwrite to replace, or edit existing file directly | | "Invalid source image" | Image too small or wrong format | Use PNG or SVG, at least 400x400 pixels | | "Publisher mismatch" during packaging | Manifest publisher ≠ cert publisher | Edit Identity.Publisher in manifest, or regenerate cert with --manifest |

CLI reference

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