Talk to SharePoint Through Its Web Services

Cnbaby

Rating: none

Klaus Salchner (view profile) December 22, 2004

　　　　
　　

Introduction
　　Microsoft Office 2003 is very tightly integrated with SharePoint by utilizing its Web services. Windows SharePoint Services comes with sixteen different Qeb services. SharePoint Portal Server 2003 supports an additional five Web services. The Web services provided by SharePoint do provide a vast array of features, but not all SharePoint features are accessible through them. If required, you can build your own Web service on top of SharePoint, thus leveraging the managed SharePoint server API itself. The Web service interfaces make it very easy to integrate SharePoint capabilities right into your application.
　　

　　This article is not a detailed documentation of every Web method and Web service provided by SharePoint. It is rather an introduction to its capabilities and how to use them. You can download the Windows SharePoint Services SKD or the SharePoint Portal Server SKD for a complete reference of all Web services and also of the server API itself. Please refer to this article for a guide of how to install and administrate SharePoint or this article for a guide of how to use and customize SharePoint portals.

How to Add a Windows SharePoint Web Service Reference
　　You can add a Web reference to each SharePoint Web service through your Visual Studio .NET IDE. In your Solution Explorer, right-click on your project and select "Add Web Reference" from your popup menu. The table below shows the URLs to use for each Web service provided by WSS. Enter the URL to the Web service and click the Go button. This will show you a summary of all available Web methods in the dialog box. Next, enter the name of the Web reference and then click Add Reference.

WSS Web Services	Web Reference
Administration Service	http://<server-url:port-number>/_vti_adm/admin.asmx
Alerts Service	http://<server-url>/_vti_bin/alerts.asmx
Document Workspace Service	http://<server-url>/_vti_bin/dws.asmx
Forms Service	http://<server-url>/_vti_bin/forms.asmx
Imaging Service	http://<server-url>/_vti_bin/imaging.asmx
List Data Retrieval Service	http://<server-url>/_vti_bin/dspsts.asmx
Lists Service	http://<server-url>/_vti_bin/lists.asmx
Meetings Service	http://<server-url>/_vti_bin/meetings.asmx
Permissions Service	http://<server-url>/_vti_bin/permissions.asmx
Site Data Service	http://<server-url>/_vti_bin/sitedata.asmx
Site Service	http://<server-url>/_vti_bin/sites.asmx
Users and Groups Service	http://<server-url>/_vti_bin/usergroup.asmx
Versions Service	http://<server-url>/_vti_bin/versions.asmx
Views Service	http://<server-url>/_vti_bin/views.asmx
Web Part Pages Service	http://<server-url>/_vti_bin/webpartpages.asmx
Webs Service	http://<server-url>/_vti_bin/webs.asmx

Setting the Web Service User Credentials
　　The SharePoint Web services only accept calls from existing SharePoint users and do also enforce access security. Import the System.Net namespace into your project and then use the NetworkCredential class to set the user credential to use for the Web service call. Here is a code snippet:

public static XmlNode VersionsGetVersions(string SharePointHost,
string UserName,
string Password,
string Domain,
string FileName)
{
// proxy object to call the Versions Web service
Versions.Versions VersionsService = new Versions.Versions();
// the user credentials to use
VersionsService.Credentials = new NetworkCredential(UserName,
Password,
Domain);
VersionsService.Url = SharePointHost + "_vti_bin/Versions.asmx";
// gets the file versions
XmlNode Result = VersionsService.GetVersions(FileName);
// dispose the Web service object
VersionsService.Dispose();
return Result;
}

