Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-InGet and set add-in metadata for an Outlook add-in

Sie können benutzerdefinierte Daten in Ihrem Outlook-Add-In verwalten, indem Sie eine der folgenden Optionen verwenden:You can manage custom data in your Outlook add-in by using either of the following:

  • Roamingeinstellungen, mit denen benutzerdefinierte Daten für das Postfach des Benutzers verwaltet werden.Roaming settings, which manage custom data for a user's mailbox.
  • Benutzerdefinierte Eigenschaften, mit denen benutzerdefinierte Daten für ein Element im Postfach des Benutzers verwaltet werden.Custom properties, which manage custom data for an item in a user's mailbox.

Beide gewähren Zugriff auf benutzerdefinierte Daten, auf die nur über Ihr Outlook-Add-In zugegriffen werden kann, jede Methode speichert die Daten jedoch getrennt voneinander, d. h. Benutzerdefinierte Eigenschaften können nicht auf über Roamingeinstellungen gespeicherten Daten zugreifen und umgekehrt. Die Daten werden auf dem Server für dieses Postfach gespeichert und es kann in nachfolgenden Outlook-Sitzungen in allen Formfaktoren auf diese zugegriffen werden, die das Outlook-Add-In unterstützt.Both of these give access to custom data that is 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 is not accessible by custom properties, and vice versa. The data is stored on the server for that mailbox, and is accessible in subsequent Outlook sessions on all the form factors that the add-in supports.

Benutzerdefinierte Daten pro Postfach: RoamingeinstellungenCustom data per mailbox: roaming settings

Mithilfe des RoamingSettings-Objekts können Sie Daten angeben, die spezifisch für das Postfach eines Exchange-Benutzers sind. Beispiele solcher Daten sind die persönlichen Daten und Einstellungen des Benutzers. Ihr Mail-Add-In kann auf Roamingeinstellungen zugreifen, wenn das Roaming auf dem entsprechenden Gerät (Desktop, Tablet oder Smartphone) aktiviert ist.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).

Änderungen an diesen Daten werden in einer speicherinterne Kopie der Einstellungen für die aktuelle Outlook-Sitzung gespeichert. Sie müssen alle Roamingeinstellungen nach dem Aktualisieren explizit speichern, damit sie zur Verfügung stehen, sobald der Benutzer Ihr Outlook-Add-In das nächste Mal auf demselben oder einem anderen unterstützten Gerät öffnet.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 will be available the next time the user opens your add-in, on the same or any other supported device.

Format der RoamingeinstellungenRoaming settings format

Die Daten in einem RoamingSettings-Objekt werden als serialisierte JSON-Zeichenfolge gespeichert.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 , , and .

Im Folgenden finden Sie ein Beispiel für die Struktur. Hierbei wird vorausgesetzt, dass es drei definierte Roamingeinstellungen mit den Namen add-in_setting_name_0, add-in_setting_name_1 und add-in_setting_name_2 gibt.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_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"
}

Laden der RoamingeinstellungenLoading roaming settings

Ein E-Mail-Add-In lädt in der Regel die Roamingeinstellungen im Office.initialize-Ereignishandler.A mail add-in typically loads roaming settings in the Office.initialize event handler. Im folgenden JavaScript-Codebeispiel wird gezeigt, wie Sie vorhandene Roamingeinstellungen laden und die Werte der beiden Einstellungen customerName und customerBalance abrufen:A mail add-in typically loads roaming settings in the Office.initialize event handler. The following JavaScript code example shows how to load existing roaming settings and get the values of 2 settings, "customerName" and "customerBalance":

var _mailbox;
var _settings;
var _customerName;
var _customerBalance;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  // Initialize instance variables to access API objects.
  _mailbox = Office.context.mailbox;
  _settings = Office.context.roamingSettings;
  _customerName = _settings.get("customerName");
  _customerBalance = _settings.get("customerBalance");
}

Erstellen oder Zuweisen einer RoamingeinstellungCreating or assigning a roaming setting

Ausgehend vom vorherigen Beispiel veranschaulicht die folgende JavaScript-Funktion setAddInSetting, wie die RoamingSettings.set-Methode verwendet wird, um eine Einstellung namens cookie mit dem heutigen Datum festzulegen. Anschließend behält sie die Daten mit der RoamingSettings.saveAsync-Methode, um alle Roamingeinstellungen erneut auf dem Server zu speichern.Continuing with the preceding example, the following JavaScript function, setAddInSetting, shows how to use the RoamingSettings.set method to set a setting named cookie with today's date, and persist the data by using the RoamingSettings.saveAsync method to save all the roaming settings back to the server.

