Effectuer des opérations de base avec du code de bibliothèque client dans SharePoint

Article
04/08/2023

Vous pouvez utiliser le modèle objet client (CSOM) SharePoint pour récupérer, mettre à jour et gérer des données dans SharePoint. Dans SharePoint, le CSOM est disponible sous plusieurs formes :

Assemblys redistribuables .NET Framework
Bibliothèque JavaScript (JSOM)
Points de terminaison REST/OData
Assemblys Windows Phone (déconseillés)
Assemblys redistribuables Silverlight (déconseillés)

Pour en savoir plus sur les ensembles d’API disponibles sur la plateforme SharePoint, consultez l’article Choisir l’ensemble d’API approprié dans SharePoint.

Cet article montre comment effectuer des opérations de base à l’aide du modèle objet .NET Framework, qui est disponible en tant que package redistribuable sur la NuGet galerie .

Pour plus d’informations sur l’utilisation des autres API clientes, reportez-vous aux articles suivants :

Opérations de base avec le modèle objet client SharePoint .NET

Les sections suivantes décrivent les tâches que vous pouvez effectuer par programmation et elles incluent des exemples de code C# pour illustrer les opérations du modèle objet client.

Quand vous créez un projet Complément pour SharePoint dans Visual Studio 2012, les références aux assemblys .NET Framework Microsoft.SharePoint.Client.Runtime.dll et Microsoft.SharePoint.Client.dll sont automatiquement ajoutées au projet. Pour les autres types de projets, tels que les applications .NET Framework ou les applications de console, vous devez ajouter ces références. Les fichiers se trouvent sur un serveur SharePoint dans %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\ISAPI.

Tous ces exemples partent du principe que le code se trouve dans un fichier code-behind pour une page web Microsoft ASP.NET. L’instruction using suivante doit être ajoutée au fichier de code.

using Microsoft.SharePoint.Client;

Sauf mention contraire, vous pouvez partir du principe que chacun de ces exemples se trouve dans une méthode sans paramètre définie dans la classe de la page. Par ailleurs, label1, label2, etc., sont les noms des objets Label présents sur la page.

Remarque

Quand vous créez un complément SharePoint hébergé par un fournisseur avec une application web ASP.NET et ajoutez une référence à un assembly au projet d’application web dans Visual Studio, définissez la propriété Copie locale de l’assembly sur True, sauf si vous savez que l’assembly est déjà installé sur le serveur web ou qu’il le sera avant le déploiement de votre complément.

.NET Framework est installé sur les rôles web Microsoft Azure et les sites web Azure. Toutefois, les assemblys clients SharePoint et les différentes extensions de code managé et instances Microsoft Foundation ne sont pas installés. Les Outils de développement Office pour Visual Studio 2012 ajoutent automatiquement les références à certains assemblys fréquemment utilisés dans les compléments SharePoint et définissent la propriété Copie locale.

Tâches du site web SharePoint

Les exemples suivants indiquent comment utiliser le modèle objet client .NET Framework pour effectuer des tâches en lien avec le site web.

Récupérer les propriétés d’un site web

Récupérez le titre d’un site web SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

// We want to retrieve the web's properties.
context.Load(web);

// Execute the query to the server.
context.ExecuteQuery();

// Now, the web's properties are available and we could display
// web properties, such as title.
label1.Text = web.Title;

Récupérer uniquement les propriétés sélectionnées d’un site web

Parfois, le client n’est intéressé que par certaines propriétés d’un objet. Le CSOM SharePoint .NET Framework ne vous oblige pas à avoir toutes les propriétés de l’objet sur un serveur. Vous pouvez utiliser des méthodes anonymes, par exemple, des expressions lambda, pour demander spécifiquement les noms des propriétés. La bibliothèque cliente demande uniquement ces propriétés sur le serveur et le serveur envoie uniquement ces propriétés au client. Cette technique limite les transferts de données inutiles entre le client et le serveur. Elle s’avère également utile si l’utilisateur n’a pas d’autorisation pour une ou plusieurs des propriétés inutilisées d’un objet.

Vous devez ajouter une instruction using pour System.Linq.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