　　For example, first you create an instance of the Versions Web service. Then, you assign a new instance of the NetworkCredential class to the Credentials property on the created Web service object. You pass along the user name, password, and the user's domain name to the NetworkCredential object. Next, you set the Web service URL, which might very well be different from the one used when you created the Web reference. Finally, you invoke the desired Web method, in the code snippet above the GetVersions() Web method. The Web method takes a file name and returns an XML document with all available versions of this file. (Document libraries can have versioning enabled and then keep a history for each version.) At the end, you call Dispose() on the Web service object to free up any underlying unmanaged resources.
　　If the user does not exist in SharePoint or does not have the permission to perform the operation, a WebException is thrown by SharePoint. The returned HTTP status is 401, which means unauthorized request. There are some inconsistencies across all Web services. For example, some Web methods take an XML string as input while others take an XmlNode as input. Most Web methods return the result as XmlNode whereas others return an XML string and while others again return complex data structures. But, after you get used to these inconsistencies, it is very easy to use these Web services and integrate SharePoint capabilities right into your application.

A Summary of the "Windows SharePoint Services" Web Services
　　The following table provides an overview what capabilities are exposed through the "Windows SharePoint Services" Web services. Each Web service is targeted towards a specific area although there is some overlap. You, for example, can use the Lists Web service and the Site Data Web service to work with SharePoint lists, or you can use the Site Data Web service and the Webs Web service to work with sites meta-data and sub-sites. Please refer to the attached "SharePoint web service browser" sample application, which provides a windows form interface to browse all Web services and all its Web methods. It enables you to play with each Web method or Web service and better understand its usage. It also displays the detailed SDK help page to each Web service and Web method.

WSS Web Services	Description
Administration Service	This Web service provides administrative capabilities like creating a new top-level site, deleting a top-level site and getting the list of available languages.
Alerts Service	Provides access to the list of active alerts and allows to delete active alerts.
Document Workspace Service	This Web service is used to manage Document Workspace sites. It allows you to create new document workspaces, delete document workspaces, create new sub-folders, delete sub-folders, and so forth.
Forms Service	Each list has forms associated which are used to display list items, create new list items, and update or delete existing list items. This Web service allows to get the collection of forms associated with a list and then get detailed information about each form.
Imaging Service	SharePoint has picture libraries that users can use to manage pictures. This Web service allows to upload pictures, download pictures, create new folders, delete folders and pictures, and the like.
List Data Retrieval Service	Allows you to run XPath like queries against a list.
Lists Service	This Web service is used to work with lists and list data. You can obtain the collection of lists, add new lists, remove lists, add new list attachments, remove attachments, and so on.
Meetings Service	This Web service is used to work with Meeting Workspaces. You can create a new Meeting workspace, remove an existing Meeting workspace, add new meetings, add new meetings using ICal files, and so forth.
Permissions Service	Sites and lists have permissions assigned to them. This Web service is used to obtain the permissions assigned to a list or site, add new permissions, and update or removing existing permissions.
Site Data Service	The Site Data Web service can be used to return meta-data about a site or list, get the collection of lists, get the attachments for a list item, get the collection of items in a list, and so on.
Site Service	This Web service can be used to return the list of site templates. When you create a new site using the Administration Web service you need to specify the site template name to use that you can obtain through this Web service.
Users and Groups Service	This Web service is used to work with users, site-groups and cross-site groups. You can add, update or remove users, site-groups, and cross-site groups. You can also add users or cross-site-groups to a site-group.
Versions Service	Document Libraries and Picture Libraries can have versioning enabled, which stores a copy of every single file version. This Web service can be used to get the list of available versions, delete versions, and also restore a file version.
Views Service	Lists have views associated that define what fields are shown, what filtering and sorting is applied, what grouping is applied, and so on. This Web service is used to work with list views. You can get the collection of views, add new views, remove views, update the Html code used to display a view, and the like.
Web Part Pages Service	Web Parts are objects that you can place on Web part pages. This Web service is used to work with Web parts and Web part pages. You can get the list of Web parts on a page, you can add or remove Web parts, and so forth.
Webs Service	This Web service is used to work with sites and sub-sites. You can get the list of list-templates, get meta-data about a sub-site, get the list of sub-sites, and so on.

　　

　　

　　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 you to manage areas. You can create new areas, update areas, remove areas, get the list of sub-areas, and so forth.
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 you to obtain user profile information. It does not allow you 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 following table 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://<server-url>/_vti_bin/areaservice.asmx
Query Service	http://<server-url>/_vti_bin/search.asmx
User Profile Service	http://<server-url>/_vti_bin/userprofileservice.asmx
SPS Crawl Service	http://<server-url>/_vti_bin/spscrawl.asmx
Outlook Adapter Service	http://<server-url>/_vti_bin/outlookadapter.asmx

