Leveraging the SharePoint - Object Model

SharePoint provides a rich and complex object model for working with SharePoint data. Although it is challenging to master the details of the SharePoint object model, an even greater challenge that many developers face is taking their knowledge of the object model and using it to craft a solution that delivers on a set of requirements. By its nature, SharePoint solutions are often made up of loosely coupled components that combine to deliver a full set of functionality, and it is sometime difficult to figure out how to translate knowledge of the object model into the set of loosely coupled components in SharePoint. Ask three SharePoint developers how to solve a particular, nontrivial problem, and you will likely receive three unique solutions that might all be equally valid.

This chapter attempts to first cover, in broad strokes, the various customization mechanisms that SharePoint exposes to developers and then provides a number of sample problems and describes how they can be solved the “SharePoint Way.” The chapter provides some basic code snippets illustrating how you can implement various features, but because this chapter is more about how components can be plugged together and combined into solutions, the coverage is not exhaustive.

Customizing SharePoint

SharePoint is a powerful platform that offers many points of extension and customization. You can’t cover everything that SharePoint encompasses within a single chapter, but this chapter highlights some of the most common bits of functionality that you are likely to need to implement in your role as a SharePoint developer.

UI Components
Master Pages and Themes

Master Pages and Themes are the primary mechanism in SharePoint to modify the look and feel of SharePoint. Master Pages can best be thought of as controlling the “edges” of a SharePoint page. Everything from the breadcrumb and up and from the quick launch and left is determined by the Out of the Box (OOTB), v4.master Master Page. This could be extended to control items to the right and below the primary content area of SharePoint pages as well. One common change typically implemented by deploying a custom Master Page is the addition of a standard footer to the bottom of pages in SharePoint.

Themes determine the color palette utilized by SharePoint. You can build themes using the Theme Designer available from Site Settings or also by using PowerPoint 2010 themes. In addition to developing a custom theme, you likely also need a custom .CSS file to provide the granular control most branding efforts require.
 

Custom Web Parts

Web parts are the primary UI building block within SharePoint. They are modular elements that you can place on almost any page within SharePoint. SharePoint ships with a large number of web parts, but it will often be necessary to write your own.
Within SharePoint 2010, there are two types of web parts: visual web parts and traditional web parts. Back in the days of SharePoint 2007, there was only a single type of web part, the traditional web part. Unlike most other visual controls within Visual Studio, web parts did not have any sort of WYSIWYG designer, and developers had to build the UI via code. SharePoint 2010 introduces the ability to build visual web parts that enable the developer to use a WYSIWYG designer to build the UI.
Following is code for a traditional, “Hello World!” web part:

