Microsoft SharePoint 2010 is the best-in-class platform for content management and collaboration. With Visual Studio, developers have an end-to-end business solutions development IDE. To leverage this powerful combination of tools it is necessary to understand the different building blocks of SharePoint.

In this article by Balaji Kithiganahalli, author of Microsoft SharePoint 2010 Development with Visual Studio 2010 Expert Cookbook, we will cover:

• Creating a list using a Client Object Model
• Handling exceptions
• Calling Object Model asynchronously

(For more resources on Microsoft Sharepoint, see here.)

Introduction

Since out-of-the-box web services does not provide the full functionality that the server model exposes, developers always end up creating custom web services for use with client applications. But there are situations where deploying custom web services may not be feasible. For example, if your company is hosting SharePoint solutions in a cloud environment where access to the root folder is not permitted. In such cases, developing client applications with new Client Object Model (OM) will become a very attractive proposition.

SharePoint exposes three OMs which are as follows:

• Managed
• Silverlight
• JavaScript (ECMAScript)

Each of these OMs provide object interface to functionality exposed in Microsoft. SharePoint namespace. While none of the object models expose the full functionality that the server-side object exposes, the understanding of server Object Models will easily translate for a developer to develop applications using an OM. A managed OM is used to develop custom .NET managed applications (service, WPF, or console applications). You can also use the OM for ASP.NET applications that are not running in the SharePoint context as well. A Silverlight OM is used by Silverlight client applications. A JavaScript OM is only available to applications that are hosted inside the SharePoint applications like web part pages or application pages.

Even though each of the OMs provide different programming interfaces to build applications, behind the scenes, they all call a service called Client.svc to talk to SharePoint. This Client.svc file resides in the ISAPI folder. The service calls are wrapped around with an Object Model that developers can use to make calls to SharePoint server. This way, developers make calls to an OM and the calls are all batched together in XML format to send it to the server. The response is always received in JSON format which is then parsed and associated with the right objects. The basic architectural representation of the client interaction with the SharePoint server is as shown in the following image:

The three Object Models come in separate assemblies. The following table provides the locations and names of the assemblies:

The Client Object Model can be downloaded as a redistributable package from the Microsoft download center at:http://www.microsoft.com/downloads/en/details.aspx?FamilyID=b4579045-b183-4ed4-bf61-dc2f0deabe47

OM functionality focuses on objects at the site collection and below. The main reason being that it will be used to enhance the end-user interaction. Hence the OM is a smaller subset of what is available through the server Object Model. In all three Object Models, main object names are kept the same, and hence the knowledge from one OM is easily portable to another. As indicated earlier, knowledge of server Object Models easily transfer development using client OM The following table shows some of the major objects in the OM and their equivalent names in the server OM:

Creating a list using a Managed OM

In this recipe, we will learn how to create a list using a Managed Object Model. We will also add a new column to the list and insert about 10 rows of data to the list. For this recipe, we will create a console application that makes use of a generic list template.

Getting ready

You can copy the DLLs mentioned earlier to your development machine. Your development machine need not have the SharePoint server installed. But you should be able to access one with proper permission. You also need Visual Studio 2010 IDE installed on the development machine.

How to do it…

In order to create a list using a Managed OM, adhere to the following steps:

1. Launch your Visual Studio 2010 IDE as an administrator (right-click the shortcut and select Run as administrator).
2. Select File | New | Project . The new project wizard dialog box will be displayed (make sure to select .NET Framework 3.5 in the top drop-down box).
3. Select Windows Console application under the Visual C# | Windows | Console Application node from Installed Templates section on the left-hand side.
4. Name the project OMClientApplication and provide a directory location where you want to save the project and click on OK to create the console application template.
5. To add a references to Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll, go to the menu Project | Add Reference and navigate to the location where you copied the DLLs and select them as shown In the following screenshot:

   

