Freigeben über

Ereignisempfänger und Listenereignisempfänger im SharePoint-Add-In-Modell

  • Artikel

Der Ansatz zum Behandeln von Ereignissen in SharePoint unterscheidet sich im neuen SharePoint-Add-In-Modell von der Vorgehensweise bei voll vertrauenswürdigem Code.

In einem typischen Szenario mit voll vertrauenswürdigem Code (Full Trust Code, FTC) / Farmlösung wurden Ereignisempfänger und Listenereignisempfänger mit dem serverseitigen SharePoint-Objektmodell-Code erstellt und über Lösungen bereitgestellt.

Serverseitiges Objekt-Modell-Code und wird über Solutions bereitgestellt. In diesem Szenario wird der Ereignisempfängercode auf dem SharePoint-Server ausgeführt.

In einem Szenario mit einem SharePoint-Add-In-Modell werden Ereignisempfänger außerhalb von SharePoint in einem Webdienst erstellt und bei SharePoint registriert. Diese Elemente werden als Remoteereignisempfänger bezeichnet. In diesem Szenario wird der Code des Ereignisempfängers auf dem Webserver ausgeführt, auf dem sich der Webdienst befindet.

Wichtig

Ab Januar 2017 unterstützt SharePoint Online Listenwebhooks, die Sie anstelle von „-ed“-Remoteereignisempfängern verwenden können. Sehen Sie sich die Übersicht über SharePoint-Webhooks an, um mehr über Webhooks zu erfahren. Beachten Sie außerdem, dass im GitHub-Repository sp-dev-samples mehrere Webhookbeispiele zur Verfügung stehen.

Richtlinien auf hoher Ebene

Als Faustregel werden die folgenden allgemeinen Richtlinien für die Erstellung von Ereignisempfängern bereitgestellt.

  • Der Dienstendpunkt, der einen Ereignisempfänger implementiert, muss für anonyme Benutzer zugänglich sein.
  • Über Ereignisempfänger, die dem Add-In hinzugefügt werden, können Sie ein Zugriffstoken zurückgeben.
  • Ereignisempfänger, die dem Hostweb hinzugefügt werden, geben Zugriffstoken zurück, wenn sie mithilfe eines App-Zugriffstokens aus dem App-Kontext angewendet werden und die Operation im Hostweb vom Endbenutzer gesteuert wird (ItemAdded usw.).
  • Das AppInstalled-Ereignis muss innerhalb von 30 Sekunden abgeschlossen sein, ansonsten geht SharePoint davon aus, dass ein Fehler aufgetreten ist. SharePoint führt das Ereignis drei Mal aus, nach der vierten Ausführung geht SharePoint davon aus, dass die Add-In-Installation fehlgeschlagen ist.
  • Normale Ereignisse wie ItemAdded haben auch eine Zeitüberschreitung von 30 Sekunden, es gibt aber keinen Wiederholungsmechanismus.
  • Ereignisempfänger, die dem Hostweb ohne App-Kontext hinzugefügt werden, z. B. mit SharePointOnlineCredentials oder anderweitig, geben kein Zugriffstoken zurück, und Sie müssen mit dem Nur-App-Zugriffstoken auf das Hostweb zugreifen.
  • Das Hinzufügen von Ereignisempfängern zum Hostweb wird unterstützt.
    • Dies ist nur über CSOM-/REST-APIs möglich, nicht mithilfe von Visual Studio-Assistenten.
  • SharePoint ruft die Ereignisempfänger-Endpunkte auf, die für ein bestimmtes Ereignis konfiguriert wurden. Es gibt jedoch keine Garantie, dass der Code in den Ereignisempfänger-Endpunkten ausgeführt wird, da der Code nicht auf dem SharePoint-Server ausgeführt wird.

Beispiel:

