Verwenden von Remoteereignisempfängern in SharePoint
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 Ereignisse AppInstalled und AppUninstalling zu behandeln. 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.
- Empfangen von Benachrichtigungen über Änderungen, die in SharePoint auftreten. 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 Vorgehensweise: Erstellen eines Add-In-Ereignisempfängers.
Bevor Sie beginnen
Laden Sie zunächst das Beispiel-Add-In Core.EventReceivers aus dem projekt Office 365 Developer patterns and practices (Entwicklermuster und -methoden) auf GitHub herunter.
Bevor Sie dieses Add-In ausführen, führen Sie folgende Schritte aus:
Vergewissern Sie sich in den Eigenschaften des Projekts Core.EventReceivers, dass Handle App Installed und Handle App Uninstalling (App-Deinstallation behandeln) auf True festgelegt ist. Wenn Sie Handle App Installed und Handle App Uninstalling (App-Deinstallation behandeln ) auf True festlegen, wird ein WCF-Dienst erstellt, der den Ereignishandler für die Ereignisse AppInstalled und AppUninstalling definiert. Öffnen Sie in Core.EventReceivers das Kontextmenü (rechte Maustaste) für AppManifest.xml, und wählen Sie Eigenschaften aus. InstalledEventEndpoint und UninstallingEventEndpoint zeigen auf den Remoteereignisempfänger, der die Ereignisse AppInstalled und AppUninstalling behandelt.
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:
Doppelklicken Sie auf Core.EventReceivers\AppManifest.xml.
Wählen Sie Berechtigungen aus.
Vergewissern Sie sich, dass Bereich auf Web und Berechtigung auf Verwalten festgelegt ist.
Um dieses Codebeispiel auszuführen, benötigen Sie ein Azure-Abonnement. Informationen zur Registrierung für eine Testversion finden Sie unter Kostenlose einmonatige Testversion.
Erstellen Sie einen Azure Service Bus-Namespace.
Führen Sie die Anweisungen unter Erstellen eines Service Bus-Namespace aus.
Kopieren Sie Primäre Verbindungszeichenfolge aus dem soeben erstellten Service Bus-Namespace.
Kehren Sie zu Visual Studio zurück.
Klicken Sie mit der rechten Maustaste auf Core.EventReceivers-Eigenschaften >>SharePoint.
Wählen Sie Debuggen über Microsoft Azure Service Bus aktivieren aus.
Fügen Sie Microsoft Azure Service Bus Verbindungszeichenfolge die Verbindungszeichenfolge ein.
Wählen Sie Speichern aus.
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 aufVertrauen.
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:
Führen Sie das Beispiel aus, und wählen Sie auf der Startseite Zurück zur Website aus.
Wählen Sie Websiteinhalte.
Wählen Sie Remoteereignisempfängeraufträge aus.
Wählen Sie Neues Element aus.
Geben Sie unter Titeldie Zeichenfolge Contoso und unter Beschreibung den Namen Contoso test ein.
Kehren Sie zur Liste zurück, und aktualisieren Sie die Seite.
Vergewissern Sie sich, dass die Beschreibung des neu hinzugefügten Elements in contoso test Updated by ReR 192336 aktualisiert wurde, 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 behandelt 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, indem er entweder das Add-In aus dem Papierkorb der Website (für Endbenutzer) löscht oder das Add-In aus der Liste Apps in Tests entfernt (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 Core.EventReceiver-Projekteigenschaften sind nur die Eigenschaften Handle App Installed und Handle App Uninstalling 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 Aufträge für Remoteereignisempfänger ein Element hinzugefügt wird, verarbeitet 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);
}
}