Ajouter des opérations d’écriture SharePoint au complément hébergé par le fournisseur

Article
04/08/2023

Cet article est le cinquiè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 BeforeSharePointWriteOps.sln.

Dans cet article, nous reprenons le codage en ajoutant certaines fonctions d’écriture de données dans le complément SharePoint Chain Store.

Modifier une valeur de colonne dans un élément de liste SharePoint

Notre complément dispose d’un bouton de ruban personnalisé qui ajoute un employé de la liste Employés locaux du magasin de Hong Kong à la base de données d’entreprise. Mais l’utilisateur doit se souvenir de modifier manuellement la valeur du champ Ajouté à la base de données d’entreprise sur Oui. Nous allons ajouter du code pour que cette opération soit réalisée automatiquement.

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.
Vérifiez que les trois projets sont définis sur Démarrer dans la colonne Action.

Dans Explorateur de solutions, ouvrez le fichier EmployeeAdder.aspx.cs.
Ajoutez la ligne suivante à la méthode Page_Load entre l’appel de AddLocalEmployeeToCorpDB et l’appel de Response.Redirect. Dans l’étape suivante, vous créez la méthode SetLocalEmployeeSyncStatus.
```
   // Write to SharePoint
 SetLocalEmployeeSyncStatus();
```
Ajoutez la nouvelle méthode suivante à la classe EmployeeAdder.
```
   private void SetLocalEmployeeSyncStatus()
 {
     using (var clientContext = spContext.CreateUserClientContextForSPHost())
     {
         List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
         ListItem selectedLocalEmployee = localEmployeesList.GetItemById(listItemID);
         selectedLocalEmployee["Added_x0020_to_x0020_Corporate_x"] = true;
         selectedLocalEmployee.Update();
         clientContext.ExecuteQuery();
     }
 }
```
Tenez compte des informations suivantes :
- The internal name for the Added to Corporate DB field is odd-looking. Internal field names cannot contain spaces, so when a user creates a field with spaces in its display name, SharePoint substitutes the string "x0020" for each space when it sets the internal name. This turns "Added to Employee DB" into "Added_x0020_to_x0020_Corporate_x0020_DB". Les noms internes ne peuvent pas comporter plus de 32 caractères, c’est pourquoi le nom est tronqué à seulement « Ajouté_x0020_à_x0020_la_x0020_ba ».
- Bien que la colonne Ajouté à la base de données d’entreprise soit appelée un champ Oui/Non dans l’interface utilisateur SharePoint, il s’agit en réalité d’une valeur booléenne, c’est pourquoi sa valeur est définie sur true, et non sur Oui.
- La méthode Update de la classe ListItem doit être appelée pour valider les modifications apportées à la base de données de contenu SharePoint. D'une manière générale mais pas universelle, lorsque vous modifiez une valeur de propriété d'un objet stocké dans les bases de données SharePoint, vous devez appeler la méthode Update de l'objet.

Demander l’autorisation d’écrire la liste web hôte

Étant donné que le complément peut désormais non seulement lire la liste, mais aussi écrire dedans, nous devons passer les autorisations demandées par le complément du statut de lecture à celui d'écriture. Procédez comme suit.

Dans l' Explorateur de solutions, ouvrez le fichier AppManifest.xml dans le projet ChainStore.
Ouvrez l’onglet Autorisations et dans le champ Autorisation, sélectionnez Écriture dans le menu déroulant.
Enregistrez le fichier.

Exécution du complément et test du bouton

