The .NET Client-Side Object Model (CSOM) is based on a set of .NET-managed assemblies, which reside in and can be referenced from the SharePoint15_RootISAPI folder. The most basic of these assemblies are Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll, which any 32-bit or 64-bit .NET 3.5 (or higher) project can reference. SharePoint 2013 also offers new assemblies for consuming such SharePoint Server 2013 features as Enterprise Content Management (ECM), taxonomy, user profiles, advanced search, analytics, Business Connectivity Services (BCS), and others.

After you reference at least the two main assemblies (Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll), you need to create an instance of the ClientContext class, defined in the Microsoft.SharePoint.Client namespace. This class represents the client context in which you are acting. It is also the proxy to the SharePoint server that you are targeting. You can think of the ClientContext class as the client-side version of the SPContext class. It has a couple of constructors based on the URL of the target site, provided as a String or System.Uri type. As soon as you have a valid reference to the ClientContext object, you can browse its Site and Web properties, which are references to the site collection and the site that you are targeting. Querying the contents of a list of contacts shows a code excerpt that queries the contents of a list of contacts in the current website.

// Open the current ClientContext
ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
// Prepare a reference to the current Site Collection
Site site = ctx.Site;
ctx.Load(site);
// Prepare a reference to the current Web Site
Web web = site.RootWeb;
ctx.Load(web);
// Prepare a reference to the list of "DevLeap Contacts"
List list = web.Lists.GetByTitle("DevLeap Contacts");
ctx.Load(list);
// Execute the prepared commands against the target ClientContext
ctx.ExecuteQuery();
// Show the title of the list just retrieved
Console.WriteLine(list.Title);
// Prepare a query for all items in the list
CamlQuery query = new CamlQuery();
query.ViewXml = "<View/>";
ListItemCollection allContacts = list.GetItems(query);
ctx.Load(allContacts);
// Execute the prepared command against the target ClientContext
ctx.ExecuteQuery();
// Browse the result
Console.WriteLine("
Contacts");
foreach (ListItem listItem in allContacts) {
    Console.WriteLine("Id: {0} - Fullname: {1} - Company: {2} - Country: {3}",
        listItem["DevLeapContactID"],
        listItem["Title"],
        listItem["DevLeapCompanyName"],
        listItem["DevLeapCountry"]
        );
}

Each time you want to access an object, you first need to add a request for that object by invoking the Load<T> method of the ClientContext instance. You can load as many objects as you like. Many of the client-side objects have a type name that is the same as that of the Server Object Model counterpart, except that on the client side, the SP prefix is missing. For example, SPWeb and SPSite on the server side become Web and Site on the client side. Once you are ready to effectively query SharePoint, you must invoke the ExecuteQuery method of the ClientContext instance. There is also an asynchronous version of this method, called ExecuteQueryAsync, for invoking the service asynchronously. Notice Querying the contents of a list of contacts uses an instance of the CamlQuery class to query the items contained in the target list; specifically, it passes an instance of the CamlQuery class to the GetItems method of the List instance variable representing the list on the client.

Although the Client Object Model provides you with a subset of the classes and methods from the Server Object Model, that subset comprises a rich set of types that is too wide to be covered completely here. Instead, the chapter will focus on more practical matters and later provide some concrete examples taken from everyday life.

ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
ctx.AuthenticationMode = ClientAuthenticationMode.FormsAuthentication;
FormsAuthenticationLoginInfo loginInfo = new FormsAuthenticationLoginInfo {
    LoginName = "UserLoginName",
    Password = "HereYourPassword",
};
ctx.FormsAuthenticationLoginInfo = loginInfo;

Unhandled Exception: Microsoft.SharePoint.Client.PropertyOrFieldNotInitializedException: The property or field 'DisplayName' has not been initialized. It has not been requested or the request has not been executed. It may need to be explicitly requested.

// Browse the result
foreach (ListItem listItem in allContacts) {
    ctx.Load(listItem,
        item => item.DisplayName,
        item => item.RoleAssignments);
    ctx.ExecuteQuery();
    Console.WriteLine("Id: {0} - Fullname: {1} - Company: {2} - Country: {3}",
        listItem["DevLeapContactID"],
        listItem["Title"],
        listItem["DevLeapCompanyName"],
        listItem["DevLeapCountry"]
        );
    Console.WriteLine(listItem.DisplayName);
}

public void Load<T>(
    T clientObject,
    params Expression<Func<T, Object>>[] retrievals)
where T : ClientObject

// Prepare a query for all items in the list
CamlQuery query = CamlQuery.CreateAllItemsQuery();
ListItemCollection allContacts = list.GetItems(query);
ctx.Load(allContacts);
// Define the extra properties to include in default properties
ctx.Load(allContacts,
    items => items.IncludeWithDefaultProperties(
        item => item.DisplayName,
        item => item.RoleAssignments));
// Execute the prepared command against the target ClientContext
ctx.ExecuteQuery();

// Prepare a query for all items in the list
CamlQuery query = new CamlQuery();
query.ViewXml = "<View><ViewFields><FieldRef Name='DevLeapContactID'/>" +"<FieldRef Name='Title'/><FieldRef Name='DevLeapCountry'/></ViewFields></View>";
ListItemCollection allContacts = list.GetItems(query);
ctx.Load(allContacts);
// Execute the prepared command against the target ClientContext
ctx.ExecuteQuery();

// Prepare a query for all items in the list
CamlQuery query = CamlQuery.CreateAllItemsQuery();
ListItemCollection allContacts = list.GetItems(query);
// Define the columns to include in the output
ctx.Load(allContacts,
    items => items.Include(
        item => item["DevLeapContactID"],
        item => item["Title"],
        item => item["DevLeapCountry"]
        ));
// Execute the prepared command against the target ClientContext
ctx.ExecuteQuery();

// Prepare a query for all items in the list
CamlQuery query = CamlQuery.CreateAllItemsQuery();
ListItemCollection allContacts = list.GetItems(query);
var linqQuery =
    from c in allContacts
    where (String)c["DevLeapCountry"] == "Italy"
    select c;
var linqQueryResult = ctx.LoadQuery(linqQuery);
// Execute the prepared command against the target ClientContext
ctx.ExecuteQuery();

public IEnumerable<T> LoadQuery<T>(ClientObjectCollection<T> clientObjects)
    where T : ClientObject;
public IEnumerable<T> LoadQuery<T>(IQueryable<T> clientObjects)
    where T : ClientObject;

// Open the current ClientContext
ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
// Prepare a reference to the target list. We can directly reference
// the property ctx.Web.Lists because both Web and Lists are of types
// inherited from ClientObject
List list = ctx.Web.Lists.GetByTitle("DevLeap Contacts");
// Retrieve the title of the list
ctx.Load(list,
    l => l.Title);
// Execute the query
ctx.ExecuteQuery();
// Show the result
Console.WriteLine(list.Title);

Console.WriteLine(ctx.Web.Title);

// Open the current ClientContext
ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
// Prepare a reference to the target list
// Here you will get a PropertyOrFieldNotInitializedException
// when accessing the Title property of the current website
List list = ctx.Web.Lists.GetByTitle(ctx.Web.Title);
// Retrieve the title of the list
ctx.Load(list,
    l => l.Title);
// Execute the query
ctx.ExecuteQuery();
// Show the result
Console.WriteLine(list.Title);

// Open the current ClientContext
ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
// Retrieve the title of the website
Web web = ctx.Web;
ctx.Load(web,
    w => w.Title);
// Execute the first query
ctx.ExecuteQuery();
// Prepare a reference to the target list
List list = ctx.Web.Lists.GetByTitle(web.Title);
// Retrieve the title of the list
ctx.Load(list,
    l => l.Title);
// Execute the second query
ctx.ExecuteQuery();
// Show the result
Console.WriteLine(list.Title);

The Silverlight Client Object Model behaves almost the same as the .NET CSOM. You can find it in the SharePoint15_RootTEMPLATELAYOUTSClientBin folder, and you can use it in any Silverlight 3.0 (or higher) solution by referencing the two main assemblies, Microsoft.SharePoint.Client.Silverlight.dll and Microsoft.SharePoint.Client.Silverlight.Runtime.dll. Like the CSOM, the Silverlight Client Object Model also supports development for such SharePoint Server 2013 features as ECM, user profiles, taxonomy, and so on.

The Silverlight Client Object Model is useful whenever you need to develop a Silverlight solution that needs to interact with data stored in a SharePoint site. For example, you can use it to build a custom data entry UI or a custom visualization of data that’s ready for hosting with the Silverlight Web Part.

Imagine that you want to show the contacts contained in the sample list from the previous example by using a custom Silverlight control. First, you create a Silverlight application, and then you make a reference to the Silverlight Client Object Model assemblies. Now, assume that you want to render the contacts with a ListBox control, using a custom ItemTemplate for rendering. The XAML code of the Main control of the sample Silverlight application shows the XAML (Extensible Application Markup Language) code of the Main control of the sample application.

<UserControl x:Class="DevLeap.SilverlightClientOMDemo.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:custom="clr-namespace:DevLeap.SP2013.SilverlightOM"
    mc:Ignorable="d"
    d:DesignHeight="300" d:DesignWidth="600">
    <UserControl.Resources>
        <custom:ListItemFieldConverter x:Key="ListItemFieldConverter" />
    </UserControl.Resources>
    <Grid x:Name="LayoutRoot" Background="LightGreen">
        <ListBox x:Name="AllContactsList">
            <ListBox.ItemTemplate>
                <DataTemplate>
                    <StackPanel Orientation="Vertical">
                        <TextBlock Text="{Binding Converter=
                          {StaticResource ListItemFieldConverter},
                          ConverterParameter='DevLeapContactID', Mode=OneWay}" />
                        <TextBlock Text="{Binding Converter=
                          {StaticResource ListItemFieldConverter},
                          ConverterParameter='Title', Mode=OneWay}" />
                        <TextBlock Text="{Binding Converter=
                          {StaticResource ListItemFieldConverter},
                          ConverterParameter='DevLeapCountry', Mode=OneWay}" />
                        <TextBlock Text="{Binding Converter=
                          {StaticResource ListItemFieldConverter},
                          ConverterParameter='DevLeapCompanyName', Mode=OneWay}" />
                    </StackPanel>
                </DataTemplate>
            </ListBox.ItemTemplate>
        </ListBox>
    </Grid>