// We want to retrieve the web's title and description.
context.Load(web, w => w.Title, w => w.Description);

// Execute the query to server.
context.ExecuteQuery();

// Now, only the web's title and description are available. If you
// try to print out other properties, the code will throw
// an exception because other properties aren't available.
label1.Text = web.Title;
label1.Text = web.Description;

Remarque

Si vous essayez d’accéder à d’autres propriétés, le code génère une exception parce que ces propriétés ne sont pas disponibles.

Modifier les propriétés du site web

L’exemple ci-dessous montre comment accéder en écriture aux propriétés du site web.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

web.Title = "New Title";
web.Description = "New Description";

// Note that the web.Update() doesn't trigger a request to the server.
// Requests are only sent to the server from the client library when
// the ExecuteQuery() method is called.
web.Update();

// Execute the query to server.
context.ExecuteQuery();

Créer un nouveau site web SharePoint

Cet exemple montre comment créer un site SharePoint comme sous-site du site web actuel. Utilisez la classe WebCreationInformation pour créer un site web. Vous devez également ajouter des instructions using pour System.Collections.Generic et System.Text.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

WebCreationInformation creation = new WebCreationInformation();
creation.Url = "web1";
creation.Title = "Hello web1";
Web newWeb = context.Web.Webs.Add(creation);

// Retrieve the new web information.
context.Load(newWeb, w => w.Title);
context.ExecuteQuery();

label1.Text = newWeb.Title;

Tâches de liste SharePoint

Les exemples suivants indiquent comment utiliser le modèle objet client .NET Framework pour effectuer des tâches en lien avec la liste.

Récupérer toutes les listes SharePoint sur un site web

Cet exemple récupère toutes les listes SharePoint sur un site web SharePoint. Pour compiler ce code, ajoutez une instruction using pour System.Linq.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

// Retrieve all lists from the server.
// For each list, retrieve Title and Id.
context.Load(web.Lists,
             lists => lists.Include(list => list.Title,
                                    list => list.Id));

// Execute query.
context.ExecuteQuery();

// Enumerate the web.Lists.
foreach (List list in web.Lists)
{
  label1.Text = label1.Text + ", " + list.Title;
}

Remarque

Vous pouvez éventuellement utiliser la méthode LoadQuery pour enregistrer la valeur renvoyée dans une autre collection, au lieu d’utiliser la propriété web.Lists. Vous devrez également ajouter les instructions using pour System.Collections.Generic et System.Linq. Vous devez aussi ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client afin de pouvoir faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

// Retrieve all lists from the server, and put the return value in another
// collection instead of the web.Lists.
IEnumerable<SP.List> result = context.LoadQuery(
  web.Lists.Include( 
      // For each list, retrieve Title and Id.
      list => list.Title,
      list => list.Id
  )
);

// Execute query.
context.ExecuteQuery();

// Enumerate the result.
foreach (List list in result)
{
  label1.Text = label1.Text + ", " + list.Title;
}

Créer et mettre à jour une liste SharePoint

Cet exemple crée une liste SharePoint et la met à jour en utilisant la classe ListCreationInformation.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

ListCreationInformation creationInfo = new ListCreationInformation();
creationInfo.Title = "My List";
creationInfo.TemplateType = (int)ListTemplateType.Announcements;
List list = web.Lists.Add(creationInfo);
list.Description = "New Description";

list.Update();
context.ExecuteQuery();

Supprimer une liste SharePoint

Cet exemple supprime une liste SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// The SharePoint web at the URL.
Web web = context.Web;

List list = web.Lists.GetByTitle("My List");
list.DeleteObject();

context.ExecuteQuery();

Ajouter un champ à une liste SharePoint

Cet exemple ajoute un champ à une liste SharePoint. Ajoutez un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client afin de pouvoir faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.

Remarque

L’exemple utilise context.CastTo pour effectuer caster. Avant d’exécuter la requête, la bibliothèque cliente ne connaît pas le type réel de l’objet « field » renvoyé et SharePoint.Field est le seul type possible. Si vous connaissez le type réel de l’objet, vous pouvez utiliser la méthode ClientContext.CastTo<RealType> pour caster l’objet.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

