Effectuer des opérations de base avec du code de bibliothèque client dans SharePointComplete basic operations using SharePoint client library code

Vous pouvez utiliser le modèle objet client (CSOM) SharePoint pour récupérer, mettre à jour et gérer des données dans SharePoint.You can use the SharePoint client object model (CSOM) to retrieve, update, and manage data in SharePoint. Dans SharePoint, le CSOM est disponible sous plusieurs formes :SharePoint makes the CSOM available in several forms:

  • Assemblys redistribuables .NET Framework.NET Framework redistributable assemblies
  • Bibliothèque JavaScriptJavaScript library
  • Points de terminaison REST/ODataREST/OData endpoints
  • Assemblys Windows PhoneWindows Phone assemblies
  • Assemblys redistribuables SilverlightSilverlight redistributable assemblies

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.For more information about the sets of APIs available on the SharePoint platform, see Choose the right API set in SharePoint.

Cet article explique comment effectuer des opérations de base à l’aide du modèle objet .NET Framework, disponible sous la forme d’un package redistribuable sur le Centre de téléchargement Microsoft (recherchez « SharePoint Server 2013 Client Components SDK » ou « SharePoint Online Client Components SDK »).This article shows how to perform basic operations by using the .NET Framework object model, which is available as a redistributable package on the Microsoft Download Center (search for "SharePoint Server 2013 Client Components SDK" or "SharePoint Online Client Components SDK").

Pour plus d’informations sur l’utilisation des autres API clientes, reportez-vous aux articles suivants :For information about how to use the other client APIs, see:

Opérations de base avec le modèle objet client SharePoint .NETBasic operations with the SharePoint .NET client object model

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.The following sections describe tasks that you can complete programmatically, and they include C# code examples that demonstrate CSOM operations.

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.When you create an Add-in for SharePoint project in Visual Studio 2012, references to the .NET Framework assemblies, Microsoft.SharePoint.Client.Runtime.dll and Microsoft.SharePoint.Client.dll, are automatically added to the project. Pour les autres types de projets, tels que les applications .NET Framework ou les applications de console, il faut ajouter ces références.For other kinds of projects, such as .NET Framework applications or console applications, you should add these references. Les fichiers se trouvent sur un serveur SharePoint dans %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\ISAPI.The files are located on any SharePoint server at %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.All of these examples assume that the code is in a code-behind file for a Microsoft ASP.NET webpage. Ajoutez l’instruction using suivante dans le fichier du code.You must add the following using statement to the code file.

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.Except where specified otherwise, you can assume that each of these examples is in a parameterless method that is defined in the page's class. Par ailleurs, label1, label2, etc., sont les noms des objets Label présents sur la page.Also, label1, label2, and so on, are the names of Label objects on the page.

Notes

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 de l’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 sera installé avant le déploiement de votre complément.When you are making a provider-hosted SharePoint Add-in with an ASP.NET web application, and you add a reference to an assembly to the web application project in Visual Studio, set the Copy Local property of the assembly to True, unless you know that the assembly is already installed on the web server, or you can ensure that it is installed before you deploy your add-in.

.NET Framework est installé sur les rôles web Microsoft Azure et les sites web Azure.The .NET Framework is installed on Microsoft Azure Web Roles and Azure websites. Toutefois, les assemblys clients SharePoint et les différentes extensions de code managé et instances Microsoft Foundation ne sont pas installés.But the SharePoint client assemblies and the various Microsoft managed code extensions and foundations are not installed. 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.Office Developer Tools for Visual Studio 2012 automatically adds references to some assemblies commonly used in SharePoint Add-ins and sets the Copy Local property.

Tâches du site web SharePointSharePoint website tasks

Les exemples suivants indiquent comment utiliser le modèle objet client .NET Framework pour effectuer des tâches en lien avec le site web.These examples show how to use the .NET Framework CSOM to complete website-related tasks.

Récupérer les propriétés d’un site webRetrieve the properties of a website

Récupérez le titre d’un site web SharePoint.Retrieve the title of a SharePoint website.


// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 webRetrieve only selected properties of a website

Parfois, le client n’est intéressé que par certaines propriétés d’un objet.Sometimes, the client is interested only in a few properties of an object. 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, pouvant être des expressions lambda, pour demander spécifiquement les noms des propriétés.The SharePoint .NET Framework CSOM does not require you to get all properties from the object on a server—you can use anonymous methods, which can be lambda expressions, to specifically request property names. La bibliothèque cliente demande uniquement ces propriétés sur le serveur et le serveur envoie uniquement ces propriétés au client.The client library queries only for those properties on the server, and the server sends only those properties to the client. Cette technique limite les transferts de données inutiles entre le client et le serveur.This technique reduces unnecessary data transfer between the client and the server. 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.It is also useful when the user does not have permission to one or more of the other, unused properties on an object.