Die set-Methode erstellt die Einstellung, wenn die Einstellung nicht bereits vorhanden sind, und weist der Einstellung den angegebenen Wert zu.The set method creates the setting if the setting does not already exist, and assigns the setting to the specified value. Mit der saveAsync-Methode werden Roamingeinstellungen asynchron gespeichert.The saveAsync method saves roaming settings asynchronously. In diesem Codebeispiel wird die Rückrufmethode saveMyAddInSettingsCallback an saveAsync übergeben.This code sample passes a callback method, saveMyAddInSettingsCallback, to saveAsync. Nach Abschluss des asynchronen Aufrufs wird saveMyAddInSettingsCallback mit einem Parameter namens asyncResult aufgerufen.When the asynchronous call finishes, saveMyAddInSettingsCallback is called by using one parameter, asyncResult. Dieser Parameter ist ein AsyncResult-Objekt, das das Ergebnis und die Details zu dem asynchronen Aufruf enthält.This parameter is an AsyncResult object that contains the result of and any details about the asynchronous call. Sie können den optionalen userContext-Parameter verwenden, um jegliche Zustandsinformationen von dem asynchronen Aufruf an die Rückruffunktion zu übergeben.You can use the optional options parameter to pass any state information to the callback function.

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

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

Entfernen einer RoamingeinstellungRemoving a roaming setting

Als Fortsetzung der vorherigen Beispiele wird mit der JavaScript-Funktion removeAddInSetting veranschaulicht, wie Sie mit der RoamingSettings.remove-Methode die cookie-Einstellung entfernen und alle Roamingeinstellungen wieder auf dem Exchange-Server speichern.Also extending the preceding examples, the following JavaScript function, removeAddInSetting, shows how to use the RoamingSettings.remove method to remove the cookie setting and save all the roaming settings back to the Exchange Server.

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

Benutzerdefinierte Daten pro Element in einem Postfach: benutzerdefinierte EigenschaftenCustom data per item in a mailbox: custom properties

Sie können Daten für ein bestimmtes Element im Benutzerpostfach mit dem CustomProperties-Objekt angeben. Ihr Add-In könnte beispielsweise bestimmte Nachrichten kategorisieren und die Kategorie mithilfe der benutzerdefinierten Eigenschaft messageCategory kennzeichnen. Wenn Ihr Mail-Add-In Termine aus Besprechungsvorschlägen in einer Nachricht erstellt, können Sie mit einer benutzerdefinierten Eigenschaft diese Termine nachverfolgen. Auf diese Weise wird sichergestellt, dass beim zweiten Öffnen der Nachricht durch den Benutzer Ihr Mail-Add-In nicht zum zweiten Mal vorschlägt, den Termin zu erstellen.You can specify data specific to an item in the user's mailbox using the CustomProperties object. For example, your mail add-in could categorize certain messages and note the category using a custom property messageCategory. Or, if your mail add-in creates appointments from meeting suggestions in a message, you can use a custom property to track each of these appointments. This ensures that if the user opens the message again, your mail add-in does not offer to create the appointment a second time.

Ähnlich wie bei Roamingeinstellungen werden die Änderungen an benutzerdefinierten Eigenschaften in speicherinternen Kopien er Eigenschaften der aktuellen Outlook-Sitzung gespeichert. Um sicherzustellen, dass diese benutzerdefinierten Eigenschaften in der nächsten Sitzung zur Verfügung stehen, speichern Sie alle benutzerdefinierten Eigenschaften auf dem Server.Similar to roaming settings, changes to custom properties are stored on in-memory copies of the properties for the current Outlook session. To make sure these custom properties will be available in the next session, save all the custom properties to the server.

Auf diese für Add-Ins oder Elemente spezifischen benutzerdefinierten Eigenschaften kann nur mithilfe des CustomProperties-Objekts zugegriffen werden. Diese Eigenschaften weichen von den benutzerdefinierten, MAPI-basierten UserProperties im Outlook-Objektmodell und erweiterten Eigenschaften in Exchange-Webdienste ab. Mit dem Outlook-Objektmodell oder EWS kann auf CustomProperties nicht zugegriffen werden.These add-in-specific, item-specific custom properties can only be accessed by using the CustomProperties object. These properties are different from the custom, MAPI-based, UserProperties in the Outlook object model, and extended properties in Exchange Web Services (EWS). You cannot access CustomProperties by using the Outlook object model or EWS.

