CSOM, le Client Object Model SharePoint

CSOM, qui es-tu ?

Le modèle objet client de SharePoint (CSOM, pour Client Side Object Model) est un ensemble d’APIs qui permet d’interagir avec SharePoint en dehors du serveur où est installé SharePoint.

Il se décline sous plusieurs formes :

• Assemblys redistribuables .NET Framework
• Bibliothèque JavaScript
• Points de terminaison REST/OData
• Assemblys Windows Phone
• Assemblys redistribuables Silverlight

Pourquoi l’utiliser ?

Quelques cas pratiques :

1. Votre client a plusieurs sites en production, les serveurs sont hébergés chez un hébergeur distant qui n’est pas disponible aujourd’hui. Malheureusement, le client vous demande de traiter une opération urgente d’import de données dans une liste SharePoint. On pourra donc effectuer notre traitement via un programme console Windows en appelant l’api modèle objet client .NET qui nous fournit une très grande partie de l’api SharePoint.
2. Dans le cas où vous devez pouvoir accéder à votre site  à partir de technologies clientes n’utilisant pas JavaScript ou qui ne seraient pas intégrées aux plateformes .NET Framework , vous avez la possibilité de consommer les entités SharePoint via des requêtes REST. Nous vous avons déjà présenté quelques fonctionnalités ici.

Par effet de mode et surtout de souplesse, très souvent, nous choisissons de nous orienter vers le modèle REST ; c’est pour cela que nous avions opté pour le .Net client object pour consommer les entités de notre SharePoint Online pour notre application CortanaSP.

Comment l’utiliser ?

Pour utiliser le modèle objet client .Net, il faut faire appel aux références : Microsoft.SharePoint.Client.Runtime.dll et Microsoft.SharePoint.Client.dll.

Quelques exemples d’opérations de bases :

• Récupérer des informations d’un site web :

// Tout d'abord récupérer le context, le constructeur a besoin de l'url du site SharePoint.
ClientContext context = new ClientContext("http://urlDeMonSite"); </code>

//le site web SharePoint .
Web web = context.Web;

// On ne récupère que le titre et la description du site
context.Load(web, w => w.Title, w => w.Description);

// Exécution de la requête.
context.ExecuteQuery();

//Ici on ne récupère que le titre du site web et sa description.
// Si on essaie de lire une autre propriété il y aura une erreur
// car la propriété ne sera pas disponible.
label1.Text = web.Title;
label1.Text = web. Description;

• Modification d’un site web :

// Tout d'abord récupérer le context, le constructeur a besoin de l'url du site SharePoint.
ClientContext context = new ClientContext("http://urlDeMonSite"); </code>

//le site web SharePoint .
Web web = context.Web;
web.Title = "mon nouveau titre";
web.Description = "nouvelle description"; 

//A noter qu'ici le web.Update() provoque pas la requête au serveur
//tant que le client n'exécute pas cette dernière avec ExecuteQuery().
web.Update(); 

// Exécution de la requête.
context.ExecuteQuery();

Ce sont deux exemples très basiques qui montrent comment faire utiliser le csom .Net.

Bonnes pratiques :

Mais il faut bien comprendre une bonne pratique :
Le modèle objet client SharePoint .NET Framework vous oblige à utiliser un modèle de programmation semblable à SQL : déclarez ce que vous voulez et exécutez la requête avant d’accéder aux données. Par exemple, le code suivant qui essaie d’afficher le titre du site web SharePoint va générer une exception.

ClientContext context = new ClientContext("http://urlMonSite"); 

Web web = context.Web;
label1.Text = web.Title;

Ce code provoque une erreur car le code du modèle objet client SharePoint .NET Framework doit :

1. Générer une requête SQL ou une procédure stockée ad hoc.
2. Exécuter la requête SQL
3. Lire les résultats à partir d’SQL.

Lorsque vous appelez une méthode, vous générez une requête. Toutes les données ne sont envoyées au serveur que lorsque vous allez exécuter la requête à l’aide de la méthode ExecuteQuery()

ClientContext context = new ClientContext("http://SiteUrl");
Web web = context.Web;
context.Load(web, w => w.Title);
context.ExecuteQuery();
label1.Text = web.Title;

Deux lignes qui font la difference :

context.Load(web, w => w.Title);
context.ExecuteQuery();</pre>

La première crée une requête pour la propriété “Title”, et la seconde exécute la requête.

Subtilités Windows Universal App :

Pour notre projet Cortana et SP, nous avons créé une application Windows Universal App (WUA). Dans ce cas précis, .Net Client n’est pas pertinent. Microsoft met à disposition une librairie plus appropriée : Microsoft.SharePoint.Client.Portable

Attention : l’utilisation de cette librairie pour une application mobile diffère quelque peu.

 using (ClientContext context = new ClientContext(siteUrl))
 {
      //Récupération des crédentiels de connection.
      SharePointOnlineCredentials credentials = new SharePointOnlineCredentials(login, mdp);
      context.Credentials = credentials;
      Web web = context.Web;
      ListItemCollection listItemCollection = web.Lists.GetByTitle(listName).GetItems(CamlQuery.CreateAllItemsQuery());
      context.Load(listItemCollection);

       await context.ExecuteQueryAsync().ContinueWith((t) =>
       {
          foreach (var item in listItemCollection)
          {
           CortanaItem ci = new CortanaItem();
           ci.Id = item.FieldValues["ID"] != null ? item.FieldValues["ID"].ToString() : string.Empty;
           ci.Title = item.FieldValues["Title"] != null ? item.FieldValues["Title"].ToString() : string.Empty;
           ci.LastModifiedDate = item.FieldValues["Modified"] != null ? item.FieldValues["Modified"].ToString() : string.Empty;
           ci.Url = item.FieldValues["FileRef"] != null ? item.FieldValues["FileRef"].ToString() : string.Empty;
           cortanaItems.Add(ci);
           }
      });
 }

 LoadDataCompleted(cortanaItems); // Fire event DataLoadCompleted

En effet, la requête doit être asynchrone dans notre cas car nous sommes sur un client Windows Phone. Il va donc falloir attendre le retour de la requête avant de pouvoir en exploiter son résultat.

Le modèle objet SharePoint .Net client est très complet et permet de consommer nos entités SharePoint pratiquement aussi aisément que le modèle objet SharePoint Server (SSOM). Il est d’usage assez fastidieux et les exemples ne sont pas nombreux. Il convient de bien organiser son code afin de ne pas surcharger les requêtes.