launch.vs.json 結構描述參考 (C++)

在 Visual Studio 2017 和更新版本中，您可以從幾乎任何基於目錄的專案中開啟和建置程式碼，而無需方案檔或專案檔。 若沒有專案檔或方案檔時，您可以透過 JSON 組態檔來指定自訂建置工作​和啟動參數。 本文說明 launch.vs.json 檔案，其指定了偵錯參數。 如需「開啟資料夾」功能的詳細資訊，請參閱在 Visual Studio 中開發程式碼，無需專案或方案。

若要建立檔案，請在 [方案總管] 中的可執行檔上按一下滑鼠右鍵，然後選擇 [偵錯和啟動設定]。 選擇與您的專案最相符的選項，然後使用下列屬性視需要修改組態。 如需偵錯 CMake 專案的詳細資訊，請參閱設定 CMake 偵錯工作階段。

預設屬性

屬性	類型​	描述
args	陣列	指定傳遞至已啟動程式的命令列引數。
buildConfigurations	陣列	索引鍵/值組，其指定要套用組態的建置模式的名稱。 例如，Debug 或 Release，以及要根據選取的建置模式使用的組態。
currentDir	字串	指定建置目標的完整目錄路徑。 除非設定此參數，否則會自動偵測目錄。
cwd	字串	程式將執行的遠端系統上目錄的完整路徑。 預設為 "${debugInfo.defaultWorkingDirectory}"
debugType	字串	根據程式碼類型 (原生、受控或混合) 指定偵錯模式。 除非設定此參數，否則會自動偵測模式。 允許值："native"、"managed"、"mixed"。
env	陣列	指定自訂環境變數的索引鍵/值清單。 例如： env:{"myEnv":"myVal"} 。
inheritEnvironments	陣列	指定繼承自多個來源的一組環境變數。 您可以在檔案 (例如 CMakeSettings.json 或 CppProperties.json) 中定義一些變數，並讓它們可用於對內容進行偵錯。 Visual Studio 16.4： 使用 env.VARIABLE_NAME 語法，根據每個目標指定環境變數。 若要取消設定變數，請將它設為 "null"。
name	字串	在 [啟動項目] 下拉式清單中指定項目的名稱。
noDebug	boolean	指定是否要對啟動的程式進行偵錯。 如果未指定，則此參數的預設值為 false。
portName	字串	指定附加至執行中的處理序時連接埠的名稱。
program	字串	要執行的偵錯命令。 預設為 "${debugInfo.fullTargetPath}"。
project	字串	指定專案檔的相對路徑。 通常，在偵錯 CMake 專案時您不需要變更此值。
projectTarget	字串	指定建置 project 時叫用的選擇性目標。 該目標必須符合 [啟動項目] 下拉式清單中的名稱。
stopOnEntry	boolean	指定是否在處理序啟動且偵錯工具附加後就立即中斷。 此參數的預設值為 false。
remoteMachine	字串	指定啟動程式時的遠端電腦名稱。
type	字串	指定專案是 dll 還是 exe。預設值為 .exe

C++ Linux 屬性

