Utiliser des récepteurs d’événements distants dans SharePoint
Utilisez des récepteurs d’événements distants pour gérer les événements dans le complément SharePoint SharePoint. Utilisez les événements AppInstalled et AppUninstalling pour installer ou désinstaller des objets SharePoint et autres récepteurs d’événements dont votre complément a besoin.
S’applique à : compléments pour SharePoint | SharePoint 2013 | SharePoint Online
Important Depuis janvier 2017, SharePoint Online prend en charge des webhooks de liste que vous pouvez utiliser à la place de récepteurs d’événement distants «-ed ». Pour en savoir plus sur webhooks, consultez Présentation des webhooks SharePoint. Notez également que plusieurs exemples de webhook sont disponibles dans le dépôt GitHub sp-dev-samples.
L’exemple Core.EventReceivers montre comment utiliser un complément hébergé par un fournisseur avec un récepteur d’événements distant pour gérer les événements AppInstalled et AppUninstalling. Les événements AppInstalled et AppUninstalling permettent d’installer et de désinstaller des objets SharePoint que le complément utilise lors de son exécution. Par ailleurs, le gestionnaire d’événements AppInstalled ajoute le gestionnaire d’événements ItemAdded à une liste. Utilisez cette solution si vous souhaitez effectuer les tâches suivantes :
- Configurer votre complément lors de la première exécution à l’aide de l’événement AppInstalled afin d’installer divers objets SharePoint ou des récepteurs d’événements supplémentaires avec lesquels votre complément fonctionne.
- Remplacer des récepteurs d’événements implémentés à l’aide de solutions de code entièrement approuvées. Dans des solutions de code entièrement approuvées, vous pouvez exécuter des récepteurs d’événements sur le serveur SharePoint. Dans le nouveau modèle de complément SharePoint, étant donné que vous ne pouvez pas exécuter le récepteur d’événements sur le serveur SharePoint, vous devez implémenter un récepteur d’événements distant sur un serveur web.
- Recevoir des notifications des modifications qui se produisent dans SharePoint. Par exemple, lors de l’ajout d’un élément à une liste, vous souhaitez effectuer une tâche.
- Compléter votre solution de Journal des modifications. L’utilisation du modèle de récepteur d’événements distant avec un modèle de journal des modifications fournit une architecture plus fiable pour la gestion de toutes les modifications apportées à des bases de données de contenu, collections de sites, sites ou listes SharePoint. Les récepteurs d’événements distants sont exécutés immédiatement, mais un échec de communication peut se produire en raison de leur exécution sur un serveur distant. Le modèle de journal des modifications garantit que toutes les modifications sont disponibles pour le traitement, mais l’application traitant les changements est généralement exécutée selon une planification (par exemple, un travail du minuteur). Cela signifie que les modifications ne sont pas traitées immédiatement. Si vous associez ces deux modèles, veillez à utiliser un mécanisme pour empêcher le traitement en double de la même modification. Pour plus d’informations, voir Interroger le journal des modifications SharePoint avec ChangeQuery et ChangeToken.
Remarque
Les compléments hébergés par SharePoint ne prennent pas en charge les récepteurs d’événements distants. Pour utiliser des récepteurs d’événements distants, vous devez utiliser un complément hébergé par un fournisseur. Vous ne devez pas utiliser des récepteurs d’événements distants pour des scénarios de synchronisation ou des processus longs. Pour plus d’informations, consultez Guide pratique pour créer un récepteur d’événements de complément.
Avant de commencer
Pour commencer, téléchargez l’exemple de complément Core.EventReceivers à partir du projet modèles et pratiques Office 365 Développeur sur GitHub.
Avant d’exécuter ce complément, effectuez les opérations suivantes :
Dans les propriétés du projet Core.EventReceivers, vérifiez que Gérer l’application installée et Gérer la désinstallation de l’application est défini sur True. Définir Gérer l’application installée et Gérer la désinstallation de l’application sur True crée un service WCF qui définit le gestionnaire d’événements pour les événements AppInstalled et AppUninstalling . Dans Core.EventReceivers, ouvrez le menu contextuel en cliquant avec le bouton droit sur AppManifest.xml, puis choisissez Propriétés. InstalledEventEndpoint et UninstallingEventEndpoint pointent vers le récepteur d’événements distant qui gère les événements AppInstalled et AppUninstalling.
L’attachement d’un récepteur d’événements distants à un objet dans le site web hôte nécessite généralement l’autorisation Gérer pour cet objet uniquement. Par exemple, lorsque vous joignez un récepteur d’événements à une liste existante, le complément nécessite l’autorisation Gérer uniquement sur la Liste. Cet exemple de code nécessite de disposer d’autorisations Gérer sur le Web, car il ajoute une liste et active une fonctionnalité sur le web hôte. Pour définir des autorisations Gérer sur le web :
Double-cliquez sur Core.EventReceivers\AppManifest.xml.
Choisissez Autorisations.
Vérifiez que l’étendue est définie sur Web et que l’autorisation est définie sur Gérer.
Pour exécuter cet exemple de code, vous avez besoin d’un abonnement Azure. Pour vous inscrire pour une version d’évaluation, voir Version d’évaluation gratuite pendant un mois.
Créez un espace de noms Azure Service Bus.
Suivez les instructions décrites dans Créer un espace de noms Service Bus.
Copiez la Chaîne de connexion principale de l’espace ce noms Service Bus que vous venez de créer.
Revenez à Visual Studio.
Cliquez avec le bouton droit sur Core.EventReceivers >Propriétés>SharePoint.
Sélectionnez Activer le débogage via Microsoft Azure Service Bus.
Dans Microsoft Azure Service Bus chaîne de connexion, collez la chaîne de connexion.
Cliquez sur Enregistrer.
Exécutez l’exemple de code, puis effectuez les étapes supplémentaires suivantes :
Cliquez sur Approuver dans la fenêtre Accorder des autorisations à l’application .
Fermez la fenêtre Accorder des autorisations à l’application .
Une fois l’installation du complément et du service WCF terminées, votre navigateur s’ouvre.
Connectez-vous à votre site Office 365. La page de démarrage du complément Core.EventReceivers s’affiche.
Utiliser le complément Core.EventReceivers
Pour visionner une démonstration de l’exemple de code Core.EventReceivers :
Exécutez l’exemple et, dans la page de démarrage, choisissez Revenir au site.
Choisissez Contenu du site.
Choisissez Travaux du récepteur d’événements distants.
Choisissez Suivant.
Dans Titre, entrez Contoso et, dans Description , entrez Contoso test.
Revenez à la liste et actualisez la page.
Vérifiez que la description de l’élément qui vient d’être ajouté a été mise à jour pour le test Contoso Mis à jour par ReR 192336, où 192336 est un horodatage.
Dans Services/AppEventReceiver.cs, AppEventReceiver implémente l’interface IRemoteEventService . Cet exemple de code fournit une implémentation pour la méthode ProcessEvent, car il utilise des événements synchrones. Si vous utilisez des événements asynchrones, vous devez fournir une implémentation pour la méthode ProcessOneWayEvent.
ProcessEvent gère les événements distants SPRemoteEventType suivants :
Événements AppInstalled lors de l’installation du complément. Quand un événement AppInstalled se produit, la méthode ProcessEvent appelle HandleAppInstalled.
Événements AppUninstalling lors de la désinstallation du complément. Quand un événement AppUninstalling se produit, la méthode ProcessEvent appelle HandleAppUninstalling. L’événement AppUninstalling s’exécute uniquement lorsqu’un utilisateur supprime complètement le complément en supprimant le complément de la Corbeille du site (pour les utilisateurs finaux) ou en supprimant le complément de la liste Applications en test (pour les développeurs).
Événements ItemAdded lors de l’ajouter d’un élément à une liste. Quand un événement ItemAdded se produit, la méthode ProcessEvent appelle HandleItemAdded.
Remarque
Dans les propriétés du projet Core.EventReceiver, seules les propriétés Handle App Installed et Handle App Uninstalling sont disponibles. Cet exemple de code montre comment ajouter le gestionnaire d’événements ItemAdded à une liste sur le web hôte en utilisant l’événement AppInstalled lors de l’installation du complément.
Remarque
Le code dans cet article est fourni tel quel, sans garantie d’aucune sorte, expresse ou implicite, y compris mais sans s’y limiter, aucune garantie implicite d’adéquation à un usage particulier, à une qualité marchande ou une absence de contrefaçon.
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 appelle RemoteEventReceiverManager.AssociateRemoteEventsToHostWeb dans RemoteEventReceiverManager.cs.
private void HandleAppInstalled(SPRemoteEventProperties properties)
{
using (ClientContext clientContext =
TokenHelper.CreateAppEventClientContext(properties, false))
{
if (clientContext != null)
{
new RemoteEventReceiverManager().AssociateRemoteEventsToHostWeb(clientContext);
}
}
}
AssociateRemoteEventsToHostWeb crée ou active différents objets SharePoint que le complément Core.EventReceivers utilise. Vos exigences peuvent être différentes. AssociateRemoteEventsToHostWeb effectue les opérations suivantes :
Active la fonctionnalité de notification Push à l’aide de Web.Features.Add.
Utilise l’objet clientContext pour rechercher une liste. Si la liste n’existe pas, CreateJobsList la crée. Si la liste existe, List.EventReceivers permet de rechercher un récepteur d’événements existant nommé ItemAddedEvent.
Si le récepteur d’événements ItemAddedEvent n’existe pas :
Instancie un nouvel objet EventReceiverDefinitionCreationInformation pour créer le nouveau récepteur d’événements distants. Le type de récepteur d’événements ItemAdded est ajouté à EventReceiverDefinitionCreationInformation.EventType.
Définit EventReceiverDefinitionCreationInformation.ReceiverURL sur l’URL du récepteur d’événements distants AppInstalled .
Ajoute un nouveau récepteur d’événements à la liste à l’aide de List.EventReceivers.Add.
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);
}
}
Lorsqu’un élément est ajouté à la liste Travaux du récepteur d’événements distants , ProcessEvent dans AppEventReceiver.svc.cs gère l’événement ItemAdded , puis appelle HandleItemAdded. HandleItemAdded appelle RemoteEventReceiverManager.ItemAddedToListEventHandler. ItemAddedToListEventHandler extrait l’élément de liste ajouté, puis ajoute la chaîne Mis à jour par ReR à la description de l’élément de liste.
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);
}
}