Freigeben über

Konfigurieren Ihres Outlook-Add-Ins für die ereignisbasierte Aktivierung

  • Artikel

Mit der ereignisbasierten Aktivierungsfunktion kann ein Benutzer ihr Add-In verwenden, um seine Aufgaben auszuführen, ohne das Add-In explizit zu starten. Ihr Add-In führt Aufgaben aus, wenn bestimmte Ereignisse auftreten, z. B. automatisch die Anlagen eines E-Mail-Elements aktualisieren, wenn sich die Empfänger ändern oder nach einer bestimmten Anlage suchen, bevor ein E-Mail-Element gesendet wird. Sie können die ereignisbasierte Aktivierung auch in den Aufgabenbereich und die Funktionsbefehle integrieren.

Hinweis

Die Unterstützung für dieses Feature wurde in Anforderungssatz 1.10 eingeführt, mit zusätzlichen Ereignissen, die jetzt in nachfolgenden Anforderungssätzen verfügbar sind. Ausführliche Informationen zum Mindestanforderungssatz eines Ereignisses und zu den Clients und Plattformen, die es unterstützen, finden Sie unter Unterstützte Ereignisse und Anforderungssätze, die von Exchange-Servern und Outlook-Clients unterstützt werden.

Informationen zum Implementieren eines ereignisbasierten Add-Ins, das in Outlook auf mobilen Geräten ausgeführt wird, finden Sie unter Implementieren der ereignisbasierten Aktivierung in mobilen Outlook-Add-Ins.

Unterstützte Ereignisse

In der folgenden Tabelle sind die derzeit verfügbaren Ereignisse und die unterstützten Clients für jedes Ereignis aufgeführt. Wenn ein Ereignis ausgelöst wird, empfängt der Handler ein event -Objekt, das spezifische Details für den Ereignistyp enthalten kann. Die Spalte Beschreibung enthält ggf. einen Link zum zugehörigen Objekt.

Kanonischer Ereignisname
und Nur-Add-In-Manifestname		 Einheitliches Manifest für Microsoft 365-Name Beschreibung Mindestanforderungssatz und unterstützte Clients
OnNewMessageCompose newMessageComposeCreated Beim Verfassen einer neuen Nachricht (einschließlich Antworten, Allen antworten und weiterleiten), aber nicht beim Bearbeiten, z. B. eines Entwurfs. 1.10
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
  • Android2
  • iOS2
OnNewAppointmentOrganizer newAppointmentOrganizerCreated Beim Erstellen eines neuen Termins, aber nicht beim Bearbeiten eines vorhandenen Termins. 1.10
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnMessageAttachmentsChanged messageAttachmentsChanged Beim Hinzufügen oder Entfernen von Anlagen beim Verfassen einer Nachricht.

Ereignisspezifisches Datenobjekt: AttachmentsChangedEventArgs		 1.11
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnAppointmentAttachmentsChanged appointmentAttachmentsChanged Beim Hinzufügen oder Entfernen von Anlagen beim Verfassen eines Termins.

Ereignisspezifisches Datenobjekt: AttachmentsChangedEventArgs		 1.11
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnMessageRecipientsChanged messageRecipientsChanged Beim Hinzufügen oder Entfernen von Empfängern beim Verfassen einer Nachricht.

Ereignisspezifisches Datenobjekt: RecipientsChangedEventArgs		 1.11
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
  • Android2
  • iOS2
OnAppointmentAttendeesChanged appointmentAttendeesChanged Beim Hinzufügen oder Entfernen von Teilnehmern beim Verfassen eines Termins.

Ereignisspezifisches Datenobjekt: RecipientsChangedEventArgs		 1.11
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnAppointmentTimeChanged appointmentTimeChanged Beim Ändern von Datum/Uhrzeit beim Verfassen eines Termins.

Ereignisspezifisches Datenobjekt: AppointmentTimeChangedEventArgs

