Author: Tobias Zimmergren
http://www.zimmergren.net | http://www.tozit.com | @zimmergren

Introduction

In this article I will talk about how you can get started with using the Client Object Model in SharePoint 2010. This new object model is introduced in SharePoint Foundation 2010, and does not require SharePoint Server 2010 to be installed.

The Client Object Model is a new object model introduced in SharePoint 2010 which is aimed at making things easier for the developer when developing client-side applications for SharePoint 2010.

Three new client APIs

With the Client Object Model, Microsoft has introduced a set of new APIs to work with to ease the daily tasks of developers.

• .NET Managed Applications (using the .NET CLR)
• Silverlight Applications
• ECMAScript (JavaScript, JScript)

The client APIs provide you as a developer with a subset of the Microsoft.SharePoint namespace which is based on the server-side object model.

Naming conventions

As a small side-note I would like to mention that the objects you are comfortable with calling “SPWeb”, “SPSite”, “SPList” and so on are now named “Web”, “Site”, “List”.

So to conclude the naming convention, the “SP” in the objects has been dropped. Easy enough to remember, right?

Good, let’s move on to some actual code samples to get things fired up!

SharePoint 2010 Client Object Model – Creating your first client-side application

With some fundamental knowledge about the Client OM mentioned above, I would like to take this one step further and actually demonstrate how you can utilize the Client OM in order to create your first client-side application and work with data from SharePoint, instead of using the built-in Web Services.

Step 1 – Creating the Visual Studio project

To be able to follow along with this article, the prerequisites are that you have SharePoint 2010 and Visual Studio 2010 installed in a development environment.

• Launch Visual Studio 2010
• Create a new project
• Choose “Windows Application” and apply the following settings to your project:
  • Target Framework: .NET 3.5
  • Build output: AnyCpu (or x64)

As you can see we are specifically targeting .NET 3.5 since this is the version of the framework that SharePoint 2010 is based on.

Also notice that we are changing the build output from x86 (unsupported!) to AnyCpu or x64 in order to be able to compile and run this project properly.

You should now have an empty Windows Application project like so:   

Step 2 – Adding the Client Object Model references

Next, we need to add references to the Client Object Model in order to be able to work with the client-side APIs from our awesome Windows Application.

1. Right click the “References” node and choose “Add Reference”  
   
   
2. Choose “Browse”
   1. Navigate to this folder:
      C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\ISAPI
      
   2. Select these two files:
      1. Microsoft.SharePoint.Client.dll
      2. Microsoft.SharePoint.Client.Runtime.dll 
         
          
         
3. Make sure they are included in the references of your project: 
   

• Add the following using-statement in your class (note the last line!): 
  

Alright – that was easy enough. Adding the references shouldn’t be any problems. Moving on the the more interesting part – getting our first client object model application up and running!

Step 3 – Make our Windows Application pull out some data from SharePoint

Now that you’ve created your Windows Application, targeted the correct framework and platform, added the Client object model references – we’re ready to take on some Client Object Model action!

Adding the necessary controls to the form

• Add the following controls to your Windows Application:
  • A new ListBox control
  • A new Button control
  • A new TextBox control (Set multiline = true, readonly = true etc to make it look like mine if you want..)

Adding some code-logic to fetch the lists on a particular site and populate the ListBox

• Double-click the Button that you’ve created and add the following code logic:

private void btnGetLists_Click(object sender, EventArgs e)
{
    lbLists.Items.Clear(); 

    using (SP.ClientContext ctx = new SP.ClientContext("http://zimmer"))
    {
        var web = ctx.Web; 

        ctx.Load(web);
        ctx.Load(web.Lists); 

        ctx.ExecuteQuery(); 

        foreach (SP.List list in web.Lists)
        {
            lbLists.Items.Add(list.Title);
        }
    }
}

• Double-click the ListBox that you’ve created and add the following code logic:

private void lbLists_SelectedIndexChanged(object sender, EventArgs e)
        {
            using (SP.ClientContext ctx = new SP.ClientContext("http://zimmer"))
            {
                var list = ctx.Web.Lists.GetByTitle(lbLists.SelectedItem.ToString());

                ctx.Load(list);
                ctx.ExecuteQuery(); 

                string infoAboutList =
                    string.Format("Title: {0}ItemCount: {1}IsHidden: {2}",
                    list.Title + Environment.NewLine,
                    list.ItemCount + Environment.NewLine,
                    list.Hidden.ToString()); 

                textBox1.Text = infoAboutList;
            }
        }

Things to note:

• You use the ClientContext object to connect and work with the SharePoint server
• You use ClientContext.Load() to load the objects you need to work with
• You use the ClientContext.ExecuteQuery() to execute the query and fetch the objects

Running the simple application

When you decide to run this awesomely simple application, it will look something like this: 

With a few simple lines of code you have created your first Client-side application for SharePoint 2010.
Of course we could elaborate this sample to make it way more complex, but this is a teaser for you to get started with the client object model.

Step 4 – Authentication Options for our application

Quite naturally, the question of how you can authenticate to SharePoint often pops up when I do my SP 2010 training and seminars. With that said, I’ll walk you through the different authentication options you’ve got for your client application.

Basically there are three (3) authentication options you can use when you’re working with the Client Object Model in SharePoint 2010:

• Anonymous
• Default
• FormsAuthentication

If you do not choose an authentication method in your code, the application will default to using the client’s Windows Credentials (DefaultCredentials)

Example 1: Using anonymous authentication

ctx.AuthenticationMode = SP.ClientAuthenticationMode.Anonymous;

Example 2: Using Forms Authentication with the Client Object Model

SP.FormsAuthenticationLoginInfo formsLoginInfo = 
new SP.FormsAuthenticationLoginInfo("TobiasZimmergren", "SecretPassword");

ctx.AuthenticationMode = SP.ClientAuthenticationMode.FormsAuthentication;

ctx.FormsAuthenticationLoginInfo = formsLoginInfo;

When you call the Forms Authentication, it will automatically call the Authentication Web Service for you and return the authenticated cookie.

Summary & Downloads

With very little effort, we have created a new Windows Form application that can be run as a client-side application – without the need of SharePoint to be installed on that machine.

Easy enough we have done so without calling any Web Services.

With that said, you should now at least be updated on how you create your first few Client Object Model applications, and be able to start your own project(s) using this new awesome OM.

ENJOY!

Download my sample project

Download my awesome sample project here