Lists Web Service - I

Article
08/03/2006

As with SPS 2003, MOSS ships with some default web services as well. Most of them have been carried over from SPS 2003, whereas there are some that are newly introduced.
The Lists webservice offers some interesting functions to perform remote operations on the lists in a site collection. Some of the web methods that are exposed are:

AddAttachment ( listName As string , listItemID As string , fileName As string , attachment As base64Binary ) As string
AddDiscussionBoardItem ( listName As string , message As base64Binary )
AddList ( listName As string , description As string , templateID As int )
AddListFromFeature ( listName As string , description As string , featureID As guid , templateID As int )
ApplyContentTypeToList ( webUrl As string , contentTypeId As string , listName As string )
CheckInFile ( pageUrl As string , comment As string , CheckinType As string ) As boolean
CheckOutFile ( pageUrl As string , checkoutToLocal As string , lastmodified As string ) As boolean
CreateContentType ( listName As string , displayName As string , parentType As string , fields As , contentTypeProperties As , addToView As string ) As string
DeleteAttachment ( listName As string , listItemID As string , url As string )
DeleteContentType ( listName As string , contentTypeId As string )
DeleteContentTypeXmlDocument ( listName As string , contentTypeId As string , documentUri As string )
DeleteList ( listName As string )
GetAttachmentCollection ( listName As string , listItemID As string )
GetList ( listName As string )
GetListAndView ( listName As string , viewName As string )
GetListCollection ( )
GetListContentType ( listName As string , contentTypeId As string )
GetListContentTypes ( listName As string , contentTypeId As string )
GetListItemChanges ( listName As string , viewFields As , since As string , contains As string )
GetListItemChangesSinceToken ( listName As string , viewName As string , query As , viewFields As , rowLimit As string , queryOptions As , changeToken As string , contains As string )
GetListItems ( listName As string , viewName As string , query As , viewFields As , rowLimit As string , queryOptions As , webID As string )
GetVersionCollection ( strlistID As string , strlistItemID As string , strFieldName As string )
UndoCheckOut ( pageUrl As string ) As boolean
UpdateContentType ( listName As string , contentTypeId As string , contentTypeProperties As , newFields As , updateFields As , deleteFields As , addToView As string )
UpdateContentTypesXmlDocument ( listName As string , newDocument As string )
UpdateContentTypeXmlDocument ( listName As string , contentTypeId As string , newDocument As string )
UpdateList ( listName As string , listProperties As , newFields As , updateFields As , deleteFields As , listVersion As string )
UpdateListItems ( listName As string , updates As string )

Of these the last two might be the ones seeing the most usage. UpdateList and UpdateListItems, both are extremely handy when adding, modifying or deleting columns (in the case of the former) and list items (in the case of the latter). The SDK documents the usage of both but it does seem that there can be quite a few pitfalls while actually implementing these. Here are some examples:
I am using the UpdateListItems here as this is the easiest
Creating the lists web service reference and initializing all data required for making the actual call.

PostLists.Lists lst = new TESTBED.PostLists.Lists();

lst.Credentials = System.Net.CredentialCache.DefaultCredentials;

// Adding a new Item in this case a folder

string
strBatch = "<method id='1' Cmd='New'>" +
                  "<Field Name='ID'>New</Field>" +
                  "<Field Name='FSObjType'>1</Field>" +
                  "<Field Name='BaseName'>testFolder</Field>" +
                  "</Method>";
XmlDocument doc = new XmlDocument();
XmlElement el = doc.CreateElement("Batch");
XmlElement properties = doc.CreateElement("listproperties");
properties.InnerXml = "";
XmlElement newFields = doc.CreateElement("newFields");

XmlElement updateFields = doc.CreateElement("updateFields");
updateFields.InnerXml = "";
XmlElement deleteFields = doc.CreateElement("deleteFields");
deleteFields.InnerXml = "";

el.SetAttribute("OnError", "Continue");
el.SetAttribute("ListVersion", "0");
el.SetAttribute("PreCalc", "TRUE");
el.SetAttribute("ViewName", "{4A163CCB-3CE7-40B1-9EB5-A9568F355E3D}");
el.InnerXml = strBatch;

// the actual call

System.Xml.XmlNode node = lst.UpdateListItems("Documents", el);
MessageBox.Show(node.OuterXml);

Now let's look at the UpdateList webmethod. This is a bit complicated. So if you dont get it right the first time try try till you get it working! Hell no, just kidding.

Setting the environment:

PostLists.Lists lst = new TESTBED.PostLists.Lists();
lst.Credentials = System.Net.CredentialCache.DefaultCredentials;

