生成包 (makepkg.exe)

项目
07/04/2024

创建应用包和应用包元数据。

makepkg 命令[/updcompat 3] [/pc] [/gameos <gameos file>] [/priorpackage <prior package file>] [/f <file name>] [/d <content directory>] [/pd <output directory>] [/l | /lk <secret_key.lekb>] [/contentid <ID>] [/productid <ProductIDGUID>] [/nocrashdump] [/resw <resw directory>] [/t <xml output directory>] [/v] [/?]

命令

genmap

根据目标文件夹的内容生成要与打包命令一起使用的 XML 文件。生成的文件将包含单个区块，可以编辑以拆分成区块或根据需要提供标签。

makepkg genmap /f <targetXmlFile> /d <contentdirectory>

genid

在产品 ID GUID 和 Store ID 之间转换。生成的 GUID 将与产品提交期间提供的产品 ID 匹配。产品 ID GUID 可以转换回 Store ID。

makepkg genid /storeid <storeId> | /productid <productId>

打包

从磁盘上的文件创建一个新的应用包。

makepkg pack /f <mapping file> /d <content directory> /pd <output package directory> /productid <ProductIDGUID> [/l | /lk <secret_key.lekb>]

通过添加在映射文件中指定的文件在输出包目录中创建一个应用包。例如，若要使用三个文件（a.txt、b.txt 和 game.exe）打包目录的内容，将使用以下映射文件：

<Package>
    <Chunk Id="1000" Marker="Launch">
        <FileGroup DestinationPath="\" SourcePath=".\" Include="a.txt"/>
        <FileGroup DestinationPath="\" SourcePath=".\" Include="b.txt"/>
        <FileGroup DestinationPath="\" SourcePath=".\" Include="game.exe"/>
    </Chunk>
</Package>

有关映射文件架构的说明，请参阅部署包架构。指定的内容目录 (/d) 必须包含名为 MicrosoftGame.config 的有效游戏配置文件。可在应用的 Visual Studio 项目中的生成输出目录中找到 MicrosoftGame.config 文件。有关游戏配置架构的说明，请参阅 MicrosoftGame.config 架构。

默认情况下，makepkg pack 使用所有开发工具包识别的已知加密密钥（也称为 /lt 加密开关）对包进行加密。不应将这些包视为受加密保护。若要保护包文件来实现安全上传，请使用 /lk<本地 EKB 文件>开关（建议用于主机的开发和提交）或 /l 开关，这将覆盖默认行为。

MakePkg.exe 将扫描包中的某些文件并将其移至特殊的注册区块中。这些文件包括 MicrosoftGame.config、MicrosoftGame.config 内引用的任何图像以及 Resources.pri（如果有）。

注意: 使用 makepkg localize，以生成 Resources.pri 文件。有关更高级方案的信息，请参阅有关生成包资源索引 (makepri.exe) 命令行工具的主题。
您可以通过在包含这些文件的区块的 ID 属性中指定“Registration”，在 layout.xml 文件中手动排列这些文件。

注意: Makepkg 拒绝包含可执行部分中的重新定位的二进制文件。这种重新定位要求在加载时对可执行部分进行修改，这可能造成在此期间对代码进行修改。出于此原因，如果为 makepkg 提供的二进制文件具有此特点，则 makepkg 将失败。防止出现该问题的一种常见方法是：在编译二进制文件时，避免将只读数据部分并入另一个可执行部分。

validate

运行验证步骤而不生成包。步骤包括运行提交验证器，这将生成用于记录包提交可能出现的问题的日志文件。采用与 makepkg pack 命令相同的参数，可选的映射文件除外。

makepkg validate [options] [/f <mapfile>] /d <sourcedir> /pd <destinationdir>

本地化

