U2U CAML Query Builder for SharePoint 2003 and SharePoint 2007 (Windows Version)

Downloads

 For SharePoint 2007 and 2010, install latest version via ClickOnce or msi
For SharePoint 2003, download version 2.1.0.0  

Build and test CAML Queries for SharePoint interactively with the U2U CAML Query Builder.

 CAML (Collaborative Application Markup Language) is an XML-based query language that helps you querying, building and customizing Web sites based on Windows SharePoint Services. The XML elements define various aspects of a WSS site.

The tool will help you build, test and execute your CAML Queries. Detailed documentation is included in this document. This version of the tool only let you build CAML queries for execution against lists.
 We provide you with 3 things:

• A Windows application you can use to connect to your portal or team site and build your CAML query string in a WYSIWYG manner. (CamlBuilder.exe)
• A small assembly you can reference helping you with the execution of your CAML query string within your code using the SharePoint object model. (U2U.SharePoint.CAML.Server.dll)
• A small assembly you can reference helping you with the execution of your CAML query string within your code using the SharePoint web services. (U2U.SharePoint.CAML.Client.dll)

  

Content of this User Guide

 

• What can you expect from this tool?
• A Small Example
• Start the application
• Building a simple query
• Testing your query
• Clearing the query
• Saving your query
• Opening your query
• Building a CAML Query for the SharePoint Object Model
• Building a CAML Query for the SharePoint Lists Web Service
• Using the CAML Query Builder DLLs in your code

  

What can you expect from this tool?

 With this tool you can easily build CAML queries for SPQuery in the SharePoint object model and for querying and updating lists via the SharePoint web serviceLists.asmx. The user interface is very intuitive and is explained on the next pages.

The tool can run on the server where you can build queries for both the SharePoint object model and the SharePoint web services. You can also install the tool on a client but in that case you can only build queries for the SharePoint web services as you won't have access the SharePoint dlls.

From version 4.0.0.0, we have changed the environment, so it is possible to create and work on multiple queries. Queries are opened in separate tabs.

CAML for creating views, list definitions, site definitions are NOT included in this tool.  

A small example

 I will illustrate the use of the U2U CAML Query Builder using a small example of an Employee list that was uploaded using the AdventureWorks MS Access database.  
  

Start the Application

 Double click the CamlBuilder.exe to start the query builder application. You have to fill out the URL to your SharePoint site. You can set the necessary credentials. Choose the mode you want to work in: if you run the application an the server where SharePoint is installed you can opt to build the CAML query with the SharePoint object model. If you have to run the application remotely from another machine or if you want to build a query that should be passed to a method of a SharePoint web service, you can choose to run against the SharePoint Web Services.

Click the Connect button to connect to the SharePoint site.  
  

Building a simple query

 A treeview with the available lists and libraries is displayed at the left side of the application. Select the list for which you want to execute a query. You can then click the Create query button or right-click and select the New Query menu item from the context menu. The query tab is loaded in the right pane, its title is the name of the selected list.   The upper part of the query designer, lets you contruct the where and order by clause. The lower part contains the generated CAML and lets you view the results from your query if you click the Execute query button or hit F5  

Building the where clause

The first combobox in the query designer, is used to coose which kind of where element you want to construct. You can choose a "Filter", which will let you choose a field operator and fill in a filtervalue, or you can choose "And" or "Or", which will expand into 2 new filter controls. The following step through shows you how to build a where clause starting from a simple filter. In the second combobox, you can select a field and the third combobox will let you select an operator. As soon as you select a field a control will appear wich will let you enter a filter value for the expression. As soon as the expression you have created is valid, the corresponding CAML is shown in the editor window.

 If you want to add another expression, you can use the filter combobox to add an expression by selecting "And" or "Or". In our example we will search for all documents which have 'silver' in their Title and were created after the 1st of september. Note that the first expression is preserved, and a new filter expression is added.

 Next, we select the Created field and we can select the date using a datetime picker.
 The Filter combobox can be used to add additional expressions. If we want to extend our query, by searching documents which Title contains 'silver' or 'develop' and were created after the 1st of september, we can use the first filter to select "Or" and add a new expression.
 

Order By

 If you want your list items returned sorted you can define an OrderBy clause. Select a field from the listbox and check the Order By checkbox. Indicate whether you want to sort in ascending order or in descending order. Take a look at the CAML query that is displayed in the bottom part of your screen: an OrderBy node is added.



A the lower panel of the window, you will find the CAML query string written out in full, dynamically changing as you add or remove fields to the sort order or the criteria. As you notice, it is quite a challenge to construct this string without the help of the builder.


  

Testing your query

 The CAML query is displayed in the bottom part of the form. At the right of the query you have aTest button. When you think your query is ready you can test it out. If you choose to work with the SharePoint object model, the query will be executed against anSPQuery object. If you choose to work with the SharePoint web services, the query will be passed to theGetListItems method of the Lists.asmx web service. (You will learn more about this method in the section"Building a CAML Query for the SharePoint Lists Web Service").

The result is shown in a datagrid in the result tab in the bottom part of the form:



You can change the query by hand in the query editor and click the Test button again. The changed query will be executed.

Use the Refresh button to rebuild the original query.

You can copy the query string to the clipboard and paste it in your development environment where you need the query.
  

Clearing your query

 If you messed up your query or you want to try it another way, you can clear your query by clicking theClear button in the upper right corner of the form.
  

Saving your query

 The U2U CAML Query Builder allows you to store the query as a file. Just use theFile | Save File menu item and save it on your file system.



The query is saved in a file with a .caml extension together with necessary information like the url of the SharePoint site, the list name on which the query was build ad what type of query was build.
  

Open your query

 When opening the application afterwards, you can load your settings and continue with your work.