winapp CLI（Windows App Development CLI）是微软推出的 Windows 应用开发命令行工具，一条命令即可搞定 Windows SDK 安装、包身份（Package Identity）生成、清单（Manifest）创建、开发证书和 MSIX 打包。本文以 .NET 应用为例，带你快速上手：10 分钟内从安装 winapp CLI，到生成清单、带身份运行、最终打包出可安装的 MSIX 安装包。

🎯 为什么选择 winapp CLI

很多现代 Windows API（系统通知、协议处理器、开机启动项、端侧 AI 等）都要求应用具备包身份。传统方式下，你要手工完成下载 SDK、生成头文件、创建 appxmanifest、准备图片资源等十几步操作；而 winapp CLI 把这些压缩成了 4 条命令：

它的完整工作流是：Build → App Identity → Package → Ship（构建 → 包身份 → 打包 → 发布）：

第 1 步：一键安装 winapp CLI

在 Windows 终端（PowerShell 或 Terminal）中执行：

winget install Microsoft.winappcli --source winget

安装完成后，用--help或-V验证是否成功：

winapp --help winapp -V

💡 如果你在做 Electron/Node.js 项目，也可以通过 NPM 安装：npm install @microsoft/winappcli --save-dev，然后用npx winapp调用。

第 2 步：创建 .NET 应用并检查包身份

前提：已安装 .NET SDK。创建一个控制台应用并运行，确认一切正常：

dotnet new console -n dotnet-app cd dotnet-app dotnet run

接下来做两件小事：

1. 把.csproj中的TargetFramework改为带 Windows SDK 的版本，例如net10.0-windows10.0.26100.0，这样才能访问 WinRT API；
2. 在代码中读取Windows.ApplicationModel.Package.Current，成功则打印包家族名，失败则输出Not packaged。

此时运行dotnet run，你会看到Not packaged—— 这就是普通可执行文件的"无身份"状态。

第 3 步：winapp init 一键初始化项目

进入项目目录，执行核心命令：

winapp init

winapp init会自动检测.csproj文件，并为你完成：

• ✅ 把Microsoft.WindowsAppSDK、Microsoft.Windows.SDK.BuildTools等 NuGet 包写入项目
• ✅ 校验并更新TargetFramework到受支持的 Windows TFM
• ✅ 生成Package.appxmanifest应用清单和Assets/图片资源（启动画面、磁贴、应用图标等）
• ✅ 生成开发证书

按提示确认包名、发布者、版本即可（全部回车接受默认值）。之后用dotnet list package可以看到新加的 NuGet 包。

[!NOTE] .NET 项目走 NuGet 管理包，不会生成winapp.yaml文件；克隆仓库后执行dotnet restore或winapp restore即可。

第 4 步：带包身份运行应用

两种方式任选其一：

# 方式 A：winapp init 已加入 WinApp 支持包，dotnet run 会自动走 winapp run dotnet run # 方式 B：直接用 winapp run 构建并运行（项目模式） winapp run .

输出从Not packaged变成了：

Package Family Name: dotnet-app_12345abcde

🎉 恭喜，你的应用已经以完整包身份运行，可以解锁通知、协议、系统集身份相关 API 了。如果你更偏好"稀疏包身份"（exe 留在原地注册身份），可以改用winapp create-debug-identity <exe>，详见 docs/debugging.md。

第 5 步：生成并安装 MSIX 包

开发完成后，一条命令链完成"发布"：

# 1. Release 构建 dotnet build -c Release # 2. 生成开发证书（已存在则跳过） winapp cert generate --if-exists skip # 3. 打包并签名（路径按你的项目 TFM 替换） winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\Package.appxmanifest --cert .\devcert.pfx # 4. 以管理员身份安装证书 winapp cert install .\devcert.pfx

双击生成的.msix文件安装，之后在终端直接输入应用名即可启动——它已经是一个正规的、带身份的 Windows 应用。

💡 小贴士：重新打包前先升级Package.appxmanifest中的Version，否则 Windows 会拒绝"降级更新"；正式分发建议使用 CA 签名证书，或对 Microsoft Store 提交（Store 会替你签名）。

📋 核心命令速查

🚀 下一步

• 完整命令参考：docs/usage.md
• 本教程详解版：docs/guides/dotnet.md
• 可运行的 .NET 示例：samples/dotnet-app/
• 其他框架入门指南：C++、Electron、Rust、Tauri、Flutter、.NET MAUI
• 把现有 EXE/CLI 打成 MSIX：docs/guides/packaging-cli.md

从Not packaged到带身份运行的Package Family Name，再到可安装的 MSIX，整个过程只需要这几条 winapp 命令。现在，打开你的终端，10 分钟后见！