Gérer les événements de complément dans le complément hébergé par le fournisseur

Article
04/08/2023

Cet article est le septième d’une série sur les concepts de base du développement de compléments SharePoint hébergés par un fournisseur. Vous devez tout d’abord avoir pris connaissance de la rubrique Compléments SharePoint et des articles précédents de la série, disponibles dans la rubrique Commencer à créer des compléments hébergés par un fournisseur pour SharePoint.

Remarque

Si vous avez consulté cette série sur les compléments hébergés par un fournisseur, votre solution Visual Studio vous sera utile pour continuer à parcourir cette rubrique. Vous pouvez également télécharger le référentiel sur SharePoint_Provider-hosted_Add-Ins_Tutorials et ouvrir le fichier BeforeAdd-inEventHandlers.sln.

Dans cet article, nous personnalisons la gestion d’un type d’événement dans SharePoint appelé événements de complément. Plus précisément, nous créons des gestionnaires pour les événements d’installation et de désinstallation de complément. Les événements de liste et d’élément de liste peuvent utiliser une gestion personnalisée ; vous les découvrirez dans un prochain article de cette série. Toutes ces événements sont déclenchés dans SharePoint, mais votre code personnalisé qui gère chaque événement se trouve dans votre application web à distance. Configurez SharePoint afin qu’il appelle votre gestionnaire personnalisé en inscrivant l’URL du gestionnaire auprès de l’événement SharePoint.

Deux emplacements pour déployer les composants SharePoint de manière programmée

Nous voulons que notre complément Chain Store crée et déploie les listes Employés locaux et Livraisons attendues automatiquement. Un complément peut déployer des composants SharePoint, tels qu’ une liste personnalisée, à tout moment. Mais lorsqu’un complément dépend d’un composant spécifique par exemple, une liste personnalisée, le composant doit vraiment être déployé avant que les utilisateurs commencent à travailler avec le complément. Pour ces composants essentiels, il existe deux emplacements pour la logique de déploiement personnalisée :

dans un gestionnaire pour l'événement d'installation du complément ;
dans une logique de « première exécution » qui s'exécute la première fois que le complément est lancé dans SharePoint.

Le choix de la meilleure solution pour un complément donné implique un niveau plus avancé. Dans cet article, nous allons uniquement mentionner quelques points de comparaison :

Un gestionnaire d’installation personnalisé doit se terminer en 30 secondes. Il n’existe aucune limite à la durée de la logique de première exécution.
En cas de problème lors de l’installation d’un complément, SharePoint annule tout ce qui a été effectué dans le cadre de l’installation. Un gestionnaire d’installation personnalisée s’exécute après que SharePoint a fait tout ce qu’il faut pour installer le complément, donc un gestionnaire personnalisé peut participer à ce système.

Par exemple, si votre logique personnalisée lève une exception, vous pouvez configurer SharePoint de façon à restaurer l’installation entière du complément. Si quelque chose ne se passe pas comme prévu dans la logique de première exécution, le complément reste installé mais ne fonctionne pas correctement.
SharePoint n’abandonne pas s’il doit restaurer une installation du complément. Il tente immédiatement à nouveau l’installation. Cela permet un maximum de quatre tentatives (la limite de temps de 30 secondes s’applique à chaque tentative). À chaque tentative, le gestionnaire d’installation personnalisée s’exécute à nouveau à partir du début. Si le gestionnaire a essayé d’installer, comme une liste avant la restauration, il tente d’installer la même liste de nouveau lors de la nouvelle tentative.

Pour l’empêcher, le code dans un gestionnaire d’installation doit être écrit afin qu’il n’effectue aucune action (par exemple, déployer un composant), sauf s’il vérifie d’abord si cette action a déjà été effectuée. Cela rend la logique d’un gestionnaire d’installation plus complexe que la logique de première exécution, car la logique de première exécution ne recommence pas (sauf si vous codez spécifiquement pour le faire). En outre, la vérification pour voir si un composant a déjà été déployé nécessite généralement un appel fastidieux via Internet à partir du gestionnaire à distance vers SharePoint. Un deuxième appel est également nécessaire pour déployer réellement le composant (le cas échéant).

Pour le complément Chain Store, nous combinons ces stratégies. Dans cet article, vous créez un gestionnaire d’installation qui enregistre le site web hôte en tant que client dans la base de données d’entreprise, puis définit un signal indiquant que le complément a déjà été exécuté sur le site web hôte.

Dans un prochain article de cette série, vous allez insérer la logique de première exécution dans la méthode Page_Load de la page d’accueil du complément. Cette logique déploie les deux listes personnalisées, entre autres choses.

