Erstellen eines Remoteereignisempfängers in Add-Ins für SharePoint

Artikel
04/08/2023

Es ist hilfreich, wenn Sie sich zunächst mit vom Anbieter gehosteten SharePoint-Add-Ins vertraut machen. Außerdem sollten Sie ein paar Add-Ins entwickelt haben, die über das Niveau von „Hello World“ hinausgehen. Weitere Informationen finden Sie unter Erste Schritte beim Erstellen von von einem Anbieter gehosteten SharePoint-Add-Ins.

Darüber hinaus sollten Sie mit dem Behandeln von Ereignissen in SharePoint-Add-Ins vertraut sein.

Erstellen eines Remoteereignisempfängers

In diesem Artikel wird gezeigt, wie Sie eine SharePoint-Add-In durch Hinzufügen eines Remoteereignisempfängers (RER) erweitern, der das ItemAdded-Ereignis für eine benutzerdefinierte Liste im Add-In-Web verarbeitet. Der RER ist im Add-In-Web mit deklarativem Markup registriert. RERs werden programmgesteuert beim Hostweb registriert. Ein entsprechendes Codebeispiel finden Sie unter SharePoint/PnP/Samples/Core.EventReceivers.

Ein RER muss ein SOAP-Webdienst sein. Im fortlaufenden Beispiel wird dies als WCF-Dienst (Windows Communication Foundation) implementiert, aber es ist grundsätzlich möglich, eine RER auf einem Nicht-Microsoft-Stapel zu implementieren.

Um diesen Artikel zu befolgen und den Code selbst einzugeben, laden Sie das Beispiel unter SharePoint-Add-in-CSOM-BasicDataOperations herunter, und öffnen Sie das Beispiel dann in Visual Studio.

Hinweis

In diesem Beispiel wird eine Datei TokenHelper.cs verwendet, die von Office Developer Tools für Visual Studio generiert wird. Bei Erstellung des Beispiels war dies die aktuelle Version, aber wenn Sie diesen Artikel lesen, ist dies möglicherweise nicht die aktuellste Version. Das Beispiel ist weiterhin hervorragend für das Erstellen Ihrer ersten RER geeignet. Wenn Sie jedoch bereit sind, darüber hinauszugehen, sollten Sie sich die Beispiele ansehen, die im Abschnitt Siehe auch am Ende dieses Artikels aufgeführt sind. Sie werden mit größerer Wahrscheinlichkeit auf dem neuesten Stand gehalten.

So registrieren Sie einen Remoteereignisempfänger

Öffnen Sie das SharePoint-Add-In-Projekt in Visual Studio.
Wählen Sie im Projektmappen-Explorer den Knoten des Add-In-Projekts aus.
Wählen Sie auf der Menüleiste Projekt>Neues Element hinzufügen aus.
Wählen Sie im Bereich Installierte Vorlagen den Knoten Office/SharePoint aus.
Wählen Sie im Bereich Vorlagen die Vorlage Remoteereignisempfänger aus.
Lassen Sie den Standardnamen im Feld Name unverändert (RemoteEventReceiver1), und wählen Sie dann Hinzufügen aus.
Wählen Sie in der Liste Welchen Typ soll der Ereignisempfänger aufweisen? die Option Listenelementereignisse aus.
Wählen Sie in der Liste Welches Element soll als Ereignisquelle dienen? die Option Benutzerdefinierte Liste aus.

Im fortlaufenden Beispiel wird eine benutzerdefinierte generische Liste verwendet. Aber ein RER kann auch Ereignisse behandeln, die in SharePoint-Standardlisten auftreten, beispielsweise Ankündigungen oder Kontakte.
Wählen Sie in der Liste Die folgenden Ereignisse behandeln die Option Ein Element wird hinzugefügt aus, und klicken Sie anschließend auf Fertig stellen.

Der Webanwendung wird ein Webdienst zur Behandlung des von Ihnen angegebenen Remoteereignisses hinzugefügt. Dem SharePoint-Add-In wird ein Remoteereignisempfänger hinzugefügt, und auf das Listenelementereignis wird in der Elements.xml Datei des Empfängers verwiesen, die selbst im Add-In-Webfeature enthalten ist.

So erstellen Sie die Liste

