> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MicrosoftGame.config 概述

> MicrosoftGame.config 概述

*MicrosoftGame.config* 是一个用于存储游戏特定配置信息的清单文件。它在打包你的游戏以便通过 Microsoft Store 引入和发布时使用，也用于在游戏开发过程中对松散文件构建进行本地迭代时注册游戏信息。

本主题介绍 *MicrosoftGame.config* 的目的和用法，以及它与 *AppXManifest.xml* 的关系。本主题还介绍了与本版本 Microsoft Game Development Kit (GDK) 中 *MicrosoftGame.config* 使用相关的一些注意事项。

## 什么是 MicrosoftGame.config？

通过 Microsoft Store 分发的每款游戏必须包含一个清单文件，该清单文件至少声明标题的身份、发布者名称，以及一组用于在 Microsoft Store 和 Shell（对于主机）以及"开始"菜单、任务栏和 Windows Shell 中的其他位置（对于 PC）显示游戏名称和图形表示的标题特定 Shell 视觉元素（字符串、图标和图像）。此外，游戏可以实现可选功能，例如可下载内容 (DLC)，这些功能依赖于同样存储在游戏清单中的配置值。清单文件的名称是 *MicrosoftGame.config*。

## 为什么创建新的清单架构？

Microsoft Store 中的每个包都包含一个名为 *AppXManifest.xml* 的清单。其架构多年来不断演变，以适应广泛的应用程序功能和场景。

使用 *MicrosoftGame.config*，游戏开发者可与更简单、[以游戏为中心的清单架构](/reference/system/microsoftgameconfig/microsoftgameconfig-schema)交互，该架构更易于使用、更不易出错并且更高效。当开发者打包或注册游戏时，工具会对 *MicrosoftGame.config* 的内容进行验证，并代表游戏开发者生成格式正确的 *AppXManifest.xml*。生成的 `AppXManifest` 会包含在结果包中。

<Note>从 2022 年 3 月 Microsoft Game Development Kit (GDK) 开始，对于使用此 Microsoft Game Development Kit (GDK) 及未来版本创建的新标题，Game configVersion 已从 0 更新为 1。现有标题可选择升级到此版本以利用这些改进。有关更多信息，请参阅 [MicrosoftGame.config 参考（示例 MicrosoftGame.config 和架构）](/reference/system/microsoftgameconfig/microsoftgameconfig-schema)。</Note>

## 可用文档

在 Microsoft Game Development Kit (GDK) 的离线文档文件 (GDK.chm) 中，你可以在下表所示的位置找到有关 *MicrosoftGame.config* 的文档。