</UserControl>

In The XAML code of the Main control of the sample Silverlight application, the XAML code by itself is not particularly exciting; it just defines a Grid control, with a ListBox control inside and a DataTemplate control for rendering each item of the contacts list. The code behind the user control is more interesting, because it makes use of the Silverlight Client Object Model. The code behind the XAML user control of the sample Silverlight application gives you a look at the code behind the user control.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Documents;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;
using System.Windows.Shapes;
using Microsoft.SharePoint.Client;
namespace DevLeap.SP2013.SilverlightOM {
    public partial class MainPage : UserControl {
        public MainPage() {
            InitializeComponent();
            loadDevLeapContacts();
        }
        private ListItemCollection allContacts;
        private void loadDevLeapContacts() {
            // Open the current ClientContext
            ClientContext ctx = ClientContext.Current;
            // Prepare a reference to the list of "DevLeap Contacts"
            List list = ctx.Web.Lists.GetByTitle("DevLeap Contacts");
            // Prepare a query for all items in the list
            CamlQuery query = CamlQuery.CreateAllItemsQuery();
            allContacts = list.GetItems(query);
            ctx.Load(allContacts);
            // Execute the prepared command against the target ClientContext
            ctx.ExecuteQueryAsync(onQuerySucceeded, onQueryFailed);
        }
        private void onQuerySucceeded(object sender,
            ClientRequestSucceededEventArgs args) {
            this.Dispatcher.BeginInvoke(new updateUI(refreshGrid));
        }
        private void onQueryFailed(object sender,
            ClientRequestFailedEventArgs args) {
            this.Dispatcher.BeginInvoke(new showExceptionUI(
                showException), args.Exception);
        }
        private delegate void updateUI();
        private void refreshGrid() {
            this.AllContactsList.ItemsSource = allContacts;
        }
        private delegate void showExceptionUI(Exception ex);
        private void showException(Exception ex) {
            MessageBox.Show(String.Format("Exception occurred: {0}", 
                ex.Message));
        }
    }
}

