對 ASP.NET Core 應用程式進行偵錯

本文介紹如何偵錯 Blazor 應用程式，包括使用瀏覽器開發人員工具或整合式開發環境 (IDE) 對 Blazor WebAssembly 應用程式進行偵錯。

Blazor Web 應用程式可以在 Visual Studio 或 Visual Studio Code 中進行偵錯。

Blazor WebAssembly 應用程式的偵錯方式包括：

• 在 Visual Studio 或 Visual Studio Code。
• 在以 Chromium 為基礎的瀏覽器中使用瀏覽器開發人員工具，此類瀏覽器包括 Microsoft Edge、Google Chrome，以及 Firefox。

Blazor WebAssembly 偵錯的可用案例包括：

• 設定和移除中斷點。
• 在 IDE 中執行具有偵錯支援的應用程式。
• 逐步執行程式碼。
• 使用 IDE 中的鍵盤快速鍵繼續執行程式碼。
• 在 [區域變數] 視窗中，觀察區域變數的值。
• 請參閱呼叫堆疊，包括 JavaScript 與 .NET 之間的呼叫鏈。
• 使用符號伺服器進行偵錯，由 Visual Studio 喜好設定。

不支援的案例包括：

• 在非本機案例中偵錯 (例如 Windows 子系統 Linux 版 (WSL) 或 Visual Studio Codespaces)。
• 透過 Visual Studio 或 Visual Studio Code 在 Firefox 中進行偵錯。

必要條件

本節說明偵錯的必要條件。

瀏覽器必要條件

下列瀏覽器的最新版本：

• Google Chrome
• Microsoft Edge
• Firefox (僅限瀏覽器開發人員工具)

請確定防火牆或 Proxy 不會封鎖與偵錯 Proxy (NodeJS 處理程序) 的通訊。 如需詳細資訊，請參閱防火牆設定一節。

注意

目前不支援 macOS 上的 Apple Safari。

整合式開發環境 (IDE) 必要條件

最新版本的 Visual Studio 或 Visual Studio Code 是必要條件。

Visual Studio Code 必要條件

Visual Studio Code 需要適用於 Visual Studio Code 的 C# 開發套件 (VS Code 中的 C# 使用者入門)。 在 Visual Studio Code Extensions Marketplace 中，使用 “c# dev kit” 篩選延伸模組清單，找到延伸模組：

安裝 C# 開發套件會自動安裝下列其他延伸模組：

• .NET 安裝工具
• C#
• 適用於 C# 開發套件的 IntelliCode

如果您遇到警告或錯誤，可以開啟問題 (microsoft/vscode-dotnettoolsGitHub 存放庫) 以描述問題。

應用程式組態必要條件

本小節的指導適用於用戶端偵錯。

開啟啟動專案的 Properties/launchSettings.json 檔案。 確認檔案 profiles 節點的每個啟動設定檔都具有下列 inspectUri 屬性。 如果缺少下列屬性，請將其新增至每個設定檔：

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"

inspectUri 屬性：

• 可讓 IDE 偵測應用程式是否為 Blazor 應用程式。
• 指示指令碼偵錯基礎結構透過 Blazor 的偵錯 Proxy 連線到瀏覽器。

架構會提供 WebSocket 通訊協定 (wsProtocol)、主機 (url.hostname)、連接埠(url.port) 和啟動瀏覽器 (browserInspectUri) 上偵測器 URI 的預留位置值。

套件

Blazor Web 應用程式：Microsoft.AspNetCore.Components.WebAssembly.Server參考共用瀏覽器偵錯主機的元件內部套件 (Microsoft.NETCore.BrowserDebugHost.Transport)。

獨立 Blazor WebAssembly：Microsoft.AspNetCore.Components.WebAssembly.DevServer：建置 Blazor 應用程式時要使用的開發伺服器。 在內部呼叫 WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging 以新增中介軟體以在 Chromium 開發人員工具內偵錯 Blazor WebAssembly 應用程式。

注意

如需將套件新增至 .NET 應用程式的指引，請參閱在套件取用工作流程 (NuGet 文件) 的安裝及管理套件底下的文章。 在 NuGet.org 確認正確的套件版本。

在 IDE 中偵錯 Blazor Web 應用程式

Visual Studio

本節的範例假設您已使用 Auto (Server 和 WebAssembly) 的互動式轉譯模式和每個元件互動功能位置，建立 Blazor Web 應用程式。

