Walkthrough: Quick Start with SharePoint Web Services
Introduction
Integrating external applications with SharePoint data and functionality is pretty easy, but the documentation is scattered, so I thought it might be helpful to provide a complete solution that covers a few main scenarios.
I’ve used the SharePoint web services to provide a custom search interface and to populate lookup tables. I’ve also seen it used as a workaround in a few scenarios where the SharePoint Object Model was behaving erratically.
This post will focus on how to quickly get started with the web services interface in WSS, and particularly how to access SharePoint data and search results quickly, in a new project. It’s not very polished, but it gets the job done.
Does this apply to me?
First, when communicating with WSS and MOSS, you have to decide which remote access tool best fits your needs.
- The SharePoint Object Model (i.e. from the WSS SDK) is great when your application is written in .NET and is deployed to a server running MOSS or WSS,
- RPC over HTTP is apparently good for large file uploads,
- WebDAV allows for browsing via Windows Explorer and drive mapping, and
- The web services interface is best when you need a connection that doesn’t depend on the WSS/MOSS SDK, when you need to connect from outside .NET code (such as via JavaScript).
As Alvin Bruney points out in his book Programming Excel Services (Safari), the web services interface is also “a way to access the resources of the server with reduced risk of instability to the server resources.”
Secondly, figure out if you need to do this from scratch at all.
Check into LINQ to SharePoint, which can use either the SharePoint Object model or the web services interface. It looks like a really slick and robust way to interface with your existing SharePoint data. On the down side, it appears to not have been updated since November 2007 and Bart De Smet, the project’s author (blog), notes that it is an alpha release and not ready for production. I’ve steered clear of it for that reason and due to client restrictions, but you might save yourself a lot of time if you can use it!
Check out this video, from the project’s CodePlex page, for a good quick start:
LINQ to SharePoint quick start video (5:37, 3.18MB, WMV)
If you decide against LINQ to SharePoint, you can still easily add web references and consume the SharePoint web services in your custom code.
Walkthrough: Accessing List data
As it turns out, the web host for Hands on DC (a volunteer organization with which I work) does some hokey things with NTLM authentication that aren’t supported by WCF. Namely, it seems like they’re doing Transport level authentication over plaintext HTTP instead of HTTP over SSL. I can see why this isn’t supported, for security reasons. Despite Dan Rigby’s excellent post about impersonation in WCF, I couldn’t get anything to work.
But alas, with no slight of hand whatsoever, the scenario works in VS2005 and a regular old-school ASMX-based web service proxy (web reference). Here’s a quick (and quite dirty) example, initially based on Ishai Sagi’s (blog) response on MSDN:
Video hint: Click the full screen icon (looks like a TV)
Download source code (39KB, ZIP file)
The query that we send to the list service is written in CAML. When we want to get more complex in our query, such as only pulling back certain columns, check out the U2U CAML Query Builder. It provides an awesome interface into creating your CAML queries.
In the WCF world, Kirk Evans has an awesome walkthrough, Calling SharePoint Lists Web Service using WCF, which includes how to streamline the XML access by using an XPathNavigator, and later using a DataTable that reads from an XmlNodeReader. Better than querying the fields directly for sure!
Walkthrough: Querying WSS Search Results
Search is a little more challenging. As is the case with every other web service, we send the query service XML, and it returns XML. We can take a shortcut and generate the request XML with a tool such as the Search Query Web Service Test Tool for MOSS (or we could also import the schema and generate a C# class from it).
Since I’m a big fan of using XSD.EXE to generate a C# class, I chose to do so with the search result support classes. It was mostly productive, although the Results node is free-form (can take any node type) and the generator doesn’t seem to support that. In the end, we can use the generated classes to get statistics about the data set, and can navigate the Documents using regular XML methods.
Here is a complete walkthrough of adding very basic search results, including a total result count and the first page of results, to our application:
Video hint: Click the full screen icon (looks like a TV)
Download source code (56KB, ZIP file)
Conclusion
Use SharePoint web services when you have the need to separate concerns and reduce risk inherent with new code deployments to the SharePoint farm, you want remote access to SharePoint from a non-SharePoint server, or you need to access SharePoint from something other than .NET (such as JavaScript).
This post and associated videos walked you through creating a Windows Forms application, from scratch, that pulls data in from SharePoint, including List-based data and search results. The process is similar to any other web service, but there are a few gotchas and pain points that I hope have been cleared up in this resource.
I collected some additional links in the process of putting this post together, and added them on delicious with the tag “sharepoint-webservices”.