在 Visual Studio 中远程调试 Windows 设备上的 PC 项目

XBOX PC Toolbox 应用处于预览阶段。请从 Windows 上的 Microsoft Store 下载。

XBOX PC Remote 工具提供了将 Visual Studio 2022 调试器附加到远程 Windows 设备上运行的游戏的能力。开发 PC 与远程 Windows 设备之间的所有调试通信都经过加密。附加调试器的功能由 Visual Studio 2022 扩展提供,该扩展可在公共 Visual Studio marketplace 中获得。在调试之前,必须使用快速入门指南中描述的步骤对你的开发 PC 和远程 Windows 设备进行预配和配对。配对和预配之后,使用 Visual Studio 中的扩展管理器下载 XBOX PC Remote Debugger 扩展。配对和预配之后,使用 Visual Studio 中的扩展管理器下载 XBOX PC Remote Debugger 扩展。

在游戏项目中启用 F5 部署和调试

用于 Visual Studio 的 XBOX PC Remote Debugger 扩展支持完整的 “F5” 集成,可用于在远程 Windows 设备上部署和调试 C++ 项目。按 F5 会构建项目,可选择将其部署到远程设备,以挂起方式启动游戏,附加 XBOX PC Remote Debugger,然后在调试下恢复游戏。安装 XBOX PC Remote Debugger Visual Studio 扩展后,在使用 F5 远程部署和调试之前请确保:

必须使用快速入门指南中描述的步骤对你的开发 PC 和远程 Windows 设备进行预配和配对。
必须在远程设备上安装 Microsoft Visual Studio 调试监视器 (MSVSMON.EXE)。MSVSMON.EXE 由 XBOX PC Toolbox 应用程序自动安装。或者,可以在远程设备上从管理员提示符中使用 WinGet 完成安装:

   winget install Microsoft.VisualStudio.2022.OnecoreMsvsmon

wdEndpoint.exe 必须在远程设备上运行。wdEndpoint.exe 由 XBOX PC Toolbox 应用程序自动安装并启动。或者,可以从远程设备上的命令提示符中使用 Winget 完成安装:

   winget install Microsoft.Gaming.RemoteIterationEndpoint

通过 WinGet 安装 wdEndpoint.exe 后手动启动它。

向 MSBuild 项目添加 F5 远程调试支持

若要为使用 MSBuild 的项目启用 F5 集成,请将以下 XML 添加到 .vcxproj 文件中。将其放在最后一个 </ItemDefinitionGroup> 元素之后、源文件 <ItemGroup> 部分之前:

<ItemGroup>
  <ProjectCapability Include="Gaming.Xbox.PC.Remote" />
</ItemGroup>
<Import Condition="'$(XboxPCRemotePath)'!='' AND Exists('$(XboxPCRemotePath)XboxPCcppDebugger.props')"
  Project="$(XboxPCRemotePath)XboxPCcppDebugger.props" />
<ItemGroup>
  <PropertyPageSchema Condition="'$(XboxPCRemotePath)'!=''" Include="$(XboxPCRemotePath)XboxPCcppDebugger.xml" />
</ItemGroup>

最新版本的 Microsoft GDK 模板会在你创建新项目时提示你包含此集成。

若要启用部署,请转到 项目 > 属性 > 配置管理器,并勾选所需配置的部署选项。在按 F5 之前,通过调试工具栏或项目属性页将调试器设置为 XBOX PC Remote Debugger。有多个属性可用于配置部署和调试。

Remote Command Arguments。要传递给游戏的命令参数列表。
Deployment Directory。开发 PC 上要部署到远程 Windows 设备的目录。默认为 $(Outdir)。
Remote Folder。游戏在远程 Windows 设备上部署到的文件夹。该文件夹相对于 Common Root。有关 Common Root 的更多信息,请参阅 wdEndpoint.exe 主题。
Remote EndPoint Name。默认远程设备是开发者机器本身,与标准 Windows 远程调试相同。将 Remote EndPoint Name 更新为 wdEndpoint.exe 正在运行的设备名称。
File filter for deployment。用于指定应从部署中排除的文件集。例如,从部署中排除 .pdb 文件是常见做法。提供以分号分隔的要排除的文件模式列表,例如:*.pdb;*.ipdb;*.iobj;*.obj;*.pch;*。

在为你的配置选中部署复选框、选择 XBOX PC Remote Debugger 作为调试器类型并填写属性后,按 F5 将会构建你的游戏,将其部署到远程 Windows 设备,并在调试器下启动它。

你可能需要配置符号路径,以便 Visual Studio 能够找到游戏的符号。请通过工具菜单可访问的选项对话框上的调试设置进行操作。

F5 远程调试器每项目默认值

XBOX PC Remote Debugger 设置默认值由 XboxPCcppDebugger.props 文件设置,对 Visual Studio 项目属性对话框中的设置所做的任何编辑都会 “按用户” 保存在本地计算机上。若要让你的 vcxproj 提供其他默认值,以避免让每个用户在其计算机上进行设置,请按如下方式将其添加到 MSBuild 中:

