Debug Office Add-ins on a Mac

Because add-ins are developed using HTML and JavaScript, they are designed to work across platforms, but there might be subtle differences in how different browsers render the HTML. This article describes how to debug add-ins running on a Mac.

Important

Debugging add-ins with Office on Mac is only possible if Office is installed on the Mac from Office.com, not the Apple App Store.

Debugging with Safari Web Inspector on a Mac

If you have add-in that shows UI in a task pane or in a content add-in, you can debug an Office Add-in using Safari Web Inspector.

To be able to debug Office Add-ins on Mac, you must have Mac OS High Sierra AND Mac Office Version 16.9.1 (Build 18012504) or later. If you don't have an Office on Mac build, you might qualify for a Microsoft 365 E5 developer subscription through the Microsoft 365 Developer Program; for details, see the FAQ. Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.

To start, open a terminal and set the OfficeWebAddinDeveloperExtras property for the relevant Office application as follows:

• defaults write com.microsoft.Word OfficeWebAddinDeveloperExtras -bool true

• defaults write com.microsoft.Excel OfficeWebAddinDeveloperExtras -bool true

• defaults write com.microsoft.Powerpoint OfficeWebAddinDeveloperExtras -bool true

• defaults write com.microsoft.Outlook OfficeWebAddinDeveloperExtras -bool true

  Important

  Mac App Store builds of Office don't support the OfficeWebAddinDeveloperExtras flag.

Then, open the Office application and sideload your add-in. Right-click (or select and hold) the add-in and you should see an Inspect Element option in the context menu. Select that option and it will pop the Inspector, where you can set breakpoints and debug your add-in.

Note

• If you're debugging an event-based or spam-reporting add-in in Outlook on Mac, follow the steps in Debug your event-based or spam-reporting Outlook add-in after configuring the OfficeWebAddinDeveloperExtras property.

• If you're trying to use the inspector and the dialog flickers, update Office to the latest version. If that doesn't resolve the flickering, try the following workaround.

  1. Reduce the size of the dialog.
  2. Choose Inspect Element, which opens in a new window.
  3. Resize the dialog to its original size.
  4. Use the inspector as required.

Clearing the Office application's cache on a Mac

Add-ins are often cached in Office on Mac for performance reasons. Normally, the cache is cleared by reloading the add-in. If more than one add-in exists in the same document, the process of automatically clearing the cache on reload might not be reliable.

Use the personality menu to clear the cache

You can clear the cache by using the personality menu of any task pane add-in. However, because the personality menu isn't supported in Outlook add-ins, you can try the option to clear the cache manually if you're using Outlook.

• Choose the personality menu. Then choose Clear Web Cache.

  Note

  You must run macOS Version 10.13.6 or later to see the personality menu.

  

Clear the cache manually

You can also clear the cache manually by deleting the contents of the ~/Library/Containers/com.Microsoft.OsfWebHost/Data/ and ~/Library/Containers/com.microsoft.{host}/Data/Documents/wef folders. Replace {host} with the Office application, such as Excel. Look for these folders via terminal.

Deleting the contents of the ~/Library/Containers/com.microsoft.{host}/Data/Documents/wef folder removes a sideloaded add-in from the add-ins menu in an application.

Note

If the ~/Library/Containers/com.Microsoft.OsfWebHost/Data/ folder doesn't exist, check for the following folders via terminal and if found, delete the contents of the folder.

• ~/Library/Containers/com.microsoft.{host}/Data/Library/Caches/ where {host} is the Office application (e.g., Excel)
• ~/Library/Containers/com.microsoft.{host}/Data/Library/Application Support/Microsoft/Office/16.0/Wef/ where {host} is the Office application (e.g., Excel)
• ~/Library/Containers/com.microsoft.Office365ServiceV2/Data/Caches/com.microsoft.Office365ServiceV2/
• ~/Library/Containers/com.microsoft.Office365ServiceV2/Data/Library/Caches/com.microsoft.Office365ServiceV2/

Tip

To look for these folders via Finder, you must set Finder to show hidden files. Finder displays the folders inside the Containers directory by product name, such as Microsoft Excel instead of com.microsoft.Excel.