winapp-cli

Windows 应用开发命令行

winapp 面向任何以 Windows 为目标的框架（.NET/csproj、C++、Electron、Rust、Tauri、Flutter 等），管理 Windows SDK、MSIX 打包、应用标识、清单、证书、签名、应用商店发布和 UI 自动化。公开预览版——可能会发生变更。

先决条件

• Windows 10 或更高版本
• 通过以下方式之一安装：
  • WinGet：winget install Microsoft.WinAppCli --source winget
  • npm（Electron/Node）：npm install @microsoft/winappcli --save-dev
  • CI：setup-WinAppCli GitHub Action
  • 手动：GitHub Releases

命令

命令	用途
init	初始化项目：SDK（stable/preview/experimental/none）、清单、winapp.yaml。.csproj 项目会跳过 winapp.yaml，直接使用 NuGet。不会自动生成证书（v0.2.0+）。
restore / update	还原或更新 SDK 包版本（--setup-sdks preview 用于预览版 SDK）。
pack <dir>	构建 MSIX。参数：--generate-cert、--cert <pfx> --cert-password、--self-contained（捆绑 WinAppSDK 运行时）、--output。自动从 .winmd 中发现第三方 WinRT 组件（v0.2.1+）。
run <dir> [-- <app args>]	以松散布局打包并作为打包应用启动——非常适合在 IDE 中按 F5 调试而无需生成 MSIX。支持 -- 参数透传（v0.3.1+）。（v0.3.0+）
create-debug-identity <exe>	为 exe 添加稀疏包标识，使其无需完整打包即可调用需要标识的 API（通知、Windows AI、shell 集成）。
unregister	移除由 run / create-debug-identity 注册的旁加载开发包。
manifest	生成 AppxManifest.xml；支持占位符和限定名称。manifest update-assets <image> 从单一源（PNG 或 SVG，v0.2.1+）生成所有必需的图标尺寸。
cert generate / install / info	管理开发证书。cert info <pfx> --password <pwd> 显示主体/颁发者/有效期。--export-cer 导出公钥。generate 和 info 支持 --json。（v0.2.1+）
sign <target> --cert <pfx>	对 MSIX 或 exe 签名；可选时间戳服务器。
tool	在配置好路径的情况下运行 Windows SDK 构建工具。
store	运行 Microsoft Store Developer CLI，用于应用商店提交/验证/发布。
create-external-catalog	为 TrustedLaunch 稀疏包生成 CodeIntegrityExternal.cat。
ui list-windows / inspect / click / search / wait-for / get-focused	通过 Microsoft UI Automation 实现 UI 自动化。全部支持 --json。inspect、get-focused、search 和 wait-for 的 JSON 封装结构在 v0.3.1 中发生了变更——参见 references/ui-json-envelope.md（其他 ui 子命令保持 0.3.1 之前的输出）。（v0.3.0+）
node create-addon / add-electron-debug-identity / clear-electron-debug-identity	Electron/Node 辅助工具。所有命令也都以类型化的 JS/TS 函数形式从 @microsoft/winappcli 暴露（v0.2.1+）。

CI 提示：传入 --no-prompt 可跳过交互式提示。

工作流

标准的初始化 → 打包流程：

1. 在应用文件夹中初始化项目。设置 SDK 引用、清单和 winapp.yaml（.csproj 项目跳过 YAML，直接配置 NuGet）。

   winapp init        # add --no-prompt in CI
   

2. 生成开发签名证书——旁加载所必需。对于非 .csproj 项目，init 不再创建证书（v0.2.0+）。请固定输出路径，以便后续步骤可以引用它。

   winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx --install
   

3. 使用框架自带的工具链构建应用（dotnet build、npm run build、cargo build 等）。

4. 打包为 MSIX，并使用第 2 步中的证书签名。

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

5. （可选）在分发前使用生产证书重新签名。

   winapp sign MyApp.msix --cert ./prod.pfx --cert-password $env:CERT_PWD
   

6. （可选）使用 winapp store … 提交到 Microsoft Store（封装了 Store Developer CLI）。

备用流程

• 在不打包的情况下调试需要身份验证的 API（通知、Windows AI、shell）：

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

• 作为打包应用运行以支持 IDE F5（松散布局；应用参数放在 -- 之后）：

  winapp run ./bin/Debug/net10.0-windows10.0.26100.0/win-x64 \
    --manifest ./appxmanifest.xml -- --my-flag value
  

• Electron：

  npx winapp init
  npx winapp node add-electron-debug-identity
  npx winapp pack ./out --output MyElectronApp.msix
  

注意事项

• winapp ui --json 的输出结构在 v0.3.1 中已更改 — ui inspect、ui get-focused、ui search 和 ui wait-for 使用新的结构；每个元素的 id / parentSelector / windowHandle 已被移除（改用 selector）。完整 schema 见 references/ui-json-envelope.md。
• winapp init 不再自动生成证书（v0.2.0+）— 需显式运行 winapp cert generate。旧的 --no-cert 标志已被移除。
• .csproj 项目会跳过 winapp.yaml — SDK 包位于项目文件中。混合配置需要调整。
• 使用 NuGet 全局缓存，而非 %userprofile%/.winapp/packages（v0.2.0+）— 依赖旧文件夹的脚本将会失效。
• 任何清单更改后需重新运行 create-debug-identity — 身份在注册时绑定。

故障排查

问题	修复方法
证书不受信任	运行 winapp cert install <pfx> 将其添加到本地计算机存储
需要身份验证的 API 失败	清单更改后重新运行 create-debug-identity
找不到 SDK	运行 winapp restore 或 winapp update
run / create-debug-identity 注册错误 0x800704EC	开发者模式已关闭 — 在 Settings → Privacy & security → For developers 中启用（或运行 Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Name AllowDevelopmentWithoutDevLicense -Value 1），然后重试
run / create-debug-identity 注册错误 0x80073CFB	包已使用冲突的身份注册 — 运行 winapp unregister（如果是从其他项目树注册的，则运行 winapp unregister --force），然后重试

参考资料

• winapp CLI 仓库 · 完整用法文档 · .NET 指南 · 示例
• Windows App SDK · MSIX 概述 · 包身份概述