Overview of the SharePoint CAML language

CAML stands for Collaborative Application Markup Language. It's an XML based query language that you can use to filter, sort and group by list items in a SharePoint list to quickly find back the correct items based on your given criteria.

You could compare it with writing SQL queries. You can define which columns need to be compared in which way with a certain value. You can combine with AND or OR. You can have as many as this combinations as you want.

The complete schema definition you can find here.

Some handy examples

One single filter

   1: <where>

   2:     <and>

   3:           <contains>

   4:                    <FieldRef name="InternalColumnName" />

   5:                    <Value Type="Text">ValueToFind</Value>

   6:           </contains>

   7:     </and>

   8: </where>

Combination of two filters

   1: <Where>

   2:   <Or>

   3:      <Geq>

   4:          <FieldRef Name="Field1"/>

   5:          <Value Type="Number">1500</Value>

   6:      </Geq>

   7:      <Leq>

   8:         <FieldRef Name="Field2"/>

   9:         <Value Type="Number">500</Value>

  10:      </Leq>

  11:    </Or>

  12: </Where>

Combining more than two filters (you can only have two filters on the same level!):

   1: <Where>

   2:     <And>

   3:       <Or>

   4:          <Geq>

   5:              <FieldRef Name="Field1"/>

   6:              <Value Type="Number">1500</Value>

   7:          </Geq>

   8:          <Leq>

   9:             <FieldRef Name="Field2"/><Value Type="Number">500</Value>

  10:          </Leq>

  11:        </Or>

  12:        <Eq>

  13:           <FieldRef Name="Field3"/><Value Type="Text">Value</Value>

  14:        </Eq>

  15:     </And>

  16: </Where>

Ordering

   1: <OrderBy> 

   2:        <FieldRef Name="Modified" Ascending="FALSE"></FieldRef> 

   3: </OrderBy> 

   4: <Where> 

   5:   <Or> 

   6:     <Neq> 

   7:       <FieldRef Name="Status"></FieldRef> 

   8:       <Value Type="Text">Completed</Value> 

   9:     </Neq> 

  10:     <IsNull> 

  11:       <FieldRef Name="Status"></FieldRef> 

  12:     </IsNull> 

  13:   </Or> 

  14: </Where>

Filtering on lookup field (first example is when querying the list item’s ID, second example is querying on the lookup value itself)

   1: <Where>

   2:     <Eq>

   3:       <FieldRef Name="LookupFieldInternalName" LookupId="TRUE" />

   4:       <Value Type="Lookup">15</Value>

   5:     </Eq>

   6: </Where>

   1: <Where>

   2:     <Eq>

   3:       <FieldRef Name="LookupFieldInternalName" />

   4:       <Value Type="Lookup">LookupValue</Value>

   5:     </Eq>

   6: </Where>

Using it within your code

The following example will show you how you can actually use these queries in your code. You will create a SPQuery object, assign the query and use it on a list. What you get back is a list of items that are the result of your query.

   1: SPWeb oWebsiteRoot = SPContext.Current.Site.RootWeb

   2: SPList oList = oWebsiteRoot.Lists["Tasks"];

   3:  

   4: SPQuery oQuery = new SPQuery();

   5: oQuery.Query = "<Where><Eq><FieldRef Name='Status'/>" +

   6:     "<Value Type='Text'>Completed</Value></Eq></Where>";

   7: SPListItemCollection collListItems = oList.GetItems(oQuery);

   8:  

   9: foreach (SPListItem oListItem in collListItems)

  10: {

  11:     Response.Write(SPEncode.HtmlEncode(oListItem["Title"].ToString()) + 

  12:         "<BR>");

  13: }

SharePoint 2010 hierarchy and related API classes

The structure of a SharePoint farm in most cases always is the same. First you have the SharePoint farm itself, in there you have one or more Web Applications, in a web application you have one or more site collections, in a site collection you have one or more sites, in a site you have one or more lists and in a list you have one or more list items.

Each of these levels has its own SharePoint API class. Instances of this class can be used to talk to these entities and do stuff with them.

When you start using these objects, it's important to dispose them when necessary. I lot of them implement the IDisposable interface, meaning you can use them in a so called 'using' statement. In the 'using' statement you create an instance of the class, do stuff with it and dispose of it when the 'using' statement comes to its end. This is important because a lot of these objects are quiet heavy and could cause a lot of memory usage or even memory leaks.

For example:

(using code example)

The respective classes

SPFarm - SharePoint farm

SPWebApplication - Web application

SPSite - Site collection

SPWeb - Site

SPList - List

SPListItem - Item

Some good things to know

