設定 C# 偵錯
您可以使用 launch.json
、launchSettings.json
或您的使用者 settings.json
檔案,在 Visual Studio Code 中設定 C# 偵錯工具。
以下是您在偵錯時可能想要變更的常見選項。
設定 VS Code 的偵錯行為
PreLaunchTask
preLaunchTask
欄位會在偵錯您的程式之前,執行 tasks.json
中相關聯的 taskName。您可以從 VS Code 命令面板執行 Tasks: Configure Tasks Runner 命令,以取得預設的建置前啟動工作。
這會建立一個執行 dotnet build
的工作。您可以在 VS Code Tasks 文件中閱讀更多資訊。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
程式
program 欄位設定為要啟動的應用程式 dll 或 .NET Core 主機可執行檔的路徑。
此屬性通常採用以下格式:「${workspaceFolder}/bin/Debug/<target-framework>/<project-name.dll>」。
範例:"${workspaceFolder}/bin/Debug/netcoreapp1.1/MyProject.dll"
其中
- <target-framework> 是偵錯專案正在建置的架構。這通常在專案檔中以 'TargetFramework' 屬性找到。
- <project-name.dll> 是偵錯專案的建置輸出 dll 名稱。這通常與專案檔名相同,但副檔名為 '.dll'。
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作為executablePath
Cwd
目標處理序的工作目錄。
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作為workingDirectory
Args
這些是要傳遞至您程式的引數。
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作為commandLineArgs
在進入點停止
如果您需要在目標的進入點停止,您可以選擇性地將 stopAtEntry
設定為 "true"。
可用性
launch.json
✔️settings.json
✔️ 作為csharp.debug.stopAtEntry
launchSettings.json
❌
啟動 Web 瀏覽器
ASP.NET Core 專案的預設 launch.json
範本 (截至 C# 擴充功能 v1.20.0) 使用以下方式來設定 VS Code,以便在 ASP.NET 啟動時啟動 Web 瀏覽器
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+(https?://\\S+)"
}
關於此設定的注意事項
-
如果您不想要瀏覽器自動啟動,您可以直接刪除此元素 (以及如果您的
launch.json
中有launchBrowser
元素,也刪除該元素)。 -
此模式使用 ASP.NET Core 寫入主控台的 URL 來啟動 Web 瀏覽器。如果您想要修改 URL,請參閱指定瀏覽器的 URL。如果目標應用程式在另一部機器或容器上執行,或者
applicationUrl
有特殊的 host name (範例:"applicationUrl": "http://*:1234/"
),這可能會很有用。 -
serverReadyAction
是 VS Code 的一項新功能。建議使用它來取代 C# 擴充功能偵錯工具內建的先前launchBrowser
功能,因為當 C# 擴充功能在遠端機器上執行時,它可以運作,它使用為 VS Code 設定的預設瀏覽器,並且它也允許使用指令碼偵錯工具。如果這些功能對您而言都不重要,您可以繼續改用launchBrowser
。如果您想要執行特定的程式而不是啟動預設瀏覽器,您也可以繼續使用launchBrowser
。 -
關於
serverReadyAction
的更多文件,可以在 Visual Studio Code 2019 年 2 月發行說明中找到。 -
其運作方式是 VS Code 抓取設定為主控台的輸出。如果某行符合模式,它會針對模式「擷取」的 URL 啟動瀏覽器。
以下是模式作用的說明
\\b
:符合單字邊界。請注意,\b
表示單字邊界,但因為這是在 json 字串中,所以\
需要逸出,因此為\\b
。Now listening on:
:這是一個字串常值,表示下一個文字必須是Now listening on:
。\\s+
:符合一或多個空格字元。(
:這是「擷取群組」的開頭。這表示要儲存並用於啟動瀏覽器的文字區域。http
:字串常值。s?
:字元s
或無。://
:字串常值。\\S+
:一或多個非空白字元。)
:擷取群組的結尾。
-
瀏覽器啟動的兩種形式都需要
"console": "internalConsole"
,因為瀏覽器啟動器會抓取目標處理序的標準輸出,以了解 Web 伺服器何時已初始化自身。
指定瀏覽器的 URL
如果您想要忽略主控台輸出的 URL,您可以從模式中移除 (
和 )
,並將 uriFormat
設定為您想要啟動的內容。
範例
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+https?://\\S",
"uriFormat": "http://localhost:1234"
}
如果您想要使用主控台輸出的連接埠號碼,但不使用 host name,您也可以使用類似以下的內容
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+http://\\S+:([0-9]+)",
"uriFormat": "http://localhost:%s"
}
實際上,您可以開啟幾乎任何 URL,例如,您可以透過執行類似以下的內容來開啟預設的 swagger ui
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+http://\\S+:([0-9]+)",
"uriFormat": "http://localhost:%s/swagger/index.html"
}
注意:您需要確保您的專案已設定 swaggerui 才能執行此操作。
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 搭配launchBrowser
和applicationUrl
環境變數
可以使用此結構描述將環境變數傳遞至您的程式
"env": {
"myVariableName":"theValueGoesHere"
}
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作為environmentVariables
主控台 (終端機) 視窗
"console"
設定控制目標應用程式啟動進入哪個主控台 (終端機) 視窗。它可以設定為以下任何值 --
"internalConsole"
(預設值):目標處理序的主控台輸入 (stdin) 和輸出 (stdout/stderr) 會透過 VS Code 偵錯主控台路由傳送。此模式的優點是它允許您在一個位置看到來自偵錯工具和目標程式的訊息,因此您不會錯過重要訊息或需要來回切換。這對於具有簡單主控台互動的程式很有用 (範例:使用Console.WriteLine
和/或Console.ReadLine
)。當目標程式需要完全控制主控台時,不應使用此模式,例如變更游標位置、使用Console.ReadKey
進行輸入等的程式。請參閱下方關於輸入到主控台的指示。"integratedTerminal"
:目標處理序將在 VS Code 的整合式終端機內執行。選取編輯器下方索引標籤群組中的 Terminal 索引標籤,以與您的應用程式互動。當使用此模式時,預設情況下,啟動偵錯時不會顯示偵錯主控台。如果使用launch.json
,可以使用internalConsoleOptions
進行設定。"externalTerminal"
:目標處理序將在其自己的外部終端機內執行。當使用此模式時,您需要在 Visual Studio Code 和外部終端機視窗之間切換焦點。
可用性
launch.json
✔️settings.json
✔️ 作為csharp.debug.console
launchSettings.json
❌
注意:
csharp.debug.console
設定僅用於使用dotnet
偵錯組態類型啟動的主控台專案。
當使用 internalConsole 時,將文字輸入到目標處理序中
當使用 internalConsole
時,您可以將文字輸入到 Visual Studio Code 中,這些文字將從 Console.ReadLine
和類似的 API (從 stdin
讀取) 傳回。若要執行此操作,在程式執行時,在偵錯主控台底部的輸入方塊中輸入文字。按下 Enter 將文字傳送至目標處理序。請注意,如果您在程式在偵錯工具下停止時在此方塊中輸入文字,則此文字將被評估為 C# 運算式,而不是傳送至目標處理序。
範例
launchSettings.json 支援
除了 launch.json
之外,啟動選項也可以透過 launchSettings.json
檔案進行設定。launchSettings.json
的優點是它允許在 Visual Studio Code、完整 Visual Studio 和 dotnet run
之間共用設定。
若要設定要使用的 launchSettings.json
設定檔 (或防止使用它),請設定 launchSettingsProfile
選項
"launchSettingsProfile": "ProfileNameGoesHere"
例如,這將使用此範例 launchSettings.json
檔案中的 myVariableName
{
"profiles": {
"ProfileNameGoesHere": {
"commandName": "Project",
"environmentVariables": {
"myVariableName": "theValueGoesHere"
}
}
}
}
如果未指定 launchSettingsProfile
,則將使用第一個具有 "commandName": "Project"
的設定檔。
如果 launchSettingsProfile
設定為 null/空字串,則 Properties/launchSettings.json 將被忽略。
依預設,偵錯工具將在 {cwd}/Properties/launchSettings.json 中搜尋 launchSettings.json
。若要自訂此路徑,請設定 launchSettingsFilePath
"launchSettingsFilePath": "${workspaceFolder}/<Relative-Path-To-Project-Directory/Properties/launchSettings.json"
限制
- 僅支援具有
"commandName": "Project"
的設定檔。 - 僅支援
environmentVariables
、applicationUrl
和commandLineArgs
屬性 launch.json
中的設定將優先於launchSettings.json
中的設定,因此,例如,如果args
已在launch.json
中設定為非空字串/陣列,則launchSettings.json
內容將被忽略。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
原始檔地圖
您可以選擇性地設定如何開啟原始檔,方法是使用以下形式提供地圖
"sourceFileMap": {
"C:\\foo":"/home/me/foo"
}
在此範例中
C:\foo
是一個或多個原始檔 (範例:program.cs
) 在模組 (範例:MyCode.dll) 編譯時的原始位置。它可以是具有原始檔的目錄,也可以是原始檔的完整路徑 (範例:c:\foo\program.cs
)。它不需要存在於執行 Visual Studio Code 的電腦上,或者如果您正在進行遠端偵錯,則不需要存在於遠端機器上。偵錯工具從.pdb
(符號) 檔案讀取原始檔的路徑,並使用此地圖轉換路徑。/home/me/foo
是 Visual Studio Code 現在可以找到原始檔的路徑。
可用性
launch.json
✔️settings.json
✔️ 作為csharp.debug.sourceFileMap
launchSettings.json
❌
僅限我的程式碼
您可以選擇性地停用 justMyCode
,方法是將其設定為 "false"。當您嘗試偵錯您拉取的沒有符號或已最佳化的程式庫時,您應該停用僅限我的程式碼。
"justMyCode":false
僅限我的程式碼是一組功能,可讓您更輕鬆地專注於偵錯您的程式碼,方法是隱藏您可能正在使用的一些最佳化程式庫的詳細資訊,例如 .NET Framework 本身。此功能最重要的子部分是 --
- 使用者未處理的例外狀況:在例外狀況即將被架構攔截之前自動停止偵錯工具
- 僅限我的程式碼逐步執行:逐步執行時,如果架構程式碼回呼使用者程式碼,則自動停止。
可用性
launch.json
✔️settings.json
✔️ 作為csharp.debug.justMyCode
launchSettings.json
❌
要求完全相符的原始碼
偵錯工具要求 pdb 和原始碼完全相同。若要變更此設定並停用原始碼必須相同,請新增
"requireExactSource": false
可用性
launch.json
✔️settings.json
✔️ 作為csharp.debug.requireExactSource
launchSettings.json
❌
逐步執行屬性和運算子
依預設,偵錯工具會跳過 Managed 程式碼中的屬性和運算子。在大多數情況下,這提供了更好的偵錯體驗。若要變更此設定並啟用逐步執行屬性或運算子,請新增
"enableStepFiltering": false
可用性
launch.json
✔️settings.json
✔️ 作為csharp.debug.enableStepFiltering
launchSettings.json
❌
記錄
您可以選擇性地啟用或停用應記錄到輸出視窗的訊息。記錄欄位中的旗標為:'exceptions'、'moduleLoad'、'programOutput'、'browserStdOut' 和 'consoleUsageMessage'。
在 'logging.diagnosticsLog' 下還有進階選項,這些選項旨在診斷偵錯工具的問題。
可用性
launch.json
✔️settings.json
✔️ 在csharp.debug.logging
下launchSettings.json
❌
PipeTransport
如果您需要讓偵錯工具使用另一個可執行檔連接到遠端電腦,以在 VS Code 和 .NET Core 偵錯工具後端 (vsdbg) 之間中繼標準輸入和輸出,則請依照此結構描述新增 pipeTransport 欄位
"pipeTransport": {
"pipeProgram": "ssh",
"pipeArgs": [ "-T", "ExampleAccount@ExampleTargetComputer" ],
"debuggerPath": "~/vsdbg/vsdbg",
"pipeCwd": "${workspaceFolder}",
"quoteArgs": true
}
關於管道傳輸的更多資訊,可以在這裡找到。
您可以在適用於 Linux 的 Windows 子系統 (WSL) 的這裡找到關於設定管道傳輸的資訊。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
作業系統特定的組態
如果每個作業系統都需要變更特定的命令,您可以使用欄位:'windows'、'osx' 或 'linux'。您可以針對特定的作業系統取代上述任何欄位。
抑制 JIT 最佳化
.NET 偵錯工具支援以下選項。如果為 true,當最佳化模組 (在 Release 組態中編譯的 .dll) 載入目標處理序時,偵錯工具會要求 Just-In-Time 編譯器產生已停用最佳化的程式碼。此選項預設為 false。
"suppressJITOptimizations": true
最佳化在 .NET 中的運作方式:如果您嘗試偵錯程式碼,當程式碼未最佳化時,會更容易。這是因為當程式碼最佳化時,編譯器和執行階段將對發出的 CPU 程式碼進行變更,使其執行速度更快,但與原始原始碼的對應較不直接。這表示偵錯工具通常無法告訴您區域變數的值,並且程式碼逐步執行和中斷點可能無法如您預期般運作。
通常 Release 建置組態會建立最佳化程式碼,而 Debug 建置組態則不會。Optimize
MSBuild 屬性控制是否告知編譯器最佳化程式碼。
在 .NET 生態系統中,程式碼會透過兩個步驟從原始碼轉換為 CPU 指令:首先,C# 編譯器會將您輸入的文字轉換為稱為 MSIL 的中間二進位形式,並將其寫出到 .dll 檔案。稍後,.NET 執行階段會將此 MSIL 轉換為 CPU 指令。這兩個步驟都可以在一定程度上進行最佳化,但由 .NET 執行階段執行的第二個步驟會執行更顯著的最佳化。
此選項的作用:此選項控制在已啟用最佳化編譯的 DLL 載入目標處理序內部時會發生什麼情況。如果此選項為 false (預設值),則當 .NET 執行階段將 MSIL 程式碼編譯為 CPU 程式碼時,它會保持啟用最佳化。如果此選項為 true,則偵錯工具會要求停用最佳化。
何時應使用此選項:當您從另一個來源下載 dll,例如 nuget 套件,並且想要偵錯此 DLL 中的程式碼時,應使用此選項。為了使其運作,您還必須找到此 DLL 的符號 (.pdb) 檔案。
如果您只對偵錯您在本機建置的程式碼感興趣,最好將此選項保留為 false,因為在某些情況下,啟用此選項會顯著減慢偵錯速度。造成此減速有兩個原因 --
- 最佳化程式碼執行速度更快。如果您關閉大量程式碼的最佳化,時間可能會累積起來。
- 如果您已啟用僅限我的程式碼,偵錯工具甚至不會嘗試載入已最佳化的 dll 的符號。尋找符號可能需要很長時間。
此選項的限制:在兩種情況下,此選項將不起作用
1:在您將偵錯工具附加到已在執行的處理序的情況下,此選項對偵錯工具附加時已載入的模組沒有影響。
2:此選項對已預先編譯 (ngen'ed) 為原生程式碼的 dll 沒有影響。但是,您可以透過使用環境變數 COMPlus_ReadyToRun
設定為 0
來啟動處理序,以停用預先編譯程式碼的使用。如果您以舊版 .NET Core (2.x) 為目標,也請將 COMPlus_ZapDisable
設定為 '1'。如果您正在偵錯工具下啟動,則可以透過將此設定新增至 launch.json
來設定此組態
"env": {
"COMPlus_ZapDisable": "1",
"COMPlus_ReadyToRun": "0"
}
可用性
launch.json
✔️settings.json
✔️ 作為csharp.debug.suppressJITOptimizations
launchSettings.json
❌
符號選項
symbolOptions
元素允許自訂偵錯工具搜尋符號的方式。範例
"symbolOptions": {
"searchPaths": [
"~/src/MyOtherProject/bin/debug",
"https://my-companies-symbols-server"
],
"searchMicrosoftSymbolServer": true,
"searchNuGetOrgSymbolServer": true,
"cachePath": "/symcache",
"moduleFilter": {
"mode": "loadAllButExcluded",
"excludedModules": [ "DoNotLookForThisOne*.dll" ]
}
}
屬性
searchPaths:要搜尋 .pdb
檔案的符號伺服器 URL (範例:https://msdl.microsoft.com/download/symbols
) 或目錄 (範例:/build/symbols) 陣列。除了預設位置之外,還將搜尋這些目錄,預設位置在模組旁邊以及最初放置 .pdb
的路徑。
searchMicrosoftSymbolServer:如果為 true
,則 Microsoft 符號伺服器 (https://msdl.microsoft.com/download/symbols) 會新增至符號搜尋路徑。如果未指定,則此選項預設為 false
。
searchNuGetOrgSymbolServer:如果為 true
,則 Nuget.org 符號伺服器 (https://symbols.nuget.org/download/symbols) 會新增至符號搜尋路徑。如果未指定,則此選項預設為 false
。
cachePath":應快取從符號伺服器下載的符號的目錄。如果未指定,在 Windows 上,偵錯工具預設為 %TEMP%\\SymbolCache
,而在 Linux 和 macOS 上,偵錯工具預設為 ~/.dotnet/symbolcache
。
moduleFilter.mode:此值可以是 "loadAllButExcluded"
或 "loadOnlyIncluded"
。在 "loadAllButExcluded"
模式中,偵錯工具會載入所有模組的符號,除非模組位於 'excludedModules' 陣列中。在 "loadOnlyIncluded"
模式中,偵錯工具將不會嘗試載入任何模組的符號,除非它位於 'includedModules' 陣列中,或者它透過 'includeSymbolsNextToModules' 設定包含。
loadAllButExcluded 模式的屬性
moduleFilter.excludedModules:偵錯工具不應載入符號的模組陣列。支援萬用字元 (範例:MyCompany.*.dll)。
loadOnlyIncluded 模式的屬性
moduleFilter.includedModules:偵錯工具應載入符號的模組陣列。支援萬用字元 (範例:MyCompany.*.dll)。
moduleFilter.includeSymbolsNextToModules:如果為 true,對於任何不在 'includedModules' 陣列中的模組,偵錯工具仍將檢查模組本身和啟動可執行檔旁邊,但它不會檢查符號搜尋清單上的路徑。此選項預設為 'true'。
可用性
launch.json
✔️settings.json
✔️ 在csharp.debug.symbolOptions
下launchSettings.json
❌
Source Link 選項
Source Link 是一項功能,可讓您在偵錯在另一部電腦上建置的程式碼 (例如來自 nuget 套件的程式碼) 時,偵錯工具可以透過從 Web 下載來自動調出相符的原始碼。為了使此功能運作,您正在偵錯的程式碼的 .pdb 檔案包含將 DLL 中的原始檔對應到偵錯工具可以從中下載的 URL 的資料。關於 Source Link 的更多資訊,可以在 https://aka.ms/SourceLinkSpec 找到。
launch.json
中的 sourceLinkOptions
元素允許依 URL 自訂 Source Link 行為。它是從 URL 到該 URL 的 Source Link 選項的地圖。URL 名稱中支援萬用字元。目前唯一的自訂是 Source Link 是否針對該 URL 啟用,但未來可能會新增更多選項。
範例
"sourceLinkOptions": {
"https://raw.githubusercontent.com/*": { "enabled": true },
"*": { "enabled": false }
}
此範例針對 GitHub URL 啟用 Source Link,並針對所有其他 URL 停用 Source Link。
此選項的預設值是針對所有 URL 啟用 Source Link。同樣地,對於 sourceLinkOptions
地圖中沒有規則的任何 URL,也會啟用 Source Link。
若要針對所有 URL 停用 Source Link,請使用 "sourceLinkOptions": { "*": { "enabled": false } }
。
如果多個項目涵蓋相同的 URL,則會使用更具體的項目 (字串長度較長的項目)。
目前,Source Link 僅適用於可以無需驗證即可存取的原始檔。因此,例如,偵錯工具可以從 GitHub 上的開放原始碼專案下載原始檔,但無法從私有 GitHub 存放庫或 Visual Studio Team Services 下載。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
目標架構選項 (macOS M1)
Apple M1 上的 .NET 支援 x86_64 和 ARM64。偵錯時,偵錯工具附加到的處理序架構和偵錯工具必須相符。如果它們不相符,可能會導致 Unknown Error: 0x80131c3c
。
擴充功能會嘗試根據 PATH 中 dotnet --info
的輸出解析 targetArchitecture
,否則它會嘗試使用與 VS Code 相同的架構。
您可以透過在 launch.json
中設定 targetArchitecture
來覆寫此行為。
範例
"targetArchitecture": "arm64"
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
檢查 DevCert
此選項控制在啟動時,偵錯工具是否應檢查電腦是否具有用於開發在 https 端點上執行的 Web 專案的自我簽署 HTTPS 憑證。為此,它會嘗試執行 dotnet dev-certs https --check --trust
,如果找不到憑證,它會提示使用者建議建立憑證。如果使用者核准,則擴充功能會執行 dotnet dev-certs https --trust
以建立受信任的自我簽署憑證。
如果未指定,當設定 serverReadyAction
時,預設為 true。此選項在 Linux、VS Code 遠端和 VS Code for the Web 案例中不起作用。
您可以透過在您的 launch.json
中將 checkForDevCert
設定為 false 來覆寫此行為。
範例
"checkForDevCert": "false"
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作為useSSL
設定 launchSettings.json
使用 C# 開發套件,您可以將您的 launchSettings.json
從 Visual Studio 帶入 Visual Studio Code 中使用
範例
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:59481",
"sslPort": 44308
}
},
"profiles": {
"EnvironmentsSample": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://localhost:7152;http://localhost:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"EnvironmentsSample-Staging": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://localhost:7152;http://localhost:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Staging",
"ASPNETCORE_DETAILEDERRORS": "1",
"ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
}
},
"EnvironmentsSample-Production": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://localhost:7152;http://localhost:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Production"
}
},
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
設定檔屬性
commandLineArgs
- 要傳遞至正在執行的目標的引數。executablePath
- 可執行檔的絕對或相對路徑。workingDirectory
- 設定命令的工作目錄。launchBrowser
- 如果應啟動瀏覽器,則設定為 true。applicationUrl
- 要為 Web 伺服器設定的分號分隔 URL 清單。sslPort
- 要用於網站的 SSL 連接埠。httpPort
- 要用於網站的 HTTP 連接埠。