Behandeln von Ereignissen in SharePoint-Add-Ins

Ihr benutzerdefinierter Code kann drei Kategorien von Ereignissen in vom Anbieter gehosteten Add-Ins behandeln:

• Listenereignisse, z. B. das Hinzufügen oder Löschen einer Liste auf einer Website.
• Listenelementereignisse, z. B. das Bearbeiten eines Elements in einer Liste.
• Add-In-Ereignisse, z. B. die Installation eines Add-Ins.

In SharePoint gehostete SharePoint-Add-Ins unterstützen keine Ereignisbehandlung, Sie können jedoch einen Workflow in eine Art Liste oder Listenelemente-Ereignishandler umwandeln, indem ein Ereignis zum Auslösen des Workflows festgelegt wird. Weitere Informationen finden Sie unter Workflows in SharePoint. Workflows können nicht von Add-In-Ereignissen ausgelöst werden, Add-In-Ereignisse können daher nicht mit einem in SharePoint-gehosteten Add-In behandelt werden.

Hinweis

Websiteereignisse und Websitesammlungsereignisse werden in SharePoint-Add-Ins nicht unterstützt.

Es gibt zwei Arten von Ereignissen:

• Before-Ereignisse werden ausgelöst, bevor die SharePoint-Infrastruktur ihre eigene Behandlung des Ereignisses durchführt (einschließlich der Übernahme von Änderungen in der Inhaltsdatenbank). In SharePoint werden benutzerdefinierte before-Ereignishandler immer synchron ausgeführt. Sie können unter anderem zum Abbrechen des Ereignisses verwendet werden. Wenn ein Add-In beispielsweise eine Funktion zum Löschen einer Liste aufweist, kann ein Handler für das Ereignis zum Löschen der Liste das Löschen abbrechen, wenn bestimmte Bedingungen nicht erfüllt werden. Wenn das Ereignis Teil einer Abfolge von Ereignissen ist, wird durch das Abbrechen verhindert, dass spätere Ereignisse auftreten. Wenn Ihr Handler für das ItemAdding-Ereignis beispielsweise das Ereignis abbricht, wird das ItemAdded-Ereignis, das normalerweise später kommt, nicht ausgelöst.

• After-Ereignisse werden ausgelöst, nachdem die SharePoint-Infrastruktur ihre eigene Behandlung des Ereignisses ausgeführt hat. In SharePoint werden after-Remoteereignishandler für Listen- und Listenelementereignisse immer synchron ausgeführt. (App-Ereignisse sind eine Ausnahme). Sie können unter anderem zum Protokollieren von Ereignissen verwendet werden.

Behandeln von Listen- und Listenelementereignissen

Zum Behandeln von Listen- und Listenelementereignissen erstellen Sie Remoteereignisempfänger (RERs), bei denen es sich um Webdienste handelt, die extern in der SharePoint-Farm oder SharePoint Online ausgeführt werden. Die URL des RER-Diensts wird für die ereignisse registriert, die er behandelt. Es gibt zwei Möglichkeiten, einen Handler zu registrieren:

• Ereignisse im Hostweb werden programmgesteuert beim CSOM (Clientobjektmodell) oder der SharePoint-REST-API registriert. Diese Aufgabe wird in der Regel in der Logik der „ersten Ausführung“ im Add-In oder in einem Handler für ein Add-In-Ereignis ausgeführt. (Eine Übersicht der Add-In-Ereignisse finden Sie unter Verarbeiten von Add-In-Ereignissen weiter unten in diesem Artikel.) Ein Codebeispiel, das ein Listenereignis programmgesteuert registriert, finden Sie unter SharePoint/PnP/Samples/Core.EventReceivers.

• Ereignisse im Add-In-Web werden normalerweise mit einfachem XML-Markup in einem Feature des Add-In-Webs registriert. Details zum Erstellen des Markups und des Diensts finden Sie in Erstellen eines Remoteereignisempfängers in Add-Ins für SharePoint. Es ist auch möglich, Add-In-Web-Ereignisse programmgesteuert zu registrieren.

Hinweis