Opening a web directly from the URL

   1: using (SPSite site = new SPSite("http://sitecollection1/subsite1"))

   2: {

   3:  

4: using (SPWeb web = site.OpenWeb())

   5:     {

   6:  

   7:         // Use the site/web object

   8:  

   9:     }

  10:  

  11: }

Using the ‘TryGetList’ method: new in SharePoint 2010 is the ‘TryGetList’ method to try to get a list in a given web. In the past, this could throw an exception and it was the only way to find out that the list did not exist.

   1: using (SPSite site = new SPSite("http://sitecollection1/subsite1"))

   2: {

   3:  

   4:     using (SPWeb web = site.OpenWeb())

   5:     {

   6:  

   7:         SPList list = web.Lists.TryGetList("ListTitle");

   8:  

   9:         if (list != null)

  10:         {

  11:  

  12:  

  13:             // List exist so you can safely use it

  14:  

  15:         }

  16:  

  17:     }

18:

  19: }

Finding particular list items: when you want to find list items based on their metadata, it’s not advisable to just write a for loop and check each item. It’s better to use a Collaborative Application Markup Language (CAML) query. A dedicated article in the ‘SharePoint for dummies’ series has been written for this.

   1: using (SPSite site = new SPSite("http://sitecollection1/subsite1"))

   2: {

   3:  

4: using (SPWeb web = site.OpenWeb())

   5:     {

   6:  

   7:         SPList list = web.Lists.TryGetList("ListTitle");

   8:  

   9:         if (list != null)

  10:         {

  11:  

  12:             SPQuery query = new SPQuery();

  13:             query.Query = "<Where>" +

14: "<Eq>" +

  15:                  "<FieldRef Name='Title' />" +

  16:                   "<Value Type='Text'>TitleYouWantToFind</Value>" +

  17:               "</Eq>" +

  18:             "</Where>";

  19:  

  20:             SPListItemCollection iColl = list.GetItems(query);

  21:  

  22:             // Loop the collection

  23:  

24: }

  25:  

  26:     }

  27:  

  28: }

Using the SharePoint command line

SharePoint also offers you a command line with a big collection of commands that you can use to perform all kinds of tasks.

In SharePoint 2010 this is called the stsadm tool, which is located in C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\BIN. You can create a shortcut to the Windows command line tool (cmd.exe) and set the start directory to C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\BIN so you can quickly start using stsadm at all times. The stsadm tool is fully extendable with your own commands. Many other people have already done this. I think the most famous one for this is Gary Lapointe, who has dedicated a large blog talking about nothing else then his stsadm extensions. If you want an overview of all the out of the box stsadm commands, please take a look at this post.

In SharePoint 2010 stsadm is stil available although officially deprecated. It’s now advised to use PowerShell which has a huge number of out of the box SharePoint 2010 commandlets. You can even fully automate your SharePoint 2010 installation. If you want an overview of all out of the box SharePoint 2010 PowerShell commandlets, take a look at this post.

Preparing your environment for debugging

By default, SharePoint will suppress error messages to the user. When something goes wrong you will most likely see the famous 'Unexpected error'. If you want to see the full message, there are some web.config settings you need to change. In SharePoint 2007 you only had to set these settings in the root web.config, in SharePoint 2010 you need to alter different ones.

Enabling web.config to enable debug information

SharePoint 2007:
- in your web application's root (C:\inetpub\wwwroot\wss\VirtualDirectories\SharePointSiteFolder), open the web.config and change the following settings. The following settings are correct:

   1: <compilation batch=”false” debug=”true“>

   2: <SafeMode MaxControls="200" CallStack="true"/>

   3: <customErrors mode=”Off”>

SharePoint 2010:

- also change the web.config in the web application's root directory as described for SharePoint 2007

- the one that you can find into the "LAYOUTS" directory under the SharePoint root (the file at the path: C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS)

Finding extra debug/logging information
* Use the event viewer: a lot of the thrown exceptions will also write stack traces there

* Enable SharePoint 2010 logging by opening the Central Administration and going to ‘Monitoring –> Configure diagnostic logging'

Select what sources should be logged. A lot of new logging information will now be available under C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\LOGS.

Developer dashboard

Very handy to use and new in SharePoint 2010. You can turn it on using stsadm or PowerShell:

stsadm -o setproperty -pn developer-dashboard -pv on

(Get-SPFarm).PerformanceMonitor.DeveloperDashboardLevel = ”On”

What will happen is that at the bottom of each loaded page, extra information information about the loaded components on that page are shown. You can see what has been loaded, how long it took, which SQL queries were launched, wich web services were consumed, ... .

More information on how to use it you can find here.