SP.List list = context.Web.Lists.GetByTitle("Announcements");

SP.Field field = list.Fields.AddFieldAsXml("<Field DisplayName='MyField2' Type='Number' />",
                                           true,
                                           AddFieldOptions.DefaultValue);
SP.FieldNumber fldNumber = context.CastTo<FieldNumber>(field);
fldNumber.MaximumValue = 100;
fldNumber.MinimumValue = 35;
fldNumber.Update();

context.ExecuteQuery();

Tâches d’éléments de liste SharePoint

Les exemples suivants illustrent l’utilisation du modèle objet client .NET Framework pour effectuer des tâches qui sont liées aux éléments de liste.

Récupérer les éléments d’une liste SharePoint

Cet exemple récupère les éléments d’une liste SharePoint. Vous devez également ajouter une instruction using pour Microsoft.SharePoint.Client.QueryExpression.

Remarque

Vous pouvez utiliser la propriété FolderServerRelativeUrl pour limiter les éléments qui sont renvoyés à ceux figurant dans un dossier spécifique.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume the web has a list named "Announcements".
List announcementsList = context.Web.Lists.GetByTitle("Announcements");

// This creates a CamlQuery that has a RowLimit of 100, and also specifies Scope="RecursiveAll"
// so that it grabs all list items, regardless of the folder they are in.
CamlQuery query = CamlQuery.CreateAllItemsQuery(100);
ListItemCollection items = announcementsList.GetItems(query);

// Retrieve all items in the ListItemCollection from List.GetItems(Query).
context.Load(items);
context.ExecuteQuery();
foreach (ListItem listItem in items)
{
  // We have all the list item data. For example, Title.
  label1.Text = label1.Text + ", " + listItem["Title"];
}

Créer un élément de liste

Cet exemple crée un élément de liste SharePoint en utilisant a classe ListItemCreationInformation.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume that the web has a list named "Announcements".
List announcementsList = context.Web.Lists.GetByTitle("Announcements");

// We are just creating a regular list item, so we don't need to
// set any properties. If we wanted to create a new folder, for
// example, we would have to set properties such as
// UnderlyingObjectType to FileSystemObjectType.Folder.
ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
ListItem newItem = announcementsList.AddItem(itemCreateInfo);
newItem["Title"] = "My New Item!";
newItem["Body"] = "Hello World!";
newItem.Update();

context.ExecuteQuery();

Mettre à jour un élément de liste

Cet exemple met à jour un élément de liste SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume that the web has a list named "Announcements".
List announcementsList = context.Web.Lists.GetByTitle("Announcements");

// Assume there is a list item with ID=1.
ListItem listItem = announcementsList.GetItemById(1);

// Write a new value to the Body field of the Announcement item.
listItem["Body"] = "This is my new value!!";
listItem.Update();

context.ExecuteQuery();

Supprimer un élément de liste

Cet exemple supprime un élément de liste SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume that the web has a list named "Announcements".
List announcementsList = context.Web.Lists.GetByTitle("Announcements");

// Assume that there is a list item with ID=2.
ListItem listItem = announcementsList.GetItemById(2);
listItem.DeleteObject();

context.ExecuteQuery(); }

Tâches de champ SharePoint

Les exemples suivants indiquent comment utiliser le modèle objet client SharePoint .NET Framework pour effectuer des tâches en lien avec le champ.

Récupérer tous les champs d’une liste

Cet exemple récupère tous les champs d’une liste SharePoint. Vous devez aussi ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client afin de pouvoir faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

SP.List list = context.Web.Lists.GetByTitle("Shared Documents");
context.Load(list.Fields);

// We must call ExecuteQuery before enumerate list.Fields.
context.ExecuteQuery();

foreach (SP.Field field in list.Fields)
{
  label1.Text = label1.Text + ", " + field.InternalName;
}

Récupérer un champ spécifique dans la liste

