Alternative ways of passing messages to a dialog box from its host page

The recommended way to pass data and messages from a parent page to a child dialog is with the messageChild method as described in Use the Office dialog API in your Office Add-ins. If your add-in is running on a platform or host that doesn't support the DialogApi 1.2 requirement set, there are two other ways that you can pass information to the dialog.

• Store the information somewhere accessible to both the host window and dialog. The two windows don't share a common session storage (the Window.sessionStorage property), but if they have the same domain (including port number, if any), they share a common local storage.

  Note

  Changes to browser security will affect your strategy for token handling.

  • If your add-in runs in Office on the web in the Microsoft Edge Legacy (non-Chromium) or Safari browser, the dialog and task pane don't share the same local storage, so it can't be used to communicate between them.
  • Starting in Version 115 of Chromium-based browsers, such as Chrome and Edge, storage partitioning is being tested to prevent specific side-channel cross-site tracking (see also Microsoft Edge browser policies). This means that data stored by storage APIs, such as local storage, are only available to contexts with the same origin and the same top-level site. To work around this, in your browser, go to chrome://flags or edge://flags, then set the Experimental third-party storage partitioning (#third-party-storage-partitioning) flag to Disabled. Where possible, we recommend to pass data between the dialog and task pane using the messageParent and messageChild methods as described in Use the Office dialog API in your Office Add-ins.

• Add query parameters to the URL that is passed to displayDialogAsync.

Use local storage

To use local storage, call the setItem method of the window.localStorage object in the host page before the displayDialogAsync call, as in the following example.

localStorage.setItem("clientID", "15963ac5-314f-4d9b-b5a1-ccb2f1aea248");

Code in the dialog box reads the item when it's needed, as in the following example.

const clientID = localStorage.getItem("clientID");
// You can also use property syntax:
// const clientID = localStorage.clientID;

Use query parameters

The following example shows how to pass data with a query parameter.

Office.context.ui.displayDialogAsync('https://myAddinDomain/myDialog.html?clientID=15963ac5-314f-4d9b-b5a1-ccb2f1aea248');

For a sample that uses this technique, see Insert Excel charts using Microsoft Graph in a PowerPoint add-in.

Code in your dialog box can parse the URL and read the parameter value.

Important

Office automatically adds a query parameter called _host_info to the URL that is passed to displayDialogAsync. (It is appended after your custom query parameters, if any. It isn't appended to any subsequent URLs that the dialog box navigates to.) Microsoft may change the content of this value, or remove it entirely, in the future, so your code shouldn't read it. The same value is added to the dialog box's session storage (the Window.sessionStorage property). Again, your code should neither read nor write to this value.