6. Now add the code necessary to create a list. A description field will also be added to our list. Your code should look like the following (make sure to change the URL passed to the ClientContext constructor to your environment):

   using Microsoft.SharePoint.Client;
   namespace OMClientApplication
   {
   class Program
   {
   static void Main(string[] args)
   {
   using (ClientContext clientCtx = new
   ClientContext(“http://intsp1”))
   {

   Web site = clientCtx.Web;
   // Create a list.
   ListCreationInformation listCreationInfo = new
   ListCreationInformation();
   listCreationInfo.Title = “OM Client Application
   List”;
   listCreationInfo.TemplateType =
   (int)ListTemplateType.GenericList;
   listCreationInfo.QuickLaunchOption =
   QuickLaunchOptions.On;
   List list = site.Lists.Add(listCreationInfo);
   string DescriptionFieldSchema = “<Field
   Type=’Note’ DisplayName=’Item Description’ Name=’Description’
   Required=’True’ MaxLength=’500′ NumLines=’10’ />”;
   list.Fields.AddFieldAsXml(DescriptionFieldSchema,
   true, AddFieldOptions.AddToDefaultContentType);
   // Insert 10 rows of data – Concat loop Id with “Item Number”
   string.
   for (int i = 1; i < 11; ++i)
   {
   ListItemCreationInformation
   listItemCreationInfo = new ListItemCreationInformation();
   ListItem li = list.AddItem(listItemCreationInf
   o);
   li[“Title”] = string.Format(“Item number
   {0}”,i);
   li[“Item_x0020_Description”] = string.
   Format(“Item number {0} from client Object Model”, i);
   li.Update();
   }
   clientCtx.ExecuteQuery();
   Console.WriteLine(“List creation completed”);
   Console.Read();
   }
   }
   }
   }

7. Build and execute the solution by pressing F5 or from the menu Debug | Start Debugging . This should bring up the command window with a message indicating that the List creation completed as shown in the following screenshot. Press Enter and close the command window.

   

8. Navigate to your site to verify that the list has been created. The following screenshot shows the list with the new field and ten items inserted:

   

   (Move the mouse over the image to enlarge.)

How it works…

The first line of the code in the Main method is to create an instance of ClientContext class. The ClientContext instance provides information about the SharePoint server context in which we will be working. This is also the proxy for the server we will be working with. We passed the URL information to the context to get the entry point to that location. When you have access to the context instance, you can browse the site, web, and list objects of that location. You can access all the properties like Name , Title , Description , and so on.

The ClientContext class implements the IDisposable interface, and hence you need to use the using statement. Without that you have to explicitly dispose the object. If you do not do so, your application will have memory leaks. For more information on disposing objects refer to MSDN at:http://msdn.microsoft.com/en-us/library/ee557362.aspx

From the context we were able to obtain access to our site object on which we wanted to create the list. We provided list properties for our new list through the ListCreationInformation instance.

Through the instance of ListCreationInformation, we set the values to list properties like name, the templates we want to use, whether the list should be shown in the quick launch bar or not, and so on.

We added a new field to the field collection of the list by providing the field schema. Each of the ListItems are created by providing ListItemCreationInformation.

The ListItemCreationInformation is similar to ListCreationInformation where you would provide information regarding the list item like whether it belongs to a document library or not, and so on. For more information on ListCreationInformation and ListItemCreationInformation members refer to MSDN at:http://msdn.microsoft.com/en-us/library/ee536774.aspx.

All of this information is structured as an XML and batched together to send it to the server. In our case, we created a list and added a new field and about ten list items. Each of these would have an equivalent server-side call, and hence, all these multiple calls were batched together to send it to the server. The request is only sent to the server when we issue an ExecuteQuery or ExecuteQueryAsync method in the client context.

The ExecuteQuery method creates an XML request and passes that to Client.svc. The application waits until the batch process on the server is completed and then returns back with the JSON response. Client.svc makes the server Object Model call to execute our request.

There’s more…

By default, ClientContext instance uses windows authentication. It makes use of the windows identity of the person executing the application. Hence, the person running the application should have proper authorization on the site to execute the commands. Exceptions will be thrown if proper permissions are not available for the user executing the application. We will learn about handling exceptions in the next recipe.

It also supports Anonymous and FBA (ASP.Net form based authentication) authentication. The following is the code for passing FBA credentials if your site supports it:

using (ClientContext clientCtx = new ClientContext("http://intsp1"))
{
clientCtx.AuthenticationMode = ClientAuthenticationMode.
FormsAuthentication;
FormsAuthenticationLoginInfo fba = new FormsAuthenticationLoginInfo("u
sername", "password");
clientCtx.FormsAuthenticationLoginInfo = fba;
//Business Logic
}

Impersonation

In order to impersonate you can pass in credential information to the ClientContext as shown in the following code:

clientCtx.Credentials = new NetworkCredential(“username”,
“password”, “domainname”);

Passing credential information this way is supported only in Managed OM.