Si vous souhaitez récupérer des informations sur un champ spécifique, utilisez la méthode Fields.GetByInternalNameOrTitle. Le type de retour de cette méthode est Field. Avant l’exécution de la requête, le client ne connaît pas le type d’objet et la syntaxe C# n’est pas disponible pour effectuer caster l’objet dans le type dérivé. Par conséquent, utilisez la méthode ClientContext.CastTo pour caster l’objet et demander à la bibliothèque cliente de recréer un objet. Vous devez également ajouter une instruction using pour System.Collections.Generic. Vous devez aussi ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client afin de pouvoir faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.

Remarque

La méthode GetByInternalNameOrTitle utilisée dans cet exemple est une méthode distante. Elle n’utilise pas les données de la collection cliente, même si celle-ci contient déjà des données.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

SP.List list = context.Web.Lists.GetByTitle("Shared Documents");
SP.Field field = list.Fields.GetByInternalNameOrTitle("Title");
FieldText textField = context.CastTo<FieldText>(field);
context.Load(textField);
context.ExecuteQuery();

// Now, we can access the specific text field properties.
label1.Text = textField.MaxLength;

Tâches d’utilisateur SharePoint

Vous pouvez utiliser le modèle objet client SharePoint .NET Framework pour gérer des utilisateurs, des groupes et la sécurité utilisateur SharePoint.

Ajouter un utilisateur à un groupe SharePoint

Cet exemple ajoute un utilisateur et des informations relatives à celui-ci dans un groupe SharePoint intitulé Members.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

GroupCollection siteGroups = context.Web.SiteGroups;

// Assume that there is a "Members" group, and the ID=5.
Group membersGroup = siteGroups.GetById(5);

// Let's set up the new user info.
UserCreationInformation userCreationInfo = new UserCreationInformation();
userCreationInfo.Email = "user@domain.com";
userCreationInfo.LoginName = "domain\\user";
userCreationInfo.Title = "Mr User";

// Let's add the user to the group.
User newUser = membersGroup.Users.Add(userCreationInfo);

context.ExecuteQuery();

Récupérer tous les utilisateurs d’un groupe SharePoint

Cet exemple récupère les informations relatives à tous les utilisateurs dans un groupe SharePoint intitulé Members.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

GroupCollection siteGroups = context.Web.SiteGroups;

// Assume that there is a "Members" group, and the ID=5.
Group membersGroup = siteGroups.GetById(5);
context.Load(membersGroup.Users);
context.ExecuteQuery();

foreach (User member in membersGroup.Users)
{
  // We have all the user info. For example, Title.
  label1.Text = label1.Text + ", " + member.Title;
}

Créer un rôle

Cet exemple crée un rôle disposant d’autorisations de création et de gestion des alertes.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

BasePermissions perm = new BasePermissions();
perm.Set(PermissionKind.CreateAlerts);
perm.Set(PermissionKind.ManageAlerts);

RoleDefinitionCreationInformation creationInfo = new RoleDefinitionCreationInformation();
creationInfo.BasePermissions = perm;
creationInfo.Description = "A role with create and manage alerts permission";
creationInfo.Name = "Alert Manager Role";
creationInfo.Order = 0;
RoleDefinition rd = context.Web.RoleDefinitions.Add(creationInfo);

context.ExecuteQuery();

Ajouter un utilisateur à un rôle

Cet exemple ajoute un utilisateur à un rôle.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// Assume that we have a SiteUser with Login user.
Principal user = context.Web.SiteUsers.GetByLoginName(@"domain\user");

// Assume that we have a RoleDefinition named "Read".
RoleDefinition readDef = context.Web.RoleDefinitions.GetByName("Read");
RoleDefinitionBindingCollection roleDefCollection = new RoleDefinitionBindingCollection(context);
roleDefCollection.Add(readDef);
RoleAssignment newRoleAssignment = context.Web.RoleAssignments.Add(user, roleDefCollection);

context.ExecuteQuery();

Règles et pratiques recommandées pour l’utilisation du modèle objet client SharePoint .NET

Ces exemples illustrent certaines pratiques recommandées et conditions requises importantes auxquelles vous devez vous conformer lorsque vous utilisez le modèle objet client SharePoint .NET Framework.

Appeler ClientContext.ExecuteQuery avant d’accéder à des propriétés de valeurs

Le CSOM 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 tente d’afficher le titre du site web SharePoint, génère une exception.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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