Notez que vous devez ajouter une instruction using pour System.Linq.Note that you need to add a using statement for System.Linq.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 are not available. 
label1.Text = web.Title;
label1.Text = web. Description;

Notes

Si vous essayez d’accéder à d’autres propriétés, le code génère une exception parce que les autres propriétés ne sont pas disponibles.If you try to access other properties, the code throws an exception because other properties are not available.


Modifier les propriétés du site webWrite to website's properties

L’exemple ci-dessous montre comment accéder en écriture aux propriétés du site web.This example shows how to write to the website's properties.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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

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

// Note that the web.Update() does not trigger a request to the server
// because the client library until ExecuteQuery() is called. 
web.Update(); 

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


Créer un nouveau site web SharePointCreate a new SharePoint website

Cet exemple montre comment créer un site SharePoint comme sous-site du site web actuel.This example shows how to create a new SharePoint site as a subsite of the current website. Utilisez la classe WebCreationInformation pour créer un site web.Use the WebCreationInformation class to create a new website. Ajoutez également les instructions using pour System.Collections.Generic et System.Text.You also need to add using statements for System.Collections.Generic and System.Text.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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 SharePointSharePoint list tasks

Les exemples suivants indiquent comment utiliser le modèle objet client .NET Framework pour effectuer des tâches en lien avec la liste.These examples show how to use the .NET Framework CSOM to complete list-related tasks.

Récupérer toutes les listes SharePoint sur un site webRetrieve all SharePoint lists in a website

Cet exemple récupère toutes les listes SharePoint sur un site web SharePoint.This example retrieves all SharePoint lists in a SharePoint website. Pour compiler ce code, ajoutez une instruction using pour System.Linq.To compile this code, you need to add a using statement for System.Linq.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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

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

// Execute query. 
context.ExecuteQuery(); 

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


Notes

Vous pouvez également utiliser la méthode LoadQuery pour enregistrer la valeur renvoyée dans une autre collection, au lieu d’utiliser la propriété web. Listes.Alternatively, you can use the LoadQuery method to store the return value in another collection, rather than use the web.Lists property. Vous devrez également ajouter les instructions using pour System.Collections.Generic et System.Linq.You will also need to add using statements for System.Collections.Generic and System.Linq. De plus, ajoutez un alias à l’instruction « using » pour l’espace de noms Microsoft.SharePoint.Client pour faire référence à ses classes de façon non ambiguë.Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. Par exemple, using SP = Microsoft.SharePoint.Client;.For example, using SP = Microsoft.SharePoint.Client;.


// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 SharePointCreate and update a SharePoint list

Cet exemple crée une liste SharePoint et la met à jour à l’aide de la classe ListCreationInformation.This example creates a SharePoint list and updates it by using the ListCreationInformation class.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 SharePointDelete a SharePoint list

Cet exemple supprime une liste SharePoint.This example deletes a SharePoint list.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 SharePointAdd a field to a SharePoint list

Cet exemple ajoute un champ à une liste SharePoint.This example adds a field to a SharePoint list. Ajoutez un alias à l’instruction « using » pour l’espace de noms Microsoft.SharePoint.Client pour faire référence à ses classes de façon non ambiguë.Add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. Par exemple, using SP = Microsoft.SharePoint.Client;.For example, using SP = Microsoft.SharePoint.Client;.

Notes

L’exemple utilise context.CastTo pour effectuer une conversion de type (transtypage).The example uses context.CastTo to do a cast. 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.Before executing the query, the client library does not know the real type of the returned object "field", and SharePoint.Field is the only possible type. Si vous connaissez le type réel de l’objet, utilisez la méthode ClientContext.CastTo pour effectuer une conversion de type (transtypage) de l’objet.If you know the real type, you can use the ClientContext.CastTo method to cast the object.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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 SharePointSharePoint list item tasks

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.These examples demonstrate how to use the .NET Framework CSOM to complete tasks that are related to list items.

Récupérer les éléments d’une liste SharePointRetrieve items from a SharePoint list

Cet exemple récupère les éléments d’une liste SharePoint.This example retrieves the items in a SharePoint list. Ajoutez également une instruction using pour Microsoft.SharePoint.Client.QueryExpression.You also need to add a using statement for Microsoft.SharePoint.Client.QueryExpression.