RERs dienen demselben Zweck wie Ereignisempfänger in Farmlösungen. Ereignisempfänger weisen jedoch benutzerdefinierten Code auf, der auf den SharePoint-Servern ausgeführt wird, sodass sie nicht in SharePoint-Add-Ins verwendet werden können.

Ihr Add-In kann die folgenden Listenelement- und Dokumentbibliotheksereignisse behandeln. Bei Ereignissen mit der Endung „ing“ handelt es sich um before-Ereignisse (synchron), und bei Ereignissen mit der Endung „ed“ handelt es such um after-Ereignisse (asynchron).

Before (synchron)	After (synchron)
ListAdding	ListAdded
ListDeleting	ListDeleted
FieldAdding	FieldAdded
FieldDeleting	FieldDeleted
FieldUpdating	FieldUpdated

Bei den FieldUpdate-Ereignissen geht es um die Änderung der Eigenschaften eines Felds (einer Spalte) in einer Liste, z. B. dessen Sortierbarkeit, nicht um die Änderung der Daten in dem Feld.

Ihr Add-In kann die folgenden Listenelementereignisse behandeln.

Before (synchron)	After (synchron)
ItemAdding	ItemAdded
ItemUpdating	ItemUpdated
ItemDeleting	ItemDeleted
ItemCheckingOut	ItemCheckedOut
ItemCheckingIn	ItemCheckedIn
ItemUncheckingOut	ItemUncheckedOut
ItemAttachmentAdding	ItemAttachmentAdded
ItemAttachmentDeleting	ItemAttachmentDeleted
ItemFileMoving	ItemFileMoved
ItemVersionDeleting*	ItemVersionDeleted*
	ItemFileConverted

Hinweis

*Diese beiden neuen Ereignisse sind in der Visual Studio-Benutzeroberfläche möglicherweise nicht verfügbar. Wenn dies nicht der Fall ist, wählen Sie „ItemDeleting“ oder „ItemDeleted“ aus, und ändern Sie dann die Namen manuell.

Wenn Sie in Visual Studio arbeiten und einen RER zu einem SharePoint-Add-In-Projekt hinzufügen, wird von den Office-Entwicklertools für Visual Studio Folgendes ausgeführt:

• Eine Webdienstdatei wie "RemoteEventReceiver1.svc" wird der Webanwendung hinzugefügt, um die Ereignisse zu verarbeiten, die Sie beim Hinzufügen des Remoteereignisempfängers zur SharePoint-Add-In angegeben haben. Der Webdienst enthält eine Codedatei zum Behandeln der Remoteereignisse.

  Nachdem Sie den Remoteereignisempfänger erstellt haben, fügen Sie der Codedatei für den Webanwendungsdienst Code zum Behandeln der Ereignisse hinzu. Standardmäßig enthält die Codedatei zwei Methoden, die Sie Ihrem Behandlungscode hinzufügen:

  • ProcessEvent() behandelt Vorabereignisse (wie die in den linken Spalten in den Tabellen im früheren Verlauf des Artikels) und gibt ein Objekt an SharePoint zurück, das meldet, ob das Ereignis abgebrochen oder fortgesetzt werden sollte.

  • ProcessOneWayEvent() behandelt Nachfolgeereignisse. Es wird asynchron ausgeführt und gibt nichts an SharePoint zurück.

  Wenn ein registriertes Ereignis auftritt, ruft SharePoint die entsprechende Methode in Ihrem Dienst auf und übergibt ein Objekt, das für Ihren Code einige Kontextinformationen bereitstellt. Beispielsweise wird der Ereignistyp (aus einer der beiden Tabellen weiter oben in diesem Artikel) identifiziert, damit Ihr Code mit der Logik verzweigt werden kann, die für das Ereignis geeignet ist.

