Client Context as Central Object

SharePoint 2010

Last modified: July 15, 2010

Applies to: SharePoint Foundation 2010

Available in SharePoint Online

Similarly to programming against server objects in the server context, which involves instantiating or returning a central object that provides access to the object model, the new client-side object models use a ClientContext object (JavaScript: ClientContext) as the "center of gravity" for all operations. The process of obtaining and working with sites and data begins by retrieving a context object. For example, ClientContext clientContext = new ClientContext("http://MyServer/sites/MySiteCollection") instantiates the context object for a specific site collection.

The ClientContext object (JavaScript: ClientContext) serves as the main entry point for accessing the client object model and as the central object through which to orchestrate requests and initiate actions within a site collection. Use object properties of the ClientContext object (JavaScript: ClientContext) to obtain site collections or Web sites through which to access other SharePoint Foundation client objects remotely.

The ClientContext() constructor (JavaScript: ClientContext(serverRelativeUrl)) initializes a client context based on a specified Web site or site collection. In the managed client object model, the URL must be the absolute URL of a particular Web site. In the ECMAScript (JavaScript, JScript) object model, either a server-relative URL or no parameter is required. In JavaScript, if you use the constructor that takes no parameter, the target Web site URL is the URL of the Web site that contains the Web page.

Before actually executing a query, you use the objects that are returned through the client context to define the actions to perform. The ClientContext class (JavaScript: ClientContext) inherits the Load<T>(T, []) (JavaScript: load(clientObject)) and LoadQuery() (JavaScript: loadQuery(clientObjectCollection, exp)) methods from the ClientRuntimeContext class (JavaScript: ClientRuntimeContext). You define a query to perform specific actions and return specific objects or properties, and then you call one of these methods to load the query.

After you load a query, call the ExecuteQuery() or ExecuteQueryAsync(ClientRequestSucceededEventHandler, ClientRequestFailedEventHandler) method (JavaScript: executeQueryAsync(succeededCallback, failedCallback)) of the ClientContext object (JavaScript: ClientContext) to send the query to the server. The Silverlight client object model provides both an ExecuteQuery() method, which can be called synchronously from threads that do not modify the user interface (UI), and an asynchronous ExecuteQueryAsync(ClientRequestSucceededEventHandler, ClientRequestFailedEventHandler) method for cases where threads do modify the UI. These methods for executing queries formulate XML that represents the actions taken on the client, and send the XML to the server. In the managed object model, this call is synchronous, which means that code execution is blocked until a response is received from the server. This call can be either synchronous or asynchronous in the Silverlight object model, but it is always asynchronous in the JavaScript object model. In an asynchronous call, code continues to execute and does not wait for the server response. In the Silverlight and JavaScript object models, you can implement a callback function that is invoked when the server response is received.

In the SharePoint Foundation Silverlight and JavaScript object models, you can use the Current property (JavaScript: current) of the client context to return the current request context from pages that operate within SharePoint Foundation.

The following example illustrates the basic steps for using methods of the ClientContext class (JavaScript: ClientContext) to return the title of a Web site:

function useClientContext() {
    var clientContext = new SP.ClientContext('/sites/MySiteCollection');
    this.oWebsite = clientContext.get_web();
    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));

function onQuerySucceeded() {
    alert('Title: ' + oWebsite.get_title());
function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());