Notes

Vous pouvez utiliser la propriété FolderServerRelativeUrl pour limiter davantage les éléments qui sont renvoyés à ceux figurant dans un dossier spécifique.You can use the FolderServerRelativeUrl property to further restrict the items that are returned to those in a specified folder.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 nouvel élément de listeCreate a new list item

L’exemple suivant crée un élément de liste SharePoint à l’aide de la classe ListItemCreationInformation.This example creates a new SharePoint list item by using the ListItemCreationInformation class.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 listeUpdate a list item

Cet exemple met à jour un élément de liste SharePoint.This example updates a SharePoint list item.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 listeDelete a list item

Cet exemple supprime un élément de liste SharePoint.This example deletes a SharePoint list item.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 SharePointSharePoint field tasks

Les exemples suivants indiquent comment utiliser le modèle objet client SharePoint .NET Framework pour effectuer des tâches en lien avec le champ.These examples show how to use the SharePoint .NET Framework CSOM to complete field-related tasks.

Récupérer tous les champs d’une listeRetrieve all of the fields in a list

Cet exemple récupère tous les champs d’une liste SharePoint.This example retrieves all of the fields in a SharePoint list. Ajoutez également un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client pour faire référence à ses classes de façon non ambiguë. Par exemple, using SP = Microsoft.SharePoint.Client;.You also need to add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously; for example, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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 listeRetrieve a specific field from the list

Pour récupérer des informations sur un champ spécifique, utilisez la méthode Fields.GetByInternalNameOrTitle.If you want to retrieve information about a specific field, use the Fields.GetByInternalNameOrTitle method. Cette méthode renvoie le type d’objet Field.The return type of this method is 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 une conversion de type (transtypage) de l’objet en type dérivé.Before the query is executed, the client does not know the type of object, and C# syntax is not available for casting it to the derived type. Par conséquent, utilisez la méthode ClientContext.CastTo pour effectuer une conversion de type (transtypage) de l’objet et indiquer à la bibliothèque cliente de recréer un objet.Therefore, use the ClientContext.CastTo method to cast it, which instructs the client library to recreate an object. Ajoutez également une instruction using pour System.Collections.Generic.You also need to add a using statement for System.Collections.Generic. Vous devez également ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client pour faire référence à ses classes de façon non ambiguë.You also need to add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. Par exemple, using SP = Microsoft.SharePoint.Client;.For example, using SP = Microsoft.SharePoint.Client;.

Notes

La méthode GetByInternalNameOrTitle utilisée dans cet exemple est une méthode distante.The GetByInternalNameOrTitle method used in this example is a remote method. Elle n’utilise pas les données de la collection cliente même si la collection cliente contient déjà des données.It does not use the data from the client collection even if the client collection is already populated.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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 SharePointSharePoint user tasks

Vous pouvez utiliser le modèle objet client SharePoint .NET Framework pour gérer des utilisateurs, des groupes et la sécurité utilisateur SharePoint.You can use the SharePoint .NET Framework CSOM to manage SharePoint users, groups, and user security.

Ajouter un utilisateur à un groupe SharePointAdd a user to a SharePoint group

Cet exemple ajoute un utilisateur et des informations relatives à celui-ci dans un groupe SharePoint intitulé Members.This example adds a user and some user information to a SharePoint group named Members.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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 SharePointRetrieve all users in a SharePoint group

Cet exemple récupère les informations relatives à tous les utilisateurs dans un groupe SharePoint intitulé Members.This example retrieves information about all users from a SharePoint group named Members.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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ôleCreate a role

Cet exemple crée un rôle disposant d’autorisations de création et de gestion des alertes.This example creates a role that has create and manage alerts permissions.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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ôleAdd a user to a role

Cet exemple ajoute un utilisateur à un rôle.This example adds a user to a role.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// 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 .NETRules and best practices for using the SharePoint .NET client object model

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.These examples illustrate some important best practices and requirements you should conform to when using the SharePoint .NET Framework CSOM.

Appeler ClientContext.ExecuteQuery avant d’accéder à des propriétés de valeursCall ClientContext.ExecuteQuery before accessing any value properties

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.The SharePoint .NET Framework CSOM requires that you use a SQL-like programming pattern: declare what you want and execute the query before you access the data. Par exemple, le code suivant, qui tente d’afficher le titre du site web SharePoint, génère une exception.For example, the following code, which attempts to display the SharePoint website's title, throws an exception.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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


