Déployer par programme un bouton personnalisé dans le complément hébergé par un fournisseur

Article
04/08/2023

Cet article est le neuviè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 BeforeProgrammaticButton.sln.

Dans cet article, vous allez découvrir comment inclure un bouton de ruban personnalisé dans un complément SharePoint lorsque la liste dont le ruban reçoit le bouton est elle-même déployée par programmation dans le même complément.

Rajouter le bouton personnalisé au projet

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’article précédent, vous avez supprimé le bouton de ruban personnalisé AddEmployeeToCorpDB du projet. Ajoutez-le à nouveau en suivant les étapes ci-dessous.

Sur la barre d’outils en haut de l’ l’Explorateur de solutions, sélectionnez le bouton Afficher tous les fichiers

Figure 1. barre d’outils Explorateur de solutions
Dans le projet ChainStore, cliquez avec le bouton droit sur AddEmployeeToCorpDBe, puis sélectionnez Inclure dans le projet.
Sélectionnez le bouton Afficher tous les fichiers.
Dans le projet ChainStore, développez AddEmployeeToCorpDB, puis ouvrez le fichier elements.xml.

Comprendre un problème et sa solution

Dans le fichier elements.xml, l'attribut RegistrationId de l'élément CustomAction identifie la liste comportant le ruban auquel le bouton est ajouté : {$ListId:Lists/Local Employees;}. Cette méthode fonctionne bien lorsque la liste a déjà été ajoutée manuellement au site web hôte. Cependant, étant donné que nous déployons la liste par programmation dans une logique de première exécution, la liste n'existe pas lorsque SharePoint installe le complément et essaie de déployer le bouton. L’installation de la macro complémentaire génèrerait une exception et échouerait.

Le déploiement de la liste dans le gestionnaire d’événements d’installation à la place de la logique de première exécution ne permet pas de résoudre le problème, car SharePoint déploie des composants personnalisés définis par une description, tels que le bouton personnalisé (et le composant de complément Passer une commande), avant d’exécuter le gestionnaire personnalisé. Par conséquent, la liste n’existe pas lorsque SharePoint tente de déployer le bouton.

La création d’un bouton personnalisé entièrement par programme n’est pas possible pour des raisons trop complexes à expliquer ici. Heureusement, ce n'est pas nécessaire. Il existe une façon relativement simple de créer un bouton personnalisé par semi-programmation et de l'affecter à une liste personnalisée.

Voici les étapes de base à suivre :

Conservez le bouton défini par une description dans le projet, mais affectez-le au ruban d'un élément qui se trouve toujours sur tous les sites SharePoint, au lieu d'une liste déployée par programmation avec le même complément.
Dans la logique de première exécution, une fois que la liste a été créée par programmation, ajoutez par programmation un bouton non défini au ruban de la liste.
Initialisez les propriétés du nouveau bouton avec les valeurs du bouton d'origine. À ce stade, il existe deux boutons identiques. Le deuxième est attribué au ruban de la liste Employés locaux.
Supprimez le bouton d’origine par programme.

Inscription par programmation du bouton personnalisé

La procédure suivante montre comment mettre en œuvre cette stratégie.

Dans le projet ChainStore, développez AddEmployeeToCorpDB, ouvrez le fichier elements.xml, puis modifiez la valeur de l’attribut RegistrationId de l’élément CustomAction à « 100 ». Il s’agit de l’ID d’un type de liste. Même s’il n’existe aucune instance de liste de ce type sur le site web, la liste type se trouve sur chaque site web SharePoint. L'attribut doit désormais se présenter comme suit.
```
  RegistrationId="100"
```
Dans le fichier SharePointComponentDeployer.cs, ajoutez la ligne suivante à la méthode DeployChainStoreComponentsToHostWeb, juste sous la ligne qui appelle CreateLocalEmployeesList (vous allez créer cette méthode à l’étape suivante).
```
  ChangeCustomActionRegistration();
```

Ajoutez la méthode suivante à la classe SharePointComponentDeployer.

   private static void ChangeCustomActionRegistration()
 {
     using (var clientContext = sPContext.CreateUserClientContextForSPHost())
     {
 	 var query = from action in clientContext.Web.UserCustomActions
 		     where action.Name == "{button_GUID} .AddEmployeeToCorpDB"
 		     select action;
 	  IEnumerable<UserCustomAction> matchingActions = clientContext.LoadQuery(query);	       
 		 clientContext.ExecuteQuery();

 	  UserCustomAction webScopedEmployeeAction = matchingActions.Single();

 	 // TODO8: Get a reference to the (empty) collection of custom actions 
 	 // that are registered with the custom list.

 	 // TODO9: Add a blank custom action to the list's collection.

 	 // TODO10: Copy property values from the descriptively deployed
 	 // custom action to the new custom action

 	// TODO11: Delete the original custom action.         

 	  clientContext.ExecuteQuery();
     }
 }

