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

It is helpful if you first have an understanding of provider-hosted SharePoint Add-ins, and for you to have developed a few that go at least a little beyond the "Hello World" level. See Get started creating provider-hosted SharePoint Add-ins.

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

Erstellen eines Remoteereignisempfängers

This article shows how you extend a SharePoint Add-in by adding a remote event receiver (RER) that handles the ItemAdded event for a custom list in the add-in web. The RER is registered with the add-in web using declarative markup. RERs are registered with the host web programmatically. For a code sample that does so, see SharePoint/PnP/Samples/Core.EventReceivers.

An RER must be a SOAP web service. The continuing example implements this as a Windows Communication Foundation (WCF) service, but it is possible in principle to implement an RER on a non-Microsoft stack.

Um diesem Artikel zu folgen und den Code selbst einzugeben, laden Sie das Beispiel von der Website SharePoint-Add-in-CSOM-BasicDataOperations herunter, und öffnen Sie das Beispiel anschließend in Visual Studio.

Hinweis

This sample use a TokenHelper.cs file that is generated by Office Developer Tools for Visual Studio. It was the current version when the sample was created, but may not be the most recent version when you read this. The sample is still great for creating your first RER. But when you are ready to move beyond that, you should look at the samples listed in the See also section at the end of this article. They are more likely to be kept up to date.

So registrieren Sie einen Remoteereignisempfänger

  1. Öffnen Sie das SharePoint-Add-In-Projekt in Visual Studio.

  2. Wählen Sie im Projektmappen-Explorer den Knoten des Add-In-Projekts aus.

  3. Wählen Sie auf der Menüleiste Projekt > Neues Element hinzufügen aus.

  4. Wählen Sie im Bereich Installierte Vorlagen den Knoten Office/SharePoint aus.

  5. Wählen Sie im Bereich Vorlagen die Vorlage Remoteereignisempfänger aus.

  6. Lassen Sie den Standardnamen im Feld Name unverändert (RemoteEventReceiver1), und wählen Sie dann Hinzufügen aus.

  7. Wählen Sie in der Liste Welchen Typ soll der Ereignisempfänger aufweisen? die Option Listenelementereignisse aus.

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

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

    A web service is added to the web application to handle the remote event that you specified. A remote event receiver is added to the SharePoint Add-in, and the list item event is referenced in the receiver's Elements.xml file that is itself contained in the add-in web feature.

So erstellen Sie die Liste

  1. Wählen Sie im Projektmappen-Explorer den Knoten des Add-In-Projekts aus.

  2. Wählen Sie auf der Menüleiste Projekt > Neues Element hinzufügen aus.

  3. Wählen Sie im Bereich Installierte Vorlagen den Knoten Office/SharePoint aus.

  4. Wählen Sie im Bereich Vorlagen die Vorlage Liste aus.

  5. Lassen Sie den Standardnamen im Feld Name unverändert (List1), und wählen Sie dann Hinzufügen aus.

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

  1. If your test SharePoint farm is not on the same computer that is running Visual Studio (or you are using a SharePoint Online tenancy as your test SharePoint site), configure the project for debugging by using the Microsoft Azure Service Bus. For more information, see the Debug and troubleshoot a remote event receiver in a SharePoint Add-in.

  2. In the code file for the service of the remote event receiver (that is, RemoteEventReceiver1.svc.cs), replace the contents with the following code. This code performs the following tasks:

    • 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

    At the time this article was written, the Office Developer Tools for Visual Studio had references to all the needed assemblies when the receiver is created, but later versions of the tools may not. If you get compiler errors, simply add the missing references; for example, you may need to add references to System.ServiceModel or System.ComponentModel.DataAnnotations.

    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();
                    }
                }
            }
        }
    }
    
  3. Ä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.

  1. Drücken Sie F5, um das Projekt auszuführen.

  2. Trust the add-in when prompted to do so. Your SharePoint Add-in runs, and a table of available lists appears and includes List1.

  3. Select the ID of List1. That ID is copied to the Retrieve List Items box.

  4. Select the Retrieve List Items button. List1 appears with no items in it.

  5. In the Add Item box, specify First Item, and then select the Add Item button. A list item that's named First Item is added to List1, which causes the remote event receiver to fire and add an entry to the EventLog list.

  6. Select the Refresh Lists button to return to the table of lists. In the table, a new list that's named EventLog appears.

  7. Select the ListID GUID value for EventLog, and then select the Retrieve List Items button. A table for EventLog appears with an entry for the Handle ItemAdding event that occurred when you added the item to List1.

Hinzufügen oder Entfernen von Ereignishandlern mit Visual Studio

  1. Wählen Sie im Projektmappen-Explorer den Projektknoten für den Remoteereignisempfänger aus.

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

    SharePoint-Remoteereignisse in Visual Studio

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

    Zur Behandlung eines anderen Ereignistyps fügen Sie der 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

The remote event receiver can be hosted in the cloud or on an on-premises server that is not also being used as a SharePoint server. The URL of a production receiver cannot specify a particular port. This means that you must use either port 443 for HTTPS, which we recommend, or port 80 for HTTP. If you are using HTTPS and the receiver service is hosted on-premises, but the add-in is on SharePoint Online, the hosting server must have a publicly trusted certificate from a certificate authority. (A self-signed certificate works only if the add-in is on an on-premises SharePoint farm.)

Siehe auch