Appuyez sur 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 pour le complément avant l’ouverture de sa page de démarrage.
Dans le formulaire d’autorisations, sélectionnez Employés locaux dans la liste, puis Approuver.
Lorsque la page d'accueil du complément s'ouvre, cliquez sur Retour au site sur le contrôle Chrome dans la partie supérieure.
Dans la page d’accueil du site Web, accédez à Contenu du site>Employés locaux. La page en mode liste s’ouvre.
Si la liste ne comporte aucun employé dont la colonne Ajouté à la base de données d’entreprise est définie sur Non, ajoutez un employé à la liste, et n’activez pas la case à cocher Ajouté à la base de données d’entreprise.
Sur le ruban, ouvrez l’onglet Éléments. Dans la section Actions de l’onglet, vous trouverez le bouton personnalisé Ajouter à la base de données d’entreprise.
Dans la liste, sélectionnez un employé dont la colonne Ajouté à la base de données d'entreprise est définie sur Non.
Sélectionnez le bouton Ajouter à la base de données d’entreprise. (Vous devez d’abord sélectionner un élément.)
Il vous semble que la page se recharge, car la méthode Page_Load de la page EmployeeAdder vous redirige vers elle. La valeur du champ Ajouté à la base de données d’entreprise pour l’employé se transforme en Oui.

Remarque

Qu’est-ce qui empêche un utilisateur de modifier manuellement la valeur Ajoutée à la base de données d’entreprise d’une manière qui rend la liste et la base de données d’entreprise incohérentes ? Rien ne fait pour le moment. Vous trouverez la solution à ce problème dans un article ultérieur de cette série.

1.To mettre fin à la session de débogage, fermez la fenêtre du navigateur ou arrêtez le débogage dans Visual Studio. Quand vous appuyez sur F5, Visual Studio retire la version précédente du complément et installe la dernière. 1.Cliquez avec le bouton droit sur le projet dans Explorateur de solutions, puis sélectionnez Retirer.

Créer une nouvelle liste personnalisée sur le site web hôte

L’amélioration suivante apportée au complément Chain Store consiste à créer des éléments dans une liste, au lieu de simplement modifier un champ dans un élément existant. Plus précisément, lorsqu’une nouvelle commande est passée au niveau de l’entreprise, un élément est automatiquement créé dans une liste SharePoint pour avertir les employés locaux qu’ils doivent attendre une livraison. La liste est appelée Livraisons attendues et vous la créez en suivant les étapes ci-dessous. Dans un prochain article de cette série, vous découvrirez comment ajouter par programmation une liste personnalisée à un site web hôte, mais pour l’instant vous ajouterez celui-ci manuellement.

À partir de la page d’accueil du magasin Fabrikam Hong Kong, accédez à Contenu du site>Ajouter un complément>Liste personnalisée.
Dans la boîte de dialogue Ajout d’une liste personnalisée, indiquez Livraisons attendues comme nom et sélectionnez Créer.
Sur la page Contenu du site, ouvrez la liste Livraisons attendues.
Dans le ruban, sur l’onglet Liste, sélectionnez Paramètres de la liste.
Dans la section Colonnes de la page Paramètres de liste, sélectionnez la colonne Titre.
Dans le formulaire Modifier la colonne, indiquez Produit au lieu de Titre comme nom de la colonne, puis sélectionnez OK.
Sur la page Paramètres, sélectionnez Créer une colonne.

Dans un précédent article de cette série, vous avez appris à créer des colonnes personnalisées pour une liste. Pour la liste Livraisons attendues, ajoutez quatre colonnes à l'aide des valeurs du tableau suivant. Laissez tous les autres paramètres sur leurs valeurs par défaut.

Nom de colonne	Type	Obligatoire ?	Valeur par défaut
Fournisseur	Une seule ligne de texte	Non requis	Aucun
Quantité	Number	Obligatoire	1
Arrivé	Oui/Non	Non requis	Non
Ajouté à l'inventaire	Oui/Non	Non requis	Non

Après avoir créé les colonnes, sur la page des paramètres de liste, sélectionnez Contenu du site pour ouvrir la page Contenu du site. Ouvrez la liste Livraisons attendues.
Sélectionnez nouvel élément. Le formulaire de création d’élément doit se présenter exactement comme suit, y compris les deux astérisques indiquant les champs obligatoires.

Figure 1. Formulaire de création d’élément pour la liste Expéditions attendues
Nous ne voulons pas créer manuellement des éléments dans cette liste, donc cliquez sur Annuler.

Insérer un élément dans une liste SharePoint

Maintenant, ajoutez une fonction au complément qui permet de créer un élément dans la liste Livraisons attendues à chaque fois qu'une commande est passée pour le magasin de Hong Kong au niveau de l'entreprise.

