SharePoint 2010: Managed .net Client with Client Object Model (OM)

Introduction

In my previous post on Client OM I discussed on the basic ideas. In this post I'll explain how to use Client OM from Managed .net client. The client Object Model for Managed .net application allows any .net managed application to communicate with SharePoint server without using any web service reference. Say you have a WPF application and from that WPF application you need to get data from SharePoint calendar. In the days of SharePoint 2007 you could read the calendar data from SharePoint through web service. If the out of box web service could not meet your demand then you needed to develop your custom web services. But with Client OM you can now program against SharePoint on the client side. In my first post on Client OM I had gone through the some basics. In this post I’ll cover how to use Client OM in managed .net applications (like windows, web, console etc).

Steps to use Client OM with Managed .net application

1. Create a new project (like console, wpf, web etc) in Visual Studio 2010. During creating the project make sure you have selected the target framework to 3.5. By default VS2010 uses .net framework 4 but Client OM will not function with .net framework. The following figure shows the “Add New Project” window with targeted framework selected as 3.5.

Figure 1: New Project dialog

2. To use Client OM with your project add reference to two following DLLs to the project from the directory C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\ISAPI.

• Microsoft.SharePoint.Client.dll
• Microsoft.SharePoint.Client.Runtime.dll

3. Now you can use Client OM. The core object in the client OM is ClientContext. You’ll need to initialize the ClientContext with the SharePoint site url. Let’s dig dipper inside Client OM.

Use Client OM 

Let’s have a look at the following code snippet:

public DateTime GetWebCreatedDate()
{
      using (ClientContext context = new ClientContext("http://myserver"))
      {
            Web web = context.Web;
           context.Load(web, w => w.Created);
           context.ExecuteQuery();
           return web.Created;
       }            
}

Code Snippet 1: Use Client OM to get web site creation date

Few points to notice about the code snippet that uses Client OM above:

a) The ClientContext is needed to initialize with SharePoint site’s url.

b) ClientContext.Load takes the SharePoint object to load as first parameter. The next parameters are the properties to be loaded for the object. As shown in the code snippet the load method is invoked asking only one attribute to load (Create Date).

c) To optimize data retrieval, the Client OM queue all requests to the SharePoint server till an invocation to the ExecuteQuery is made. So no data will be available from the server till the ExecuteQuery method is invoked. After finishing the ExecuteQuery method invocation the properties asked to load in the Load method is populated.

d) If you want to use a property that you are not asked to load in the ClientContext.Load method, you’ll get PropertyOrFieldNotInitializedException is thrown. The same exception will be thrown if you want to use any property of the Client object before calling the ExecuteQuery method.

In the above code snippet, if I tried to use web.Created property before context.ExecuteQuery, I would get PropertyOrFieldNotInitializedException. Even after calling ExecuteQuery, if you try to use any other properties that you have specified in load method (like web.Id or web.Title in above code snippet), you’ll get the same exception. To get more properties of web you need to provide the property/field name in the load method. For example, to load Title and Id you need to modify the load method as shown below:

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

Similarly you can specify as much property as you need. However if you don’ t provide any second parameter to the load method as shown below, then all properties of the object will be loaded. The following load method will populate all fields of web object.

context.Load(web);

In real life scenario, we will barely need to use the above load method as it’ll send a large amount data to the client which is waste of network bandwidth and server resources.

Load properties/Fields selectively 

As I have specified before, in Client OM you can specify the fields/properties to load. The load method of ClientContext works two ways:

1. For single item: For a single item the load methods take a series of arguments that specify the property to load for the item. For example the following few statements load one two and three properties correspondingly.

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

2. For List of items: To specify properties/fields to load for each item of the list, an extension method ‘include’ is used. As the following code snippet shows, a caml query is used to filter data from list. Then in the load method I have used ‘include’ extension method to specify the properties to be loaded.

ClientContext clientContext = new ClientContext("http://myserver");
Web web = clientContext.Web;
List list = web.Lists.GetByTitle("Employee");
CamlQuery query = new CamlQuery();
query.ViewXml = @"<View>
    <Query>
      <Where>
        <Eq>
          <FieldRef Name='FirstName'/>
          <Value Type='Text'>Sohel</Value>
        </Eq>
      </Where>
    </Query>
  </View>";

ListItemCollection listItems = list.GetItems(query);
clientContext.Load(listItems, li => li.Include(i => i["FirstName"], i => i["LastName"]));
clientContext.ExecuteQuery();

Code Snippet 2: Code snippet to showing Include extension method

Update List with Client OM 

With Client OM, you can update list items. As shown in Code Snippet 3, you can get the data as soon as the first clientContext.ExecuteQuery is invoked. After that you can loop through all the list items and update the list item. To send back changes to the server again you need invoke ExecuteQuery method again. The following code snippet show how a list is filtered and then updated.

ClientContext clientContext = new ClientContext("http://myserver");
Web web = clientContext.Web;
List list = web.Lists.GetByTitle("Employee");
CamlQuery query = new CamlQuery();
query.ViewXml = @"<View>
    <Query>
      <Where>
        <Eq>
          <FieldRef Name='FirstName'/>
          <Value Type='Text'>Sohel</Value>
        </Eq>
      </Where>
    </Query>
  </View>";

ListItemCollection listItems = list.GetItems(query);
clientContext.Load(listItems, li => li.Include(i => i["FirstName"],i=>i["LastName"]).Where(i=>i["FirstName"].ToString()=="sohel");
clientContext.ExecuteQuery();


foreach (ListItem item in listItems)
{
    Console.WriteLine(item["FirstName"].ToString());
    item["FirstName"] = "sohel 1";
    item.Update();
}
clientContext.ExecuteQuery();

The important thing to notice in the above code snippet is that the ClientContext.ExecuteQuery is invoked twice. Once to get list items from server. Then after modifying list item on the client side, we need to invoke the ExecuteQuery again to send data back to the server. To delete a list item you need to call the DeleteObject method of the list item. The following code snippet shows how you can delete an item.

foreach (ListItem item in listItems)
{
    item.DeleteObject();
}

Authentication with Client OM 

To specify authentication in the client context you need to set the context.AuthenticationMode Property with either default, anonymous or forms. For forms authentication you also need to set a instance of FormsAuthenticationLoginInfo object to the property FormsAuthenticationLoginInfo. The following code snippet shows how to use form authentication with Client OM.

context.AuthenticationMode = ClientAuthenticationMode.FormsAuthentication;
context.FormsAuthenticationLoginInfo = new FormsAuthenticationLoginInfo 
{ 
       LoginName="username",
       Password="password",
};

Optimization in Client OM 

Two methods play important roles in optimizing the Client OM. One is ClientContext.Load method. This method helps us to specify the properties of an object we want to retrieve. If this option would not be available then whenever we needed to load the Web object, a lot of unnecessary properties would be sent to the client. This would case heavy unnecessary traffic to the system. This would also cause the server to load too much unnecessary data and process it.

Another optimization is done with ExecuteQuery. Since all operations against ClientContext are queued till this method is called the number of round-trip to the server is reduced significantly. But with the introduction of ExecuteQuery, developers need to change their mindset as we can’t just call any field or property as we want rather we need to call ExecuteQuery first.

Deployment Consideration 

When you use .net Managed Client OM you only need two extra assemblies (Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll). So your code will have no web services reference.