Aktivieren von Add-Ins mit Ereignissen

Die ereignisbasierte Aktivierung löst ihr Add-In automatisch aus, um seine Aufgaben auszuführen, ohne es explizit zu starten. Dadurch kann das Add-In kritische Inhalte ohne manuelle Vorgänge überprüfen, einfügen oder aktualisieren. Das Add-In wird im Hintergrund geöffnet, um zu vermeiden, dass der Benutzer gestört wird. Sie können die ereignisbasierte Aktivierung auch in den Aufgabenbereich und die Funktionsbefehle integrieren.

Übersicht

Während die einzelnen Schritte zum Hinzufügen von ereignisbasierter Funktionalität zu Ihrem Add-In je nach Plattform und Manifesttyp variieren, sieht der allgemeine Ablauf wie folgt aus.

1. Aktualisieren Sie das Manifest mit einer Erweiterung für das Ereignis.
2. Verbinden Sie das Ereignis im Manifest mit einer JavaScript-Funktion, um das Ereignis zu behandeln.
3. Lassen Sie die Ereignishandlerfunktion ihre Aktionen ausführen, und rufen event.completed Sie dann auf, wenn sie abgeschlossen ist.
4. Rufen Sie Office.actions.associate auf, um die Ereignishandlerfunktion mit der im Manifest angegebenen ID zu verbinden.

Testen der ereignisbasierten Aktivierung

Erfahren Sie, wie Sie Workflows optimieren und die Benutzererfahrung mit ereignisbasierter Aktivierung verbessern können. Testen Sie die Beispiele, um das Feature in Aktion zu sehen.

Outlook-Beispiele

• Automatisches Festlegen des Betreffs einer neuen Nachricht oder eines neuen Termins
• Automatisches Überprüfen auf eine Anlage, bevor eine Nachricht gesendet wird
• Automatisches Aktualisieren Ihrer Signatur beim Wechseln zwischen E-Mail-Konten
• Verschlüsseln von Anlagen, Verarbeiten von Besprechungsanfragen und Reagieren auf Termindatums-/Uhrzeitänderungen mithilfe der ereignisbasierten Outlook-Aktivierung
• Festlegen Ihrer Signatur mithilfe der ereignisbasierten Outlook-Aktivierung
• Identifizieren und Markieren externer Empfänger mithilfe der ereignisbasierten Outlook-Aktivierung
• Überprüfen der Farbkategorien einer Nachricht oder eines Termins vor dem Senden mithilfe von intelligenten Warnungen
• Überprüfen der Vertraulichkeitsbezeichnung einer Nachricht

Word Beispiele

• Hinzufügen von Kopfzeilen beim Öffnen eines Dokuments

Unterstützte Ereignisse

In den folgenden Tabellen 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.

Excel-, PowerPoint- Word-Ereignisse

Outlook-Ereignisse

Die Unterstützung für dieses Feature in Outlook wurde in Anforderungssatz 1.10 eingeführt, mit zusätzlichen Ereignissen, die jetzt in nachfolgenden Anforderungssätzen verfügbar sind. In der folgenden Tabelle sind der Mindestanforderungssatz für jedes Ereignis sowie die Clients und Plattformen aufgeführt, die es unterstützen. Weitere Informationen zu Outlook-Clients und den unterstützten Anforderungssätzen finden Sie unter Von Exchange-Servern und Outlook-Clients unterstützte Anforderungssätze.

Ereignisbasierte Aktivierung in Outlook auf mobilen Geräten

Outlook für Mobile 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.

Verhalten und Einschränkungen

Beachten Sie bei der Entwicklung eines ereignisbasierten Add-Ins die folgenden Featureverhalten und Einschränkungen.

• Ereignisbasierte Add-Ins funktionieren nur, wenn sie von einem Administrator bereitgestellt werden. Wenn Benutzer sie direkt aus Dem Microsoft Marketplace oder dem Office Store installieren, werden sie nicht automatisch gestartet (Problemumgehungen zur Einschränkung des Microsoft Marketplace finden Sie unter Microsoft Marketplace-Auflistungsoptionen für Ihr ereignisbasiertes Add-In). Admin Bereitstellungen erfolgen durch Hochladen des Manifests in die Microsoft 365 Admin Center.

• APIs, die mit der Benutzeroberfläche interagieren oder UI-Elemente anzeigen, werden für Word, PowerPoint und Excel unter Windows nicht unterstützt. Dies liegt daran, dass der Ereignishandler in einer reinen JavaScript-Runtime ausgeführt wird. Weitere Informationen finden Sie unter Runtimes in Office-Add-Ins.

• Ereignisbasierte Add-Ins erfordern eine Internetverbindung, um gestartet werden zu können, wenn ein bestimmtes Ereignis eintritt. Es wird erwartet, dass Add-In-Ereignishandler 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.

• Das Verhalten mehrerer Add-Ins, die dasselbe Ereignis abonnieren, ist nicht deterministisch. Outlook startet die Add-Ins in keiner bestimmten Reihenfolge. Für Excel, PowerPoint und Word wird nur ein zufälliges Add-In aktiviert. Wenn beispielsweise mehrere Word Add-Ins, die behandelnOnDocumentOpened, wird nur einer dieser Handler ausgeführt.