Wenn die URL des Ereignisempfänger-Endpunkts nicht verfügbar ist, wird der Code des Ereignisempfängers nicht ausgeführt. Die URL kann aus mehreren Gründen nicht verfügbar sein. Zu den häufigsten Gründen gehören eine falsche Konfiguration, wenn die Endpunkt-URL registriert wird, DNS-Probleme beim Auflösen der URL, oder dass die Website, auf der der Endpunkt gehostet wird, heruntergefahren wird oder sich in einem nicht betriebsbereiten Zustand befindet.

Wenn ein Fehler in einem schlecht geschriebenen Code des Ereignisempfängers vorhanden ist, gibt es außerdem keine Möglichkeit, SharePoint zu benachrichtigen dass der Fehler aufgetreten ist und das Ereignis erneut ausgeführt werden sollte. Mit Ereignisempfängern, die an SharePoint-Listen angefügt sind, können Sie dieses Problem in einem gewissen Maß umgehen. Weitere Informationen zu diesem Vorgehen finden Sie weiter unten.

  • Wenn ein Ereignisempfänger eine große Menge Code ausführt, sollte ein asynchrones Muster verwendet werden.
  • Weitere Informationen zu Zeitüberschreitungen in Ereignisempfängern finden Sie im folgenden MSDN-Artikel. (Suchen Sie im Artikel nach Timeout.) Behandeln von Ereignissen in Add-Ins für SharePoint (MSDN-Artikel)
  • Wenn Ereignisempfänger in SharePoint-Listen arbeiten, empfehlen wir, dass Sie einen bestimmten Änderungsverfolgungsmechanismus zusammen mit dem Ereignisempfänger verwenden, um eine qualitativ hochwertigere Verarbeitung sicherzustellen.

Debuggen von Remoteereignisempfängern

Zum Debuggen von Ereignisempfängern müssen Sie in Azure und Visual Studio ein paar unterschiedliche Dinge konfigurieren. Die folgenden Artikel enthalten schrittweise Anweisungen und weitere Informationen zum Debuggen.

Weitere Beispiele

  • Core.EventReceivers (Office 365-PnP-Beispiel)
    • Dieses Beispiel zeigt, wie ein SharePoint-Add-In das Ereignis für die installierte App verwenden kann, um zusätzliche Arbeit im Hostweb auszuführen, z. B. das Anfügen von Ereignisempfängern an Listen im Hostweb.
  • Core.AppEvents.HandlerDelegation (Office 365-PnP-Beispiel)
    • In diesem Beispiel wird gezeigt, wie Handler für die Ereignisse „AppInstalled“ und „AppUninstalling“ implementiert werden, für die Folgendes gilt:
      1. Sie enthalten Rollback-Logik, wenn der Handler auf einen Fehler stößt.
      2. Sie enthalten die Logik „Bereits ausgeführt“ aufgrund der Tatsache, dass SharePoint den Handler bis zu weiteren drei Malen wiederholt, wenn dieser fehlschlägt oder länger als 30 Sekunden zur Fertigstellung benötigt.
      3. Sie verwenden die Handlerdelegierungsstrategie, um Anrufe vom Handlerwebdienst an SharePoint zu minimieren.
      4. Sie verwenden Sie die CSOM-Klassen „ExceptionHandlingScope“ und „ConditionalScope“.
  • Core.AppEvents (Office 365-PnP-Beispiel)
    • In diesem Beispiel wird gezeigt, wie Handler für die Ereignisse „AppInstalled“ und „AppUninstalling“ implementiert werden, für die Folgendes gilt:
      1. Sie enthalten Rollback-Logik, wenn der Handler auf einen Fehler stößt.
      2. Sie enthalten die Logik „Bereits ausgeführt“ aufgrund der Tatsache, dass SharePoint den Handler bis zu weiteren drei Malen wiederholt, wenn dieser fehlschlägt oder länger als 30 Sekunden zur Fertigstellung benötigt.

PnP-Beispiele

Gilt für

  • Office 365 mit mehreren Mandanten (MT)
  • Office 365 dediziert (D)
  • SharePoint 2013 lokal