Call Load and ExecuteQuery Before Accessing Value Properties

Applies to: SharePoint Foundation 2010

Available in SharePoint Online

Before you can access value properties of a client object, you must call the Load<T>(T, []) method (JavaScript: load(clientObject)) and the ExecuteQuery() or ExecuteQueryAsync(ClientRequestSucceededEventHandler, ClientRequestFailedEventHandler) method (JavaScript: executeQueryAsync(succeededCallback, failedCallback)) on the ClientContext object (JavaScript: ClientContext).

If you are familiar with the Microsoft SharePoint Foundation 2010 server object model, you might be tempted to write code that uses the client library in the same way that you write code that uses the server library. For example, if you want to display the title of a Web site, you might think that you can write code like the following in C# example that uses the client library.

Incorrect Code

using System;
using Microsoft.SharePoint.Client;

namespace Microsoft.SDK.SharePointServices.Samples
{
    class WebSiteTitle
    {
        static void Main()
        {
            ClientContext clientContext = new ClientContext("http://MyServer/sites/MySiteCollection");
            Web oWebsite = clientContext.Web;
            Console.WriteLine(oWebsite.Title);
        }
    }
}

Compiling the code returns a PropertyOrFieldNotInitializedException because the value of the property has not been retrieved from the server. The example returns an exception because the client library uses a SQL-like programming pattern. When you use SQL, you must:

  1. Build a SQL query, through either an ad-hoc SQL query or a stored procedure.

  2. Execute the SQL query.

  3. Read the results from SQL.

The client object model uses the same pattern as SQL. When you call a method, you are building a query with the client library. You can build queries, and they can accumulate before being executed, but you have not sent them to the server until you first load the appropriate object or property through the Load<T>(T, []) method (JavaScript: load(clientObject)), and then call the ExecuteQuery() or ExecuteQueryAsync(ClientRequestSucceededEventHandler, ClientRequestFailedEventHandler) method (JavaScript: executeQueryAsync(succeededCallback, failedCallback)). To make the previous code work, you must make the following changes.

Correct Code

using System;
using Microsoft.SharePoint.Client;

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

            clientContext.Load(oWebsite,
                w=>w.Title);

            clientContext.ExecuteQuery();

            Console.WriteLine(oWebsite.Title);
        }
    }
}
Imports System
Imports Microsoft.SharePoint.Client

Namespace Microsoft.SDK.SharePointServices.Samples
    Class WebSiteTitle
      
        Shared Sub Main()
            Dim clientContext As New ClientContext("http://MyServer/sites/MySiteCollection")
             Dim oWebsite As Web = clientContext.Web
         
             clientContext.Load(oWebsite, Function(w) w.Title)
         
             clientContext.ExecuteQuery()
         
             Console.WriteLine(oWebsite.Title)
        End Sub
    End Class
End Namespace
function retrieveWebSite() {
    var clientContext = new SP.ClientContext('/sites/MySiteCollection');
    this.oWebsite = clientContext.get_web();

    clientContext.load(oWebsite, 'Title');

    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

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

To improve performance, the first method call added to the previous example uses a LINQ query expression to ask explicitly for the Web site’s Title property (JavaScript: title). The second method call then executes the query. Specifying the Web site's title through the client object model thus works similarly to the SQL command SELECT Title FROM Webs. If you want to retrieve all properties of the Web site, you can use clientContext.Load(oWebsite);, which is similar to the SQL command SELECT * FROM Webs.

See Also

Concepts

Data Retrieval Overview

Value Objects Cannot Be Used Across Methods in a Query

SharePoint Client Objects Can Be Used Across Methods in a Query

Group Data Retrieval on the Same SharePoint Client Object

Retrieving a SharePoint Client Object Does Not Retrieve All Properties