Back to Details

winapp-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Windows App Development CLI

Windows应用开发CLI

The Windows App Development CLI (
winapp
) is a command-line interface for managing Windows SDKs, MSIX packaging, generating app identity, manifests, certificates, and using build tools with any app framework. It bridges the gap between cross-platform development and Windows-native capabilities.
Windows应用开发CLI（
winapp
）是一个命令行界面工具，用于管理Windows SDK、MSIX打包、生成应用标识、清单、证书，以及在任意应用框架中使用构建工具。它填补了跨平台开发与Windows原生功能之间的差距。

When to Use This Skill

何时使用该工具

Use this skill when you need to:
  • Initialize a Windows app project with SDK setup, manifests, and certificates
  • Create MSIX packages from application directories
  • Generate or manage AppxManifest.xml files
  • Create and install development certificates for signing
  • Add package identity for debugging Windows APIs
  • Sign MSIX packages or executables
  • Access Windows SDK build tools from any framework
  • Build Windows apps using cross-platform frameworks (Electron, Rust, Tauri, Qt)
  • Set up CI/CD pipelines for Windows app deployment
  • Access Windows APIs that require package identity (notifications, Windows AI, shell integration)
当你需要以下操作时，可以使用本工具：
  • 初始化包含SDK配置、清单和证书的Windows应用项目
  • 从应用目录创建MSIX包
  • 生成或管理AppxManifest.xml文件
  • 创建并安装用于签名的开发证书
  • 添加包标识以调试Windows API
  • 为MSIX包或可执行文件签名
  • 从任意框架访问Windows SDK构建工具
  • 使用跨平台框架（Electron、Rust、Tauri、Qt）构建Windows应用
  • 为Windows应用部署设置CI/CD流水线
  • 访问需要包标识的Windows API（通知、Windows AI、外壳集成）

Prerequisites

前置条件

  • Windows 10 or later
  • winapp CLI installed via one of these methods:
    • WinGet: 
      winget install Microsoft.WinAppCli --source winget
    • NPM (for Electron): 
      npm install @microsoft/winappcli --save-dev
    • GitHub Actions/Azure DevOps: Use setup-WinAppCli action
    • Manual: Download from GitHub Releases
  • Windows 10或更高版本
  • 通过以下方式之一安装winapp CLI：
    • WinGet：
      winget install Microsoft.WinAppCli --source winget
    • NPM（适用于Electron）：
      npm install @microsoft/winappcli --save-dev
    • GitHub Actions/Azure DevOps：使用setup-WinAppCli动作
    • 手动安装：从GitHub Releases下载

Core Capabilities

核心功能

1. Project Initialization (
winapp init
)

1. 项目初始化（
winapp init
）

Initialize a directory with required assets (manifest, certificates, libraries) for building a modern Windows app. Supports SDK installation modes: 
stable
, 
preview
, 
experimental
, or 
none
.
为构建现代Windows应用初始化目录，包含所需资源（清单、证书、库）。支持SDK安装模式：
stable
、
preview
、
experimental
或
none
。

2. MSIX Packaging (
winapp pack
)

2. MSIX打包（
winapp pack
）

Create MSIX packages from prepared directories with optional signing, certificate generation, and self-contained deployment bundling.
从已准备好的目录创建MSIX包，支持可选的签名、证书生成和自包含部署捆绑。

3. Package Identity for Debugging (
winapp create-debug-identity
)

3. 调试用包标识（
winapp create-debug-identity
）

Add temporary package identity to executables for debugging Windows APIs that require identity (notifications, Windows AI, shell integration) without full packaging.
为可执行文件添加临时包标识，无需完整打包即可调试需要标识的Windows API（通知、Windows AI、外壳集成）。

4. Manifest Management (
winapp manifest
)

4. 清单管理（
winapp manifest
）

Generate AppxManifest.xml files and update image assets from source images, automatically creating all required sizes and aspect ratios.
生成AppxManifest.xml文件，并从源图片更新图像资源，自动创建所有所需尺寸和宽高比的资源。

