Clarify & update "Debug WebView2 apps with Visual Studio"

microsoft-edge/webview2/how-to/debug-visual-studio.md

@@ -6,98 +6,181 @@ ms.author: msedgedevrel
 ms.topic: conceptual
 ms.service: microsoft-edge
 ms.subservice: webview
-ms.date: 02/11/2022
+ms.date: 09/17/2024
 ---
 # Debug WebView2 apps with Visual Studio
 
 Microsoft Visual Studio provides various debugging tools for web and native code in WebView2 apps, to debug web and native code in Win32 apps or Office Add-ins.  This article focuses on debugging WebView2 controls.  The other methods of debugging in Visual Studio are available, as well.
 
 
-<!-- ====================================================================== -->
-## Open DevTools using an approach other than F12
+<!-- ------------------------------ -->
+#### Summary of high-level steps
+
+To debug JavaScript code in a WebView2 control: 
+
+1. Install the **JavaScript diagnostics** component in the **Desktop development with C++** workload of Visual Studio, or in another platform's workload.
+
+1. Set a breakpoint on a line of JavaScript code.
+
+1. In the project's **Properties** > **Debugging** page, set **Debugger Type** to **JavaScript (WebView2)** (instead of **Auto** or **Native**).
 
-When you debug your app in Visual Studio with the native debugger attached, pressing **F12** may trigger the native debugger instead of Developer Tools.  To avoid that situation, press **Ctrl+Shift+I**.  Or, right-click the page, and then select `Inspect`.
+1. Start the debugger, as usual.  For example, in the menu bar, select **Debug** > **Start Debugging (F5)**.
+
+1. In the running WebView2 app, interact with a webpage that runs the JavaScript code.  The debugger pauses on the line of JavaScript code that has the breakpoint.
+
+1. Use the debugger panes in Visual Studio.
+
+These steps are detailed below, using the main, Win32/C++ sample (WebView2APISample).
 
 
 <!-- ====================================================================== -->
 ## Requirements
 
-*  To debug scripts, the app must be launched from within Visual Studio.
+* Clone the WebView2Samples repo, if you want to follow the specific example steps below (using the main, Win32/C++ sample, WebView2APISample).  A step below shows how to do this.
 
-*  You cannot attach a debugger to a running WebView2 process.
+* Install Visual Studio 2022.  You can use Visual Studio 2022 to work with the WebView2 sample apps and your own WebView2 app.  (Visual Studio 2019 works, as well.)  A step below shows how to do this.
 
-*  Install Visual Studio 2019 version 16.4 Preview 2 or later.
+* Install and set up the script debugger tools in Visual Studio.  That is, install the **Desktop development with C++** workload of Visual Studio (or the equivalent workload for a different language), including its **JavaScript diagnostics** component.  A step below shows how to do this.
 
+* Build and run the main, Win32/C++ sample, so that the WebView2APISample app builds and runs (if you want to follow the specific example steps below).  A step below shows how to do this.
 
-To debug your code, first install and set up the script debugger tools in Visual Studio, per the following two sections.
+* To debug scripts, the app must be launched from within Visual Studio.
+
+* You cannot attach a debugger to a running WebView2 process.
 
 
 <!-- ====================================================================== -->
 ## Install the JavaScript diagnostics component
 
