Getting started with the SharePoint Webservice - Lists Service

http://weblog.vb-tech.com/nick/archive/2006/02/24/1453.aspx
This is the first long article I’m writing based on SharePoint technologies. It’s aimed at reasonable .Net developers who are looking to get started developing around SharePoint technologies. By no means is everything I say in the best approach. If you spot something that should be done another way please do mention it in the comments! SharePoint is such a big application and topic we’re all learning as we go along.

First things first I thought I’d take you through the development environment I’m running under. I’ve got a laptop running Windows XP, which also has VMWare installed. This allows me to run a number of virtual operating systems on top of XP, one of these of course being Windows 2003 Server. On this virtual OS I have Windows SharePoint Services, MS Sql Server, Visual Studio.Net 2003 and Biztalk 2004 installed. Having VS.Net 2003 installed directly on a development Windows 2003 Server make debugging of SharePoint webparts very easy, and will no doubt help us using the SharePoint webservice.

So why would we want to use the SharePoint webservice? All site page data and document data is stored in SQL server and compiled into SharePoint pages/documents upon request. It is not recommended that you tamper with the data directly in SQL server as it’s very easy to break a WSS site altogether very easily. That leaves 2 methods of accessing data from a SharePoint database, the SharePoint object model, or webservice.

A full list of webservice methods for things such as alerts and sites are available in the SharePoint Products and Technologies 2003 SDK. I’ll hopefully cover them all in time, but today we’ll focus on just the list webservice.

You can navigate to the webservice discovery file by typing in :
localhost/sitename/_vti_bin/lists.asmx?wsdl

Here are the methods and their definitions as taken from the SDK:

AddAttachment – Adds an attachment to the specified list item in the specified list.
AddList – Creates a list in the current site based on the specified name, description, and list template ID.
DeleteAttachment – Removes the attachment from the specified list item.
DeleteList – Deletes the specified list.
GetAttachmentCollection – Returns a list of the URLs for attachments to the specified item.
GetList – Returns a schema for the specified list.
GetListAndView – Returns the list and view schemas for the specified list.
GetListCollection – Returns the names and GUIDs for all the lists in the site.
GetListItemChanges – Returns changes made to the list since the specified date and time.
GetListItems – Returns information about items in the list based on the specified query.
UpdateList – Updates a list based on the specified field definitions and list properties.
UpdateListItems – Adds, deletes, or updates the specified items in a list on the current site.

So lets get using this webservice. It’s worth reminding you that I’m using Visual Studio.Net 2003 for this (not VS 2005!). You can add a SharePoint webservice exactly the same way you’d add any other webservice, just right click on the references folder and then ‘Add Web Reference…”. Plant the url to sites webservice you wish to call in the next box, give it a decent name and click ok.

The first webservice method we’ll use is GetList. We can pass in the name of the list as a string as a parameter and it returns an XmlNode with the schema represented in the InnerXml value of the node. The most important piece of information you’ll get is the list guid as you’ll need this do use some of the various other list webservice methods. Here’s our first bit of code:

Site1.Lists listsWS = new SharePointWebservice1.Site1.Lists();
listsWS.Credentials = System.Net.CredentialCache.DefaultCredentials;
XmlNode list = listsWS.GetList(“Contacts”);

MessageBox.Show(listsWS.Attributes[”ID”].Value);

Most sites that are created from templates have a contacts list so I’ve decided to pull that back. If you run the code you’ll get a nice message box pop up with the Guid of the list.
Now we have the guid of the list we can look at doing something a little more useful. Fancy adding a new field to your contacts list? How about a date field called ‘Last Contacted’? You can add new columns to a list with UpdateList. With this single method you can add, ammend, and delete fields by passing in 3 different XmlNodes containing XML fragments to do what you want to the list columns. As we only want to add a new column we can pass null values in for update and delete XmlNodes. Here’s the XmlFragment for creating a new date column:

