Overview of debugging Office Add-ins

Debugging Office Add-ins is essentially the same as debugging any web application. However, a single set of tools won't work for all add-in developers. This is because add-ins can be developed on different operating systems and run cross-platform. This article helps you find the detailed debugging guidance for your development environment.

Tip

This article is concerned with debugging in the narrow sense of setting breakpoints and stepping through code. For guidance on testing and troubleshooting, start with Test Office Add-ins and Troubleshoot development errors with Office Add-ins.

Note

Although you should test your add-in on all the platforms that you want to support, you'll only very rarely need to debug on an environment different from your development computer. For this reason, this article uses "your development computer" and "your development environment" to refer to the environment on which you're debugging. If a problem in the code occurs only on a platform other than the one on your development computer, and you need to set breakpoints or step through code to solve it, then the environment on which you're debugging isn't literally your development environment.

Server-side or client-side?

Debugging the server-side code of an Office Add-in is the same as debugging the server-side of any web application. See the debugging instructions for your IDE or other tools. The following are examples for some of the most popular tools.

• Debug ASP.NET or ASP.NET Core apps in Visual Studio
• Debugging Express
• Node.js Debugging Guide
• Node.js debugging in VS Code
• Webpack Debugging

The rest of this article is concerned only with debugging client-side JavaScript (which may be transpiled from TypeScript).

Special cases

There are some special cases in which the debugging process differs from normal for a given combination of platform, Office application, and development environment. If you're debugging any of these special cases, use the links in this section to find the proper guidance. Otherwise, continue to General guidance.

• Debugging the Office.initialize or Office.onReady function: Debug the initialize and onReady functions.
• Debugging an Excel custom function in a non-shared runtime: Custom functions debugging in a non-shared runtime.
• Debugging a function command in a non-shared runtime:
  • Outlook add-ins on a Windows development computer: Debug function commands in Outlook add-ins
  • Other Office application add-ins or Outlook on a Mac development computer: Debug a function command with a non-shared runtime.
• Debugging an event-based or spam-reporting Outlook add-in: Debug event-based and spam-reporting add-ins.
• Debugging an add-in in the new Outlook on Windows desktop client (preview): See the "Debug your add-in" section of Develop Outlook add-ins for the new Outlook on Windows.
• Debugging a Blazor-based add-in: Debug the add-in the same way you would debug a Blazor web application. See Debug ASP.NET Core Blazor WebAssembly.

General guidance

To find guidance for debugging client-side code, the first variable is the operating system of your development computer.

• Windows
• Mac
• Linux or other Unix variant

Debug on Windows

The following provides general guidance to debugging on Windows. Debugging on Windows depends on your IDE.

• Visual Studio: Debug using the browser's F12 tools. See Debug Office Add-ins in Visual Studio.

• Any other IDE (or you don't want to debug inside your IDE): Use the developer tools that are associated with the webview control that add-ins use on your development computer. See one of the following:

  • For the Trident webview: Debug add-ins using developer tools for Internet Explorer
  • For the EdgeHTML webview: Debug add-ins using developer tools for Edge Legacy
  • For the WebView2 webview: Debug add-ins using developer tools in Microsoft Edge (Chromium-based)

For information about which runtime is being used, see Browsers and webview controls used by Office Add-ins and Runtimes in 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.

Debug on Mac

Use the Safari Web Inspector. Instructions are in Debug Office Add-ins on a Mac.

Debug on Linux

There is no desktop version of Office for Linux, so you'll need to sideload the add-in to Office on the web to test and debug it. Debugging guidance is in Debug add-ins in Office on the web.

Note

We don't recommend that you develop Office Add-ins on a Linux computer except in the unusual case where you can be sure that all the add-in's users will be accessing the add-in through Office on the web from a Linux computer.

Debug add-ins in staging or production

To debug an add-in that is already in staging or production, attach a debugger from the UI of the add-in. For instructions, see Attach a debugger from the task pane.

Versions of office.js for debugging

There are debug versions of the Office JavaScript libraries. These versions are more human readable and easier to step through with a debugger. Use them when the Office JavaScript APIs aren't working as expected. Avoid using them when you publish and deploy your add-in.

The debug versions are found at the following CDN locations.

• Office JavaScript API library: https://appsforoffice.microsoft.com/lib/1/hosted/office.debug.js
• Office JavaScript API (preview) library: https://appsforoffice.microsoft.com/lib/beta/hosted/office.debug.js

See also

• Runtimes in Office Add-ins