Tenez compte des informations suivantes :

Étant donné que l'action personnalisée (en d'autres termes, le bouton personnalisé) a été inscrite auprès du ruban d'une liste type, sa portée s'étend à l'ensemble du site et elle se trouve dans la collection d'actions personnalisées du site. Le code peut ainsi la récupérer à partir de cette collection.
La valeur de provient action.Name de l’attribut ID de l’élément CustomAction dans le fichier elements.xml dans AddEmployeeToCorpDB.

Importante

Vous devez modifier la valeur action.Name dans le code pour correspondre à la valeur dans votre fichier elements.xml. Le composant GUID du nom sera différent. Notez qu’un caractère "." se trouve entre le GUID et le reste du nom. Voici un exemple de ligne :

where action.Name == "4a926a42-3577-4e02-9d06-fef78586b1bc.AddEmployeeToCorpDB"

Remplacez TODO8 par le code suivant. Lorsque vous retirez un complément, les composants créés par le complément ne sont pas supprimés. Une fois votre logique de première exécution exécutée, une action personnalisée se trouvera dans la collection UserCustomActions de la liste et elle ne sera pas être retirée la prochaine fois que vous sélectionnerez F5. Pour éviter toute confusion, la dernière ligne de ce code listActions.Clear(); vide la collection.
```
 var queryForList = from list in clientContext.Web.Lists
 		   where list.Title == "Local Employees"
 		   select list;
 IEnumerable<List> matchingLists = clientContext.LoadQuery(queryForList);
 clientContext.ExecuteQuery();

 List employeeList = matchingLists.First();
 var listActions = employeeList.UserCustomActions;
 clientContext.Load(listActions);
 listActions.Clear();
```
Remplacez TODO9 par la ligne suivante, qui ajoute une action personnalisée non définie à la liste Employés locaux.
```
  var listScopedEmployeeAction = listActions.Add();
```
Remplacez TODO10 par le code suivant.
```
 listScopedEmployeeAction.Title = webScopedEmployeeAction.Title;
 listScopedEmployeeAction.Location = webScopedEmployeeAction.Location;
 listScopedEmployeeAction.Sequence = webScopedEmployeeAction.Sequence;
 listScopedEmployeeAction.CommandUIExtension = webScopedEmployeeAction.CommandUIExtension;
 listScopedEmployeeAction.Update();
```
Tenez compte des informations suivantes :
- Il attribue les valeurs de propriété du bouton d'étendue web (qui a été déployé avec un balisage descriptif) aux propriétés correspondantes du bouton d'étendue de liste afin que les deux boutons soient identiques, sauf en matière d'étendue.
- La propriété Sequence spécifie l'ordre relatif d'affichage du bouton dans la zone du ruban. Dans ce cas, le bouton se trouve dans la section Actions de l’onglet Éléments du ruban. Dans le balisage descriptif, cette valeur a été définie sur 10001, qui est suffisamment élevé pour vous assurer qu’elle apparaîtra après (autrement dit, à droite de) un bouton prêt à l’emploi que SharePoint place lui-même dans la section Actions du ruban.
Remplacez TODO11 par la ligne suivante, ce qui supprime le bouton défini de façon descriptive d’origine. Si nous n’avions pas cette ligne, chaque liste sur le site web qui utilise le modèle de liste « 100 » comporterait un bouton personnalisé. Étant donné que la fonctionnalité du bouton est étroitement liée à la liste Employés locaux, il ne servirait à rien que le bouton se trouve sur une autre liste. En outre, sans cette ligne, le bouton apparaîtrait deux fois sur la liste Employés locaux, car cette liste utilise le modèle « 100 ».
```
  webScopedEmployeeAction.DeleteObject();
```