• Ein Projektelement für den Remoteereignisempfänger wird dem SharePoint-Add-In-Projekt hinzugefügt. Die Datei "Elements.xml" für den Remoteereignisempfänger verweist auf den Webdienst in der Webanwendung und die Remoteereignisse, die Sie angegeben haben. Das folgende Beispiel zeigt eine Datei "Elements.xml", die das Hinzufügen oder Löschen eines Listenelements behandelt.

  <?xml version="1.0" encoding="utf-8"?>
  <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Receivers ListTemplateId="104">
      <Receiver>
          <Name>RemoteEventReceiver1ItemAdding</Name>
          <Type>ItemAdding</Type>
          <SequenceNumber>10000</SequenceNumber>
          <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url>
      </Receiver>
      <Receiver>
          <Name>RemoteEventReceiver1ItemDeleting</Name>
          <Type>ItemDeleting</Type>
          <SequenceNumber>10000</SequenceNumber>
          <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url>
      </Receiver>
  </Receivers>
  </Elements>
  

Um die Ereignisse zu ändern, die der Remote-Ereignisempfänger behandelt, öffnen Sie den Projektmappen-Explorer und dann das Fenster Eigenschaften für den Remote-Ereignisempfänger, erweitern den Knoten SharePoint-Ereignisse und legen dann nur die zu behandelnden Ereignisse auf True fest.

Hinweis

Weitere Informationen zu RERs, einschließlich Informationen zur Problembehandlung, finden Sie unter Häufig gestellte Fragen zu Remoteereignisempfängern.

Verarbeiten von Add-In-Ereignissen

Add-In-Ereignisse werden auch von Remotewebdiensten verarbeitet, werden aber im Add-In-Paket anders als Listen- und Listenelement-RERs konfiguriert, sie werden daher als separate Komponentenkategorie behandelt. Bei einem Add-In-Ereignis wird der Remotewebdienst im Add-In-Manifest registriert und nicht in einem Add-In-Webfeature. Das Add-In muss nicht einmal über ein Add-In-Web verfügen. Es gibt drei Add-In-Ereignisse, wie in den nächsten Abschnitten beschrieben.

AppInstalled-Ereignis

Das AppInstalled-Ereignis wird unmittelbar ausgeführt, nachdem SharePoint alle erforderlichen Vorgänge beim Installieren des Add-Ins ausgeführt hat, jedoch bevor der Benutzer bemerkt, dass die Installation abgeschlossen ist. Obwohl es sich hier um ein After-Ereignis handelt, führt SharePoint Ihren Handler synchron aus. Das Add-In kann erst verwendet werden, wenn der Handler abgeschlossen ist, und der Handler kann die Installation abbrechen (wodurch verursacht wird, dass SharePoint alle Vorgänge, die im Rahmen der Installation ausgeführt wurden, zurücksetzt). Es hat sich in der Tat bewährt, alle Fehler in Ihrem Handler abzufangen und SharePoint anzuweisen, die Installation zurückzusetzen. Weitere Informationen finden Sie unter Einbeziehen von Rollbacklogik und „Bereits erledigt“-Logik im Add-In-Ereignishandler.

Hinweis

Bei der Installation eines Add-Ins mit Mandantenbereich wird dieses in der Websitesammlung des Add-In-Katalogs erstellt, und das AppInstalled-Ereignis wird nur dann ausgeführt. Das Add-In ist auf mehreren Websites in dem Mandanten sichtbar, es führt diese jedoch nicht separat aus.

Neben dem Abbruch der Add-In-Installation kann dieses Ereignis für viele andere Zwecke verwendet werden:

• Installieren von SharePoint-Komponenten im Hostweb, die nicht deklarativ mit dem Hostwebfeature installiert werden können, z. B. Listen oder Unterwebsites.

• Programmgesteuertes Registrieren von Listen- und Listenelement-Ereignishandlern beim Hostweb oder Add-In-Web.

• Festlegen von Initialisierungseinstellungen, die auf die App-Instanz bezogen sind. Das Add-In kann beispielsweise einen Eigenschaftenbehälter für das Add-In-Web für die Einstellungen umfassen, die sich von einer Instanz des Add-Ins zur anderen unterscheiden. Ihr AppInstalled-Handler kann zum Beispiel basierend auf dem Websitetyp des Hostwebs (z. B. Teamwebsite oder Blogwebsite) unterschiedliche Werte in den Eigenschaftenbehälter schreiben.

  Hinweis

  Durch Überprüfen, ob das Hostweb eine AppCatalog-Website ist, lässt sich einfach feststellen, ob das Add-In mit Mandantenbereich installiert wurde. Finden Sie unter Mandantschaften und Bereitstellungsbereiche von Add-Ins für SharePoint.

