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 speicherinternen 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 Objekt des Typs RoamingSettings werden als serialisierte JSON-Zeichenfolge (JavaScript Object Notation) gespeichert.The data in a RoamingSettings object is stored as a serialized JavaScript Object Notation (JSON) string.

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 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"
}

Laden der RoamingeinstellungenLoading roaming settings

Ein Mail-Add-In lädt typischerweise Roaming-Einstellungen in den Office.initialize Event-Handler. Das folgende JavaScript-Codebeispiel zeigt, wie man bestehende Roaming-Einstellungen lädt und die Werte von 2 Einstellungen erhält, customerName und customerBalance: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 Methode set erstellt die Einstellung, wenn die Einstellung noch nicht vorhanden ist, und weist die Einstellung dem angegebenen Wert zu. Die Methode saveAsync speichert Roaming-Einstellungen asynchron. Dieses Codebeispiel übergibt eine Callback-Methode, saveMyAddInSettingsCallback, an saveAsync. Wenn der asynchrone Aufruf beendet ist, wird saveMyAddInSettingsCallback mit einem Parameter aufgerufen, asyncResult. Dieser Parameter ist ein AsyncResult Objekt, das das Ergebnis und alle Details über den asynchronen Aufruf enthält. Mit dem optionalen Parameter userContext können Sie beliebige Zustandsinformationen aus dem asynchronen Aufruf an die Callback-Funktion übergeben.The set method creates the setting if the setting does not already exist, and assigns the setting to the specified value. The saveAsync method saves roaming settings asynchronously. This code sample passes a callback method, 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 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 der 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 add-in-spezifischen, artikelspezifischen benutzerdefinierten Eigenschaften kann nur über das Objekt CustomProperties zugegriffen werden. Diese Eigenschaften unterscheiden sich von den benutzerdefinierten, MAPI-basierten, UserProperties im Outlook-Objektmodell und erweiterten Eigenschaften in Exchange Web Services (EWS). Sie können nicht über das Outlook-Objektmodell oder EWS auf CustomProperties zugreifen.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 MAPI-basierte erweiterte Eigenschaften erhalten, indem es die Operation EWS GetItem verwendet. Greifen Sie auf GetItem auf der Serverseite über ein Callback-Token oder auf der Client-Seite über die Methode mailbox.makeEwsRequestAsync zu. Geben Sie in der Anfrage GetItem die benutzerdefinierten erweiterten Eigenschaften an, die Sie in einem Property-Set benötigen. Ein Mail-Add-In kann auch makeEwsRequestAsync und EWS CreateItem und UpdateItem Operationen 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

Im folgenden Beispiel wird ein einfacher Methodensatz für ein Outlook-Add-In veranschaulicht, in dem benutzerdefinierte Eigenschaften verwendet werden. Sie können dieses Beispiel als Ausgangspunkt für ein eigenes Mail-Add-In nutzen, in dem benutzerdefinierte Eigenschaften verwendet werden.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