Upravit

Sdílet prostřednictvím

Get and set add-in metadata for an Outlook add-in

  • Článek

Manage custom data in your Outlook add-in using roaming settings, custom properties, or session data. These options give access to custom data that's only accessible by your Outlook add-in, but each method stores the data separately from the other. That is, the data stored through roaming settings isn't accessible by custom properties, and vice versa.

The following table provides an overview of the available options to manage custom data in Outlook add-ins.

Custom data option Minimum requirement set Applies to Description
Roaming settings 1.1 Mailbox Manages custom data in a user's mailbox. The add-in that sets the custom data can access it from other supported devices where the user's mailbox is set up. Stored data is accessible in subsequent Outlook sessions.
Custom properties 1.1 Mail item Manages custom data for a mail item in a user's mailbox. The add-in that sets the custom data can access it from the mail item on supported devices where the user's mailbox is set up. Stored data is accessible in subsequent Outlook sessions.
Session data 1.11 Mail item Manages custom data for a mail item in the user's current Outlook session. The add-in that sets the custom data can only access it from the mail item while it's being composed.

Note

For information on requirement sets and their supported clients, see Outlook JavaScript API requirement sets.

To learn more about each custom data option, select the applicable tab.

You can specify data specific to a user's Exchange mailbox using the RoamingSettings object. Examples of such data include the user's personal data and preferences. Your mail add-in can access roaming settings when it roams on any device it's designed to run on (desktop, tablet, or smartphone).

Changes to this data are stored on an in-memory copy of those settings for the current Outlook session. You should explicitly save all the roaming settings after updating them so that they'll be available the next time the user opens your add-in, on the same or any other supported device.

Important

While the Outlook add-in API limits access to these settings to only the add-in that created them, these settings shouldn't be considered secure storage. They can be accessed by other services, such as Microsoft Graph. They shouldn't be used to store sensitive information, such as user credentials or security tokens.

Roaming settings format

The data in a RoamingSettings object is stored as a serialized JavaScript Object Notation (JSON) string.

The following is an example of the structure, assuming there are three defined roaming settings named add-in_setting_name_0, add-in_setting_name_1, and add-in_setting_name_2.

{
  "add-in_setting_name_0": "add-in_setting_value_0",
  "add-in_setting_name_1": "add-in_setting_value_1",
  "add-in_setting_name_2": "add-in_setting_value_2"
}

Loading roaming settings

A mail add-in typically loads roaming settings in the Office.onReady handler. The following JavaScript code example shows how to load existing roaming settings and get the values of two settings, customerName and customerBalance.

let _mailbox;
let _settings;
let _customerName;
let _customerBalance;

Office.onReady((info) => {
  if (info.host === Office.HostType.Outlook) {
    // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    _customerName = _settings.get("customerName");
    _customerBalance = _settings.get("customerBalance");
  }
});

Creating or assigning a roaming setting

Continuing with the earlier example, the following JavaScript function, setAddInSetting, shows how to use the RoamingSettings.set method to set a setting named cookie with today's date. Then, it persists the data by using the RoamingSettings.saveAsync method to save all the roaming settings to the user's mailbox.

The set method creates the setting if the setting doesn't already exist, and assigns the setting to the specified value. The saveAsync method saves roaming settings asynchronously. This code sample passes a callback function, saveMyAddInSettingsCallback, to saveAsync. When the asynchronous call finishes, saveMyAddInSettingsCallback is called by using one parameter, asyncResult. This parameter is an AsyncResult object that contains the result of and any details about the asynchronous call. You can use the optional userContext parameter to pass any state information from the asynchronous call to the callback function.

// Set a roaming setting.
function setAddInSetting() {
  _settings.set("cookie", Date());
  // Save roaming settings to the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

// Callback function after saving custom roaming settings.
function saveMyAddInSettingsCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Removing a roaming setting

Still extending the earlier example, the following JavaScript function, removeAddInSetting, shows how to use the RoamingSettings.remove method to remove the cookie setting and save all the roaming settings to the mailbox.

// Remove an add-in setting.
function removeAddInSetting()
{
  _settings.remove("cookie");
  // Save changes to the roaming settings for the mailbox, so that they'll be available in the next Outlook session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

Try the code example in Script Lab

To learn how to create and manage a RoamingSettings object, get the Script Lab for Outlook add-in and try out the "Use add-in settings" sample. To learn more about Script Lab, see Explore Office JavaScript API using Script Lab.

See also