Wichtig: Wenn Sie einen Termin an ein anderes Datums-/Uhrzeitfenster im Kalender ziehen und ablegen, tritt das OnAppointmentTimeChanged Ereignis nicht auf. Dies tritt nur auf, wenn das Datum/die Uhrzeit direkt von einem Termin geändert wird.		 1.11
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnAppointmentRecurrenceChanged appointmentRecurrenceChanged Beim Hinzufügen, Ändern oder Entfernen der Wiederholungsdetails beim Verfassen eines Termins. Wenn das Datum/die Uhrzeit geändert wird, tritt auch das OnAppointmentTimeChanged Ereignis auf.

Ereignisspezifisches Datenobjekt: RecurrenceChangedEventArgs		 1.11
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnInfoBarDismissClicked infoBarDismissClicked Beim Schließen einer Benachrichtigung beim Verfassen einer Nachricht oder eines Terminelements. Nur das Add-In, das die Benachrichtigung hinzugefügt hat, wird benachrichtigt.

Ereignisspezifisches Datenobjekt: InfobarClickedEventArgs		 1.11
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnMessageSend messageSending Beim Senden eines Nachrichtenelements. Weitere Informationen finden Sie in der exemplarischen Vorgehensweise zu intelligenten Warnungen. 1.12
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnAppointmentSend appointmentSending Beim Senden eines Terminelements. Weitere Informationen finden Sie unter Behandeln von OnMessageSend- und OnAppointmentSend-Ereignissen in Ihrem Outlook-Add-In mit intelligenten Warnungen. 1.12
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnMessageCompose messageComposeOpened Beim Verfassen einer neuen Nachricht (einschließlich Antworten, Allen antworten und weiterleiten) oder bearbeiten Sie einen Entwurf. 1.12
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnAppointmentOrganizer appointmentOrganizerOpened Beim Erstellen eines neuen Termins oder beim Bearbeiten eines vorhandenen Termins. 1.12
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnMessageFromChanged messageFromChanged Beim Ändern des E-Mail-Kontos im Feld Von einer Nachricht, die gerade erstellt wird. Weitere Informationen finden Sie unter Automatisches Aktualisieren Ihrer Signatur beim Wechseln zwischen Exchange-Konten. 1.13
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnAppointmentFromChanged appointmentFromChanged Beim Ändern des E-Mail-Kontos im Organisatorfeld eines Termins, der gerade erstellt wird. Weitere Informationen finden Sie unter Automatisches Aktualisieren Ihrer Signatur beim Wechseln zwischen Exchange-Konten. 1.13
OnSensitivityLabelChanged sensitivityLabelChanged Beim Ändern der Vertraulichkeitsbezeichnung beim Verfassen einer Nachricht oder eines Termins. Informationen zum Verwalten der Vertraulichkeitsbezeichnung eines E-Mail-Elements finden Sie unter Verwalten der Vertraulichkeitsbezeichnung Ihrer Nachricht oder Ihres Termins im Verfassenmodus.

Ereignisspezifisches Datenobjekt: SensitivityLabelChangedEventArgs		 1.13
  • Webbrowser
  • Windows (neu und klassisch1)
  • Neue Mac-Benutzeroberfläche
OnMessageReadWithCustomAttachment Nicht verfügbar Beim Öffnen einer Nachricht, die einen bestimmten Anlagentyp im Lesemodus enthält. Vorschau3
  • Windows (klassisch1)
OnMessageReadWithCustomHeader Nicht verfügbar Beim Öffnen einer Nachricht, die einen bestimmten Internetheadernamen im Lesemodus enthält. Vorschau3
  • Windows (klassisch1)

Hinweis

1 Ereignisbasierte Add-Ins im klassischen Outlook unter Windows erfordern mindestens Windows 10 Version 1903 (Build 18362) oder Windows Server 2019 Version 1903.

