> ## 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 Marketplace 延伸模組進行部署與偵錯，將 Visual Studio 2022 偵錯工具附加至在遠端 Windows 電腦上執行的 PC 遊戲組建。
> [!NOTE]
>
> XBOX PC Toolbox 應用程式目前為預覽版。請從 Windows 上的 [Microsoft Store](https://aka.ms/toolboxinstaller) 下載。
[XBOX PC 遠端工具](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/remote-gamedev-tools)包含將 Visual Studio 2022 偵錯工具附加至在遠端 Windows 裝置上執行之遊戲的功能。開發電腦與遠端 Windows 裝置之間的所有偵錯流量都會加密。附加偵錯工具的功能是由 [Visual Studio 2022 延伸模組](https://marketplace.visualstudio.com/items?itemName=XboxGDK.Microsoft-Xbox-PC-Remote-Debugger)提供，可在公開的 Visual Studio Marketplace 中取得。
偵錯之前，必須依照[快速入門指南](/zh-TW/tools/tools-pc/xbox-pc-remote-tools/quickstart)中所述的步驟佈建並配對您的開發電腦與遠端 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 延伸模組。
## 在遊戲專案中啟用 F5 部署與偵錯
適用於 Visual Studio 的 XBOX PC Remote Debugger 延伸模組支援完整的「F5」整合，可在遠端 Windows 裝置上部署與偵錯 C++ 專案。按 F5 會建置專案、選擇性地將其部署至遠端裝置、以暫停狀態啟動遊戲、附加 XBOX PC Remote Debugger，然後在偵錯狀態下繼續執行遊戲。
安裝 [XBOX PC Remote Debugger Visual Studio 延伸模組](https://marketplace.visualstudio.com/items?itemName=XboxGDK.Microsoft-Xbox-PC-Remote-Debugger)之後，在使用 F5 遠端部署與偵錯之前，請確定下列事項：
1. 必須依照[快速入門指南](/zh-TW/tools/tools-pc/xbox-pc-remote-tools/quickstart)中所述的步驟佈建並配對您的開發電腦與遠端 Windows 裝置。
2. 遠端裝置上必須安裝 Microsoft Visual Studio Debug Monitor (`MSVSMON.EXE`)。`MSVSMON.EXE` 會由 [XBOX PC Toolbox 應用程式](/zh-TW/tools/tools-pc/xboxpctoolbox/xboxpctoolbox)自動安裝。或者，也可以在遠端裝置上從系統管理員命令提示字元使用 WinGet 進行安裝：
```
winget install Microsoft.VisualStudio.2022.OnecoreMsvsmon
```
3. 遠端裝置上必須執行 [`wdEndpoint.exe`](/zh-TW/tools/tools-pc/commandlinetools/gr-wdEndpoint)。`wdEndpoint.exe` 會由 [XBOX PC Toolbox 應用程式](/zh-TW/tools/tools-pc/xboxpctoolbox/xboxpctoolbox)自動安裝並啟動。或者，也可以在遠端裝置上從命令提示字元使用 Winget 進行安裝：
```
winget install Microsoft.Gaming.RemoteIterationEndpoint
```
透過 WinGet 安裝 `wdEndpoint.exe` 之後，請手動啟動它。
### 為 MSBuild 專案新增 F5 遠端偵錯支援
若要為使用 MSBuild 的專案啟用 F5 整合，請將下列 XML 新增至您的 `.vcxproj` 檔案。請將其放在最後一個 `` 元素之後，以及原始程式檔 `` 區段之前：
```xml theme={null}
```
> [!NOTE]
>
> 最新版的 [Microsoft GDK 範本](https://aka.ms/gdktemplates)會在建立新專案時提示您加入此整合。
若要啟用部署，請前往 **專案 > 屬性 > 組態管理員**，並勾選所需組態的 **部署** 選項。
按 **F5** 之前，請使用偵錯工具列或專案屬性頁將偵錯工具設為 **XBOX PC Remote Debugger**。有數個屬性可用於設定部署與偵錯。
* `Remote Command Arguments`。要傳遞給遊戲的命令引數清單。
* `Deployment Directory`。開發電腦上要部署至遠端 Windows 裝置的目錄。預設值為 `$(Outdir)`。
* `Remote Folder`。遊戲在遠端 Windows 裝置上部署至的資料夾。此資料夾相對於 *Common Root*。如需有關 *Common Root* 的詳細資訊，請參閱 [`wdEndpoint.exe`](/zh-TW/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 能找到遊戲的符號。請使用可從 **工具** 功能表存取的 **選項** 對話方塊中的 **偵錯** 設定進行設定。
#### F5 遠端偵錯工具的個別專案預設值
XBOX PC Remote Debugger 設定的預設值是由 `XboxPCcppDebugger.props` 檔案設定，而在 Visual Studio 專案屬性對話方塊中對設定所做的任何編輯，都會以「每位使用者」的方式儲存在本機電腦上。
若要讓您的 vcxproj 提供其他預設值，以避免每位使用者都必須在自己的電腦上設定，請依下列方式將其新增至 MSBuild：
```xml theme={null}
MyGameTitle
```
### Visual C++ Runtime (CRT) 部署
若要讓程式在遠端電腦上執行，需要 Visual C++ Runtime 檔案。對於零售 CRT，可以在遠端電腦上安裝 Visual C++ REDIST 套件。對於偵錯 CRT，這些檔案必須與遊戲一起部署。
在 MSBuild 中，一個簡單的解決方法是在專案的 Global 區段中新增屬性：
```xml theme={null}
true
```
這會將 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**。
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** 將遊戲部署至遠端裝置並在偵錯工具下啟動。
## 將 Visual Studio 偵錯工具附加至在遠端 Windows 裝置上執行的遊戲
若要將偵錯工具附加至已在遠端裝置上執行的遊戲，請從 Visual Studio 的 **偵錯** 功能表選取 **附加至處理序...**。從 **連線類型** 下拉式清單中選取 **XBOX PC Remote Device**，並在 **連線目標** 文字方塊中輸入遠端裝置的 IP 位址或主機名稱。系統會顯示遠端裝置上執行中的處理序清單。選取您要偵錯的遊戲，然後選取 **附加** 按鈕。
## 另請參閱
[XBOX PC 遠端工具](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/remote-gamedev-tools)
## Related topics
- [使用 Visual Studio 偵錯 PC 專案](/zh-TW/tools/tools-pc/visualstudio/gr-vs-debugging-with-visualstudio.md)
- [Visual Studio](/zh-TW/tools/tools-pc/visualstudio/index.md)
- [Visual Studio (內容)](/zh-TW/tools/tools-pc/visualstudio/gr-visualstudio-toc.md)
- [XBOX PC 遠端工具](/zh-TW/tools/tools-pc/xbox-pc-remote-tools/index.md)
- [使用 Visual Studio 偵錯 XBOX 專案](/zh-TW/tools/tools-console/visualstudio/debugging-with-visualstudio.md)