Obtenir un aperçu rapide du modèle objet SharePoint

  • Article

Cet article est le quatriè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, vous allez cesser de coder pendant un court instant pour découvrir rapidement le modèle objet côté client SharePoint (CSOM). Ce modèle est largement documenté sur MSDN avec des rubriques de référence, des procédures et des exemples de code. Dans cet article, nous pouvons fournir uniquement un aperçu, mais nous pensons qu’une présentation, aussi brève soit-elle, vous permettra de beaucoup mieux comprendre le code que vous allez rencontrer dans les articles suivants.

Hiérarchie de contenu

Le tableau ci-dessous présente la hiérarchie de contenu dans SharePoint et les classes CSOM qui le représentent. Toutes ces entités ont des enfants, qui sont du premier type inférieur.

Entité Classe Remarques
Batterie de serveurs SharePoint locale ou abonnement SharePoint Online (également appelé client) Dans un CSOM, l'accès à ce niveau est uniquement limité par programmation. Par exemple, il n'existe aucune classe de batterie, d'abonnement ou de client. (Le modèle objet côté serveur SharePoint, qui ne peut pas être utilisé dans les compléments, permet d'accéder par programmation à ces entités.)
collection de sites Site Collection de sites web regroupés pour des raisons essentiellement administratives, ainsi que pour héberger des composants SharePoint, tels que des pages maîtres ou des groupes de sécurité personnalisés, qui peuvent être appliqués à l’ensemble des sites enfant. Tous les sites appartiennent à la même collection de sites.
site web Web Ensemble de pages et de composants SharePoint. Peut avoir des sous-sites web.
liste List Les bibliothèques de documents et d'autres types de bibliothèques de fichiers sont également à ce niveau. Une bibliothèque de documents est un type spécial de liste dans laquelle chaque ligne comprend un document joint. Les autres colonnes sont des données sur le document, comme son auteur, la date de sa dernière modification et la personne l'ayant vérifié.
élément de liste ListItem Ligne d'une liste comportant des valeurs particulières dans les champs de la ligne. Elle a aussi un type. Voir la ligne suivante.
élément de liste Content Type Type d'un élément de liste. Ces éléments sont représentés par la classe ContentType. Chacun constitue essentiellement un ensemble de colonnes et de métadonnées. Le plus simple est le type de contenu intégré Item. Tous les autres types de contenu sont dérivés du type Item. SharePoint inclut de nombreux types de contenu intégrés, tels que Événement et Annonce.
colonne Field Un objet Field n'inclut pas seulement des informations sur le type de données sous-jacent, mais également des informations sur la façon dont les données sont mises en forme et affichées sur les formulaires, tels que les formulaires pour la création, l'affichage et la modification d'éléments de liste spécifiques.

Vous pouvez créer des listes personnalisées, des types de contenu, des types de colonnes et des éléments de liste par programmation.

En plus du contenu, le CSOM vous permet d’avoir accès aux utilisateurs, groupes, rôles et autorisations, à la taxonomie, la recherche, et bien plus.

Exécution côté client et traitement par lot

Le CSOM utilise un système de traitement par lot. Des fragments de code géré sont convertis en XML et envoyés au serveur dans une seule requête HTTP. Pour chaque commande, un appel de modèle objet côté serveur correspondant est réalisé, et le serveur renvoie une réponse au client au format JSON (JavaScript Object Notation).

Le code SharePoint sur un client commence par récupérer un objet de contexte client qui représente le contexte de la demande actuelle, y compris l’identité du site web SharePoint (et sa collection de sites parent). Grâce à ce contexte, vous pouvez accéder aux objets CSOM. Le code suivant représente la structure de base que vous verrez très souvent.

  using (var clientContext = spContext.CreateUserClientContextForSPHost())
  {
      // CRUD operation or query code goes here.

      clientContext.ExecuteQuery();
  }

Notez ce qui suit à propos de ce code :

  • L’objet spContext est de type SharePointContext et est défini dans le fichier SharePointContext.cs (ou .vb) qui est généré par les outils de développement Office pour Visual Studio. Ce fichier peut être modifié, mais il est rare que vous deviez le faire. Pour la plupart des projets de complément SharePoint, ce fichier et le fichier TokenHelper.cs (ou .vb), qui sont également générés par les outils, fonctionnent en tant qu’extensions du CSOM lui-même.

  • L’objet clientContext est le type CSOM ClientContext.

  • La méthode ExecuteQuery regroupe le code d’opération CRUD et un message XML qu’elle envoie au serveur SharePoint. Une fois sur le serveur, ce code est traduit en code de modèle objet côté serveur et exécuté.

Vous avez vu un exemple de ce modèle dans l’article précédent de cette série, dans la méthode GetLocalEmployeeName présentée ci-dessous.

private string GetLocalEmployeeName()
{
    ListItem localEmployee;

    using (var clientContext = spContext.CreateUserClientContextForSPHost())
    {
        List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
        localEmployee = localEmployeesList.GetItemById(listItemID);
        clientContext.Load(localEmployee);
        clientContext.ExecuteQuery();
    }
    return localEmployee["Title"].ToString();
}

Notez les points suivants concernant cette méthode :

  • Les deux premières lignes du bloc using s'affichent pour obtenir des références à la liste et l'objet d'élément de liste. En réalité, lorsque ces lignes s'exécutent dans l'exécution côté client SharePoint, elles sont simplement converties au format XML. La méthode ExecuteQuery envoie ce code XML au serveur.

  • La méthode Load ajoute un élément supplémentaire au message : elle indique au serveur d'envoyer l'objet spécifié au client. La méthode ExecuteQuery reçoit cet objet (en tant que JSON) et l’utilise pour initialiser la variable côté client localEmployee. Le code côté client à la suite fait référence à l’objet ListItem et ses membres. Comme vous pouvez le constater, la ligne suivante fait référence à la valeur du champ "Title" de l’élément. Cette ligne aurait généré une exception si la méthode Load n’avait pas été appelée, car l’objet n’existe pas vraiment côté client jusqu’à ce qu’il soit chargé.

Étapes suivantes

Dans l’article suivant, nous allons revenir au codage et allons apprendre à ajouter des opérations d’écriture SharePoint au complément hébergé par un fournisseur.