In SharePoint 2010 Microsoft provided a version of the managed code CSOM for developers of .NET applications. This library has been rebuilt for SharePoint 2013 and is provided as part of the SharePoint installation. As in the 2010 release, it is provided as part of a redistributable package for developers to include in their applications.
It is made up of the following .NET assemblies:
Later in this chapter you learn about which parts of the CSOM are in what DLL and namespace, but the naming of the DLLs should also give you a few hints.
You can install the DLLs on any computer by downloading the SharePoint Client Components SDK available at: http://www.microsoft.com/en-us/download/details.aspx?id=30355.
Additionally you can find them in the following location on a machine with SharePoint installed, as shown in Figure 9-1:
%ProgramFiles%Common FilesMicrosoft Sharedweb server extensions15ISAPI
After you have added references to these DLLs from your .NET application such as a Windows Forms application or console application, you can add a using statement as follows:
using Microsoft.SharePoint.Client;
In managed code one of the first things you must do to make calls to SharePoint is to establish a ClientContext. It sets up things such as the URL to your SharePoint site and the authentication details needed to communicate with the services. You can instantiate a ClientContext object along with the URL of your site as shown here:
ClientContext context = new ClientContext("http://MySharePointSite");
After you have established a ClientContext the next thing most people want to know is how to interact with SharePoint data. The core set of SharePoint data objects in the CSOM are as follows:
If you are familiar with the SharePoint Server-Side Object Model these items will all sound familiar. However, the naming convention is slightly different, and in the CSOM the “SP” on the front is omitted. However, they map one to one with their server-side equivalent.
In an installation where your SharePoint Server uses Windows Authentication (NTLM) to secure it, the CSOM passes the authentication context of the application process along with it. For example, if you ran your console application under your account the CSOM would be running as you are making the calls to SharePoint. This means you would need to have the correct privileges in SharePoint for the operations or data you were trying to access or you would receive an access denied exception. So, for example, if you were trying to manipulate ListItem object data with the CSOM you would need the corresponding security privileges on those list items in SharePoint.
The CSOM has been built from the ground up with two important features in mind:
When you work with remote systems and call them over potentially latent and unknown bandwidth connections, these two things are very important. You must be able to keep the number of calls and responses to a minimum and you should only bring back the minimum amount of data you need to do your job. For this reason the CSOM only executes calls when you ask it to and includes all statements and operations since the last time you made it execute. This might at times seem cumbersome to someone new to using the CSOM; however, it enforces the developer’s involvement in these choices and ultimately helps make better performing code.
The core object required to work with almost every aspect of the CSOM is a Site or Web object. Because all SharePoint data is stored in sites these objects are usually the first ones you need to instantiate.
You can do it by querying the context for the Site and Web objects corresponding to the URL with which you constructed the ClientContext. You do this with the .Site and .Web properties like so:
ClientContext clientContext = new ClientContext("http://MySharePointSiteUrl"); Site site = clientContext.Site; Web web = clientContext.Web;
Once you have your Site and Web context objects you are ready to start working with data in them. As mentioned previously the CSOM only brings back the data you ask it to. You use the Load method on the ClientContext to do this as follows:
List list = web.Lists.GetByTitle("Movies"); ListItemCollection listItems = list.GetItems(CamlQuery.CreateAllItemsQuery(50)); clientContext.Load(listItems, items => items.Include(item => item["Title"])); clientContext.ExecuteQuery();
In the Load statement the Include command instructs the CSOM to include that property in the results. In the example this instructs the CSOM to load the Title property. Now you are ready to execute the operation against the SharePoint Server. Remember, the CSOM only sends commands to SharePoint when you are ready. Calling Load does not do that. The transaction only executes when you call the ExecuteQuery method, like this:
ClientContext clientContext = new ClientContext("http://MySharePointSiteUrl"); Web web = clientContext.Web; clientContext.Load(web); clientContext.ExecuteQuery(); // this line executes the instructions
By making the developer explicitly request that the instructions be carried out, the CSOM enables you to batch your commands into appropriate sets and thus minimize the number of requests and responses to and from the server. On a highly latent connection this can save many seconds of transmission time and thus help keep your application speedy.
This same technique is applicable in other scenarios and operations, such as bringing back only the properties you desire; for example:
ClientContext clientContext = new ClientContext("http://MySharePointSiteUrl"); Web web = clientContext.Web; clientContext.Load(web, w => w.Title, w => w.Description); clientContext.ExecuteQuery();
Here the Load method is called, passing along a description of the properties to return. If you don’t specify these properties only the default ones will be returned.
The CSOM also allows for operations such as creating data. Because you don’t have a reference to an existing object, the CSOM instead uses a creation information object such as ListItemCreationInformation to capture all the information, such as the column data, about the ListItem.
The following example shows a basic use of the ListItemCreationInformation class to insert a new row into a list:
ClientContext clientContext = new ClientContext("http://MySharePointSiteUrl"); Web web = clientContext.Web; List list = web.Lists. GetByTitle("Tasks") clientContext.Load(web); clientContext.Load(list); ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation(); ListItem listItem = list.AddItem(itemCreateInfo); listItem["Title"] = "New Announcement!"; listItem.Update(); clientContext.ExecuteQuery();
Some other examples of creation information classes include:
To try a practical example of using the CSOM in a console application, work through the following exercise.
ClientContext clientContext = new ClientContext("http://servername/sitename"); Site site = clientContext.Site; Web web = clientContext.Web; clientContext.Load(web, w => w.Title); List list = web.Lists.GetByTitle("Movies"); ListItemCollection listItems = list.GetItems(CamlQuery.CreateAllItemsQuery(50)); clientContext.Load(listItems, items => items.Include(item => item["Title"], item => item["Length"], item => item.Id)); clientContext.ExecuteQuery(); Console.WriteLine(web.Title); foreach (ListItem item in listItems) { Console.WriteLine(string.Format("Item: {0}, {1}, {2}", item.Id, item["Title"], item["Length"])); } ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation(); ListItem listItem = list.AddItem(itemCreateInfo); listItem["Title"] = "Diamonds Are Forever"; listItem["Length"] = 120; listItem.Update(); clientContext.Load(listItems, items => items.Include(item => item["Title"], item => item["Length"], item => item.Id)); clientContext.ExecuteQuery(); Console.WriteLine("Added Movie: " + listItem["Title"]);