Namespaces Used in the Returned SharePoint XML Documents
　　Many of the Web methods return their results in the form of an XML document. Most root nodes have a namespace URI associated with them. 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 purposes:

<Lists xmlns="http://schemas.microsoft.com/sharepoint/soap/">
<List ID="{789AEDFE-597E-476D-8F11-9C1F8203CCDF}"
Title="Announcements"/>
</Lists>

　　Naturally, one would think of running an XPath query such as "//List" by using the SelectNodes() method on the XmlDocument or XmlNode object. You expect it to return all the List nodes of this XML document. But, the result returned is empty. The reason for this is 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? You 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 an
// 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 that
// we then can 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, you create a new XmlDocument object and load the XML string of the passed along XmlNode into it. This way, you can manipulate the XML document as needed without affecting the original XmlNode object itself. Then, you create an XmlNamespaceManger object and assign it to the XmlDocument object. You do this by passing along the NameTable property of the XmlDocument. Next, you add all the namespace URIs with their namespace prefixes. There are five different namespaces you will run into frequently (see declared constants). Finally, you run the XPath query and return the collection of matching XML nodes. The namespace shown in your sample XML snippet gets the "sp" namespace prefix associated so that your 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, you want to get the collection of SharePoint lists. For each list, you 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, you call the GetList() Web method on the Lists Web service, passing along the list name. This returns an 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, you call the GetViewCollction() Web method on the Views web service, passing along the list name again. This returns an 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, you want to get the list of site users and to which site group each user belongs. You also want to get the list of site groups and which users belong to each site group.

• On the Users-and-Groups Web service, you 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, you call the GetRoleCollectionFromUser() Web method on the Users-and-Groups Web service, passing along the user's login name. This returns an 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 again run the "//d:Role" XPath query to get all the matching Role nodes. The Name attribute contains the site group name.
  
• Finally, call the GetUserCollectionFromRole() Web method on the Users-and-Groups Web service for each site group, passing along the site group name. This returns an XML document with all the users belonging to this site group.
  
• Next, you again 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.
  

Example 3—Get the list of sites, site-templates, and list-templates
　　With the last example, you want to get a list of all sites in the site collection. You want to get the list of site templates for the site collection. Additionally, you want the list of list templates for each site.

• First, you 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, you 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; it returns all matching template nodes. The Title attribute contains the template title and the Name attribute the SharePoint template name.
  
• For each site, you 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, you make sure that the 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 that 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 that 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, and so on. 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 also can write your own Web services by using the managed SharePoint server API. Here is a sample application that provides a document check-in and check-out capability through a new Web service. If you have comments on this article or this topic, please contact me @ klaus_salchner@hotmail.com. I want to hear if you learned something new. Contact me if you have questions about this topic or article.

About the Author
　　Klaus Salchner has worked for 14 years in the industry, nine years in Europe and another five years in North America. As a Senior Enterprise Architect with solid experience in enterprise software development, Klaus spends considerable time on performance, scalability, availability, maintainability, globalization/localization, and security. The projects he has been involved in are used by more than a million users in 50 countries on three continents.
　　Klaus calls Vancouver, British Columbia his home at the moment. His next big goal is running the New York marathon in 2005. Klaus is interested in guest speaking opportunities or as an author for .NET magazines or Web sites. He can be contacted at klaus_salchner@hotmail.com or http://www.enterprise-minds.com.
　　Enterprise application architecture and design consulting services are available. If you want to hear more about it, contact me! Involve me in your projects and I will make a difference for you. Contact me if you have an idea for an article or research project. Also contact me if you want to co-author an article or join future research projects!
　　
　　Downloads


SharePointClient2005.zip - SharePoint web service browser

SharePointDemo2005.zip - SharePoint explorer