Introduction
Microsoft Windows SharePoint Services 3.0 provides tools for collaboration that help people stay connected across organizational and geographic boundaries. Windows SharePoint Services gives people access to information they need. Built on Microsoft Windows Server 2003, Windows SharePoint Services also provide a foundation platform for building Web-based business applications that can flex and scale easily to meet the changing and growing needs of your business.
There are occasions when the project teams will have to communicate with the SharePoint services programmatically. There are multiple approaches to communicate to the Sharepoint programmatically.
- Through Sharepoint web services exposed by the Sharepoint sites
- Through the SharePoint object model
- Exposing SharePoint object model through custom web service
The following article will try to cover the approaches with pros and cons of the same.
Windows SharePoint Services Web Service
The Windows SharePoint Services Web Service provides methods that can be used to work remotely with a deployment of Microsoft Windows SharePoint Services. Sharepoint services expose a set of web services which can be consumed by the client application to access sites and document libraries. The following diagram represents the high level communication diagram.
The following table provides the services exposed by WSS and the high level description of the usage of the same.
|
Service
|
Description
|
|
Administration
|
Provides methods for managing a deployment of Windows SharePoint Services, such as for creating or deleting sites.
|
|
Alerts
|
Provides methods for working with alerts for list items in a SharePoint site.
|
|
Document Workspace
|
Exposes the Document Workspace Web service and its eleven methods for managing Document Workspace sites and the data they contain.
|
|
Forms
|
Provides methods for returning forms used in the user interface when working with the contents of a list.
|
|
Imaging
|
Provides methods that enable you to create and manage picture libraries.
|
|
List Data Retrieval
|
Provides a method for performing queries against lists in Microsoft Windows SharePoint Services.
|
|
Lists
|
Provides methods for working with lists and list data.
|
|
Meetings
|
Provides methods that enable you to create and manage Meeting Workspace sites.
|
|
Permissions
|
Provides methods for working with the permissions for a site or list.
|
|
Site Data
|
Provides methods that return metadata or list data from sites or lists in Microsoft Windows SharePoint Services.
|
|
Sites
|
Provides a method for returning information about the site templates for a site collection.
|
|
Users and Groups
|
Provides methods for working with users, site groups, and cross-site groups.
|
|
Versions
|
Provides methods for working with file versions.
|
|
Views
|
Provides methods for working with views of lists.
|
|
Web Part Pages
|
Provides the methods to send information to and retrieve information from XML Web services.
|
|
Webs
|
|
Refer to the following link for details of the services and the methods exposed.
How To
The following section provides how to get the list of document libraries available under a SharePoint site using a .NET client. The concept will be similar when trying to communicate to the WSS web services using other programming language like Java. The client will have to create the proxy object using the WSDL exposed by the web service and then make a call the Web service to consume the web methods exposed by the web service.
We will assume we have a site called MySite which can be accessed through the following URL:
All web services will be in the path:
Step 1: Add Web Reference to WSS Web Service
List web service (http://servername:34635/sites/MySite/_vti_bin/Lists.asmx) exposes the necessary web methods to query available document libraries in the site.
Add a web reference to the web site by clicking “Add web reference” in the project explorer:
Step 2: Calling Web Service in the Code
GetListCollection() method of the List service is used to get the list of document libraries available in the site. In order to call this method, first the developer has to create the instance of the proxy object, which in turn will call the web method exposed by the WSS.
List.Lists ListsWebService = new List.Lists();
ListsWebService.Credentials = new NetworkCredential("username", "password", "domain"); ;
ListsWebService.Url = "http://servername:34635/sites/MySite/_vti_bin/Lists.asmx";
try
{
var getListXMLNode = ListsWebService.GetListCollection();
XElement getListXElement = XElement.Parse(getListXMLNode.OuterXml.ToString());
var ListCollection = getListXElement.Elements().Select(e => new
ListCollection
{
DocTemplateUrl = e.Attribute("DocTemplateUrl").Value.ToString(),
DefaultViewUrl = e.Attribute("DefaultViewUrl").Value.ToString(),
Title = e.Attribute("Title").Value.ToString(),
Description = e.Attribute("Description").Value.ToString(),
BaseType = Convert.ToInt32(e.Attribute("BaseType").Value.ToString()),
ServerTemplate = Convert.ToInt32(e.Attribute("ServerTemplate").Value.ToString())
});
if (serverTemplate > 0)
{
ListCollection = ListCollection.Where(l => l.ServerTemplate == serverTemplate);
}
return ListCollection.ToList();
}
The data fetched will be in an XML format, will have all the lists present in the site. This needs to be further processed to get the list of document libraries available in the site. Fully functional code is given at the end of this article.
SharePoint Object Model
Windows SharePoint Services offers a highly structured server-side object model that makes it easy to access objects that represent the various aspects of a SharePoint Web site. From higher-level objects, you can drill down through the object hierarchy to obtain the object that contains the members you need to use in your code. If the code is going to be executed on the same machine as WSS, the Sharepoint object model can be used. To work with the Sharepoint object model, the developer will have to refer to the Microsoft.SharePoint.dll located in the following directory:
C:\program files\common files\microsoft shared\web server extensions\12\isapi
Refer to the following link for details on the server architecture and object model hierarchy:
How To
The following section provides how to get the list of document libraries available under a SharePoint site using Sharepoint object model.
Step 1: Add Reference to Microsoft.SharePoint.dll
Add reference to the SharePoint library from the following location in the machine where the WSS is installed.
C:\program files\common files\microsoft shared\web server extensions\12\isapi
Note: The developers can copy the Microsoft.SharePoint.dll to their system and do the development. But, the code can only be executed on a machine where the WSS or SharePoint is installed.
Step 2: Coding in Object Model
Microsoft.Sharepoint.dll exposes multiple classes and methods which can be used to query and manipulate the share point collection/sites and lists. The following code gets the lists of type document library.
using (SPSite siteCollection = new SPSite(sitePath))
{
List folderList = new List();
SPWeb web = siteCollection.OpenWeb();
web.AllowUnsafeUpdates = true;
SPListCollection collection = web.GetListsOfType(SPBaseType.DocumentLibrary);
FolderProperties folder;
foreach (SPList list in collection)
{
folder = new FolderProperties();
if (!list.Hidden)
{
folder.RelativeURL = list.Url();
folder.Title = list.Title;
folder.Name = list.Name();
folderList.Add(folder);
}
}
return folderList;
}
SharePoint Service vs. Object Model
SharePoint object model can be used, if the final application is going to get executed on a SharePoint server. So you can use this model in case the final application is hosted on the same machine as Sharepoint server or you are writing some web parts.
If you are developing an application that is going to remotely communicate to the WSS 3.0, then the best way to handle them is to work with web services exposed by WSS 3.0
Note: You copy the Microsoft.Sharepoint.dll to a development machine and use them in your application. But, this Microsoft.Sharepoint.dll library will not be loaded on the development machine. You will need to deploy it on a machine having SharePoint server to execute the same.
Custom Web Service with Object Model Code.
There are cases when the application will have to deploy on a remote machine and access the Sharepoint server using object model. In these scenarios, it is recommended to expose the required functionality through a web service, which would be deployed on the same machine as Sharepoint. Now that the web service is deployed on the same machine, development can be done using the Sharepoint object model. The functionality exposed by this web service can be accessed by remote applications.
How To
The following section provides how to get the list of document libraries available under a SharePoint site using custom services hosted on the SharePoint machine/server.
Step 1: Create Custom Web Service
Create a web service project using Visual Studio:
Add project reference to the SharePoint library from the following location in the machine where the WSS is installed.
C:\program files\common files\microsoft shared\web server extensions\12\isapi
Add the necessary web methods to access the Sharepoint server using the object model. The following web method will return all the document libraries available under the site path.
[WebMethod]
public List<folderproperties> GetDocumentLibaries(string sitePath)
{
using (SPSite siteCollection = new SPSite(subSitePath))
{
List<folderproperties> folderList = new List<folderproperties>();
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPListCollection collection = web.GetListsOfType(SPBaseType.DocumentLibrary);
FolderProperties folder;
foreach (SPList list in collection)
{
folder = new FolderProperties();
if (!list.Hidden)
{
folder.RelativeURL = list.Url();
folder.Title = list.Title;
folder.Name = list.Name();
folderList.Add(folder);
}
}
return folderList;
}
catch (Exception)
{
throw;
}
finally
{
web.Close();
}
}
}
Step 2: Add Reference to the Above Created Custom Service
Add web reference to the client application by clicking “Add web reference” in the project explorer.
Step 3: Calling Web Service in the Code
GetDocumentLibaries() method of the service is used to get the list of document libraries available in the site. In order to call this method, first the developer has to create the instance of the proxy object, which in turn will call the web method exposed by the web service.
CustomSharePointService client = new CustomSharePointService();
client.Credentials = new NetworkCredential(UserName, Password, Domain);
GridView1.DataSource = client.GetDocumentLibaries
("http://mysheceusd01:24832/sites/MySite/");
GridView1.DataBind();
Issues and Resolution
THe following sections provide some of the issues faced with using object model with custom service and how they were resolved.
Issue: File not found error while trying to access the Sharepoint from code at the line using {(SPSite siteCollection = new SPSite(subSitePath)).
The above issue could be because of multiple reasons. The object model code throws similar messages like FileNotFound for multiple scenarios like:
- Wrong SharePoint URL
- Insufficient permission in accessing the SharePoint site
- Application pool issue
Resolution: So in case you come across the above issue, please follow these steps to debug the issue.
- Check for URL in browser and check if the user has enough privileges to access this site.
- Check the code from Windows or console application.
- If the step 2 is successful, check for the application pool of the web service or web site which has the object model code. Change it to the application pool of site collection you are trying to connect.
- If the step 3 also does not work, check for the following stuff in web.config and IIS:
<identity impersonate ="true"/> in web.config - Enabled the Windows authentication in the IIS settings.
Summary
The following matrix provides the comparison for each of the development approaches, which helps developers in choosing the right kind of development and deployment approach.
|
Parameters
|
Development Methodology
|
|
WSS services
|
Object Model
|
Custom web service with Object model
|
|
Ease of development
|
Medium
|
High
|
Medium
|
|
Remote access
|
Yes
|
No
|
Yes
|
|
Flexibility
|
Medium
|
High
|
High
|
References
Code
This section contains the code required for running the demo application. It has two projects.
CustomSharePointServices contains the custom service project, which contains the object model code exposed through web service. Here are all the methods that can be used as is, but may not be optimal code in some cases. :)
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Services;
using Microsoft.SharePoint;
using System.Web.Services.Protocols;
using System.Xml;
namespace CustomSharePointServices
{
[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[System.ComponentModel.ToolboxItem(false)]
public class CustomSharePointService : System.Web.Services.WebService
{
public static readonly XmlQualifiedName DetailElementName =
new XmlQualifiedName("detail");
public static readonly string FileNotFound = "File not found";
public static readonly string VersionNotFound = "Version Not Found";
public static readonly string FileNotCheckedOut = "File not checked out";
[WebMethod]
public bool CreateDocLib(string docLibPath, string name, string description)
{
using (SPSite siteCollection = new SPSite(docLibPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPListTemplateType templateType =
SPListTemplateType.DocumentLibrary;
Guid listId = web.Lists.Add(name, description, templateType);
SPList documentLibrary = web.Lists[listId];
documentLibrary.EnableVersioning = true;
documentLibrary.Update();
}
finally
{
web.Close();
}
}
return true;
}
[WebMethod]
public bool DocumentCheckOut(string documentPath)
{
bool retvalue = false;
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
if (listFile.CheckOutStatus == SPFile.SPCheckOutStatus.None)
{
listFile.CheckOut();
retvalue = true;
}
}
else
{
throw new SoapException(FileNotFound, DetailElementName);
}
web.Close();
}
return retvalue;
}
[WebMethod]
public bool DocumentUnDoCheckOut(string documentPath)
{
bool retvalue = false;
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
if (listFile.CheckOutStatus != SPFile.SPCheckOutStatus.None)
{
listFile.UndoCheckOut();
retvalue = true;
}
}
else
{
throw new SoapException(FileNotFound, DetailElementName);
}
web.Close();
}
return retvalue;
}
[WebMethod]
public bool DocumentCheckIN(string documentPath, string comment)
{
bool retvalue = false;
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
if (listFile.CheckOutStatus != SPFile.SPCheckOutStatus.None)
{
listFile.CheckIn(comment);
retvalue = true;
}
}
else
{
throw new SoapException
(FileNotCheckedOut, DetailElementName);
}
}
finally
{
web.Close();
}
}
return retvalue;
}
[WebMethod]
public bool UploadDocument(string documentPath, byte[] contents)
{
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
listFile.SaveBinary(contents);
}
else
{
listFile = web.Files.Add(documentPath, contents);
}
}
catch (Exception)
{
throw;
}
finally
{
web.Close();
}
}
return true;
}
[WebMethod]
public List<string> GetDocumentVersions(string documentPath)
{
List<string> versionList = null;
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
SPFileVersionCollection versions = listFile.Versions;
versionList = new List<string>();
foreach (SPFileVersion item in versions)
{
versionList.Add(item.VersionLabel);
}
}
else
{
throw new SoapException(FileNotFound, DetailElementName);
}
web.Close();
}
finally
{
web.Close();
}
}
return versionList;
}
[WebMethod]
public bool ReNameDocument(string documentPath, string newName)
{
bool retvalue = false;
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
listFile.Item["Name"] = string.Format("{0}", newName);
listFile.Item.Update();
retvalue = true;
}
else
{
throw new SoapException(FileNotFound, DetailElementName);
}
web.Close();
}
finally
{
web.Close();
}
}
return retvalue;
}
[WebMethod]
public byte[] DownloadDocumentByVersion
(string documentPath, string versionID)
{
byte[] content = null;
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
if (listFile.UIVersionLabel == versionID)
{
content = listFile.OpenBinary();
return content;
}
SPFileVersionCollection versions = listFile.Versions;
foreach (SPFileVersion item in versions)
{
if (item.VersionLabel == versionID)
{
content = item.OpenBinary();
return content;
}
}
throw new SoapException(VersionNotFound, DetailElementName);
}
else
{
throw new SoapException(VersionNotFound, DetailElementName);
}
}
finally
{
web.Close();
}
}
}
[WebMethod]
public byte[] DownloadDocument(string documentPath)
{
byte[] content = null;
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
content = listFile.OpenBinary();
return content;
}
else
{
throw new SoapException(FileNotFound, DetailElementName);
}
}
finally
{
web.Close();
}
}
}
[WebMethod]
public bool DeleteDocument(string documentPath)
{
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
listFile.Delete();
}
else
{
throw new SoapException(FileNotFound, DetailElementName);
}
}
finally
{
web.Close();
}
}
return true;
}
[WebMethod]
public bool DeleteDocumentByVersion(string documentPath, string versionID)
{
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
SPFileVersionCollection versions = listFile.Versions;
foreach (SPFileVersion item in versions)
{
if (item.VersionLabel == versionID)
{
item.Delete();
break;
}
}
}
else
{
throw new SoapException(VersionNotFound, DetailElementName);
}
}
finally
{
web.Close();
}
}
return true;
}
[WebMethod]
public bool DeleteDocumentAllVersions(string documentPath)
{
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
SPFileVersionCollection versions = listFile.Versions;
versions.DeleteAll();
}
else
{
throw new SoapException(VersionNotFound, DetailElementName);
}
}
finally
{
web.Close();
}
}
return true;
}
[WebMethod]
public bool CreateFolder(string docLibPath, string name, string description)
{
using (SPSite siteCollection = new SPSite(docLibPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFolderCollection folders =
web.GetFolder(docLibPath).SubFolders;
folders.Add(name);
}
catch (Exception)
{
throw;
}
finally
{
web.Close();
}
}
return true;
}
[WebMethod]
public List<string> GetFolders(string docLibPath)
{
using (SPSite siteCollection = new SPSite(docLibPath))
{
List<string> folderList = new List<string>();
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFolderCollection folders =
web.GetFolder(docLibPath).SubFolders;
foreach (SPFolder folder in folders)
{
if (folder.Name.ToLower() != "forms")
{
folderList.Add(folder.Name);
}
}
return folderList;
}
catch (Exception)
{
throw;
}
finally
{
web.Close();
}
}
}
[WebMethod]
public List<folderproperties> GetDocumentLibaries(string subSitePath)
{
using (SPSite siteCollection = new SPSite(subSitePath))
{
List<folderproperties> folderList = new List<folderproperties>();
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPListCollection collection =
web.GetListsOfType(SPBaseType.DocumentLibrary);
FolderProperties folder;
foreach (SPList list in collection)
{
folder = new FolderProperties();
if (!list.Hidden)
{
folder.RelativeURL = list.Url();
folder.Title = list.Title;
folder.Name = list.Name();
folderList.Add(folder);
}
}
return folderList;
}
catch (Exception)
{
throw;
}
finally
{
web.Close();
}
}
}
[WebMethod]
public List<fileproperties> GetDocumentLibariesFiles
(string docLibPath, string documentLibraryName)
{
using (SPSite siteCollection = new SPSite(docLibPath))
{
List<fileproperties> fileList = new List<fileproperties>();
FileProperties fileProperties;
SPWeb web = siteCollection.OpenWeb();
try
{
SPFileCollection f = web.GetFolder(documentLibraryName).Files;
foreach (SPFile file in f)
{
fileProperties = new FileProperties();
fileProperties.RelativeURL = file.Url;
fileProperties.AbsoulteURL = docLibPath + file.Url;
fileProperties.LastModified =
file.TimeLastModified.ToString();
fileProperties.FileName = file.Name;
fileProperties.Title = file.Title;
fileProperties.isCheckedOut =
file.CheckOutStatus.ToString();
if (file.CheckedOutBy != null)
{
fileProperties.CheckedOutBy =
file.CheckedOutBy.Name.ToString();
}
fileProperties.FileCreatedDate = file.Author.Name;
fileProperties.FileCreatedBy = file.TimeCreated.ToString();
fileProperties.FileModifiedDate =
file.TimeLastModified.ToString();
fileProperties.FileModifiedBy = file.ModifiedBy.Name;
fileList.Add(fileProperties);
}
return fileList;
}
catch (Exception)
{
throw;
}
finally
{
web.Close();
}
}
}
[WebMethod]
public List<string> GetFileFromFolder(string docLibPath, string folderName)
{
using (SPSite siteCollection = new SPSite(docLibPath))
{
List<string> fileList = new List<string>();
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFolder folder =
web.GetFolder(docLibPath).SubFolders[folderName];
foreach (SPFile file in folder.Files)
{
fileList.Add(file.Name);
}
return fileList;
}
catch (Exception)
{
throw;
}
finally
{
web.Close();
}
}
}
[WebMethod]
public bool IsFolderExists(string FolderPath)
{
bool retvalue = false;
using (SPSite siteCollection = new SPSite(FolderPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFolder folder = web.GetFolder(FolderPath);
if (folder != null && folder.Exists)
{
retvalue = true;
}
else
{
retvalue = false;
}
web.Close();
}
finally
{
web.Close();
}
}
return retvalue;
}
[WebMethod]
public bool IsDocumentExists(string documentPath)
{
using (SPSite siteCollection = new SPSite(documentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(documentPath);
if (listFile != null && listFile.Exists)
{
return true;
}
else
{
return false;
}
}
finally
{
web.Close();
}
}
}
[WebMethod]
public bool CopyFile(string srcDocumentPath, string destinationDocumentPath)
{
bool retValue;
using (SPSite siteCollection = new SPSite(srcDocumentPath))
{
SPWeb web = siteCollection.OpenWeb();
try
{
web.AllowUnsafeUpdates = true;
SPFile listFile = web.GetFile(srcDocumentPath);
if (listFile != null && listFile.Exists)
{
listFile.CopyTo(destinationDocumentPath);
retValue = true;
}
else
{
retValue = false;
}
}
finally
{
web.Close();
}
return retValue;
}
}
}
}
Sample is a web application, which has the code for displaying the document libraries using WSS web service, object model and by consuming custom web service.
History
- 15th June, 2010: Initial post