Wählen Sie im Projektmappen-Explorer den Knoten des Add-In-Projekts aus.
Wählen Sie auf der Menüleiste Projekt>Neues Element hinzufügen aus.
Wählen Sie im Bereich Installierte Vorlagen den Knoten Office/SharePoint aus.
Wählen Sie im Bereich Vorlagen die Vorlage Liste aus.
Lassen Sie den Standardnamen im Feld Name unverändert (List1), und wählen Sie dann Hinzufügen aus.
Aktivieren Sie das Optionsfeld Listeninstanz basierend auf einer bestehenden Listenvorlage erstellen, wählen Sie in der Liste Benutzerdefinierte Liste aus, und klicken Sie auf Fertig stellen.

So fügen Sie dem Remoteereignisempfänger Funktionen hinzu

Wenn sich Ihre SharePoint-Testfarm nicht auf demselben Computer befindet, auf dem Visual Studio ausgeführt wird (oder Sie einen SharePoint Online-Mandanten als SharePoint-Testwebsite verwenden), konfigurieren Sie das Projekt für das Debuggen mithilfe der Microsoft Azure Service Bus. Weitere Informationen finden Sie unter Debuggen und Problembehandlung eines Remoteereignisempfängers in einem SharePoint-Add-In.

In the code file for the service of the remote event receiver (that is, RemoteEventReceiver1.svc.cs), replace the contents with the following code. Dieser Code führt die folgenden Aufgaben aus:

Er ruft ein gültiges Clientkontextobjekt ab.
Wenn nicht bereits eine Liste mit dem Namen EventLog vorhanden ist, erstellt er eine für die Namen der auftretenden Remoteereignisse.
Er fügt der Liste einen Eintrag für das Ereignis hinzu, einschließlich Uhrzeit- und Datumsstempel.

Hinweis

Zum Zeitpunkt der Erstellung dieses Artikels enthielten die Office-Entwicklertools für Visual Studio Verweise auf alle erforderlichen Assemblys, wenn der Empfänger erstellt wurde, aber in späteren Versionen der Tools nicht. Wenn Compilerfehler auftreten, fügen Sie einfach die fehlenden Verweise hinzu. Sie müssen z. B. Verweise auf System.ServiceModel oder System.ComponentModel.DataAnnotations hinzufügen.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Text;
using Microsoft.SharePoint.Client;
using Microsoft.SharePoint.Client.EventReceivers;
using System.Runtime.Serialization;
using System.ServiceModel;
using System.ServiceModel.Channels;

namespace BasicDataOperationsWeb.Services
{
    public class RemoteEventReceiver1 : IRemoteEventService
    {
        public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
        {
            // When a "before" event occurs (such as ItemAdding), call the event 
            // receiver code.
            ListRemoteEventReceiver(properties);
            return new SPRemoteEventResult();
        }

        public void ProcessOneWayEvent(SPRemoteEventProperties properties)
        {
            // When an "after" event occurs (such as ItemAdded), call the event 
            // receiver code.            
        }

        public static void ListRemoteEventReceiver(SPRemoteEventProperties properties)
        {
            string logListTitle = "EventLog";

            // Return if the event is from the EventLog list itself. Otherwise, it may go into
            // an infinite loop.
            if (string.Equals(properties.ItemEventProperties.ListTitle, logListTitle, 
                StringComparison.OrdinalIgnoreCase))
                return;

            // Get the token from the request header.
            HttpRequestMessageProperty requestProperty = 
                (HttpRequestMessageProperty)OperationContext
                .Current.IncomingMessageProperties[HttpRequestMessageProperty.Name];
            string contextTokenString = requestProperty.Headers["X-SP-ContextToken"];

            // If there is a valid token, continue.
            if (contextTokenString != null)
            {
                SharePointContextToken contextToken =
                    TokenHelper.ReadAndValidateContextToken(contextTokenString, 
                        requestProperty.Headers[HttpRequestHeader.Host]);

                Uri sharepointUrl = new Uri(properties.ItemEventProperties.WebUrl);
                string accessToken = TokenHelper.GetAccessToken(contextToken, 
                                                    sharepointUrl.Authority).AccessToken;
                bool exists = false;

                // Retrieve the log list "EventLog" and add the name of the event that occurred
                // to it with a date/time stamp.
                using (ClientContext clientContext = 
                    TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), 
                                                                                                        accessToken))
                {
                    clientContext.Load(clientContext.Web);
                    clientContext.ExecuteQuery();
                    List logList = clientContext.Web.Lists.GetByTitle(logListTitle);

                    try
                    {
                        clientContext.Load(logList);
                        clientContext.ExecuteQuery();
                        exists = true;
                    }

                    catch (Microsoft.SharePoint.Client.ServerUnauthorizedAccessException)
                    {
                        // If the user doesn't have permissions to access the server that's 
                        // running SharePoint, return.
                        return;
                    }

                    catch (Microsoft.SharePoint.Client.ServerException)
                    {
                        // If an error occurs on the server that's running SharePoint, return.
                        exists = false;
                    }

                    // Create a log list called "EventLog" if it doesn't already exist.
                    if (!exists)
                    {
                        ListCreationInformation listInfo = new ListCreationInformation();
                        listInfo.Title = logListTitle;
                        // Create a generic custom list.
                        listInfo.TemplateType = 100;
                        clientContext.Web.Lists.Add(listInfo);
                        clientContext.Web.Context.ExecuteQuery();
                    }

                    // Add the event entry to the EventLog list.
                    string itemTitle = "Event: " + properties.EventType.ToString() + 
                        " occurred on: " + 
                        DateTime.Now.ToString(" yyyy/MM/dd/HH:mm:ss:fffffff");
                    ListCollection lists = clientContext.Web.Lists;
                    List selectedList = lists.GetByTitle(logListTitle);
                    clientContext.Load<ListCollection>(lists);
                    clientContext.Load<List>(selectedList);
                    ListItemCreationInformation listItemCreationInfo = 
                        new ListItemCreationInformation();
                    var listItem = selectedList.AddItem(listItemCreationInfo);
                    listItem["Title"] = itemTitle;
                    listItem.Update();
                    clientContext.ExecuteQuery();
                }
            }
        }
    }
}