Configurer la solution de débogage pour un récepteur d’événements

Le débogage des récepteurs d’événements nécessite l’utilisation d’Azure Service Bus. Suivez les instructions de la rubrique Déboguer et dépanner un récepteur d’événement distant dans un complément pour SharePoint. Étant donné que vous utilisez un site Web SharePoint Online en tant que site de test, veillez à suivre les instructions relatives à un site de test à distance. Le reste de cette série part du principe que vous avez configuré correctement le débogage.

Créer le gestionnaire d’installation

Remarque

Les paramètres pour les projets de démarrage dans Visual Studio ont tendance à revenir aux paramètres par défaut chaque fois que la solution est rouverte. Suivez toujours ces étapes immédiatement après la réouverture de l’exemple de solution dans cette série d’articles :

Cliquez avec le bouton droit sur le nœud de la solution en haut de l’Explorateur de solutions, puis sélectionnez Définir les projets de démarrage.
Assurez-vous que les trois projets sont définis sur Démarrer dans la colonne Action.

Dans l’Explorateur de solutions, sélectionnez le projet ChainStore de sorte que ses propriétés apparaissent dans le volet Propriétés de Visual Studio.
Définissez la valeur de l’option Gérer l’installation du Complément sur True. (Il est possible que cette option soit encore intitulée Gérer l’installation de l'application.) Cette opération a deux conséquences :
- Un dossier portant le nom Services est créé dans le projet ChainStoreWeb (et non dans le projet ChainStore) et deux fichiers y sont ajoutés : un fichier AppEventReceiver.svc et son fichier code-behind AppEventReceiver.svc.cs (les noms de fichiers commencent par la chaîne « App », car auparavant, les compléments étaient appelés « applications » ou « apps ». Ne renommez pas ces fichiers, car les outils de développement Office pour Visual Studio considèrent que ces fichiers conservent ces noms).
- L’URL du gestionnaire est enregistrée dans le manifeste du complément. Cette partie du manifeste n'est pas visible dans le concepteur de manifeste. Pour l’afficher, cliquez sur le fichier AppManifest.xml puis sélectionnez Visualiser le code. Un nouvel enfant de l’élément Propriétés se présente comme suit.
```
   <InstalledEventEndpoint>~remoteAppUrl/Services/AppEventReceiver.svc</InstalledEventEndpoint>
```
  Ce marquage indique à SharePoint d’appeler la méthode ProcessEvent de ce service lorsqu’il a terminé d’effectuer toutes ses opérations liées à l’installation du complément. Le gestionnaire personnalisé est le dernier élément à exécuter dans le cadre de l’installation. La chaîne ~remoteAppUrl est un espace réservé que les outils de développement Office pour Visual Studio remplacent par l’URL hôte du service. Lors du débogage, il s’agit d’une URL Azure Service Bus. Lorsque vous créez le package pour le déploiement en production, il s'agit de l'URL de production.
Ouvrez le fichier AppEventReceiver.svc.cs.
Vous voyez que les outils de développement Office pour Visual Studio ont créé un exemple d’implémentation de la méthode ProcessEvent. Toutes les implémentations de cette méthode commencent par l’initialisation d’un objet SPRemoteEventResult et se terminent par le renvoi de cet objet à SharePoint. Entre autres, cet objet indique à SharePoint ou non s’il doit restaurer l’événement, car la logique de gestion personnalisée a échoué.

Les outils peuvent également inclure un bloc using dans cette méthode qui crée un objet ClientContext. Le gestionnaire personnalisé du complément Chain Store n'est pas amené à rappeler SharePoint, donc supprimez ce bloc. La méthode doit désormais se présenter comme suit :
```
   public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
 {
     SPRemoteEventResult result = new SPRemoteEventResult();

     return result;
 }
```

Le récepteur d’événements peut être appelé par l’un des trois événements de complément possibles. Ajoutez la structure switch suivante à la méthode ProcessEvent entre les lignes qui créent et renvoient l’objet result (les noms des événements disposent d’une chaîne « App », car auparavant les compléments étaient appelés « applications » ou « apps »).

  switch (properties.EventType)
{
    case SPRemoteEventType.AppInstalled:

        // TODO2: Custom installation logic goes here.

        break;
    case SPRemoteEventType.AppUpgraded:
        // This sample does not implement an add-in upgrade handler.
        break;
    case SPRemoteEventType.AppUninstalling:

        // TODO3: Custom uninstallation logic goes here.         

        break;
}

Notre logique d’installation va appeler une procédure stockée SQL pour enregistrer le magasin de Hong Kong comme client dans l’application web à distance. Il est très important que, si cette procédure échoue, le gestionnaire signale à SharePoint de restaurer l’installation du complément, donc ajoutez les blocs try/catch suivants à la place de TODO2.
```
  try
{
    CreateTenant(tenantName);
 }
catch (Exception e)
{
     // Tell SharePoint to cancel and roll back the event.
    result.ErrorMessage = e.Message;
    result.Status = SPRemoteEventServiceStatus.CancelWithError;
}
```
Tenez compte des informations suivantes :
- Vous créez l’objet tenantName et la méthode CreateTenant dans une étape ultérieure.
- La propriété Status de l'objet SPRemoteEventResult peut avoir trois valeurs possibles : Continue (par défaut), CancelNoError et CancelWithError. Les deux dernières indiquent à SharePoint de restaurer l'événement.
L’URL du site web hôte, c'est-à-dire le discriminateur client de l’échantillon, fait partie des informations que SharePoint transmet au récepteur dans le paramètre SPRemoteEventProperties. Ajoutez la ligne suivante à la méthode ProcessEvent sur la ligne située juste en dessous de l’initialisation de l’objet SPRemoteEventResult.
```
  string tenantName = properties.AppEventProperties.HostWebFullUrl.ToString();
```
À présent, notre code doit traiter une particularité de la propriété AppEventProperties.HostWebFullUrl. Dans la plupart des autres contextes, SharePoint inclut un caractère "/" de fermeture à la fin de l’URL du site web hôte, afin que la logique de notre exemple de code suppose que ce caractère soit présent. Mais SharePoint ajoute ce caractère à la fin de la valeur HostWebFullUrl si, et seulement si, le site web hôte est le site web racine d’une collection de sites. Notre site web pour Hong Kong étant un sous-site web dans la collection de sites, nous devons ajouter ce caractère pour nous assurer que la même chaîne de nom de client est utilisée dans l’ensemble de l’échantillon.

Ajoutez le code suivant sous l’initialisation de l’objet tenantName.
```
  if (!tenantName.EndsWith("/"))
{
    tenantName += "/";
}
```

Ajoutez l'instruction using suivante en haut du fichier.

  using System.Data.SqlClient;
  using System.Data;
  using ChainStoreWeb.Utilities;

Ajoutez la méthode suivante à la classe AppEventReceiver. Nous n'aborderons pas ce sujet dans le détail, car l'objectif de cette série d'articles consiste à enseigner la programmation de compléments SharePoint, et non la programmation SQL Server/Azure.
```
  private void CreateTenant(string tenantName)
{
    // Do not catch exceptions. Allow them to bubble up and trigger roll back
    // of installation.

    using (SqlConnection conn = SQLAzureUtilities.GetActiveSqlConnection())
    using (SqlCommand cmd = conn.CreateCommand())
    {
        conn.Open();
        cmd.CommandText = "AddTenant";
        cmd.CommandType = CommandType.StoredProcedure;
        SqlParameter name = cmd.Parameters.Add("@Name", SqlDbType.NVarChar);
        name.Value = tenantName;
        cmd.ExecuteNonQuery();
    }//dispose conn and cmd
}
```
Cette méthode crée une ligne dans une table de base de données appelée Clients. En plus de la colonne Nom, la table contient également une colonne Version avec une valeur par défaut définie sur 0000.0000.0000.0000. Dans un prochain article de cette série, vous allez créer une logique de première exécution qui examine cette valeur pour déterminer si le complément a déjà été installé sur le site web hôte. Si la version est 0000.0000.0000.0000, votre code déploie les listes Employés locaux et Livraisons attendues et déclenche ensuite le numéro de version.

Créer le gestionnaire de désinstallation

Il est généralement recommandé de gérer l’événement de désinstallation chaque fois que vous gérez l’événement installé. L’idée de base est que le gestionnaire de désinstallation supprime ou recycle des éléments déployés par le gestionnaire installé. Il existe, toutefois, de nombreuses exceptions, donc vous devez vraiment comprendre les cas d’utilisation de votre complément. Par exemple, une liste déployée avec un complément et remplie avec le complément peut toujours avoir une valeur, même une fois le complément désinstallé, auquel cas vous ne voudrez pas désinstaller la liste dans le gestionnaire d’événements de désinstallation.

L’événement de désinstallation ne s’exécute pas, comme vous pouvez vous y attendre, lorsqu’un utilisateur supprime le complément de page Contenu du site. Cette opération déplace uniquement le complément vers la Corbeille du site web. Un utilisateur peut le restaurer, mais la restauration n’exécute pas de nouveau le gestionnaire d’événements installé, afin que tous les éléments déployés à l’aide de ce dernier existent toujours si le complément est restauré. Les composants SharePoint peuvent être déplacés de la Corbeille vers la Corbeille second niveau. C’est uniquement lorsqu’un complément est supprimé du second niveau que l’événement de désinstallation se produit. Quand un utilisateur fait cela, le complément ne peut pas être restauré, donc nous voulons que le client du magasin de Hong Kong soit supprimé de la base de données d’entreprise à ce stade.

Définissez la valeur de l’option Gérer la désinstallation du Complément sur True. (Il est possible que cette option soit encore intitulée Gérer la désinstallation de l'application.) Ceci enregistre le gestionnaire dans le fichier AppManifest.xml comme vous avez précédemment enregistré le gestionnaire d’installation. Si vous examinez le fichier, vous voyez qu’ils ont exactement la même URL. Les outils de développement Office pour Visual Studio supposent que vous utilisez le même fichier *.svc. Nous effectuons cette procédure dans cet exemple, et c’est une pratique standard.
Ajoutez le code suivant à la place de TODO3 dans le fichier AppEventReceiver.svc.cs.
```
  try
{
    DeleteTenant(tenantName);
 }
catch (Exception e)
{
     // Tell SharePoint to cancel and roll back the event.
    result.ErrorMessage = e.Message;
    result.Status = SPRemoteEventServiceStatus.CancelWithError;
}
```
Tenez compte des informations suivantes :
- La méthode DeleteTenant est ajoutée à l’étape suivante.
- Annuler la désinstallation du complément revient à laisser celui-ci dans la Corbeille second niveau, à partir de laquelle il peut toujours être restauré.

Ajoutez la méthode suivante à la classe AppEventReceiver.

  private void DeleteTenant(string tenantName)
{
    // Do not catch exceptions. Allow them to bubble up and trigger roll back
    // of un-installation (removal from 2nd level Recycle Bin).

    using (SqlConnection conn = SQLAzureUtilities.GetActiveSqlConnection())
    using (SqlCommand cmd = conn.CreateCommand())
    {
        conn.Open();
        cmd.CommandText = "RemoveTenant";
        cmd.CommandType = CommandType.StoredProcedure;
        SqlParameter name = cmd.Parameters.Add("@Name", SqlDbType.NVarChar);
        name.Value = tenantName;
        cmd.ExecuteNonQuery();                
    }//dispose conn and cmd
}

Remarque

Dans un article précédent de cette série, vous avez configuré le projet afin qu’il régénère la base de données d’entreprise à chaque fois que vous appuyez sur F5. Cela permet de vider la table Clients.

Exécuter le complément et tester le gestionnaire d’installation

Utilisez la touche F5 pour déployer et exécuter votre complément. Visual Studio héberge l’application web à distance dans IIS Express et héberge la base de données SQL dans SQL Express. Il effectue une installation temporaire du complément sur votre site SharePoint de test, exécute le gestionnaire d’événements d’installation et exécute immédiatement le complément. Vous êtes invité à accorder des autorisations pour le complément avant l’ouverture de sa page de démarrage.
Lorsque la page d’accueil du complément s’ouvre, sélectionnez l’icône d’engrenage du contrôle Chrome dans la partie supérieure, puis sélectionnez Paramètres du compte.
Sur la page Paramètres de comptes, sélectionnez le bouton Afficher la version du complément. La version apparaît sous 0000.0000.0000.0000.

Figure 1. Page paramètres du compte
Pour terminer la session de débogage, fermez la fenêtre du navigateur ou arrêtez le débogage dans Visual Studio. Chaque fois que vous appuyez sur F5, Visual Studio retire la version précédente du complément et installe la dernière.
Vous allez travailler avec ce complément et la solution Visual Studio dans d’autres articles. Nous vous recommandons donc de retirer le complément une dernière fois quand vous avez terminé de travailler et que vous ne comptez pas le réutiliser pendant un moment. Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions et sélectionnez Retirer.

Étapes suivantes

Dans l'article suivant de cette série, vous allez ajouter une logique de première exécution au complément, ce qui permet de déployer par programmation la liste Employés locaux et le bouton de ruban personnalisé : Ajouter une logique de première exécution au complément hébergé par le fournisseur.

Gérer les événements de complément dans le complément hébergé par le fournisseur

Deux emplacements pour déployer les composants SharePoint de manière programmée

Configurer la solution de débogage pour un récepteur d’événements

Créer le gestionnaire d’installation

Créer le gestionnaire de désinstallation

Exécuter le complément et tester le gestionnaire d’installation

Étapes suivantes

Ressources supplémentaires