从内容目录中的 PNG 和 RESW 文件生成一个 Resources.pri 文件。目录中必须有一个 MicrosoftGame 文件，才能发现本地化的信息。此文件应指定用于 shell 本地化的语言定义和图像文件。得到的 Resources.pri 将放置在输出目录（如有）的根目录下，如果未提供输出目录，则放置在内容目录下。如果提供了临时目录，则 Resources.pri 文件的 XML 转换将在该临时目录下生成，以便手动验证。有关使用 Resources.pri 文件的详细信息，请参阅 MicrosoftGame.config 本地化。

makepkg localize [/d <content directory>] /pd <destinationdir> /resw <resw directory> /t <xml output directory> /gc <game config path>

genkey

生成本地托管密钥 blob (LEKB)。生成随机内容密钥并存储在 LEKB 文件中。

生成的 LEKB 与 makepkg pack /lk 加密开关一起使用。通常，将针对要拥有的每个信任边界使用 genkey。例如，可使用 genkey 一次，并在工作室范围内使用一个密钥，或者每个产品使用一个密钥，具体取决于谁应该有权访问包。

若要生成 LEKB，请执行以下操作：

makepkg genkey /ekb <The path to save the generated LEKB file.>

若要使用 LEKB 来加密包，请使用 /lk 加密开关：

makepkg pack /lk <The path to your LEKB file created by the genkey command.>

LEKB 文件应作为选项提供给 makepkg pack，供其在包创建期间使用稳定的加密密钥（/lk 加密）。它有 4 个主要优势：

packageutil 比较可以生成正确的更新大小估计（与 /l 不同）。
它可以使用主机和电脑下载内容更新时所用的算法，将增量安全上传到合作伙伴中心。（与 /l 不同）
可以将其安装到开发工具包上（与/ l不同）。
它使用安全的加密密钥材料，并且只能在特定的环境中解密（与 /lt 不同）。

LEKB 文件的内容仅进行过轻微的混淆处理。你有责任通过对 LEKB 文件进行访问保护来确保内容包的安全性。 任何通过 makepkg pack 处理 LEKB 文件和内容包文件输出的人员可解密其内容。

注意: 建议使用 genkey 为本地 EKB 文件创建的扩展名 .lekb，以便与 makepkg pack 生成的 .ekb 文件进行区分，其中“l”表示“本地创建”。

选项