1. 開啟應用程式。
2. 在用戶端專案 (.Client) Counter 元件 (Pages/Counter.razor) 的 currentCount++; 行上設定中斷點。
3. 按下 F5 以在偵錯工具中執行應用程式。
4. 在瀏覽器中，瀏覽至位於 /counter 的 Counter 頁面。 稍候幾秒鐘等待偵錯 Proxy 載入並執行。 選取 [按一下我] 按鈕以叫用中斷點。
5. 在 Visual Studio 中，檢查 [區域變數] 視窗中的 currentCount 欄位值。
6. 按 [F5] 繼續執行。

您也可以在靜態轉譯和互動式轉譯伺服器端元件的伺服器專案叫用中斷點。

1. 停止偵錯工具。

2. 將下列元件新增至伺服器應用程式。 元件採用互動式伺服器轉譯模式 (InteractiveServer)。

   Components/Pages/Counter2.razor：

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. 在 Counter2 元件中的 currentCount++; 行上設定中斷點。

4. 按下 F5 以在偵錯工具中執行應用程式。

5. 在瀏覽器中，瀏覽至位於 /counter-2 的 Counter2 頁面。 稍候幾秒鐘等待偵錯 Proxy 載入並執行。 選取 [按一下我] 按鈕以叫用中斷點。

6. 按 [F5] 繼續執行。

在偵錯 Proxy 執行之前，應用程式啟動期間不會叫用中斷點。 這包括 Program 檔案中的中斷點，以及應用程式所要求第一頁載入元件的 OnInitialized{Async} 生命週期方法中斷點。

Visual Studio Code

本節的範例假設您已使用互動式 Auto (Server 和 WebAssembly) 的轉譯模式和每個元件互動功能位置，建立 Blazor Web 應用程式。

1. 開啟解決方案資料夾 (包含伺服器和 .Client 專案資料夾的資料夾)，在 Visual Studio Code 開啟應用程式。
2. 在用戶端專案 (.Client) Counter 元件 (Pages/Counter.razor) 的 currentCount++; 行上設定中斷點。
3. 開啟 [執行和偵錯]窗格，然後選取 [執行和偵錯]按鈕。 或者是按 F5([開始偵錯])。 在 UI 最上方的命令選擇區選取 C# 偵錯工具。 選取伺服器專案的預設設定檔 (例如 C#:BlazorSample [Default Configuration])。
4. 在瀏覽器中，瀏覽至位於 /counter 的 Counter 頁面。 稍候幾秒鐘等待偵錯 Proxy 載入並執行。 選取 [按一下我] 按鈕以叫用中斷點。
5. 選取 UI 中的 [繼續]按鈕，或按 F5 ([繼續])繼續執行。

您也可以在伺服器專案內叫用中斷點。

1. 選取 [停止]按鈕，或在鍵盤按 Shift+F5，停止偵錯。

2. 將下列元件新增至伺服器應用程式。 元件採用互動式伺服器轉譯模式 (InteractiveServer)。

   Components/Pages/Counter2.razor：

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. 在 Counter2 元件中的 currentCount++; 行上設定中斷點。

