Créer un gestionnaire pour l’événement de mise à jour dans les compléments SharePoint

  • Article

Avant de commencer, vous devez parfaitement maîtriser le contenu des articles Gestion des événements relatifs au complément et Mise à jour des compléments SharePoint, et connaître la configuration requise et les concepts fondamentaux fournis dans ces derniers.

Remarque

Système de numérotation des versions : par souci de cohérence, cet article suppose que les numéros de version de complément sont 1.0.0.0, 2.0.0.0, 3.0.0.0, et ainsi de suite. Cependant, la logique et ces conseils s’appliquent quel que soit votre système de numérotation.

Créer un récepteur UpgradedEventEndpoint

Pour obtenir une logique de mise à jour personnalisée, vous pouvez créer un récepteur d’événements distant SharePoint qui gère l’événement de mise à jour de complément. Soyez prudent avec cette technique. Utilisez-la uniquement pour les étapes qui ne peuvent pas être effectuées d’une autre manière. En outre, les conseils contenus dans l’article relatif à la gestion des événements de complément s’appliquent à l’événement de mise à jour de complément, ainsi qu’aux événements d’installation et de désinstallation de complément. Cela implique les points suivants :

  • Votre gestionnaire doit effectuer l’opération et renvoyer un état d’annulation ou un statut de poursuite à SharePoint dans les 30 secondes. Dans le cas contraire, SharePoint appellera de nouveau le gestionnaire, jusqu’à trois fois.

  • Si votre gestionnaire renvoie un état d’annulation, SharePoint effectuera jusqu’à trois nouvelles tentatives.

  • Généralement, vous devez inclure une logique de restauration et « d'exécution préalable » dans votre gestionnaire.

Un gestionnaire UpgradedEventEndpoint vous sera par exemple utile quand un champ calculé est ajouté à une base de données distante. Supposons qu'une colonne Ville est ajoutée et que sa valeur est calculée à partir d'une colonne Code postal existante. Le code intégré à votre gestionnaire UpgradedEventEndpoint peut alors parcourir les éléments existants de la base de données et remplir la valeur du nouveau champ Ville en fonction de la valeur du champ Code postal et d'une source de données externe qui associe les codes postaux aux villes. La modification du schéma de base de données lui-même est plus efficace lorsqu'elle est réalisée en dehors du gestionnaire UpgradedEventEndpoint en respectant les meilleures pratiques de la plateforme de base de données.

Pour plus de détails sur la façon de créer un gestionnaire d’événements de complément, voir Gestion des événements dans les compléments SharePoint et Créer un récepteur d’événements de complément dans SharePoint.

La procédure suivante part du principe que vous avez ajouté l’élément de récepteur d’événements de complément à votre projet de complément SharePoint dans Visual Studio

Pour gérer l’événement de mise à jour de complément pour la première fois

  1. Ouvrez le fichier AppEventReceiver.svc.cs et ajoutez une structure conditionnelle à la méthode ProcessEvent, laquelle vérifie si l’événement qui a appelé le gestionnaire est l’événement de mise à jour. Votre code de mise à jour est placé dans cette structure. S'il doit accéder à SharePoint, vous pouvez utiliser le modèle objet client (CSOM) du code managé SharePoint ou l'interface REST (Representational State Transfer).

    L'emplacement de la structure conditionnelle dans la méthode dépend de la façon dont vous avez structuré le reste du code dans la méthode. Généralement, celle-ci se compose de deux structures conditionnelles similaires qui testent les événements d'installation et de désinstallation de complément. Elle peut se trouver au sein d'une structure conditionnelle qui contrôle certaines propriétés ou sous-propriétés de l'objet SPRemoteEventProperties transmis à la méthode ProcessEvent pour les valeurs null ou incorrectes. Elle peut également se trouver dans un bloc try.

    L'exemple ci-dessous illustre la structure. L'élément properties est un objet SPRemoteEventProperties .

       if (properties.EventType == SPRemoteEventType.AppUpgraded)
 {
 }

  2. Pour utiliser le modèle CSOM dans le gestionnaire, ajoutez (dans le bloc conditionnel) un bloc using qui obtient un objet ClientContext en appelant la méthode TokenHelper.CreateAppEventClientContext. Indiquez true pour le deuxième paramètre pour accéder au service web de complément. Indiquez false pour accéder au site web hôte. Si vous avez besoin d’accéder aux deux, vous devrez utiliser deux objets de contexte client différents.

  3. Si le gestionnaire doit accéder à des composants qui ne sont pas des composants SharePoint, placez le code en dehors des blocs de contexte client. Votre code doit être structuré comme suit.

       if (properties.EventType == SPRemoteEventType.AppUpgraded)
 {
     using (ClientContext cc = TokenHelper.CreateAppEventClientContext(properties, true))
     {
         // CSOM code that accesses the add-in web
     }
     using (ClientContext cc = TokenHelper.CreateAppEventClientContext(properties, false))
     {
         // CSOM code that accesses the host web
     }
     // Other update code
 }

  4. Pour utiliser l'interface REST, votre code utilise d'autres méthodes de la classe TokenHelper pour obtenir un jeton d'accès, qui est alors inclus dans les requêtes qu'il envoie à SharePoint. Pour plus d'informations, voir Effectuer des opérations de base à l'aide de terminaux REST SharePoint. Votre code doit être structuré comme suit.

       if (properties.EventType == SPRemoteEventType.AppUpgraded)
 {
     string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
     if (contextTokenString != null)
     {
         contextToken = TokenHelper.ReadAndValidateContextToken(contextTokenString, 
                                                                                                                   Request.Url.Authority);
         accessToken = TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority)
                                    .AccessToken;

        // REST code that accesses SharePoint
     }  
     // Other update code
 }

  5. Pour accéder à SharePoint, votre code REST doit aussi connaître l’URL du site web hôte, du site web de complément ou des deux. Ces URL sont toutes les deux des sous-propriétés de l’objet SPRemoteEventProperties transmis à la méthode ProcessEvent. Le code suivant montre comment les obtenir.

       Uri hostWebURL = properties.AppEventProperties.HostWebFullUrl;
   Uri appWebURL = properties.AppEventProperties.AppWebFullUrl;

