mcpField
W
winui-packaging

winui-packaging

github.com/microsoft开发490169 次安装3 周前更新
代码仓库

关于 winui-packaging

winui-packaging 是面向 WinUI 项目的 Windows 应用打包技能，指导开发者使用 WinApp CLI 构建、签名及准备分发包，并涵盖证书、CI/CD 与商店提交边界。

主要功能

  1. 01生成和安装开发证书
  2. 02按架构创建 MSIX 包
  3. 03为现有包签名和加时间戳
  4. 04配置自包含 Windows App SDK 运行时
  5. 05规划 CI/CD 打包及签名流程

适用场景

  1. 01为测试机器生成并信任开发证书
  2. 02构建多架构且未签名的 CI 工件
  3. 03使用生产证书对包进行时间戳签名

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/microsoft/win-dev-skills --skill winui-packaging

安装后在 Claude Code 中输入/winui-packaging确认已加载。

附带文件references/sourcegen-patterns.md

详细介绍

需要 WinApp CLI 0.7+。分析器设置请参阅 winui-dev-workflow。

快速参考
任务命令
发布程序包并签名winapp package .\MyApp.csproj --arch x64 --cert .\devcert.pfx
未签名的多架构捆绑包winapp package .\MyApp.csproj --arch x64 --arch arm64 --no-sign
生成开发证书winapp cert generate
信任证书（管理员）winapp cert install ./devcert.pfx
签名现有文件winapp sign ./app.msix ./devcert.pfx
捆绑 Windows App SDK 运行时winapp package .\MyApp.csproj --arch x64 --cert .\devcert.pfx --self-contained
端到端工作流
步骤 1：检查项目和部署意图
  • 传入明确的项目文件，不要传入 . 或猜测的 bin 文件夹。WinUI 项目打包使用 SDK 原生的 dotnet publish 打包方式，默认使用 Release，并保留项目的 AOT 设置。
  • 检查清单标识、目标架构、应用 TFM 对应的 SDK，以及发布警告。
  • 对于 Native AOT，请在项目中设置 <PublishAot>true</PublishAot>，并修复 IL/CsWinRT 警告；没有 winapp package --aot。AOT 还需要 MSVC C++ 构建工具。请参阅源生成器模式。
  • 项目打包会拒绝 WindowsPackageType=None；请先恢复打包设置（请参阅 winui-dev-workflow 中的 Critical Rules）。

不要为了生成发布产物而运行、注册或注销开发程序包。项目打包无需执行开发用的 winapp run --no-launch 步骤即可构建。对于 WinUI SDK 原生打包，不要传入布局覆盖选项 --manifest、--executable 或 --skip-pri；应改为修正项目或清单。

步骤 2：生成证书（一次性）
winapp cert generate --manifest .\Package.appxmanifest

此命令会创建开发用 devcert.pfx（默认密码：password）。此证书命令的 --manifest 标志会自动匹配 Package.appxmanifest 中的 Publisher 字段。请勿将 PFX 文件或密码纳入源代码管理；生产签名需要遵循组织的签名策略。

步骤 3：在指定测试计算机上信任证书（可选，需管理员权限）
winapp cert install ./devcert.pfx

此操作会将证书添加到计算机信任存储区，并在重启后保留。只有在获得批准后，才能在指定测试计算机上执行；仅在 CI 中构建或打包并不需要此操作。

步骤 4：打包并签名
winapp package .\MyApp.csproj --arch x64 --cert .\devcert.pfx
# Repeat --arch for a bundle
winapp package .\MyApp.csproj --arch x64 --arch arm64 --no-sign

选择一种签名策略：--cert 接受的是 PFX 文件，而不是证书指纹；其主题必须与清单的 Identity.Publisher 匹配。--no-sign 会保留供外部签名的产物。请使用命令报告的产物路径，不要猜测输出目录。

要进行带时间戳的生产签名，请先创建未签名程序包，然后对生成的产物签名：

# Replace MyApp.msix with the package/bundle path returned above
winapp sign .\MyApp.msix .\prod.pfx --timestamp http://timestamp.digicert.com

--timestamp 属于 winapp sign，而非 winapp package。请使用经批准的时间戳服务，并妥善保护 PFX 和密码。

步骤 5：安装或分发

如果任务包含安装或测试，请根据 winui-ui-testing 步骤 1 选择目标，并取得在该计算机上信任证书和配置依赖项的许可。仅进行打包并不意味着获得了安装应用的许可。

自包含不等于单文件

winapp package --self-contained 仅设置 WindowsAppSDKSelfContained=true，不会设置 .NET 的 SelfContained=true。如需完全自包含的 JIT .NET 应用，请在项目中同时设置两者：

<PropertyGroup>
  <SelfContained>true</SelfContained>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
</PropertyGroup>

Native AOT 涵盖 .NET 运行时，但仍需选择 Windows App SDK。原生 WinUI 运行时文件会保留在可执行文件旁或程序包内；不要承诺提供单文件 WinUI EXE。某些 API 仍需要额外的 MSIX 依赖项；请参阅部署指南。

CI/CD

在配备 CLI 0.7+、应用的 .NET SDK，以及（对于 AOT）原生 C++ 工具链的 Windows 运行器上，打包步骤可以是：

winapp package .\MyApp.csproj --arch x64 --arch arm64 --no-sign
  • 已提交的包引用（包括分析器）可正常还原；无需机器本地的分析器。
  • 使用 CI 系统的制品步骤归档报告的 .msix/.msixbundle 输出。无需启动 UI 或进行开发注册。
  • 通过获批的机密存储获取生产签名材料，并在单独的受保护步骤中签名。切勿提交 PFX，也不要仅为构建而安装开发根证书。
Store 提交

将应用关联到其 Partner Center 标识，并遵循当前的提交要求（包验证、评级、屏幕截图、隐私政策）。当需要 Store 上传制品或拆分资源包时，请使用 SDK/Visual Studio 打包工作流。winapp package 会生成包制品；它不会发布到 Store，也不能替代该提交工作流。

故障排除
错误解决方案
"Publisher mismatch"运行 winapp cert generate --manifest 重新生成
"Certificate not trusted"以管理员身份运行 winapp cert install ./devcert.pfx
"Access denied"cert install 需要管理员权限
"Certificate file already exists"使用 --if-exists overwrite 或 --if-exists skip
清单缺失 / 布局覆盖被拒绝检查显式项目及其原始清单；不要使用 winapp init 或布局覆盖来绕过 SDK 打包
"Package installation failed"检查签名/信任以及确切冲突的标识；只有在确认并获授权后，才移除过时的注册
签名随时间失效使用 winapp sign --timestamp 通过获批的时间戳服务进行签名
参考资料
文件适用场景
references/sourcegen-patterns.md设置 AOT/裁剪、JSON 源生成器、Native AOT 就绪状态、CsWin32

评论

支持 Markdown