Partager via

Récepteurs d’événement et récepteurs d’événement de liste dans le modèle de complément SharePoint

  • Article

L’approche que vous adoptez pour gérer des événements dans SharePoint dans le nouveau modèle de complément SharePoint diffère de ce qu’elle était avec le code de confiance totale.

Dans un scénario de code de confiance totale/solution de batterie de serveurs classique, les récepteurs d’événements et les récepteurs d’événements de liste étaient créés avec le code du modèle

d’objet côté serveur SharePoint et déployés via des solutions. Dans ce scénario, le code de récepteur d’événement s’exécute sur le serveur SharePoint.

Dans un scénario de modèle de complément SharePoint, des récepteurs d’événement sont créés hors de SharePoint à l’intérieur d’un service web, et enregistrés avec SharePoint. On les appelle récepteurs d’événement distants. Dans ce scénario, le code de récepteur d’événement s’exécute sur le serveur web hébergeant le service web.

Importante

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.

Conseils généraux

En règle générale, nous prodiguons les conseils généraux suivants pour la création de récepteurs d’événement.

  • Le point de terminaison de service qui implémente un récepteur d’événement doivent être accessible aux utilisateurs anonymes.
  • Des récepteurs d’événement ajoutés au site web complément vous permettent de retourner un jeton d’accès.
  • Des récepteurs d’événement ajoutés au site web hôte retournent un jeton d’accès s’ils sont appliqués à partir d’un contexte d’application utilisant un jeton d’accès d’application, et l’opération dans le site web hôte est pilotée par l’utilisateur final (ItemAdded, etc.).
  • Un événement AppInstalled doit s’achever dans les 30 secondes. Autrement, SharePoint considère qu’il a échoué. SharePoint réessaie d’exécuter l’événement à 3 reprises. Après la quatrième tentative, il considère que l’installation du complément a échoué.
  • Des événements normaux, tel ItemAdded, ont également un délai d’expiration de 30 secondes, mais il n’existe pas de mécanisme de nouvelle tentative.
  • Des récepteurs d’événement ajoutés à un site web hôte sans contexte d’application, par exemple, avec SharePointOnlineCredentials ou par d’autres moyens, ne renvoient pas de jeton d’accès, et vous devez accéder au site web hôte avec un jeton d’accès application seule.
  • L’ajout de récepteurs d’événement au site web hôte est pris en charge.
    • Cela n’est possible que via des API CSOM/REST, pas en utilisant des assistants Visual Studio.
  • SharePoint appellera de façon absolue les points de terminaison du récepteur d’événement configurés pour un événement donné. Toutefois, il n’est nullement garanti que le code dans les points de terminaison du récepteur d’événement seront exécutés, car le code ne s’exécute pas sur le serveur SharePoint.

Par exemple :

Si l’URL de point de terminaison du récepteur d’événement n’est pas disponible, le code du récepteur d’événement ne s’exécute pas. Il se peut que L’URL soit indisponible pour diverses raisons. Parmi les raisons les plus courantes figurent une configuration incorrecte lors de l’inscription de l’URL du point de terminaison, des problèmes de DNS lors de la tentative de résoudre l’URL, ou un arrêt ou un état inexploitable du site web hébergeant le point de terminaison.

En outre, en cas de bogue dans un code de récepteur d’événement mal écrit, il est impossible d’informer SharePoint de la présence de ce bogue et l’événement doit être exécuté à nouveau. Vous pouvez contourner ce problème dans une certaine mesure avec des récepteurs d’événement attachés à des listes SharePoint. Pour plus d’informations sur cette approche, voir ci-dessous.

  • Quand un récepteur d’événement exécute une quantité importante de code, il convient d’utiliser un modèle asynchrone.
  • Pour plus d’informations sur les délais d’expiration des récepteurs d’événement, voir l’article MSDN suivant (Recherchez le délai d’expiration dans l’article.) Gérer les événements dans les compléments pour SharePoint (article MSDN)
  • Quand des destinataires d’événement opèrent sur des listes SharePoint, nous recommandons d’utiliser un mécanisme de suivi des modifications spécifique avec le récepteur d’événement pour assurer un traitement de qualité supérieure.

Débogage de récepteurs d’événement

Pour déboguer des récepteurs d’événement, vous devez configurer différents paramètres dans Azure et Visual Studio. Les articles suivants fournissent des instructions pas à pas et d’autres informations concernant le débogage.

Autres exemples

  • Core.EventReceivers (exemple PnP O365)
    • Cet exemple illustre la manière dont un complément SharePoint peut utiliser l’événement Application installé pour effectuer d’autres tâches dans le site web hôte, comme joindre des récepteurs d’événement à des listes dans le site web hôte.
  • Core.AppEvents.HandlerDelegation (exemple PnP O365)
    • Cet exemple montre comment implémenter des gestionnaires pour les événements AppInstalled et AppUninstalling qui :
      1. incorporent une logique de restauration si le gestionnaire rencontre une erreur ;
      2. incorporent une logique « déjà terminé » pour tenir compte du fait que SharePoint réessaie d’exécuter le gestionnaire jusqu’à trois fois s’il échoue ou prend plus de 30 secondes ;
      3. utilisent la stratégie de délégation de gestionnaire pour minimiser les appels du service web du gestionnaire à SharePoint ;
      4. utilisent les classes CSOM ExceptionHandlingScope et ConditionalScope.
  • Core.AppEvents (exemple PnP O365)
    • Cet exemple montre comment implémenter des gestionnaires pour les événements AppInstalled et AppUninstalling qui :
      1. incorporent une logique de restauration si le gestionnaire rencontre une erreur ;
      2. incorporent une logique « déjà terminé » pour tenir compte du fait que SharePoint réessaie d’exécuter le gestionnaire jusqu’à trois fois s’il échoue ou prend plus de 30 secondes.

Exemples PnP

S’applique à

  • Office 365 multi-locataire (MT).
  • Office 365 dédiés (D)
  • SharePoint 2013 en local