A Look at CAML for SharePoint Development

Overview

For a quick summary of how CAML improved performance on a list items query, read this article from author and SharePoint development expert Sahil Malik.
The Collaborative Application Markup Language (CAML) is an XML-based language that is primarily used to perform data manipulation. In a number of cases, using CAML helps improve your program's performance.

CAML Tutorial

If you are unfamiliar with CAML syntax, Karine Bosch wrote a fantastic tutorial on writing CAML queries for SharePoint Magazine. She covers all the basics and the "gotchas" of CAML syntax in an easy-to-follow manner.

Helpful Tools

When I am writing code where I need to use CAML, I am partial to two FREE tools.
Screenshot of Stramit CAML viewer. Click on the image for a larger view.


The Stramit CAML Viewer is an "all-in-one" tool that not only lets you view and test CAML queries, but it also displays the GUIDs for lists and views. You can download this tool from CodePlex.

Screenshot of U2U Caml Query Builder. Click on the image for a larger view.


The U2U CAML Query Builder is a slick, time-saving tool that will automatically build the CAML query for you based on the information entered by you. It also has a feature where you can copy the built CAML query to the clipboard. You can download this tool from the U2U site.

CAML in Action: A Simple Query

Note: This code will only work on a server where SharePoint is installed. For example, if you are going to add a view to a list that exists on http://bogus/bogussite, you need to have this code on the server that houses http://bogus.

In this example, I have a list on my site called Doctor Who Episodes. I would like to get the list of episodes that starred Jon Pertwee as the Doctor, and I would like to order that list by the year. My application, written for demonstration purposes only (no "fancy" formatting, application usability design, or full performance evaluation was considered), will display the episode list in a text box the moment the application runs (Form_Load).
Click on the image for a larger view.


After creating a new C# Windows application called SimpleCAMLQuery, I added reference to the Microsoft.SharePoint library in my project and referenced the library in my code.

using Microsoft.SharePoint;


I added the following in the Form_Load event:
I defined three variables to hold the URL for the site, the list name, and the view name.

String siteName = "http://bogus/bogussite";
String listName = "Doctor Who Episodes";
String viewName = "All Items";


I then used SPSite, SPWeb, and SPList to open my list on my site. I also used SPQuery to open my view, since this class has the method/function to use for the CAML query.

SPSite site = new SPSite(siteName);
SPWeb web = site.OpenWeb();
SPList list = web.Lists[listName];
SPQuery query = new SPQuery(list.Views[viewName]);


I then build my CAML query using the StringBuilder class. You can also put the CAML query directly into a string object if you prefer. If the field has spaces or special characters in the name (as it does in my example - the field in my list is called "The Doctor"), you need to reference the hexadecimal values in the name.


System.Text.StringBuilder oSb = new System.Text.StringBuilder();
oSb.Append(" <Where>");
oSb.Append(" <Eq>");
oSb.Append(" <FieldRef Name=\"The_x0020_Doctor\" />");
oSb.Append(" <Value Type=\"Text\>Jon Pertwee</Value>");
oSb.Append(" </Eq>");
oSb.Append(" </Where>");
oSb.Append(" <OrderBy>");
oSb.Append(" <FieldRef Name=\"Year\" Ascending=\"True\" />");
oSb.Append(" </OrderBy>");

Note: The order in which the Where and the OrderBy tag blocks appear in the CAML doesn't matter. Some people place the OrderBy tag blocks before the Where tag blocks. I usually place the OrderBy tag blocks after the Where tag blocks because I'm used to writing SQL, and in SQL syntax, the Order clause comes after the Where clause.

I then called the Query method/function of the SPQuery object to set up the CAML query

query.Query = oSb.ToString();


Finally, I put the results in a SPListItemCollection object and looped through the object.

SPListItemCollection results = list.GetItems(query);
foreach (SPListItem i in results)
{
  txtResults.Text += i["LinkTitle"].ToString();
  txtResults.Text += Environment.NewLine;
  txtResults.Text += i["Synopsis"].ToString();
  txtResults.Text += Environment.NewLine;
  txtResults.Text += i["Year"].ToString();
  txtResults.Text += "----------------------------------------";
  txtResults.Text += Environment.NewLine;
  txtResults.Text += Environment.NewLine;
}



Here is the full code:
Click on the image for a larger view.

Additional examples of CAML in Action

If you would like to see additional examples of using CAML, view these previous posts on my blog:

• Programmatically Deleting All Items from a List (see Approach #2 in the document)


• Programmatically Create View on a List

If you have any questions, comments, or additional examples, please feel free to post a comment.