設定 C# 偵錯
您可以使用 launch.json
、launchSettings.json
或您的使用者 settings.json
檔案,在 Visual Studio Code 中設定 C# 偵錯工具。
以下是您在偵錯時可能想要變更的常見選項。
設定 VS Code 的偵錯行為
PreLaunchTask
preLaunchTask
欄位會在偵錯您的程式之前,執行 tasks.json
中關聯的 taskName。您可以從 VS Code 命令選擇區執行命令工作: 設定工作執行器,以取得預設的建置預先啟動工作。
這會建立執行 dotnet build
的工作。您可以在 VS Code 工作文件中閱讀更多資訊。
可用性
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+)"
}
關於此項目的注意事項
-
如果您不想要瀏覽器自動啟動,您可以直接刪除此元素 (以及
launchBrowser
元素,如果您的launch.json
有該元素的話)。 -
此模式使用 ASP.NET Core 寫入主控台的 URL 啟動 Web 瀏覽器。如果您想要修改 URL,請參閱 指定瀏覽器的 URL。如果目標應用程式在另一部機器或容器上執行,或者如果
applicationUrl
具有特殊的主機名稱 (範例:「"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": "https://127.0.0.1:1234"
}
如果您想要使用主控台輸出的連接埠號碼,但不要使用主機名稱,您也可以使用類似這樣的內容
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+http://\\S+:([0-9]+)",
"uriFormat": "https://127.0.0.1:%s"
}
實際上,您可以開啟幾乎任何 URL,例如,您可以透過執行類似這樣的內容來開啟預設 Swagger UI
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+http://\\S+:([0-9]+)",
"uriFormat": "https://127.0.0.1:%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 的整合式終端機內執行。選取編輯器下方索引標籤群組中的 [終端機] 索引標籤,以與您的應用程式互動。使用此模式時,預設情況下,啟動偵錯時不會顯示偵錯主控台。如果使用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
是模組 (範例:MyCode.dll) 編譯時,一個或多個原始檔 (範例:program.cs
) 的原始位置。它可以是包含原始檔的目錄,或原始檔的完整路徑 (範例: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,當最佳化模組 (在發行組態中編譯的 .dll) 在目標程序中載入時,偵錯工具會要求 Just-In-Time 編譯器產生已停用最佳化的程式碼。此選項預設為 false。
"suppressJITOptimizations": true
最佳化在 .NET 中的運作方式:如果您嘗試偵錯程式碼,則程式碼未最佳化時會更容易。這是因為當程式碼最佳化時,編譯器和執行階段會變更發出的 CPU 程式碼,使其執行速度更快,但與原始碼的直接對應較少。這表示偵錯工具經常無法告訴您區域變數的值,而且程式碼逐步執行和中斷點可能無法如您預期般運作。
通常,發行組建組態會建立最佳化程式碼,而偵錯組建組態則不會。[最佳化] MSBuild 屬性控制是否告知編譯器最佳化程式碼。
在 .NET 生態系統中,程式碼會透過兩個步驟的程序從來源轉換為 CPU 指令:首先,C# 編譯器會將您輸入的文字轉換為稱為 MSIL 的中繼二進位格式,並將其寫出到 .dll 檔案。稍後,.NET 執行階段會將此 MSIL 轉換為 CPU 指令。這兩個步驟都可以在某種程度上進行最佳化,但由 .NET 執行階段執行的第二個步驟會執行更顯著的最佳化。
此選項的作用:此選項控制在已啟用最佳化編譯的 DLL 載入目標程序內部時會發生什麼情況。如果此選項為 false (預設值),則當 .NET 執行階段將 MSIL 程式碼編譯為 CPU 程式碼時,它會保持啟用最佳化。如果此選項為 true,則偵錯工具會要求停用最佳化。
何時應使用此選項:當您從另一個來源 (例如 NuGet 套件) 下載 dll,並且想要偵錯此 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 名稱中支援萬用字元。目前唯一的自訂是是否為該 URL 啟用 Source Link,但未來可能會新增更多選項。
範例
"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 遠端和適用於 Web 的 VS Code 案例中不起作用。
您可以透過在 launch.json
中將 checkForDevCert
設定為 false 來覆寫此行為。
範例
"checkForDevCert": "false"
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作為useSSL
設定 launchSettings.json
使用 C# 開發套件,您可以將 Visual Studio 中的 launchSettings.json
帶到 Visual Studio Code 中使用
範例
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "https://127.0.0.1:59481",
"sslPort": 44308
}
},
"profiles": {
"EnvironmentsSample": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://127.0.0.1:7152;https://127.0.0.1:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"EnvironmentsSample-Staging": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://127.0.0.1:7152;https://127.0.0.1:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Staging",
"ASPNETCORE_DETAILEDERRORS": "1",
"ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
}
},
"EnvironmentsSample-Production": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://127.0.0.1:7152;https://127.0.0.1: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 連接埠。