选项	说明
/validationpath	指定用于加载 SubmissionValidator.dll 的路径。如果未指定此值，则将从 MakePkg.exe 所在的目录加载 SubmissionValidator.dll
/updcompat 3	与 pack 命令配合使用。 3 是唯一受支持的值，它使用子文件内容更新粒度。
/pc	与 pack 命令配合使用。可选参数，用于指示这是一个专用于电脑发布的 MSIXVC 包。使用此标志生成的包只能针对 Windows 10 电脑进行部署、测试或发布，而不适用于 Xbox 主机。
/priorpackage <之前的包文件>	与 pack 命令配合使用。可选参数，指定用于优化子文件内容更新的先前包文件。暗指 /updcompat 3。
/gameos <gameos 文件>	与 pack 命令配合使用。用于指定要嵌入包中的 gameos 文件的可选参数。如果未使用此参数，或者如果没有指定 gameos 文件，则需要在布局目录中的可执行文件旁边放入 GameOs.xvd 文件。
/storeid <storeId>	与 genid 命令配合使用。指定要使用的 Store ID。
/f <文件名>	指定输入文件。与 pack 或 validate 命令配合使用时，它指定映射文件。与 appdata 命令配合使用时，它指定应用程序清单文件。
/d <内容目录>	指定内容目录。指定的目录（如您项目的 layout\image\loose 目录）必须包含有效的 MicrosoftGame.config 文件。
/pd <输出目录>	指定输出目录。
/lk <lekbfile>	使用指定的 ekb 文件，并使用内容许可证对包加密。有关详细信息，请参阅 genkey 命令。默认情况下，makepkg pack 通过使用所有开发工具包可识别的用于测试目的的已知加密密钥来对包进行加密。 /lk 和 /l 开关都将覆盖默认行为。注意：提交包进行认证时，必须使用 /l 或 /lk，除非认证团队指示你执行其他操作。
/l	使用唯一的内容许可证对包加密。与 pack 命令配合使用。默认情况下，makepkg pack 通过使用所有开发工具包可识别的用于测试目的的已知加密密钥来对包进行加密。 /lk 和 /l 开关都将覆盖默认行为。注意：提交包进行认证时，必须使用 /l 或 /lk，除非认证团队指示你执行其他操作。
/contentid <ID>	用于指定此包所属的内容 ID 的可选参数。此 ID 是 GUID。如果此参数不存在或者指定的值为 00000000-0000-0000-0000-000000000000，则将使用基于包家族名称的稳定 GUID。此参数在您准备提交版本时不是必需的。它与 pack 命令配合使用。建议在每游戏产品的 makepkg 不通调用之间使此选项保持相同，以便使用 packageutil 比较实用程序来计算更新大小。
/productid <ProductIDGUID>	用于指定此包所属的产品 ID 的可选参数。 ID 是 GUID。如果此参数不存在，GUID 将为 00000000-0000-0000-0000-000000000000。此参数在您准备提交版本时不是必需的。它与 pack 和 genid 命令配合使用。当您想要枚举从刻录光盘安装的 DLC 包或当系统脱机运行时要包括的产品 ID。
/symbolpaths	允许在符号捆绑期间指定符号分辨率查找的更多路径。应将路径指定为分号分隔的列表。
/skipsymbolbundling	指定跳过符号捆绑步骤。我们不建议使用此标志。
/skipvalidation	指定跳过验证步骤。使用此标志时不生成提交验证器日志文件。对于可能提交认证的版本，我们不建议使用此标志，但它可以缩短本地迭代时间。
/validationcritical	指定提交验证器中的故障将被视为 MakePkg 进程的严重故障。
/validationlanguage	指定用于生成提交验证程序日志文件的其他语言。应使用 BCP-47 格式指定此语言，如果字符串资源可用，则会使用此目标语言生成第二个日志文件。当前支持的语言为日语 (ja-JP)、韩语 (ko-KR) 和简体中文 (zh-CN)。
/t	与 localize 命令一起使用。用于将 Resources.pri 内容转换为 XML 格式的可选目录。以 xml 格式查看 Resources.pri 的内容对于确保 Resources.pri 的内容是您所期望的内容十分方便。
/resw	与 localize 命令一起使用。相对于根目录的可选目录路径，如果直接根目录下不存在 RESW 文件，则这些文件包含在该路径中。
/gc	与本地化命令一起使用。如果 MicrosoftGame.config 文件没有位于内容目录的底部，或者有一个不同于 MicrosoftGame.config 的名称，则它的可选路径。
/v	支持使详细输出到主机。
/loggable	阻止包含不适合写入日志文件的控制字符的输出。例如，复制进度在非详细模式下使用滚动百分比，这会导致日志文件过大。
/?	显示帮助。

备注

当makepkg pack 运行时，会创建一个 Binary（二进制）包文件，被称为 Xbox Virtual Container (XVC)。用于主机的 XVC 文件扩展名为 .xvc，用于电脑的 XVC 文件扩展名为 .msixvc。除了扩展差异外，包名称中还添加了一个后缀以区分 Xbox One 系列包 (_x) 和 Xbox Series X|S 系列包 (_xs)。

运行 makepkg pack 或 makepkg validate 时，将执行一套验证测试。这些测试所需的时间取决于游戏大小和文件数。

验证测试的结果记录到一个 XML 文件，该文件位于与用于应用包输出的输出目录相同的目录。该日志列出为通过验证而必须为游戏纠正的所有错误。验证测试检查以往导致游戏延迟乃至后来被控制和认证过程拒绝的常见错误。

makepkg 设置以下退出代码：

退出代码	说明
0	成功
1	错误环境：内核驱动程序未安装；未在提升的命令提示符下运行
2	命令行无效
3	未能生成输出

更多详细信息也会记录到 stderr。

另请参阅

部署包架构

生成包资源索引 (makepri.exe)

MicrosoftGame.config

通过