Dans l' Explorateur de solutions, ouvrez le fichier OrderForm.aspx.cs.
Ajoutez une instruction using pour l'élément Microsoft.SharePoint.Client en haut du fichier.
Dans la méthode btnCreateOrder_Click, ajoutez la ligne suivante juste en dessous de l’appel vers CreateOrder. Vous créerez la méthode CreateExpectedShipment dans l’étape suivante.
```
  CreateExpectedShipment(txtBoxSupplier.Text, txtBoxItemName.Text, quantity);
```
Ajoutez la méthode suivante à la classe OrderForm.
```
private void CreateExpectedShipment(string supplier, string product, UInt16 quantity)
{
  using (var clientContext = spContext.CreateUserClientContextForSPHost())
  {
    List expectedShipmentsList = clientContext.Web.Lists.GetByTitle("Expected Shipments");
    ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
    ListItem newItem = expectedShipmentsList.AddItem(itemCreateInfo);
    newItem["Title"] = product;
    newItem["Supplier"] = supplier;
    newItem["Quantity"] = quantity;
    newItem.Update();
    clientContext.ExecuteQuery();
  }
}
```
Tenez compte des informations suivantes à propos de ce code :
- Un objet ListItem n’est pas créé avec un constructeur. Ceci, pour des raisons de performance. Un objet ListItem comporte de nombreuses propriétés (avec des valeurs par défaut). Si un constructeur est utilisé, l’intégralité de l’objet serait inclus dans le message XML que la méthode ExecuteQuery envoie au serveur.
- L’objet ListItemCreationInformation est un objet léger qui contient uniquement les valeurs minimales qui ne sont pas par défaut dont le serveur a besoin pour créer un objet ListItem. Il peut sembler qu’il existe une ligne créant un objet ListItem, mais n’oubliez pas que cette ligne ajoute uniquement certaines marques XML à un message envoyé au serveur. L’objet ListItem est créé sur le serveur.
- Il est inutile de renvoyer l’objet ListItem au client, donc il n’existe aucun appel à la méthode ClientContext.Load.
- Le code ne doit pas définir explicitement les champs Arrivé ou Ajouté à l’inventaire, car ils sont définis sur leur valeur par défaut Non qui correspond à ce que nous souhaitons.

Recherche de composants supprimés