• 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-In-Einschränkungen in Excel, PowerPoint, Word und klassischem Outlook unter Windows

Beachten Sie beim Entwickeln eines ereignisbasierten Add-Ins für die Ausführung auf einem Windows-Client Folgendes:

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

• 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: <Override> untergeordnetes Element des <Runtime> Knotens
  • Einheitliches Manifest für Microsoft 365: "script" Eigenschaft 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.

• Wenn die im Manifest angegebene JavaScript-Funktion zum Behandeln eines Ereignisses ausgeführt wird, wird code in Office.onReady() und Office.initialize nicht ausgeführt. Es wird empfohlen, den Ereignishandlern stattdessen jede Startlogik hinzuzufügen, die von Ereignishandlern benötigt wird, z. B. die Überprüfung der Clientversion des Benutzers.

Ereignisbasierte Add-In-Einschränkungen in Excel, PowerPoint und Word

Die folgenden Plattformen oder Features werden noch nicht unterstützt.

• Office für Mac
• Das einheitliche Manifest für Microsoft 365

Ereignisbasierte Add-In-Einschränkungen in Outlook im Web und dem neuen Outlook unter Windows

In Outlook im Web und dem neuen Outlook unter Windows wird die ereignisbasierte Aktivierung nur auf Standardoberflächen zum Lesen und Verfassen von Nachrichten und Terminen unterstützt. Die ereignisbasierte Aktivierung funktioniert möglicherweise nicht, wenn sie auf einigen nicht standardmäßigen Oberflächen erstellt wird. Zum Beispiel:

• Antworten auf eine Besprechungseinladung mithilfe der Option RSVP mit Notiz .
• Weiterleiten einer Besprechung aus dem Kalender.

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.

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.

   

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 oder Spamberichterstellungs-Office-Add-In.

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.

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.

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 oder Spamberichterstellungs-Office-Add-In.

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 Ihres Add-Ins

Abhängig von der Office-Anwendung können ereignisbasierte Add-Ins über eine der folgenden Optionen bereitgestellt werden.

• Admin verwaltete Bereitstellung: Das Add-In wird über die Microsoft 365 Admin Center bereitgestellt.
• Eingeschränkte Auflistung im Microsoft Marketplace: Das Add-In wird im Microsoft Marketplace veröffentlicht, aber nicht in den Suchergebnissen angezeigt. Der Add-In-Erwerb erfordert eine Flight-Code-URL. Das Add-In muss weiterhin von einem Administrator bereitgestellt werden, damit das ereignisbasierte Aktivierungsfeature funktioniert.
• Uneingeschränkter Eintrag im Microsoft Marketplace: Das Add-In wird im Microsoft Marketplace veröffentlicht und kann von Benutzern und Administratoren mithilfe des Namens oder der ID des Add-Ins gesucht werden. Admin Bereitstellung ist nicht erforderlich, damit das ereignisbasierte Aktivierungsfeature funktioniert. Das Add-In muss bestimmte Anforderungen für eine uneingeschränkte Auflistung erfüllen.

In der folgenden Tabelle werden die Bereitstellungsoptionen für die ereignisbasierte Aktivierung durch die Office-Anwendung beschrieben.

Anweisungen zum Bereitstellen eines Add-Ins über die Microsoft 365 Admin Center finden Sie unter Admin verwaltete Bereitstellung. Weitere Informationen zum Auflisten Ihres ereignisbasierten Add-Ins im Microsoft Marketplace finden Sie unter Microsoft Marketplace-Auflistungsoptionen für Ihr ereignisbasiertes Add-In.

Admin verwaltete Bereitstellung

Admin Bereitstellungen erfolgen durch Hochladen des Manifests in die Microsoft 365 Admin Center. Führen Sie hierzu die folgenden Schritte aus.

1. Erweitern Sie im Verwaltungsportal den Abschnitt Einstellungen im Navigationsbereich, und wählen Sie dann Integrierte Apps aus.
2. Wählen Sie auf der Seite Integrierte Apps die Aktion Benutzerdefinierte Apps hochladen aus.

Weitere Informationen zum Bereitstellen eines Add-Ins finden Sie unter Bereitstellen und Veröffentlichen von Office-Add-Ins im Microsoft 365 Admin Center.

Bereitstellen von Manifestupdates

Wenn ein ereignisbasiertes Add-In vom Administrator bereitgestellt wurde, erfordert jede Änderung, die Sie am Manifest vornehmen, die Zustimmung des Administrators über das 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.

Siehe auch

• Problembehandlung bei ereignisbasierten Add-Ins und Spam-Berichts-Add-Ins
• Debuggen von ereignisbasierten Add-Ins und Spambericht-Add-Ins
• Microsoft Marketplace-Auflistungsoptionen für Ihr ereignisbasiertes Add-In
• Behandeln von OnMessageSend- und OnAppointmentSend-Ereignissen in Ihrem Outlook-Add-In mit intelligenten Warnungen