| 主题位置                                                                                           | 涵盖内容                                                                                                                                                                                                                                |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-toc)        | 提供有关 *MicrosoftGame.config* 及其在游戏注册和打包中作用的概述信息                                                                                                                                                                                      |
| [MicrosoftGame.config 编辑器](/build/core-features/common/game-config/MicrosoftGameConfig-Editor) | 提供了 UI 工具的概述，该工具可以更方便地编辑 *MicrosoftGame.config* 文件，并可以自动从其关联的合作伙伴中心项目同步标题 ID、名称和关键值                                                                                                                                                 |
| [开发环境和工具](https://learn.microsoft.com/build/archive/gc-tools-toc)                              | 讨论使用 [wdapp.exe](/tools/tools-pc/commandlinetools/gr-wdapp) 和 [xbapp.exe（NDA 主题）](/tools/tools-console/commandlinetools/xbapp) 注册松散文件构建并启动你的游戏                                                                                      |
| [参考](/reference/gc-reference-toc)                                                              | 提供有关 *MicrosoftGame.config* 的示例 .config 和架构的[参考详细信息](/reference/system/microsoftgameconfig/microsoftgameconfig-schema)                                                                                                              |
| [打包](/build/core-features/common/packaging/overviews/packaging)                                | 讨论使用 makepkg.exe 通过 *MicrosoftGame.config* 为[主机](/build/core-features/common/packaging/overviews/packaging-getting-started-for-console)和 [PC](/build/core-features/common/packaging/overviews/packaging-getting-started-for-PC) 生成包 |

## MicrosoftGame.config 创建

在为 Gaming.Desktop.x64、Gaming.Xbox.XboxOne.x64 或 Gaming.Xbox.Scarlett.x64 平台创建新项目时，Visual Studio 中会将一个 *MicrosoftGameConfig.mgc* 与你的项目关联。它具有默认值，允许在 PC 和 XBOX 上进行早期开发，无需进一步配置，直到你开始使用 Gaming Runtime、Microsoft Store 和标题身份中的功能。

构建项目时，*MicrosoftGameConfig.mgc* 在被复制到项目的输出目录时会重命名为 *MicrosoftGame.config*。

以下是 XBOX 的默认 *MicrosoftGameConfig.mgc* 示例。

```xml theme={null}
<?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](/build/core-features/common/game-config/MicrosoftGameConfig-toc) 的在线 GDK 文档，或者你可以在离线 GDK 文档的"System"部分找到 MicrosoftGame.config 主题。

<Note>如果你手动向项目添加 *Microsoftgame.config* 文件，必须确保将文件属性更改为 `copy` 文件类型。</Note>

### 手动添加 MicrosoftGame.config 文件

也可以手动向你的项目添加一个或多个 MicrosoftGame.config 文件。手动添加文件可以通过两种方式完成：

* 在现有文件上设置适当的属性，以便 Visual Studio 将其识别为 MicrosoftGame.config 文件。
* 使用 Microsoft Game Development Kit (GDK) C++ 项目系统提供的项模板。

要将现有文件用作 MicrosoftGame.config 文件：

* 将配置设置为 "Gaming.Xbox.XboxOne.x64"、"Gaming.Xbox.Scarlett.x64" 或 "Gaming.Desktop.x64" 平台。
* 将游戏的 *MicrosoftGame.config* 文件作为文件添加到 Visual Studio 项目中。
* 在 *MicrosoftGame.config* 文件的属性中，将"项类型"设置为 **Microsoft Game Config**，如下所示。

<img src="https://mintcdn.com/microsoft-4404708b/sIrPFR_ir_sNKVEv/images/gdk/features/common/MGCCompile.png?fit=max&auto=format&n=sIrPFR_ir_sNKVEv&q=85&s=6053672114c61f34e722e5f12a9adae0" alt="向项目添加 MGCCompile 项类型" width="983" height="212" data-path="images/gdk/features/common/MGCCompile.png" />

要使用项模板添加新的 *MicrosoftGameConfig.mgc* 文件：

* 右键单击项目并选择"添加"->"新建项"。
* MicrosoftGameConfig.mgc 模板可以在 Visual C++->Gaming->Microsoft Game Development Kit->Edition 节点的树下找到，如下所示。

<img src="https://mintcdn.com/microsoft-4404708b/sIrPFR_ir_sNKVEv/images/gdk/features/common/GameConfig_ItemTemplate.png?fit=max&auto=format&n=sIrPFR_ir_sNKVEv&q=85&s=4a7921430d30b8c9d212864a5cabf176" alt="MicrosoftGame.config 项模板" width="800" height="470" data-path="images/gdk/features/common/GameConfig_ItemTemplate.png" />

### MicrosoftGame.config 的 Visual Studio 项目属性

每当 *MicrosoftGameConfig.mgc* 文件被添加到项目中时（无论是在创建项目时自动添加还是手动添加），都会将一个属性 (`MGCCompile`) 添加到你的 Visual Studio 项目中。项目系统使用 `MGCCompile` 属性自动执行以下操作：

* 如果你有本地化字符串资源，则生成 .pri 文件
* 如有必要，将 *MicrosoftGameConfig.mgc* 文件重命名为 *MicrosoftGame.config*
* 将你的 *MicrosoftGame.config* 复制到输出文件夹
* 构建后注册你的 *MicrosoftGame.config*
* 在调试器中以身份启动你的游戏

添加此属性后，它应包含在你的 Visual Studio 项目文件中，并且在直接检查文件时可以看到以下项组。

```xml theme={null}
  <ItemGroup>
    <MGCCompile Include="MicrosoftGame.Config" />
  </ItemGroup>
```

### 在 Visual Studio 和 MSBuild 中管理多个 MicrosoftGameConfig.mgc 文件

Microsoft Game Development Kit (GDK) Visual Studio 项目可能关联了多个 MicrosoftGameConfig.mgc 文件。例如，对不同的构建配置或对 XBOX 和 PC 构建使用不同的 MicrosoftGameConfig.mgc 文件是很常见的。如果你之前使用自定义构建逻辑来管理多个 MicrosoftGameConfig.mgc 文件，此场景现在由项目系统直接支持。

MicrosoftGameConfig.mgc 文件可以通过两种方式分配给各个构建配置。首先，**XBOX Gaming Project Control 工具窗口**支持[管理多个 MicrosoftGameConfig.mgc 文件（NDA 主题）](/tools/tools-console/visualstudio/xbox-gaming-project-control#multiple_game_configs)，如下所示。

<img src="https://mintcdn.com/microsoft-4404708b/CwRBzaXvHw9zaPoe/images/gdk/features/common/vs_pgc_mgc_default.png?fit=max&auto=format&n=CwRBzaXvHw9zaPoe&q=85&s=ef008f86df2e81369e1b4f81f8cea2b5" alt="在 XBOX Project Gaming Control 中管理多个 MicrosoftGameConfig.mgc 文件" width="1178" height="513" data-path="images/gdk/features/common/vs_pgc_mgc_default.png" />

或者，可以通过直接编辑项目文件将 MicrosoftGameConfig.mgc 文件分配给配置。使用 `MGCCompile` 属性的 `DefaultApplyTo` 元素指定默认的 MicrosoftGameConfig.mgc 文件。此默认文件将用于所有配置，除非显式覆盖。使用 `MGCCompile` 属性的 `ApplyTo` 元素将配置文件分配给特定的构建配置。

以下项目文件片段将 MicrosoftGameConfig\_dev.mgc 指定为默认配置文件。MicrosoftGameConfig\_dev.mgc 将用于除 *Release* 之外的所有构建配置，*Release* 已指定为覆盖 (MicrosoftGameConfig\_release.mgc)。

```xml theme={null}
<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](https://learn.microsoft.com/visualstudio/ide/using-intellisense) 功能。这允许以下两个屏幕截图所示的额外洞察。

在编写元素时会自动列出有效的元素名称。

<img src="https://mintcdn.com/microsoft-4404708b/sIrPFR_ir_sNKVEv/images/gdk/features/common/GameConfig_IntelliSense.png?fit=max&auto=format&n=sIrPFR_ir_sNKVEv&q=85&s=c11cb20b0ffc64762331daa5b29ada9e" alt="MicrosoftGame.config 的 IntelliSense 示例：编写元素时会自动列出有效的元素名称" width="388" height="242" data-path="images/gdk/features/common/GameConfig_IntelliSense.png" />

当存在无效元素或无效元素值时会显示警告。

<img src="https://mintcdn.com/microsoft-4404708b/sIrPFR_ir_sNKVEv/images/gdk/features/common/GameConfig_IntelliSense2.png?fit=max&auto=format&n=sIrPFR_ir_sNKVEv&q=85&s=c0a076b64a1494d6f586bf0bc624bff1" alt="MicrosoftGame.config 的 IntelliSense 示例：存在无效元素或无效元素值时会显示警告" width="977" height="80" data-path="images/gdk/features/common/GameConfig_IntelliSense2.png" />

### MicrosoftGame.config 的平台要求

在为你的标题创建 *MicrosoftGame.config* 文件时，需要为每个 Microsoft Game Development Kit (GDK) 平台（Gaming.Xbox.XboxOne.x64、Gaming.Xbox.Scarlett.x64 和 Gaming.Desktop.x64）创建一个。这是为了确保存储在 *MicrosoftGame.config* 中的元素值与构建可执行文件所针对的平台一一对应。这主要由 *MicrosoftGame.config* 文件中 `Executable` 元素中的 `TargetDeviceFamily` 属性指定。有关更多信息，请参阅参考主题中的[其他元素详细信息](/reference/system/microsoftgameconfig/microsoftgameconfig-schema)部分。

启动标题时，其行为会根据平台要求、启动标题的设备和可执行文件类型而有所不同，如下表所示。

| MicrosoftGame.config 存在情况 | TargetDeviceFamily 设置 | 启动设备             | 行为                                                                       | 备注 |
| ------------------------- | --------------------- | ---------------- | ------------------------------------------------------------------------ | -- |
| 是                         | XBOX Series X\|S      | XBOX Series X\|S | 在 XBOX Series X 开发工具包上原生启动                                               |    |
| 是                         | XBOX Series X\|S      | XBOX One         | 返回错误 (0x887e0002)，指示在启动设备上启动了错误的平台                                       |    |
| 是                         | XboxOne               | XBOX Series X\|S | 在 XBOX Series X 开发工具包上使用 Microsoft Game Development Kit (GDK) 向后兼容 VM 启动 |    |
| 是                         | XboxOne               | XBOX One         | 在 XBOX One 开发工具包上原生启动                                                    |    |
| 是                         | 未定义                   | XBOX Series X\|S | 在 XBOX Series X 开发工具包上原生启动                                               |    |
| 是                         | 未定义                   | XBOX One         | 在 XBOX One 开发工具包上原生启动                                                    |    |
| 否                         | 不适用                   | XBOX Series X\|S | 在 XBOX Series X 开发工具包上原生启动                                               |    |
| 否                         | 不适用                   | XboxOne          | 在 XBOX One 开发工具包上原生启动                                                    |    |
| 是                         | PC                    | PC               | 在 PC 上作为带身份的 Win32 x64 启动                                                |    |
| 是                         | 未定义                   | PC               | 在 PC 上作为带身份的 Win32 x64 启动                                                |    |
| 否                         | 不适用                   | PC               | 在 PC 上作为不带身份的 Win32 x64 启动                                               |    |

<Note>在没有 MicrosoftGame.config 的情况下 XBOX Series X|S 标题在 XBOX Series X 开发工具包上启动时，如果适用，它将重用现有的 Microsoft Game Development Kit (GDK) VM 状态。例如，如果向后兼容的 Microsoft Game Development Kit (GDK) 标题（XBOX Series X|S 上的 XBOX One）在尝试启动 XBOX Series X|S 原生标题之前已启动，它将使用同一个向后兼容的 Microsoft Game Development Kit (GDK) VM 运行。如果你遇到此场景，建议使用配置了 TargetDeviceFamily 的 MicrosoftGame.config 以指示正确的意图。ERA 标题将在单独的 VM 状态下运行，因此不会在此场景中影响 Microsoft Game Development Kit (GDK) VM 行为。</Note>

### 在 Visual Studio 之外创建和编辑 MicrosoftGame.config

如上所述，Visual Studio 提供了许多方法来创建和管理你标题的 MicrosoftGame.config 文件。除了在 Visual Studio 中创建和编辑之外，还有一个独立工具可以直接创建和编写 MicrosoftGame.config。

[MicrosoftGame.config 编辑器](/build/core-features/common/game-config/MicrosoftGameConfig-Editor)是一个 UI 工具，可以更方便地编写和编辑 .config 文件。此编辑器还包含通过"商店关联向导"连接到合作伙伴中心中你的标题信息的钩子，可自动拉取和同步信息，例如你的 TitleId、MSAAppId 和 StoreId。欢迎反馈，请使用编辑器内的建议工具告诉我们你的想法。

## 不使用 MicrosoftGame.config 启动游戏

在 Microsoft Game Development Kit (GDK) 中，你可以在不存在 *MicrosoftGame.config* 的情况下启动 PC 游戏或 XBOX 游戏。这允许在创建 *MicrosoftGame.config* 之前进行早期开发，旨在为你何时选择加入 Gaming Runtime、Microsoft Store 和标题身份中的功能提供灵活性。要使用 Microsoft Game Development Kit (GDK) 发布标题，需要 *MicrosoftGame.config* 才能创建标题包，然后再提交到 Microsoft Store。建议在你开始开发需要 Gaming Runtime、XBOX services、Microsoft Store 或标题身份的功能时，就立即采用并配置你标题的 *MicrosoftGame.config*。

没有 *MicrosoftGame.config* 的 PC 游戏可以通过双击构建的可执行文件进行构建和启动。它们将在不集成 Gaming Runtime 功能的情况下运行。要支持 Gaming Runtime 功能、标题身份、MSIXVC 打包支持以及提交到 Microsoft Store 的能力，需要 *MicrosoftGame.config*。

没有 *MicrosoftGame.config* 的 XBOX 游戏将能够利用 GDK 工具直接部署松散文件构建、启动、调试并使用 Microsoft Game Development Kit (GDK) 功能的子集。要支持完整的 Microsoft Game Development Kit (GDK) 功能、标题身份、XVC 打包支持以及提交到 Microsoft Store 的能力，需要 *MicrosoftGame.config*。

要在 XBOX 上不使用 *MicrosoftGame.config* 启动你的标题，你可以：

* 使用 [xbapp.exe（NDA 主题）](/tools/tools-console/commandlinetools/xbapp) 启动。
* 使用 XBOX Manager 部署/启动功能。
* 从 XBOX 上的 Developer Home (Dev Home) 启动标题。

有关启动 Win32 PC 游戏的更多信息，请参阅以下部分。

<a id="MSGC-PCLaunch" />

## 启动 Win32 游戏

不使用 Gaming Runtime 或游戏云服务的 Win32 PC 游戏可以像任何其他 Windows 可执行文件一样启动和/或调试。只需用鼠标单击游戏可执行文件或直接在命令提示符窗口中运行可执行文件，游戏进程就会创建。

游戏服务代表游戏执行工作。要使用 Gaming Runtime 或游戏云服务，游戏必须提供上下文数据。例如，游戏可以将一个称为标题身份的唯一标识符传递给 XBOX services，从而使该服务能够识别哪个游戏正在向玩家授予成就。像标题身份这样的上下文信息可以通过一个称为"注册"的过程持久存储在 Windows App 存储库中。通过注册，游戏还可以指定 Windows Shell 应使用哪些字符串和徽标在"开始"菜单的应用程序列表中表示游戏。

通过称为"应用启动"的操作，游戏进程被创建，游戏可以访问从应用存储库中获得的持久上下文信息。如果你不通过应用启动方式启动游戏，则会创建一个进程来运行游戏，但其上下文将不可用。这会阻止游戏正确使用 Gaming Runtime 和游戏云服务。

你可以通过以下任何一种方式应用启动你的游戏。

* "开始"菜单（应用列表、应用磁贴）
* 任务栏搜索（搜索结果列表/详细信息面板）
* [wdapp.exe](/tools/tools-pc/commandlinetools/gr-wdapp) 启动
* Windows Device Portal (WDP)：**已安装的应用** > **启动**

## 调试 Win32 游戏

在 Microsoft Game Development Kit (GDK) 中，当选择 F5 进行构建和运行时，Win32 PC 游戏会经过注册和应用启动路径。这使此工作流程达到了 XBOX 上存在的相同标准。

关于在 Win32 PC 上"调试已安装的应用包"，如果你的游戏清单被命名为 *MicrosoftGame.config*，则 Visual Studio 中的"调试已安装的应用包"不会将你的游戏添加到其可调试的包列表中。仅当在包含可执行文件的文件夹中存在名为 *AppXManifest.xml* 的文件时，"调试已安装的应用包"才会将你的游戏识别为包。为了解决这个问题，你可以创建一个简单的 `AppXManifest`，包含游戏的有效值，并手动将其保存在包含可执行文件和 *MicrosoftGame.config* 的文件夹中。

## 另请参阅

[MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-toc)
[MicrosoftGame.config 本地化](/build/core-features/common/game-config/MicrosoftGameConfig-Localization)
[MicrosoftGame.config 编辑器](/build/core-features/common/game-config/MicrosoftGameConfig-Editor)
[MicrosoftGame.config 参考（示例 MicrosoftGame.config 和架构）](/reference/system/microsoftgameconfig/microsoftgameconfig-schema)
[打包概述](/build/core-features/common/packaging/overviews/packaging)


## Related topics

- [MicrosoftGame.config 本地化](/zh-CN/build/core-features/common/game-config/MicrosoftGameConfig-Localization.md)
- [MicrosoftGame.config 编辑器](/zh-CN/build/core-features/common/game-config/MicrosoftGameConfig-Editor.md)
- [MicrosoftGame.config](/zh-CN/build/core-features/common/game-config/MicrosoftGameConfig-toc.md)
- [XtfStartTitleOSByGameConfig](/zh-CN/reference/tools/xtf/xtfapi/functions/xtfstarttitleosbygameconfig-xtfapi-xbox-windows-m.md)
- [PC 端口行为](/zh-CN/build/console-features/networking/game-mesh/pc-port-behavior.md)