5. Certificate Management (
winapp cert
)

5. 证书管理（
winapp cert
）

Generate development certificates and install them to the local machine store for signing packages.
生成开发证书并安装到本地计算机存储，用于包签名。

6. Package Signing (
winapp sign
)

6. 包签名（
winapp sign
）

Sign MSIX packages and executables with PFX certificates, with optional timestamp server support.
使用PFX证书为MSIX包和可执行文件签名，支持可选的时间戳服务器。

7. SDK Build Tools Access (
winapp tool
)

7. SDK构建工具访问（
winapp tool
）

Run Windows SDK build tools with properly configured paths from any framework or build system.
从任意框架或构建系统运行配置好路径的Windows SDK构建工具。

Usage Examples

使用示例

Example 1: Initialize and Package a Windows App

示例1：初始化并打包Windows应用

bash
undefined
bash
undefined

Initialize workspace with defaults

使用默认设置初始化工作区

winapp init
winapp init

Build your application (framework-specific)

构建应用（取决于具体框架）

...

...

Create signed MSIX package

创建已签名的MSIX包

winapp pack ./build-output --generate-cert --output MyApp.msix
undefined
winapp pack ./build-output --generate-cert --output MyApp.msix
undefined

Example 2: Debug with Package Identity

示例2：使用包标识调试

bash
undefined
bash
undefined

Add debug identity to executable for testing Windows APIs

为可执行文件添加调试标识以测试Windows API

winapp create-debug-identity ./bin/MyApp.exe
winapp create-debug-identity ./bin/MyApp.exe

Run your app - it now has package identity

运行应用 - 现在已具备包标识

./bin/MyApp.exe
undefined
./bin/MyApp.exe
undefined

Example 3: CI/CD Pipeline Setup

示例3：CI/CD流水线设置

yaml
undefined
yaml
undefined

GitHub Actions example

GitHub Actions示例

  • name: Setup winapp CLI uses: microsoft/setup-WinAppCli@v1
  • name: Initialize and Package run: | winapp init --no-prompt winapp pack ./build-output --output MyApp.msix
undefined
  • name: Setup winapp CLI uses: microsoft/setup-WinAppCli@v1
  • name: Initialize and Package run: | winapp init --no-prompt winapp pack ./build-output --output MyApp.msix
undefined

Example 4: Electron App Integration

示例4：Electron应用集成

bash
undefined
bash
undefined

Install via npm

通过npm安装

npm install @microsoft/winappcli --save-dev
npm install @microsoft/winappcli --save-dev

Initialize and add debug identity for Electron

初始化并为Electron添加调试标识

npx winapp init npx winapp node add-electron-debug-identity
npx winapp init npx winapp node add-electron-debug-identity

Package for distribution

打包用于分发

npx winapp pack ./out --output MyElectronApp.msix
undefined
npx winapp pack ./out --output MyElectronApp.msix
undefined

Guidelines

使用指南

  1. Run 
    winapp init
    first     - Always initialize your project before using other commands to ensure SDK setup, manifest, and certificates are configured.
  2. Re-run 
    create-debug-identity
    after manifest changes     - Package identity must be recreated whenever AppxManifest.xml is modified.
  3. Use 
    --no-prompt
    for CI/CD     - Prevents interactive prompts in automated pipelines by using default values.
  4. Use 
    winapp restore
    for shared projects     - Recreates the exact environment state defined in 
    winapp.yaml
    across machines.
  5. Generate assets from a single image - Use 
    winapp manifest update-assets
    with one logo to generate all required icon sizes.
  1. 先运行
    winapp init
     - 在使用其他命令前，务必先初始化项目，确保SDK配置、清单和证书已正确设置。
  2. 修改清单后重新运行
    create-debug-identity
     - 每当AppxManifest.xml被修改时，必须重新创建包标识。
  3. 在CI/CD中使用
    --no-prompt
     - 在自动化流水线中使用默认值，避免交互式提示。
  4. 为共享项目使用
    winapp restore
     - 在不同机器上根据
    winapp.yaml
    重新创建完全一致的环境状态。
  5. 从单张图片生成资源 - 使用
    winapp manifest update-assets
    和一张Logo生成所有所需尺寸的图标。

