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 afin de 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.

Notes

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, voir Créer un récepteur d’événements complément.

Avant de commencer

Pour commencer, téléchargez l’exemple de complément Core.EventReceivers à partir du projet consacré aux pratiques et modèles de développement d’Office 365 sur GitHub.

Avant d’exécuter ce complément, effectuez les opérations suivantes :

  1. Dans les propriétés du projet Core.EventReceivers, vérifiez que les options Handle App Installed et Handle App Uninstalling sont définies sur True. La définition des options Gérer l’installation de l’application et Gérer la désinstallation de l’application sur True a pour effet de créer 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. Les valeurs InstalledEventEndpoint et UninstallingEventEndpoint désignent le récepteur d’événements distant qui gère les événements AppInstalled et AppUninstalling.

  2. La jonction d’un récepteur d’événements distant à un objet du site web hôte requiert 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 :

    1. Double-cliquez sur Core.EventReceivers\AppManifest.xml.

    2. Choisissez les Autorisations.

    3. Vérifiez que la valeur Étendue est définie sur Web, et la valeur Autorisation sur Gérer.

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

  4. Créez un espace de noms Azure Service Bus.

    1. Suivez les instructions décrites dans Créer un espace de noms Service Bus.

    2. Copiez la Chaîne de connexion principale de l’espace ce noms Service Bus que vous venez de créer.

    3. Revenez à Visual Studio.

    4. Cliquez avec le bouton droit sur Core.EventReceivers > Propriétés > SharePoint.

    5. Sélectionnez Activer le débogage via Microsoft Azure Service Bus.

    6. Dans Chaîne de connexion Microsoft Azure Service Bus, collez la chaîne de connexion.

    7. Choisissez Enregistrer.

  5. Exécutez l’exemple de code, puis effectuez les étapes supplémentaires suivantes :

    • Dans la fenêtre Accorder les autorisations à l’application, cliquez sur Approuver.

    • Fermez la fenêtre Accorder les 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 :

  1. Exécutez l’échantillon, puis, dans la page de démarrage, choisissez Retour au site.

  2. Choisissez Contenu du site.

  3. Sélectionnez Travaux du récepteur d’événements distant.

  4. Choisissez Nouvel élément.

  5. Dans Titre, entrez Contoso, puis, dans Description, entrez Test Contoso.

  6. Revenez à la liste et actualisez la page.

  7. Vérifiez que la description de l’élément nouvellement ajouté a été mise à jour sur 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.

La méthode ProcessEvent gère les événements à distance 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 ne s’exécute que quand un utilisateur supprime complètement le complément, soit en le supprimant de la corbeille du site (pour les utilisateurs finaux), soit en le retirant de la liste Applications en cours de 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.

Notes

Dans les propriétés du projet Core.EventReceiver, seules les propriétés Gérer l’installation de l’application et Gérer la désinstallation de l’application 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.

Notes

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 notifications Push en utilisant 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 distant. 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 distant AppInstalled.

    • Ajoute un nouveau récepteur d’événements à la liste en utilisant 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);
            }
        }

Lors de l’ajout d’un élément à la liste des 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);
            }

        }

Voir aussi