L’ensemble de la méthode doit désormais se présenter comme suit (à l’exception de l’espace réservé qui doit être remplacé par un GUID).

   private static void ChangeCustomActionRegistration()
 {
     using (var clientContext = SPContext.CreateUserClientContextForSPHost())
     {
 	 var query = from action in clientContext.Web.UserCustomActions
 		     where action.Name == "{button_GUID} .AddEmployeeToCorpDB"
 		     select action;
 	  IEnumerable<UserCustomAction> matchingActions = clientContext.LoadQuery(query);	       
 		 clientContext.ExecuteQuery();

 	  UserCustomAction webScopedEmployeeAction = matchingActions.Single();

 	 var queryForList = from list in clientContext.Web.Lists
 			    where list.Title == "Local Employees"
 			    select list;
 	 IEnumerable<List> matchingLists = clientContext.LoadQuery(queryForList);
 	 clientContext.ExecuteQuery();

 	List employeeList = matchingLists.First();
 	var listActions = employeeList.UserCustomActions;
 	clientContext.Load(listActions);
 	listActions.Clear();

 	var listScopedEmployeeAction = listActions.Add();

 	listScopedEmployeeAction.Title = webScopedEmployeeAction.Title;
 	listScopedEmployeeAction.Location = webScopedEmployeeAction.Location;
 	listScopedEmployeeAction.Sequence = webScopedEmployeeAction.Sequence;
 	listScopedEmployeeAction.CommandUIExtension = webScopedEmployeeAction.CommandUIExtension;
 	listScopedEmployeeAction.Update();

 	webScopedEmployeeAction.DeleteObject();         

 	clientContext.ExecuteQuery();
     }
 }

Demander un contrôle total sur le site web hôte

Étant donné que le complément ajoute et supprime désormais des actions personnalisées à étendue web, nous devons passer les autorisations demandées par le complément du statut de gestion au statut de contrôle total :

Dans l' Explorateur de solutions, ouvrez le fichier AppManifest.xml dans le projet ChainStore.
Ouvrez l’onglet Autorisations. Laissez la valeur Portée définie sur Web, mais dans le champ Autorisation, sélectionnez Contrôle total dans la liste déroulante.
Enregistrez le fichier.

Exécuter le complément et tester le déploiement de bouton

Ouvrez la page Contenu du site du site web de la boutique de Hong Kong et supprimez la liste Employés locaux.

Remarque

Le retrait d’un complément dans Visual Studio ne supprime pas les listes créées par le complément. Vous devez donc le supprimer manuellement chaque fois que vous testez le code qui le crée.
Utilisez la touche F5 pour déployer et exécuter votre complément. Visual Studio héberge l’application web distante 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 et exécute immédiatement celui-ci. Vous êtes invité à accorder des autorisations au complément avant l'ouverture de sa page d'accueil.
Lorsque la page d'accueil du complément s'ouvre, sélectionnez le lien Retour au site sur le contrôle Chrome dans la partie supérieure.
Accédez à la page Contenu du site. La liste Employés locaux est à cet endroit, car votre logique de première exécution l’a ajoutée ici.

Remarque

Si la liste n'est pas là ou si d’autres indications montrent que le code de première exécution n’est pas en cours d’exécution, il se peut que la table Clients ne reprenne pas un état vide lorsque vous sélectionnez F5. La raison la plus fréquente de ce problème est que le projet ChainCorporateDB n’est plus défini comme un projet de démarrage dans Visual Studio. Consultez la note dans la partie supérieure de cet article pour savoir comment résoudre ce problème. En outre, vérifiez que vous avez configuré la base de données à reconstruire comme décrit dans Configurer Visual Studio pour reconstruire la base de données d’entreprise avec chaque session de débogage.
Ouvrez la liste et ajoutez un élément.
Dans l’affichage de liste, sélectionnez l’élément, puis ouvrez l’onglet Élément du ruban.
Dans l’onglet Élément, sélectionnez le bouton Ajouter à la base de données d’entreprise. L’employé est ajouté à la base de données d’entreprise et le champ Ajouté à la base de données d’entreprise est défini sur Oui.
Accédez à la page Contenu du site et sélectionnez Ajouter un complément.
Ajoutez une nouvelle Liste personnalisée. Par défaut, elle sera de type « Générique » (Générique est le type de liste 100). Une fois la liste créée, ouvrez l’onglet Élément du ruban. Notez que le bouton Ajouter à la base de données d’entreprisen’est pas sur le ruban. C’est parce que votre code a supprimé le bouton de portée web.
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

Les événements des listes et des éléments de liste peuvent également avoir des gestionnaires personnalisés dans SharePoint. Vous apprendrez comment en créer un et le déployer dans votre logique de première exécution dans la rubrique Gérer les événements d’élément de liste dans le complément hébergé par le fournisseur.