MicrosoftGame.config 概述
MicrosoftGame.config 是一个清单文件，用于存储游戏特定的配置信息。 它在打包游戏期间使用，旨在通过 Microsoft Store 引入和发布，以及在游戏开发期间在松散文件版本的本地迭代过程中注册有关游戏的信息。
本主题介绍 MicrosoftGame.config 的用途和用法，以及它与 AppXManifest.xml 的关系。 它还说明了与在此版本的 Microsoft 游戏开发工具包 (GDK) 中使用 MicrosoftGame.config 相关的一些注意事项。
什么是 MicrosoftGame.config？
通过 Microsoft Store 分发的每个游戏都必须包含一个清单，其中至少声明了游戏的标识、发布者名称及一组游戏特定的 Shell 视觉对象（字符串、图标和图像），用于在 Microsoft Store 和 Shell（对于主机）以及“开始”菜单、任务栏及 Windows Shell（对于电脑）中的其他位置显示游戏的名称和图形表示。 此外，游戏还可以实现可选功能（如可下载内容 (DLC)），这些功能依赖于也存储在游戏清单中的配置值。 该清单文件的名称为 MicrosoftGame.config。
为什么创建新的清单架构？
Microsoft Store 中的每个包都包含一个名为 AppXManifest.xml 的清单。 该清单架构经过多年的演变，适合各种各样的应用程序功能和方案。
借助 MicrosoftGame.config，游戏开发者可以与更简单、以游戏为中心的清单架构 交互，该架构更易于访问、更不易出错且更高效。 当开发者打包或注册游戏时，工具会对 MicrosoftGame.config 的内容执行验证，并代表游戏开发者生成格式正确的 AppXManifest.xml。 生成的 AppXManifest 将包含在生成的包中。
注意
自 2022 年 3 月 Microsoft 游戏开发工具包 (GDK) 起，使用此 Microsoft 游戏开发工具包 (GDK) 和未来版本创建的新游戏的 Game configVersion 已从 0 更新为 1。 现存游戏可以选择加入此版本更新以利用这些改进。 有关更多信息，请参阅 MicrosoftGame.config 参考 (示例 MicrosoftGame.config 和架构)。
可用文档
在 Microsoft 游戏开发工具包 (GDK) (GDK.chm) 的离线文档文件中，可在下表中显示的位置找到有关 MicrosoftGame.config 的文档。
| 主题位置 | 所含内容 |
|---|---|
| MicrosoftGame.config | 提供有关 MicrosoftGame.config 及其在游戏注册和打包中的作用的概述信息 |
| MicrosoftGame.config 编辑器 | 提供可以更轻松地编辑 MicrosoftGame.config 文件，以及从其关联的合作伙伴中心项目自动同步标题 ID、名称和键值的 UI 工具概述 |
| 开发环境和工具 | 讨论如何使用 wdapp.exe 和 xbapp.exe（NDA 主题）要求授权注册松散文件版本和启动游戏 |
| 参考 | 提供示例 .config 和 MicrosoftGame.config 的架构的参考详细信息 |
| 打包 | 讨论如何使用 makepkg.exe 通过 MicrosoftGame.config 为主机和电脑生成包 |
MicrosoftGame.config 创建
在为 Gaming.Desktop.x64、Gaming.Xbox.XboxOne.x64 或 Gaming.Xbox.Scarlett.x64 平台创建新项目时，MicrosoftGameConfig.mgc 将与你在 Visual Studio 中的项目关联。 它将提供默认值，让你可以在电脑和 Xbox 上进行早期开发，在开始使用游戏运行时、Microsoft Store 和游戏标识中的功能之前无需进一步配置。
生成项目时，将 MicrosoftGameConfig.mgc 复制到项目的输出目录时重命名为 MicrosoftGame.config。
Xbox 的这个默认 MicrosoftGameConfig.mgc 的示例如下所示。
<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
<Identity Name="41336PublisherName.ExampleGame"
Publisher="CN=A4954634-DF4B-47C7-AB70-D3215D246AF1"
Version="1.6.0.0"/>
<ExecutableList>
<Executable Name="ExampleGame.exe"
Id="Game"/>
<!-- TargetDeviceFamily="XboxOne" Or "Scarlett" | TargetDeviceFamily specifies what device the executable was built for.
IsDevOnly="false" | IsDevOnly specifies if is a Development only executable.
OverrideDisplayName="Xbox Game Override"
OverrideLogo="GraphicsLogoOverride.png"
OverrideSquare44x44Logo="SmallLogoOverride.png"
OverrideSplashScreenImage="SplashScreenOverride.png" -->
</ExecutableList>
<ShellVisuals DefaultDisplayName="Example Game"
PublisherDisplayName="Example Publisher"
Square150x150Logo="GraphicsLogo.png"
Square44x44Logo="SmallLogo.png"
Description="Example Game"
ForegroundText="light"
BackgroundColor="#000040"
SplashScreenImage="SplashScreen.png"
StoreLogo="StoreLogo.png"/>
<!-- <MSAAppId>0000000000000000</MSAAppId> | Required if TitleId is specified and Game configVersion = 1 is specified in the MicrosoftGame.config -->
<!-- <TitleId>FFFFFFFF</TitleId> | Required if MSAAppId is specified and Game configVersion = 1 is specified in the MicrosoftGame.config -->
<!-- <StoreId>9NTL0QDWZ4FS</StoreId> | StoreID specifies the store identity of this title. Required in development so that commerce related APIs will function. -->
<!-- <Resources> | Resources is a list of Language Locale pairs used to localize Shell Visuals.
<Resource Language="en-us"/>
<Resource Language="de-de"/>
<Resource Language="es-mx"/>
</Resources> -->
<!-- <DevelopmentOnly> | DevelopmentOnly is a list of development-only properties.
<DebugNetworkPortList>
<DebugNetworkPort>4600</DebugNetworkPort> | DebugNetworkPort specifies an additional port to open for development on a Development Kit.
</DebugNetworkPortList>
</DevelopmentOnly> -->
<!-- <PersistentLocalStorage>
<SizeMB>322</SizeMB> | SizeMB specifies the size in MB of Persistent Local Storage.
</PersistentLocalStorage> -->
</Game>
有关 MicrosoftGame.config 元素的详细信息，请参阅在 MicrosoftGame.config 中找到的联机 GDK 文档，或者可以在脱机 GDK 文档的“系统”部分找到 MicrosoftGame.config 主题。
注意
如果手动将Microsoftgame.config文件添加到项目，则必须确保将文件属性更改为copy文件类型。
手动添加 MicrosoftGame.config 文件
也可以手动将一个或多个 MicrosoftGame.config 文件添加到项目中。 手动添加文件有两种方式：
- 通过在现有文件上设置适当的属性，以便 Visual Studio 将其识别为 MicrosoftGame.config 文件。
- 通过使用随附 Microsoft 游戏开发工具包 (GDK) C++ 项目系统提供的项模板。
要将现有文件用作 MicrosoftGame.config 文件，请执行以下操作：
- 将配置设置为“Gaming.Xbox.XboxOne.x64”、“Gaming.Xbox.Scarlett.x64”或“Gaming.Desktop.x64”平台。
- 将游戏的 MicrosoftGame.config 文件添加为 Visual Studio 项目中的文件。
- 在 MicrosoftGame.config 文件的属性中，将“项类型”设置为 Microsoft Game Config，如下所示。
要使用项目模板添加新 MicrosoftGameConfig.mgc 文件，请执行以下操作：
- 在项目上单击鼠标右键，然后选择“添加”->“新建项目”。
- MicrosoftGameConfig.mgc 模板可以在 Visual C++->游戏- >Microsoft 游戏开发工具包->树的版本节点中找到，如下所示。
MicrosoftGame.config 的 Visual Studio 项目属性
无论何时将 MicrosoftGameConfig.mgc 文件添加到项目中，是在创建项目时自动添加，还是手动添加，都会将属性 (MGCCompile) 添加到 Visual Studio 项目中。 项目系统使用 MGCCompile 属性自动执行以下操作：
- 生成 .pri 文件（如果你已本地化了字符串资源）
- 如有必要，将 MicrosoftGameConfig.mgc 文件重命名为 MicrosoftGame.config
- 将 MicrosoftGame.config 复制到输出文件夹
- 生成后注册 MicrosoftGame.config
- 在调试程序中使用标识启动游戏
添加此属性后，它应包含在 Visual Studio 项目文件中，并且可以在直接检查文件时被视为以下项组。
<ItemGroup>
<MGCCompile Include="MicrosoftGame.Config" />
</ItemGroup>
管理 Visual Studio 和 MSBuild 中的多个 MicrosoftGameConfig.mgc 文件
Microsoft 游戏开发工具包 (GDK) Visual Studio 项目可能有多个与之关联的 MicrosoftGameConfig.mgc 文件。 例如，为不同的生成配置或为 Xbox 和电脑生成使用不同的 MicrosoftGameConfig.mgc 文件是很常见的。 如果以前使用自定义生成逻辑来管理多个 MicrosoftGameConfig.mgc 文件，则项目系统现在直接支持这种情况。
MicrosoftGameConfig.mgc 文件可通过两种方式分配给各个生成配置。 首先，Xbox 游戏项目控件工具窗口支持管理多个 MicrosoftGame.config 文件（NDA 主题）要求授权，如下所示。
或者，可通过直接编辑项目文件将 MicrosoftGameConfig.mgc 文件分配给配置。 使用 MGCCompile 属性的 DefaultApplyTo 元素指定默认的 MicrosoftGameConfig.mgc 文件。 除非显式重写，否则此默认文件将用于所有配置。 使用 MGCCompile 属性的 ApplyTo 元素将配置文件分配给特定的生成配置。
项目文件 a 中的以下代码段将 MicrosoftGameConfig_dev.mgc 指定为默认配置文件。 将 MicrosoftGameConfig_dev.mgc 用于除 Release 之外的所有生成配置，已为其指定替代 (MicrosoftGameConfig_release.mgc)。
<ItemGroup>
<MGCCompile Include="MicrosoftGameConfig_release.mgc">
<ApplyTo Condition="'$(Configuration)|$(Platform)'=='Release|Gaming.Xbox.XboxOne.x64'">True</ApplyTo>
</MGCCompile>
<MGCCompile Include="MicrosoftGameConfig_dev.mgc">
<DefaultApplyTo">True</DefaultApplyTo>
</MGCCompile>
</ItemGroup>
对 MicrosoftGame.config 的 IntelliSense 支持
Visual Studio 中的 MicrosoftGame.config 修改现在支持 IntelliSense 功能。 这样可获得其他见解，如以下两个屏幕截图中所示。
创建元素时自动列出有效的元素名称。
如果存在无效元素或无效元素值，则会出现警告。
MicrosoftGame.config 的平台要求
为游戏创建 MicrosoftGame.config 文件时，需要为每个 Microsoft 游戏开发工具包 (GDK) 平台（Gaming.Xbox.XboxOne.x64、Gaming.Xbox.Scarlett.x64 和 Gaming.Desktop.x64）都创建一个文件。 要确保存储在 MicrosoftGame.config 中的元素值与为其生成可执行文件的平台是一对一的映射，这是必需的。 它主要由 TargetDeviceFamily 属性（MicrosoftGame.config 文件中的 Executable 元素）指定。 有关详细信息，请参阅参考主题中的其他元素详细信息部分。
当你启动游戏时，它将根据平台要求、启动游戏的设备和可执行文件类型以不同的方式运行，如下表所示。
| MicrosoftGame.config 状态 | TargetDeviceFamily 设置 | 启动设备 | 操作 | 说明 |
|---|---|---|---|---|
| 否 | Xbox 系列 X\|S | Xbox 系列 X\|S | 在 Xbox Series X 开发工具包上以本机方式启动 | |
| 是 | Xbox 系列 X\|S | Xbox One | 返回一个指示在启动设备上启动了错误平台的错误 (0x887e0002) | |
| 否 | XboxOne | Xbox 系列 X\|S | 在 Xbox 系列 X 开发工具包上通过 Microsoft 游戏开发工具包 （GDK） 后向兼容 VM 启动 | |
| 否 | XboxOne | Xbox One | 在 Xbox One 开发工具包上以本机方式启动 | |
| 否 | 未定义 | Xbox 系列 X\|S | 在 Xbox Series X 开发工具包上以本机方式启动 | |
| 否 | 未定义 | Xbox One | 在 Xbox One 开发工具包上以本机方式启动 | |
| 是 | 不适用 | Xbox 系列 X\|S | 在 Xbox Series X 开发工具包上以本机方式启动 | |
| 否 | N/A | XboxOne | 在 Xbox One 开发工具包上以本机方式启动 | |
| 否 | 电脑 | 电脑 | 在电脑上以具有标识的 Win32 x64 的形式启动 | |
| 否 | 未定义 | 电脑 | 在电脑上以具有标识的 Win32 x64 的形式启动 | |
| 是 | N/A | 电脑 | 在电脑上以无标识的 Win32 x64 的形式启动 |
注意
如果在没有 MicrosoftGame.config 的情况下在 Xbox Series X 开发工具包上启动 Xbox Series X|S 游戏，该游戏将重复使用现有的 Microsoft 游戏开发工具包 (GDK) VM 状态（如果适用）。 例如，如果在尝试启动 Xbox Series X|S 本机游戏之前启动了后向兼容 Microsoft 游戏开发工具包 (GDK) 游戏（Xbox Series X|S 上的 Xbox One），则该游戏将使用相同的后向兼容 Microsoft 游戏开发工具包 (GDK) VM 运行。 建议使用配置了 TargetDeviceFamily 的 MicrosoftGame.config，以便在你遇到此情况时指示正确的意图。 ERA 游戏将以单独的 VM 状态运行，因此在这种情况下不会影响 Microsoft 游戏开发工具包 (GDK) VM 行为。
在 Visual Studio 外部创建和编辑 MicrosoftGame.config
如上所述，Visual Studio 提供了许多方法来创建和管理游戏的 MicrosoftGame.config 文件。 除了在 Visual Studio 中创建和编辑外，还有一个独立工具可以直接提供 MicrosoftGame.config 的创建和创作。
此 MicrosoftGame.config 编辑器 是可更轻松地编写和编辑 .config 文件的 UI 工具。 此编辑器还包括通过应用商店关联向导自动向下拉取和同步信息 (如 TitleId、MSAAppId 和 StoreId) 的合作伙伴中心中标题信息的挂钩。 欢迎提供反馈，因此请使用编辑器内的建议工具来告知你的想法。
在没有 MicrosoftGame.config 的情况下启动游戏
在 Microsoft 游戏开发工具包 (GDK) 中，无需提供 MicrosoftGame.config 即可启动电脑游戏或 Xbox 游戏。 当你想要在游戏运行时、Microsoft Store 和游戏标识内选择功能时，这样做可以在创建 MicrosoftGame.config 之前进行早期开发，从而拥有更多的灵活性。 要通过 Microsoft 游戏开发工具包 (GDK) 交付游戏，在提交到 Microsoft Store 之前需要使用 MicrosoftGame.config 创建游戏包。 建议在开始开发需要游戏运行时、Xbox 服务、Microsoft Store 或游戏标识的功能时，立即采用并配置游戏的 MicrosoftGame.config。
可通过双击生成的可执行文件来生成和启动没有 MicrosoftGame.config 的电脑游戏。 它们将在不集成游戏运行时功能时运行。 为支持游戏运行时功能、游戏标识、MSIXVC 打包和提交到 Microsoft Store 的功能，需要 MicrosoftGame.config。
没有 MicrosoftGame.config 的 Xbox 游戏将能够利用 Microsoft 游戏开发工具包 (GDK) 工具来部署松散文件版本，并启动、调试和利用现成的游戏核心功能子集。 若要支持完整的 Microsoft 游戏开发工具包 (GDK) 功能、游戏标识、XVC 打包支持和提交到 Microsoft Store 的功能，将需要 MicrosoftGame.config。
要在 Xbox 上在没有 MicrosoftGame.config 的情况下启动游戏，你可以：
- xbapp.exe（NDA 主题）要求授权启动。
- 利用 Xbox One 管理器的部署/启动功能。
- 从 Xbox 上的开发人员主页（开发者主页）启动游戏。
有关启动 Win32 电脑游戏的详细信息，请参阅以下部分。
启动 Win32 游戏
不使用游戏运行时或游戏云服务的 Win32 电脑游戏可以像任何其他 Windows 可执行文件一样启动和/或调试。 只需用鼠标单击游戏可执行文件，或者直接在命令提示符窗口中运行可执行文件，即可创建游戏进程。
游戏服务代表游戏执行工作。 要使用游戏运行时或游戏云服务，游戏必须提供上下文数据。 例如，游戏可以向 Xbox 服务传递一个唯一标识符（称为游戏标识），使服务可以确定哪个游戏正在向玩家授予成就。 游戏标识等上下文信息可通过名为注册的进程永久存储在 Windows 应用存储库中。 通过注册，游戏还可指定 Windows Shell 在“开始”菜单的应用程序列表中应使用哪些字符串和徽标来表示游戏。
通过名为应用启动的操作，可创建游戏进程，并允许游戏访问其在应用存储库中的持久上下文信息。 如果你未对游戏进行应用启动，则将创建一个进程来运行游戏，但其上下文将不可用。 这将使游戏无法正常使用游戏运行时和游戏云服务。
你可以通过以下任一方式对游戏进行应用启动。
- “开始”菜单（应用列表、应用磁贴）
- 任务栏搜索（搜索结果列表/详细信息面板）
- wdapp.exe launch
- Windows 设备门户 (WDP)：已安装的应用>开始
调试 Win32 游戏
在 Microsoft 游戏开发工具包 (GDK) 中，当选择 F5 生成并运行时，Win32 电脑游戏将经过注册和应用启动路径。 这使此工作流与 Xbox 上存在的同一标准保持一致。
对于在 Win32 电脑上调试安装的应用包，如果游戏的清单名为 MicrosoftGame.config，则 Visual Studio 中的“调试安装的应用包”功能不会将游戏添加到其可调试包列表中。只有在可执行文件的文件夹中存在名为 AppXManifest.xml 的文件时，“调试安装的应用包”功能才会将游戏识别为包。 要解决此问题，你可以创建一个包含游戏的有效值的简单 AppXManifest，然后使用可执行文件和 MicrosoftGame.config 将其手动保存在文件夹中。
另请参阅
MicrosoftGame.config
MicrosoftGame.config 本地化
MicrosoftGame.config 编辑器
MicrosoftGame.config 参考（示例 MicrosoftGame.config 和架构）
包装概述