除錯

您可以使用 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 中的除錯。

使用解決方案資源管理器進行除錯

安裝 C# Dev Kit 擴充套件後，在解決方案資源管理器中右鍵單擊專案時，會出現一個“除錯”上下文選單。

有三個選項

• 啟動新例項 - 以附加偵錯程式的方式啟動您的專案。
• 不除錯啟動 - 在不附加偵錯程式的情況下執行您的專案。
• 單步進入新例項 - 以附加偵錯程式的方式啟動您的專案，但會在程式碼的入口點停止。

使用命令面板進行除錯

安裝 C# Dev Kit 擴充套件後，您還可以透過命令面板 ⇧⌘P (Windows、Linux Ctrl+Shift+P) 使用 Debug: Select and Start Debugging 命令來啟動除錯。

注意：這會將一個啟動配置條目新增到您的除錯下拉列表中。

使用動態（記憶體中）啟動配置進行除錯

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

現有的 launch.json

如果您有一個現有的 launch.json，可以轉到“除錯”檢視，選擇下拉列表，然後選擇 C# 選項。這將為您提供一系列可以新增到下拉列表中的啟動目標。選擇後，您可以按 F5 或使用新生成的配置選擇“開始除錯”。

沒有 launch.json

如果您的專案中沒有 launch.json，可以在“除錯”檢視的“顯示所有自動除錯配置”中新增並訪問這些動態配置。

刪除動態（記憶體中）啟動配置

您可以使用命令面板 ⇧⌘P (Windows、Linux Ctrl+Shift+P) 並使用命令 Debug: Select and Start Debugging 來刪除已生成的配置。

在下拉列表中，它列出了您所有現有的除錯配置。如果您將滑鼠懸停在動態配置上，右側會出現一個可點選的垃圾桶圖示。您可以選擇該圖示來刪除動態配置。

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

當編輯器中開啟一個 .cs 檔案時，可以透過編輯器視窗右上角的按鈕訪問執行和除錯選項。這些操作將使用當前檔案查詢專案系統並確定要啟動的關聯專案。

兩個選項是

• 執行與此檔案關聯的專案：這將以 noDebug: true 的方式啟動您的程式，並附加偵錯程式。
• 除錯與此檔案關聯的專案：這將以偵錯程式的方式啟動您的程式。

使用 launch.json 進行除錯

如果您正在使用 C# Dev Kit，我們不建議使用此選項。但是，如果您需要直接修改除錯配置，請參閱 為 C# 除錯配置 launch.json。

附加到程序

您可以使用命令面板 ⇧⌘P (Windows、Linux Ctrl+Shift+P) 並執行 Debug: Attach to a .NET 5+ or .NET Core process 命令來附加到 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 的除錯控制檯。此模式允許您在一個地方檢視來自偵錯程式和目標程式的 both 訊息。有關更多詳細資訊，請參閱 完整文件。
  • integratedTerminal - VS Code 的整合終端。
  • externalTerminal - 可以透過使用者設定配置的外部終端。
• csharp.debug.sourceFileMap - 將構建時路徑對映到本地源位置。構建時路徑的所有例項都將被替換為本地源路徑。
    示例
      {\"<build-path>\":\"<local-source-path>\"}
• csharp.debug.justMyCode - 啟用時（預設），偵錯程式僅顯示和單步進入使用者程式碼（“我的程式碼”），忽略系統程式碼和其他已最佳化或沒有除錯符號的程式碼。 更多資訊。
• 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 - 確定啟動 Web 瀏覽器時的 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）在目標程序中載入時，偵錯程式會請求即時（JIT）編譯器生成不帶最佳化功能的程式碼。 更多資訊
• csharp.debug.symbolOptions.searchPaths - 用於搜尋 .pdb 檔案的符號伺服器 URL（例如：http://MyExampleSymbolServer）或目錄（例如：/build/symbols）的陣列。除了預設位置（緊鄰模組）和 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# Hot Reload** 輸出視窗的日誌詳細程度。可以設定為 minimal（預設）、detailed 或 diagnostic。如果熱過載開始出現意外行為，建議提高詳細程度。

Breakpoints

C# 偵錯程式支援各種斷點，例如源行斷點、條件斷點和日誌點。

斷點 - 條件斷點

藉助表示式評估，偵錯程式還支援條件斷點。您可以設定斷點，在表示式評估為 true 時中斷。

斷點 - 函式斷點

偵錯程式還支援函式斷點。您可以透過單擊“除錯”窗格的“斷點”部分中的 + 來設定斷點，以便在特定函式處中斷。

斷點 - 日誌點

日誌點（在 Visual Studio 中也稱為跟蹤點）允許您在不編輯程式碼的情況下將輸出傳送到除錯控制檯。它們與斷點不同，因為它們不會停止應用程式的執行流。

要新增日誌點，請右鍵單擊程式碼行旁邊的最左側邊距。選擇“新增日誌點”並鍵入要記錄的訊息。花括號 ({}) 之間的任何表示式將在命中日誌點時進行評估。

日誌訊息還支援以下標記

斷點 - 觸發斷點

觸發斷點是一種在另一個斷點命中後自動啟用的斷點。當代碼中出現僅在特定先決條件發生後才出現的故障情況時，它們非常有用。

可以透過右鍵單擊字形邊距，選擇 新增觸發斷點，然後選擇哪個其他斷點啟用此斷點來設定觸發斷點。

在異常處停止

C# 偵錯程式支援在丟擲或捕獲異常時偵錯程式停止的配置選項。這透過“執行”檢視的“斷點”部分中的兩個不同條目來實現。

請注意，在資料夾首次使用 C# 偵錯程式進行除錯之前，“斷點”部分將缺少這些條目。

勾選“所有異常”會將偵錯程式配置為在丟擲異常時停止。如果啟用了 “僅我的程式碼”（預設啟用），則在庫程式碼中內部丟擲並捕獲異常時，偵錯程式不會中斷。但是，如果異常在庫程式碼中丟擲並返回到使用者程式碼，偵錯程式將中斷。

勾選“使用者未處理的異常”會將偵錯程式配置為在從使用者程式碼丟擲或透過使用者程式碼傳播後，在非使用者程式碼中捕獲到異常時停止。使用者未處理的異常並不總是被除錯程序中的 bug——這可能是使用者程式碼正在實現一個 API 並預計會引發異常。在許多情況下，這是一個實際問題，因此，預設情況下，偵錯程式將在異常變為使用者未處理時停止。

異常條件

兩個複選框都支援條件，以便僅對選定的異常型別進行中斷。要編輯條件，請選擇鉛筆圖示（參見上圖），或右鍵單擊該條目並呼叫“編輯條件”。條件是用於中斷的異常型別的逗號分隔列表，如果列表以 '!' 開頭，則表示要忽略的異常型別列表。

條件示例

Expression evaluation

偵錯程式還允許您在“監視”視窗以及除錯控制檯中評估表示式。

熱過載

安裝 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 FAQ。

如何應用程式碼更改

一旦熱過載會話啟動並進行新更改，您就可以透過以下任一操作將這些更改應用到您的應用程式：

後續步驟

繼續閱讀以瞭解：

• 除錯 - 瞭解如何為任何語言的專案在 VS Code 中使用偵錯程式。