using System;
using System.ComponentModel;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
namespace Wrox.ObjectModel.TraditionalWebPart
{
[ToolboxItemAttribute(false)]
public class TraditionalWebPart : WebPart

Custom Web Parts

Web parts are the primary UI building block within SharePoint. They are modular elements that you can place on almost any page within SharePoint. SharePoint ships with a large number of web parts, but it will often be necessary to write your own. Within SharePoint 2010, there are two types of web parts: visual web parts and traditional web parts. Back in the days of SharePoint 2007, there was only a single type of web part, the traditional web part. Unlike most other visual controls within Visual Studio, web parts did not have any sort of WYSIWYG
designer, and developers had to build the UI via code. SharePoint 2010 introduces the ability to build visual web parts that enable the developer to use a WYSIWYG designer to build the UI.

Following is code for a traditional, “Hello World!” web part:

using System;
using System.ComponentModel;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
namespace Wrox.ObjectModel.TraditionalWebPart
{
[ToolboxItemAttribute(false)]
public class TraditionalWebPart : WebPart
Customizing SharePoint ❘ 5
{
protected override void CreateChildControls()
{
Label label = new Label();
label.Text = “Hello World!”;
Controls.Add(label);
}
}
}

As stated earlier, the “visual” aspect of the new Visual Web Part simply refers to the design time experience. Rather than having to programmatically create the controls and adding them to the web part as in the preceding example, a Visual Web Part enables you to drag and drop controls onto the design surface. Figure 1-1 shows what a visual web part looks like in Visual Studio.

.

Figure 1-1: A Visual Web Part design canvas

When placed on a SharePoint page, the two web parts appear to be nearly identical, as shown in  Figure 1-2.

.

Figure 1-2: Web parts

You probably wonder why traditional web parts continue to exist within SharePoint 2010 because Visual Web Parts provide a better design experience. The answer is twofold. The first is to maintain backward compatibility and to allow solutions that can be deployed to both 2007 and 2010 environments. The second is that because of the way Visual Web Parts deploy, they are not supported within Sandboxed Solutions. There are some alternative implementations of Visual Web Parts, such as those found within Microsoft’s Visual Studio 2010 SharePoint Power Tools, which do work for sandboxed solutions.

Web parts are primarily applicable when you need to implement functionality that requires a UI, is meant to be end-user configurable, and is meant for the site owners or designers to place on pages of their choosing. This may not always be the case however.

Custom Application Pages

The other primary UI building block within SharePoint is the custom application page. These are standard .ASPX pages that are deployed beneath the _layouts directory within your SharePoint environment.

Unlike web parts, custom application pages are standalone pages of self-contained functionality.

Users cannot edit the contents of the page or add custom web parts. If you don’t want the user to determine the placement of the control, or you need to link to the page from another solution element (for example, a custom action, web part, and so on), application pages are generally the right solution to the problem.

A common use for custom application pages is for settings pages, which is probably the scenario in which you see them most used within the OOTB SharePoint screens. For example, go to the site settings section of any site in SharePoint, and every one of the settings links take you to an application page.

Creating a custom application page is as simple as selecting Add ➪ New Item within your project, and selecting the Application Page type. This creates an .ASPX page beneath the Layouts directory of your project, as shown in Figure 1-3.

.

Figure 1-3: Application page in Visual Studio

As you can see in the screenshot, application pages are just like any traditional .ASPX page written in .NET with a few references added to SharePoint assemblies. Just like the other pages within SharePoint, application pages make use of a Master Page, and content placeholder regions are exposed for you to add content to. Figure 1-4 shows a sample application page.

Application pages are deployed to the Layouts directory and, as such, are not deployed as part of a feature. This means that application pages are accessible from within any site within your farm just by appending \_layouts\<path to page> and SharePoint does not secure them assuming the user has access to the site, so you need to check user access within your own code.

.

Figure 1-4: Application page in SharePoint

Custom Lists

SharePoint Lists provide a flexible and extensible way for users to store data within SharePoint and is frequently be used by developers as a location to store information as well. In many instances, these types of “configuration” lists are hidden from the user, and all interactions with the list data occurs through UI elements such as web parts and application pages, but there are cases, particularly when the user must maintain lists of data that you want to expose the list directly to the user.

In those cases, it may be sufficient to simply link them directly to the list and use the default list UI to allow the users to manage the list items. In more complicated scenarios (consider an example in which you have complex multicolumn validation requirements or in which you have multilevel dropdowns) the OOTB UI provided by lists is insufficient.
 

Custom List Forms

List forms refer to the add, edit, and display forms accessible from SharePoint when a user adds a new list item or clicks on an existing list item and chooses to view or edit it. Typical scenarios in which you might need to customize these would be if you need to add complex validation logic that spans across multiple columns in the list or in which selections made to one column affect those available in another. However, list forms are only one way in which you can enter list data within a list. Users interacting with a list through the datasheet view, through the office information panel, or through Access cannot enjoy the same experience, so you need to account for these usage scenarios.
 

Customizing SharePoint  9

