Verwenden von Remoteereignisempfängern in SharePoint

Die SharePoint-Add-In-Teile dieses Artikels sind Legacy-Anleitungen. Die unten stehende Außerbetriebnahme zieht die anderen APIs oder Plattformen, die hier erläutert werden, nicht außer Betrieb.

Wichtig

SharePoint-Add-Ins haben am 2. April 2026 das Ende der Lebensdauer in SharePoint Online erreicht. Sowohl von SharePoint als auch vom Anbieter gehostete Add-Ins werden eingestellt und funktionieren nicht mehr in SharePoint Online, einschließlich Government-Clouds. Die Hinweise zu Add-Ins-Entwicklung, -Bereitstellung und -Verwendung werden als historische Referenz und für anwendbare SharePoint Server-Szenarien beibehalten, nicht für neue SharePoint Online-Lösungen.

SharePoint Server-Add-Ins, die über einen lokalen App-Katalog bereitgestellt werden, werden durch diese Änderung nicht zurückgezogen. Der Erwerb von SharePoint-Add-Ins aus dem öffentlichen Marketplace endete am 2. April 2026 für SharePoint Server.

Mit dieser Einstellung werden SharePoint-REST-APIs, CSOM, JSOM oder SharePoint-Framework (SPFx) nicht außer Betrieb genommen. Verwenden Sie für SharePoint Online SPFx für Benutzeroberflächenerweiterungen und Microsoft Entra ID für die Authentifizierung bei externen Anwendungen. Weitere Informationen finden Sie in der Ankündigung der Einstellung und in der Anleitung zur Add-In-Migration.

Verwenden Sie Remoteereignisempfänger für die Behandlung von Ereignissen im SharePoint-Add-In-Modell. Verwenden Sie die Ereignisse AppInstalled und AppUninstalling, um SharePoint-Objekte und andere Ereignisempfänger, die Ihr Add-In benötigt, einzurichten oder zu entfernen.

Gilt für: Add-Ins für SharePoint | SharePoint 2013 | SharePoint Online

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.

Das Core.EventReceivers-Beispiel zeigt, wie ein vom Anbieter gehostetes Add-In mit einem Remoteereignisempfänger verwendet wird, um die AppInstalled- und AppUninstalling-Ereignisse zu verarbeiten. Die Ereignisse AppInstalled und AppUninstalling richten SharePoint-Objekte, die das Add-In bei seiner Ausführung verwendet, ein und entfernen diese. Darüber hinaus fügt der AppInstalled-Ereignishandler den ItemAdded-Ereignishandler zu einer Liste hinzu. Verwenden Sie diese Lösung, wenn Sie die folgenden Aufgaben ausführen möchten:

  • Konfigurieren des Add-Ins bei der ersten Ausführung mit dem AppInstalled-Ereignis für das Einrichten verschiedener SharePoint-Objekte oder zusätzlicher Ereignisempfänger, die das Add-In verwendet.
  • Ersetzen von Ereignisempfängern, die mit Lösungen mit voll vertrauenswürdigen Code implementiert sind. In Lösungen mit voll vertrauenswürdigem Code können Sie Ereignisempfänger auf dem SharePoint-Server ausführen. Da Sie im neuen SharePoint-Add-In-Modell den Ereignisempfänger nicht auf dem SharePoint-Server ausführen können, müssen Sie einen Remoteereignisempfänger auf einem Webserver implementieren.
  • Erhalten von Benachrichtigungen über Änderungen in SharePoint. Beispielsweise möchten Sie eine Aufgabe ausführen, wenn einer Liste ein neues Element hinzugefügt wird.
  • Vervollständigen Ihrer Änderungsprotokolllösung. Die Verwendung des Remote-Ereignisempfängermusters mit einem Änderungsprotokollmuster bietet eine zuverlässigere Architektur für die Behandlung aller Änderungen, die an SharePoint-Inhaltsdatenbanken, -Websitesammlungen, -Websites oder -Listen vorgenommen werden. Remote-Ereignisempfänger werden sofort ausgeführt, aber da sie auf einem Remoteserver ausgeführt werden, tritt möglicherweise ein Kommunikationsfehler auf. Das Änderungsprotokollmuster stellt sicher, dass alle Änderungen für die Verarbeitung verfügbar sind, die Anwendung, die die Änderungen verarbeitet, wird jedoch in der Regel anhand eines Zeitplans ausgeführt (z. B. ein Zeitgeberauftrag). Dies bedeutet, dass Änderungen nicht sofort verarbeitet werden. Wenn Sie diese beiden Muster gemeinsam verwenden, stellen Sie sicher, dass Sie einen Mechanismus verwenden, durch den verhindert wird, dass dieselbe Änderung zweimal verarbeitet wird. Weitere Informationen finden Sie unter Abfragen des SharePoint-Änderungsprotokolls mit ChangeQuery und ChangeToken.