The syntax is almost the same as that used with the CSOM. However, a small but significant difference is the way the code retrieves a reference to the ClientContext object. Because the Silverlight control must be hosted within a website, you could construct the Silverlight version of ClientContext by using the default constructor, which requires the target website as an argument of type System.Uri. Alternatively, you could take advantage of a shortcut to the current website context by using the ClientContext.Current static entry point. This is a constructive shortcut, because many times the Silverlight control will be hosted exactly in the same website that it will target. Furthermore, consider that the ClientContext.Current property internally uses a custom Silverlight init parameter with the name MS.SP.url and the value of the current context URL, provided to the Silverlight environment at startup. If you host your control using the Silverlight Web Part, then this init parameter, together with a few others, will be automatically provided to the control. However, if you directly insert the control inside a page, without using a Silverlight Web Part, then the ClientContext.Current property will be null unless you do not provide the MS.SP.url init parameter by yourself.

Another fundamental difference between this sample and the one based on the CSOM is the use of an asynchronous programming model. This is not a kind of virtuosity, but a real need, because in Silverlight you have to work within the confines of the asynchronous programming pattern. In fact, while working with Silverlight, if you try to execute some blocking code from the main UI thread, you will get an exception of type InvalidOperationException with the following message:

The method or property that is called may block the UI thread and is not allowed. Please use
a background thread to invoke the method or property, for example, using System.Threading.
ThreadPool.QueueUserWorkItem method to invoke the method or property.

The Silverlight Client Object Model also provides a synchronous pattern based on the ExecuteQuery method used in the CSOM. You can call this method only from threads that do not modify the UI, however.

The code behind the XAML user control of the sample Silverlight application shows that the sample directly binds the ListItemCollection retrieved from the server to the ListBox control. However, as you probably know, every ListItem object of SharePoint has its fields stored in a named collection, and the XAML binding syntax does not support named collections. Nevertheless, the code in The XAML code of the Main control of the sample Silverlight application binds the fields using markup. This is possible because the XAML references a custom converter registered as a resource of the user control. In XAML (for instance, Silverlight and Windows Presentation Foundation [WPF]), a converter is a type that converts one input bound to a control into another output, rendering the output of the conversion. In the XAML sample code in The XAML code of the Main control of the sample Silverlight application, the converter converts the name of a field of a ListItem object into the corresponding field value. A custom converter, converting from a named field to its value displays the source code of the custom converter. If you do not like to use a custom converter, you can wrap ListItem instances with a custom type of your own.

 namespace DevLeap.SP2013.SilverlightOM {
    public class ListItemFieldConverter : IValueConverter {
        public object Convert(object value, Type targetType, object parameter,
            System.Globalization.CultureInfo culture) {
            // In case the source item is NULL, just stop
            if (value == null)
                return value;
            // In case the fieldName is empty or NULL, just stop
            String fieldName = parameter as String;
            if (String.IsNullOrEmpty(fieldName))
                return null;
            // Cast the source item to ListItem
            ListItem item = value as ListItem;
            if (item != null) {
                // Return the field
                return (item[fieldName]);
            }
            else
                return (null);
        }
        public object ConvertBack(object value, Type targetType, object
        parameter,System.Globalization.CultureInfo culture) {
            // We do not support two-way conversion
            throw new NotImplementedException();
        }
    }
}

In a real solution, the converter could be more complete and accurate, but for the sake of simplicity, A custom converter, converting from a named field to its value uses a concise implementation.

Aside from binding rules and asynchronous programming tasks, the Silverlight Client Object Model has the same potential, capabilities, and recommended procedures as the Client Object Model. Consider, however, that Silverlight is a discontinued technology. Thus, you should not invest too much time in developing new solutions based on it.

The third client object model offered by SharePoint targets the ECMAScript world. Often called the JavaScript Object Model (JSOM), it is a set of .js files built for ECMAScript-enabled (JavaScript, JScript) platforms. The main .js files that are available are

These files are deployed in the SharePoint15_RootTEMPLATELAYOUTS directory and are automatically downloaded to the client (web browser) when a user browses to a SharePoint page. In fact, the default master pages of SharePoint define a ScriptManager control, which automatically includes references to these .js files. You could also reference them by yourself, however, within a custom ASPX page. Every file is also available with a debug-enabled version—these filenames end with .debug.js instead of .js. For example, the SP.js file is also available in a debug version, named SP.debug.js. The browsers supported by the scripts include Microsoft Internet Explorer 7 and higher, Firefox 3.5 and higher, and Safari 4.0 and higher.

In everyday life, you will probably use the JSOM in a custom SharePoint page, in a custom Web Part, or in a SharePoint app that consumes a remote SharePoint web site. For a SharePoint page or a Web Part, you will need to create a new empty SharePoint project and add an item (for example, an Application Page item) to it. In order to reference the scripts, you can use the SharePoint:ScriptLink control, which accepts a set of arguments, including the following:

Then you need to define a script block that uses the object model. Although the CSOM and the Silverlight Client Object Model share almost the same syntax, the JSOM does not. The data types used do not completely correspond on both platforms, and the members’ names differ. For example, to access the Title property of an item from the JSOM, you need to invoke the get_title() method. In addition, some arguments are case sensitive, and there are other differences. A SharePoint application page using the JSOM shows an example of an application page that uses the JSOM to retrieve a List instance and show its Title property.

<%@ Assembly Name="$SharePoint.Project.AssemblyFullName$" %>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="asp" Namespace="System.Web.UI" Assembly="System.Web.Extensions, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="ShowECMAScriptInAction.aspx.cs" Inherits="DevLeap.SP2013.JSOM.Layouts.DevLeap.SP2013.JSOM.ShowECMAScriptInAction" DynamicMasterPageFile="~masterurl/default.master" %>
<asp:Content ID="PageHead" ContentPlaceHolderID="PlaceHolderAdditionalPageHead"
  runat="server">
<SharePoint:ScriptLink ID="SPScriptLink" runat="server" LoadAfterUI="true"  Localizable="false" Name="SP.js" />
<script language="javascript" type="text/javascript">
    var clientContext;
    var web;
    var oContactsList;
    function onQuerySucceeded(sender, args) {
        alert('Title of the List: ' + this.oContactsList.get_title());
    }
    function onQueryFailed(sender, args) {
        alert('Request failed ' + args.get_message() + '
' + 
        args.get_stackTrace());
    }
    function retrieveContacts() {
        this.clientContext = new SP.ClientContext.get_current();
        this.web = this.clientContext.get_web();
        this.oContactsList = this.web.get_lists().getByTitle("DevLeap Contacts");
        this.clientContext.load(this.oContactsList);
        this.clientContext.executeQueryAsync(
            Function.createDelegate(this, this.onQuerySucceeded),
            Function.createDelegate(this, this.onQueryFailed));
    }