 “Custom Field Types, Content Types and List Definitions,” covers lists and list forms in great detail and illustrates how to create custom list forms, so they will not be covered further here, but 2010 provides a number of mechanisms for customizing these forms: You can use SharePoint Designer, InfoPath, and Visual Studio to create more robust list forms.
 

Custom Field Types

Field types are the basic building blocks of lists and content types. Whenever you add a new column to a SharePoint list, you select from a variety of predefined column types such as Currency, Number, and Choice. By selecting these types, you can decide what types of data can be entered and how that data displays and can be manipulated. Figure 1-5 shows a standard column creation dialog.

.

Figure 1-5: Creating a column in SharePoint

Creating custom field types adds to the list of standard types of new columns and enables you to dictate how information displays and interacts within the standard SharePoint list UI. They are most appropriate when you need to implement rules about the types of data fields can contain or the formatting of the display of your data (masking a Social Security number, for example).

Delegate Controls

SharePoint supports delegate controls, which might best be described as functionality placeholders. Developers can register their own implementation of the functionality that overrides the OOTB implementation. You can embed many delegate controls within the default Master Page and include things such as the search box.
As example of how to embed a delegate control in a Master Page is shown in the following code snippet:

<SharePoint:DelegateControl ControlId=”SmallSearchInputBox”
AllowMultipleControls=”false”/>

This snippet basically tells SharePoint that the developer wants to embed a control called SmallSearchInputBox into this location, but the developer requires no knowledge of the implementation of the control.

Delegate controls can also have a default implementation specified directly within the body as well.

Following is an example in the TopNavigationDataSource delegate control from the v4.master:

<SharePoint:DelegateControl runat=”server”
ControlId=”TopNavigationDataSource” Id=”topNavigationDelegate”>
<Template_Controls>
<asp:SiteMapDataSource
ShowStartingNode=”False”
SiteMapProvider=”SPNavigationProvider”
id=”topSiteMap”
runat=”server”
StartingNodeUrl=”sid:1002”/>
</Template_Controls>
</SharePoint:DelegateControl>

You can override this default implementation of a delegate control by deploying a feature that contains a control definition that uses the same ID specified in the ControlId attribute of the delegate control. The elements file would look something like this:

<?xml version=”1.0” encoding=”utf-8” ?>
<Elements xmlns=”http://schemas.microsoft.com/sharepoint/“>
<Control
Id=”SmallSearchInputBox”
Sequence=”25”
ControlClass=”WroxSearchBox”
ControlAssembly=”Wrox.ObjectModel”/>
</Elements>

The preceding definition basically tells SharePoint that this control (WroxSearchBox) should be used anywhere the SmallSearchInputBox delegate control is requested. The “AllowMultipleControls” attribute of the DelegateControl determines what happens if multiple implementations of the control exist. If it is set to true, all controls will be included in the order of their sequence number (lowest to highest). If it is false, only the control with the lowest sequence number is used.

Delegate controls are most useful when you need to replace a bit of OOTB functionality that exists within multiple locations in SharePoint such as the search box, navigation providers, and so on. Unfortunately, not every control in the OOTB Master Pages uses delegate controls, so their use is limited to specific controls.

Following is a list of the delegate controls that exist within the v4.master Master Page:
 

·        AdditionalPageHead

·        GlobalNavigation

·        GlobalSiteLink0

·        GlobalSiteLink2

·        GlobalSiteLink3

·        PublishingConsole

·        SmallSearchInputBox

·        TopNavigationDataSource

·        QuickLaunchDataSource

·        TreeViewAndDataSource

Some of these delegate controls, such as the TopNavigationDataSource control, are embedded within content placeholders of the Master Page. This means that page layouts can replace the entire contents of this section and remove the delegate control definition. This is an issue covered in more depth when discussing implementing a global navigation solution in Chapter 11, “Building a Custom Global Navigation Solution.”
 

Nonvisual Components

Visual components are only half of the story with most SharePoint customizations. Equally necessary is the ability to implement nonvisual functionality, such as executing code at periodic intervals (a timer job) or executing code after an item is added to a list (event handlers or workflow).

Event Handlers

You can attach event handlers in SharePoint to lists and document libraries and can trigger them before adding, updating, or deleting items or after you add, update, or delete items. The event handlers that occur before the event end in “ing” (for example, ItemAdding), whereas the event handlers that occur after an event occurred end in “ed” (for example, ItemAdded).

Within the “ing” events, the developer can stop the action from occurring. So for example, if you need to implement a rule that enforces that items can be added to a list, but can never be removed, you could do that with an ItemDeleting event handler that cancels the action.
 

Workflow

SharePoint 2007 supported a single type of workflow called a list workflow. These were workflows associated with a list that you could manually trigger when you created an item and when you updated an item. Unlike event handlers, you can trigger list workflows only after an action occurs and only on item addition or update. You cannot trigger event handlers on a deletion.

Because there is considerable functionality overlap, determining when to write a list workflow versus writing an event handler is confusing. Workflows provide some advantages during the creation process because codeless workflows can be authored via SharePoint Designer, and workflow actions exist so that developers don’t need to write custom code. But assuming you need to write code with either implementation, event handlers are best used for short-running, atomic processes that do not require user involvement and are tied to the specific list in question. Event handlers are also the only option if you want to intercept an action before it happens. If the requirement being met involves long-running processes that involve waiting for multiple inputs from users or which are triggered from multiple locations, a workflow is more likely to be the correct solution.

SharePoint 2010 also introduces a new type of workflow called a site workflow. Site workflows are tied to sites rather than individual lists and can be only manually triggered (or via code). Site workflows are primarily useful when the workflow in question is not tied to actions around a particular item in a list. Imagine a scenario in which you need to find a single item in a list based on some characteristic and then email the creator of that item. In that case, because you want the workflow to find the item, a site workflow is appropriate. If instead you want to email the creator of an item every time it updates, a list workflow is appropriate.

Timer Jobs

Timer jobs are SharePoint’s mechanism to enable you to run code on a scheduled basis. You can schedule timer jobs to run anywhere from every minute to every month.
Timer jobs are the preferred mechanism any time you must run code on a scheduled basis or where operations are particularly long running. An example of a sample scenario in which a timer job might be appropriate might be if you have a requirement in which every month you want to scan all MySites sites and find any files older than 90 days to confirm if you can delete them.

Feature Receivers

Feature receivers are just an alternative form of an event receiver tied to SharePoint Features rather than SharePoint Lists. Feature receivers enable the developer to run arbitrary code whenever a feature is installed or removed from a farm/web application/site collection/web, whenever a feature is activated or deactivated, or when a feature is upgraded.

One common use for feature receivers is to register timer jobs deployed by a feature. Following is an example of what code to add for a timer job whenever the feature activates:
 

public override void FeatureActivated(
SPFeatureReceiverProperties properties)
{
SPSite site = (SPSite)properties.Feature.Parent;
CustomTimerJob smbJob = new CustomTimerJob(“My Job Name”, site);

SPMinuteSchedule schedule = new SPMinuteSchedule();
schedule.BeginSecond = 0;
schedule.EndSecond = 59;
schedule.Interval = 2;
smbJob.Schedule = schedule;
smbJob.Update();
}

Another sample use would be if a feature depends on certain data, such as a SharePoint subsite existing, prior to it properly working. Your feature receiver could create the required subsite as part of the activation process.

External Access

Up to this point, this chapter has focused only on solutions that exist within SharePoint and run within the farm, but it is also common to need to access SharePoint content and interact with SharePoint from outside of the farm. One example of such a need would be an application that enables you to scan documents from your desktop and store them directly within SharePoint. SharePoint provides two mechanisms to support external access. The first, which existed in SharePoint 2007 and continues to exist in 2010, are web services. The second is Client Object Model, which is new to SharePoint 2010, which you can access from .NET, Silverlight, or JavaScript. The main advantage to using the Client Object Model over the web services is that rather than having to learn a completely new way to access SharePoint content, developers can reuse much of their knowledge of the server-side object model. There definitely are some differences, but in general, the Client Object Model provides a much more familiar framework.

SharePoint Web Services

SharePoint provides a rich set of web services (both .ASMX and WCF/RESTful) to enable external applications to interact with SharePoint. Although not everything is exposed via web services, a great deal of functionality is. For those writing code in .NET, Silverlight, or Javascript, the Client Object Model introduced in 2010 will likely be the preferred mechanism for interacting with SharePoint, but for developers writing in other languages, web services continue to be the primary mechanism used to interact with SharePoint.

The list of web services SharePoint provides follows:
 

·        Admin

·        Alerts

·        Authentication e

·        BDC Admin

·        Cell Storage

·        Copy

·        Diagnostics

·         Document Workspace

·         Forms

·        Imaging

·        Lists

·        Meetings

·        People

·        Permissions

·        Shared Access

·        Distribution List

·        Site Data

·        Sites

·        Search

·        User/Group

·        Versions

·        Views

·        Web Part Pages

·        Webs

·        Organization Profile Service

·        Published Links

·        Social Data

·        User Profile

Covering each one of these services is outside of the scope of this chapter, but you can benefit from learning the capabilities of these web services. As mentioned, Microsoft recommends using the managed Client Object Model whenever possible instead of the web services. Chapter 4, “Leveraging the SharePoint Lists Web Service,” focuses on just one of these web services, the List Web Service.

Client Object Model

The Client Object Model is a set of APIs that enable you to design custom applications that access SharePoint content. It includes libraries for client applications based on the .NET Framework. This new API is targeted for building things such as console, Windows Forms, and WPF applications. The Client Object Model also includes a library for Silverlight and JavaScript client applications. The Silverlight library is composed of a subset of the object model. These interfaces include the Managed .NET Client Object model, Silverlight Client Object, ECMAScript (JavaScript, Jscript) Client Object Model, and LINQ to SharePoint.

The .NET Client Object Model for SharePoint 2010 is one of the newest APIs for working with SharePoint content. The Client Object Model API enables you to build custom applications in any of the Managed .NET languages using an object-oriented approach. This new API is the ideal method to access and manipulate SharePoint 2010 content from a client application. The new APIs were designed to have counterparts to many of the types of objects that you have been using from the Microsoft .SharePoint server API. However, some objects from the server API provided with limited functionality in the Client Object Model APIs.

Using the new object model is fairly straightforward. You begin by creating a client context object like you would if you were using the server API. From there, you can load, create, and manipulate the core components of SharePoint: sites, webs, lists, and libraries. You can, of course, access the children of these objects. Depending on the client that you develop, you can use methods to synchronously or asynchronously perform operations against these objects, which enables you more control of your application’s user experience. For Silverlight and JavaScript client, you can only asynchronously perform actions, whereas .NET clients enable only synchronous operations. As previously mentioned, Client Object Model APIs exist for .NET, Silverlight, and ECMAScript. When you use the API for any of these languages, the syntax looks similar, but there may be some minor differences depending on the language. In the following sections you learn how to use the Client Object Model to load sites and to manipulate lists and libraries.
 

Working with the ClientContext

The most basic building block of content access from standalone applications to SharePoint is the ClientContext class. This class is similar to the SPContext server class. The ClientContext class is responsible for making connections to sites, executing queries, fetching lists, and performing all other actions in SharePoint 2010.
To create a client context for a SharePoint 2010 site located on the local server, use the follow code:

ClientContext clientContext = new ClientContext(“http://localhost/”)

This code assumes that your user logged in with an account that has SharePoint permissions. This new client context allows you to access SharePoint 2010 objects. This newly created client context will use the credentials of the user running the application. In some scenarios, this can be a problem.

The user account that you need to use for SharePoint could be different from the account you use to log into the computer. In this case you can specify the credentials that your application needs to use.
To replace the default network credentials with custom ones you use code like the following:

NetworkCredential credential = new NetworkCredential(“Administrator”, “Password”,
“TestDomain”);
clientContext.Credentials = credential;

This creates a new network credential and sets the credentials for the client context to them. If you use forms-based authentication, you also need to change the AuthenticationMode property of the ClientContext object to ClientAuthenticationMode.FormsAuthentication to make this work.

Your next step toward accessing content with the Client Object Model is to load a web or multiple webs into the context you have created. The Client Object Model does not load any content until it is explicitly requested. To request that the client context load a SharePoint 2010 client object, you must write lines of code that specify what objects to load. To add objects to load into the context, you first access the property from the client context that you want loaded. Next, you call the Load method on the client context with the property as a parameter. Finally, you must call the ExecuteQuery method on the client context to send the request to SharePoint.

The Client OM enables you to load multiple objects by calling Load multiple times. When this is done, all requests are batched and performed using specialized WCF services. This need to explicitly load objects or queries into the context serves a vital purpose. The Load method consolidates multiple requests together to reduce network traffic and improve performance.

Working with Sites and Webs

Now that you have a client context, look at the things you can do with it. For starters, you can load the root web and its child webs. To do this, use the following code:

Web rootWeb = clientContext.Web;
clientContext.Load(rootWeb);
clientContext.Load(rootWeb.Webs);
clientContext.ExecuteQuery();

This loads the entire web and its properties except for the EffectiveBasePermissions, HasUniqueRoleAssignments, and RoleAssignments properties. If you need to work with any of these properties, you must explicitly request them. If you are concerned with reducing unnecessary data transfer between your client application and the server, you should request only the specific properties that your application will use. For example, if you know that you want to use only the title of a Web site, you would use the following code to load only the title property:

Web oWeb = clientContext.Web;
clientContext.Load(oWeb, web=>web.Title);
clientContext.ExecuteQuery();

Using the Client OM, you can also change many properties of an existing web. For instance, you can update a web and change the title and description. To do so, access the web you want to change, modify the properties, and update the web. Because this is the Client OM, you must always call ExecuteQuery to send the request to the server. Code to do this would look like the following:

Web oWeb = clientContext.Web;
oWeb.Title = “Updated Web Title”;
oWeb.Description = “This is a sample of updating a web”;
oWeb.Update();

You can also create Web site objects with the Client OM. To do this use the WebCreationInformation class. You need to set the various properties on the WebCreationInformation object and add it to the web’s collection. The web’s collection you add the new creation object to becomes the parent web for your new one. To add a new blog site use the following code:

Web oWeb = clientContext.Web;
WebCreationInformation webBlogCreate = new WebCreationInformation();
webBlogCreate.Description = “This is a new Blog Site”;
webBlogCreate.Language = 1033; //English Language code is 1033
webBlogCreate.Title = “New Blog Site”;
webBlogCreate.Url = “newblogsite”;
webBlogCreate.UseSamePermissionsAsParentSite = true;

webBlogCreate.WebTemplate = “BLOG#0”;
Web oNewWeb = oWeb.Webs.Add(webBlogCreate);
clientContext.ExecuteQuery();

In the previous example, the value for the Language property is 1033. This is the Microsoft locale code for the English – United States locale. If you create a site for another locale, you need to replace 1033 with the locale code for your locale. A value for the URL of the new site is set. You do not need to put in a full URL here; this needs to be only the final part of the URL. Finally, set the WebTemplate property. In this case you use the string BLOG#0, but you can use any template in your SharePoint 2010 environment. Because this property is just a string, you can even use a custom web template. Now that you have some understanding of the basic building blocks of the Client Object Model, look at using them to access lists.

Working with Lists and Libraries

Lists and document libraries are a key component of the content stored in SharePoint. Lists and libraries are quite similar in design, but they certainly hold different types of information. Lists generally hold data that you can represent in a spreadsheet or tabular manner, whereas libraries hold documents and metadata about those documents. In the following sections you learn how to work with list and library data. You also learn how to create new lists and libraries.
Working with Lists

If you have worked with SharePoint before, lists are probably not new to you. They are one of the main components for storing data in SharePoint. This section discusses how to create, update, and delete lists and list items.

Managing Lists

Before starting to work with list data, you need to create a custom list to work with. This is certainly not required because most SharePoint 2010 site templates come with predefined lists. It is, however, a common development task to create and modify lists. To create a list, use the client context you created in the last section. You also use a new class called List CreationInformation. To create a list, you create a ListCreationInformation object and set the Title and TemplateType properties. The Title property is just the string title that you want to use for the name of the list.
The TemplateType property is an integer representing the template to use for your new list instance. You can retrieve template types from the ListTemplateType enumeration and cast to an integer, or you can enter them directly as an integer. The following code creates a list using the announcements template and titled Custom Announcements List:

ListCreationInformation listCreationInfo = new ListCreationInformation();
listCreationInfo.Title = “Custom Announcements”;
listCreationInfo.TemplateType = (int)ListTemplateType.Announcements;
List oList = oWebsite.Lists.Add(listCreationInfo);
clientContext.ExecuteQuery();

            You can also update properties of the list with the Client OM API. To do this you need to load the list using the client context. You can do this with a LINQ to objects query or CAML query, or by calling the GetByTitle method on the clientContext.Webs.Lists object and passing the title of the list. The GetByTitle approach has the benefit of loading only the list that you modify instead of loading all the lists in your query. After you load the list, you can set the property that you want to update, and call the Update method on the list object. Of course, you also must call ExecuteQuery on the client context to send the update to SharePoint, as follows:

List oList = clientContext.Web.Lists.GetByTitle(“Custom Announcements”);
oList.Description = “This is the new Custom Announcements List”;
oList.Update();
clientContext.ExecuteQuery();

Another common list management task is adding a field to an existing list. To perform this task, you need to get a reference to the list object that you want to add the field to. You can add a field with any of the types available from the user SharePoint 2010 interface. You can then use the AddField or AddFieldAsXml method to add a field. If you need to add attributes to your new field, you can also do that. The following code creates a new number field and sets the minimum and maximum values for the field.

List oList = clientContext.Web.Lists.GetByTitle(“Custom Announcements”);
Field oField = oList.Fields.AddFieldAsXml(
“<Field DisplayName=’Percent Complete’ Type=’Number’/>”,
true, AddFieldOptions.DefaultValue);
FieldNumber fieldNum = clientContext.CastTo<FieldNumber>(oField);
fieldNum.MaximumValue = 100;
fieldNum.MinimumValue = 0;
fieldNum.Update();
clientContext.ExecuteQuery();

The final list management task discussed is deleting a list. Deleting a list with the Client OM is simple.

As with adding a field or modifying a list, you start by getting a reference to the list you want to delete.

Then you call the DeleteObject method on that object. Finally, you call ExecuteQuery on the clientcontext to perform the request.

List oList = clientContext.Web.Lists.GetByTitle(“Custom Announcements”);
oList.DeleteObject();
clientContext.ExecuteQuery();

Now that you have learned how to create, modify, and delete SharePoint lists, you learn how to work with list data. As you will see in the next section, this is similar to the creating of lists from this section.
 

Adding List Items

Creating list items with the Client OM is straightforward. To create a list item and add it to the list, you use the ListItemCreationInformation class. After you instantiate a ListItemCreationInformation object, you need to add it to a list object using the AddItem method on the list. Of course, that means that you need to get or load the list that you want to modify. With the list item creation information added to the list, you can set the various field values for the list item and call the Update method on the list item. Finally, call the ExecuteQuery method on the client context to send your changes to the SharePoint server. The code to perform follows:

List oList = clientContext.Web.Lists.GetByTitle(“Custom Announcements”);
ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
ListItem oListItem = oList.AddItem(itemCreateInfo);
oListItem[“Title”] = “New List Item”;
oListItem[“Body”] = “This is my new List Item”;
oListItem.Update();
clientContext.ExecuteQuery();

Updating List Items

Updating list items is easy with the Client OM. All you need to do is get the list item you want to update, set the fields to update, and call the Update method on the list item. The list properties are accessed and modified with the indexer for the list item in the same way as if you were modifying a dictionary object. The following code gets the third list item in the Custom Announcements list and updates the Title property:

List oList = clientContext.Web.Lists.GetByTitle(“Custom Announcements”);
ListItem listItem = oList.Items.GetById(3);
listItem[“Title”] = “My Updated Title.”;
listItem.Update();
clientContext.ExecuteQuery();

You can also update more than one list item at a time with only a single call to execute the query. To do this, you need to get the list items that you want to update. The easiest way to get multiple items is to use the GetItems method. This method takes a CamlQuery as a parameter. To illustrate this, you can load all the items that have a completed percentage of 50 and update them to 100 like this:

CamlQuery query = new CamlQuery();
query.ViewXml = “<View><Query><Where><Eq>”+
“<FieldRef Name=’Percent Complete’/><Value Type=’Number’>” +
“50</Value></Eq></Where></Query>” +
“<RowLimit>2</RowLimit></View>”;
ListItemCollection collListItem = list.GetItems(query);
context.Load(collListItem);
context.ExecuteQuery();
foreach (SPCL.ListItem item in collListItem)
{
item[“Percent Complete”] = 100;
item.Update();
}
context.ExecuteQuery();

Deleting List Items

Deleting a list item is similar to deleting a list. All you need to do is get the list item you want to delete and call the DeleteObject method on the list item. The following code gets the third list item in the Custom Announcements list and deletes it:

List oList = clientContext.Web.Lists.GetByTitle(“Custom Announcements”);
ListItem listItem = oList.Items.GetById(3);
listitem.DeleteObject()
clientContext.ExecuteQuery();

You can also delete more than one list item at a time with only a single call to execute the query. To do this, you need to get the list items that you want to delete. As you saw in the previous section, the easiest way to get multiple items is to use the GetItems method. The following code fetches all list items that have Percent Complete of 100 and deletes them:

CamlQuery query = new CamlQuery();
query.ViewXml = “<View><Query><Where><Eq>”+
“<FieldRef Name=’Percent Complete’/><Value Type=’Number’>” +
“100</Value></Eq></Where></Query>” +
“<RowLimit>2</RowLimit></View>”;
ListItemCollection collListItem = list.GetItems(query);
context.Load(collListItem);
context.ExecuteQuery();
foreach (SPCL.ListItem item in collListItem)
{
item.DeleteObject();
}
context.ExecuteQuery();

Querying Lists

Now that you know how to access lists, consider how to access subsets of data. There are two ways to query lists with the Client OM. You can write a LINQ to objects query, or you can create a CAML query. Because you can create queries for the Client OM in two ways, you probably wonder how to decide when to use one or the other. As a general rule LINQ style queries are much easier to create. If you have used LINQ to SQL, you are already familiar with the basics. So then why use a CAML query? CAML style queries are not as easy to create as LINQ to objects queries. CAML queries are, however, much faster with the Client OM than LINQ queries are. This performance improvement is because LINQ queries are performed on a frontend web server, whereas CAML queries are performed directly against the database. In addition, you cannot query some objects with LINQ.

For instance, you cannot query list items with LINQ directly. In this case you must perform a CAML query.

The LINQ queries are not using the new LINQ to SharePoint provider. LINQ to SharePoint is available only when you program against the server object model, which is discussed later in this chapter.

Querying with LINQ

If you are familiar with LINQ syntax, you probably know that LINQ can be expressed as method syntax or query syntax. For those of you new to LINQ, a brief explanation of LINQ syntax is given. Query syntax, also called queryable load, is the style of LINQ that looks similar to SQL expressions. It contains familiar SQL keywords such as from, in, where, and select, but the syntax does slightly differ. Still, those familiar with writing SQL queries can quickly pick up the new syntax. If you want to write a LINQ expression in query syntax to load the list in the root web with the name Announcements, it would look like this:

var query = from list
in clientContext.Web.Lists
where list.Title == “Announcements”
select list;
var result = clientContext.LoadQuery(query);
clientContext.ExecuteQuery();
Method syntax, however, looks different. A LINQ expression written in method syntax, also called
in-place load, looks like multiple method calls. The previous query in method syntax would look
like this:
clientContext.Load(clientContext.Web,
website => website.Lists.Include(
list => list.Title).Where(
list => list.Title == “Announcements”));
clientContext.ExecuteQuery();

You have seen the two styles of LINQ that you can use. Why is this important? The style of LINQ that you use determines how the Client OM loads your objects. If you use the query style syntax, the results of your query are stored in an object instead of in the client context. This is called a queryable load. The method syntax query causes the Client OM to perform an in-place load, meaning that the objects load in the client context. In-place loads keep data in the client context through subsequent loads. In a queryable load, you are responsible for keeping the results in the application because they are not stored in the client context. The benefit of the queryable load is that you can perform multiple queries that each return different results and keep the data separate. If you perform multiple queries using the in-place loads and then you looped through the results in the client context, you would loop over records that do not match your latest query.

Querying with CAML

Querying items with LINQ is nice and easy as you have seen. Unfortunately, you cannot query all the objects in the Client OM using LINQ. For example, you cannot query list items with LINQ. If you want to query only list items with LINQ to objects, your only option is to pass an empty query to the GetItems method and then work with the result. This is not considered to be a good practice with the Client OM. You should not create queries to return too many records. Microsoft recommends against returning 2,000 or more records. This causes a large amount of traffic to cross the wire, and realistically the user experience of a grid with so many records would not be good. If you need to work with so many records, your user interface is probably going to show them in some kind of paged view.

Querying with CAML queries gives you the ability to execute queries and return the results in pages.

To use this built-in paging, use a class called ListItemCollectionPosition. Initially, you set it to null so that the CAML query starts at the first item. You create a new CamlQuery object and set the ViewXml property. Now here is the first part of paged results with CAML. You set the RowLimit in the CamlQuery object to the number of items you want returned at once. To set up the client request, you create a new ListItemCollection and set it equal to list.GetItems(camlQuery). In this example, list is the List Client OM object that you query and camlQuery is the CamlQuery Client OM object representing your query.

ListItemCollectionPosition itmPosition = null;
CamlQuery query = new CamlQuery();
Query.ListItemCollectionPosition = itmPosition;
while(true)
{
query.ViewXml = “<View><ViewFields>” +
“<FieldRef Name=’Title’/>”+
“<RowLimit>10</RowLimit></View>”;
ListItemCollection collListItem = list.GetItems(query);
context.Load(collListItem);
context.ExecuteQuery();
itmPosition = collListItem.ListItemCollectionPosition;
foreach(ListItem item in collListItem)
Console.WriteLine(“Title: {0}”,item[“Title”]);
if(itmPosition == null
break;
}

Working with Libraries

If you are somewhat new to SharePoint, you might not be aware of the relationship between lists and document libraries. For those new to SharePoint, a document library is a special type of list that, in addition to containing metadata, contains actual files and folders. Because of this relationship accessing lists and accessing libraries is similar.
 Managing Libraries

Because libraries are specialized lists, all the list management operations previously described apply to libraries. Some additional management tasks are specific to libraries. For instance, libraries can be versioned; individual documents must be checked in and out. Documents are published and unpublished while this operation doesn’t make sense of list items. In this section, you learn how to add and upload documents, work with file versions, and work with publishing.
Adding Documents

Adding items to document libraries is a little more complicated than adding list items to lists.

One major item is getting the actual file bytes into the document library. There are two methods to do this, and each have their own issues. In the first method you read the bytes into a FileCreationInformation object and add that object into a document library. This returns a SharePoint Client OM File object. With that file object you call the Load method on the ClientContext that causes the file to upload. After that you call the ExecuteQuery method on the ClientContext. Finally, you can get the ListItem that the file is associated with by accessing the ListItemAllFields method on the SharePoint File object that you just loaded. At this point, you have a list item, and you can modify the metadata properties and update the list item.

The code for this would look like:

ClientContext context = new ClientContext(“http://localhost/”);
Web web = ctx.Web;
FileCreationInformation newFile = new FileCreationInformation();
newFile.Content = System.IO.File.ReadAllBytes(@”C:\TestFile.doc”);
newFile.Url = “/” + fileName;
List docs = web.Lists.GetByTitle(“Shared Documents”);
File uploadFile = docs.RootFolder.Files.Add(newFile);
context.Load(uploadFile);
context.ExecuteQuery();
SPClient.ListItem item = uploadFile.ListItemAllFields;
//Set the metadata
string docTitle = string.Empty;
item[“Title”] = docTitle;
item.Update();
context.ExecuteQuery();

This approach is relatively straightforward and makes it simple to set the document metadata. It is also good for creating folders in libraries. This approach does, however, come with a major issue.

Using the FileCreationInformation approach works only for files that are not too large. You get server errors when the file byte size is larger than the size that your site is configured to use. Although there are ways to change this setting, there is actually a better way to add and upload documents.

The second method is to utilize the WebDAV feature of SharePoint by calling the File SaveBinaryDirect method on the Client OM File class. This method takes a client context, server relative file path, stream object, and boolean flag indicating if the method should replace an existing file.
 

context.Load(list.RootFolder,item => item.ServerRelativeUrl);
context.ExecuteQuery();
string path = list.RootFolder.ServerRelativeUrl + “/“;
using (FileStream fs = new FileStream(txtFilename.Text, FileMode.Open))
{
SPCL.File.SaveBinaryDirect(context, path + filename, fs, true);
}
string file = path + filename.Replace(“\\“,”“);
SPCL.CamlQuery query = new SPCL.CamlQuery();

query.ViewXml = “<View><Query><Where><Eq><FieldRef Name=’FileRef’/>” +
“<Value Type=’Text’>” + file +
“</Value></Eq></Where></Query>” +
“<RowLimit>2</RowLimit></View>”;
SPCL.ListItemCollection collListItem = list.GetItems(query);
context.Load(collListItem);
context.ExecuteQuery();
if (collListItem.Count == 1)
{
collListItem[0][“Title”] = txtTitle.Text;
collListItem[0].Update();
context.ExecuteQuery();
}

This chapter just touched the surface of the things that you can do with the Client Object Model but has hopefully enabled you to understand the power exposed by it.