An Honest look at SharePoint Web Services
- by juanlarios
INTRODUCTION
If you are a SharePoint developer you know that there are two basic ways to develop against SharePoint. 1) The object Model 2) Web services.
SharePoint object model has the advantage of being quite rich. Anything you can do through the SharePoint UI as an administrator or end user, you can do through the object model. In fact everything that is done through the UI is done through the object model behind the scenes. The major disadvantage to getting at SharePoint this way is that the code needs to run on the server. This means that all web parts, event receivers, features, etc… all of this is code that is deployed to the server.
The second way to get to SharePoint is through the built in web services. There are many articles on how to manipulate web services, how to authenticate to them and interact with them. The basic idea is that a remote application or process can contact SharePoint through a web service. Lots has been written about how great these web services are. This article is written to document the limitations, some of the issues and frustrations with working with SharePoint built in web services. Ultimately, for the tasks I was given to , SharePoint built in web services did not suffice.
My evaluation of SharePoint built in services was compared against creating my own WCF Services to do what I needed. The current project I'm working on right now involved several "integration points". A remote application, installed on a separate server was to contact SharePoint and perform an task or operation. So I decided to start up Visual Studio and built a DLL and basically have 2 layers of logic. An integration layer and a data layer. A good friend of mine pointed me to SOLID principles and referred me to some videos and tutorials about it. I decided to implement the methodology (although a lot of the principles are common sense and I already incorporated in my coding practices). I was to deliver this dll to the application team and they would simply call the methods exposed by this dll and voila! it would do some task or operation in SharePoint.
SOLUTION
My integration layer implemented an interface that defined some of the basic integration tasks that I was to put together. My data layer was about the same, it implemented an interface with some of the tasks that I was going to develop. This gave me the opportunity to develop different data layers, ultimately different ways to get at SharePoint if I needed to. This is a classic SOLID principle. In this case it proved to be quite helpful because I wrote one data layer completely implementing SharePoint built in Web Services and another implementing my own WCF Service that I wrote. I should mention there is another layer underneath the data layer. In referencing SharePoint or WCF services in my visual studio project I created a class for every web service call. So for example, if I used List.asx. I created a class called "DocumentRetreival" this class would do the grunt work to connect to the correct URL, It would perform the basic operation of contacting the service and so on. If I used a view.asmx, I implemented a class called "ViewRetrieval" with the same idea as the last class but it would now interact with all he operations in view.asmx. This gave my data layer the ability to perform multiple calls without really worrying about some of the grunt work each class performs. This again, is a classic SOLID principle.
So, in order to compare them side by side we can look at both data layers and with is involved in each. Lets take a look at the "Create Project" task or operation. The integration point is described as , "dll is to provide a way to create a project in SharePoint". Projects , in this case are basically document libraries. I am to implement a way in which a remote application can create a document library in SharePoint. Easy enough right? Use the list.asmx Web service in SharePoint. So here we go! Lets take a look at the code.
I added the List.asmx web service reference to my project and this is the class that contacts it:
class DocumentRetrieval
{
private ListsSoapClient _service;
d private bool _impersonation;
public DocumentRetrieval(bool impersonation, string endpt)
{
_service = new ListsSoapClient();
this.SetEndPoint(string.Format("{0}/{1}", endpt, ConfigurationManager.AppSettings["List"]));
_impersonation = impersonation;
if (_impersonation)
{
_service.ClientCredentials.Windows.ClientCredential.Password = ConfigurationManager.AppSettings["password"];
_service.ClientCredentials.Windows.ClientCredential.UserName = ConfigurationManager.AppSettings["username"];
_service.ClientCredentials.Windows.AllowedImpersonationLevel =
System.Security.Principal.TokenImpersonationLevel.Impersonation;
}
private void SetEndPoint(string p)
{
_service.Endpoint.Address = new EndpointAddress(p);
}
/// <summary>
/// Creates a document library with specific name and templateID
/// </summary>
/// <param name="listName">New list name</param>
/// <param name="templateID">Template ID</param>
/// <returns></returns>
public XmlElement CreateLibrary(string listName, int templateID, ref ExceptionContract exContract)
{
XmlDocument sample = new XmlDocument();
XmlElement viewCol = sample.CreateElement("Empty");
try
{
_service.Open();
viewCol = _service.AddList(listName, "", templateID);
}
catch (Exception ex)
{
exContract = new ExceptionContract("DocumentRetrieval/CreateLibrary", ex.GetType(), "Connection Error", ex.StackTrace, ExceptionContract.ExceptionCode.error);
}finally
{
_service.Close();
}
return viewCol;
}
}
There was a lot more in this class (that I am not including) because i was reusing the grunt work and making other operations with LIst.asmx, For example, updating content types, changing or configuring lists or document libraries.
One of the first things I noticed about working with the built in services is that you are really at the mercy of what is available to you. Before creating a document library (Project) I wanted to expose a IsProjectExisting method. This way the integration or data layer could recognize if a library already exists. Well there is no service call or method available to do that check. So this is what I wrote:
public bool DocLibExists(string listName, ref ExceptionContract exContract)
{
try
{
var allLists = _service.GetListCollection();
return allLists.ChildNodes.OfType<XmlElement>().ToList().Exists(x => x.Attributes["Title"].Value ==listName);
}
catch (Exception ex)
{
exContract = new ExceptionContract("DocumentRetrieval/GetList/GetListWSCall", ex.GetType(), "Unable to Retrieve List Collection", ex.StackTrace, ExceptionContract.ExceptionCode.error);
}
return false;
}
This really just gets an XMLElement with all the lists. It was then up to me to sift through the clutter and noise and see if Document library already existed. This took a little bit of getting used to. Now instead of working with code, you are working with XMLElement response format from web service. I wrote a LINQ query to go through and find if the attribute "Title" existed and had a value of the listname then it would return True, if not False. I didn't particularly like working this way. Dealing with XMLElement responses and then having to manipulate it to get at the exact data I was looking for. Once the check for the DocLibExists, was done, I would either create the document library or send back an error indicating the document library already existed.
Now lets examine the code that actually creates the document library. It does what you are really after, it creates a document library. Notice how the template ID is really an integer. Every document library template in SharePoint has an ID associated with it. Document libraries, Image Library, Custom List, Project Tasks, etc… they all he a unique integer associated with it. Well, that's great but the client came back to me and gave me some specifics that each "project" or document library, should have. They specified they had 3 types of projects. Each project would have unique views, about 10 views for each project. Each Project specified unique configurations (auditing, versioning, content types, etc…) So what turned out to be a simple implementation of creating a document library as a repository for a project, turned out to be quite involved.
The first thing I thought of was to create a template for document library. There are other ways you can do this too. Using the web Service call, you could configure views, versioning, even content types, etc… the only catch is, you have to be working quite extensively with CAML. I am not fond of CAML. I can do it and work with it, I just don't like doing it. It is quite touchy and at times it is quite tough to understand where errors were made with CAML statements. Working with Web Services and CAML proved to be quite annoying. The service call would return a generic error message that did not particularly point me to a CAML statement syntax error, or even a CAML error. I was not sure if it was a security , performance or code based issue. It was quite tough to work with. At times it was difficult to work with because of the way SharePoint handles metadata. There are "Names", "Display Name", and "StaticName" fields. It was quite tough to understand at times, which one to use. So it took a lot of trial and error. There are tools that can help with CAML generation. There is also now intellisense for CAML statements in Visual Studio that might help but ultimately I'm not fond of CAML with Web Services.
So I decided on the template. So my plan was to create create a document library, configure it accordingly and then use The Template Builder that comes with the SharePoint SDK. This tool allows you to create site templates, list template etc… It is quite interesting because it does not generate an STP file, it actually generates an xml definition and a feature you can activate and make that template available on a site or site collection. The first issue I experienced with this is that one of the specifications to this template was that the "All Documents" view was to have 2 web parts on it. Well, it turns out that using the template builder , it did not include the web parts as part of the list template definition it generated. It backed up the settings, the views, the content types but not the custom web parts. I still decided to try this even without the web parts on the page. This new template defined a new Document library definition with a unique ID. The problem was that the service call accepts an int but it only has access to the built in library int definitions. Any new ones added or created will not be available to create. So this made it impossible for me to approach the problem this way.
I should also mention that one of the nice features about SharePoint is the ability to create list templates, back them up and then create lists based on that template. It can all be done by end user administrators. These templates are quite unique because they are saved as an STP file and not an xml definition. I also went this route and tried to see if there was another service call where I could create a document library based no given template name. Nope! none.
After some thinking I decide to implement a WCF service to do this creation for me. I was quite certain that the object model would allow me to create document libraries base on a template in which an ID was required and also templates saved as STP files. Now I don't want to bother with posting the code to contact WCF service because it's self explanatory, but I will post the code that I used to create a list with custom template.
public ServiceResult CreateProject(string name, string templateName, string projectId)
{
string siteurl = SPContext.Current.Site.Url;
Guid webguid = SPContext.Current.Web.ID;
using (SPSite site = new SPSite(siteurl))
{
using (SPWeb rootweb = site.RootWeb)
{
SPListTemplateCollection temps = site.GetCustomListTemplates(rootweb);
ProcessWeb(siteurl, webguid, web => Act_CreateProject(web, name, templateName, projectId, temps));
}//SpWeb
}//SPSite
return _globalResult;
}
private void Act_CreateProject(SPWeb targetsite, string name, string templateName, string projectId, SPListTemplateCollection temps) {
var temp = temps.Cast<SPListTemplate>().FirstOrDefault(x => x.Name.Equals(templateName));
if (temp != null)
{
try
{
Guid listGuid = targetsite.Lists.Add(name, "", temp);
SPList newList = targetsite.Lists[listGuid];
_globalResult = new ServiceResult(true, "Success", "Success");
}
catch (Exception ex)
{
_globalResult = new ServiceResult(false, (string.IsNullOrEmpty(ex.Message) ? "None" : ex.Message + " " + templateName), ex.StackTrace.ToString());
}
}
private void ProcessWeb(string siteurl, Guid webguid, Action<SPWeb> action) {
using (SPSite sitecollection = new SPSite(siteurl)) {
using (SPWeb web = sitecollection.AllWebs[webguid]) {
action(web);
}
}
}
This code is actually some of the code I implemented for the service. there was a lot more I did on Project Creation which I will cover in my next blog post. I implemented an ACTION method to process the web. This allowed me to properly dispose the SPWEb and SPSite objects and not rewrite this code over and over again.
So I implemented a WCF service to create projects for me, this allowed me to do a lot more than just create a document library with a template, it now gave me the flexibility to do just about anything the client wanted at project creation. Once this was implemented , the client came back to me and said, "we reference all our projects with ID's in our application. we want SharePoint to do the same". This has been something I have been doing for a little while now but I do hope that SharePoint 2010 can have more of an answer to this and address it properly. I have been adding metadata to SPWebs through property bag. I believe I have blogged about it before. This time it required metadata added to a document library. No problem!!! I also mentioned these web parts that were to go on the "All Documents" View. I took the opportunity to configure them to the appropriate settings. There were two settings that needed to be set on these web parts. One of them was a Project ID configured in the webpart properties. The following code enhances and replaces the "Act_CreateProject " method above:
private void Act_CreateProject(SPWeb targetsite, string name, string templateName, string projectId, SPListTemplateCollection temps) {
var temp = temps.Cast<SPListTemplate>().FirstOrDefault(x => x.Name.Equals(templateName));
if (temp != null)
{
SPLimitedWebPartManager wpmgr = null;
try
{
Guid listGuid = targetsite.Lists.Add(name, "", temp);
SPList newList = targetsite.Lists[listGuid];
SPFolder rootFolder = newList.RootFolder;
rootFolder.Properties.Add(KEY, projectId);
rootFolder.Update();
if (rootFolder.ParentWeb != targetsite)
rootFolder.ParentWeb.Dispose();
if (!templateName.Contains("Natural"))
{
SPView alldocumentsview = newList.Views.Cast<SPView>().FirstOrDefault(x => x.Title.Equals(ALLDOCUMENTS));
SPFile alldocfile = targetsite.GetFile(alldocumentsview.ServerRelativeUrl);
wpmgr = alldocfile.GetLimitedWebPartManager(PersonalizationScope.Shared);
ConfigureWebPart(wpmgr, projectId, CUSTOMWPNAME);
alldocfile.Update();
}
if (newList.ParentWeb != targetsite)
newList.ParentWeb.Dispose();
_globalResult = new ServiceResult(true, "Success", "Success");
}
catch (Exception ex)
{
_globalResult = new ServiceResult(false, (string.IsNullOrEmpty(ex.Message) ? "None" : ex.Message + " " + templateName), ex.StackTrace.ToString());
}
finally
{
if (wpmgr != null)
{
wpmgr.Web.Dispose();
wpmgr.Dispose();
}
}
}
}
private void ConfigureWebPart(SPLimitedWebPartManager mgr, string prjId, string webpartname)
{
var wp = mgr.WebParts.Cast<System.Web.UI.WebControls.WebParts.WebPart>().FirstOrDefault(x => x.DisplayTitle.Equals(webpartname));
if (wp != null)
{
(wp as ListRelationshipWebPart.ListRelationshipWebPart).ProjectID = prjId;
mgr.SaveChanges(wp);
}
}
This Shows you how I was able to set metadata on the document library. It has to be added to the RootFolder of the document library, Unfortunately, the SPList does not have a Property bag that I can add a key\value pair to. It has to be done on the root folder. Now everything in the integration will reference projects by ID's and will not care about names. My, "DocLibExists" will now need to be changed because a web service is not set up to look at property bags. I had to write another method on the Service to do the equivalent but with ID's instead of names. The second thing you will notice about the code is the use of the Webpartmanager. I have seen several examples online, and also read a lot about memory leaks, The above code does not produce memory leaks. The web part manager creates an SPWeb, so just dispose it like I did.
CONCLUSION
This is a long long post so I will stop here for now, I will continue with more comparisons and limitations in my next post. My conclusion for this example is that Web Services will do the trick if you can suffer through CAML and if you are doing some simple operations. For Everything else, there's WCF!
**** fireI apologize for the disorganization of this post, I was on a bus on a 12 hour trip to IOWA while I wrote it, I was half asleep and half awake, hopefully it makes enough sense to someone.