Hinweis

Von SharePoint gehostete Add-Ins unterstützen keine Remoteereignisempfänger. Wenn Sie Remoteereignisempfänger verwenden möchten, müssen Sie ein vom Anbieter gehostetes Add-In verwenden. Sie sollten Remoteereignisempfänger nicht für Synchronisierungsszenarien oder lange ausgeführte Prozesse verwenden. Weitere Informationen finden Sie unter Gewusst wie: Erstellen eines Add-In-Ereignisempfängers.

Bevor Sie beginnen

Laden Sie zunächst das Core.EventReceivers-Beispiel-Add-In aus dem Office 365-Projekt "Patterns and Practices" auf GitHub herunter.

Bevor Sie dieses Add-In ausführen, führen Sie folgende Schritte aus:

  1. Überprüfen Sie in den Eigenschaften für das Core.EventReceivers-Projekt, ob Handle-App Installed und App-Deinstallation auf True festgelegt sind. Wenn Sie "App installierte Handle" und "App-Deinstallation behandeln " auf "true" festlegen, wird ein WCF-Dienst erstellt, der den Ereignishandler für das Ereignis AppInstalled und AppUninstall definiert. Öffnen Sie in Core.EventReceivers das Kontextmenü (rechte Maustaste) für AppManifest.xml, und wählen Sie Eigenschaften aus. InstalledEventEndpoint und UninstallingEventEndpoint verweisen auf den Remoteereignisempfänger, der die AppInstalled- und AppUninstalling-Ereignisse verarbeitet.

  2. Das Anfügen eines Remoteereignisempfängers an ein Objekt im Hostweb erfordert in der Regel nur die Berechtigung "Verwalten " für dieses Objekt. Wenn Sie z. B. einen Ereignisempfänger an eine vorhandene Liste anfügen, benötigt das Add-In nur die Berechtigung Verwalten für die Liste. Dieses Codebeispiel erfordert Verwalten-Berechtigungen für das Web, da es eine Liste anfügt und ein Feature im Hostweb aktiviert. So legen Sie Verwaltungsberechtigungen für das Web fest:

    1. Doppelklicken Sie auf Core.EventReceivers\AppManifest.xml.

    2. Wählen Sie Berechtigungen aus.

    3. Stellen Sie sicher, dass der Bereich auf "Web" und die Berechtigung auf "Verwalten" festgelegt ist.

  3. Um dieses Codebeispiel auszuführen, benötigen Sie ein Azure-Abonnement. Informationen zur Registrierung für eine Testversion finden Sie unter Kostenlose einmonatige Testversion.

  4. Erstellen Sie einen Azure Service Bus-Namespace.

    1. Führen Sie die Anweisungen unter Erstellen eines Service Bus-Namespace aus.

    2. Kopieren Sie Primäre Verbindungszeichenfolge aus dem soeben erstellten Service Bus-Namespace.

    3. Kehren Sie zu Visual Studio zurück.

    4. Klicken Sie mit der rechten Maustaste auf Core.EventReceivers-Eigenschaften>>SharePoint.

    5. Wählen Sie Debuggen über Microsoft Azure Service Bus aktivieren aus.

    6. Fügen Sie in Microsoft Azure Service Bus Verbindungszeichenfolge die Verbindungszeichenfolge ein.

    7. Wählen Sie Speichern aus.

  5. Führen Sie das Codebeispiel aus, und führen Sie die folgenden zusätzlichen Schritte aus:

    • Klicken Sie im Fenster "Berechtigungen für die App erteilen" auf "Vertrauen".

    • Schließen Sie das Fenster Berechtigungen für die App erteilen .

    • Wenn die Installation des Add-Ins und des WCF-Diensts abgeschlossen ist, wird Ihr Browser geöffnet.

    • Melden Sie sich bei Ihrer Office 365-Website an. Die Startseite des Core.EventReceivers-Add-Ins wird angezeigt.

