Talk to SharePoint through its web services

A summary of the SharePoint Portal Server web services

SharePoint Portal Server provides the same web services as Windows SharePoint Services. It also provides the following five additional web services.

WSS Web Services	Description
Area Service	Areas are sections used in SharePoint Portal Server to group content. This web service allows to manage areas. You can create new areas, update areas, remove areas, get the list of sub-areas, etc.
Query Service	The Query web service is used by clients to search SharePoint. You can send in complex search XML requests and get a result-set of matches.
User Profile Service	Users in SPS have user profiles that are used to target content to audiences (users). This web service allows to obtain user profile information. It does not allow to create or modify user profiles.
SPS Crawl Service	This web service is undocumented and is used by SharePoint itself for site crawling purposes.
Outlook Adapter Service	Provides the same capabilities as the Alerts web service of WSS.

The table below shows the URLs to use for each web service provided by SharePoint Portal Server. You can add them the same way as the WSS web services described above.

WSS Web Services	Web Reference
Area Service	http:///_vti_bin/areaservice.asmx>
Query Service	http:///_vti_bin/search.asmx>
User Profile Service	http:// /_vti_bin/userprofileservice.asmx
SPS Crawl Service	http:///_vti_bin/spscrawl.asmx>
Outlook Adapter Service	http:// /_vti_bin/outlookadapter.asmxd>

Namespaces used in the returned SharePoint XML documents

Many of the web methods return its result in form of an XML document. Most root nodes have a namespace URI associated with it. Here is an example XML document returned by the GetListCollection() web method (on the Lists web service). Please note that this is just a partial XML snippet for demonstration purpose:

Naturally we would think of running an XPath query like "//List" using the SelectNodes() method on the XmlDocument or XmlNode object. We expect it to return all the List nodes of this XML document. But the result returned is empty. The reason being that you need to query within the namespace associated with the root node. But how do you do that if there is no namespace qualifier (or prefix) associated with the namespace URI. We need to use the XmlNamespaceManager class to associate a namespace prefix to the namespace URI. Here is the code snippet:

private XmlNodeList RunXPathQuery(XmlNode XmlNodeToQuery, string XPathQuery) {
// load the complete XML node and all its child nodes into a XML document XmlDocument Document = new XmlDocument();
Document.LoadXml(XmlNodeToQuery.OuterXml);
// all the possible namespaces used by SharePoint and a randomly choosen prefix
const string SharePointNamespacePrefix = "sp";
const string SharePointNamespaceURI = http://schemas.microsoft.com/sharepoint/soap/";
const string ListItemsNamespacePrefix = "z";
const string ListItemsNamespaceURI = "#RowsetSchema";
const string PictureLibrariesNamespacePrefix = "y";
const string PictureLibrariesNamespaceURI = http://schemas.microsoft.com/sharepoint/soap/ois/";
const string WebPartsNamespacePrefix = "w";
const string WebPartsNamespaceURI = http://schemas.microsoft.com/WebPart/v2;
const string DirectoryNamespacePrefix = "d";
const string DirectoryNamespaceURI = http://schemas.microsoft.com/sharepoint/soap/directory/;
// now associate with the xmlns namespaces (part of all XML nodes returned
// from SharePoint) a namespace prefix which we can then use in the queries
XmlNamespaceManager NamespaceMngr = new XmlNamespaceManager(Document.NameTable); NamespaceMngr.AddNamespace(SharePointNamespacePrefix, SharePointNamespaceURI); NamespaceMngr.AddNamespace(ListItemsNamespacePrefix, ListItemsNamespaceURI); NamespaceMngr.AddNamespace(PictureLibrariesNamespacePrefix, PictureLibrariesNamespaceURI); NamespaceMngr.AddNamespace(WebPartsNamespacePrefix, WebPartsNamespaceURI); NamespaceMngr.AddNamespace(DirectoryNamespacePrefix, DirectoryNamespaceURI);
// run the XPath query and return the result nodes
return Document.SelectNodes(XPathQuery, NamespaceMngr);
}

First we create a new XmlDocument object and load the XML string of the passed along XmlNode into it. This way we can manipulate the XML document as needed without affecting the original XmlNode object itself. Then we create an XmlNamespaceManger object and assign it to the XmlDocument object. This we do by passing along the NameTable property of the XmlDocument. Next we add all the namespace URI's with its namespace prefixes. There are five different namespaces you will run into frequently (see declared constants). Finally we run the XPath query and return the collection of matching XML nodes. The namespace shown in our sample XML snippet gets the "sp" namespace prefix associated so our XPath query would change to "//sp:List". This will now return all matching XML nodes.

