1. Using the SharePoint 2010 Client Object Model - Part 3
In the first two parts of this posting I described the pattern you can use to retrieve data with the client object model (“client OM”). I showed how to use the same pattern to retrieve both a set of lists, as well as data contained within a single list. In this post we’ll talk about ways that we can create and use filters when querying for data via the client OM.
I won’t rehash our pattern all over again. Suffice to say, it’s exactly the same, and the only part we are playing with here is step 2 – creating the statement to return the data and selecting which fields to return. Creating the connection and executing the query remain the same:
//create the connection
ClientContext ctx = newClientContext("http://foo");
//execute the query
ctx.ExecuteQuery();
For this release, the semantics of creating a query, ordering the results, etc. are going to be controlled by CAML. So as we saw in the previous posting, we use an instance of the CamlQuery class to do that. The CAML syntax has not changed between versions, so all the CAML you know and love will still be useful in the client OM.
From an implementation standpoint, the CamlQuery class has a property called ViewXml, and even though it may not be obvious from the property name, that’s where you plug in your criteria for your query as well. The ViewXml property expects to have a parent element called <View>, and then within it you add a <Query> and <Where> element to implement your criteria.
Suppose, for example, you want to retrieve all items from your list where the Title property equals Steve. Your code would look something like this:
CamlQuery cq = new CamlQuery();
cq.ViewXml = "<View><Query><Where><Eq><FieldRef Name='Title'/><Value Type='Text'>Steve</Value></Eq></Where></Query></View>";
As you can see it’s just standard CAML that is going in our ViewXml property. To use our CAML in our query, we go back to our List and call its GetItems method, returning an instance of a ListItemCollection. Here’s an example:
ListItemCollection lic = lst.GetItems(cq);
Just as you do with CAML in SharePoint 2007, you can also include sorting in your queries too. Here’s an example where I’m only sorting on one field, and I’m doing so in descending order (the default sort order is ascending):
cq.ViewXml = "<View><Query><Where><Eq><FieldRef Name='Title'/><Value Type='Text'>Steve</Value></Eq></Where><OrderBy><FieldRef Name='ID' Ascending='False'/></OrderyBy></Query></View>";
Now remember in the first two postings in this series where I talked about trying to choose the specific fields you wanted when executing a query, and how that impacts the size of the data sent over the wire? And I also showed a way in which you could get non-default properties returned when you asked for a ListItemCollection. Well I’m going to combine those two concepts now as we talk about loading our data. So far I’ve shown you a couple of ways to instruct the client OM to load up property values in a ListItemCollection (where “lic” is ListItemCollection):
METHOD #1:
ctx.Load(lic);
METHOD #2:
ctx.Load(lic, items => items.IncludeWithDefaultProperties(item => item.DisplayName));
Another way to set the list of properties retrieved is with a hybrid approach between these two models. We can use a Lambda expression and define every single property that we want returned for the ListItemCollection. In this example, suppose we only really need to see the ID, Title and DisplayName values. Here is how we would express that:
METHOD #3:
ctx.Load(lic, itms => itms.Include(
itm => itm["ID"],
itm => itm["Title"],
itm => itm.DisplayName));
Not only is it arguably the clearest code in terms of plainly stating what fields we’re going to return, it also delivers the data in the smallest payload by a wide margin. Here’s the size of the resulting data over the wire for each of the three methods above:
Again, it may not look like a huge difference when you examine the raw numbers, but over time, with lots of clients, or over a slow or latent network it can really add up. You can also control the number of items that are returned in a query. You can do it in CAML, or you can do it in your Lambda for setting the fields to be returned. Here’s an example of each method to limit the number of rows returned to 3.
CAML:
cq.ViewXml = "<View><RowLimit>3</RowLimit></View>";
Lambda:
ctx.Load(lic, itms => itms.Take(3).Include(
itm => itm["ID"],
itm => itm["Title"],
itm => itm.DisplayName));
What else can we do? The CamlQuery class is also used for paging queries, and lets you set the FolderServerRelativeUrl so you can effectively execute your queries in the subfolder of a list. Paging queries are a little more unique, so here’s a skeleton of how that would be implemented; note this is just for illustrative purposes, not necessarily a real scenario of how one would want to use paging:
//initialize a paging instance
ListItemCollectionPosition pos = null;
while (true)
{
//create the CAML query
CamlQuery cq = newCamlQuery();
//set our paging position and view xml
cq.ListItemCollectionPosition = pos;
cq.ViewXml = "<View><ViewFields><FieldRef Name='ID'/><FieldRef
Name='Title'/><FieldRef Name='Body'/></ViewFields>
<RowLimit>2</RowLimit></View>";
//get items using our CAML class
ListItemCollection lic = lst.GetItems(cq);
//load the items up - note how I have to ask separate for ListItemCollectionPosition
//if I don't, it will say property not initialized when I try and
//work with it below
ctx.Load(lic, itms => itms.ListItemCollectionPosition,
itms => itms.Include(
itm => itm["ID"],
itm => itm["Title"],
itm => itm.DisplayName));
//execute the query
ctx.ExecuteQuery();
//get our new paging position
pos = lic.ListItemCollectionPosition;
//enumerate each item
foreach (ListItem l in lic)
{
ItemsLst.Items.Add(l["Title"]);
}
//see if we've reached the end
if (pos == null)
break;
else
Debug.WriteLine(pos.PagingInfo);
}
Coming Next…
So, what other things can we do? Surprisingly, a lot. You can manage security in your site, you can create new lists, you can change the fields in a list, you can even add custom menu items, all with the client OM. I’ll cover some of these other random things in the future posts in this series.