使用 Visual Studio 调试 XBOX 项目

在 Visual Studio 中调试 XBOX Microsoft Game Development Kit (GDK) 项目由 XBOX Debugger 组件启用，该组件作为 Microsoft Game Development Kit (GDK) 的一部分安装。支持 Visual Studio 2019 和 2022。如以下截图所示，XBOX Debugger 是所有平台为 Gaming.Xbox.One.x64 或 Gaming.Xbox.Scarlett.x64 项目的默认调试器。

​

配置 Visual Studio 调试器

在 Visual Studio 中通过 F5 启动调试器时，默认使用通过其他 Microsoft Game Development Kit (GDK) 工具（例如 XBOX Manager 或 xbConnect）设置的默认主机。要覆盖此行为，可通过项目属性页面的 XBOX One 部分下的 Remote IP Address 属性指定一个主机，如下截图所示。 Visual Studio 中的调试工具栏包含一个下拉列表，用于指示通过 F5 或 Ctrl-F5 启动时 title 将部署到哪个主机。该下拉列表带有一个按钮，可在需要更改目标主机时快速访问项目属性页。 也可以从 XBOX Gaming Explorer 启动调试器。在此情况下，使用的主机为 XBOX Gaming Explorer 顶部连接功能区中标识的主机，如下截图所示。

​

符号路径

Game OS 若干组件的程序数据库 (.pdb) 文件在使用 Visual Studio 进行调试时可用。配置 Visual Studio 使用这些符号可在中断进入调试器时获得例如更完整的调用堆栈。 部分 Game OS 符号由 Microsoft Game Development Kit (GDK) 安装程序安装到你的开发 PC 上，另一部分可从 Microsoft 公共符号服务器获取。 由安装程序安装的 Game OS 符号位于开发 PC 上的 C:\Program Files (x86)\Microsoft GDK<edition number>\GXDK\gameKit\symbols。平台无关的 .pdb 位于符号文件夹的根目录，平台特定的 .pdb 位于 Xbox Series X|S 与 XboxOne 子目录中。 要将本地 PC 上 Game OS 符号目录的路径添加进去，可使用 Visual Studio Options 对话框 Debugging 部分下的 Symbols 设置，如下截图所示。 要访问 Microsoft 公共符号服务器上可用的 Game OS 符号，请在 Symbols 对话框中勾选 Microsoft Symbol Servers 复选框。将 Microsoft 符号服务器添加为符号文件位置会让 Visual Studio 在符号服务器上搜索你的 title 所加载的所有二进制文件。全面的符号搜索可能耗时较长。你可以配置 Visual Studio 只查找 title 所使用的特定二进制文件集合的 .pdb，从而缩短此搜索时间。要指定 Visual Studio 应在其中查找 .pdb 的二进制集合，可在 Options 对话框中使用 Load only specified modules 选项。以下截图显示了 Visual Studio 配置为仅为少数选定二进制文件从公共符号服务器加载符号。

​

与调试相关的属性

可以通过项目属性对话框以及 XBOX Gaming Explorer 的 Settings 选项卡中公开的一组属性进一步配置调试器。这些属性包括例如向你的 title 传递命令行参数以及开启日志模块加载等能力。有关可用属性的详情，请参见 Visual Studio Properties for XBOX Development 和 XBOX Gaming Explorer。

​

附加到正在运行的 title

XBOX 菜单以及 XBOX Gaming Explorer 都包含用于将调试器附加到主机上正在运行游戏的菜单选项。 要附加到当前正在你默认主机上运行的游戏，请使用 XBOX 菜单上的 Attach to Running Game。XBOX 菜单可从 Visual Studio 菜单栏访问，如下截图所示。 你也可以附加到已通过 XBOX Gaming Explorer 添加的任何主机上正在运行的游戏。Home 选项卡中 Game Processes 和 Titles 部分的上下文菜单都包含用于附加到运行中游戏的菜单项，如下截图所示。 Consoles 选项卡中特定主机的上下文菜单可用于附加到该主机上正在运行的游戏，如下截图所示。 Visual Studio Debug 菜单下的 Attach 对话框也可用于附加到正在运行的 title。使用 Visual Studio 2022 时，在 Connection Type 下拉列表中选择 XBOX Direct Connection，并在 Connection Target 文本框中输入主机的 Host IP 或 System IP 地址。Host 与 System IP 地址可以使用 xbconnect 命令行工具确定。 使用 Visual Studio 2019 时，在 Connection Type 下拉列表中选择 Remote No Authentication，并在 Connection Target 文本框中输入主机的 Host IP 地址。