Ändern Sie in „Home.aspx.cs“ alle Instanzen von SPHostUrl in SPAppWebUrl.

Beispielsweise sollte sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]); in sharepointUrl = new Uri(Request.QueryString["SPAppWebUrl"]); geändert werden.

Ausführen und Testen des Ereignishandlers

Testen Sie den Handler mit dem folgenden Verfahren.

Drücken Sie F5, um das Projekt auszuführen.
Vertrauen Sie dem Add-In, wenn Sie dazu aufgefordert werden. Ihre SharePoint-Add-In wird ausgeführt, und eine Tabelle mit verfügbaren Listen wird angezeigt und enthält List1.
Wählen Sie die ID von List1 aus. Die ID wird in das Feld Listenelemente abrufen kopiert.
Wählen Sie die Schaltfläche Listenelemente abrufen aus. List1 wird ohne Elemente angezeigt.
Geben Sie im Feld Element hinzufügendie Option First Item (Erstes Element) an, und wählen Sie dann die Schaltfläche Element hinzufügen aus. Ein Listeneintrag mit dem Namen Erstes Element wird der Liste List1 hinzugefügt, was dazu führt, dass der Remoteereignisempfänger ausgelöst wird und einen Eintrag im Ereignisprotokoll ("EventLog") hinzufügt.
Wählen Sie die Schaltfläche Listen aktualisieren aus, um zum Listenverzeichnis zurückzukehren. In der Tabelle wird eine neue Liste mit dem Namen EventLog angezeigt.
Wählen Sie den ListID GUID-Wert für EventLog und dann die Schaltfläche Listenelemente abrufen aus. Eine Tabelle für EventLog wird mit einem Eintrag für das Ereignis Handle ItemAdding angezeigt, das aufgetreten ist, als Sie das Element der Liste List1 hinzugefügt haben.

Hinzufügen oder Entfernen von Ereignishandlern mit Visual Studio

Wählen Sie im Projektmappen-Explorer den Projektknoten für den Remoteereignisempfänger aus.
Legen Sie im Bereich Eigenschaften die Eigenschaften von Ereignissen, die Sie behandeln möchten, auf True fest.

Wenn Sie beispielsweise darauf reagieren möchten, wenn ein Benutzer ein Listenelement hinzufügt, dann legen Sie die Handle ItemAdding-Eigenschaft auf True fest. Wenn Sie dieses Ereignis nicht behandeln möchten, dann legen Sie diese Eigenschaft auf False fest.

SharePoint-Remoteereignisse in Visual Studio
Wenn Sie ein Ereignis hinzugefügt haben, dann fügen Sie den Ereignishandlercode so wie bei den vorherigen Ereignissen der Codedatei für den Webdienst hinzu.

Um einen anderen Ereignistyp zu behandeln, fügen Sie dem SharePoint-Add-In einen weiteren Remoteereignisempfänger hinzu. Wenn ein Remoteereignisempfänger z. B. Listenelementereignisse behandelt, dann können sie ihm ein weiteres Listenelementereignis hinzufügen. Zur Behandlung von Listenereignissen müssen Sie jedoch einen weiteren Remoteereignisempfänger hinzufügen.

URL- und Hostingeinschränkungen für Remoteereignisempfänger in der Produktion

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.)