Créer un récepteur d'événements distant dans des compléments pour SharePoint
Il serait préférable que vous connaissiez les compléments SharePoint hébergés par un fournisseur et que vous ayez déjà développé des compléments au-delà du niveau « Hello World ». Consultez l’article Commencer à créer des compléments hébergés par un fournisseur pour SharePoint.
Nous vous recommandons également de lire l’article Gestion des événements dans les compléments pour SharePoint.
Créer un récepteur d’événements distant
Cet article explique comment étendre un complément SharePoint en ajoutant un récepteur d’événements distants qui gère l’événement ItemAdded pour une liste personnalisée du site web de complément. Le récepteur d’événements distants est inscrit avec le site web de complément via des balises déclaratives. Les récepteurs d’événements distants sont inscrits avec le site web hôte via un programme. Pour consulter un exemple de code qui exécute cette tâche, reportez-vous à l’article SharePoint/PnP/Samples/Core.EventReceivers.
Un récepteur d’événements distants doit être un service web SOAP. L’exemple de cet article l’implémente comme un service Windows Communication Foundation (WCF), mais il est en principe possible d’implémenter un récepteur d’événements distants sur une pile non Microsoft.
Pour suivre cet article et entrer le code vous-même, téléchargez l’exemple à partir de SharePoint-Add-in-CSOM-BasicDataOperations, puis ouvrez l’exemple dans Visual Studio.
Remarque
Cet exemple utilise un fichier TokenHelper.cs généré par les outils de développement Office Visual Studio. Il s’agissait de la version existant au moment de la création de l’exemple, mais il existe peut-être maintenant une version plus récente. L’exemple est tout de même utile pour créer votre premier récepteur d’événements distants. Cependant, quand vous serez prêt à aller plus loin, consultez les exemples fournis dans la section Voir aussi à la fin de cet article. Ils sont mis à jour plus régulièrement.
Pour enregistrer un récepteur d’événements distants
Ouvrir un projet de complément SharePoint dans Visual Studio
Dans l’Explorateur de solutions, sélectionnez le nœud du projet de complément.
Dans la barre de menus, sélectionnez Project>Ajouter un nouvel élément.
Dans le volet Modèles installés, sélectionnez le nœud Office/SharePoint.
Dans le volet Modèles, sélectionnez le modèle Récepteur d’événements distants.
Dans la zone Nom, conservez le nom par défaut (RemoteEventReceiver1), puis sélectionnez Ajouter.
Dans la liste Quel type de récepteur d’événements voulez-vous ?, sélectionnez Liste des événements d’élément.
Dans la liste Quel élément doit être la source de l’événement ?, sélectionnez Liste personnalisée.
L'exemple en cours utilise une liste générique personnalisée. Mais un récepteur d'événement distant peut également gérer les événements qui se produisent dans des listes SharePoint standard comme Annonces ou Contacts.
Dans la liste Gérer les événements suivants, sélectionnez Un élément est en cours d’ajout, puis Terminer.
Un service web est ajouté à l’application web pour gérer l’événement distant spécifié. Un récepteur d’événements distants est ajouté au complément SharePoint et l’événement d’élément de liste est référencé dans le fichier Elements.xml du récepteur, qui est lui-même contenu dans la fonctionnalité du site web de complément.
Pour créer la liste
Dans l’Explorateur de solutions, sélectionnez le nœud du projet de complément.
Dans la barre de menus, sélectionnez Project>Ajouter un nouvel élément.
Dans le volet Modèles installés, sélectionnez le nœud Office/SharePoint.
Dans le volet Modèles, sélectionnez le modèle Liste.
Dans la zone Nom, conservez le nom par défaut (List1), puis sélectionnez Ajouter.
Sélectionnez Créer une instance de liste basée sur un modèle de liste existant. Ensuite, sélectionnez Liste personnalisée dans la liste, puis Terminer.
Pour ajouter des fonctionnalités au récepteur d’événements distants
Si votre batterie de test SharePoint ne se trouve pas sur l’ordinateur qui exécute Visual Studio (ou si vous utilisez un client SharePoint Online comme site de test SharePoint), configurez le projet de débogage à l’aide de Microsoft Azure Service Bus. Pour en savoir plus, consultez l’article Déboguer et dépanner un récepteur d’événement distant dans un complément pour SharePoint.
Dans le fichier de code pour le service du récepteur d’événements distants (c’est-à-dire, RemoteEventReceiver1.svc.cs), remplacez le contenu par le code suivant. Ce code effectue les tâches suivantes :
Obtient un objet de contexte client valide.
S'il n'existe pas de liste appelée EventLog, créez-la afin qu'elle contienne le nom des événements distants qui se produisent.
Ajoute une entrée à la liste pour l’événement, y compris un horodatage.
Remarque
Au moment de la rédaction de cet article, les outils de développement Office Visual Studio avaient des références à tous les assemblys nécessaires au moment de la création du récepteur, mais les versions ultérieures des outils n’en avaient peut-être pas. Si vous recevez des erreurs de compilation, ajoutez simplement les références manquantes. Par exemple, vous devrez peut-être ajouter les références à System.ServiceModel ou à 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(); } } } } }Dans Home.aspx.cs, remplacez toutes les instances de
SPHostUrlparSPAppWebUrl.Par exemple,
sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);doit être remplacé parsharepointUrl = new Uri(Request.QueryString["SPAppWebUrl"]);.
Exécuter et tester le gestionnaire d’événements
Testez votre gestionnaire par le biais de la procédure suivante.
Sélectionnez la touche F5 pour exécuter le projet.
Approuvez le complément lorsque vous êtes y invité. Votre complément SharePoint s'exécute. Un tableau contenant les listes disponibles s'affiche en incluant List1.
Sélectionnez l’ID de List1. Cet ID est copié dans la zone Récupérer les éléments de liste.
Sélectionnez le bouton Récupérer les éléments de liste. List1 apparaît sans élément.
Dans la zone Ajouter un élément, indiquez Premier élément, puis sélectionnez le bouton Ajouter un élément. Un élément de liste appelé First Item est ajouté à List1, ce qui déclenche le récepteur d'événements distants et ajoute une entrée à la liste EventLog.
Sélectionnez le bouton Actualiser les listes pour retourner dans le tableau des listes. Dans le tableau, une nouvelle liste appelée EventLog apparaît.
Sélectionnez la valeur de GUID ListID pour EventLog, puis sélectionnez le bouton Récupérer les éléments de liste. Un tableau pour EventLog apparaît. Il contient une entrée pour l'événement Handle ItemAdding qui s'est produit lorsque vous avez ajouté l'élément à List1.
Ajouter ou supprimer des gestionnaires d’événements à l’aide de Visual Studio
Dans l’Explorateur de solutions, sélectionnez le nœud de projet du récepteur d’événements distants.
Dans le volet Propriétés, définissez sur True les propriétés des événements à gérer.
Par exemple, si vous voulez répondre chaque fois qu'un utilisateur ajoute un élément de liste, définissez la valeur de la propriété Handle ItemAdding sur True. Si vous ne voulez pas gérer cet événement, définissez la valeur de cette propriété sur False.
Événements distants SharePoint dans Visual Studio
Si vous avez ajouté un événement, ajoutez le code de gestion des événements au fichier de code pour le service web comme vous l'avez fait avec les événements précédents.
Pour gérer un type différent d'événement, ajoutez un autre récepteur d'événements distant à l'Complément SharePoint. Par exemple, si un récepteur d'événements distants gère des événements d'élément de liste, vous pouvez ajouter un autre événement d'élément de liste à celui-ci. Mais, vous devez ajouter un autre récepteur d’événements distants si vous voulez gérer des événements de liste.
URL et restrictions d’hébergement pour les récepteurs d’événements distants de production
Le récepteur d’événements distants peut être hébergé dans le cloud ou sur un serveur local qui n’est pas utilisé en même temps comme serveur SharePoint. L’URL d’un récepteur de production ne peut pas spécifier un port particulier. Cela signifie que vous devez utiliser soit le port 443 pour HTTPS (recommandé) soit le port 80 pour HTTP. Si vous utilisez HTTPS et que le service de récepteur est hébergé sur le serveur local, mais que le complément se trouve sur SharePoint Online, le serveur d’hébergement doit obtenir un certificat approuvé publiquement auprès d’une autorité de certification. (Un certificat auto-signé est valable uniquement si le complément se trouve sur une batterie de serveurs SharePoint locale.)