将 MonoGame 桌面游戏发布至 Microsoft Store：完整的 MSIX 与 WAP 指南

将独立游戏带到 Windows 10 和 Windows 11 的 Microsoft Store，使开发者能够直接触达数以亿计的 PC 玩家，享受系统级自动更新、Windows Game Bar 集成以及容器化安装的安全优势。然而，如果您的游戏是基于 MonoGame（.NET 8.0 或 .NET 9.0 WindowsDX）构建的，将其引入商店需要一座架构桥梁：将传统的 Win32 可执行文件（.exe）与现代化的 MSIX / AppX 应用模型连接起来。

在 Arar Games，我们凭借 Paint Trek 和 Blocked: Pixel Panzer 两款作品走通了从代码编译到商店上线的全流程。本指南将全面拆解该工程管线：项目配置、Visual Studio 的 Publish 菜单选项解析、Package.appxmanifest 配置、磁贴图标尺寸缩放、解决 WACK 验证问题以及提交到 Microsoft Partner Center 的实战经验。

---

1. 架构基石：Win32 与 MSIX 对比

传统 MonoGame 游戏编译为标准的 Win32 应用程序，包含运行时 .dll 和存放已编译二进制资产（.xnb 纹理、.ogg 音频与着色器）的 Content/ 文件夹。

通过 Windows 应用打包 (WAP) 项目将其封装为 MSIX bundle 具有极高的技术价值：

flowchart TD
    subgraph Solution
        Shared["Shared Library"]
        Desktop["Desktop Project (.NET 9.0 WindowsDX)"]
        Shared --> Desktop
    end

    subgraph Packaging
        WAP["Windows App Packaging (.wapproj)"]
        Manifest["Package.appxmanifest"]
        StoreAssoc["Package.StoreAssociation.xml"]
        Desktop --> WAP
        Manifest --> WAP
        StoreAssoc --> WAP
    end

    subgraph Distribution
        WAP --> Sideload["Sideloading Package (*.appxbundle)"]
        WAP --> UploadBundle["Store Bundle (*_bundle.appxupload)"]
        UploadBundle --> MSStore["Microsoft Partner Center"]
    end

为什么选择 WAP 打包 MonoGame？

1. 隔离的容器化生命周期： MSIX 应用在沙盒虚拟环境中运行。卸载时会干净彻底地删除所有文件和虚拟注册表项，不留系统垃圾。
2. 动态架构与资源分发： 单个 .appxupload 包整合了 x86 和 x64 双架构及多种 DPI 缩放资源（scale-100 至 scale-400）。玩家仅下载适配自身设备的文件，大幅精简下载体积。
3. 自动化崩溃遥测： Visual Studio 会将调试符号（.appxsym）自动打包。当游戏在玩家设备上发生崩溃时，Partner Center 控制台能呈现包含具体行号的完整调用堆栈。

---

2. 项目组织与配置

在主游戏项目的 .csproj 中配置多架构和内容输出：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net9.0-windows</TargetFramework>
    <UseWindowsForms>true</UseWindowsForms>
    <Platforms>AnyCPU;x64;x86</Platforms>
  </PropertyGroup>
  <ItemGroup>
    <Content Include="Content\**\*.*">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </Content>
  </ItemGroup>
</Project>

还原 NuGet 包：

dotnet restore YourGame.Desktop.csproj -r win-x64
dotnet restore YourGame.Desktop.csproj -r win-x86

---

3. Visual Studio Publish 菜单详解

右键点击 WAP 项目选择 Publish 时可见三个功能：

1. Associate App with the Store...（将应用与商店关联）： 登录开发者账号并选择已保留的应用名称，自动拉取正式的 Publisher ID、Package Family Name 并生成 Package.StoreAssociation.xml。
2. Convert Content Group Map File（转换内容组映射文件）： 用于支持超大型游戏（50GB 以上）的流式渐进安装（Streaming Install）。独立游戏无需使用，可直接忽略。
3. Create App Packages...（创建应用程序包）： 主打包向导，用于生成本地测试安装包（Sideloading）或商店上架用的 _bundle.appxupload 包。

---

4. 打包向导配置实战

• 分发方式： 提交商店选择 "Microsoft Store under a new or existing app name"；本地 QA 测试选择 "Sideloading"。
• 架构选择： 勾选 ☑️ x86 与 ☑️ x64（Release 配置）。
• 捆绑包设置： Generate app bundle: Always。
• 版本号硬性规则： 遵循 Major.Minor.Build.Revision（如 1.0.0.0）。提交到 Partner Center 的新包版本号必须严格高于商店当前生效的版本。勾选 Automatically increment 可以在每次编译时自动递增最后一位修订号。

---

5. Package.appxmanifest 关键配置

• <rescap:Capability Name="runFullTrust" />：MonoGame 深度依赖 DirectX 11 和原生 Win32 调用，此受限功能赋予其完全桌面执行权限，同时兼具容器安装优势。
• InitialRotationPreference="landscape"：将屏幕锁定为横屏，适配 ASUS ROG Ally、联想 Legion Go 等 Windows 掌机。

---

6. 图标缩放规范与 BadgeLogo 避坑

Warning

锁屏角标 (BadgeLogo) 必须纯白： 锁屏图标必须仅由纯白像素 (#FFFFFF) 和透明通道组成。包含任何彩色像素都会导致 WACK 对比度合规检测失败。

---

7. WACK 验证与问题排查

• "AppCert.exe wasn't found" 报错： 在 Visual Studio Installer 的独立组件中搜索并安装 "Windows App Certification Kit"。本地运行 WACK 是可选的，上传至商店后台后微软云端会自动执行验证。
• MonoGame 资源误报 Blocked Executable： .xnb 或 .ogg 二进制可能随机匹配可执行特征。微软商店审核系统能识别其为合法静态游戏数据，不影响审核通过。

---

8. 本地侧载测试 (Sideloading)

在 AppPackages/YourGame_Test/ 目录下，以管理员身份运行 PowerShell：

Set-ExecutionPolicy RemoteSigned -Scope Process
.\Add-AppDevPackage.ps1

验证手柄控制、音频播放和 60 帧流畅度。

---

9. Microsoft Partner Center 提交流程

1. Pricing and availability： 选择全球 240 个市场，以美元设置基准价格。
2. Properties： 选择 Games 分类并提供有效的隐私政策网址（Privacy Policy URL）。
3. Age ratings： 完成 IARC 问卷评级（街机游戏通常获得 Everyone / PEGI 3）。
4. Store listings： 上传 1920x1080 纯 PC 实机截图（不可带有移动端触摸摇杆）。
5. Packages： 拖拽上传 _bundle.appxupload 文件，核对通过后点击 Submit to the Store。

---

结语

通过 WAP 项目封装、配置 runFullTrust 与 x86/x64 混合打包，MonoGame 开发者无需重写 UWP 即可将原生 .NET 9 桌面游戏推向全球 Windows 玩家！