Peter Seale's weblog

Friday, June 29, 2007 3:33:13 AM UTC 

UPDATE 2007-07-18: I've posted some instructions revealing how to use the GetListItems method of the lists.asmx web service. Check it out: http://www.pseale.com/blog/BriefestIntroductionToGetListItemsUsingCAMLAndListsasmx.aspx

UPDATE 2007-10-09: I've re-updated this to be gentler and more respectful. Probably not enough, but at least I'm heading in the proper direction. If there's one thing you get out of this, it's that I really, really, really please please would like to have some thorough documentation on CAML (the XML itself). Not necessarily samples or "wisdom"-type articles; instead I'd like just a thorough basis (a solid foundation) upon which we can build.

In Other News

Before I get to the main event, let's divert to something less infuriating. I won't give this away, except to say the page I'm about to link to is the #1 search result on Google for "Oracle DBA redneck". Be enlightened in Redneck philosophy. I think this page speaks better for the man's Oracle skills than any resume or testimonial—because if he doesn't have the skills, then this page guarantees he will never find work again. Clearly the man has confidence.

And Now, CAML

I'll keep this short, so as to narrowly funnel the rage. Let's try to do this factually:

• CAML is an XML query language (Collaborative AML) used to do "a variety of things" in SharePoint. It's not the Caml programming language; this little "bit of trivia" becomes a little less…trivial…when you're searching for documentation.
   
• Which brings me to Point Number Two. Despite what you may have heard, there is no documentation on CAML. Sure, they've auto-generated some skeleton pages on MSDN, and added a bare minimum of exposition. So if you go visit the links, you'll see the form (if not the content): Headers, Subheaders, sparse text, and ooh, code samples! There's probably thousands of MSDN pages on CAML. Now look closely. What do you see? Do the code samples actually help? Are they really code samples, or are they the same function declaration in 7 language descriptions, including JScript and J#? Let's bring this back: Point Number Two:  Worthless documentation is, in the long run, worse than no documentation at all. You don't waste time reading if it's not there to read!
   
• Where are the CAML tools? U2U has a free CAML query-building GUI tool that works pretty much as you imagine—it loads your list metadata, you select your columns and your query type, you click the magic button, and…it actually spits out valid CAML! Except that (in my case) you have to split up the three emitted XML chunks, then reconstitute them with three other (thankfully non-XML (but one is a GUID, and you'll have to dig at another web service to find out what the GUID is…)) parameters. So easy! Incidentally there's another in-browser Query Builder deployed such that it appears on your List Actions menu.
   
• Lastly: Where's the outrage? I don't see enough people complaining about this, so I think a lot of people don't even see the pain to begin with.
   

I'd like to end on a positive note, but can't, so we'll have to settle for:

Action Items - Help Me Cope With the CAML Ecosystem in its Current State

• I will avoid CAML at all costs, only dipping in if absolutely necessary (underway).
• I will check around to see if I've missed something big, e.g. some actual documentation. It's entirely possible.
• I will search for more tools.

MSDN Rage Meter

This is what I like to call a "usefulness heat map". Or if you like to think in negative (or video game) terms, a visual Rage Meter. White indicates useful content; Red indicates filler.

This is how most of MSDN looks through the lens of my metaphorical Rage Meter. All, form does not equal content!