Lorsque vous mettez à jour un complément pour la deuxième fois (ou la troisième, etc.), vous devez parfois vous assurer que certains éléments de votre logique ne sont pas exécutés plusieurs fois sur la même instance de complément. La procédure suivante vous montre comment faire.

Pour gérer l’événement de mise à jour de complément les fois suivantes

  1. Ouvrez le fichier AppEventReceiver.svc.cs et recherchez le code qui a implémenté les actions de mise à jour dans la première mise à jour (de 1.0.0.0 à 2.0.0.0). Nous l’appellerons le code de mise à jour précédent. (Ce code se trouve généralement après le code d’autorisation qui obtient le contexte client ou les jetons d’accès.) Maintenant que vous effectuez une nouvelle mise à jour (de 2.0.0.0 à 3.0.0.0), le code de mise à jour précédent comporte généralement des actions que vous ne souhaitez pas réexécuter sur la même instance de complément. mais vous souhaitez qu’il s’exécute sur une instance de complément qui n’a jamais été mise à jour vers 2.0.0.0 (auquel cas, l’instance est maintenant mise à jour de 1.0.0.0. à 3.0.0.0).

  2. Insérez le code de mise à jour précédent dans une structure conditionnelle qui teste la version précédente de l’instance de complément et n’exécute le code que si celui-ci n’a jamais été exécuté auparavant pour cette instance de complément. La version précédente de l’instance est stockée dans la sous-propriété PreviousVersion de l’objet SPRemoteEventProperties.

  3. Ajoutez votre nouvelle logique de mise à jour (pour la mise à jour de 2.0.0.0 vers 3.0.0.0) en dessous de cette structure. Voici un exemple.

       Version ver2OOO = new Version("2.0.0.0");
 if (properties.AppEventProperties.PreviousVersion < ver2OOO)
 {
     // Code to update from 1.0.0.0 to 2.0.0.0 (previous update code) is here.
 }
 // Code to update from 2.0.0.0 to 3.0.0.0 is here.

  4. Pour chaque mise à jour ultérieure, répétez ces étapes. Pour la mise à jour de 3.0.0.0 vers 4.0.0.0, votre code doit avoir la structure suivante.

     Version ver2OOO = new Version("2.0.0.0");
 if (properties.AppEventProperties.PreviousVersion < ver2OOO)
 {
     // Code to update from 1.0.0.0 to 2.0.0.0 is here.
 }

 Version ver3OOO = new Version("3.0.0.0");
 if (properties.AppEventProperties.PreviousVersion < ver3OOO)
 {
     // Code to update from 2.0.0.0 to 3.0.0.0 (previous update code) is here.
 }
 // Code to update from 3.0.0.0 to 4.0.0.0 is here.

Importante

Si vous ajoutez un composant à un complément dans un gestionnaire UpgradedEventEndpoint, n’oubliez pas d’ajouter le même code dans un gestionnaire InstalledEventEndpoint, car le composant doit également être inclus dans le complément lors d’une nouvelle installation. En outre, vous devez ajouter un élément UninstallingEventEndpoint (ou le réviser) pour que le complément puisse supprimer le composant.

