偵錯

您可以使用 Microsoft C# 擴充功能在 Visual Studio Code 中對 C# 應用程式進行偵錯。

執行與偵錯

C# 擴充功能與 C# Dev Kit 共同提供了多種執行和偵錯 C# 應用程式的方式。

若要在沒有 C# Dev Kit 的情況下執行和偵錯，請參閱 Microsoft C# 擴充功能的 GitHub 頁面以取得文件。

使用 F5 偵錯

安裝 C# Dev Kit 擴充功能且「偵錯」檢視中沒有可選擇的偵錯組態時，您可以透過開啟 .cs 檔案並按下 F5 來開始對專案進行偵錯。偵錯工具會自動尋找您的專案並開始偵錯。如果您有多個專案，它會提示您選擇要開始偵錯的專案。

您也可以從 VS Code 側邊欄的執行與偵錯檢視開始偵錯工作階段。詳情請參閱 在 VS Code 中偵錯。

使用方案總管 (Solution Explorer) 偵錯

安裝 C# Dev Kit 擴充功能後，在方案總管中右鍵點選專案時，會出現一個偵錯內容選單。

共有三個選項

• 啟動新執行個體 - 這會以附加偵錯工具的方式啟動您的專案。
• 啟動但不偵錯 - 這會執行您的專案，但不附加偵錯工具。
• 逐步進入新執行個體 - 這會以附加偵錯工具的方式啟動您的專案，但在程式碼進入點停止。

使用命令選擇區偵錯

安裝 C# Dev Kit 擴充功能後，您也可以使用偵錯: 選取並開始偵錯命令，從命令選擇區 ⇧⌘P (Windows, Linux Ctrl+Shift+P) 開始偵錯。

注意：這會將啟動組態項目加入到您的偵錯下拉式清單中。

使用動態（記憶體中）啟動組態進行偵錯

安裝 C# Dev Kit 擴充功能後，您可以建立動態啟動組態。建立方式取決於您的專案是否已有 launch.json 檔案。

現有的 launch.json

如果您有現有的 launch.json，您可以前往「偵錯」檢視，選取下拉式選單，並選擇 C# 選項。這應該會為您提供一系列可加入下拉式清單的啟動目標。選取後，您可以使用新產生的組態按下 F5 或開始偵錯。

沒有 launch.json

如果您的專案中沒有 launch.json，您可以在「偵錯」檢視的顯示所有自動偵錯組態中加入並存取這些動態組態。

移除動態（記憶體中）啟動組態

您可以透過命令選擇區 ⇧⌘P (Windows, Linux Ctrl+Shift+P) 並使用偵錯: 選取並開始偵錯命令來移除產生的組態。

下拉式清單會列出您所有現有的偵錯組態。若將滑鼠游標懸停在動態組態上，右側會出現一個可點擊的垃圾桶圖示。您可以選取該圖示以移除該動態組態。

使用編輯器中的偵錯/執行按鈕偵錯

當編輯器中開啟 .cs 檔案時，可以透過編輯器視窗右上角的按鈕來使用執行和偵錯選項。這些動作會使用目前的檔案來查詢專案系統，並決定要啟動的相關聯專案。

這兩個選項分別為

• 執行與此檔案相關聯的專案：這將使用偵錯配接器的 noDebug: true 啟動您的程式。
• 偵錯與此檔案相關聯的專案：這將在偵錯工具下啟動您的程式。

使用 launch.json 偵錯

如果您正在使用 C# Dev Kit，建議不要使用此選項。不過，如果您需要直接修改偵錯組態，請參閱 設定 C# 偵錯的 launch.json。

附加至處理序

您可以使用命令選擇區 ⇧⌘P (Windows, Linux Ctrl+Shift+P) 並執行偵錯: 附加至 .NET 5+ 或 .NET Core 處理序命令，以附加至 C# 處理序。

組態選項

有許多選項和設定可用於設定偵錯工具。您可以使用 launchSettings.json、VS Code 使用者設定來修改偵錯選項，或直接修改您的 launch.json。

launchSettings.json

如果您有來自 Visual Studio 的 launchSettings.json，您應該會看到您的設定檔列出在透過 F5 執行或透過命令選擇區執行中。

詳情請參閱 設定 C# 偵錯。

使用者設定

如果您在 C# 偵錯工具期間想要變更某些設定，可以在 檔案 > 喜好設定 > 設定 (⌘, (Windows, Linux Ctrl+,)) 下搜尋這些選項。

• csharp.debug.stopAtEntry - 若為 true，偵錯工具應在目標的進入點停止。此選項預設為 false。
• csharp.debug.console - 啟動主控台專案時，指示目標程式應在哪個主控台中啟動。注意：此選項僅用於「dotnet」偵錯組態類型。
  • internalConsole [預設] - VS Code 的偵錯主控台。此模式允許您在同一處查看來自偵錯工具和目標程式的訊息。請參閱完整文件以取得詳細資訊。
  • integratedTerminal - VS Code 的整合終端機。
  • externalTerminal - 可透過使用者設定設定的外部終端機。