Some real life examples of using the SharePoint web services

The following examples demonstrate how you can leverage the SharePoint web services to interact tightly with SharePoint from within your application. The detailed code for each example can be found in the attached "SharePoint explorer" sample application. The description below explains which web service and web method to use to obtain the desired SharePoint information.

Example 1 - Get the collection of SharePoint lists, fields and views

In the first example we want to get the collection of SharePoint lists. For each list we want to get all the defined list fields (fields you can use to store information) and finally all views associated with the list. Here are the web methods to call:

• On the Lists web service call the GetListCollection() web method to get the collection of all SharePoint lists. This returns an XML document with all SharePoint lists.
• Next you run the "//sp:List" XPath query to get all matching List nodes. The Title attribute of each matching node contains the name of the SharePoint list.
• For each SharePoint list we call the GetList() web method on the Lists web service, passing along the list name. This returns a XML document with detailed information about the list including the list of fields.
• Next you run the "//sp:Field" XPath query to get all the matching Field nodes. The Name attribute contains the field name.
• For each SharePoint list we call the GetViewCollction() web method on the Views web service, passing along again the list name. This returns a XML document listing all views for the list.
• Finally you run the "//sp:View" XPath query to get all the matching View nodes. The Name attribute contains the name of the view.

Example 2 - Get the list of users and site-groups

In this example we want to get the list of site users and to which site group each user belongs. We also want to get the list of site groups and which users belong to each site group.

• On the Users-and-Groups web service we call the GetUserCollectionFromWeb() web method. This returns an XML document with all the site users.
• Next you run the "//d:User" XPath query to get all the matching User nodes. The Name attribute contains the user name and the LoginName attribute the user's login name.
• For each user we call the GetRoleCollectionFromUser() web method on the Users-and-Groups web service passing along the user's login name. This returns a XML document with all the site groups the user belongs to.
• Next you run the "//d:Role" XPath query to get all the matching Role nodes. The Name attribute contains the site group name.
• To get the list of site groups call the GetRoleCollectionFromWeb() web method on the Users-and-Groups web service. This returns an XML document with all site groups.
• Next you run again the "//d:Role" XPath query to get all the matching Role nodes. The Name attribute contains the site group name.
• Finally call for each site group the GetUserCollectionFromRole() web method on the Users-and-Groups web service passing along the site group name. This returns an XML document with all the users belonging to this site group.
• Next you run again the "//d:User" XPath query to get all the matching User nodes. The Name attribute contains the user name and the LoginName attribute the user's login name.

Example 3 - Get the list of sites, site-templates and list-templates

With the last example we want to get a list of all sites in the site collection. We want to get for the site collection the list of site templates. Additionally we want for each site the list of list templates.

• First we call the GetAllSubWebCollection() web method on the Webs web service. This returns an XML document with all sites in the site collection.
• Next run the "//sp:Web" XPath query to return all matching Web nodes. The Url attribute contains the absolute URL for the site.
• Then we call the GetSiteTemplates() web method on the Sites web service. This returns an array of available site templates in the site collection, which is an array of the type Sites.Templates. The attached sample application converts all structures to an XML document using reflection, so you can run XPath queries against it (see the method SharePoint.SitesGetSiteTemplates()).
• Next run the "//SharePointServices.Sites.Templates" XPath query which returns all matching template nodes. The Title attribute contains the template title and the Name attribute the SharePoint template name.
• For each site we call the GetListTemplates() web method on the Webs web service. Before calling the web service object you need to set the URL to the site URL (returned by GetAllSubWebCollection()). This way we make sure that t he call is to the site itself and returns the list templates of that site. This returns an XML document with all list templates.
• To finish run the "//sp:SiteTemplate" XPath query to return all matching SiteTemplate nodes. The DisplayName attribute contains the name of the list template.

Summary

SharePoint comes with a vast number of web services and web methods which enable you to tightly integrate SharePoint capabilities into your application. It is very easy to learn and use these web services and web methods. Please refer to the attached "SharePoint web service browser" example which provides a complete wrapper class for all existing (about 150) web methods. This removes the burden of adding all the web references and worrying about the details how to instantiate each web method, etc. The sample application provides a user interface to explore all web methods. You can browse the web services and web methods, display the SDK help page, enter the input values, execute the web method and look at the displayed output values.

The second example - "SharePoint explorer" provides a much more comprehensive sample of how to use and work with the SharePoint web services and web methods. It retrieves as much information and displays the data in lists and tree nodes (always running simple XPath queries against the result-set). The user interface allows you to traverse through the related data. You can also write your own web services using the managed SharePoint server API. Here is a sample application which provides a document check-in and check-out capability through a new web service.