SharePoint 2010: Conditional Scope

In my previous post I had explained about Exception Handling Scope. If you have not read the post already then I’ll suggest you to read the post as the idea behind this scope in SharePoint Client Object Model has been described in that previous post.

In Client Object Model, if you need to load data based on some condition. But if the condition is based on some server side values then you need to use two different requests. First request will be to get the values from the server to check the condition. Second request will be to load data or not, based on the condition expression value.

In SharePoint Client Object Model API, there’s a new class called ConditionalScope to load data conditionally. Here’s how to use the ConditionalScope:

• In ConditionalScope constructor pass the ClientContext instance as first parameter. In the second parameter, pass the condition to be evaluated on the server. As shown below, the condition to check is whether the list is hidden or not.

var conditionalScope = new ConditionalScope(clientContext, () => !list.Hidden);

• The second step is to put the load expression in ConditionalScope’s StartScope method. As shown below, if the list is not hidden, then load the Title of the list.

using (conditionalScope.StartScope())
{
    clientContext.Load(list, ol => ol.Title);
}

In the above statement, the load will be executed if the condition specified in ConditionalScope’s constructor is true (in this case, not hidden).

• Finally, after executing ClientContext.ExecutQuery method, you need to find out if the expression passed in Coditional Scope was true or false. If condition was true then u know the data has been loaded (in this case the title of the list). If the condition was not true then data was not loaded. To check whether the condition evaluated true of false, check conditional scope’s TestResult. Remember, you will only get this property value after executing Executing query to the server.

clientContext.ExecuteQuery();
if (conditionalScope.TestResult.HasValue && conditionalScope.TestResult.Value)
{
    Console.WriteLine("Title:" + list.Title);
}

As shown in the code snippet above, if the TestResult has been evaluated to true then the title property is available.

The whole code will look like below:

var clientContext = new ClientContext(siteUrl);
var web = clientContext.Web;
var list = web.Lists.GetByTitle(listName);

var conditionalScope = new ConditionalScope(clientContext, () => !list.Hidden);


using (conditionalScope.StartScope())
{
    clientContext.Load(list, ol => ol.Title);
}

clientContext.ExecuteQuery();
if (conditionalScope.TestResult.HasValue && conditionalScope.TestResult.Value)
{
    Console.WriteLine("Title:" + list.Title);
}

 

Limitations

You can not use Conditional scope in all cases for all operations:

• You can only load data using Conditional Scope. You can not however call any method or set properties in Conditional Scope’s StartScope method. If you use the ConditionalScope to set properties or to call server side method, you may get the following error:

Incorrect usage of conditional scope. Some actions, such as setting a property or invoking a method, are not allowed inside a conditional scope.

• expression passed in ConditionalScope’s second argument has restrictions. You can not use all kinds of expressions. For example you can not use expression like, list.Fields.Count. However, you can use List.ItemCount. I have not found any documentation on MSDN with the supported expression for ConditionalScope.
• Before using ConditionalScope.TestResult in your decision to access data, you need to execute Query.