​

使用 Visual Studio 2022 调试 XBOX 项目

使用 Visual Studio 2022 进行调试要求所调试的 title 是使用 2021 年 10 月（或更新版本）Microsoft Game Development Kit (GDK) 构建的。存在对 2021 年 10 月（或更新版本）Microsoft Game Development Kit (GDK) 的依赖，是因为这些 Microsoft Game Development Kit (GDK) 版本中附带的 Game OS 包含使用 Visual Studio 2022 调试所需的二进制文件。若在较旧的 Game OS 上尝试使用 Visual Studio 2022 调试，将会显示以下错误。

​

调试打包构建

XBOX Gaming Explorer 中用于在调试器下启动 title 或附加到运行中 title 的上下文菜单选项，对打包构建和松散文件部署同样有效。 流式安装包通过 XBOX Gaming Explorer 中的 Install 部署类型和图标进行识别，如下截图所示。

​

调试 Game Lifecycle 状态之间的转换

要正确支持 Game Lifecycle，需要为 full、suspended 和 constrained 生命周期状态之间的转换编写事件处理程序。Visual Studio 提供了多项功能，可帮助你编写让你的 title 成功通过 Game Lifecycle 状态转换所需的健壮事件处理程序。 XBOX Gaming Explorer 中的上下文菜单包含 Suspend、Resume 和 Constrain 你的 title 的选项，可让你在开发套件上调试自己的处理程序。 请注意，你也可以从 XBOX Manager 和 xbApp 命令行工具手动触发这些状态转换。 无论状态转换是如何触发的，描述该转换以及任何失败情况的诊断消息都可以在 xbWatson 以及 Visual Studio 内的 XBOX System Monitor 窗口中查看。 在零售环境中，Suspend 事件的处理程序必须在 1 秒内完成，否则系统会终止你的 title。此 suspend 时间限制显然不应始终在开发工具包上强制执行，否则调试 Suspend 处理程序将几乎不可能完成。 默认情况下，当 Visual Studio 调试器（或其他用户模式调试器）已附加时，1 秒的 suspend 超时会被禁用，让你有时间完成调试任务。 Visual Studio 调试器也可以配置为在附加时重新启用 suspend 超时。在此模式下，如果你的 Suspend 处理程序未在 1 秒内完成，调试器会强制中断，让你可以看到 suspend 时间限制到期时 Suspend 处理程序执行到了哪一步。以此模式运行调试器有助于了解你的 Suspend 处理程序超时的频率及原因。设置 Visual Studio 中的 Break On Suspend Timeout 属性可将调试器置于启用 suspend 超时的模式。此模式下发生的调试中断是在调试器注入到进程中的一个新线程上完成的。切换到包含 Suspend 处理程序的线程即可开始调试。 如果 suspend 超时发生时你的 title 没有附加调试器，系统会创建一个 quiesce 崩溃转储。这些转储可以使用 xbWatson 中的 Memory Dump 面板 访问。

​

Visual Studio 2022 中的 C++ Dynamic Debugging

C++ Dynamic Debugging 是一项新的调试功能，可在不牺牲性能的情况下为优化过的代码提供完整的调试体验。可在任意位置放置去优化断点，并按需对函数进行去优化以单步进入。要启用 C++ Dynamic Debugging：在你的项目上右键，Properties > Configuration Properties > Advanced > Advanced Properties > Use C++ Dynamic Debugging (preview)。使用动态调试功能需要 Visual Studio 2022 的 17.14 Preview 2 或更新版本。有关更多信息请访问 https://aka.ms/dynamicdebugging。

​

另请参阅

XBOX Gaming Explorer Visual Studio