• Ausführen einer App-Instanz-relativen Konfiguration in der Remotewebanwendung des Add-Ins, z. B. Hinzufügen einer Tabelle zu einer Datenbank.

Wichtig

Die Implementierung des AppInstalled-Ereignisses muss innerhalb von 30 Sekunden abgeschlossen sein, ansonsten denkt die SharePoint-Installationsinfrastruktur, dass ein Fehler aufgetreten ist. Die Infrastruktur führt das Ereignis erneut aus und wiederholt den Code von Anfang an, bis zu drei weitere Male. Nach vier Zeitüberschreitungen setzt SharePoint die gesamte Add-In-Installation zurück. Die vollständigen Auswirkungen dieser Tatsachen werden in Einbeziehen von Rollbacklogik und „Bereits erledigt“-Logik im Add-In-Ereignishandler beschrieben.

AppUninstalling-Ereignis

Das AppUninstalling-Ereignis wird nicht ausgeführt, wenn das Add-In aus dem Hostweb entfernt wird. Durch Entfernen eines Add-Ins wird das Add-In nur in den Papierkorb des Benutzers verschoben. Bevor das AppUninstalling-Ereignis ausgelöst wird, sind zwei weitere Schritte erforderlich. Zuerst muss ein Benutzer das Add-In aus dem Papierkorb entfernen, wodurch es in den endgültigen Papierkorb verschoben wird. Zweitens muss ein Benutzer das Add-In aus dem papierkorb der zweiten Phase entfernen. Diese letzte Aufgabe löst das AppUninstalling-Ereignis aus. Das AppUninstalling-Ereignis erfolgt synchron und kann zum Abbrechen der Deinstallation verwendet werden, durch die das Add-In im endgültigen Papierkorb belassen werden würde.

Die Hauptfunktion eines Handlers für dieses Ereignis besteht darin, Elemente zu löschen oder wiederzuverwenden, die mit einem AppInstalled-Ereignis (oder einem AppUpdated-Ereignis) bereitgestellt wurden. SharePoint kann nicht diese Elemente nicht löschen oder sie in den Papierkorb verschieben, da diese Elemente für SharePoint nicht bekannt sind, zumindest nicht als Komponenten des Add-Ins. Es bietet sich in der Regel an, diese Elemente zu löschen. Es sollten aber keine Elemente gelöscht werden, die noch nützlich sein können, auch nachdem das Add-In verschwunden ist: Wenn eine Liste oder Website, die von Ihrem AppInstalled-Handler erstellt wurde, noch verwendet wird, löschen Sie diese nicht in Ihrem AppUninstalling-Handler.

AppUpgraded-Ereignis

Das AppUpgraded-Ereignis wird unmittelbar ausgeführt, nachdem SharePoint alle erforderlichen Vorgänge beim Aktualisieren des Add-Ins auf eine neue Version ausgeführt hat, jedoch bevor der Benutzer bemerkt, dass die Aktualisierung abgeschlossen ist. Genau wie beim AppInstalled-Ereignis handelt es sich um ein after-Ereignis, dieses ist jedoch im Wesentlichen synchron, daher empfiehlt es sich, Fehler abzufangen und SharePoint anzuweisen, das Update zurückzusetzen.

Einige Beispiele für mögliche Aktionen eines Handlers für dieses Ereignis:

• Hinzufügen, Ändern oder Entfernen von Add-In-Komponenten aus dem Hostweb.

• Führen Sie Aktionen im Add-In-Web aus, die mit der deklarativen Updatesemantik in einem Add-In-Webfeature nicht möglich sind. Sie können zum Beispiel keine Elemente mit dem deklarativen Updatemarkup löschen, dies ist jedoch programmgesteuert in einem AppUpgraded-Handler möglich.