• csharp.debug.sourceFileMap - 將建置時路徑對應至本機原始檔位置。所有建置時路徑的執行個體都將替換為本機原始檔路徑。
    範例
      {\"<build-path>\":\"<local-source-path>\"}
• csharp.debug.justMyCode - 啟用時（預設值），偵錯工具僅顯示並逐步執行使用者程式碼（"My Code"），忽略系統程式碼及其他已最佳化或沒有偵錯符號的程式碼。更多資訊。
• csharp.debug.requireExactSource - 要求目前原始程式碼與 pdb 相符的旗標。此選項預設為 true。
• csharp.debug.enableStepFiltering - 啟用逐步執行屬性和運算子的旗標。此選項預設為 true。
• csharp.debug.logging.exceptions - 決定是否將例外狀況訊息記錄到輸出視窗的旗標。此選項預設為 true。
• csharp.debug.logging.moduleLoad - 決定是否將模組載入事件記錄到輸出視窗的旗標。此選項預設為 true。
• csharp.debug.logging.programOutput - 當不使用外部主控台時，決定是否將程式輸出記錄到輸出視窗的旗標。此選項預設為 true。
• csharp.debug.logging.diagnosticsLog - 用於診斷偵錯工具問題的各種設定。
• csharp.debug.logging.browserStdOut - 決定是否將來自啟動網頁瀏覽器的 stdout 文字記錄到輸出視窗的旗標。此選項預設為 true。
• csharp.debug.logging.elapsedTiming - 若為 true，引擎記錄會包含 adapterElapsedTime 和 engineElapsedTime 屬性，以指示請求花費的時間（以微秒為單位）。此選項預設為 false。
• csharp.debug.logging.threadExit - 控制當目標處理序中的執行緒結束時是否記錄訊息。此選項預設為 false。
• csharp.debug.logging.processExit - 控制當目標處理序結束或偵錯停止時是否記錄訊息。此選項預設為 true。
• csharp.debug.suppressJITOptimizations - 若為 true，當最佳化模組（以 Release 組態編譯的 .dll）載入目標處理序時，偵錯工具會要求 Just-In-Time 編譯器產生停用最佳化的程式碼。更多資訊
• csharp.debug.symbolOptions.searchPaths - 符號伺服器 URL 陣列（範例：http://MyExampleSymbolServer）或目錄（範例：/build/symbols），用於搜尋 .pdb 檔案。除了模組旁邊的預設位置以及最初放置 pdb 的路徑外，還會搜尋這些目錄。
• csharp.debug.symbolOptions.searchMicrosoftSymbolServer - 若為 true，則將 Microsoft 符號伺服器 (https://msdl.microsoft.com/download/symbols) 加入到符號搜尋路徑。若未指定，此選項預設為 false。
• csharp.debug.symbolOptions.searchNuGetOrgSymbolServer - 若為 true，則將 NuGet.org 符號伺服器 (https://symbols.nuget.org/download/symbols) 加入到符號搜尋路徑。若未指定，此選項預設為 false。
• csharp.debug.symbolOptions.cachePath - 從符號伺服器下載的符號應快取的目錄。若未指定，在 Windows 上偵錯工具預設為 %TEMP%\\SymbolCache，而在 Linux 和 macOS 上預設為 ~/.dotnet/symbolcache。
• csharp.debug.symbolOptions.moduleFilter.mode - 控制模組篩選器運作的兩種基本模式之一。
  • loadAllButExcluded - 載入所有模組的符號，除非該模組位於 excludedModules 陣列中。
  • loadOnlyIncluded - 不要嘗試載入任何模組的符號，除非它位於 includedModules 陣列中，或是透過 includeSymbolsNextToModules 設定包含。
• csharp.debug.symbolOptions.moduleFilter.excludedModules - 偵錯工具不應載入其符號的模組陣列。支援萬用字元（範例：MyCompany.*.dll）。除非 mode 設定為 loadAllButExcluded，否則將忽略此屬性。
• csharp.debug.symbolOptions.moduleFilter.includedModules - 偵錯工具應載入其符號的模組陣列。支援萬用字元（範例：MyCompany.*.dll）。除非 mode 設定為 loadOnlyIncluded，否則將忽略此屬性。
• csharp.debug.symbolOptions.moduleFilter.includeSymbolsNextToModules - 若為 true，對於任何不在 includedModules 陣列中的模組，偵錯工具仍會檢查模組本身旁邊和啟動執行檔旁邊，但不會檢查符號搜尋清單上的路徑。此選項預設為 true。除非 mode 設定為 loadOnlyIncluded，否則將忽略此屬性。
• csharp.debug.allowFastEvaluate - 若為 true（預設狀態），偵錯工具將透過模擬簡單屬性和方法的執行來嘗試更快的評估。
• csharp.experimental.debug.hotReload - 若為 true，如果目標應用程式支援熱重新載入，偵錯工具將啟用在偵錯時套用變更。
• csharp.debug.hotReloadOnSave - 若為 true（預設狀態），偵錯工具將在儲存檔案時自動套用程式碼變更。
• csharp.debug.hotReloadVerbosity - 控制 C# 熱重新載入輸出視窗的記錄詳細程度。它可以設定為 minimal（預設）、detailed 或 diagnostic。如果熱重新載入開始出現非預期的行為，建議提高詳細程度。

中斷點

C# 偵錯工具支援各種中斷點，例如原始程式碼行中斷點、條件式中斷點和記錄點。

中斷點 - 條件式中斷點

藉助於運算式評估，偵錯工具也支援條件式中斷點。您可以設定中斷點，以便在運算式評估為 true 時進行中斷。

中斷點 - 函式中斷點

偵錯工具也支援函式中斷點。您可以透過按一下偵錯面板中「中斷點」區段的 +，設定在特定函式中斷。

中斷點 - 記錄點 (Logpoints)

記錄點（在 Visual Studio 中也稱為追蹤點）允許您將輸出傳送到偵錯主控台，而無需編輯程式碼。它們與中斷點不同，因為它們不會停止應用程式的執行流程。

要新增記錄點，請在程式碼行旁邊的最左側邊界按一下滑鼠右鍵。選取新增記錄點並輸入您要記錄的訊息。任何在大括號（'{' 和 '}'）之間的運算式將在到達記錄點時被評估。

記錄訊息中也支援下列權杖

中斷點 - 觸發中斷點

觸發的中斷點是在另一個中斷點被觸及後自動啟用的中斷點。在診斷僅在特定前提條件後發生的程式碼失敗案例時，它們非常有用。

可以透過右鍵點選符號邊界，選取 新增觸發的中斷點，然後選擇哪個其他中斷點來啟用該中斷點。

在例外狀況時停止

C# 偵錯工具支援在擲回或攔截例外狀況時停止的組態選項。這可以透過「執行」檢視中中斷點區段的兩個不同項目來完成

請注意，在首次使用 C# 偵錯工具偵錯資料夾之前，中斷點區段將不會顯示這些項目。

勾選所有例外狀況將會設定偵錯工具，使其在例外狀況被擲回時停止。如果已啟用 Just My Code（預設已啟用），則如果例外狀況在程式庫程式碼中被內部擲回並攔截，偵錯工具將不會中斷。不過，如果例外狀況是在程式庫程式碼中擲回並傳回使用者程式碼，則偵錯工具將會中斷。

勾選使用者未處理的例外狀況將會設定偵錯工具，使其在例外狀況於使用者程式碼中擲回或穿過使用者程式碼後，在非使用者程式碼中被攔截時停止。成為使用者未處理的例外狀況並不總是代表受偵錯處理序中有 Bug——這可能是使用者程式碼正在實作 API 並預期會引發例外狀況。在許多情況下這確實是個問題，因此偵錯工具預設會在例外狀況變為使用者未處理時停止。

例外狀況條件

兩個核取方塊皆支援條件，僅在選定的例外狀況類型時中斷。要編輯條件，請選取鉛筆圖示（請見上圖）或在項目上按右鍵並呼叫編輯條件。條件是以逗號分隔的例外狀況類型清單，若清單以 '!' 開頭，則為要忽略的例外狀況類型清單。

範例條件

運算式評估

偵錯工具還允許您在監看式視窗以及偵錯主控台中評估運算式。

熱重新載入 (Hot Reload)

安裝 C# Dev Kit 擴充功能後，偵錯工具允許您在偵錯時套用 C# 程式碼變更。

若要啟用熱重新載入，必須將 csharp.experimental.debug.hotReload 設定為 true，詳情請參閱使用者設定。只有當目標偵錯引擎支援套用程式碼變更時，熱重新載入工作階段才會啟動。

支援的專案和案例

C# Dev Kit 支援「傳統」熱重新載入體驗，也稱為「編輯並繼續」。無論您是在中斷點停止還是在程式執行中，都可以套用程式碼變更。

截至 2023 年 11 月，某些功能（例如 MetadataUpdateHandler）尚不可用，該功能可讓 ASP.NET Core 應用程式在變更後自動重新整理瀏覽器。也不支援在不偵錯的情況下套用程式碼變更。

執行階段在 .NET 8 中增加了對 Linux/macOS 上偵錯時套用變更的支援，因此在這些作業系統上執行 .NET 應用程式時，需要 .NET 8+ 的執行階段版本。

請參閱支援的專案以取得有關 C# Dev Kit 目前支援專案的更多資訊。另請參閱 C# Dev Kit 常見問題集以取得有關疑難排解其他不支援案例的詳細資訊。

如何套用程式碼變更

一旦熱重新載入工作階段啟動並進行了新的變更，您可以使用下列任何動作將這些變更套用到您的應用程式

後續步驟

繼續閱讀以了解

• 偵錯 - 了解如何將 VS Code 中的偵錯工具用於您專案中的任何語言。