Edit

Share via

Debug the initialize and onReady functions

Note

This article assumes that you're familiar with Initialize your Office Add-in.

The paradox of debugging the Office.initialize and Office.onReady functions is that a debugger can only attach to a process that's running, but these functions run immediately as the add-in's runtime process starts up, before a debugger can attach. In most situations, restarting the add-in after a debugger is attached doesn't help because restarting the add-in closes the original runtime process and the attached debugger and starts a new process that has no debugger attached.

Fortunately, there are two ways that you can debug these functions that are described in the following sections.

Debug using Office on the web

To debug with Office on the web, use the following steps.

  1. Sideload and run the add-in in Office on the web. This is usually done by opening an add-in's task pane or running a function command. The add-in runs in the overall browser process, not a separate process as it would in desktop Office.
  2. Open the browser's developer tools. This is usually done by pressing F12. The debugger in the tools attaches to the browser process.
  3. Apply breakpoints as needed to the code in the Office.initialize or Office.onReady function.
  4. Relaunch the add-in's task pane or the function command just as you did in step 1. This action does not close the browser process or the debugger. The Office.initialize or Office.onReady function runs again and processing stops on your breakpoints.

Tip

For more detailed information, see Debug add-ins in Office on the web.

Debug using Office on Windows

Note

The technique described in this section works only when the add-in using the WebView2 webview control. To determine which webview you're using, see Browsers and webview controls used by Office Add-ins.

Tip

In recent versions of Office, one way to identify the webview control that Office is using is through the personality menu on any add-in where it's available. (The personality menu isn't supported in Outlook.) Open the menu and select Security Info. In the Security Info dialog on Windows, the Runtime reports Microsoft Edge, Microsoft Edge Legacy, or Internet Explorer. The runtime isn't included on the dialog in older versions of Office.

To debug your add-in’s initialization sequence, configure your environment so that Microsoft WebView2 (Chromium-based) developer tools automatically open when the add-in launches.

  1. Close the Office application where you plan to debug the add-in.
  2. Set the WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS environment variable to include the value --auto-open-devtools-for-tabs.
  3. Open the Office application.
  4. Run the add-in.
  5. The Microsoft Edge (Chromium-based) developer tools should automatically open. Use the tool the same as you would when debugging a task pane, as specified in Debug a task pane add-in using Microsoft Edge (Chromium-based) developer tools.

Note

You may see other instances of the Microsoft Edge (Chromium-based) developer tool auto-opening since this environment variable will affect all WebView2 instances in your system.

See also