• Ändern App-Instanz-relativer Komponenten in der Webanwendung oder Remotedatenbank des Add-Ins.

Ausführliche Anweisungen zum Erstellen von Add-In-Ereignishandlern finden Sie unter Erstellen eines Add-In-Ereignisempfängers in SharePoint-Add-Ins.

Einbeziehen von Rollbacklogik und „Bereits erledigt“-Logik in Add-In-Ereignishandler

Wenn SharePoint Fehler beim Verarbeiten eines der drei Add-In-Ereignisse feststellt, wird das Ereignis abgebrochen, und alle Änderungen, die in Verbindung mit dem Ereignis vorgenommen wurden, werden zurückgesetzt. Die Add-In-Ereignishandler müssen in dieses System integriert werden, da Sie, wenn der Teil des Ereignisses, das Sie implementieren, fehlschlägt, das gesamte Ereignis zurücksetzen möchten, anstatt fortzufahren und alles in einem möglicherweise beschädigten Zustand zu hinterlassen. Die folgenden Aufgaben muss Ihr Handler in der Regel ausführen:

• SharePoint benachrichtigen, dass ein Fehler aufgetreten ist. Die SOAP-Nachricht, die Ihr Add-In-Ereignishandler an SharePoint zurückgibt, weist eine Status-Eigenschaft auf, die die Werte Continue, CancelWithError, oder CancelWithoutError aufweisen kann. Jeder Cancel-Status weist SharePoint an, das Ereignis zurückzusetzen.

• Zurücksetzen, was der Handler bereits ausgeführt hat, bevor im Handler ein Fehler auftritt. SharePoint kann dies in der Regel nicht für Sie ausführen, da es nicht weiß, welche Aufgaben Ihr Handler ausgeführt hat. Dies ist keine universelle Regel. Wenn eine Add-In-Installation beispielsweise abgebrochen wird, löscht SharePoint das gesamte Add-In-Web, es macht also keinen Sinn, dass ein AppInstalled-Ereignishandler die Vorgänge zurücksetzt, die er im Add-In-Web ausgeführt hat. In der Regel sollten aber alle Vorgänge zurückgesetzt werden, die im Hostweb oder für Remotekomponenten des Add-Ins ausgeführt wurden.

Hinweis

Die vorherigen Punkte gelten für das AppUninstalling-Ereignis sowie für die anderen beiden Add-In-Ereignisse. Wenn Ihr Handler für das Deinstallieren von Ereignissen beispielsweise eine Zeile in einer Remotedatenbank löscht und dann auf einen Fehler stößt, muss die Zeile wiederhergestellt werden. Da der Dienst eine Abbruchmeldung an SharePoint sendet, wird das Add-In nicht aus dem Papierkorb entfernt. Wenn es von dort aus wiederhergestellt und erneut verwendet wird, kann es möglicherweise nicht ohne diesen Datenbankeintrag arbeiten. Der AppUninstalling-Handler wird jedoch abgeschlossen, bevor SharePoint das Add-In aus dem Papierkorb entfernt. Wenn SharePoint daher selbst einen Fehler feststellt und das Entfernen abbrechen muss, gibt es keine Möglichkeit für den Handler, ausgeführte Aktionen rückgängig zu machen.

Wenn SharePoint nicht innerhalb von 30 Sekunden eine Ergebnisnachricht von Ihrem Handler empfängt, wird der Handler erneut aufgerufen. Der Vorgang wird vollständig abgebrochen, und das Ereignis wird nach drei Wiederholungen (insgesamt vier Versuche) zurückgesetzt. Bei jedem Aufrufen des Handlers beginnt der Code wieder von vorne. Sie möchten aber in der Regel nicht, dass Ihr Handler Vorgänge, die bereits ausgeführt wurden, wiederholt, z. B. das Erstellen einer Liste im Hostweb, und Sie können nicht wissen, ob Ihre Rollbacklogik abgeschlossen oder ausgelöst wurde, bevor eine Zeitüberschreitung beim Handler auftrat. Aus diesem Grund sollte Ihre Handlerlogik keine Aktion ausführen, ohne zuerst zu überprüfen, ob die Aktion bereits ausgeführt wurde, es sei denn, dies würde keinen Schaden anrichten.