Verwenden des Core.EventReceivers-Add-Ins

So zeigen Sie eine Demonstration des Core.EventReceivers-Codebeispiels an:

  1. Führen Sie das Beispiel aus, und wählen Sie auf der Startseite Zurück zur Website aus.

  2. Wählen Sie Websiteinhalte.

  3. Wählen Sie Jobs für Remoteereignisempfänger aus.

  4. Wählen Sie Neues Element aus.

  5. Geben Sie unter Titelcontoso ein, und geben Sie in Beschreibungdie Zeichenfolge contoso test ein.

  6. Kehren Sie zur Liste zurück, und aktualisieren Sie die Seite.

  7. Überprüfen Sie, ob die Beschreibung des neu hinzugefügten Elements in Contoso Updated by ReR 192336, wobei 192336 ein Zeitstempel ist.

In Services/AppEventReceiver.cs implementiert AppEventReceiver die IRemoteEventService-Schnittstelle . Dieses Codebeispiel stellt eine Implementierung für die ProcessEvent-Methode bereit, da es synchrone Ereignisse verwendet. Wenn Sie asynchrone Ereignisse verwenden, müssen Sie eine Implementierung für die ProcessOneWayEvent-Methode bereitstellen.

ProcessEvent verarbeitet die folgenden SPRemoteEventType-Remoteereignisse:

  • AppInstalled-Ereignisse, wenn das Add-In installiert wird. Wenn ein AppInstalled-Ereignis auftritt, ruft ProcessEventHandleAppInstalled auf.

  • AppUninstalling-Ereignisse, wenn das Add-In deinstalliert wird. Wenn ein AppUninstalling-Ereignis auftritt, ruft ProcessEventHandleAppUninstalling auf. Das AppUninstalling-Ereignis wird nur ausgeführt, wenn ein Benutzer das Add-In vollständig entfernt, entweder durch Löschen des Add-Ins aus dem Papierkorb der Website (für Endbenutzer) oder durch Entfernen des Add-Ins aus der Liste der getesteten Apps (für Entwickler).

  • ItemAdded-Ereignisse, wenn ein Element zu einer Liste hinzugefügt wird. Wenn ein ItemAdded-Ereignis auftritt, ruft ProcessEventHandleItemAdded auf.

Hinweis

In den Projekteigenschaften Core.EventReceiver sind nur die Eigenschaften "App installierte handhaben " und "App-Deinstallation handhaben " verfügbar. Dieses Codebeispiel zeigt, wie Sie den ItemAdded-Ereignishandler zu einer Liste im Hostweb mithilfe des AppInstalled-Ereignisses während der Add-In-Installation hinzufügen können.

Hinweis

Der Code in diesem Artikel wird wie besehen und ohne jegliche Garantie zur Verfügung gestellt, gleich ob ausdrücklich oder konkludent, einschließlich jedweder stillschweigenden Gewährleistung der Eignung für einen bestimmten Zweck, Marktgängigkeit oder Nichtverletzung von Rechten.

public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
        {

            SPRemoteEventResult result = new SPRemoteEventResult();

            switch (properties.EventType)
            {
                case SPRemoteEventType.AppInstalled:
                    HandleAppInstalled(properties);
                    break;
                case SPRemoteEventType.AppUninstalling:
                    HandleAppUninstalling(properties);
                    break;
                case SPRemoteEventType.ItemAdded:
                    HandleItemAdded(properties);
                    break;
            }


            return result;
        }

HandleAppInstalled ruft RemoteEventReceiverManager.AssociateRemoteEventsToHostWeb in RemoteEventReceiverManager.cs auf.

 private void HandleAppInstalled(SPRemoteEventProperties properties)
        {
            using (ClientContext clientContext =
                TokenHelper.CreateAppEventClientContext(properties, false))
            {
                if (clientContext != null)
                {
                    new RemoteEventReceiverManager().AssociateRemoteEventsToHostWeb(clientContext);
                }
            }
        }