4. 選取 UI 中的 [開始偵錯]按鈕，或按 F5([開始偵錯]，在偵錯工具執行應用程式。

5. 在瀏覽器中，瀏覽至位於 /counter-2 的 Counter2 頁面。 稍候幾秒鐘等待偵錯 Proxy 載入並執行。 選取 [按一下我] 按鈕以叫用中斷點。

6. 選取 UI 中的 [繼續]按鈕，或按 F5 ([繼續])繼續執行。

在偵錯 Proxy 執行之前，應用程式啟動期間不會叫用中斷點。 這包括 Program 檔案中的中斷點，以及應用程式所要求第一頁載入元件的 OnInitialized{Async} 生命週期方法中斷點。

不支援啟動但不偵錯 [Ctrl+F5 (Windows) 或 ⌘+F5 (macOS)]。 當應用程式以偵錯設定執行時，偵錯的額外負荷一律會導致效能小幅降低。

在 IDE 中偵錯 Blazor WebAssembly 應用程式

Visual Studio

1. 開啟應用程式。
2. 在 Counter 元件 (Pages/Counter.razor) 的 currentCount++; 行上設定中斷點。
3. 按下 F5 以在偵錯工具中執行應用程式。
4. 在瀏覽器中，瀏覽至位於 /counter 的 Counter 頁面。 稍候幾秒鐘等待偵錯 Proxy 載入並執行。 選取 [按一下我] 按鈕以叫用中斷點。
5. 在 Visual Studio 中，檢查 [區域變數] 視窗中的 currentCount 欄位值。
6. 按 [F5] 繼續執行。

在偵錯 Proxy 執行之前，應用程式啟動期間不會叫用中斷點。 這包括 Program 檔案中的中斷點，以及應用程式所要求第一頁載入元件的 OnInitialized{Async} 生命週期方法中斷點。

Visual Studio Code

1. 在 Visual Studio Code 開啟應用程式資料夾。
2. 在 Counter 元件 (Pages/Counter.razor) 的 currentCount++; 行上設定中斷點。
3. 開啟 [執行和偵錯]窗格，然後選取 [執行和偵錯]按鈕。 或者是按 F5([開始偵錯])。 在 UI 最上方的命令選擇區選取 C# 偵錯工具。 選取預設設定檔 (例如 C#:BlazorSample [Default Configuration])。
4. 按下 F5 以在偵錯工具中執行應用程式。
5. 獨立應用程式隨即啟動，並開啟偵錯瀏覽器。
6. 在瀏覽器中，瀏覽至位於 /counter 的 Counter 頁面。 稍候幾秒鐘等待偵錯 Proxy 載入並執行。 選取 [按一下我] 按鈕以叫用中斷點。
7. 按 [F5] 繼續執行。

在偵錯 Proxy 執行之前，應用程式啟動期間不會叫用中斷點。 這包括 Program 檔案中的中斷點，以及應用程式所要求第一頁載入元件的 OnInitialized{Async} 生命週期方法中斷點。

不支援啟動但不偵錯 [Ctrl+F5 (Windows) 或 ⌘+F5 (macOS)]。 當應用程式以偵錯設定執行時，偵錯的額外負荷一律會導致效能小幅降低。

偵錯工具支援

當使用 <DebuggerSupport>{VALUE}</DebuggerSupport> 啟用偵錯支援時，將為運行時間啟用偵錯，其中 {VALUE}預留位置為 true 或 false。

根據預設， Blazor 架構會 停用所有非偵錯組態調的偵錯支援。 若要啟用非偵錯設定的偵錯支援，請將 <DebuggerSupport> 屬性新增至應用程式的專案檔。

在下列範例中，會為自訂「DebugCustom」設定啟用的偵錯工具支援:

<DebuggerSupport Condition="'$(Configuration)' == 'DebugCustom'">true</DebuggerSupport>

如需詳細資訊，請參閱 自訂偵錯工具設定Blazor WebAssembly。(dotnet/runtime #96239)。

附加至現有的 Visual Studio Code 偵錯工作階段

若要附加至執行中的 Blazor 應用程式，請開啟 .vscode/launch.json 檔案，並將 {URL} 預留位置取代為執行應用程式的 URL：

{
  "name": "Attach and Debug",
  "type": "blazorwasm",
  "request": "attach",
  "url": "{URL}"
}

Visual Studio Code 啟動選項

下表中的啟動設定選項支援 blazorwasm 偵錯類型 (.vscode/launch.json)。

選項	描述
browser	為偵錯工作階段啟動的瀏覽器。 設為 edge 或 chrome。 預設為 edge。
cwd	要在其中啟動應用程式的工作目錄。
request	使用 launch 啟動偵錯工作階段並附加至 Blazor WebAssembly 應用程式，或使用 attach 將偵錯工作階段附加至執行中的應用程式。
timeout	等待偵錯工作階段附加的毫秒數。 預設為 30,000 毫秒 (30 秒)。
trace	用來從 JS 偵錯工具產生記錄。 設定為 true 以產生記錄。
url	偵錯時在瀏覽器中開啟的 URL。
webRoot	指定網頁伺服器的絕對路徑。 如果透過子路由提供應用程式，則應該設定。

使用 Google Chrome 或 Microsoft Edge 對 Blazor WebAssembly 進行偵錯

本節中的指引適用於在下列環境對 Blazor WebAssembly 應用程式進行偵錯：

• 在 Windows 或 macOS 上執行的 Google Chrome。
• 在 Windows 上執行的 Microsoft Edge。

1. 使用 dotnet run 在命令殼層中執行應用程式。

2. 啟動瀏覽器並瀏覽至應用程式的 URL。

3. 若要開始遠端偵錯，請使用下列按鍵組合：

   • Windows 為 Shift+Alt+d。
   • macOS 為 Shift+⌘+d。

   瀏覽器必須在啟用遠端偵錯的狀況下執行，該設定並未預設啟用。 如果停用遠端偵錯，則會顯示找不到可偵錯的瀏覽器索引標籤錯誤頁面，並顯示啟動瀏覽器並開啟偵錯連接埠的指示。 請遵循瀏覽器的指示。

   遵循啟用遠端偵錯的指示之後，應用程式隨即在新的瀏覽器視窗開啟。 在新瀏覽器視窗按 HotKey 組合，啟動遠端偵錯：

   • Windows 為 Shift+Alt+d。
   • macOS 為 Shift+⌘+d。

   新的視窗開發人員工具瀏覽器索引標籤開啟，並顯示應用程式的映像影像。

   注意

   如果您遵循指示，開啟已啟用遠端偵錯的新瀏覽器索引標籤，您可以關閉原始瀏覽器視窗，保持開啟第二個視窗，讓第一個索引標籤執行應用程式，以及讓第二個索引標籤執行偵錯工具。

4. 稍後一段時間後，[來源] 索引標籤會顯示應用程式的 .NET 元件和頁面清單。

5. 開啟 file:// 節點。 在元件程式碼 (.razor 檔案) 和 C# 程式碼檔案 (.cs)，當程式碼在應用程式的瀏覽器索引標籤執行時，會叫用您設定的中斷點 (啟動遠端偵錯之後開啟的初始索引標籤)。 叫用中斷點之後，逐步執行 (F10) 程式碼，或是在偵錯索引標籤如常繼續執行 (F8) 程式碼。

針對以 Chromium 為基礎的瀏覽器偵錯，Blazor 提供偵錯 Proxy 以實作 Chrome DevTools 通訊協定，並使用 .NET 特定資訊來強化通訊協定。 按下鍵盤快速鍵偵錯時，Blazor 會將 Chrome DevTools 指向 Proxy。 Proxy 會連線到您要偵錯的瀏覽器視窗 (因此需要啟用遠端偵錯)。

使用 Firefox 對 Blazor WebAssembly 應用程式進行偵錯

本節中的指引適用於在 Windows 上執行的 Firefox 中對 Blazor WebAssembly 應用程式進行偵錯。

用 Firefox 對 Blazor WebAssembly 應用程式進行偵錯需要設定瀏覽器以進行遠端偵錯，並使用瀏覽器開發人員工具透過 .NET WebAssembly 偵錯 Proxy 連線到瀏覽器。

注意

目前不支援透過 Visual Studio 在 Firefox 中偵錯。

若要在開發期間對 Firefox 中的 Blazor WebAssembly 應用程式進行偵錯：

1. 設定 Firefox：
   • 在新瀏覽器索引標籤中開啟 about:config。閱讀並關閉出現的警告。
   • 將值設定為 True，啟用 devtools.debugger.remote-enabled。
   • 將值設定為 True，啟用 devtools.chrome.enabled。
   • 將值設定為 False，停用 devtools.debugger.prompt-connection。
2. 關閉所有 Firefox 執行個體。
3. 使用 dotnet run 在命令殼層中執行應用程式。
4. 重新啟動 Firefox 瀏覽器並瀏覽至應用程式。
5. 在新瀏覽器索引標籤中開啟 about:debugging。將此索引標籤保持開啟。
6. 返回執行應用程式的索引標籤。 若要開始遠端偵錯，請使用 Shift+Alt+d 這個按鍵組合。
7. 在 Debugger 索引標籤中，開啟您想要在 file:// 節點下偵錯的應用程式來源檔案，並設定中斷點。 例如，在 Counter 元件 (Pages/Counter.razor) 之 IncrementCount 方法的 currentCount++; 行設定中斷點。
8. 瀏覽至應用程式瀏覽器索引標籤的 Counter 元件頁面 (/counter)，然後選取計數器按鈕叫用中斷點。
9. 按 F5，繼續在偵錯索引標籤執行。

發生未處理的例外狀況時中斷

偵錯工具預設不會中斷未處理的例外狀況，因為 Blazor 會攔截開發人員程式碼未處理的例外狀況。

若要在未處理的例外狀況處中斷：

• 在 Visual Studio 開啟偵錯工具的例外狀況設定 ([偵錯]>[Windows]>[例外狀況設定]。
• 設定下列 JavaScript 例外狀況設定：
  • 所有例外狀況
  • 未攔截的例外狀況

瀏覽器來源對應

瀏覽器來源對應可讓瀏覽器將編譯的檔案對應回其原始來源檔案，且通常用於用戶端偵錯。 不過 Blazor 目前不會將 C# 直接對應至 JavaScript/WASM。 相對地，Blazor 會在瀏覽器中執行 IL 解譯，因此不會用到來源對應。

防火牆設定

如果防火牆封鎖與偵錯 Proxy 的通訊，請建立防火牆例外規則以允許瀏覽器與 NodeJS 處理程序之間的通訊。

警告

修改防火牆設定時請謹慎小心，以避免造成安全性弱點。 請謹慎執行安全性指引、遵循最佳安全性作法，並遵守防火牆製造商發出的警告。

允許與 NodeJS 處理程序進行開放式通訊：

• 根據防火牆的功能和設定，將節點伺服器開放任意連線。
• 此操作可能會產生風險，取決於您的網路。
• 僅建議在開發人員電腦上使用。

可能的話，只允許在信任或私人網路上與 NodeJS 處理程序建立開放式通訊。

如需 Windows 防火牆設定指引，請參閱建立輸入程式或服務規則。 如需詳細資訊，請參閱 Windows 防火牆文件集內的 具備進階安全性的 Windows Defender 防火牆及相關文章。

疑難排解

如果您遇到錯誤，下列秘訣可能會有幫助：

• 移除中斷點：
  • Google Chrome：在 [偵錯工具] 索引標籤中，開啟瀏覽器中的開發人員工具。 在主控台中，執行 localStorage.clear() 以移除所有中斷點。
  • Microsoft Edge：在 [應用程式] 索引標籤中，開啟 [本機存放裝置]。 以滑鼠右鍵按一下網站，然後選取 [清除]。
• 確認您已安裝並信任 ASP.NET Core HTTPS 開發憑證。 如需詳細資訊，請參閱在 ASP.NET Core 中強制執行 HTTPS。
• Visual Studio 需要 [工具]>[選項]>[偵錯]>[一般] 中的[為 ASP.NET 啟用 JavaScript 偵錯 (Chrome 和 Edge)] 選項。 這是 Visual Studio 的預設設定。 如果偵錯無法運作，請確認該選項已選取。
• 如果您的環境使用 HTTP Proxy，請確定在 Proxy 略過設定中包含 localhost。 這可以藉由在下列任一項目中設定 NO_PROXY 環境變數來完成：
  • 專案的 launchSettings.json 檔案。
  • 在其使用者或系統內容變數層級，套用至所有應用程式。 使用環境變數時，請重新啟動 Visual Studio，讓變更生效。
• 請確定防火牆或 Proxy 不會封鎖與偵錯 Proxy (NodeJS 處理程序) 的通訊。 如需詳細資訊，請參閱防火牆設定一節。

未叫用的 OnInitialized{Async} 中斷點

Blazor 架構的偵錯 Proxy 不會在應用程式啟動時立即啟動，因此可能不會叫用 OnInitialized{Async} 生命週期方法的中斷點。 建議您在方法主體的開頭新增延遲，以便在叫用中斷點之前，讓偵錯 Proxy 有一些時間啟動。 您可以根據 if 編譯器指示詞來包含延遲，以確保應用程式的發行組建沒有延遲。

OnInitialized：

protected override void OnInitialized()
{
#if DEBUG
    Thread.Sleep(10000);
#endif

    ...
}

OnInitializedAsync：

protected override async Task OnInitializedAsync()
{
#if DEBUG
    await Task.Delay(10000);
#endif

    ...
}

Visual Studio (Windows) 逾時

如果 Visual Studio 擲回無法啟動偵錯配接器的例外狀況，指出已達到逾時，您可以使用登錄設定來調整逾時：

VsRegEdit.exe set "<VSInstallFolder>" HKCU JSDebugger\Options\Debugging "BlazorTimeoutInMilliseconds" dword {TIMEOUT}

上述命令中的 {TIMEOUT} 預留位置以毫秒為單位。 例如，請將一分鐘指派為 60000。