Installations- und Aktualisierungsfehler können auf der SharePoint-Benutzeroberfläche angezeigt werden, wie in der folgenden Abbildung dargestellt.

Abrufen von Details für Installationsfehler

Strategien für die Architektur von Add-In-Ereignishandlern

Ausgedrückt in Pseudocode sollte Ihr Handler in der Regel etwa wie folgt aufgebaut sein. Tritt ein Fehler im Abschnitt "Try" auf, sollte der Abschnitt "Catch" und "Rollback" aufgerufen werden. (Dies kann je nach Sprache und Framework automatisch erfolgen.)

Try
    If X not already done,
        Do X.
Catch
    Send cancel message to SharePoint.
    If X not already undone,
        Undo X.

Durch Implementieren der Rollback- und „Bereits erledigt“-Logik in Ihrem Webdienst kann der Handler jedoch verlangsamt werden. Sowohl die Installations- als auch die Rollbacklogik nehmen in der Regel Änderungen an Remoteelementen des Webdiensts vor, z. B. am SharePoint-Hostweb oder an einer Back-End-Datenbank. Wenn Ihre Installations- und Rollbacklogik zwischen den Try- und Catch-Abschnitten aufgeteilt ist, tätigt der Dienst separate Aufrufe zu den Remotekomponenten, häufig mehrere solcher Aufrufe in jedem Abschnitt.

Die bewährte Methode besteht in der Regel darin, die Installations- und Rollbacklogik in den Remotekomponenten selbst in einem Verfahren zu implementieren, die von Ihrem Handler im Try-Abschnitt aufgerufen werden kann. Das Verfahren sollte eine Erfolgs- oder Fehlermeldung zurückgeben. Wenn ein Fehler zurückgegeben wird, ruft Code in Ihrem Try-Abschnitt den Catch-Abschnitt auf (z. B. durch Auslösen einer Ausnahme). Die einzige Aufgabe, die der Catch-Abschnitt hat, ist das Benachrichtigen von SharePoint. Wir bezeichnen dies als die Handlerdelegierungsstrategie. Der folgende Pseudocode zeigt die Strategie:

Try
    Call the "Do X" procedure on remote platform.
    If remote platform reports failure, call Catch.
Catch
    Send cancel message to SharePoint.

Die Prozedur „Do X“ selbst, die auf dem Remotesystem ausgeführt wird, enthält die Rollback- und „Bereits erledigt“-Logik, wie die folgende.

Try
    If X not already done,
        Do X.
        Set success flag to true.
Catch
    If X was done before error,
        Undo X.
    Set success flag to false.
Send
    Return success flag to the event handler.

Wenn der Handler z. B. eine Aktion in einer SQL Server-Datenbank ausführen muss, können Sie auf dem SQL-Server eine gespeicherte Prozedur mit einem TRY-CATCH-Block für die Logik zum Zurücksetzen der Installation und mit IF-ELSE-Blöcken zum Implementieren von „Bereits erledigt“-Logik installieren.

Das SharePoint-Add-In-Modell bietet keine Möglichkeit, benutzerdefinierten serverseitigen Code in SharePoint zu speichern und diesem über das CSOM (clientseitige Objektmodell) aufzurufen. Das CSOM bietet jedoch eine Möglichkeit, try-catch- und if-then-else-Logik zu bündeln und zur Ausführung an den Server zu senden.

Ein detailliertes Beispiel eines Add-In-Ereignishandlers, der die Handlerdelegierungsstrategie verwendet, um eine Liste zu einem Hostweb hinzuzufügen, finden Sie unter Erstellen eines Add-In-Ereignisempfängers in SharePoint-Add-Ins. Ein Codebeispiel finden Sie unter SharePoint/PnP/Samples/Core.AppEvents.HandlerDelegation.