</script>
</asp:Content>
<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
<input type="button" onclick="retrieveContacts()"
  value="Click me to get the list!" />
</asp:Content>
<asp:Content ID="PageTitle" ContentPlaceHolderID="PlaceHolderPageTitle"
  runat="server">
ECMAScript Object Model Demo Page
</asp:Content>
<asp:Content ID="PageTitleInTitleArea"
  ContentPlaceHolderID="PlaceHolderPageTitleInTitleArea" runat="server" >
  ECMAScript Object Model Demo Page
</asp:Content>

The core of A SharePoint application page using the JSOM is in the method retrieveContacts, where the syntax is not so different from the other versions of the Client Object Model. You can get a reference to an SP.ClientContext instance either by using the get_current() method from A SharePoint application page using the JSOM or by using a constructor that accepts the server-relative URL of the target site. The latter syntax is useful when you need to work with data from a target site that differs from the site at your location (for example, when your code is in a remote SharePoint app). The only fundamental difference is syntactical and involves using the get_ and set_ prefixes for every property accessor, as well as using the asynchronous pattern when executing the query against the SharePoint server. For a more interesting and powerful example of this, consider A SharePoint application page using jQuery together with the JSOM, which combines jQuery with the JSOM.

<%@ Assembly Name="$SharePoint.Project.AssemblyFullName$" %>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="asp" Namespace="System.Web.UI" Assembly="System.Web.Extensions, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="UseJQueryWithECMAScript.aspx.cs" Inherits="DevLeap.SP2013.JSOM.Layouts.DevLeap.SP2013.JSOM.UseJQueryWithECMAScript" DynamicMasterPageFile="~masterurl/default.master" %>
<asp:Content ID="PageHead" ContentPlaceHolderID="PlaceHolderAdditionalPageHead"
runat="server">
    <SharePoint:ScriptLink ID="SPScriptLink" runat="server" LoadAfterUI="true" Localizable="false" Name="SP.js" />
    <script type="text/javascript" 
src="http://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"></script>
    <script type="text/javascript" 
src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.8.3.min.js"></script>
    <script type="text/javascript" 
src="http://code.jquery.com/ui/1.9.2/jquery-ui.min.js"></script>
    <link href="http://code.jquery.com/ui/1.9.2/themes/redmond/jquery-ui.css" rel="Stylesheet" type="text/css" /> 
<style type="text/css">
        #listOfContacts .ui-selecting {
            background: #FECA40;
        }
        #listOfContacts .ui-selected {
            background: #F39814;
            color: white;
        }
        #listOfContacts {
            list-style-type: none;
            margin: 0;
            padding: 0;
            width: 60%;
        }
        #listOfContacts li {
            margin: 3px;
            padding: 0.4em;
            font-size: 1em;
            height: 15px;
            width: 600px;
        }
    </style>
    <script language="javascript" type="text/javascript">
        var clientContext;
        var web;
        var oContactsList;
        var listItems;
        _spBodyOnLoadFunctionNames.push("InitData");
        function onQuerySucceeded(sender, args) {
            dataBindList();
        }
        function onQueryFailed(sender, args) {
            alert('Request failed ' + args.get_message() + '
' +
               args.get_stackTrace());
        }
        function InitData() {
            this.clientContext = new SP.ClientContext.get_current();
            this.web = this.clientContext.get_web();
            this.oContactsList = this.web.get_lists()
            .getByTitle("DevLeap Contacts");
            var camlQuery = new SP.CamlQuery();
            var q = '<View><RowLimit>100</RowLimit></View>';
            camlQuery.set_viewXml(q);
            this.listItems = this.oContactsList.getItems(camlQuery);
            this.clientContext.load(this.listItems);
            this.clientContext.executeQueryAsync(
                Function.createDelegate(this, this.onQuerySucceeded),
                Function.createDelegate(this, this.onQueryFailed));
        }
        function dataBindList() {
            var listItemsEnumerator = this.listItems.getEnumerator();
            // iterate though all of the items
            while (listItemsEnumerator.moveNext()) {
                var item = listItemsEnumerator.get_current();
                var id = item.get_id();
                var title = item.get_item("Title");
                var contactId = item.get_item("DevLeapContactID");
                var companyName = item.get_item("DevLeapCompanyName");
                var country = item.get_item("DevLeapCountry");
                $("#listOfContacts").append('<li class="ui-widget-content"
                  id="item_' + id + '">Title: ' + title +  ' - Contact ID: ' +
                  contactId + ' - Company Name: ' + 
                  companyName + ' - Country: ' + country + '</li>'),
            }
            $("#listOfContacts").selectable();
        }
    </script>
</asp:Content>
<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
    <div id="listOfContactsContainer">
        <ol id="listOfContacts"></ol>
    </div>
</asp:Content>
<asp:Content ID="PageTitle" ContentPlaceHolderID="PlaceHolderPageTitle"
  runat="server">
    jQuery and ECMAScript Object Model Demo Page
</asp:Content>
<asp:Content ID="PageTitleInTitleArea"
  ContentPlaceHolderID="PlaceHolderPageTitleInTitleArea" runat="server">
    jQuery and ECMAScript Object Model Demo Page
</asp:Content>

A SharePoint application page using jQuery together with the JSOM uses jQuery version 1.8.3, which is the most current version at the time of this writing. It also uses a custom jQuery UI theme (named Redmond). For the sake of simplicity, the sample project loads the .js file of the jQuery world, the CSS (Cascading Style Sheets) code, and images of the UI theme from publicly available content delivery networks (CDNs). Additionally, the sample page of A SharePoint application page using jQuery together with the JSOM loads the well-known list of contacts and renders them using a custom selectable order list. The core methods are InitData, to configure and start downloading data, and dataBindList, which renders the items retrieved. The first thing you should notice is the invocation of a method to execute the InitData function as soon as the page loads; the method uses this syntax:

_spBodyOnLoadFunctionNames.push("InitData");

This method is provided by the JavaScript infrastructure of SharePoint and can be implemented in any page. The InitData function prepares and loads the queries, executing them asynchronously to keep the UI fluent, even when downloading data. The syntax used here is not substantially different from before. As soon as data is available, the dataBindList method does the real job: using jQuery to enumerate the list items and bind them to dynamic HTML content. Figure 7-3 depicts the output of the application page implemented with jQuery and the JSOM.