-First, install the **JavaScript diagnostics** component in **Desktop development with C++**, as follows.
+Use the **Visual Studio Installer** to install the **Desktop development with C++** workload of Visual Studio, including its **JavaScript diagnostics** component, as follows.  Or, if you are using a language workload other than C++, select that workload's **JavaScript diagnostics** component, similar to the below steps.
+
+1. If not done already, clone the WebView2Samples repo, as described in [Clone the WebView2Samples repo](./machine-setup.md#clone-the-webview2samples-repo) in _Set up your Dev environment for WebView2_.
+
+1. If not done already, install Visual Studio 2022, as described in [Install Visual Studio](./machine-setup.md#install-visual-studio) in _Set up your Dev environment for WebView2_.
+
+1. In Visual Studio 2022, install the **Desktop development with C++** workload, as follows:
 
 1. In the Windows Explorer bar, type `Visual Studio Installer`.
 
 1. Select **Visual Studio Installer** to open it.
 
 1. In the Visual Studio Installer, on the installed version, click the **More** button, and then select **Modify**.
 
-1. In Visual Studio, under **Workloads**, select the **Desktop Development with C++** setting:
+1. In Visual Studio, under **Workloads**, select the **Desktop Development with C++** workload, so that a checkmark appears:
 
    ![Visual Studio Modifying Workloads Screen](./debug-visual-studio-images/workloads.png)
 
 1. Select **Individual components**, at the top.
 
 1. In the search box, enter `JavaScript diagnostics`.
 
-1. Select the **JavaScript diagnostics** setting.
-
-1. Click **Modify**.
+1. Select the **JavaScript diagnostics** checkbox:
 
    ![Visual Studio: Modifying values in the 'Individual components' tab](./debug-visual-studio-images/indiv-comp.png)
 
+1. Click the **Modify** button.
+
+Continue with the next section, below.
+
 
 <!-- ====================================================================== -->
-## Enable script debugging for WebView2 apps
+## Select the JavaScript (WebView2) debugger
 
-Second, enable script debugging for WebView2 apps, as follows.
+Next, enable script debugging for WebView2 apps, as follows.
 
-1. Right-click your WebView2 project, and then select **Properties**.
+1. If not done already, do the steps in [Win32 sample app](../samples/webview2apissample.md) so that the WebView2APISample app builds and runs.  The **WebView2Samples** solution should be open in Visual Studio, and the sample app should not be running.  Or, open your own WebView2 app project in Visual Studio.
 
-1. Under the **Configuration Properties**, select **Debugging**.
+1. In Visual Studio, in Solution Explorer, right-click the **WebView2APISample** project (or your own project), and then select **Properties**.
 
-1. Under the **Debugger Type**, select **JavaScript (WebView2)**.
+   The **Property Pages** dialog opens.
 
-   ![The 'Debugging' configuration property in Visual Studio](./debug-visual-studio-images/enb-js.png)
+1. On the left, expand **Configuration Properties**, and then select **Debugging**.
+
+1. To the right of **Debugger Type**, select **JavaScript (WebView2)**, and then click the **OK** button:
+
+   ![The "Debugging" > "Local Windows debugger" > "Debugger type" property in Visual Studio](./debug-visual-studio-images/enb-js.png)<!-- WebView2APISample -->
 
 
 <!-- ====================================================================== -->
 ## Debug your WebView2 app
 
 After doing the above setup, debug your WebView2 app, as follows.
 
-1. To set a breakpoint in your source code, hover to the left of the line number, and click to set a breakpoint.  The JS/TS debug adapter doesn't perform source path mapping.  You must open the exact same path associated with your WebView2.
+1. To set a breakpoint in your source code, hover to the left of the line number, and click to set a breakpoint.  For example, open `WebView2Samples\SampleApps\WebView2APISample\assets\ScenarioJavaScriptDebugIndex.js`, and set a breakpoint on line 2: `console.log("onAddClick+");`, in the body of the `onAddClick` function:
+
+   ![Running the Local Windows Debugger in Visual Studio](./debug-visual-studio-images/run-local-windows-debugger.png)
+
+   When setting a breakpoint, you must open the file that's in the exact same path that's associated with your WebView2 control, because the JS/TS debug adapter doesn't perform source path mapping.  
 
-   ![Adding a breakpoint in Visual Studio](./debug-visual-studio-images/breakpoint.png)
+   The breakpoint will be triggered when this section of the code is executed.  This breakpoint is triggered upon clicking the **Add a new item** button in the sample app, in a later step below.
 
-1. To run the debugger, select the bit size of the platform, and then click the green Play button next to **Local Windows Debugger**.  The app runs and the debugger connects to the first WebView2 process that is created.
+1. Select the bit size of the platform, such as **x64**.
 
-   ![The Local Windows Debugger in Visual Studio](./debug-visual-studio-images/run.png)
+1. To run the debugger, do any of the following: 
 
-1. In the **Debug Console**, find the output from the debugger.
+   * In the menu bar, select **Debug** > **Start Debugging (F5)**.
+   * In Solution Explorer, right-click the project > **Debug** > **Start New Instance** or **Step Into New Instance**.
+   * Click the green Play button to the left of **Local Windows Debugger**.
+
+   The WebView2APISample app (or your own app) runs and opens, and the debugger connects to the first WebView2 process that's created.  In **Properties** > **Debugging** for the project, **Local Windows Debugger** was set to **JavaScript (WebView2)**.
 
-   ![Debug Console in Visual Studio](./debug-visual-studio-images/console.png)
+1. In Visual Studio, click the **Output** tab, in the lower right.
+
+   The tab contains only the following message, which mentions the JS debugger: "Verbose logs are written to: C:\Users\myUsername\AppData\Local\Temp\visualstudio-js-debugger.txt".
+
+1. In the WebView2APISample app window, select **Scenario** > **Script Debugging** > **JavaScript Local File**.
+
+   The file `WebView2APISample/Debug/x64/assets/ScenarioJavaScriptDebugIndex.html` is rendered:
+
+   ![Rendered HTML file "WebView Script Debugging Example"](./debug-visual-studio-images/webview-script-debugging-example.png)
+
+1. In Visual Studio, examine the **Output** pane.  The following output has been added:
+
+   ```
+   This is the very first line of code that executes.
+   Second
+   Third
+   inside
+   onAddClick+
+   onAddClick-
+   onAddClick+
+   onAddClick-
+   End
+   ```
+
+1. In the webpage in the app, click the **Add a new item** popup button.
+
+   The breakpoint in the `onAddClick` function is hit, and the app is paused in the debugger.
+
+1. Switch to the Visual Studio window, and examine the debugger panes.
+
+1. Click the **Output** tab, to display the app's output:
+
+   ![Output tab in Visual Studio 2022 showing output from debugger](./debug-visual-studio-images/output-tab-vs2022.png)
+
+   The app output shows "This is the very first line of code that executes", because of the line `console.log("This is the very first line of code that executes.");` in the file `WebView2Samples\SampleApps\WebView2APISample\assets\ScenarioJavaScriptDebugIndex.html`.
 
 
 <!-- ====================================================================== -->
 ## Troubleshooting
 
-### Virtual source path mapping not supported in Visual Studio 2019
+
+<!-- ------------------------------ -->
+#### Open DevTools using an approach other than F12
+
+When you debug your app in Visual Studio with the native debugger attached, when viewing your running app, pressing **F12** might start the native debugger instead of starting Developer Tools.
+
+To open DevTools, press **Ctrl+Shift+I**.  Or, right-click the page in the running app, and then select `Inspect`.
+
+
+<!-- ---------------------------------------------------------------------- -->
+#### Virtual source path mapping not supported in Visual Studio 2019
 
 If you use the WebView2 [SetVirtualHostNameToFolderMapping](/dotnet/api/microsoft.web.webview2.core.corewebview2.setvirtualhostnametofoldermapping) method, the debugger in Visual Studio 2019 doesn't understand the virtual source path mapping, so breakpoints don't work correctly.
 
-Virtual source path mapping works when you use the debugger in <!-- Visual Studio 2022 or? -->Visual Studio Code.
+When setting a breakpoint, you must open the file that's in the exact same path that's associated with your WebView2 control, because the JS/TS debug adapter doesn't perform source path mapping.  
+
+Virtual source path mapping is supported by the debugger in Visual Studio Code.
 
 
 <!-- ====================================================================== -->