Tout ce qui a été ajouté ou modifié par le gestionnaire InstalledEventEndpoint doit être annulé ou supprimé par le gestionnaire UninstallingEventEndpoint. La seule exception concerne les données qui resteront utiles après la suppression du complément de la corbeille secondaire et qui ne doivent pas être supprimées. (Les sites web créés par le complément, autres que le site web de complément, doivent être considérés comme des données.)

Ajouter une logique de restauration au gestionnaire

Si une erreur se produit lors de la mise à jour d’un complément, l’infrastructure SharePoint arrête le processus de mise à jour et restaure la version précédente de l’instance de complément et de ses composants. Toutefois, l’infrastructure n’a aucun moyen de connaître les opérations effectuées par la logique de votre gestionnaire UpgradedEventEndpoint et ne peut donc pas toujours les annuler. Une exception non gérée, générée lors de l’exécution de votre gestionnaire UpgradedEventEndpoint, indique presque toujours que le processus entier de mise à jour du complément doit être annulé, mais il ne le sera pas, car l’infrastructure ne sait pas comment défaire certaines opérations effectuées par votre code UpgradedEventEndpoint. Pour cette raison, le code UpgradedEventEndpoint doit :

  • Intercepter toutes les exceptions.

  • Créer une branche vers un code de restauration personnalisé permettant d’annuler les opérations effectuées jusqu’à ce point.

  • Signaler à l’infrastructure SharePoint que l’intégralité de la mise à jour du complément doit être annulée.

  • Transmettre un message d'erreur à l'infrastructure.

Toutes les opérations réalisées par UpgradedEventEndpoint n'ont pas à être explicitement annulées dans le gestionnaire. Le site web de complément est restauré par l’infrastructure, de sorte que votre code n’a pas à annuler les modifications apportées au site web de complément. En revanche, le gestionnaire UpgradedEventEndpoint doit annuler les modifications apportées au site web hôte ou à d’autres composants extérieurs au complément SharePoint.

Lors de la deuxième (ou de la troisième, etc.) mise à jour, votre logique de gestion des exceptions doit tenir compte du fait que la version de l'instance de complément en cours de mise à jour n'est pas nécessairement la version immédiatement précédente. Dans ce cas, il se peut que plusieurs blocs de code de mise à jour doivent être inversés. Pour cette raison, votre logique conditionnelle doit être basée sur le numéro de la version précédente. L'exemple suivant illustre une logique de restauration pour une mise à jour vers la version 4.0.0.0.

catch (Exception e)
{ 
    // Rollback of the 3.0.0.0 to 4.0.0.0 update logic goes here.

    Version ver3OOO = new Version("3.0.0.0");
    if (properties.AppEventProperties.PreviousVersion < ver3OOO)
    {
        // Rollback of the 2.0.0.0 to 3.0.0.0 update logic goes here.
    }

    Version ver2OOO = new Version("2.0.0.0");
    if (properties.AppEventProperties.PreviousVersion < ver2OOO)
    {
        // Rollback of the 1.0.0.0 to 2.0.0.0 update logic goes here.
    }
}

Enfin, votre logique de gestion des erreurs doit affecter un message d’erreur et un état d’annulation à l’objet SPRemoteEventResult renvoyé par la méthode ProcessEvent à l’infrastructure de mise à jour de SharePoint, comme dans l’exemple suivant. Dans ce code, l’élément result est un objet SPRemoteEventResult qui a été déclaré plus tôt dans la méthode ProcessEvent.

catch (Exception e)
{     
    result.ErrorMessage = "custom message " + e.Message;
    result.Status = SPRemoteEventServiceStatus.CancelWithError;

     // Rollback logic from the preceding code snippet  is here. 

}

Importante

Il est essentiel d’affecter l’élément SPRemoteEventServiceStatus.CancelWithError (ou SPRemoteEventServiceStatus.CancelNoError) à la propriété Status. Il s’agit de la propriété qui signale à l’infrastructure d’annuler la mise à jour. Cependant, SharePoint appellera votre gestionnaire trois fois avant d’annuler la mise à jour.

Utiliser la stratégie de délégation de gestionnaire

La stratégie de délégation de gestionnaire est décrite dans l’article Gestion des événements de complément et peut être également utilisée dans un gestionnaire UpdatedEventHandler. Non seulement votre logique de restauration et « d’exécution préalable » est contenue et exécutée sur le composant à distance, mais votre logique de contrôle de version également. Les limites de la stratégie s’appliquent ici aussi : vous ne pouvez généralement pas l’utiliser pour mettre à jour plusieurs systèmes distants.

Étapes suivantes

Retournez à Étapes principales de mise à jour d’un complément ou consultez directement l’un des articles suivants pour découvrir comment mettre à jour le prochain composant majeur de votre complément SharePoint.

Voir aussi