Common Patterns

常见使用模式

Pattern: Initialize New Project

模式：初始化新项目

bash
cd my-project
winapp init
bash
cd my-project
winapp init

Creates: AppxManifest.xml, development certificate, SDK configuration, winapp.yaml

创建：AppxManifest.xml、开发证书、SDK配置、winapp.yaml

undefined
undefined

Pattern: Package with Existing Certificate

模式：使用现有证书打包

bash
winapp pack ./build-output --cert ./mycert.pfx --cert-password secret --output MyApp.msix
bash
winapp pack ./build-output --cert ./mycert.pfx --cert-password secret --output MyApp.msix

Pattern: Self-Contained Deployment

模式：自包含部署

bash
undefined
bash
undefined

Bundle Windows App SDK runtime with the package

将Windows App SDK运行时与包捆绑

winapp pack ./my-app --self-contained --generate-cert
undefined
winapp pack ./my-app --self-contained --generate-cert
undefined

Pattern: Update Package Versions

模式：更新包版本

bash
undefined
bash
undefined

Update to latest stable SDKs

更新到最新稳定版SDK

winapp update
winapp update

Or update to preview SDKs

或更新到预览版SDK

winapp update --setup-sdks preview
undefined
winapp update --setup-sdks preview
undefined

Limitations

局限性

  • Windows 10 or later required (Windows-only CLI)
  • Package identity debugging requires re-running 
    create-debug-identity
    after any manifest changes
  • Self-contained deployment increases package size by bundling the Windows App SDK runtime
  • Development certificates are for testing only; production requires trusted certificates
  • Some Windows APIs require specific capability declarations in the manifest
  • winapp CLI is in public preview and subject to change
  • 需要Windows 10或更高版本（仅支持Windows的CLI）
  • 包标识调试需要在修改清单后重新运行
    create-debug-identity
  • 自包含部署会因捆绑Windows App SDK运行时而增加包体积
  • 开发证书仅用于测试；生产环境需要受信任的证书
  • 部分Windows API需要在清单中声明特定权限
  • winapp CLI处于公开预览阶段，可能会有变更

Windows APIs Enabled by Package Identity

包标识解锁的Windows API

Package identity unlocks access to powerful Windows APIs:
API CategoryExamples
NotificationsInteractive native notifications, notification management
Windows AIOn-device LLM, text/image AI APIs (Phi Silica, Windows ML)
Shell IntegrationExplorer, Taskbar, Share sheet integration
Protocol HandlersCustom URI schemes (
yourapp://
)
Device AccessCamera, microphone, location (with consent)
Background TasksRun when app is closed
File AssociationsOpen file types with your app
包标识可解锁对强大Windows API的访问权限：
API类别示例
通知交互式原生通知、通知管理
Windows AI本地LLM、文本/图像AI API（Phi Silica、Windows ML）
外壳集成文件资源管理器、任务栏、共享面板集成
协议处理程序自定义URI方案（
yourapp://
）
设备访问摄像头、麦克风、位置（需用户授权）
后台任务应用关闭后仍可运行
文件关联使用你的应用打开特定文件类型

Troubleshooting

故障排除

IssueSolution
Certificate not trustedRun 
winapp cert install <cert-path>
to install to local machine store
Package identity not workingRun 
winapp create-debug-identity
after any manifest changes
SDK not foundRun 
winapp restore
or 
winapp update
to ensure SDKs are installed
Signing failsVerify certificate password and ensure cert is not expired
问题解决方案
证书不被信任运行
winapp cert install <cert-path>
将证书安装到本地计算机存储
包标识不生效修改清单后重新运行
winapp create-debug-identity
找不到SDK运行
winapp restore
或
winapp update
确保SDK已安装
签名失败验证证书密码，确保证书未过期

References

参考资料