> ## 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.

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

> 通过 GDK 应用商店扩展进行部署和调试,将 Visual Studio 2022 调试器附加到远程 Windows 计算机上运行的 PC 游戏版本。

<Info>XBOX PC Toolbox 应用处于预览阶段。请从 Windows 上的 [Microsoft Store](https://aka.ms/toolboxinstaller) 下载。</Info>

[XBOX PC Remote 工具](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/remote-gamedev-tools) 提供了将 Visual Studio 2022 调试器附加到远程 Windows 设备上运行的游戏的能力。开发 PC 与远程 Windows 设备之间的所有调试通信都经过加密。附加调试器的功能由 [Visual Studio 2022 扩展](https://marketplace.visualstudio.com/items?itemName=XboxGDK.Microsoft-Xbox-PC-Remote-Debugger) 提供,该扩展可在公共 Visual Studio marketplace 中获得。

在调试之前,必须使用 [快速入门指南](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/tutorials/get-started-with-remote-devices/remote-win-gamedev-quickstart) 中描述的步骤对你的开发 PC 和远程 Windows 设备进行预配和配对。

配对和预配之后,使用 [Visual Studio 中的扩展管理器](https://learn.microsoft.com/visualstudio/ide/finding-and-using-visual-studio-extensions?view=visualstudio) 下载 XBOX PC Remote Debugger 扩展。
配对和预配之后,使用 [Visual Studio 中的扩展管理器](https://aka.ms/XboxPCRemoteDebugger) 下载 XBOX PC Remote Debugger 扩展。

<img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/gdk/tools/xbox_pc_remote_debugger_extension.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=b5beb1a3b79d24e2963ece62f6bbfe6d" alt="Visual Studio Marketplace 中的 XBOX PC Remote Debugger 扩展" width="1152" height="386" data-path="images/gdk/tools/xbox_pc_remote_debugger_extension.png" />

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

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

安装 [XBOX PC Remote Debugger Visual Studio 扩展](https://marketplace.visualstudio.com/items?itemName=XboxGDK.Microsoft-Xbox-PC-Remote-Debugger) 后,在使用 F5 远程部署和调试之前请确保:

1. 必须使用 [快速入门指南](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/tutorials/get-started-with-remote-devices/remote-win-gamedev-quickstart) 中描述的步骤对你的开发 PC 和远程 Windows 设备进行预配和配对。

2. 必须在远程设备上安装 Microsoft Visual Studio 调试监视器 (`MSVSMON.EXE`)。`MSVSMON.EXE` 由 [XBOX PC Toolbox 应用程序](/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) 自动安装。或者,可以在远程设备上从管理员提示符中使用 WinGet 完成安装:

```
   winget install Microsoft.VisualStudio.2022.OnecoreMsvsmon
```

3. [`wdEndpoint.exe`](/tools/tools-pc/commandlinetools/gr-wdEndpoint) 必须在远程设备上运行。`wdEndpoint.exe` 由 [XBOX PC Toolbox 应用程序](/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) 自动安装并启动。或者,可以从远程设备上的命令提示符中使用 Winget 完成安装:

```
   winget install Microsoft.Gaming.RemoteIterationEndpoint 
```

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

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

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

```xml theme={null}
<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>
```

<Note>最新版本的 [Microsoft GDK 模板](https://aka.ms/gdktemplates) 会在你创建新项目时提示你包含此集成。</Note>

<img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/gdk/tools/xbox_pc_remote_debugger_template_prompt.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=a620c5d24191e498dba4589f65921d57" alt="在新项目中启用远程调试的提示" width="879" height="567" data-path="images/gdk/tools/xbox_pc_remote_debugger_template_prompt.png" />

若要启用部署,请转到 **项目 > 属性 > 配置管理器**,并勾选所需配置的 **部署** 选项。

<img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/gdk/tools/xbox_pc_remote_debugger_deploy_checkbox.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=ba9f7ae896391e1f7e9415b60f472c40" alt="为配置启用部署" width="696" height="435" data-path="images/gdk/tools/xbox_pc_remote_debugger_deploy_checkbox.png" />

在按 **F5** 之前,通过调试工具栏或项目属性页将调试器设置为 **XBOX PC Remote Debugger**。有多个属性可用于配置部署和调试。

<img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/gdk/tools/xbox_pc_remote_debugger_property_page.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=12b098d60639fc9733dd2c9bf4e3ee50" alt="XBOX PC Remote Debugger 属性" width="792" height="544" data-path="images/gdk/tools/xbox_pc_remote_debugger_property_page.png" />

* `Remote Command Arguments`。要传递给游戏的命令参数列表。

* `Deployment Directory`。开发 PC 上要部署到远程 Windows 设备的目录。默认为 `$(Outdir)`。

* `Remote Folder`。游戏在远程 Windows 设备上部署到的文件夹。该文件夹相对于 *Common Root*。有关 *Common Root* 的更多信息,请参阅 [`wdEndpoint.exe`](/tools/tools-pc/commandlinetools/gr-wdEndpoint) 主题。

* `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 设备,并在调试器下启动它。

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

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

XBOX PC Remote Debugger 设置默认值由 `XboxPCcppDebugger.props` 文件设置,对 Visual Studio 项目属性对话框中的设置所做的任何编辑都会 “按用户” 保存在本地计算机上。

若要让你的 vcxproj 提供其他默认值,以避免让每个用户在其计算机上进行设置,请按如下方式将其添加到 MSBuild 中:

```xml theme={null}
<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 中一个简单的解决方案是向项目的全局部分添加一个属性:

```xml theme={null}
<CopyCppRuntimeToOutputDir>true</CopyCppRuntimeToOutputDir>
```

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

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

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

1. 安装 XBOX PC Remote Debugger 支持,并确保你的远程 Windows 设备已预配并运行 `wdEndpoint.exe`。

2. 在 Visual Studio 中打开你的 CMake 项目文件夹。

3. 在 **解决方案资源管理器** 中,右键单击 **CMakeLists.txt** 并选择 **添加调试配置…**。

4. 选择 **XBOX PC Remote Debugger Folder**。

<img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/gdk/tools/xbox_pc_remote_debugger_cmake_debug_configuration.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=f4f1ad1f89fb057f614d8f163a37d99d" alt="向 CMake 项目添加调试配置" width="869" height="569" data-path="images/gdk/tools/xbox_pc_remote_debugger_cmake_debug_configuration.png" />

Visual Studio 会创建一个 `.vs\launch.vs.json` 文件,其中包含一个 `Xbox PC Remote Debugger` 启动配置。

典型的配置如下所示:

```json theme={null}
   {
     "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"
       }
     ]
   }
```

5. 使用以下属性的值更新生成的配置:

   * `deployDirectory`。包含要部署文件的本地输出文件夹。

   * `remoteGameshareFolder`。要在远程设备上创建或使用的文件夹。

   * `remoteMachineName`。`wdEndpoint.exe` 正在运行的远程设备的名称。

   * `targetName`。部署后要启动的游戏可执行文件。

6. 根据需要选择更新这些属性:

   * `deployExcludeFilter`。以分号分隔的要从部署中排除的文件模式列表。

   * `args`。游戏启动时要传递的命令行参数。

   * `disableDeploy`。当你希望跳过部署,仅使用调试器启动或附加时,请设置此项。

7. 在本地构建游戏,然后从调试器工具栏中选择 **CMakeLists.txt**,按 **F5** 将游戏部署到远程设备并在调试器下启动。

<img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/gdk/tools/xbox_pc_remote_debugger_cmake_debug_toolbar.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=c0a5c9d225c7a0c1433e18e3bc8fa646" alt="从调试器工具栏选择 CMakeLists.txt" width="684" height="92" data-path="images/gdk/tools/xbox_pc_remote_debugger_cmake_debug_toolbar.png" />

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

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

<img src="https://mintcdn.com/microsoft-4404708b/5IpvKlT-jmAaVkeY/images/gdk/tools/xbox_pc_remote_debugger_attach.png?fit=max&auto=format&n=5IpvKlT-jmAaVkeY&q=85&s=9af2fa1ec8dcaf6e5709e9a074ce951e" alt="附加对话框(已选择正确的传输)的图片" width="936" height="692" data-path="images/gdk/tools/xbox_pc_remote_debugger_attach.png" />

## 另请参阅

[XBOX PC Remote 工具](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/remote-gamedev-tools)


## Related topics

- [使用 Visual Studio 调试 PC 项目](/zh-CN/tools/tools-pc/visualstudio/gr-vs-debugging-with-visualstudio.md)
- [XBOX PC Remote Tools](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/index.md)
- [Visual Studio](/zh-CN/tools/tools-pc/visualstudio/index.md)
- [Visual Studio(目录)](/zh-CN/tools/tools-pc/visualstudio/gr-visualstudio-toc.md)
- [XBOX PC Remote 工具:2026 年 3 月 (2603) 发行说明](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md)