Figure 7-3. A sample SharePoint page that uses jQuery and the JSOM.

More generally, you can consider using the JSOM whenever you need to dynamically load or even change SharePoint data from a JavaScript-enabled environment; you can use it in conjunction with jQuery or while developing custom ribbons. You will learn about this in Chapter 12 Another scenario in which you will surely use the JSOM is when developing custom SharePoint apps, as you will discover in Part III

Creating new contents using the CSOM involves using some types specifically provided for the purpose. In fact, from the client viewpoint, the creation of a new List—or new ListItem, or whatever else—implies the need to request that the server execute the necessary action. Thus, for creating a new list, there is a class named ListCreationInformation, which describes the request to create a new list instance. The code excerpt in Creating a new List instance using the CSOM uses this type to create a new list of contacts.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");

ListCreationInformation lci = new ListCreationInformation();
lci.Title = "Contacts CSOM";
lci.Description = "Contacts Created by Client Side Object Model";
lci.TemplateType = (Int32)ListTemplateType.Contacts;
lci.QuickLaunchOption = QuickLaunchOptions.On;
List newList = ctx.Web.Lists.Add(lci);
ctx.ExecuteQuery();

Creating a new List instance using the CSOM demonstrates how the ListCreationInformation instance defines the main properties of the list to be created, such as Title, Description, and QuickLaunchOption. The object also defines the TemplateType property, which defines the base model to use for creating the list instance. If you want to create a new list instance based on a custom list definition, you can use the property ListCreationInformation.TemplateFeatureId to reference the GUID (globally unique identifier) of the feature provisioning the list definition.

If you try to create a list that already exists with the Title provided by your code, you will get an exception of type Microsoft.SharePoint.Client.ServerException, with the following error message:

Unhandled Exception: Microsoft.SharePoint.Client.ServerException: A list, survey, discussion
board, or document library with the specified title already exists in this Web site. Please
choose another title.

One last thing to consider is that just after ExecuteQuery method invocation, the List instance you get back from the Add method of the Lists property is a fully functional instance that you can use to add items, configure properties, and so on.

When you create a list instance, you need to add new items to the list. Creating a new list item using the CSOM demonstrates how to add a contact to the newly created list of contacts.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
List contactsList = ctx.Web.Lists.GetByTitle("Contacts CSOM");
ListItem item = contactsList.AddItem(new ListItemCreationInformation());
item["Title"] = "Paolo Pialorsi";
item["Email"] = "[email protected]";
item["Company"] = "DevLeap";
item.Update();
ctx.ExecuteQuery();

Creating a new list item using the CSOM adds the ListItem object to the List instance using a ListItemCreationInformation type, which simply defines a creation task for a new ListItem. The result of the AddItem method is a ListItem instance that can be used to configure fields of the item, and then finally allows the Update method to be invoked to confirm the values of the fields. As usual with the CSOM, however, you need to inform the server about what you want to do. Thus, you need to call the ExecuteQuery method on the ClientContext instance.

Updating a ListItem instance is similar to creating a new item. The only difference is that you need to retrieve the item from the store. You can do this by enumerating the items returned from a CamlQuery object, as shown in A SharePoint application page using jQuery together with the JSOM, or you can retrieve a specific item by ID using the GetItemById method of the List type. Updating a list item by using the CSOM presents an example of updating the item created in Creating a new list item using the CSOM.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
List contactsList = ctx.Web.Lists.GetByTitle("Contacts CSOM");
ListItem itemToUpdate = contactsList.GetItemById(1);
itemToUpdate["Company"] = "DevLeap - Changed!";
itemToUpdate.Update();
ctx.ExecuteQuery();

While working with lists and items, you occasionally may look for one that does not exist. Due to the architecture of the Client Object Model, you must query the server to determine if the desired item exists. Suppose you use a try…catch code block to trap the exception related to the missing item. In this case, the exception would be a ServerException, with the following error message:

Unhandled Exception: Microsoft.SharePoint.Client.ServerException: Item does not exist. It
may have been deleted by another user.

You could then follow a backup path to avoid issues on the client side, create the missing item from scratch, or try to retrieve another item. If you look for a list that does not exist, you’ll receive the following exception:

Unhandled Exception: Microsoft.SharePoint.Client.ServerException: List 'Contacts CSOM' does not exist at site with URL 'http://devbook.sp2013.local'.

This time, you will probably need to query the server for new data or create the missing list. Code excerpt showing how to retrieve or create a list in the event that it is missing, and then add an item to it illustrates one possible scenario.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
List contactsList = null;
try {
    contactsList = ctx.Web.Lists.GetByTitle("Contacts CSOM");
    ctx.Load(contactsList);
    ctx.ExecuteQuery();
}
catch (ServerException) {
    ListCreationInformation lci = new ListCreationInformation();
    lci.Title = "Contacts CSOM";
    lci.Description = "Contacts Created by Client Side Object Model";
    lci.TemplateType = (Int32)ListTemplateType.Contacts;
    lci.QuickLaunchOption = QuickLaunchOptions.On;
    contactsList = ctx.Web.Lists.Add(lci);
    ctx.ExecuteQuery();
}
finally {
    ListItem item = contactsList.AddItem(new ListItemCreationInformation());
    item["Title"] = "Paolo Pialorsi";
    item["Email"] = "[email protected]";
    item["Company"] = "DevLeap";
    item.Update();
    ctx.ExecuteQuery();
}

The boldface code in Code excerpt showing how to retrieve or create a list in the event that it is missing, and then add an item to it shows the three calls to the ExecuteQuery method. In the worst situation, this code could execute all the try…catch…finally blocks, invoking the server via ExecuteQuery three times. This could lead to performance degradation and also put a great deal of stress on the server side. Luckily, the CSOM provides a class named ExceptionHandlingScope that is specifically defined to support such situations and avoid executing multiple queries against the server.

The prototype for using ExceptionHandlingScope displays the prototype of using the ExceptionHandlingScope type.

ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
ExceptionHandlingScope scope = new ExceptionHandlingScope(ctx);
using (scope.StartScope()) {
    using (scope.StartTry()) {
        // Try to do something on the server side
    }
    using (scope.StartCatch()) {
        // Do something else in case of failure on the server side
    }
    using (scope.StartFinally()) {
        // Execute this code, whatever is the result of previous code blocks
    }
}
// Now invoke the server, just one time
ctx.ExecuteQuery();

