用 GDK 给 PC 打 MSIXVC 包

July 24, 2024About 5 min

用 GDK 给 PC 打 MSIXVC 包

微软商店的 PC 包是 MSIXVC 格式,靠 GDK 里的 MakePkg 工具生成。核心三步:写 MicrosoftGame.config、用 MakePkg genmap 生成 layout、用 MakePkg validate/pack 校验并打包。

官方文档:https://learn.microsoft.com/en-us/gaming/gdk/docs/features/common/packaging/overviews/packaging-getting-started-for-pc

Warning

SubmissionValidator.dll 在 GDK\bin 下。
要提交给微软的版本,打包前 SubmissionValidator.dll 必须是最新的,去 Xbox Developer Downloads → GDK → Submission Validator 下。
GDK 装完没有这个 dll 也去同一处下载。

前置检查

确认目标 Windows 10 版本满足 GDK 的最低要求(比如 GDK Feb 版要求 18362 以上)。查版本:win+R → winver。

准备内容

把所有源材料放一个目录,移除不兼容 MSIXVC 或不该进零售包的文件:

PDB 文件
UWP/Appx 的 footprint 文件,包括 AppxSignature.p7x、AppxBlockMap.xml(以前发过 UWP 版会带这些,必须删)
任何指向其他 PC 商店的引用:资源、二进制等

MicrosoftGame.config

在游戏根目录建 MicrosoftGame.config。从 Partner Center 的 Package Setup → Identity 拿四个值填进去:Package/Identity/Name、Package/Identity/Publisher、Package/Properties/PublisherDisplayName、Store ID。模板:

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="0">

  <Identity Name='REPLACE:<Package/Identity/Name>' Version="0.0.84.0" Publisher='REPLACE:<Package/Identity/Publisher>' />
  <TitleId>REPLACE:<Title ID (hexadecimal)></TitleId>
  <!-- The fourth digit of the version number is reserved for Microsoft Store use -->
  <!-- Optional: Use StoreId if your product will offer durable DLC packages.
       Look up the Store ID (12 character alphanumeric string) of your main application package. (Example: 9PNX12345AAA)
  -->
  <StoreId>REPLACE:<Store ID></StoreId>

  <!-- Include any additional languages your title supports -->
  <Resources>
    <Resource Language="en-US" />
    <Resource Language="ja-JP" />
    <Resource Language="fr-FR" />
    <Resource Language="es-ES" />
    <Resource Language="de-DE" />
    <Resource Language="it-IT" />
    <Resource Language="ko-KR" />
    <Resource Language="zh-TW" />
  </Resources>

  <ExecutableList>
    <Executable Name="REPLACE:<Executable Name>"
                Id="App"
                OverrideDisplayName="REPLACE"/>
  </ExecutableList>

  <!-- Asset sizes: StoreLogo 100x100, Square150x150Logo 150x150,
       Square44x44Logo 44x44, SplashScreenImage 1920x1080 or 3840x2160 -->
  <ShellVisuals DefaultDisplayName="REPLACE:<Package/Identity/Name>"
                PublisherDisplayName="REPLACE:<Package/Identity/Publisher>"
                StoreLogo="StoreLogo.png"
                Square150x150Logo="Logo.png"
                Square44x44Logo="SmallLogo.png"
                Description="REPLACE"
                ForegroundText="light"
                BackgroundColor="#464646"
                SplashScreenImage="SplashScreen.png"/>

  <DesktopRegistration>
    <!-- 需要首次运行以管理员权限跑自定义安装动作时用 CustomInstallActions,
         指定的 exe 必须放在游戏根目录下的 Installers 文件夹里
    <CustomInstallActions>
      <Folder>Installers</Folder>
      <InstallActionList>
        <InstallAction File="CustomInstaller.exe" Name="UniqueInstallTaskName" Arguments="/silent /example" />
      </InstallActionList>
    </CustomInstallActions>
    -->
    <DependencyList>
      <!-- 不需要可整段省略;VCLibs 版本以实际为准 -->
      <Dependency Name="Microsoft.VCLibs.110.00.UWPDesktop" MinVersion="11.0.61135.0"/>
    </DependencyList>
    <ProcessorArchitecture>x64</ProcessorArchitecture>

    <!-- 启用 mod 时取消注释,Name 改成你游戏唯一的值
    <ModFolder Name="REPLACE_MyGameName"/> -->

    <!-- 仅当游戏需要做系统级注册表/文件写入时才取消注释
    <DisableRegistryWriteVirtualization>true</DisableRegistryWriteVirtualization>
    <DisableFilesystemWriteVirtualization>true</DisableFilesystemWriteVirtualization>
    -->

    <!-- 用到 Xbox Live 多人邀请时
    <MultiplayerProtocol>true</MultiplayerProtocol>
    -->
  </DesktopRegistration>

  <!-- 游戏会往安装目录写文件、又改不了源码时
  <ExtendedAttributeList>
    <ExtendedAttribute Name="RestrictedCapability" Value="packageWriteRedirectionCompatibilityShim"/>
  </ExtendedAttributeList>
  -->
