New Debug Options for SPFx (Edge)

2020-02-14

VS Code

As the development pendulum has swung back to the “front end,” I find a majority of my time in VS Code. Back in the early days of VS Code, I missed the rich toolset of Visual Studio, but as I became more comfortable with the combination of command line and graphical interfaces in VS Code, as well as the explosion of awesome extensions for VS Code, I found myself opening Visual Studio less and less. (Honestly, when I open Visual Studio these days, it’s because the icon is next to VS Code in my taskbar and I accidentally click the wrong one. As long as it’s open, I apply the latest updates and close it back down.)

BLAH BLAH BLAH! Just take me to the code!

I have a long list of extensions that I regularly use in VS Code, but I use a few extensions daily that help with debugging SharePoint Framework(SPFx) webparts and extensions. The two that have been around for a while are

SPFx Debug Configuration by Elio Struyf
Debugger for Chrome by Microsoft

The Original Debugging Extensions

While Elio’s extension allows you to add SPFx debugging profiles to any project, I rarely use it these days as Microsoft included the debugging profiles as part of the Yeoman scaffolding for SPFx. He has updated it to include debugging profiles for other SPFX scenarios, so it’s still worth installing.

That said, the Debugger for Chrome is one of the first extensions I add to any new VS Code install. I have used Chrome as my primary browser for years, in large part because of the debugging tools built into the browser. Over the last year, I have slowly shifted my primary browser to the new Chromium version of Edge (I like the nickname “Edgium,” but it looks like “Chredge” has become the more popular nickname.) So I recently decided to see if it was possible to use Edge as my debugging browser for SPFx debugging. It turns out, you can!

Enter Debugging for Edge (Chredge)

The Debugger for Edge extension by Microsoft has actually been around for a while, but it has been updated to support Chredge. There may be a more complete implentation is you dig through the documentation, but I found that, with a few tweaks to the Chrome profiles, you can launch Chredge and attach the debugger to VS Code. This gives the same experience, letting you easily set breakpoints and watches, inspect variables and all of your other important debugging tasks. While you can create profiles that use Chredge, it’s a manual process for now. I expect Microsoft will build the profiles into the Yeoman template soon.

After installing “Debugger for Microsoft Edge”, you can update the profiles in the ".vscode\launch.json" file of you project. This file can be accedd via the Alt+D+C key combination. You can convert the existing profiles to Chredge, but I usually just copy the existing profiles and modify them to create new profiles. If you use the copy approach, make sure you change the name for each profile to be unique so you can tell which on you are selecting in the debugging tab.

Setting up the profiles

Local workbench

Change the type to “edge”: "type": "edge",
Add a version to use the chromium version of Edge: "version": "canary",
Change the remote debugging port: "--remote-debugging-port=2015"

Hosted workbench

Change the type to “edge”: "type": "edge",
Add a version to use the chromium version of Edge: "version": "canary",
Change the remote debugging port: "--remote-debugging-port=2015"
Optional: remove the "-incognito" flag. This will allow you to used stored credentials to login to the hosted workbench

How to use the workbenches

Before launching the debugger to either workbench, you need to run “gulp serve –nobrowser” to load your code into the localhost website. NOTE: Running “gulp serve” with no options will open the Local Workbench in your default browser, but does not launch the debugger.

Local workbench:

This is the workbench that runs in the localhost website created by the "gulp serve" command. To be honest, I don’t spend a lot of time here. Since you can’t access data from the local workbench, this is only useful for UI design and setting up your webpart properties. If you want to design how data is displayed, you will need to build mock data to populate your webpart. My development pattern is usually to build the data services first (using the hosted workbench) and design the UI later.

To launch the debugger with the local workbench, go to the Debug tab (Ctrl+Shift+D), select Local Workbench from the dropdown, and launch the debugger by pressing F5. Make sure to run "gulp serve --nobrowser" before you launch the debugger or you will get a friendly reminder from the workbench.

