Windows 应用开发 CLI

Windows 应用开发 CLI (winapp) 是一个命令行界面，用于管理 Windows SDK、MSIX 打包、生成应用标识、清单、证书，并与任何应用框架一起使用构建工具。它弥合了跨平台开发与 Windows 原生能力之间的差距。

何时使用此技能

在需要以下操作时，可使用此技能：

• 通过 SDK 设置、清单和证书初始化 Windows 应用项目
• 从应用目录创建 MSIX 包
• 生成或管理 AppxManifest.xml 文件
• 为签名创建和安装开发证书
• 为调试 Windows API 添加包标识
• 签署 MSIX 包或可执行文件
• 从任何框架访问 Windows SDK 构建工具
• 使用跨平台框架（Electron、Rust、Tauri、Qt）构建 Windows 应用
• 为 Windows 应用部署设置 CI/CD 流水线
• 访问需要包标识的 Windows API（通知、Windows AI、Shell 集成）
• 通过 winapp store 将应用发布到 Microsoft Store
• 为资产管理创建外部目录
• 通过 NuGet 设置使用 Windows 应用 SDK 的 .NET (csproj) 项目

先决条件

• 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 下载

核心功能

1. 项目初始化 (winapp init)

使用构建现代 Windows 应用所需的资产（清单、证书、库）初始化目录。支持 SDK 安装模式：stable、preview、experimental 或 none。

2. MSIX 打包 (winapp pack)

从准备好的目录创建 MSIX 包，可选择签名、生成证书和捆绑自包含部署。

3. 调试用包标识 (winapp create-debug-identity)

为可执行文件添加临时包标识，以便在不完整打包的情况下调试需要包标识的 Windows API（通知、Windows AI、Shell 集成）。

4. 清单管理 (winapp manifest)

生成 AppxManifest.xml 文件，并从源图像更新图像资产，自动创建所有所需尺寸和纵横比。支持清单占位符以动态内容，以及在 AppxManifest 中使用限定名称以实现灵活的应用标识定义。

5. 证书管理 (winapp cert)

生成开发证书并将其安装到本地计算机存储区，用于签名包。

6. 包签名 (winapp sign)

使用 PFX 证书对 MSIX 包和可执行文件进行签名，可选择支持时间戳服务器。

7. SDK 构建工具访问 (winapp tool)

从任何框架或构建系统运行 Windows SDK 构建工具，并正确配置路径。

8. Microsoft Store 集成 (winapp store)

直接从 winapp 运行 Microsoft Store 开发者 CLI 命令，无需离开 CLI 即可执行商店提交、包验证和发布工作流程。

9. 创建外部目录 (winapp create-external-catalog)

创建外部目录以简化开发者的资产管理，将目录数据与主包分离。

使用示例

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

# 使用默认值初始化工作区
winapp init
# 注意：init 不再自动生成证书（v0.2.0+）。需要显式生成一个：
winapp cert generate

# 构建你的应用（框架特定）
# ...

# 创建已签名的 MSIX 包
winapp pack ./build-output --generate-cert --output MyApp.msix

示例 2：使用包标识进行调试

# 为可执行文件添加调试标识以测试 Windows API
winapp create-debug-identity ./bin/MyApp.exe

# 运行应用 - 它现在拥有包标识
./bin/MyApp.exe

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

# GitHub Actions 示例
- name: 设置 winapp CLI
  uses: microsoft/setup-WinAppCli@v1

- name: 初始化和打包
  run: |
    winapp init --no-prompt
    winapp pack ./build-output --output MyApp.msix

示例 4：Electron 应用集成

# 通过 npm 安装
npm install @microsoft/winappcli --save-dev

# 初始化并为 Electron 添加调试标识
npx winapp init
npx winapp node add-electron-debug-identity

# 为分发打包
npx winapp pack ./out --output MyElectronApp.msix

指南

1. 首先运行 winapp init – 在使用其他命令之前始终初始化项目，以确保 SDK 设置和清单已配置。注意：从 v0.2.0 开始，winapp init 不再自动生成开发证书。当你需要使用开发证书签名时，请显式运行 winapp cert generate。
2. 清单更改后重新运行 create-debug-identity – 每当 AppxManifest.xml 被修改时，必须重新创建包标识。
3. 在 CI/CD 中使用 --no-prompt – 通过使用默认值，防止在自动化流水线中出现交互式提示。
4. 对共享项目使用 winapp restore – 在不同机器上重新创建 winapp.yaml 中定义的精确环境状态。
5. 从单个图像生成资产 – 使用 winapp manifest update-assets 和一个 Logo 来生成所有必需的图标尺寸。

常见模式

模式：初始化新项目

cd my-project
winapp init
# 创建：AppxManifest.xml、SDK 配置、winapp.yaml
# 注意：.NET (csproj) 项目会跳过 winapp.yaml，直接在 .csproj 中配置 NuGet 包

# 显式生成开发签名证书（init 不再执行此操作）
winapp cert generate

模式：使用现有证书打包

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

模式：自包含部署

# 将 Windows 应用 SDK 运行时与包捆绑
winapp pack ./my-app --self-contained --generate-cert

模式：更新包版本

# 更新到最新的稳定版 SDK
winapp update

# 或更新到预览版 SDK
winapp update --setup-sdks preview

局限性

• 需要 Windows 10 或更高版本（仅限 Windows 的 CLI）
• 包标识调试需要在任何清单更改后重新运行 create-debug-identity
• 自包含部署通过捆绑 Windows 应用 SDK 运行时增加了包大小
• 开发证书仅用于测试；生产环境需要受信任的证书
• 某些 Windows API 需要在清单中声明特定功能
• winapp init 不再自动生成证书（v0.2.0+）；请显式运行 winapp cert generate
• .NET (csproj) 项目会跳过 winapp.yaml；SDK 包直接在项目文件中配置
• winapp CLI 使用 NuGet 全局缓存存放包（而不是 %userprofile%/.winapp/packages）
• winapp CLI 处于公开预览阶段，可能会有变更

包标识启用的 Windows API

包标识解锁了对强大 Windows API 的访问：

故障排除

参考

• GitHub 仓库
• 完整 CLI 文档
• .NET 项目指南
• 示例应用程序
• Windows 应用 SDK
• MSIX 打包概述
• 包标识概述