Ce code échoue parce que le code du modèle objet client SharePoint .NET Framework doit :This code fails because SharePoint .NET Framework CSOM code must:

  • Générer une requête SQL ou une procédure stockée ad hoc.Build either an ad hoc SQL query or a stored procedure.
  • Exécuter la requête SQL.Execute the SQL query.
  • Lire les résultats à partir du SQL.Read results from SQL.

Dans le CSOM SharePoint .NET Framework, une requête est créée quand vous appelez une méthode.In SharePoint .NET Framework CSOM, when you call a method, you build a query. Les requêtes s’accumulent et ne sont pas envoyées au serveur tant que la méthode ExecuteQuery n’est pas appelée.Queries accumulate and are not sent to the server until ExecuteQuery is called.

L’exemple suivant montre le code permettant d’afficher le titre du site web.The following example shows the code that is required to display the website's title. Ajoutez également une instruction using pour System.Linq.You also need to add a using statement for System.Linq. Vous devez également ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client pour faire référence à ses classes de façon non ambiguë.Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. Par exemple, using SP = Microsoft.SharePoint.Client;.For example, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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 site web.The differences are the addition of these lines; the first line creates a query for the web's Title property. La deuxième ligne exécute la requête.The second line executes the query.

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êteDo not use value objects returned from methods or properties in the same query

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.When a value object is returned from a method or property, you cannot use that object until after you have executed the query. 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.For example, the following code tries to create a SharePoint list that has the same title as the parent website, but it throws an exception.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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.An exception is thrown because the property is not available before you execute the query. 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.In SQL, you would declare a local variable to hold the value for web.Title and use the local variable for web creation. Dans la bibliothèque cliente, vous ne pouvez pas créer de variable locale.In the client library, you can't create a local variable. Vous devez fractionner les fonctionnalités en deux requêtes distinctes, comme illustré dans l’exemple suivant.You have to split functionality into two separate queries as is shown in the following example. Vous devez également ajouter une instruction using pour System.Linq.You also need to add a using statement for System.Linq. De plus, ajoutez un alias à l’instruction « using » pour l’espace de noms Microsoft.SharePoint.Client pour faire référence à ses classes de façon non ambiguë.Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. Par exemple, using SP = Microsoft.SharePoint.Client;.For example, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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 :The difference is the following three lines:

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êteUsing methods or properties that return client objects in another method call in the same query

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.Unlike a value object, a client object can be used in another method call in the same query.

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 de valeur.In .NET remoting, the value object is a class or struct that is marshaled by value, while the client object is a class or struct that is marshaled by reference. For example, the ListItem is a client object, while the UrlFieldValue and other field values are value objects.

Dans la bibliothèque cliente, l’objet serveur correspondant présente l’attribut [ClientCallable(ValueObject = true)].In the client library, the corresponding server object has the [ClientCallable(ValueObject = true)] attribute. Ces valeurs peuvent avoir uniquement des propriétés et aucune méthode.Those values could have only properties and no methods. Les types primitifs, tels que les chaînes et les entiers, sont traités comme des objets « value ».Primitive types, such as strings and ints, are treated as value objects. Toutes les valeurs sont marshalées entre le client et le serveur.All the values are marshaled between the client and the server. La valeur par défaut de l’objet ValueObject est False.The default value of the ValueObject is false.

L'équivalent de l'objet valeur est l'objet client. Si l'objet serveur correspondant présente 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 :The counterpart to the value object is the client object. If the corresponding server object has the [ClientCallable(ValueObject = false)] attribute, the object is a client object. For client objects, we keep track of how the object is created; this is called ObjectPath in the client library implementation. For example, if we have code like the following:

ClientContext context = new ClientContext("http://SiteUrl"); 
Web web = context.Web; 
SP.List list = web.Lists.GetByTitle("Announcements"); 

Nous savons que la liste est créée de la façon suivante :We know that the list is created by:

  • Obtention de la propriété Web à partir du contexte.Getting the Web property from the context.
  • Obtention de la propriété Lists à partir du résultat ci-dessus.Getting the Lists property from the above result.
  • Appel de la méthode GetByTitle avec le paramètre Announcements à partir du résultat ci-dessus.Invoking the GetByTitle method with the Announcements parameter from the above result.

Quand le CSOM SharePoint .NET Framework transmet ces informations au serveur, vous pouvez recréer l’objet sur le serveur.When the SharePoint .NET Framework CSOM passes this information to the server, you can recreate the object on the server. Dans la bibliothèque cliente, vous pouvez suivre l’ObjectPath créé par l’objet client.In the client library, you can keep track of the ObjectPath that the client object created. É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.Because you know how the object is created, you could use the object as a parameter to invoke other methods within the same query.