Many of you will notice that this is Collaborative Application Markup Language (CAML). Something Dot Net developers fear, but really need to get to know if they are to really get to know SharePoint! There’s a lot more information about what fields you can include in the XML in the SharePoint SDK so I won’t go into that now. So we can now go ahead and run this code. Once it’s completed go back to your contacts list on the SharePoint site and you’ll see a field for filling in the ‘Last Contacted’ date for all your contacts.

Site1.Lists listsWS = new SharePointWebservice1.Site1.Lists();
listsWS.Credentials = System.Net.CredentialCache.DefaultCredentials;
XmlNode list = listsWS.GetList(“Contacts”);

XmlDocument doc = new XmlDocument();
XmlNode ndProperties = doc.CreateNode(XmlNode.Element, “List”, “”);
XmlAttribute ndTitleAttrib = (XmlAttribute)doc.CreateNode(XmlNodeType.Attribute, “Title”, “”);
XmlAttribute ndDescription = (XmlAttribute)doc.CreateNode(XmlNodeType.Attribute, “Description”, “”);
XmlNode ndNewFields = doc.CreateNode(XmlNodeType.Element, “Fields”, “”);

string listName = list.Attributes[”ID”].Value;
string listVersion = list.Attributes[”Version”].Value;

ndTitleAttrib.Value = “Contacts”;
ndDescription.Value = “My contacts list”;

ndProperties.Attributes.Append(ndTitleAttrib);
ndProperties.Attributes.Append(ndDescriptionAttrib);

ndNewFields.InnerXml = “<Method ID='1'><Field Type='DateTime' DateOnly='TRUE' Required='TRUE' DisplayName='Last Contacted' FromBaseType='TRUE'/></Method>”;

listsWS.UpdateList(listName, ndProperties, ndNewFields, null, null, listVersion);

The two null values that are passed in are for updateFields and deleteFields. Again for these two fields you need to pass in CAML pretty much the same way as you did for adding fields. Check the SharePoint SDK for values you can pass in to accomplish updates and deletes.

So the final piece of the jigsaw today, and one that could actually be useful, is to be able to actually add new list items to our list using the lists webservice. The method we call for inserting items is the same method used to ammend and delete list items. The Guid of the list is passed in as the first parameter, with the second being an XmlNode. The basics of being able to perform operations on list items is done using CAML again. Below is the code and CAML that I’m going to be running to insert a new item into the contacts lists:

Site1.Lists listsWS = new SharePointWebservice1.Site1.Lists();
listsWS.Credentials = System.Net.CredentialCache.DefaultCredentials;
XmlNode list = listsWS.GetList(“Contacts”);

string listName = list.Attributes[”ID”].Value;
string listVersion = list.Attributes[”Version”].Value;

XmlDocument doc = new XmlDocument();
XmlElement elBatch = doc.CreateElement(“Batch”);
elBatch.SetAttribute(“OnError”, “Continue”);
elBatch.SetAttribute(“ListVersion”, listVersion);

elBatch.InnerXml = “<Method ID='1' Cmd='New'><Field Name='ID'>New</Field><Field Name='ows_LinkTitle'>Swan</Field><Field Name='Title'>Swan</Field></Method>”;

XmlNode rNode = list.UpdateListItems(listName, elBatch);
MessageBox.Show(rNode.InnerText);

I find writing CAML pretty hard and take a kind of trial and error approach. For example, when bringing back a list item all the field names are prepended with ows_ eg ows_title. From putting together this quick sample though I’ve found that title should be just title (not ows_title)! If anybody knows the convention for passing in field names with CAML let me know. I may well update this article with a better explanation! The message box that is displayed at the end of the code should show 0x00000000 if your item has been successfully added to the list, or report the problem if it can’t.

And that draws a close to my first blog post about using SharePoint 2003 Webservices. I’m going to put together some more code to do something a little more useful such as reading contacts from a text file and importing them to SharePoint, I’ll hopefully get that posted within the next day or so. Apart from that watch out next week when I’ll be discussing another SharePoint webservice. All comments and feedback gratefully received on this piece!