使用 Visual Studio Code 對 WebView2 應用程式進行偵錯

發行項
07/31/2024

使用 Microsoft Visual Studio Code 對在 WebView2 控件中執行的腳本進行偵錯。 Visual Studio Code 具有用於瀏覽器偵錯的內建調試程式。請參閱 VS Code 中的瀏覽器偵錯。

建立launch.json檔案

若要對程式代碼進行偵錯，您的項目必須有 launch.json 檔案。 launch.json檔案是調試程式組態檔，可設定及自定義 Visual Studio Code 調試程式。設定調試程式所需的其中一個屬性是 request 屬性。有兩 request 種類型： launch 和 attach。

下列程式代碼示範如何從 Visual Studio Code (啟動應用程式，而不是將調試程式附加至應用程式) 的執行中實例。若要這樣做，必須先前已建置應用程式。如果您的項目沒有launch.json檔案，請在您目前專案的子資料夾中.vscode建立新launch.json檔案，並將下列程式代碼貼到其中：

"name": "Hello debug world",
"type": "msedge",
"port": 9222, // The port value is optional, and the default value is 9222.
"request": "launch",
"runtimeExecutable": "C:/path/to/your/webview2/app.exe",
"env": {
   // Customize for your app location if needed
   "Path": "%path%;e:/path/to/your/app/location; "
},
"useWebView": true,
// The following two lines set up source path mapping, where `url` is the start page
// of your app, and `webRoot` is the top level directory with all your code files.
"url": "file:///${workspaceFolder}/path/to/your/toplevel/foo.html",
"webRoot": "${workspaceFolder}/path/to/your/assets"

傳入的命令行 URL 參數

Visual Studio Code 來源路徑對應現在需要 URL，因此您的應用程式現在會在 url 啟動時收到命令行參數。如有需要， url 您可以放心地忽略參數。

對程式代碼進行偵錯

若要在原始碼中設定斷點，請按一行程式代碼，然後按 F9：
在 [ 執行] 索引標籤上，從下拉功能表中選取啟動組態。
按兩下 [開始偵錯]，這是啟動組態下拉式清單旁的綠色三角形：
若要檢視偵錯輸出和錯誤，請開啟 [偵錯控制台]：

目標 WebView2 偵錯

在某些 WebView2 應用程式中，您可能會使用多個 WebView2 控制件。若要挑選在此情況下要偵錯的 WebView2 控件，您可以使用目標 WebView2 偵錯。

開 launch.json 啟並完成下列動作，以使用目標 WebView2 偵錯。

確認 useWebview 參數設定為 true。
urlFilter新增參數。當 WebView2 控制件巡覽至 URL 時， urlFilter 參數值會用來比較出現在 URL 中的字串。

"useWebview": "true",
"urlFilter": "*index.ts",

// Options for "urlFilter":
// Match any url that ends with "index.ts":
"urlFilter": "*index.ts",
// Match any url that contains "index" anywhere in the URL:
"urlFilter": "*index*",
// Explicitly match a file named "index.ts":
"urlFilter": "file://C:/path/to/my/index.ts",

在偵錯應用程式時，您可能需要從轉譯程式的開頭逐步執行程序代碼。如果您要在網站上轉譯網頁，而且無法存取原始程式碼，您可以使用 ?=value 選項，因為網頁會忽略無法辨識的參數。

無法同時對兩個 WebView2 控制件進行偵錯

在 URL 中找到第一個相符項目之後，調試程式就會停止。您無法同時對兩個 WebView2 控制件進行偵錯，因為 CDP 連接埠是由所有 WebView2 控制件共用，並使用單一埠號碼。

對執行中的進程進行偵錯

您可能需要將調試程式附加至執行中的 WebView2 進程。若要這樣做，請在 launch.json中更新 request 參數，將其值變更為 attach：

"name": "Hello debugging world",
"type": "msedge",
"port": 9222,
"request": "attach",
"runtimeExecutable": "C:/path/to/your/webview2/myApp.exe",
"env": {
   "Path": "%path%;e:/path/to/your/build/location; "
},
"useWebView": true

您的 WebView2 控制項必須開啟 Chrome 開發人員通訊協定 (CDP) 埠，才能對 WebView2 控制件進行偵錯。您必須先建置程式代碼，以確保只有一個 WebView2 控件開啟 CDP 埠，才能啟動調試程式。

您也需要在下Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments新增 REGKEY<myApp.exe> = --remote-debugging-port=9222，以便調試程式可以找到適當的埠。若要新增此登錄機碼：