2 Outlook auf Mobilgeräten unterstützt APIs bis zum Postfachanforderungssatz 1.5. Die Unterstützung ist jetzt jedoch für zusätzliche APIs und Features aktiviert, die in späteren Anforderungssätzen wie dem OnNewMessageCompose -Ereignis eingeführt wurden. Weitere Informationen finden Sie unter Implementieren der ereignisbasierten Aktivierung in mobilen Outlook-Add-Ins.

3 Um eine Vorschau der OnMessageReadWithCustomAttachment Ereignisse und OnMessageReadWithCustomHeader anzuzeigen, müssen Sie das klassische Outlook unter Windows Version 2312 (Build 17110.10000) oder höher installieren. Nehmen Sie dann am Microsoft 365 Insider-Programm teil, und wählen Sie die Option Betakanal aus, um auf Office-Beta-Builds zuzugreifen.

Problembehandlung für Ihr Add-In

Während Sie Ihr ereignisbasiertes Add-In entwickeln, müssen Sie möglicherweise Probleme beheben, z. B. das Add-In wird nicht geladen oder das Ereignis tritt nicht auf. Eine Anleitung zur Problembehandlung für ein ereignisbasiertes Add-In finden Sie unter Problembehandlung bei ereignisbasierten Add-Ins und Spamberichts-Add-Ins.

Bereitstellen für Benutzer

Ereignisbasierte Add-Ins sind nur auf vom Administrator verwaltete Bereitstellungen beschränkt, auch wenn sie von AppSource abgerufen werden. Wenn Benutzer das Add-In aus AppSource oder dem In-App Office Store beziehen, können sie die ereignisbasierte Funktion des Add-Ins nicht aktivieren. Weitere Informationen zum Auflisten Ihres ereignisbasierten Add-Ins in AppSource finden Sie unter AppSource-Auflistungsoptionen für Ihr ereignisbasiertes Outlook-Add-In.

Admin Bereitstellungen erfolgen durch Hochladen des Manifests in die Microsoft 365 Admin Center. Erweitern Sie im Verwaltungsportal den Abschnitt Einstellungen im Navigationsbereich, und wählen Sie dann Integrierte Apps aus. Wählen Sie auf der Seite Integrierte Apps die Aktion Benutzerdefinierte Apps hochladen aus.

Die Seite Integrierte Apps im Microsoft 365 Admin Center mit hervorgehobener Aktion Benutzerdefinierte Apps hochladen.

Wichtig

Add-Ins, die das Feature "Intelligente Warnungen" verwenden, können nur in AppSource veröffentlicht werden, wenn die Sendemoduseigenschaft des Manifests auf die Option benutzereingabeaufforderung oder soft block festgelegt ist. Wenn die Eigenschaft des Sendemodus eines Add-Ins auf blockieren festgelegt ist, kann es nur vom Administrator eines organization bereitgestellt werden, da die AppSource-Überprüfung fehlschlägt.

Bereitstellen von Manifestupdates

Da ereignisbasierte Add-Ins von Administratoren bereitgestellt werden, erfordert jede Änderung, die Sie am Manifest vornehmen, die Zustimmung des Administrators über die Microsoft 365 Admin Center. Bis der Administrator Ihre Änderungen akzeptiert, werden Benutzer in ihren organization daran gehindert, das Add-In zu verwenden. Weitere Informationen zum Administratoreinwilligungsprozess finden Sie unter Admin Zustimmung zum Installieren ereignisbasierter Add-Ins.

Ereignisbasiertes Aktivierungsverhalten und Einschränkungen

Es wird erwartet, dass Add-In-Startereignishandler kurz ausgeführt, einfach und so nicht invasiv wie möglich sind. Nach der Aktivierung tritt für Ihr Add-In ein Timeout innerhalb von ca. 300 Sekunden auf. Dies ist die maximale Zeit, die für die Ausführung ereignisbasierter Add-Ins zulässig ist. Um zu signalisieren, dass das Add-In die Verarbeitung eines Startereignisses abgeschlossen hat, muss der zugeordnete Ereignishandler die event.completed-Methode aufrufen. (Beachten Sie, dass die Ausführung von Code nach der event.completed Anweisung nicht garantiert ist.) Jedes Mal, wenn ein Ereignis ausgelöst wird, das ihr Add-In behandelt, wird das Add-In reaktiviert und führt den zugeordneten Ereignishandler aus, und das Timeoutfenster wird zurückgesetzt. Das Add-In endet nach einem Zeitüberschreitung, oder der Benutzer schließt das Fenster zum Verfassen oder sendet das Element.