Ce code échoue parce que le code du modèle objet client SharePoint .NET Framework doit :

générer une requête SQL ou une procédure stockée ad hoc ;
exécuter la requête SQL ;
lire les résultats à partir de SQL.

Dans le CSOM SharePoint .NET Framework, une requête est créée quand vous appelez une méthode. Les requêtes s’accumulent et ne sont pas envoyées au serveur tant que n’est ExecuteQuery pas appelé.

L’exemple suivant montre le code permettant d’afficher le titre du site web. Vous devez également ajouter une instruction using pour System.Linq. Vous devez aussi ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client afin de pouvoir faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;

context.Load(web, w => w.Title);

context.ExecuteQuery();

label1.Text = web.Title;

La seule différence est l’ajout des deux lignes suivantes. La première ligne crée une requête pour la propriété Title du web. La deuxième ligne exécute la requête.

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

Ne pas utiliser d’objets de valeurs renvoyés à partir de méthodes ou propriétés dans la même requête

Quand une méthode ou une propriété renvoie un objet « value », vous ne pouvez pas utiliser cet objet tant que vous n’avez pas exécuté la requête. Par exemple, le code suivant tente de créer une liste SharePoint ayant le même titre que le site web parent, mais il génère une exception.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;
ListCreationInformation creationInfo = new ListCreationInformation();
creationInfo.TemplateType = (int)ListTemplateType.Announcements;
creationInfo.Description = web.Title;
creationInfo.Title = web.Title;
List newList = web.Lists.Add(creationInfo);

Une exception est générée car la propriété n’est pas disponible avant l’exécution de la requête. Dans SQL, il suffirait de déclarer une variable locale pour conserver la valeur de web.Title et d’utiliser cette variable locale pour créer le site web. Dans la bibliothèque cliente, vous ne pouvez pas créer de variable locale. Vous devez fractionner la fonctionnalité en deux requêtes distinctes, comme illustré dans l’exemple suivant. Vous devez également ajouter une instruction using pour System.Linq. Vous devez aussi ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client afin de pouvoir faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;

context.Load(web, w => w.Title, w => w.Description);

context.ExecuteQuery();

ListCreationInformation creationInfo = new ListCreationInformation();
creationInfo.TemplateType = (int)ListTemplateType.Announcements;
creationInfo.Description = web.Description;
creationInfo.Title = web.Title;
SP.List newList = web.Lists.Add(creationInfo);

context.ExecuteQuery();

La différence réside dans les trois lignes suivantes :

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

Utilisation de méthodes ou de propriétés renvoyant les objets clients dans un autre appel de méthode au sein de la même requête

Contrairement à un objet valeur, un objet client peut être utilisé dans un autre appel de méthode au sein de la même requête.

Dans une communication à distance .NET, l'objet valeur est une classe ou un struct qui est marshalé par valeur, tandis que l'objet client est une classe ou un struct qui est marshalé par référence. Par exemple, ListItem est un objet client, tandis que UrlFieldValue et les autres valeurs de champ sont des objets valeur.

Dans la bibliothèque cliente, l’objet serveur correspondant présente l’attribut [ClientCallable(ValueObject = true)]. Ces valeurs peuvent avoir uniquement des propriétés et aucune méthode. Les types primitifs, tels que les chaînes et les entiers, sont traités comme des objets « value ». Toutes les valeurs sont marshalées entre le client et le serveur. La valeur par défaut de la ValueObject est false.

La contrepartie de l’objet valeur est l’objet client. Si l’objet serveur correspondant contient l’attribut [ClientCallable(ValueObject = false)], l’objet est un objet client. Pour les objets clients, nous effectuons le suivi de la façon dont l'objet est créé ; il s'agit de ObjectPath dans la mise en œuvre de la bibliothèque cliente. Par exemple, si nous avons le code suivant :

ClientContext context = new ClientContext("https://{site_url}");
Web web = context.Web;
SP.List list = web.Lists.GetByTitle("Announcements");

Nous savons que la liste est créée de la façon suivante :

En obtenant la propriété Web à partir du contexte.
En obtenant la propriété Lists à partir du résultat ci-dessus.
En appelant la méthode GetByTitle avec le paramètre Announcements à partir du résultat ci-dessus.

