使用 Visual Studio Code 偵錯 WebView2 應用程式

使用 Microsoft Visual Studio Code 偵錯在 WebView2 控制項中執行的指令碼。

詳細內容：

• 簡介
• 建立launch.json檔案
  • 使用登錄值
  • 傳遞的命令列 URL 參數
• 偵錯您的程式碼
• 目標 WebView2 偵錯
  • 無法同時偵錯兩個 WebView2 控制項
• 偵錯執行中的程序
  • 使用環境變數
• 偵錯追蹤選項
• 偵錯 Office 增益集
• 偵錯 WebView2 WinUI 2 (UWP) 應用程式
• 來源具有 WebResourceRequested 事件或虛擬主機名稱對應的來源對應
• 疑難排解偵錯工具
  • 不會止於斷點
  • 無法附加至執行中的程序
• 另請參閱

簡介

使用 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": {
   // The following variable is needed when the "runtimeExecutable" property is set.
   // The port number below must match the value of the "port" property above.
   "WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS": "--remote-debugging-port=9222"
   // Customize for your app location.
   "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 containing all your code files.
"url": "file:///${workspaceFolder}/path/to/your/toplevel/foo.html",
"webRoot": "${workspaceFolder}/path/to/your/assets"

使用登錄值

您可以將以資料--remote-debugging-port=9222命名<myApp.exe>的新登錄值新增至登錄機碼Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments下的新登錄值，讓偵錯工具可以找到正確的連接埠，而不是設定WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS環境變數。 如需詳細資訊，請參閱 WebView2 瀏覽器旗標。

傳遞的命令列 URL 參數

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

偵錯您的程式碼

1. 若要在原始程式碼中設定中斷點，請按一下程式碼行，然後按 F9：

   

2. 在 [執行] 索引標籤上，從下拉式功能表中選取啟動設定。

3. 按一下 Start Debugging，這是啟動設定下拉式清單旁的綠色三角形：

   

4. 若要檢視偵錯輸出和錯誤，請開啟偵 錯主控台：

   

目標 WebView2 偵錯

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

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

1. 確認 useWebview 參數已設定為 true。

2. 新增 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; "
}

您的 WebView2 控制項必須開啟 Chrome 開發人員通訊協定 (CDP) 連接埠，才能偵錯 WebView2 控制項。 在啟動偵錯工具之前，必須先建置您的程式碼，以確保只有一個 WebView2 控制項具有開啟的 CDP 埠。

您也需要在 下Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments新增 REGKEY<myApp.exe> = --remote-debugging-port=9222，讓偵錯工具可以找到正確的連接埠。 若要新增此登錄機碼：

1. 按 Windows 鍵 ，然後搜尋登錄 編輯程式。 開啟 [登錄編輯程式 ] 應用程式，然後按一下 [ 是 ] 以允許編輯。

2. 在左側的資料夾樹狀目錄中，嘗試展開 HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments。

3. 如果該路徑的一部分不存在，請 \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。

4. 以滑鼠右鍵按一下 AdditionalBrowserArguments 資料夾，將滑鼠游標停留在 [新增] 上，然後選取 [字串值]。 在 [名稱 ] 欄中，以滑鼠右鍵按一下 New Value #1，選取 [重新命名]，然後輸入應用程式可執行檔的檔名，例如 myApp.exe。

5. 在 [名稱 ] 欄位中，以滑鼠右鍵按一下可執行檔的名稱，例如 myApp.exe，然後選取 [ 修改]。 [ 編輯字串 ] 對話方塊隨即開啟。

6. 在 [值資料 ] 文字方塊中，輸入 --remote-debugging-port=9222：

   

7. 按一下 [確定] 按鈕，然後確認登錄機碼與 [名稱] 欄) 中的檔案名稱.exe符合下列 (：

   

使用環境變數

您可以將環境變數設定為 --remote-debugging-port=9222，而不是新增上述登錄機碼。WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS 請確定您的應用程式是在設定環境變數之後啟動，並確定您的應用程式繼承環境變數。 如需詳細資訊，請參閱 WebView2 瀏覽器旗標。

偵錯追蹤選項

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

1. 新增 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 輸出，已開啟詳細追蹤：

偵錯 Office 增益集

如果您要偵錯 Office 增益集，請在 Visual Studio Code 的個別執行個體中開啟增益集原始程式碼。 在 WebView2 應用程式中開啟 launch.json 。 將下列程式碼新增到 launch.json，以將偵錯工具附加至 Office 增益集：

,"debugServer": 4711

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

1. 安裝過去 106.0.1370.34的 WebView2 執行階段版本。

2. 按 Windows 鍵 開啟登錄編輯程式，然後搜尋登錄 編輯程式。 開啟 [登錄編輯程式 ] 應用程式，然後選取 [ 是 ] 以允許編輯。

3. 將登錄機碼HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments--remote-debugging-pipe設定為 。 若要這樣做，請遵循上述偵 錯執行中的程序 一節中所述的步驟。

4. 確認登錄機碼已在編輯器中設定，且符合下列內容：

   

5. 將新的設定 launch.json 新增至您的檔案。 開啟 launch.json 並新增下列程式碼：

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

6. 啟動您的應用程式。

7. 按一下 [開始偵錯 ] 按鈕以附加至處理程序並開始偵錯。

   

具有事件或虛擬主機名稱對應的 WebResourceRequested 來源對應

需要源映射來調試編譯內容的源代碼，包括：

• 轉譯的 JavaScript，例如 TypeScript 或縮小的 JavaScript。
• 編譯的 CSS，例如 SASS 或 SCSS。

WebView2 不會載入使用任一方法載入之內容所參考的來源對應：

• 事件。WebResourceRequested 請參閱：

  • 透過在 WebView2 應用程式中使用本機內容中處理事件來載入本機內容。WebResourceRequested
  • 來源對應事件為 WebResourceRequested 在 WebView2 應用程式中使用本機內容。

• 虛擬主機名稱對應。 請參閱：

  • 使用在 WebView2 應用程式中使用本機內容中的虛擬主機名稱對應載入本機內容。
  • 在 WebView2 應用程式中使用本機內容中具有虛擬主機名稱對應的來源對應。

疑難排解偵錯工具

使用偵錯工具時，您可能會遇到這些案例。

不會止於斷點

如果偵錯工具未在中斷點停止，而且您有偵錯輸出：

若要解決此問題，請確認具有中斷點的檔案是 WebView2 控制項所使用的相同檔案。 偵錯工具不會執行來源路徑對應。

無法附加至執行中的程序

如果無法附加至執行中的程序，而且收到逾時錯誤：

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

另請參閱

• 開始使用 WebView2
• WebView2Samples 存放庫 - WebView2 功能的完整範例。
• WebView2 API 參考