Hosted workbench:

This is a workbench that is part of the system pages in SharePoint, hench the “/_layouts” part of the url. This workbench is “hosted” in SharePoint, but is configured to connect to your localhost for your code. Because it’s a system page, you can append the “/layouts/workbench.aspx” url to any site in SharePoint to see how your webpart performs there. This is where I spend most of my time debugging because the hosted workbench allows you to use the page context to authenticate to the SharePoint and Graph APIs. This is what gives you the ability to interact with data. (Full disclosure: there are other ways to authenticate to APIs, but this is the most popular pattern for Office 365 data interaction.) And you can build the UI experience here also (with live data), so I find it’s just a better experience.

To use the hosted workbench, make sure you run "gulp serve --nobrowser" to load your code into the localhost website. On the Debug tab (Ctrl+Shift+D), select the Hosted Workbench (or whatever you named it) from the dropdown. You can start the hosted workbench by pressing F5, which will launch Edge to the url in the debugging profile. HINT: If you are using profiles in Edge, the debugger will launch a new tab on the last browser session you were active in, so if you have a profile linked to the tenant in your hosted workbench, open that profile in Edge before launching the hosted workbench and you will be logged right in. (This is why I delete the "-incognito" flag in the default profile!)

Pro Tip #1

I normally just copy the existing Chrome profiles to create my Edge profiles. While Edge has been pretty stable, I like having the option to switch back to Chrome as needed. Also, it makes it easy to test your design to ensure there are no bugs when using the Chrome browser.

Pro Tip #2

Most of the SPFx projects I build start in my dev tenant, but eventually I need to run it in a client’s tenant. I create debugging profiles for each tenant that I want to test the webpart by doing the following: 1. Copy the Hosted Workbench profile and paste it under the previous profile (Don’t forget to fix the commas!) 2. Change the “name” property of each profile to reflect the environment. e.g., “Hosted Workbench(Dev)”, “Hosted Workbench()” 3. Change the “url” property to the targeted tenant and site where the workbench will be hosted.

On to the code

Below is the contents of a basic ".vscode/launch.json" file configured to use Edge/Chredge for debugging. You can get to it via the menus in VS Code, “Debug, Open Confgurations” or the Alt+D+C key combination.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


{
  /**
   * Install Edge Debugger Extension for Visual Studio Code to debug 
   * your components with the Edge browser: Debugger for Edge Extension
   */
  "version": "0.2.0",
  "configurations": [{
      "name": "Local workbench",
      "type": "edge",
      "version": "canary",
      "request": "launch",
      "url": "https://localhost:4321/temp/workbench.html",
      "webRoot": "${workspaceRoot}",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack:///.././src/*": "${webRoot}/src/*",
        "webpack:///../../../src/*": "${webRoot}/src/*",
        "webpack:///../../../../src/*": "${webRoot}/src/*",
        "webpack:///../../../../../src/*": "${webRoot}/src/*"
      },
      "runtimeArgs": [
        "--remote-debugging-port=2015"
      ]
    },
    {
      "name": "Hosted workbench",
      "type": "edge",
      "version": "canary",
      "request": "launch",
      "url": "https://<tenant>.sharepoint.com/_layouts/workbench.aspx",
      "webRoot": "${workspaceRoot}",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack:///.././src/*": "${webRoot}/src/*",
        "webpack:///../../../src/*": "${webRoot}/src/*",
        "webpack:///../../../../src/*": "${webRoot}/src/*",
        "webpack:///../../../../../src/*": "${webRoot}/src/*"
      },
      "runtimeArgs": [
        "--remote-debugging-port=2015"
      ]
    }
  ]
}

SUMMARY

Debugging code has always been and will always be a critical part of the development lifecycle. With the addition of the new Edge (Chromium) browser, developers have even more options to choose from when building and debugging code. If you have other tips & tricks, please share so we can all learn and grow.