Quand le CSOM SharePoint .NET Framework transmet ces informations au serveur, vous pouvez recréer l’objet sur celui-ci. Dans la bibliothèque cliente, vous pouvez suivre le ObjectPath créé par l’objet client. Étant donné que vous connaissez la méthode de création de l’objet, vous pouvez utiliser l’objet comme paramètre pour appeler les autres méthodes dans la même requête.

Regrouper l’extraction de données sur le même objet pour améliorer les performances

Lors de la lecture de plusieurs données à partir du même objet, vous devez essayer d’obtenir toutes ces données dans une seule requête ; c’est-à-dire un appel unique à la Load<T>(T, []) méthode . Le code suivant vous permet de récupérer le titre et la description d’un site web, ainsi que la description de la liste Announcements de deux manières. Pour compiler ce code, ajoutez une instruction using pour System.Linq. Vous devez aussi ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client afin de pouvoir faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.

static void Method1()
{
  ClientContext context = new ClientContext("https://{site_url}");
  Web web = context.Web;
  SP.List list = web.Lists.GetByTitle("Announcements");
  context.Load(web, w => w.Title, w => w.Description);
  context.Load(list, l => l.Description);
  context.ExecuteQuery();
}

static void Method2()
{
  ClientContext context = new ClientContext("https://{site_url}");
  Web web = context.Web;
  SP.List list = web.Lists.GetByTitle("Announcements");
  context.Load(web, w => w.Title);
  context.Load(list, l => l.Description);
  context.Load(web, w => w.Description);
  context.ExecuteQuery();
}

Ces méthodes n’ont pas la même efficacité. Dans la méthode Method1, le code permettant de récupérer le titre et la description du web est regroupé. Dans la méthode Method2, ce code est fractionné par d’autres actions. En d’autres termes, Method2 génère deux requêtes distinctes sur le même objet web et deux jeux de résultats pour le même web. Comme la bibliothèque cliente tente de renvoyer des données cohérentes, le second jeu de résultats comporte le titre et la description. Voici comment on pourrait synthétiser le code précédent :

// Method1:
SELECT Title, Description FROM Webs WHERE ...
SELECT Description FROM Lists WHERE …

// Method2:
SELECT Title FROM Webs WHERE …
SELECT Description FROM Lists WHERE …
SELECT Title, Description FROM Webs WHERE …

Spécifier les propriétés des objets que vous voulez renvoyer

Dans le modèle objet SharePoint Server, si vous obtenez un objet SPWeb, vous pouvez inspecter toutes ses propriétés. Dans SQL, pour obtenir toutes les colonnes d’une table, vous pouvez exécuter la commande suivante :

SELECT * FROM Webs

Dans la bibliothèque cliente, ni la méthode Load<T>, ni aucune autre méthode ne renvoie toutes les propriétés, de sorte que vous devez explicitement spécifier ce que vous voulez. Par exemple, le code suivant extrait l’objet site web sans spécifier les propriétés à renvoyer. Il essaie ensuite de lire deux propriétés dont l’une ne figure pas parmi les propriétés automatiquement renvoyées par Load. Ce code génère une exception.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;
context.Load(web);
context.ExecuteQuery();

Console.WriteLine(web.Title);
Console.WriteLine(web.HasUniqueRoleAssignments);

Pour compiler le code correctement, mettez-le à jour comme ci-dessous. Pour compiler ce code, ajoutez une instruction using pour System.Linq. Vous devez aussi ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client afin de pouvoir faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;
context.Load(web);
context.Load(web, web => web.HasUniqueRoleAssignments);
context.ExecuteQuery();

Console.WriteLine(web.Title);
Console.WriteLine(web.HasUniqueRoleAssignments);

Utilisez l’étendue conditionnelle pour tester la présence de conditions préalables avant de charger des données.

Pour exécuter du code de façon conditionnelle, définissez une étendue conditionnelle à l’aide d’un objet ConditionalScope. Par exemple, récupérez la propriété list quand la liste n’est pas nulle. Vous devez également ajouter des instructions using pour System.Collections.Generic et System.Linq. Vous devez aussi ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client afin de pouvoir faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.

