winui-packaging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quick Reference

快速参考

Task	Command
Build for release	`.\BuildAndRun.ps1 /p:Configuration=Release`
Package + sign	`winapp package <dir> --cert devcert.pfx`
Generate + sign + package	`winapp package <dir> --generate-cert --install-cert`
Generate dev certificate	`winapp cert generate`
Trust certificate (admin)	`winapp cert install ./devcert.pfx`
Sign existing file	`winapp sign ./app.msix ./devcert.pfx`
Self-contained deployment	`winapp package <dir> --cert devcert.pfx --self-contained`

任务	命令
构建发布版本	`.\BuildAndRun.ps1 /p:Configuration=Release`
打包 + 签名	`winapp package <dir> --cert devcert.pfx`
生成证书 + 签名 + 打包	`winapp package <dir> --generate-cert --install-cert`
生成开发证书	`winapp cert generate`
信任证书（管理员权限）	`winapp cert install ./devcert.pfx`
签名已有文件	`winapp sign ./app.msix ./devcert.pfx`
独立部署	`winapp package <dir> --cert devcert.pfx --self-contained`

End-to-End Workflow

端到端工作流程

Step 1: Build for Release

步骤1：构建发布版本

Use the BuildAndRun.ps1 script from the

winui-dev-workflow

skill to build your app in Release configuration without launching it:

powershell

.\BuildAndRun.ps1 /p:Configuration=Release -SkipRun

使用

winui-dev-workflow

技能中的BuildAndRun.ps1脚本，以Release配置构建应用但不启动：

powershell

.\BuildAndRun.ps1 /p:Configuration=Release -SkipRun

Step 2: Generate Certificate (one-time)

步骤2：生成证书（一次性操作）

powershell

winapp cert generate --manifest .

Creates

devcert.pfx

(default password:

password

). The

--manifest

flag auto-matches the

Publisher

field in

Package.appxmanifest

powershell

winapp cert generate --manifest .

生成

devcert.pfx

文件（默认密码：

password

）。

--manifest

参数会自动匹配

Package.appxmanifest

中的

Publisher

字段。

Step 3: Trust Certificate (one-time, requires admin)

步骤3：信任证书（一次性操作，需管理员权限）

powershell

winapp cert install ./devcert.pfx

Adds cert to machine Trusted Root store. Persists across reboots.

powershell

winapp cert install ./devcert.pfx

将证书添加到机器的受信任根证书存储区，重启后依然有效。

Step 4: Package and Sign

步骤4：打包并签名

powershell

winapp package <build-output-dir> --cert ./devcert.pfx

This locates

appxmanifest.xml

, stages the layout, generates

resources.pri

, creates

.msix

, and signs it.

powershell

winapp package <build-output-dir> --cert ./devcert.pfx

该命令会定位

appxmanifest.xml

、准备布局、生成

resources.pri

、创建

.msix

文件并完成签名。

Step 5: Install or Distribute

步骤5：安装或分发

powershell

undefined

powershell

undefined

Local install

本地安装

Add-AppxPackage ./MyApp.msix

Or double-click the .msix file

或双击.msix文件

undefined

undefined

Key Rules

关键规则

Publisher must match between certificate and manifest
```
Identity.Publisher
```
— use
```
winapp cert generate --manifest
```
to auto-match
Prefer
winapp package --cert
over separate
```
winapp sign
```
— one step instead of two
cert install
requires admin — run terminal as Administrator
Default PFX password is
```
password
```
— override with
```
--password
```

--timestamp
is critical for production — without it, signatures expire with the cert:

powershell

winapp package <dir> --cert prod.pfx --timestamp http://timestamp.digicert.com

--self-contained
bundles Windows App SDK runtime — larger but no runtime dependency

发布者信息必须匹配：证书与清单
```
Identity.Publisher
```
中的发布者信息需一致——使用
```
winapp cert generate --manifest
```
可自动匹配
优先使用
winapp package --cert
：相比单独执行
```
winapp sign
```
，一步完成打包和签名
cert install
需要管理员权限：需以管理员身份运行终端
默认PFX密码为
```
password
```
：可通过
```
--password
```
参数覆盖
--timestamp
对生产环境至关重要：如果不添加该参数，签名会随证书过期而失效：
powershell
```
winapp package <dir> --cert prod.pfx --timestamp http://timestamp.digicert.com
```
**
```
--self-contained
```
**会捆绑Windows App SDK运行时：安装包体积更大，但无需依赖外部运行时