Sie können nicht immer die Handlerdelegierungsstrategie verwenden. Wenn Ihr Handler beispielsweise mehrere Komponenten aufruft, z. B. eine Datenbank und das SharePoint-Hostweb, besteht die Möglichkeit, dass eine erfolgreich ausgeführt wird und die andere fehlschlägt. In diesem Szenario wird die Rollbacklogik der ersten Komponente nicht ausgeführt, wenn Sie diese mit der Handlerdelegierungsstrategie entwickelt haben. Wenn Sie die Komponenten synchron aufrufen, kann aus diesem Grund nur die zuletzt aufgerufene die Handlerdelegierungsstrategie verwenden. Wenn sie asynchron aufgerufen werden, können Sie diese Strategie nicht verwenden.

Ein Beispiel für einen Add-In-Ereignishandler, der die Handlerdelegierungsstrategie nicht verwendet, finden Sie unter SharePoint/PnP/Samples/Core.AppEvents.

Tipp

Wenn das AppInstalled-Ereignis fehlschlägt, löscht SharePoint das Add-In-Web, sofern vorhanden. Wenn das AppUpated-Ereignis fehlschlägt, stellt SharePoint das Add-In-Web mit dem Zustand vor der Aktualisierung wieder her. Aus diesem Grund müssen die Handler nie Aktionen zurücksetzen, die im Add-In-Web vorgenommen wurden. Wenn Ihr Handler Aktionen sowohl im Hostweb als auch im Add-In-Web ausführt, sollte zuerst das Add-In-Web verarbeitet werden. Auf diese Weise kann die Handlerdelegierungsstrategie sicher für das Hostweb verwendet werden. Auch wenn die Add-In-Webaktionen erfolgreich ausgeführt werden und die Hostwebaktionen fehlschlagen, wird die gesamte Rollbacklogik ausgeführt.

Remoteereignisempfänger in Add-Ins, die mehrere Sicherheitszonen unterstützen

Es gibt einige Einschränkungen beim Entwerfen von Add-Ins, die mehrere Sicherheitszonen unterstützen und über einen Remoteereignisempfänger verfügen.

Häufig gestellte Fragen zu Remoteereignisempfängern

Im Folgenden finden Sie häufig gestellte Fragen, die Sie möglicherweise im Umgang mit Remote-Ereignisempfängern haben.

Wie unterscheiden sich Remote-Ereignisempfänger von Ereignisempfängen in SharePoint 2010?

In SharePoint 2010 behandeln Ereignisempfänger Ereignisse, die in SharePoint-Listen, -Websites und anderen SharePoint-Objekten vorkommen, indem der Code auf dem SharePoint-Server ausgeführt wird (voll vertrauenswürdig oder in einem Sandkasten). Diese Art von Ereignisempfänger ist in SharePoint immer noch vorhanden. SharePoint unterstützt jedoch auch Remoteereignisempfänger, in denen der Code, der ausgeführt wird, wenn das Ereignis ausgelöst wird, von einem Webdienst gehostet wird. Wenn Sie also einen Remoteereignisempfänger registrieren, müssen Sie SharePoint auch anweisen, welcher Webdienst aufgerufen werden soll.

In den folgenden Codebeispielen implementiert das erste Beispiel (SharePoint-Lösungen) Funktionalität mit einem Ereignishandler. Das zweite Beispiel (SharePoint-Add-Ins) implementiert die gleiche Funktionalität mithilfe eines Remoteereignisempfängers.

SharePoint-Lösungen

    // Trigger an event when an item is added to the SharePoint list.
    Public class OnPlantUpdated : SPItemEventReceiver
    {
    Public override void ItemAdding (SPItemEventProperties properties)
    {
    Properties.After.Properties.ChangedProperties.Add("Image",CreateLink(properties));
    Properties.status =SPEventReceiverStatus.Continue;
    }

    /// When an item updates, run the following.
    Public override void ItemUpdating(SPItemEventProperties properties)
    {
    Properties.AfterProperties.ChangedProperties.Add("Image",CreateLink9properties));
    Properties.Status= SPEventReceiverStatus.Continue;
    }