屬性	類型​	描述
program	字串	遠端電腦上程式可執行檔的完整路徑。 使用 CMake 時，巨集 ${debugInfo.fullTargetPath} 可用作此欄位的值。
processId	整數	要附加偵錯工具到其中的選擇性處理序識別碼。
sourceFileMap	object	傳遞至偵錯引擎的選擇性來源檔案對應。 格式：{ "\<Compiler source location>": "\<Editor source location>" } 或 { "\<Compiler source location>": { "editorPath": "\<Editor source location>", "useForBreakpoints": true } }。 範例：{ "/home/user/foo": "C:\\foo" } 或 { "/home/user/foo": { "editorPath": "c:\\foo", "useForBreakpoints": true } }。 如需詳細資訊，請參閱來源檔案對應選項。
additionalProperties	字串	其中一個 sourceFileMapOptions。 (請參閱下方。)
MIMode	字串	指出 MIDebugEngine 將連線到其中的已啟用 MI 的主控台偵錯工具類型。 允許的值為 "gdb"、"lldb"。
args	陣列	傳遞至程式的命令列引數。
environment	陣列	要新增至程式環境的環境變數。 範例：[ { "name": "squid", "value": "clam" } ]。
targetArchitecture	字串	偵錯項目的架構。 除非設定此參數，否則會自動偵測架構。 允許的值為 x86、arm、arm64、mips、x64、amd64、x86_64。
visualizerFile	字串	偵錯此處理序時要使用的 .natvis 檔案。 此選項與 GDB 美化顯示不相容。 如果您使用此設定，請參閱 "showDisplayString"。
showDisplayString	boolean	指定 visualizerFile 時，showDisplayString 會啟用顯示字串。 開啟此選項可能會降低偵錯期間的效能。
remoteMachineName	字串	裝載 gdb 和要偵錯的程式的遠端 Linux 電腦。 使用連線管理員新增新的 Linux 電腦。 使用 CMake 時，巨集 ${debugInfo.remoteMachineName} 可用作此欄位的值。
miDebuggerPath	字串	已啟用 MI 的偵錯工具 (例如 gdb) 的路徑。 如果未指定，它會先在 PATH 中搜尋偵錯工具。
miDebuggerServerAddress	字串	要連線其中的已啟用 MI 的偵錯工具伺服器的網路位址。 範例："localhost:1234"。
setupCommands	陣列	要執行以設定基礎偵錯工具的一或多個 GDB/LLDB 命令。 範例："setupCommands": [ { "text": "-enable-pretty-printing", "description": "Enable GDB pretty printing", "ignoreFailures": true }]。 如需詳細資訊，請參閱啟動設定命令。
customLaunchSetupCommands	陣列	如果提供，則此值會將用於啟動目標的預設命令取代為一些其他命令。 例如，使用 "-target-attach" 以附加至目標處理序。 空的命令清單會將啟動命令取代為空白，如果將啟動選項作為命令行選項提供給偵錯工具，這會很有用。 範例："customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]。
launchCompleteCommand	字串	在偵錯工具完全設定之後 (以使目標處理序執行) 要執行的命令。 允許的值為 "exec-run"、"exec-continue"、"None"。 預設值為 "exec-run"。
debugServerPath	字串	偵錯要啟動的伺服器的選擇性完整路徑。 預設值為 null。
debugServerArgs	字串	選擇性偵錯伺服器引數。 預設值為 null。
filterStderr	boolean	在 stderr 串流中搜尋伺服器啟動的模式並記錄 stderr，以對輸出進行偵錯。 預設為 false。
coreDumpPath	字串	指定程式的核心傾印檔案的選擇性完整路徑。 預設值為 null。
externalConsole	boolean	如果為 true，則會針對偵錯項目啟動主控台。 如果為 false，則不會啟動主控台。 此設定的預設值為 false。 在某些情況下，基於技術原因，會忽略此選項。
pipeTransport	字串	如果存在，則此值會告訴偵錯工具使用另一個可執行檔作為管道連線到遠端電腦，該管道將在 Visual Studio 和已啟用 MI 的偵錯工具 (例如 gdb) 之間轉遞標準輸入/輸出。 允許的值：一或多個管道傳輸選項。

debugInfo 巨集

下列巨集提供偵錯環境的相關資訊。 它們對於自訂應用程式的啟動以進行偵錯非常有用。

Macro	描述	範例
addressSanitizerRuntimeFlags	用來自訂位址清理程式行為的執行階段旗標。 用來設定環境變數 "ASAN_OPTIONS"。	"env": {"ASAN_OPTIONS": "${addressSanitizerRuntimeFlags}:anotherFlag=true"}
defaultWorkingDirectory	設定為 "fullTargetPath" 的目錄部分。 如果已定義 CMake 變數 VS_DEBUGGER_WORKING_DIRECTORY，則 defaultWorkingDirectory 會改為設定為該值。	"cwd":"${debugInfo.defaultWorkingDirectory}"
fullTargetPath	正在偵錯的二進位檔的完整路徑。	"program": "${debugInfo.fullTargetPath}"
linuxNatvisPath	VS linux .natvis 檔案的完整視窗路徑。 通常會顯示為 "visualizerFile" 值。
parentProcessId	目前 Visual Studio 執行個體的處理序識別碼。 用作 shellexec 的參數。	請參閱下面的 pipeTransport 範例。
remoteMachineId	用於連線到遠端電腦的唯一數字識別碼。 用作 shellexec 的參數。	請參閱下面的 pipeTransport 範例。
remoteWorkspaceRoot	工作區遠端複本的 Linux 路徑。	指定遠端電腦上的檔案位置。 例如："args": ["${debugInfo.remoteWorkspaceRoot}/Data/MyInputFile.dat"]
resolvedRemoteMachineName	目標遠端電腦的名稱。	部署指示詞中的 "targetMachine" 值
shellexecPath	Visual Studio 用來管理遠端電腦連線的 shellexec 程式的路徑。	請參閱下面的 pipeTransport 範例
tty	gdb 會將正在偵錯的程式的輸入和輸出重新導向到此裝置。 用作 gdb (-tty) 的參數。	請參閱下面的 pipeTransport 範例。
windowsSubsystemPath	Windows 子系統 Linux 版執行個體的完整路徑。