CI/CD with GitHub Actions

基于GitHub Actions的CI/CD流程

yaml

name: Build and Package
on: [push]
jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: microsoft/setup-WinAppCli@v0.1

      - name: Build
        run: dotnet build -c Release -p:Platform=x64

      - name: Package
        run: |
          winapp cert generate --if-exists skip --quiet
          winapp package ./bin/x64/Release/ --cert ./devcert.pfx --quiet

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: msix-package
          path: "*.msix"

CI/CD tips:

Use
```
--quiet
```
for clean output
Use
```
--if-exists skip
```
with
```
cert generate
```
to avoid failures on re-runs
Store production PFX as a repository secret

yaml

name: Build and Package
on: [push]
jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: microsoft/setup-WinAppCli@v0.1

      - name: Build
        run: dotnet build -c Release -p:Platform=x64

      - name: Package
        run: |
          winapp cert generate --if-exists skip --quiet
          winapp package ./bin/x64/Release/ --cert ./devcert.pfx --quiet

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: msix-package
          path: "*.msix"

CI/CD提示：

使用
```
--quiet
```
参数获得简洁输出
在
```
cert generate
```
中使用
```
--if-exists skip
```
避免重复运行时失败
将生产环境PFX文件存储为仓库密钥

Store Submission

Microsoft Store提交流程

Partner Center account — register at partner.microsoft.com
Age ratings — complete the questionnaire in Partner Center
Screenshots — capture at 1366x768 minimum resolution
Privacy policy — required for apps that access internet or user data
Submit: upload the signed
```
.msix
```
/
```
.msixbundle
```
produced by
```
winapp package
```
via Microsoft Partner Center — Apps and games → your app → Packages. Microsoft Store submission is browser-based; there is no first-party CLI submit command yet.

合作伙伴中心账户——前往partner.microsoft.com注册
年龄分级——在合作伙伴中心完成问卷
截图——捕获分辨率不低于1366x768的截图
隐私政策——访问互联网或用户数据的应用必须提供隐私政策
提交：通过Microsoft合作伙伴中心上传由
```
winapp package
```
生成的已签名
```
.msix
```
/
```
.msixbundle
```
文件——进入“应用和游戏”→你的应用→“包”。Microsoft Store提交目前仅支持浏览器操作，暂无官方CLI提交命令。

Troubleshooting

故障排查

Error	Solution
"Publisher mismatch"	Run `winapp cert generate --manifest` to re-generate
"Certificate not trusted"	Run `winapp cert install ./devcert.pfx` as admin
"Access denied"	`cert install` needs admin elevation
"Certificate file already exists"	Use `--if-exists overwrite` or `--if-exists skip`
"appxmanifest.xml not found"	Run `winapp init` or pass `--manifest <path>`
"Package installation failed"	Trust cert first; remove stale: `Get-AppxPackage <name> \| Remove-AppxPackage`
Signature invalid after time	Re-sign with `--timestamp`

错误	解决方案
“发布者信息不匹配”	运行 `winapp cert generate --manifest` 重新生成证书
“证书未被信任”	以管理员身份运行 `winapp cert install ./devcert.pfx`
“访问被拒绝”	`cert install` 需要管理员权限
“证书文件已存在”	使用 `--if-exists overwrite` 或 `--if-exists skip` 参数
“未找到appxmanifest.xml”	运行 `winapp init` 或通过 `--manifest <path>` 指定路径
“包安装失败”	先信任证书；移除旧版本：`Get-AppxPackage <name>
签名随时间失效	使用 `--timestamp` 参数重新签名

References

参考资料

File	Read when...
`references/sourcegen-patterns.md`	Setting up AOT/trimming, JSON source generators, NativeAOT readiness, CsWin32

文件	适用场景
`references/sourcegen-patterns.md`	配置AOT/裁剪、JSON源生成器、NativeAOT就绪、CsWin32时阅读