Wenn der Benutzer über mehrere Add-Ins verfügt, die dasselbe Ereignis abonnieren, startet die Outlook-Plattform die Add-Ins in keiner bestimmten Reihenfolge. Derzeit können nur fünf ereignisbasierte Add-Ins aktiv ausgeführt werden.

In allen unterstützten Outlook-Clients muss der Benutzer auf dem aktuellen E-Mail-Element verbleiben, in dem das Add-In aktiviert wurde, damit es ausgeführt wird. Wenn Sie vom aktuellen Element weg navigieren (z. B. zu einem anderen Erstellungsfenster oder einer anderen Registerkarte wechseln), wird der Add-In-Vorgang beendet. Ein Add-In, das für das Ereignis aktiviert wird, behandelt jedoch den OnMessageSend Elementwechsel unterschiedlich, je nachdem, auf welchem Outlook-Client es ausgeführt wird. Weitere Informationen finden Sie im Abschnitt "Benutzer navigiert von der aktuellen Nachricht weg" unter Behandeln von OnMessageSend- und OnAppointmentSend-Ereignissen in Ihrem Outlook-Add-In mit intelligenten Warnungen.

Zusätzlich zum Elementwechsel beendet ein ereignisbasiertes Add-In auch den Betrieb, wenn der Benutzer die Nachricht oder den Termin sendet, die er verfasst.

Ereignisbasierte Add-Ins im klassischen Outlook unter Windows

Beachten Sie beim Entwickeln eines ereignisbasierten Add-Ins, das im klassischen Outlook unter Windows-Client ausgeführt werden soll, Folgendes:

  • Importe werden in der JavaScript-Datei, in der Sie die Behandlung für die ereignisbasierte Aktivierung implementieren, nicht unterstützt.

  • Add-Ins führen keinen code aus, der in Office.onReady() und Office.initializeenthalten ist. Es wird empfohlen, Ihren Ereignishandlern stattdessen Eine beliebige Startlogik hinzuzufügen, z. B. das Überprüfen der Outlook-Version des Benutzers.

  • Nur die JavaScript-Datei, auf die im Manifest verwiesen wird, wird für die ereignisbasierte Aktivierung unterstützt. Sie müssen Ihren JavaScript-Code zur Ereignisbehandlung in dieser einzelnen Datei bündeln. Der Speicherort der JavaScript-Datei, auf die verwiesen wird, im Manifest variiert je nach Art des Manifests, das Ihr Add-In verwendet.

    • Nur Add-In-Manifest: <Untergeordnetes Element des Laufzeitknotens außer Kraft setzen>><
    • Einheitliches Manifest für Microsoft 365: Eigenschaft "script" des "code"-Objekts

    Beachten Sie, dass ein großes JavaScript-Paket Probleme mit der Leistung Ihres Add-Ins verursachen kann. Es wird empfohlen, schwere Vorgänge vorzuverarbeiten, damit sie nicht in Ihrem Ereignisbehandlungscode enthalten sind.

Nicht unterstützte APIs

Einige Office.js APIs, die die Benutzeroberfläche ändern oder ändern, sind von ereignisbasierten Add-Ins nicht zulässig. Die folgenden APIs sind blockiert.

API Methoden
Office.devicePermission
  • requestPermissionsAsync