AssociateRemoteEventsToHostWeb erstellt oder aktiviert verschiedene SharePoint-Objekte, die das Core.EventReceivers-Add-In verwendet. Ihre Anforderungen können davon abweichen. AssociateRemoteEventsToHostWeb führt Folgendes aus:

  • Aktiviert das Pushbenachrichtigungsfeature mithilfe von Web.Features.Add.

  • Verwendet das clientContext-Objekt , um nach einer Liste zu suchen. Wenn die Liste nicht vorhanden ist, erstellt CreateJobsList die Liste. Wenn die Liste vorhanden ist, wird List.EventReceivers verwendet, um einen vorhandenen Ereignisempfänger zu suchen, dessen Name ItemAddedEvent ist.

  • Wenn der ItemAddedEvent-Ereignisempfänger nicht vorhanden ist:

    • Instanziiert ein neues EventReceiverDefinitionCreationInformation-Objekt , um den neuen Remoteereignisempfänger zu erstellen. Der ItemAdded-Ereignisempfängertyp wird zu EventReceiverDefinitionCreationInformation.EventType hinzugefügt.

    • Legt EventReceiverDefinitionCreationInformation.ReceiverURL auf die URL des AppInstalled-Remoteereignisempfängers fest.

    • Fügt der Liste mithilfe von List.EventReceivers.Add einen neuen Ereignisempfänger hinzu.

public void AssociateRemoteEventsToHostWeb(ClientContext clientContext)
        {
            // Add Push Notification feature to host web.
            // Not required but it is included here to show you
            // how to activate features.
            clientContext.Web.Features.Add(
                     new Guid("41e1d4bf-b1a2-47f7-ab80-d5d6cbba3092"),
                     true, FeatureDefinitionScope.None);


            // Get the Title and EventReceivers lists.
            clientContext.Load(clientContext.Web.Lists,
                lists => lists.Include(
                    list => list.Title,
                    list => list.EventReceivers).Where
                        (list => list.Title == LIST_TITLE));

            clientContext.ExecuteQuery();

            List jobsList = clientContext.Web.Lists.FirstOrDefault();

            bool rerExists = false;
            if (null == jobsList)
            {
                // List does not exist, create it.
                jobsList = CreateJobsList(clientContext);

            }
            else
            {
                foreach (var rer in jobsList.EventReceivers)
                {
                    if (rer.ReceiverName == RECEIVER_NAME)
                    {
                        rerExists = true;
                        System.Diagnostics.Trace.WriteLine("Found existing ItemAdded receiver at "
                            + rer.ReceiverUrl);
                    }
                }
            }

            if (!rerExists)
            {
                EventReceiverDefinitionCreationInformation receiver =
                    new EventReceiverDefinitionCreationInformation();
                receiver.EventType = EventReceiverType.ItemAdded;

                // Get WCF URL where this message was handled.
                OperationContext op = OperationContext.Current;
                Message msg = op.RequestContext.RequestMessage;
                receiver.ReceiverUrl = msg.Headers.To.ToString();

                receiver.ReceiverName = RECEIVER_NAME;
                receiver.Synchronization = EventReceiverSynchronization.Synchronous;

                // Add the new event receiver to a list in the host web.
                jobsList.EventReceivers.Add(receiver);
                clientContext.ExecuteQuery();

                System.Diagnostics.Trace.WriteLine("Added ItemAdded receiver at " + receiver.ReceiverUrl);
            }
        }

Wenn der Liste der Remote Event Receiver-Aufträge ein Element hinzugefügt wird, behandelt ProcessEvent in AppEventReceiver.svc.cs das ItemAdded-Ereignis und ruft dann HandleItemAdded auf. HandleItemAdded ruft RemoteEventReceiverManager.ItemAddedToListEventHandler auf. ItemAddedToListEventHandler ruft das Listenelement ab, das hinzugefügt wurde, und fügt die Zeichenfolge Updated by ReR zu der Beschreibung des Listenelements hinzu.

 public void ItemAddedToListEventHandler(ClientContext clientContext, Guid listId, int listItemId)
        {
            try
            {
                List photos = clientContext.Web.Lists.GetById(listId);
                ListItem item = photos.GetItemById(listItemId);
                clientContext.Load(item);
                clientContext.ExecuteQuery();

                item["Description"] += "\nUpdated by RER " +
                    System.DateTime.Now.ToLongTimeString();
                item.Update();
                clientContext.ExecuteQuery();
            }
            catch (Exception oops)
            {
                System.Diagnostics.Trace.WriteLine(oops.Message);
            }

        }

Siehe auch