</Game>

准备图标和 VC 运行库

检查包对 Visual C/C++ 运行库的依赖,把它们列进 MicrosoftGame.config 的 DependencyList 或直接拷进 payload。按 ShellVisuals 里列的尺寸,把对应图标放进游戏根目录。

装 GDK,配 MakePkg

GDK 命令提示符默认在 C:\Program Files (x86)\Microsoft GDK\Command Prompts。建议把 C:\Program Files (x86)\Microsoft GDK\bin 加进环境变量 Path。

生成 layout 映射

在含游戏内容单一目录的上层打开 GDK 命令提示符:

MakePkg genmap /f layout.xml /d <Your_game_folder>

layout.xml 的名字随意。注意它不能包含 pdb、UWP footprint 文件或指向其他商店的引用,且必须包含 MicrosoftGame.config、各图标 png(SplashScreen / Logo / SmallLogo / StoreLogo / WideLogo)。生成后可手动调整 Chunk 分组(下例按数据子目录拆 chunk,实现分块流式下载):

<Package>
  <Chunk Id="1000" Marker="Launch">
    <FileGroup DestinationPath="\" Include="*.dll" SourcePath=".\"/>
    <FileGroup DestinationPath="\" Include="*.png" SourcePath=".\"/>
    <FileGroup DestinationPath="\" Include="*.exe" SourcePath=".\"/>
    <FileGroup DestinationPath="\" Include="*.config" SourcePath=".\"/>
    <FileGroup DestinationPath="\" Include="*.dat" SourcePath=".\"/>
    <FileGroup DestinationPath="\data" SourcePath=".\data" Include="*.*" />
  </Chunk>
  <Chunk Id="1073741823">
    <FileGroup DestinationPath="\" Include="Update.AlignmentChunk" SourcePath=".\"/>
  </Chunk>
</Package>

符号文件

为了让微软能更好归类 RETAIL 的崩溃 dump,准备一个 symbol 文件夹,打成 zip,包含 exe、dll 以及对应的 pdb。符号文件夹结构要和游戏文件夹一致。

校验与打包

先 validate,确认 <Output_Folder> 里的 Validator_xxx.xml 没有 <failure> 节点:

MakePkg validate /f layout.xml /lt /d <Your_game_folder> /nogameos /pc /pd <Output_Folder> /ContentId 00000000-0000-0000-0000-000000000001 /symbolpaths <your_symbol_folder>

再 pack:

MakePkg pack /f layout.xml /lt /d <Your_game_folder> /nogameos /pc /pd <Output_Folder> /ContentId 00000000-0000-0000-0000-000000000001 /symbolpaths <your_symbol_folder>

ContentId 可以换成你自己的 GUID 或整个省略,仅用于开发。算内容更新大小时,比较的两个包必须用同一个 GUID。

Warning

用了 /ContentId,装新版前必须先 wdapp uninstall <Last_Version_package_name> 卸掉旧版。

安装测试

目标 PC 先开发者模式:设置 → 搜 Developer → Use developer features → Developer mode,等它装完功能。然后:

Wdapp install <Your_Package.msixvc>

包必须在本地盘或映射成盘符的网络位置,UNC 共享暂不支持。看不到进度可以去 Microsoft Store 的 Downloads and updates 里看。某些 Insider 版本有 wdapp 不显示进度的 bug,可临时用 PowerShell 的 add-appxpackage <Your_Package.msixvc> 顶一下(但它不支持 Intelligent Delivery 相关特性)。

提交前最终打包

之前用 /LT 是开发密钥加密,不能用于提交。最终提交要用 /L 重新打,用唯一密钥加密。这个包不能 sideload 测试,所以要用和 sideload 测试包完全相同的内容来跑。提交校验器过期时去 http://aka.ms/xgddl(Xbox One Software → Submission Validator)下最新版。

几个进阶点

写数据:MSIXVC 是只读卷,存档/设置要写用户 AppData,改不了源码就用 packageWriteRedirectionCompatibilityShim 受限能力自动重定向。
框架包依赖:依赖的 redist 若在商店里有框架包(如 Microsoft.DirectXRuntime),用 DependencyList 声明依赖比 chain-install redist 更好,商店能自动更新。
受限能力:Mod、CustomInstallActions、关写虚拟化、写安装目录这几类能力,除了配 config,还要邮件你的 Account Manager 开权限。