Behind the scenes, the ExceptionHandlingScope instance collects activities (internally called ClientActions) to execute on the server side for all the three situations (try, catch, and finally). The server will begin executing the code inside the StartTry block, and then in case of failure, it will execute the code in the StartCatch block. Regardless of whether exceptions occur in the StartTry block, the server will finally execute the code in the StartFinally block. However, the request sent to the server defining all the previously described code blocks is just one, as well as the response. The complete code to retrieve or create a list in the event that it is missing, and then add an item to it presents a complete example.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
ExceptionHandlingScope scope = new ExceptionHandlingScope(ctx);
List contactsList;
using (scope.StartScope()) {
    using (scope.StartTry()) {
        // Try to reference the target list
        contactsList = ctx.Web.Lists.GetByTitle("Contacts CSOM");
    }
    using (scope.StartCatch()) {
        // Create the list, in case it doesn't exist
        ListCreationInformation lci = new ListCreationInformation();
        lci.Title = "Contacts CSOM";
        lci.Description = "Contacts Created by Client Side Object Model";
        lci.TemplateType = (Int32)ListTemplateType.Contacts;
        lci.QuickLaunchOption = QuickLaunchOptions.On;
        contactsList = ctx.Web.Lists.Add(lci);
    }
    using (scope.StartFinally()) {
        // Add the ListItem, whether the list has just been created
        // or was already existing
        contactsList = ctx.Web.Lists.GetByTitle("Contacts CSOM");
        ListItem item = contactsList.AddItem(new ListItemCreationInformation());
        item["Title"] = "Paolo Pialorsi";
        item["Email"] = "[email protected]";
        item["Company"] = "DevLeap";
        item.Update();
    }
}
// Now invoke the server, just one time
ctx.ExecuteQuery();

Another common scenario is deleting an item from a list. Deleting a ListItem instance illustrates how to do this.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
List contactsList = ctx.Web.Lists.GetByTitle("Contacts CSOM");
// This will work only in case an item with ID = 1 exists.
// Otherwise you should change the ID or search for a specific item to delete.
ListItem itemToDelete = contactsList.GetItemById(1);
itemToDelete.DeleteObject();
ctx.ExecuteQuery();

This is very similar to the syntax used to update an item. The only difference is the invocation of the DeleteObject method.

Already in this chapter you’ve seen many ways of querying items in a list. Real-life applications, however, can contain thousands of items. Thus, it is not realistic to query these items with a unique query batch as shown in these smaller-scale examples. For such situations, take advantage of the paging capabilities of the SharePoint querying engine. How to efficiently paginate query results using the CSOM shows a code excerpt that demonstrates how to efficiently paginate query results.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
List contactsList = ctx.Web.Lists.GetByTitle("Contacts CSOM");
ListItemCollectionPosition itemPosition = null;
Int32 currentPage = 0;
do {
    CamlQuery query = new CamlQuery();
    query.ListItemCollectionPosition = itemPosition;
    query.ViewXml = "<View><RowLimit>10</RowLimit></View>";
    ListItemCollection pageOfContacts = contactsList.GetItems(query);
    ctx.Load(pageOfContacts);
    ctx.ExecuteQuery();
    itemPosition = pageOfContacts.ListItemCollectionPosition;
    currentPage++;
    Console.WriteLine("Page #: {0}", currentPage);
    foreach (ListItem item in pageOfContacts) {
        Console.WriteLine("Contact: {0}", item["Title"]);
    }
    Console.WriteLine();
} while (itemPosition != null);

First, to paginate data, you need to instruct the CAML query about the page size by using a <RowLimit/> element. In this example, the page size is 10 items per page. Next, declare a variable of type ListItemCollectionPosition to define a paging context for the running CamlQuery object. Each time you execute the query, which invokes the GetItems method of the List instance, set the property ListItemCollectionPosition of the query in order to instruct SharePoint about the page that you want to retrieve. You can retrieve the value to provide for each page from the ListItemCollectionPosition property of the class ListItemCollection. When retrieving the last page, the ListItemCollectionPosition property will have a null value, and you will know that you’ve consumed the whole set of data.

In addition to creating a standard list, at times you will need to create a custom document library. Creating a custom document library demonstrates the code to do the job.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
ListCreationInformation lci = new ListCreationInformation();
lci.Title = "Custom Documents";
lci.Description = "Custom Documents Created by Client Side Object Model";
lci.TemplateType = (Int32)ListTemplateType.DocumentLibrary;
lci.QuickLaunchOption = QuickLaunchOptions.On;
List newList = ctx.Web.Lists.Add(lci);
ctx.ExecuteQuery();

The only difference between Creating a custom document library and Creating a new List instance using the CSOM is the value of ListTemplateType. For a document library, you could also define a DocumentTemplateType property to specify a custom document template.

Uploading files to and downloading files from a document library is simple. To upload, use code similar to that shown in Uploading a file to a document library using the CSOM.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
List targetList= ctx.Web.Lists.GetByTitle("Custom Documents");
FileCreationInformation fci = new FileCreationInformation();
fci.Content = System.IO.File.ReadAllBytes("SampleFile.txt");
fci.Url = "SampleFile.txt";
fci.Overwrite = true;
File fileToUpload = newList.RootFolder.Files.Add(fci);
ctx.Load(fileToUpload);
ctx.ExecuteQuery();

The key point of Uploading a file to a document library using the CSOM is the creation of an instance of FileCreationInformation type. The FileCreationInformation instance accepts a relative value for the Url property of the file to upload, and then collects the file in the right folder, based on the folder where the FileCreationInformation instance will be added. To upload a file, you can use the SaveBinaryDirect static method provided by the File class.

To avoid problems while uploading files, be careful to check the maximum upload file size. If necessary, you have the option to increase the maximum upload file size.

Downloading a file from a document library using the CSOM illustrates downloading a file.

 ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
List targetList = ctx.Web.Lists.GetByTitle("Custom Documents");
ctx.Load(targetList, lst => lst.RootFolder);
ctx.ExecuteQuery();
String fileToDownload = (targetList.RootFolder.ServerRelativeUrl + 
"/SampleFile.txt");
FileInformation fileInfo = File.OpenBinaryDirect(ctx, fileToDownload);
using (System.IO.StreamReader sr = new System.IO.StreamReader(fileInfo.Stream)) {
    String content = sr.ReadToEnd();
    Console.WriteLine(content);
}