SharePoint-Add-Ins

    /* Trigger an event when an item is added to the SharePoint list*/
    Public class OnPlantUpdated : IRemoteEventService
    {
    public SPRemoteEventResult ProcessEvent (SPRemoteEventProperties properties)
    {
    SPRemoteEventResult result =new SPRemoteEventResult();
    If (properties.EventType == SPRemoteEventType.ItemAdding ||  
                properties.EventType == SPRemoteEventType.ItemUpdating)
    {
    // Add code that runs when an item is added or updated.
    }

Das vollständige Codebeispiel finden Sie unter Hinzufügen von Listenelementeigenschaften mit einem Remoteereignisempfänger.

Eine ausführliche Demonstration des Codebeispiels finden Sie unter Migrieren eines SharePoint-Ereignisempfängers in einen Remote-Ereignisempfänger

Weitere Informationen finden Sie unter SPRemoteEventType-Enumeration.

Wie funktionieren Remoteereignisempfänger?

Die folgende Abbildung zeigt, wie Remoteereignisempfänger funktionieren:

• Der Benutzer führt eine Aktion in SharePoint aus (z. B. bearbeitet ein Listenelement).

• SharePoint kommuniziert dann mit dem registrierten Webdienst. Sie können einige Vorgänge ausführen, z. B. eine Listenelementeigenschaft aktualisieren oder ein Back-End-System aktualisieren.

• Der Webdienst kann auch mit dem Zugriffssteuerungsdienst kommunizieren, um sein eigenes signiertes Token anzufordern, um den Rückruf an SharePoint auszuführen. Mit diesem Token können Sie aufgrund des vorherigen Vorgangs zu dem Listenelement oder im Backend-System Remote-Aktionen aus dem Webdienst ausführen.

  Funktionsweise von Emote-Ereignisempfängern in SharePoint

  

Wie werden Remoteereignisempfänger gedebuggt?

Siehe Debugging und Problembehandlung eines Remoteereignisempfängers in einem Add-In für SharePoint

Kann ich clientseitigen Code (JavaScript) aus Remoteereignisempfängern ausführen?

Nein, Sie können clientseitigen Code (JavaScript) nicht aus Remoteereignisempfängern ausführen?

Gibt es Einschränkungen dazu, wo ein Remoteereignisempfänger oder seine eigene URL gehostet werden kann?

Der Remoteereignisempfänger kann in der Cloud oder auf einem lokalen Server gehostet werden, der nicht auch als SharePoint-Server verwendet wird. Die URL eines Produktionsempfängers kann keinen bestimmten Port angeben. Dies bedeutet, dass Sie entweder Port 443 für HTTPS verwenden müssen (empfohlen) oder Port 80 für HTTP. Wenn Sie HTTPS verwenden und der Empfänger lokal ist, das Add-In sich jedoch in SharePoint Online befindet, muss der Hostserver über ein öffentlich vertrauenswürdiges Zertifikat von einer Zertifizierungsstelle verfügen. (Ein selbst signiertes Zertifikat funktioniert nur, wenn sich das Add-In in einer lokalen SharePoint-Farm befindet.)

Funktioniert ein SharePoint 2010-Ereignishandler in SharePoint nach dem Upgrade?

Wenn ein SharePoint 2010-Lösungspaket mit einem Ereignishandler auf SharePoint aktualisiert wird, funktioniert das Lösungspaket in Abhängigkeit von Ihren Anpassungen möglicherweise ohne jegliche Änderungen. Dies schließt auch die Ereignishandler ein. Wenn die SharePoint 2010-Lösung in ein SharePoint-Add-In in SharePoint umgestaltet wird, sollte der Ereignishandler als Remoteereignisempfänger umgeschrieben werden. Siehe Migrieren eines SharePoint-Ereignisempfängers in einen Remoteereignisempfänger.

Siehe auch

• Erstellen eines Remoteereignisempfängers in SharePoint-Add-Ins
• Erstellen eines Add-In-Ereignisempfängers in SharePoint-Add-Ins
• Debugging und Problembehandlung eines Remoteereignisempfängers in einem SharePoint-Add-In
• Entwickeln von SharePoint-Add-Ins