Regrouper l’extraction de données sur le même objet pour améliorer les performancesGroup data retrieval on the same object together to improve performance

Pendant la lecture de plusieurs fragments de données à partir du même objet, essayez d’accéder à toutes les données à l’aide d’une seule requête, soit en appelant la méthode Load(T, []).When reading multiple pieces of data from the same object, you should try to get all of it in a single query; that is, a single call to the Load(T, []) method. 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.The following code shows two ways to retrieve a website's title and description and the Announcements list's description. Pour compiler ce code, ajoutez une instruction using pour System.Linq.To compile this code, you need to add a using statement for System.Linq. De plus, ajoutez un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client pour faire référence à ses classes de façon non ambiguë.Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. Par exemple, using SP = Microsoft.SharePoint.Client;.For example, using SP = Microsoft.SharePoint.Client;.


static void Method1() 
{ 
    ClientContext context = new ClientContext("http://SiteUrl"); 
    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("http://SiteUrl"); 
    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 ne garantissent pas la même efficacité.These are not equally efficient. Dans la méthode Method1, le code permettant de récupérer le titre et la description du site web est regroupé sur la même ligne.In Method1, the code to retrieve the web's title and description is grouped together. Dans la méthode Method2, celui-ci est séparé par d’autres actions.In Method2, the code to retrieve the web's title and description is separated by other 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 site web.This means that Method2 triggers two separated queries on the same web object, and there are two result sets for the same 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.Because the client library tries to return consistent data, the second result set includes both the title and description. Voici comment on pourrait synthétiser le code précédent :You could think of the previous code as the following.

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 renvoyerSpecify which properties of objects you want to return

Dans le modèle objet serveur SharePoint, 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 :In the SharePoint server object model, if you get an SPWeb object, you can inspect all of its properties. In SQL, to get all of the columns of a table you can run:

SELECT * FROM Webs 

Dans la bibliothèque cliente, ni Load, 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 récupère l'objet de site web sans spécifier les propriétés à renvoyer. Il essaye ensuite de lire deux propriétés et l'une d'elles ne figure pas parmi les propriétés qui sont automatiquement renvoyées par Load. Ce code génère une exception.In the client library, neither Load nor any other method returns all properties, so you have to explicitly specify what you want. For example, the following code retrieves the website object without specifying which properties to return. It then tries to read two properties and one of them is not among the properties that is automatically returned by Load. This code throws an exception.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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.To get the code to compile successfully, update it to the following. Pour compiler ce code, ajoutez une instruction using pour System.Linq.To compile this code, you need to add a using statement for System.Linq. Vous devez également ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client pour faire référence à ses classes de façon non ambiguë.Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. Par exemple, using SP = Microsoft.SharePoint.Client;.For example, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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.Use conditional scope to test for preconditions before loading data

Pour exécuter du code de façon conditionnelle, définissez une étendue conditionnelle à l’aide d’un objet ConditionalScope.To conditionally execute code, set a conditional scope by using a ConditionalScope object. Par exemple, récupérez la propriété de liste quand la liste n’est pas nulle.For example, retrieve the list property when the list is not null. Ajoutez également les instructions using pour System.Collections.Generic et System.Linq.You also need to add using statements for System.Collections.Generic and System.Linq. Vous devez également ajouter un alias à l’instruction using pour l’espace de noms Microsoft.SharePoint.Client pour faire référence à ses classes de façon non ambiguë.Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. Par exemple, using SP = Microsoft.SharePoint.Client;.For example, using SP = Microsoft.SharePoint.Client;.

Notes

L’appel de méthodes et la définition de propriétés au sein d’une étendue conditionnelle ne sont pas autorisées, étant donné que la bibliothèque cliente n’effectue pas le suivi des effets secondaires liés aux appels de méthodes et aux définitions de propriétés. Veillez à utiliser uniquement Load au sein de l’étendue conditionnelle.Calling method and setting properties within a conditional scope are not permitted, because the client library does not track the side effects of method calls and property settings. You should use only Load inside the conditional scope.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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 exceptionsUse an exception handling scope to catch exceptions

Cet exemple montre comment créer et utiliser une étendue de gestion des exceptions à l’aide d’un objet ExceptionHandlingScope.This example shows how to create and use an exception handling scope with an ExceptionHandlingScope object. Le scénario consiste à mettre à jour la description d’une liste et à autoriser la création d’un dossier.The scenario is to update the description of a list and also enable folder creation. Il est possible que la liste n’existe pas.There is a possibility that the list might not exist.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

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();  


Voir aussiSee also