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.