下面的 pipeTransport 範例示範如何使用上面定義的一些 debugInfo 巨集：

"pipeTransport": {
    "pipeProgram": "${debugInfo.shellexecPath}",
    "pipeArgs": [
        "/s",
        "${debugInfo.remoteMachineId}",
        "/p",
        "${debugInfo.parentProcessId}",
        "/c",
        "${debuggerCommand}",
        "--tty=${debugInfo.tty}"
    ],
    "pipeCmd": [
        "/s",
        "${debugInfo.remoteMachineId}",
        "/p",
        "${debugInfo.parentProcessId}",
        "/c",
        "${debuggerCommand}"
    ]
    }

C++ Windows 遠端偵錯和部署屬性

在遠端電腦上偵錯和部署應用程式時使用。

屬性	類型​	描述
cwd	字串	遠端電腦上目標的工作目錄。 使用 CMake 時，巨集 ${debugInfo.defaultWorkingDirectory} 可用作此欄位的值。 預設值是偵錯程式/命令的目錄。
deploy	字串	指定要部署的額外檔案或目錄。 例如： "deploy": {"sourcePath":"<Full path to source file/directory on host machine>", "targetPath":"<Full destination path to file/directory on target machine>"}
deployDirectory	字串	專案輸出自動部署到其中的遠端電腦上的位置。 預設為 "C:\Windows Default Deploy Directory\<name of app>
deployDebugRuntimeLibraries	字串	指定是否要為使用中的平台部署偵錯執行階段程式庫。 如果使用中的 configurationType 為 "Debug"，則會預設為 "true"
deployRuntimeLibraries	字串	指定是否要為使用中的平台部署執行階段程式庫。 如果使用中的 configurationType 為 "MinSizeRel"、"RelWithDebInfo" 或 "Release"，則會預設為 "true"。
disableDeploy	boolean	指定是否應該部署檔案。
remoteMachineName	字串	指定啟動程式的遠端 ARM64 Windows 電腦的名稱。 可能是伺服器名稱或遠端電腦的 IP 位址。
authenticationType	字串	指定遠端連線的類型。 可能的值是 "windows" 和 "none"。 預設值為 "windows"。 此值應該符合在遠端電腦上執行的遠端偵錯工具上指定的驗證設定。

啟動設定命令

與 setupCommands 屬性搭配使用：

屬性	類型​	描述
text	字串	要執行的偵錯工具命令。
description	字串	命令的選擇性描述。
ignoreFailures	boolean	如果為 true，則應該忽略命令中的失敗。 預設為 false。

管道傳輸選項

與 pipeTransport 屬性搭配使用：

屬性	類型​	描述
pipeCwd	字串	管道程式的工作目錄的完整路徑。
pipeProgram	字串	要執行的完整管道命令。
pipeArgs	陣列	傳遞至管道程式以設定連線的命令列引數。
debuggerPath	字串	目標機器的偵錯工具完整路徑，例如 /use/bin/gdb。
pipeEnv	object	傳遞至管道程式的環境變數。
quoteArgs	boolean	如果個別的引數包含字元 (例如空格或 Tab 定位字元)，是否應該加上引號？ 如果為 false，偵錯工具命令將不再自動加上引號。 預設值為 true。

來源檔案對應選項

搭配 sourceFileMap 屬性使用：

屬性	類型​	描述
editorPath	字串	編輯器所要尋找的原始程式碼的位置。
useForBreakpoints	boolean	設定中斷點時，則應使用此來源對應。 如果為 false，則只會使用檔名和行號來設定中斷點。 如果為 true，則只有在使用此來源對應時，才會使用檔案的完整路徑和行號來設定中斷點。 否則，設定中斷點時只會使用檔名和行號。 預設值為 true。