Notice that the listing retrieves a Stream object from the FileInformation object to manage the file at a low level. Additionally, the FileInformation instance can be retrieved by invoking the OpenBinaryDirect static method of the File class.

As with downloading and uploading a file, to check a document in and out, you need to use the corresponding methods File.CheckIn and File.CheckOut. It’s a good habit to check the CheckOutType property of the current File instance to determine if the file has to be checked in or checked out. Check-in and checkout of a file in a document library using the CSOM provides an example.

ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
List targetList = ctx.Web.Lists.GetByTitle("Custom Documents");
ctx.Load(targetList, lst => lst.RootFolder);
ctx.ExecuteQuery();
String fileToRetrieve = (targetList.RootFolder.ServerRelativeUrl + 
"/SampleFile.txt");
File file = ctx.Web.GetFileByServerRelativeUrl(fileToRetrieve);
ctx.Load(file);
ctx.ExecuteQuery();
if (file.CheckOutType == CheckOutType.None) {
    file.CheckOut();
}
else {
    file.CheckIn("Finished check-out!", CheckinType.MajorCheckIn);
}
ctx.ExecuteQuery();

Just as on the Server Object Model, the CheckIn method allows you specify the revision (minor, major, or overwrite) of the document that you want to check in.

To copy and move a file from a document library, you first need to retrieve a reference to the target File instance, as you did in the previous examples. Once you have the reference, you can invoke the MoveTo method or the CopyTo method, depending on whether you want to move the file or copy it. Copying or moving a file between document libraries demonstrates how.

ClientContext ctx = new ClientContext("http://devbook.sp2013.local/");
List targetList = ctx.Web.Lists.GetByTitle("Custom Documents");
ctx.Load(targetList, lst => lst.RootFolder);
ctx.ExecuteQuery();
String fileToRetrieve = (targetList.RootFolder.ServerRelativeUrl + 
"/SampleFile.txt");
File file = ctx.Web.GetFileByServerRelativeUrl(fileToRetrieve);
file.CopyTo("Shared Documents/SampleFileCopy.txt", true);
file.MoveTo("Shared Documents/SampleFileMoved.txt", MoveOperations.Overwrite);
ctx.ExecuteQuery();

Both of these methods accept some parameters beyond the destination file relative URL. The CopyTo method accepts a Boolean argument that determines if the file should overwrite any existing destination item, and the MoveTo method uses an enumeration for almost the same purpose. Note that both methods copy or move not only the binary content of the file, but also its field values (metadata).

The previous section showed you how to consume the SharePoint REST API using an HTTP client, such as the WebClient class of System.Net. However, it wouldn’t be very pleasant to manually compose all the URLs corresponding to every kind of query, and then manually parse the responses in XML (Atom) format. Fortunately, Microsoft Visual Studio and .NET provide established support for services compliant with the OData specification. In fact, if you add a service reference to the ListData.svc service within a Visual Studio 2012 .NET project, the environment will recognize the service as an OData service and will provide you with a high-level interface to access the published resources.

Every OData service can provide a set of metadata, which is available by invoking the URL $metadata, and the Add Service Reference tool can read this metadata to create a set of typed classes representing each published resource. Figure 7-5 shows the Add Service Reference dialog box while a reference to an OData-compliant service is being added. Remember that you must refresh the reference each time you change or update the schema of your data in SharePoint.

Figure 7-5. The Add Service Reference dialog box, shown while adding a reference to an OData-compliant service.

After you create a service reference to an OData service, you will be able to create an instance of an object called {ServiceName}DataContext that represents the proxy to the service and inherits from System.Data.Services.Client.DataServiceContext. If you’re using a SharePoint REST service, the proxy class will have a name like {SiteTitle}DataContext, where SiteTitle represents the title of the target site, without spaces. In the book’s example, the site title is DevLeap Book Portal, so the class will have a long but clear and self-explanatory name: DevLeapBookPortalDataContext.

Through instances of this class, you will be able to access and query the list items of the site as if they were collections of typed entities. In fact, every list corresponds to a collection property of the proxy class. Every content type corresponds to an entity type. For instance, for the book’s sample site, the DevLeap Contacts list of SharePoint will correspond to a DevLeapContacts collection property of the proxy class. This collection will host typed instances of contact items. Querying contacts using the REST proxy displays an example of querying the contacts using the REST proxy.

 DevLeapBookPortalDataContext dc = new DevLeapBookPortalDataContext(
        new Uri("http://devbook.sp2013.local/_vti_bin/ListData.svc"));
dc.Credentials = System.Net.CredentialCache.DefaultCredentials;
foreach (var item in dc.DevLeapContacts) {
    Console.WriteLine(item);
}

Querying contacts using the REST proxy shows that the DataContext class provides a constructor that requires an argument of type System.Uri that corresponds to the URL of the ListData.svc service endpoint. If you need to authenticate this against the remote service, you can use the Credentials property of the DataContext class. This property accepts a type implementing System.Net.ICredential, which for example is implemented by the System.Net.CredentialCache.DefaultCredentials class, and which corresponds to the system credentials of the current application. Then you only need to query (enumerate) the content of the collections in which you are interested to access the corresponding items.

One interesting thing to know is that the autogenerated code supports LINQ queries, too. Thus, you can write a query targeting the collections of items published by the DataContext class, as shown in Querying contacts by using a LINQ query. Furthermore, the LINQ query is not a LINQ to Objects query working in memory; rather, it is a query managed by a query provider that will translate the LINQ query into a REST (OData-style) query.

 DevLeapBookPortalDataContext dc = new DevLeapBookPortalDataContext (
        new Uri("http://devbook.sp2013.local/_vti_bin/ListData.svc"));
dc.Credentials = System.Net.CredentialCache.DefaultCredentials;
var query = from c in dc.DevLeapContacts
            where c.ContentType == "DevLeapCustomer"
            select new {
                c.ContactID,
                c.Title,
                c.CompanyName,
                c.CustomerLevelValue
            };
foreach (var item in query) {
    Console.WriteLine(item);
}

