Call Load and ExecuteQuery Before Accessing Value Properties

Article
10/20/2016

Applies to: SharePoint Foundation 2010

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:

Build a SQL query, through either an ad-hoc SQL query or a stored procedure.
Execute the SQL query.
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.

Share via

Call Load and ExecuteQuery Before Accessing Value Properties

See Also

Concepts

Additional resources