<ItemGroup>
  <ProjectCapability Include="Gaming.Xbox.PC.Remote" />
</ItemGroup>
<Import Condition="'$(XboxPCRemotePath)'!='' AND Exists('$(XboxPCRemotePath)XboxPCcppDebugger.props')"
  Project="$(XboxPCRemotePath)XboxPCcppDebugger.props" />
<PropertyGroup>
  <RemoteGameshareFolder>MyGameTitle</RemoteGameshareFolder>
</PropertyGroup>
<ItemGroup>
  <PropertyPageSchema Condition="'$(XboxPCRemotePath)'!=''" Include="$(XboxPCRemotePath)XboxPCcppDebugger.xml" />
</ItemGroup>

Visual C++ 运行时 (CRT) 部署

为了让程序在远程计算机上运行,它需要 Visual C++ 运行时文件。对于零售 CRT,可以通过在远程计算机上安装 Visual C++ REDIST 包来完成。对于调试 CRT,这些文件必须随游戏一起部署。 MSBuild 中一个简单的解决方案是向项目的全局部分添加一个属性:

<CopyCppRuntimeToOutputDir>true</CopyCppRuntimeToOutputDir>

这会将 Visual C++ CRT 复制到 OutDir 中。如果 UseDebugLibraries 设置为 true,将使用调试版本,否则将使用零售版本。

向 CMake 项目添加 F5 远程调试支持

对于打开文件夹项目(例如 CMake 项目),F5 远程调试支持在 launch.vs.json 中配置,而不是在 .vcxproj 文件中。

安装 XBOX PC Remote Debugger 支持,并确保你的远程 Windows 设备已预配并运行 wdEndpoint.exe。
在 Visual Studio 中打开你的 CMake 项目文件夹。
在 解决方案资源管理器 中,右键单击 CMakeLists.txt 并选择 添加调试配置…。
选择 XBOX PC Remote Debugger Folder。

Visual Studio 会创建一个 .vs\launch.vs.json 文件,其中包含一个 Xbox PC Remote Debugger 启动配置。典型的配置如下所示:

   {
     "version": "0.2.1",
     "defaults": {},
     "configurations": [
       {
         "type": "default",
         "name": "MyGame.exe",
         "project": "CMakeLists.txt",
         "projectTarget": "MyGame.exe",
         "deployDirectory": "${workspaceRoot}\\out\\build\\x64-Release\\bin",
         "deployExcludeFilter": "*.pdb;*.ipdb;*.iobj;*.obj;*.pch;*.ilk;*.exp;*.lib;*.winmd;*.appxrecipe;*.log;*.tlog;*unsuccessfulbuild;*.lastbuildstate;*.copycomplete",
         "remoteGameshareFolder": "MyGame",
         "remoteMachineName": "MyROGAlly",
         "targetName": "MyGame.exe",
         "args": [],
         "deployType": "GamingXboxPCRemoteDeploy"
       }
     ]
   }

使用以下属性的值更新生成的配置:
- deployDirectory。包含要部署文件的本地输出文件夹。
- remoteGameshareFolder。要在远程设备上创建或使用的文件夹。
- remoteMachineName。wdEndpoint.exe 正在运行的远程设备的名称。
- targetName。部署后要启动的游戏可执行文件。
根据需要选择更新这些属性:
- deployExcludeFilter。以分号分隔的要从部署中排除的文件模式列表。
- args。游戏启动时要传递的命令行参数。
- disableDeploy。当你希望跳过部署,仅使用调试器启动或附加时,请设置此项。
在本地构建游戏,然后从调试器工具栏中选择 CMakeLists.txt,按 F5 将游戏部署到远程设备并在调试器下启动。

将 Visual Studio 调试器附加到远程 Windows 设备上运行的游戏

若要将调试器附加到远程设备上已在运行的游戏,请从 Visual Studio 的调试菜单中选择 附加到进程…。从 连接类型 下拉列表中选择 XBOX PC Remote Device,并在 连接目标 文本框中输入远程设备的 IP 地址或主机名。将显示远程设备上正在运行的进程列表。选择要调试的游戏并选择附加按钮。

另请参阅

XBOX PC Remote 工具

​在游戏项目中启用 F5 部署和调试

​向 MSBuild 项目添加 F5 远程调试支持

​F5 远程调试器每项目默认值

​Visual C++ 运行时 (CRT) 部署

​向 CMake 项目添加 F5 远程调试支持

​将 Visual Studio 调试器附加到远程 Windows 设备上运行的游戏

​另请参阅

在游戏项目中启用 F5 部署和调试

向 MSBuild 项目添加 F5 远程调试支持

F5 远程调试器每项目默认值

Visual C++ 运行时 (CRT) 部署

向 CMake 项目添加 F5 远程调试支持

将 Visual Studio 调试器附加到远程 Windows 设备上运行的游戏

另请参阅