偵錯

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

執行與偵錯

C# 擴充功能以及 C# 開發套件提供多種執行和偵錯 C# 應用程式的方式。

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

使用 F5 偵錯

在安裝 C# 開發套件擴充功能且偵錯檢視中沒有可選取的偵錯組態的情況下，您可以開啟 .cs 檔案，然後按下 F5 來開始偵錯專案。偵錯工具會自動尋找您的專案並開始偵錯。如果您有多個專案，系統會提示您要開始偵錯哪個專案。

您也可以從 VS Code 側邊欄的 [執行和偵錯] 檢視開始偵錯工作階段。如需詳細資訊，請參閱VS Code 中的偵錯。

使用方案總管偵錯

在安裝 C# 開發套件擴充功能後，當您在方案總管中以滑鼠右鍵按一下專案時，會有 [偵錯] 內容功能表。

有三個選項

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

使用命令面板偵錯

在安裝 C# 開發套件擴充功能後，您也可以從命令面板 ⇧⌘P (Windows、Linux Ctrl+Shift+P) 使用 [偵錯: 選取並開始偵錯] 命令來開始偵錯。

注意：這會將啟動組態項目新增至您的偵錯下拉式清單。

使用動態 (記憶體內) 啟動組態偵錯

在安裝 C# 開發套件擴充功能後，您可以建立動態啟動組態。建立方式取決於您的專案是否有現有的 launch.json 檔案。

現有的 launch.json

如果您有現有的 launch.json，您可以移至 [偵錯] 檢視，選取下拉式清單，然後選取 [C#] 選項。這應該會提供您可以新增至下拉式清單的啟動目標選取項目。選取後，您可以按下 F5 或使用新產生的組態來 [開始偵錯]。

沒有 launch.json

如果您的專案中沒有 launch.json，您可以在 [偵錯] 檢視的 [顯示所有自動偵錯組態] 中新增和存取這些動態組態。

移除動態 (記憶體內) 啟動組態

您可以使用命令面板 ⇧⌘P (Windows、Linux Ctrl+Shift+P) 和 [偵錯: 選取並開始偵錯] 命令來移除產生的組態。

在下拉式清單中，它會列出所有現有的偵錯組態。如果您將滑鼠指標停留在動態組態上方，右側會出現可按一下的垃圾桶圖示。您可以選取該圖示來移除動態組態。

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

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

有兩個選項

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

使用 launch.json 偵錯

如果您使用 C# 開發套件，我們建議不要使用此選項。但是，如果您需要直接修改偵錯組態，請參閱設定 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 - 啟用時 (預設值)，偵錯工具只會顯示和逐步執行使用者程式碼 ("我的程式碼")，而忽略系統程式碼以及其他已最佳化或沒有偵錯符號的程式碼。更多資訊。
• 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，當最佳化模組 (.dll 在發行組態中編譯) 載入目標處理程序時，偵錯工具會要求 Just-In-Time 編譯器產生已停用最佳化的程式碼。更多資訊
• 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，如果目標應用程式支援 Hot Reload，偵錯工具將啟用在偵錯時套用變更。
• csharp.debug.hotReloadOnSave - 如果為 true (預設狀態)，偵錯工具會在儲存檔案時自動套用程式碼變更。
• csharp.debug.hotReloadVerbosity - 控制 C# Hot Reload 輸出視窗的記錄詳細程度。它可以設定為 minimal (預設)、detailed 或 diagnostic。如果 Hot Reload 開始出現非預期的行為，建議增加詳細程度層級。

中斷點

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

中斷點 - 條件式中斷點

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

中斷點 - 函式中斷點

偵錯工具也支援功能中斷點。您可以按一下 [偵錯] 窗格之 [中斷點] 區段中的 +，將中斷點設定為在特定函式上中斷。

中斷點 - 記錄點

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

若要新增記錄點，請在程式碼行旁邊的最左邊邊界中按一下滑鼠右鍵。選取 [新增記錄點]，然後輸入您要記錄的訊息。當點擊記錄點時，會評估大括號 ('{' 和 '}') 之間的任何運算式。

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

中斷點 - 觸發的中斷點

觸發的中斷點是在點擊另一個中斷點後自動啟用的中斷點。當診斷僅在特定先決條件之後發生的程式碼失敗案例時，它們可能非常有用。

可以透過在字元形狀邊界上按一下滑鼠右鍵、選取 [新增觸發的中斷點]，然後選擇哪個其他中斷點啟用中斷點來設定觸發的中斷點。

例外狀況時停止

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

請注意，在第一次使用 C# 偵錯工具偵錯資料夾之前，[中斷點] 區段會缺少這些項目。

勾選 [所有例外狀況] 將組態偵錯工具，以便在擲回例外狀況時停止。如果啟用僅我的程式碼 (預設為啟用)，如果例外狀況在程式庫程式碼中內部擲回和攔截，偵錯工具將不會中斷。但是，如果例外狀況在程式庫程式碼中擲回並傳回至使用者程式碼，偵錯工具將會中斷。

勾選 [使用者未處理的例外狀況] 將組態偵錯工具，以便在使用者程式碼中擲回或在使用者程式碼中傳遞後，在非使用者程式碼中攔截例外狀況時停止。變成使用者未處理的例外狀況不一定是偵錯處理程序中的錯誤，可能是使用者程式碼正在實作 API，而且預期會引發例外狀況。在許多情況下，存在實際問題，因此，預設情況下，當例外狀況變成使用者未處理時，偵錯工具將會停止。

例外狀況條件

這兩個核取方塊都支援僅在選取的例外狀況類型上中斷的條件。若要編輯條件，請選取鉛筆圖示 (請參閱上方影像)，或以滑鼠右鍵按一下項目並叫用 [編輯條件]。條件是要中斷的例外狀況類型逗號分隔清單，如果清單以 '!' 開頭，則是要忽略的例外狀況類型清單。

範例條件

運算式評估

偵錯工具也讓您可以在 [監看式] 視窗以及 [偵錯主控台] 中評估運算式。

Hot Reload

在安裝 C# 開發套件擴充功能後，偵錯工具可讓您在偵錯時套用 C# 程式碼變更。

為了啟用 Hot Reload，csharp.experimental.debug.hotReload 必須設定為 true，如需更多資訊，請參閱使用者設定。只有在目標偵錯工具引擎支援套用程式碼變更時，Hot Reload 工作階段才會開始。

支援的專案和案例

C# 開發套件支援「傳統」Hot Reload 體驗，也稱為「編輯並繼續」。您可以套用程式碼變更，同時進行偵錯，無論您是否停在中斷點或程式是否正在執行。

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

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

如需目前 C# 開發套件支援之專案的詳細資訊，請參閱支援的專案。如需疑難排解其他不支援案例的詳細資訊，另請參閱 C# 開發套件常見問題集。

如何套用程式碼變更

一旦 Hot Reload 工作階段開始並進行新的變更，您可以使用下列任何動作將這些變更套用至您的應用程式

後續步驟

繼續閱讀以瞭解

• 偵錯 - 瞭解如何在 VS Code 中將偵錯工具與任何語言的專案搭配使用。