Client Context as Central Object

Article
10/20/2016

Applies to: SharePoint Foundation 2010

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:

using System;
using Microsoft.SharePoint.Client;

namespace Microsoft.SDK.SharePointServices.Samples
{
    class UsingClientContext
    {
        static void Main()
        {
            ClientContext clientContext = new ClientContext("http://MyServer/sites/MySiteCollection");

            Web oWebsite = clientContext.Web;

            clientContext.Load(oWebsite);

            clientContext.ExecuteQuery();

            Console.WriteLine(oWebsite.Title);
        }
    }
}

Imports System
Imports Microsoft.SharePoint.Client

Namespace Microsoft.SDK.SharePointServices.Samples
   Class UsingClientContext
      
      Shared Sub Main()
         Dim clientContext As New ClientContext("http://MyServer/sites/MySiteCollection")

         Dim oWebsite As Web = clientContext.Web

         clientContext.Load(oWebsite)

         clientContext.ExecuteQuery()
         
         Console.WriteLine(oWebsite.Title)
      End Sub
   End Class
End Namespace

function useClientContext() {
    var clientContext = new SP.ClientContext('/sites/MySiteCollection');
    this.oWebsite = clientContext.get_web();
    clientContext.load(oWebsite);
    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());
}

Client Context as Central Object

See Also

Concepts

Other Resources

Additional resources