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

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

Blazor Web App可以在 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 喜好設定。

不支援的案例包括：

• 在非本機環境中偵錯（例如 適用於 Linux 的 Windows 子系統 (WSL) 或 Visual Studio Codespaces）。
• 透過 Visual Studio 或 Visual Studio Code 在 Firefox 中進行偵錯。

必要條件

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

瀏覽器必要條件

下列瀏覽器的最新版本：

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

請確定防火牆或代理伺服器不會封鎖與偵錯代理伺服器（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 檔案。 確認檔案 inspectUri 節點的每個啟動設定檔都具有下列 profiles 屬性。 如果缺少下列屬性，請將其新增至每個設定檔：

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

inspectUri 屬性：

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

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

注意

當使用 .NET CLI 執行應用程式時，預設會使用 launchSettings.json 中其 commandName 為 Project 的第一個啟動設定檔。 若要使用不同的設定檔（例如 https），請將 -lp|--launch-profile 選項 傳遞給 dotnet watch 或 dotnet run，或將偏好的設定檔移至檔案頂端。

套件

Blazor Web Apps: Microsoft.AspNetCore.Components.WebAssembly.Server：參照供共用瀏覽器偵錯主機的組件使用的內部套件 (Microsoft.NETCore.BrowserDebugHost.Transport)。

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

注意

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

在 IDE 中偵錯 Blazor Web App

Visual Studio

本節中的範例假設您已建立 Blazor Web App，並將互動式轉譯模式設為 Auto（Server 和 WebAssembly），且互動位置設為每個元件。

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

在伺服器專案中，靜態轉譯和互動式轉譯的伺服器端元件內也可以觸發中斷點。

1. 停止偵錯工具。
2. 在伺服器應用程式中，開啟以靜態方式轉譯的 Weather 元件（Components/Pages/Weather.razor），並在 OnInitializedAsync 方法中的任何位置設定中斷點。
3. 按下 F5 以在偵錯工具中執行應用程式。
4. 在瀏覽器中，瀏覽至位於 Weather 的 /weather 頁面。 請稍候幾秒，讓偵錯代理程式載入並執行。 應用程式執行會在斷點停止。
5. 按 [F5] 繼續執行。

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

Visual Studio 程式碼

本節的範例假設您已建立一個 Blazor Web App，並採用互動式 Auto（Server 和 WebAssembly）轉譯模式以及每個元件的互動位置。

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

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

1. 選取 [停止]按鈕，或在鍵盤按 Shift+F5，停止偵錯。
2. 在伺服器應用程式中，開啟以靜態方式轉譯的 Weather 元件（Components/Pages/Weather.razor），並在 OnInitializedAsync 方法中的任何位置設定中斷點。
3. 選取 UI 中的 [開始偵錯]按鈕，或按 F5([開始偵錯]，在偵錯工具執行應用程式。
4. 在瀏覽器中，瀏覽至位於 Weather 的 /weather 頁面。 請稍候幾秒，讓偵錯代理程式載入並執行。 應用程式執行會在斷點停止。
5. 選取 UI 中的 [繼續]按鈕，或按 F5 ([繼續])繼續執行。

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

在 IDE 中偵錯 Blazor WebAssembly 應用程式

Visual Studio

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

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

Visual Studio 程式碼

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

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

附加至現有的 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 watch（或 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 會連線到您要偵錯的瀏覽器視窗 (因此需要啟用遠端偵錯)。

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

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

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

注意

目前不支援從 Visual Studio 在 Firefox 中進行偵錯。

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

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

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

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

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

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

瀏覽器原始碼對應表

瀏覽器來源對應可讓瀏覽器將編譯的檔案對應回其原始來源檔案，且通常用於用戶端偵錯。 不過， Blazor 目前不會將 C# 直接對應至 JavaScript/Wasm。 而是由 Blazor 在瀏覽器中解譯 IL，因此來源映射並不適用。

防火牆設定

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

警告

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

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

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

如果可以，僅允許與 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，讓變更生效。
• 請確定防火牆或代理伺服器不會封鎖與偵錯代理伺服器（NodeJS 程序）的通訊。 如需詳細資訊，請參閱防火牆設定一節。

OnInitialized{Async} 中斷點未命中

Blazor 架構的偵錯 Proxy 不會在應用程式啟動時立即啟動，因此 OnInitialized{Async} 生命週期方法中的中斷點可能不會被命中。 建議您在方法本文開頭加入延遲，讓偵錯代理程式能在命中中斷點之前有時間啟動。 您可以使用 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。

控制熱裝填

WasmEnableHotReload MSBuild 屬性會啟動熱重載，並在true配置建置時預設為Debug。 在任何其他組態中建置時，不會啟用熱重新載入 （設定為 false）。

例如， DebugWebAssembly若要在偵錯時使用自訂組態名稱，將屬性設定為 true 以啟用熱重新載入：

<PropertyGroup>
  <WasmEnableHotReload>true</WasmEnableHotReload>
</PropertyGroup>

若要停用 Debug 組態中的熱重新載入功能，請將值設定為 false：

<PropertyGroup>
  <WasmEnableHotReload>false</WasmEnableHotReload>
</PropertyGroup>