按 下 Windows 標誌鍵 ，然後搜尋 登錄編輯器。開啟註冊 表編輯器 應用程式，然後按下 [ 是 ] 以允許編輯。
在左側的資料夾樹狀結構中，嘗試展開 HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments。
如果該 \Edge\WebView2\AdditionalBrowserArguments 路徑的部分不存在，請建立這三個巢狀子資料夾，如下所示：
1. 若要建立 \Edge 子資料夾：在資料夾樹狀結構中，以滑鼠右鍵按兩下 HKEY_CURRENT_USER\Software\Policies\Microsoft 資料夾，將滑鼠停留在 [ 新增] 上方，然後選取 [ 金鑰]。資料夾會新增為資料夾的 Microsoft 子系，一開始名為 New Key #1。以滑鼠右鍵按下 New Key #1 資料夾，然後選取 [ 重新命名]。輸入 Edge 作為新金鑰的名稱。
2. \WebView2建立子資料夾，如上一個步驟所示。
3. \AdditionalBrowserArguments建立子資料夾，如上一個步驟所示。
  
  樹狀結構現在已展開為 HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments。
以滑鼠右鍵按下檔 AdditionalBrowserArguments 夾，將滑鼠停留在 [ 新增] 上方，然後選取 [ 字串值]。在 [ 名稱] 資料 行中，以滑鼠右鍵按下 New Value #1，選取 [ 重新命名]，然後輸入應用程式可執行檔的檔名，例如 myApp.exe。
在 [ 名稱] 數據 行中，以滑鼠右鍵按下可執行檔名，例如 myApp.exe，然後選取 [ 修改]。 [ 編輯字串 ] 對話框隨即開啟。
在 [ 值資料] 文字框中，輸入 --remote-debugging-port=9222：
按下 [確定] 按鈕，然後確認登錄機碼符合下列 (與 [名稱] 資料行中檔案的檔名 .exe) ：

偵錯追蹤選項

若要啟用偵錯追蹤，請將參數新 trace 增至 launch.json ，如下所示：

trace新增參數：

"name": "Hello debugging world",
"type": "msedge",
"port": 9222,
"request": "attach",
"runtimeExecutable": "C:/path/to/your/webview2/app.exe",
"env": {
"Path": "%path%;e:/path/to/your/build/location; "
},
"useWebView": true
,"trace": true  // Turn on debug tracing, and save the output to a log file.

將偵錯輸出儲存至記錄檔：

將偵錯輸出儲存至記錄檔

,"trace": "verbose"  // Turn on verbose tracing in the Debug Output pane.

開啟詳細資訊追蹤的 Visual Studio Code 偵錯輸出：

開啟詳細資訊追蹤的 Visual Studio Code 偵錯輸出

偵錯 Office 增益集

如果您要偵錯 Office 載入宏，請在 Visual Studio Code 的個別實例中開啟載入宏原始程式碼。在您的 WebView2 應用程式中開 launch.json 啟。將下列程式代碼新增至 launch.json，以將除錯程式附加至 Office 載入巨集：

,"debugServer": 4711

偵錯 WebView2 WinUI 2 (UWP) 應用程式

安裝過去的 106.0.1370.34WebView2 運行時版本。
按 下 Windows 標誌鍵 ，然後搜尋登錄編輯器，以開啟 註冊表編輯器。開啟註冊 表編輯器 應用程式，然後選取 [ 是 ] 以允許編輯。
將登入機碼 HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments 設定為等於 --remote-debugging-pipe。若要這樣做，請遵循上述偵錯執行中進程一節中所述的步驟。
確認登錄機碼已在編輯器中設定，且符合下列專案：

將新的組態新增至您的 launch.json 檔案。開 launch.json 啟並新增下列程序代碼：

"name": "Attach to UWP App",
"useWebView":{
   "pipeName":"JSDebugPipe"
}
"request": "attach",
"type": "msedge",
"webRoot":"${workspaceFolder}"

啟動您的應用程式。
按兩下 [ 開始偵錯 ] 按鈕以附加至進程並開始偵錯。

針對調試程序進行疑難解答

使用調試程式時，您可能會遇到這些案例。

不會在斷點停止

如果調試程式未在斷點停止，而且您有偵錯輸出：

若要解決此問題，請確認具有斷點的檔案與 WebView2 控件所使用的檔案相同。調試程式不會執行來源路徑對應。

無法附加至執行中的進程

如果您無法附加至執行中的行程，則會收到逾時錯誤：

若要解決此問題，請確認 WebView2 控件已開啟 CDP 埠。請確定您 additionalBrowserArguments 在登錄中的值正確無誤，或選項正確無誤。請參閱 dotnet 的 additionalBrowserArguments 和 Win32 的 additionalBrowserArguments。

共用方式為