Notice that the DevLeapContacts property of the DataContext class is of type System.Data.Services.Client.DataServiceQuery<DevLeapContactsItem>. The DataServiceQuery<T> class implements the IQueryable<T> interface of the LINQ infrastructure and represents the proxy to the OData LINQ query provider, also known as WCF Data Services Client Library.

If you step into the code and add a watch on the query variable, you will see that the variable internally represents the query as a REST request, as with the following:

http://devbook.sp2013.local/_vti_bin/ListData.svc/DevLeapContacts()?$filter=ContentType
  eq 'DevLeapCustomer'&$select=ContactID,Title,CompanyName,CustomerLevelValue

If you try to copy this URL and paste it into the browser address bar, you will get back exactly the results of the query, represented in XML format.

If you like to query data of a SharePoint site while ignoring that it is a SharePoint site, then the REST way is your way, because you have a typed collection of items—even queryable with LINQ—that abstracts from the underlying repository. Of course there are some limitations with this approach. For instance, you cannot write just any kind of query, and there are some keywords and operators (join, average, First, FirstOrDefault, and so on) that by now are not supported by the WCF Data Services Client Library. If you try to invoke an unsupported query command, you will get back an exception like the following one:

Unhandled Exception: System.NotSupportedException: The method 'Join' is not supported.

An unsupported query syntax displays a code excerpt of an unsupported query syntax.

// This query does not work, because join is not supported
var query = from c in dc.DevLeapContacts
            where c.ContentType == "DevLeapCustomer"
            join i in dc.Invoices on c.Id equals i.InvoiceCustomerLookupId
            select new { c.ContactID, c.Title, c.CompanyName, i.Name };

However, there are already a lot of useful commands and keywords that are supported. For example, you can do paging by using Skip and Take, and you can do ordering and more. Paging in a LINQ query demonstrates how to implement paging across a list of items.

// Get the second page, with a page size of 10
var query = (from c in dc.ContactsCOM
            select c).Skip(10).Take(10);

The URL request corresponding to the query in Paging in a LINQ query is the following:

http://devbook.sp2013.local/_vti_bin/ListData.svc/ContactsCOM()?$skip=10&$top=10

You can see the $skip and $top parameters illustrated in the previous section, which apply the paging rules defined in the code of Paging in a LINQ query.

The ability to query SharePoint data using the REST API is very interesting and by itself is probably sufficient to boost the enthusiasm level for this API. However, this is just half of the story. With the REST API, from the perspective of the OData specification, you can also manage (insert, update, or delete) data using a fully typed approach, even if you are working on the client side.

The DataContext class provides an identity management service, which allows working with retrieved entities as though they were entities of a typical object-relational mapper (O/RM), such as LINQ to SQL, LINQ to Entities, or LINQ to SharePoint.

Whenever you retrieve an entity—not a custom anonymous type based on a custom projection—you can manage its properties and inform the source SharePoint server about your changes, applying them with a batch job. Updating a previously existing item via REST shows a code excerpt that updates the property of an existing item.

 DevLeapBookPortalDataContext dc = new DevLeapBookPortalDataContext(
        new Uri("http://devbook.sp2013.local/_vti_bin/ListData.svc"));
dc.Credentials = System.Net.CredentialCache.DefaultCredentials;
DevLeapContactsItem item = (from c in dc.DevLeapContacts
                            where c.ID == 1
                            select c).First();
item.CompanyName += " - Changed!";
dc.UpdateObject(item);
dc.SaveChanges();

As the code sample shows, immediately after updating the entity, you need to manually invoke the UpdateObject method of the DataContext class to instruct it about the change you made. This is a requirement because internally the DataContext proxy class does not automatically track changes to objects. You can change many entities at the same time, and when you have finished, you simply need to invoke the SaveChanges method of the DataContext object in order to send your changes back to the server.

If you need to add a new item to a target list, you can use the general-purpose AddObject method provided by the DataContext class. In the following snippet, you can see the signature of this method:

public void AddObject(string entitySetName, object entity);

You can also use a fully typed method called AddTo{ListName}, which is a wrapper around the AddObject untyped method, and is automatically generated by the tools that generate the service reference. For the sake of clarity, the following shows the definition of the method AddToDevLeapContacts:

public void AddToDevLeapContacts(DevLeapContactsItem devLeapContactsItem) {
    base.AddObject("DevLeapContacts", devLeapContactsItem);
}

Adding a new item to a list presents a code excerpt that adds an item to the sample list of contacts.

 DevLeapBookPortalDataContext dc = new DevLeapBookPortalDataContext(
        new Uri("http://devbook.sp2013.local/_vti_bin/ListData.svc"));
dc.Credentials = System.Net.CredentialCache.DefaultCredentials;
DevLeapContactsItem item = new DevLeapContactsItem {
    Title = "Sample Customer",
    ContactID = "CC001",
    ContentType = "DevLeapCustomer",
    CompanyName = "Sample Company",
    CountryValue = "Germany",
    CustomerLevelValue = "Level A"
};
dc.AddToDevLeapContacts(item);
dc.SaveChanges();

The sample code creates a new instance of an object with a type compliant with the target list. Then it sets the properties of the item (for instance, the fields) and adds it to the target list using the AddTo{ListName} method. Lastly, it invokes the SaveChanges method of the DataContext object to confirm the changes on the server side. Notice that the target list accepts two kinds of content types, so the sample also configures the ContentType property of the item in order to instruct SharePoint about the right content type to use on the server side.

The last common task in managing data is deleting entities. The DataContext class offers a DeleteObject method, which accepts an entity that will be marked to be deleted at the next SaveChanges invocation. Thus, to delete an item, you simply need to invoke SaveChanges, as Deleting an item from a list demonstrates.

 DevLeapBookPortalDataContext dc = new DevLeapBookPortalDataContext(
        new Uri("http://devbook.sp2013.local/_vti_bin/ListData.svc"));
dc.Credentials = System.Net.CredentialCache.DefaultCredentials;
DevLeapContactsItem item = (from c in dc.DevLeapContacts
                            where c.ContactID == "CC001"
                            select c).First();
dc.DeleteObject(item);
dc.SaveChanges();

The OData client library available in Visual Studio 2012 also provides full support for handling concurrency issues while managing data. However, it is beyond the scope of this chapter (and this book) to give you the proper coverage of the WCF Data Services Client Library. The key is understand the potential of this API while managing SharePoint data and external data in general whenever you have an OData provider available.