Toute personne disposant des privilèges de propriétaire de liste pour une liste SharePoint peut supprimer la liste. Si la liste est déployée sur le site web hôte par un complément, le propriétaire du site web hôte peut la supprimer. Cela peut arriver si le propriétaire décide de travailler sans la fonctionnalité fournie par la liste. (Elle peut être restaurée à partir de la Corbeille SharePoint si le propriétaire change d'avis.)

La méthode CreateExpectedShipment dépend de l’existence de la liste Livraisons attendues. Supposons que le propriétaire du site web a décidé de supprimer la liste. Plus tard, lorsqu’une commande est ajoutée avec le complément Formulaire de commande, la méthode CreateExpectedShipment est appelée et lève une exception dont le message indique qu’il n’y a aucune liste Livraisons attendues sur le site web SharePoint.

Vous souhaiterez peut-être que la méthode vérifie la nullité de expectedShipmentsList avant d’en faire quoi que ce soit. Lorsque vous utilisez CSOM, vous ne pouvez pas effectuer cette vérification avec une structure simple comme celle-ci :

if (expectedShipmentsList != null) { ... }

Au lieu de cela, vous devez utiliser une classe CSOM spéciale appelée ConditionalScope. Les raisons de cela sont liées au système de traitement par lots CSOM, ce qui a été mentionné dans l’article précédent de cette série (voir Exécution côté client et traitement par lots). ConditionalScope et le système le traitement par lots sont des rubriques avancées qui n’entrent pas dans le cadre de cette série, mais vous devriez consulter la documentation de MSDN à leur sujet après avoir suivi cette série de didacticiels.

Vous pouvez vérifier l’existence d’une liste d’une autre façon, comme suit : au lieu d’utiliser la méthode GetByTitle pour obtenir une référence à la liste, vous pouvez vérifier si une liste avec le nom spécifié existe dans la « liste des listes » du site web avec du code en procédant comme suit.

var query = from list in clientContext.Web.Lists 
             where list.Title == "Expected Shipments" 
             select list; 
IEnumerable<List> matchingLists = clientContext.LoadQuery(query); 
clientContext.ExecuteQuery(); 
if (matchingLists.Count() != 0) 
{ 
  List expectedShipmentsList = matchingLists.Single(); 
  // Do something with the list. 
}
clientContext.ExecuteQuery();

Le code précédent a l’avantage de vous permettre d’éviter les complications de la classe ConditionalScope et nous utilisons exactement ce code ailleurs dans cette série d’articles. Toutefois, il présente un inconvénient : ce code nécessite un appel supplémentaire de ExecuteQuery uniquement pour obtenir la valeur que vous voulez vérifier dans l’instruction if.

Si nous utilisons cette technique dans la méthode CreateExpectedShipment pour vérifier l’existence de la liste, cette méthode doit comporter deux appels de ExecuteQuery, chacun effectuant une requête HTTP à partir du serveur web distant vers SharePoint. Ces requêtes constituent la partie la plus fastidieuse d’une méthode CSOM, il est donc généralement recommandé de les réduire.

Nous laisserons la méthode CreateExpectedShipment telle quelle, mais dans un complément de production, vous devez réfléchir à la façon dont votre code va fonctionner si un composant qu’il référence est supprimé. La restauration par programme de la liste de la Corbeille est une option, mais elle ennuierait les utilisateurs qui ont intentionnellement décidé de supprimer la liste.

Vous devez également tenir compte du fait que ne rien faire du tout pour empêcher l’exception pourrait constituer le meilleur choix. Une exception à partir de SharePoint préviendrait les utilisateurs que la suppression de la liste a détruit une partie du complément, ce que la personne qui l’a supprimé n’avait peut-être pas réalisé. Un utilisateur peut ensuite décider de restaurer la liste à partir de la Corbeille ou de continuer sans la partie du complément qui ne fonctionne plus.

Demander l’autorisation de gérer le site web

Rappelez-vous que lorsqu’un complément demande une autorisation de lecture ou d’écriture avec l’étendue de liste, SharePoint invite l’utilisateur à approuver le complément et la boîte de dialogue contient une liste déroulante dans laquelle l’utilisateur sélectionne la liste à laquelle le complément doit recevoir l’accès. Vous ne pouvez sélectionner qu'une seule liste. Toutefois, le complément Chain Store peut désormais écrire dans deux listes différentes. Pour avoir accès à plusieurs listes, le complément doit demander une autorisation à étendue web. Suivez les étapes ci-dessous :

Dans l' Explorateur de solutions, ouvrez le fichier AppManifest.xml dans le projet ChainStore.
Ouvrez l’onglet Autorisations et dans le champ Étendue, sélectionnez Web dans la liste déroulante.
Dans le champ Autorisation, sélectionnez Écriture dans la liste déroulante.
Enregistrez le fichier.

Exécution du complément et test de la création d'élément

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 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 le lien Formulaire de commande au bas de la page.
Saisissez des valeurs dans le formulaire et sélectionnez Passer une commande.
Utilisez le bouton de retour du navigateur pour revenir à la page d’accueil, puis sélectionnez Retour au site sur le contrôle Chrome dans la partie supérieure.
À partir de la page d’accueil du magasin de Hong Kong, accédez à la page Contenu du site et ouvrez la liste Livraisons attendues. Il existe désormais un élément dans la liste correspondant à la commande. La capture d'écran suivante présente un exemple :

Figure 2. Liste des expéditions attendues avec un seul élément
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.
Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions et sélectionnez Retirer.

Étapes suivantes

Dans le prochain article, vous allez apprendre à faire apparaître le formulaire de commande distant comme un composant WebPart dans une page SharePoint : Inclure un composant de complément dans le complément hébergé par le fournisseur.