Feed your CAML some IntelliSense so it doesn’t bite you in the you-know-what!

As every SharePoint developer knows, the CAML is an ornery beast. Get too close – it’ll spit at you, and as soon as you get knee-deep in the hot sands of SharePoint-land, it’s just a matter of time before it bites you in the ***!

But wait! There’s hope for all you CAML-geeks!

Announcing the CAML.NET IntelliSense project

I’ve added a new component to the CAML.NET toolset that aims to help you tame that sometimes finicky, but ever-popular and oh-so-useful CAML language.

Click here to download the CAML.NET.Intellisense installer.

You probably already know how to add the SharePoint schemas to Visual Studio so you get IntelliSense when editing CAML files. If not, here’s a link to a great article by my friend Andrew Connell that walks you through the procedure.

This is a good first step, but we can take it even further by copying the core schema files and then extending them so they provide more information. Specifically, we can add the detailed guidance from the SDK that is scattered all over the Internet and that developers seem to have a hard time finding.

Let’s face it – even with an up to date set of bookmarks, who wants to go searching all over the place for that missing tidbit that tells you just what that obscure attribute is for when you’re right in the middle of building the CAML for your feature? If you’re like me, this quickly becomes a major distraction. Hard enough to stay focused in the first place!

Using Annotated Schemas

The main idea behind the CAML.NET IntelliSense project is to extend the core schemas in two ways:

1. Gather as much information as possible about each element and attribute and place it into xs:annotation elements so that it pops up in context while editing; and
2. Identify and replace as many xs:string types as possible with enumerated types so the valid values for each attribute also popup in context while editing.

For example, using the core WSS schemas directly, we get a drop-down like the following while editing a Field element:

That’s better than nothing, but it doesn’t say what the attribute is for, so unless we’re already familiar with it, we have to refer back to the SDK either online or in the CHM file. On the other hand, using the enhanced annotated WSS schema, we can provide more information in context. We only need to refer to the SDK documentation when we really need it. Most of the time, we just need a hint, which is what Intellisense is all about, right?

Extending the Core Schemas with Enumerated Types

In addition to annotating the schemas with the corresponding SDK documentation for each element, we can go one step further and change the plain vanilla xs:string types to custom enumerated types so we get the list of valid choices for the attribute values. This comes in very handy and also helps to eliminate those nasty little typos that can be really hard to find (and the CAML gets mighty snippy about).

There are lots of places in the SDK documentation where the expected attribute values are listed in the description, but are not enumerated in the schema. This again means that we have to go digging through the documentation to discover what SharePoint expects the attribute values to be. This can be an enormous waste of time – even if you have a pretty good idea of what the values are. Who can keep all that detail in their head?

So, I’ve tried to find and enumerate as many attribute values as I could so they are available at your fingertips when you need them. Each enumeration is also annotated, so you get contextual help for the available values as shown below.

Here’s another example that shows the enumeration of list template types when adding a ListInstance element to a feature. This is a biggie. How many times have you had to hunt down the table of list template type identifiers?

Installing the Enhanced Schemas

The CAML.NET IntelliSense download package includes an MSI installer that copies the extended schemas into the local Visual Studio schema cache, so all you have to do is run the installer and then close and re-open Visual Studio. The current version handles both Visual Studio 2005 and 2008.

Note: If you’re already using the wss.xsd schema from the 12 hive, you should remove the previous catalog file from the Visual Studio schema cache. You may also have to fiddle with your IDE settings a bit because Visual Studio somehow remembers the previous schema settings and adds both the old and the new schemas for files that have already been edited, event after you have removed the old catalog file. This can interfere with the new catalog file you’ve just installed. In the worst case, you will have to choose “don’t use this schema” from the “schemas” dialog for files you have already started editing.

As you can imagine, there are a LOT of elements and attributes to deal with. I’ve made a pretty good start at addressing the most frequently used items, and I’ll continue to add more annotations as my schedule permits. If you find missing or incorrect annotations, please drop me a line or leave a comment and I’ll update the schema.

Now you can ride that CAML high in the saddle and head on out to the SharePoint. You know – the oasis? Right next to the 12 hive! See you there!

“The camel has a single hump,
The dromedary two;
Or else the other way around,
I’m never sure. Are you?”

– Ogden Nash

Stay tuned for CAML.NET 2.0!