Office.context.auth*
  • getAccessToken
  • getAccessTokenAsync
    		•
    Office.context.mailbox
    • displayAppointmentForm
    • displayMessageForm
    • displayNewAppointmentForm
    • displayNewMessageForm
    Office.context.mailbox.item
    • close
    Office.context.ui
    • displayDialogAsync
    • messageParent

    Hinweis

    * OfficeRuntime.auth wird in allen Outlook-Versionen unterstützt, die die ereignisbasierte Aktivierung und einmaliges Anmelden (Single Sign-On, SSO) unterstützen, während Office.auth nur in bestimmten Outlook-Builds unterstützt wird. Weitere Informationen finden Sie unter Verwenden des einmaligen Anmeldens (Single Sign-On, SSO) oder der ressourcenübergreifenden Ressourcenfreigabe (Cross-Origin Sharing, CORS) in Ihrem ereignisbasierten Oder Spam-Reporting-Outlook-Add-In.

    Vorschaufeatures in Ereignishandlern (klassisches Outlook unter Windows)

    Das klassische Outlook unter Windows enthält eine lokale Kopie der Produktions- und Betaversionen von Office.js, anstatt aus dem Content Delivery Network (CDN) zu laden. Standardmäßig wird auf die lokale Produktionskopie der API verwiesen. Um auf die lokale Betakopie der API zu verweisen, müssen Sie die Registrierung Ihres Computers konfigurieren. Dadurch können Sie Vorschaufeatures in Ihren Ereignishandlern im klassischen Outlook unter Windows testen.

    1. Navigieren Sie in der Registrierung zu HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Wenn der Schlüssel nicht vorhanden ist, erstellen Sie ihn.

    2. Erstellen Sie einen Eintrag namens , EnableBetaAPIsInJavaScript und legen Sie dessen Wert auf fest 1.

      Der Registrierungswert EnableBetaAPIsInJavaScript ist auf 1 festgelegt.

    Aktivieren des einmaligen Anmeldens (Single Sign-On, SSO)

    Um einmaliges Anmelden in Ihrem ereignisbasierten Add-In zu aktivieren, müssen Sie die zugehörige JavaScript-Datei zu einem bekannten URI hinzufügen. Eine Anleitung zum Konfigurieren dieser Ressource finden Sie unter Verwenden des einmaligen Anmeldens (Single Sign-On, SSO) oder der ressourcenübergreifenden Ressourcenfreigabe (Cross-Origin Resource Sharing, CORS) in Ihrem ereignisbasierten Outlook-Add-In oder Outlook-Add-In für Spamberichterstattung.

    Anfordern externer Daten

    Sie können externe Daten mithilfe einer API wie Fetch oder mithilfe von XMLHttpRequest (XHR) anfordern, einer Standardweb-API, die HTTP-Anforderungen für die Interaktion mit Servern ausgibt.

    Hinweis

    Wenn Ihr Add-In in einer reinen JavaScript-Runtime ausgeführt wird, verwenden Sie absolute URLs in Ihren Fetch-API-Aufrufen. Relative URLs in Fetch-API-Aufrufen werden in einer reinen JavaScript-Runtime nicht unterstützt.

    Beachten Sie, dass Sie zusätzliche Sicherheitsmaßnahmen verwenden müssen, wenn Sie XMLHttpRequest-Objekte verwenden, die dieselbe Ursprungsrichtlinie und CORS (Cross-Origin Resource Sharing) erfordern.

    Hinweis

    Vollständige CORS-Unterstützung ist in Outlook im Web-, Mac- und Windows-Clients (neu und klassisch (ab Version 2201, Build 16.0.14813.10000) verfügbar.

    Um CORS-Anforderungen von Ihrem ereignisbasierten Add-In zu senden, müssen Sie das Add-In und die zugehörige JavaScript-Datei einem bekannten URI hinzufügen. Eine Anleitung zum Konfigurieren dieser Ressource finden Sie unter Verwenden des einmaligen Anmeldens (Single Sign-On, SSO) oder der ressourcenübergreifenden Ressourcenfreigabe (Cross-Origin Resource Sharing, CORS) in Ihrem ereignisbasierten Outlook-Add-In oder Outlook-Add-In für Spamberichterstattung.

    Siehe auch