Sharepoint 2013 : Working with the CSOM (part 1) - Understanding client object model fundamentals

Much like the standard code you write against the server-side object model, CSOM requires a starting point in the form of a context object. The context object provides an entry point into the associated API that can be used to gain access to other objects. Once you have access to the objects, you can interact with the scalar properties of the object freely (for example, Name, Title, Url, and so on). Example 1 shows how to create a context in each of the models and return an object representing a site collection. After the site collection object is returned, the Url property is examined.

//Managed Client Object Model
string appWebUrl = Page.Request["SPAppWebUrl"];
using (ClientContext ctx = new ClientContext(appWebUrl))
{
    Site siteCollection = ctx.Site;
    ctx.Load(siteCollection);
    ctx.ExecuteQuery();
    string url = siteCollection.Url;
}

//JavaScript Client Object Model
var siteCollection;
var ctx = new SP.ClientContext.get_current();
siteCollection = ctx.get_site();
ctx.load(site);
ctx.executeQueryAsync(success, failure);

function success() {
    string url = siteCollection.get_url();
}
function failure() {
    alert("Failure!");
}

The ClientContext class in the managed object model inherits from the ClientContextRuntime class. Using the ClientContext class, you can get a valid runtime context by passing in the URL of a site. In Example 1, the URL of the app web is retrieved from the SPAppWebUrl query string parameter. This URL is always available to the remote web and can be used to create a client context for scenarios in which the SharePoint app is using the “internal” security principal.

The SP.ClientContext object in the JavaScript client object model inherits from the SP.ClientContext Runtime object and provides equivalent functionality to the ClientContext class found in the managed client object model. Like the managed model, you can get a runtime context in the JavaScript model by using the SP.ClientContext class and passing a URL. In Example 1, the context is created by using the get_current method, which returns a client context for the app web.

The ClientContextRuntime class used by the managed client defines two methods for loading objects: Load and LoadQuery. You use these load methods to designate objects that should be retrieved from the server. The Load method specifies an object or collection to retrieve, whereas you use the Load Query method to return collections of objects by using a Language-Integrated Query (LINQ) request.

Executing the Load or LoadQuery method does not cause the client to communicate with the server. Instead, it adds the load operation to a batch that will be executed on the server. In fact, you can execute multiple load methods (as well as other operations) before calling the server. Each operation is batched waiting for your code to initiate communication with server. To execute the batched operations, your code must call the ExecuteQuery method in managed code or the Execute QueryAsync method in JavaScript. The ExecuteQuery method creates an XML request and passes it to the Client.svc service synchronously. The ExecuteQueryAsync method sends the request asynchronously. Designated success and failure callback methods receive notification when the asynchronous batch operation is complete.

The sample code in Example 1 uses the Load method to request an object representing the current site collection. After an object is returned, you can generally access any of the scalar properties associated with the object. In cases for which you do not want to return all of the scalar properties for a given object, you can designate the properties to return. In the managed object, properties are designated by providing a series of lambda expressions. In the JavaScript object model, properties are designated by name. This technique helps to minimize the amount of data sent between the client and server. The following code shows how to request only the Title and ServerRelativeUrl properties for a site collection object:

//Managed CSOM references properties via lambda expressions
ctx.Load(site, s=>s.Title, s=>s.ServerRelativeUrl);

//JavaScript CSOM references properties by name
ctx.Load(site, "Title", "ServerRelativeUrl");