Working with CAML.Net – Part 2

In Part 1 of this series, I introduced the CAML.NET Framework, which provides a way for C# developers (and eventually VB developers) to construct CAML queries and other data structures using a strongly-typed .NET language instead of XML.  This has the added benefit of enabling CAML queries to be packaged easily into .NET assemblies that can then be called from any .NET application.  It does this using a combination of static classes, generic methods and a base class library for automatic data-binding to and from SharePoint list items.

The use of a strongly-typed CAML query language is compelling for a number of reasons.  First of all – it’s strongly typed, which means it is easier to avoid and detect errors in the code.  Second – CAML.NET makes it easy to reuse the compiled queries and incorporate them into other projects.  It’s also easier to share them with other developers who may not understand the CAML syntax, but need to retrieve data from one or more SharePoint lists as part of their solution.

Having a strongly-typed language for expressing CAML queries is one thing.  Using the language effectively is another.  It would be nice if we could also share the essential elements of a CAML query with non-technical colleagues so that they can understand more precisely what the query is supposed to do.  Currently, the only way to do that is to use a whiteboard or a Visio diagram to sketch the query components and then use that diagram separately as the basis for implementing the query.

A New Tool for CAML Developers

In this post, I will introduce a new tool that further simplifies the developer experience when working with CAML and provides the basis for a new breed of developer tools aimed at bridging the gap between mainstream .NET development and SharePoint solution development.

The CAML Query Designer add-in for Visual Studio 2005 consists of the following components:

• A graphical design surface for designing CAML queries,
• A CAML.NET explorer tool window for browsing the query structure,
• A custom code generator that tranforms the query diagram into C# code.

Recall the CamlQuery class which is included in the CAML.NET package.   In Part 1, I gave an example of a derived query that retrieves list items by matching the name of its content type with an arbitrary string passed as an argument to the class constructor. 

    public class QueryByContentType : CamlQuery
    {
        public QueryByContentType(string typeName) : base(
            CAML.Where(CAML.Eq(CAML.FieldRef(“ContentType”), CAML.Value(typeName)))
            )
        { }
    }

To build this same query using the CAML.NET Query Designer, we  start by creating a CAML object model using the CAML.NET Visual Studio Project Item template.

This creates a new .caml file and opens the design surface.

 The toolbox contains several objects we can drag onto the design surface.  We’ll start with a Query object, and then add the fields we are interested in.  In this case, we’ll specify the name of the query as “QueryByContentType”, and then we’ll add the ContentType field as a field of interest.

 

At this point, we haven’t declared a relationship between the query and the field.  We’ve only added the field to the model.  We can relate the field to the query in two ways: we can link the field directly to the query using a connector; or we can add a qualifying statement to the query and then reference the field from the statement. 

Note: Connecting fields directly to the query says that the query should limit the result set to only those fields.  If there are no fields connected to the query, then the result set will include all fields associated with each item.

Next, we need to specify that the query should match all list items where the content type field matches a given expression.  To do this, we drag a Comparison operator from the toolbox onto the design surface and associate it with the ContentType field.   The Comparison operator can only be attached to the Query object.  To associate it with the ContentType field, we can simply select the field from the dropdown list in the properties pane.

Next, we could enter a literal expression into the Expression property of the comparison operator, but what we really want is to parameterize the expression so that the query can be applied to more than one content type.  To do that, we add a Query Parameter object to the model and give it the name “typeName” so we can reference it from the comparison operator.  As before with the Comparison object, the Query Parameter object can only be added to a Query object.

Now, the query is complete.  At this point, we can simply save the model.  This does two things:

• creates a folder within our Visual Studio project to help keep the queries organized,
• generates a C# class for each Query object in the model

With the where clause defined, we can then further refine the query by limiting the result set to just the Title and Author fields.  To do this, we can drag two additional Field objects onto the model and connect them directly to the query object.

Since we are explicitly including the Author field in the result set, we might as well limit the result set to only those items where the Author field is not null.  We can do that easily by replacing the Comparison object with a Logical Join and then adding a Condition to specify the desired relationship.

The following screenshot shows the regenerated code.

 

Although this is a rather trivial example, it’s easy to envision using the tool to construct much more complex queries.  Using the CAML.NET Query Designer significantly reduces the overhead associated with building and maintaining CAML queries, and will hopefully inspire the development of reusable CAML query libraries.  It is also possible to involve a wider range of skillsets in the development process because the diagrams can be easily printed and shared with business analysts and other developers.

There is still a bit of work to be done on the designer.  Some of the remaining features include:

• GroupBy and OrderBy clauses
• Importing fields and site columns directly from SharePoint
• Generating the raw CAML alongside the CAML.NET code

I’m hoping to have a community edition available for download *real soon*.  If I could just figure out how to live without eating and sleeping.  In the meantime, you can see a brief Camtasia demo of the CAML Query Designer in action by clicking here.  

For more information about the CAML.NET Framework and to stay abreast of new developments, visit http://codeplex.com/camldotnet.

As always, your comments and feedback are most welcome.

-JFH