XmlNode ndList = lst.GetList("ASampleList");
XmlNode ndVersion = ndList.Attributes["Version"];

XmlDocument xmlDoc = new System.Xml.XmlDocument();
XmlNode ndDeleteFields = xmlDoc.CreateNode(XmlNodeType.Element,"Fields", "");
XmlNode ndProperties = xmlDoc.CreateNode(XmlNodeType.Element, "List","");
XmlAttribute ndTitleAttrib = (XmlAttribute)xmlDoc.CreateNode(XmlNodeType.Attribute,"Title", "");
XmlAttribute ndDescriptionAttrib =(XmlAttribute)xmlDoc.CreateNode(XmlNodeType.Attribute,"Description", "");
XmlNode ndNewFields = xmlDoc.CreateNode(XmlNodeType.Element,"Fields", "");
XmlNode ndUpdateFields = xmlDoc.CreateNode(XmlNodeType.Element,"Fields", "");

ndTitleAttrib.Value = "RobinSannerList";
ndDescriptionAttrib.Value = "New_Description";

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

Creating a new field:

ndNewFields.InnerXml = "<Method ID='1'>" +
"<Field Type='DateTime' DateOnly='TRUE' DisplayName='A_New_Test_Field' FromBaseType='TRUE' Required='TRUE' Description='sometextdescription'/>" +
"</Method>";

Making the call:

try
{
           XmlNode ndReturn =
           lst.UpdateList("{18D0E90B-20B9-4931-96EB-5435D08532DC}",
                           ndProperties, ndNewFields, null , null,
                           ndVersion.Value);
           MessageBox.Show(ndReturn.OuterXml);
}

catch (Exception ex)
{
MessageBox.Show("Message:\n" + ex.Message + "\nStackTrace:\n" + ex.StackTrace);

}

Updating the field:

ndUpdateFields.InnerXml = "<Method ID='2'>" +
"<Field Type='DateTime' Name='A_New_Test_Field' DisplayName='SomeNewName'/>" +
"</Method>";

Making the call:

try
{
           XmlNode ndReturn =
           lst.UpdateList("{18D0E90B-20B9-4931-96EB-5435D08532DC}",
                           ndProperties, null, ndUpdateFields, null,
                           ndVersion.Value);
           MessageBox.Show(ndReturn.OuterXml);
}

catch (Exception ex)
{
MessageBox.Show("Message:\n" + ex.Message + "\nStackTrace:\n" + ex.StackTrace);
}

Deleting the Field:

ndDeleteFields.InnerXml = "<Method ID='3'>" +
"<Field Name='SomeNewName'/></Method>";

Making the call:

try
{
           XmlNode ndReturn =
           lst.UpdateList("{18D0E90B-20B9-4931-96EB-5435D08532DC}",
                           ndProperties, null, null, ndDeleteFields,
                           ndVersion.Value);
           MessageBox.Show(ndReturn.OuterXml);
}

catch (Exception ex)
{
MessageBox.Show("Message:\n" + ex.Message + "\nStackTrace:\n" + ex.StackTrace);
}

Of course all is not so rosy while you are doing this and there are some issues that have been trudging along since SPS2003. More on this in the next post.

-Harsh

Comments

Anonymous
August 04, 2006
Here is an assortment of various 2007 Microsoft Office SharePoint Server Documentation / Reference Materials...
Anonymous
August 16, 2006
This is a very useful summary of Sharepoint list webservices.
I am having very much trouble finiding anything useful on these two GetListItemChanges and GetListItemChanges. I am trying to access a list's item history and no one seems to have any idea about how this can be done.
Do you have any suggestion?
Anonymous
August 16, 2006
This is a very useful summary of Sharepoint list webservices.
I am having very much trouble finiding anything useful on these two GetListItemChanges and GetListItemChanges. I am trying to access a list's item history and no one seems to have any idea about how this can be done.
Do you have any suggestion?
Anonymous
August 16, 2006
i think thats a nice topic for another blog entry. Watch this space..i think i will put in something today on that
Anonymous
August 23, 2006
Je viens de passer quelques temps avec les WebServices de SharePoint 2007.
Je voulais découvrir un peu...
Anonymous
January 19, 2007
發現一個好 Blog. 似乎是我們 SharePoint 技術支援的夥伴撰寫的 AddAttachment ( listName As string , listItemID As string , fileName
Anonymous
September 17, 2007
2007 MOSS Resource Links (Microsoft Office SharePoint Server) Here is an assortment of various 2007 Microsoft

Share via

Lists Web Service - I

Comments

Additional resources