Remarque

Vous n’êtes pas autorisé à appeler des méthodes et à définir des propriétés au sein d’une étendue conditionnelle car la bibliothèque cliente ne suit pas les effets secondaires liés à ces actions. Utilisez uniquement la méthode Load dans l’étendue conditionnelle.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

SP.List list = context.Web.GetCatalog(ListTemplateType.WebPartCatalog);
BasePermissions perm = new BasePermissions();
perm.Set(PermissionKind.ManageLists);

ConditionalScope scope =
    new ConditionalScope(context,
                         () => list.ServerObjectIsNull &amp;&amp; context.Web.DoesUserHavePermissions(perm).Value);
using (scope.StartScope())
{
  context.Load(list, l => l.Title);
}
context.ExecuteQuery();

label1.Text = scope.TestResult.Value;

if (scope.TestResult.Value)
{
  label1.Text = list.Title;
}

Utiliser une étendue de gestion des exceptions pour intercepter des exceptions

Cet exemple montre comment créer et utiliser une étendue de gestion des exceptions à l’aide d’un objet ExceptionHandlingScope. Le scénario consiste à mettre à jour la description d’une liste et à autoriser la création d’un dossier. Il est possible que la liste n’existe pas.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

ExceptionHandlingScope scope = new ExceptionHandlingScope(context);

using (scope.StartScope())
{
  using (scope.StartTry())
  {
    List fooList = context.Web.Lists.GetByTitle("Sample");
    fooList.Description = "In Try Block";
    fooList.Update();
  }
  using (scope.StartCatch())
  {
    // Assume that if there's an exception,
    // it can be only because there was no "Sample" list.
    ListCreationInformation listCreateInfo = new ListCreationInformation();
    listCreateInfo.Title = "Sample";
    listCreateInfo.Description = "In Catch Block";
    listCreateInfo.TemplateType = (int)ListTemplateType.Announcements;
    List fooList = context.Web.Lists.Add(listCreateInfo);
  }
  using (scope.StartFinally())
  {
    List fooList = context.Web.Lists.GetByTitle("Sample");
    fooList.EnableFolderCreation = true;
    fooList.Update();
  }
}

context.ExecuteQuery();

Effectuer des opérations de base avec du code de bibliothèque client dans SharePoint

Opérations de base avec le modèle objet client SharePoint .NET

Tâches du site web SharePoint

Récupérer les propriétés d’un site web

Récupérer uniquement les propriétés sélectionnées d’un site web

Modifier les propriétés du site web

Créer un nouveau site web SharePoint

Tâches de liste SharePoint

Récupérer toutes les listes SharePoint sur un site web

Créer et mettre à jour une liste SharePoint

Supprimer une liste SharePoint

Ajouter un champ à une liste SharePoint

Tâches d’éléments de liste SharePoint

Récupérer les éléments d’une liste SharePoint

Créer un élément de liste

Mettre à jour un élément de liste

Supprimer un élément de liste

Tâches de champ SharePoint

Récupérer tous les champs d’une liste

Récupérer un champ spécifique dans la liste

Tâches d’utilisateur SharePoint

Ajouter un utilisateur à un groupe SharePoint

Récupérer tous les utilisateurs d’un groupe SharePoint

Créer un rôle

Ajouter un utilisateur à un rôle

Règles et pratiques recommandées pour l’utilisation du modèle objet client SharePoint .NET

Appeler ClientContext.ExecuteQuery avant d’accéder à des propriétés de valeurs

Ne pas utiliser d’objets de valeurs renvoyés à partir de méthodes ou propriétés dans la même requête

Utilisation de méthodes ou de propriétés renvoyant les objets clients dans un autre appel de méthode au sein de la même requête

Regrouper l’extraction de données sur le même objet pour améliorer les performances

Spécifier les propriétés des objets que vous voulez renvoyer

Utilisez l’étendue conditionnelle pour tester la présence de conditions préalables avant de charger des données.

Utiliser une étendue de gestion des exceptions pour intercepter des exceptions

Voir aussi

Ressources supplémentaires