Ein Mail-Add-In kann jedoch mit dem GetItem-EWS-Vorgang die MAPI-basierten erweiterten Eigenschaften abrufen. Greifen Sie auf GetItem auf der Serverseite unter Verwendung eines Rückruftokens oder auf der Clientseite unter Verwendung der mailbox.makeEwsRequestAsync-Methode zu. Geben Sie in der GetItem-Anforderung die benötigten benutzerdefinierten erweiterten Eigenschaften in einem Eigenschaftensatz an. Ein Mail-Add-In kann auch makeEwsRequestAsync und CreateItem- und UpdateItem-EWS-Vorgänge zum Erstellen und Ändern erweiterter Eigenschaften verwenden.However, a mail add-in can get MAPI-based extended properties by using the EWS GetItem operation. Access GetItem on the server side by using a callback token, or on the client side by using the mailbox.makeEwsRequestAsync method. In the GetItem request, specify the custom extended properties you need in a property set. A mail add-in can also use makeEwsRequestAsync and EWS CreateItem and UpdateItem operations to create and modify extended properties.

Verwenden benutzerdefinierter EigenschaftenUsing custom properties

Bevor Sie benutzerdefinierte Eigenschaften verwenden, müssen Sie sie durch Aufrufen der loadCustomPropertiesAsync-Methode laden. Sind bereits benutzerdefinierte Eigenschaften für das aktuelle Element festgelegt, werden sie zu diesem Zeitpunkt vom Exchange-Server geladen. Nach der Erstellung des Eigenschaftenbehälters können Sie mithilfe der set- und get-Methode benutzerdefinierte Eigenschaften hinzufügen und abrufen. Zum Speichern von Änderungen an Eigenschaftenbehältern müssen Sie die saveAsync-Methode verwenden, um die Änderungen auf dem Exchange-Server zu speichern.Before you can use custom properties, you must load them by calling the loadCustomPropertiesAsync method. If any custom properties are already set for the current item, they are loaded from the Exchanger server at this point. After you have created the property bag, you can use the set and get methods to add and retrieve custom properties. To save any changes that you make to the property bag, you must use the saveAsync method to persist the changes on the Exchange server.

Hinweis

Da Outlook für Mac keine benutzerdefinierten Eigenschaften zwischenspeichert, könnten Mail-Add-Ins in Outlook für Mac bei einem Ausfall des Benutzernetzwerks nicht auf deren benutzerdefinierte Eigenschaften zugreifen.Because Outlook for Mac doesn't cache custom properties, if the user's network goes down, mail add-ins in Outlook for Mac would not be able to access their custom properties.

Beispiel für benutzerdefinierte EigenschaftenCustom properties example

Das folgende Beispiel zeigt eine vereinfachte Gruppe von Methoden für ein Outlook-Add-In, das benutzerdefinierte Eigenschaften verwendet.The following example shows a simplified set of methods for an Outlook add-in that uses custom properties. You can use this example as a starting point for your add-in that uses custom properties. Sie können dieses Beispiel als Ausgangspunkt für Ihr Add-In verwenden, das benutzerdefinierte Eigenschaften verwendet.The following example shows a simplified set of methods for an Outlook add-in that uses custom properties. You can use this example as a starting point for your add-in that uses custom properties.

Dieses Beispiel umfasst die folgenden Methoden:This example includes the following methods:

  • Office.initialize – Initialisiert das Add-In und lädt den benutzerdefinierten Eigenschaftenbehälter vom Exchange-Server.Office.initialize -- Initializes the add-in and loads the custom property bag from the Exchange server.

  • customPropsCallback – Ruft den vom Server zurückgegebenen benutzerdefinierten Eigenschaftenbehälter ab und speichert ihn zur späteren Verwendung.customPropsCallback -- Gets the custom property bag that is returned from the server and saves it for later use.

  • updateProperty – Legt eine bestimmte Eigenschaft fest oder aktualisiert sie und speichert die Änderung dann auf dem Server.updateProperty -- Sets or updates a specific property, and then saves the change to the server.

  • removeProperty – Entfernt eine bestimmte Eigenschaft aus dem Eigenschaftenbehälter und speichert die Entfernung dann auf dem Server.removeProperty -- Removes a specific property from the property bag, and then saves the removal to the server.

var _mailbox;
var _customProps;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  _mailbox = Office.context.mailbox;
  _mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}

// Callback function from loading custom properties.
function customPropsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
  else {
    // Successfully loaded custom properties,
    // can get them from the asyncResult argument.
    _customProps = asyncResult.value;
  }
}

// Get individual custom property.
function getProperty() {
  var myProp = customProps.get("myProp");
}

// Set individual custom property.
function updateProperty(name, value) {
  _customProps.set(name, value);
  // Save all custom properties to server.
  _customProps.saveAsync(saveCallback);
}

// Remove a custom property.
function removeProperty(name) {
  _customProps.remove(name);
  // Save all custom properties to server.
  _customProps.saveAsync(saveCallback);
}

// Callback function from saving custom properties.
function saveCallback() {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Siehe auchSee also