|Creating a Custom Web Service for SharePoint
Category: Microsoft Office SharePoint Server 2007, Windows SharePoint Services 3.0
There are a couple of Microsoft articles available on the internet that walk you through the creation process. Here are the links:
If you are an experienced SharePoint developer, then the articles mentioned above should be enough to get you started but if you are a developer who is new to SharePoint development and you are looking to create your first web service for SharePoint then go ahead, read this article. This article will guide you through the process of creating a custom web service for SharePoint. This web service will work with new versions of SharePoint, Office SharePoint Server 2007 and Windows SharePoint Service 3.0. We will create a simple service that will upload documents to SharePoint. We will call it UploadService. Remember, there are steps in the Microsoft articles that are confusing especially for the beginners, I have taken care of that as well. I have tried to include as much information as possible including screenshots and code snippets to make the job easier for the developer. I have used Microsoft articles as a base for this article. There are some mistakes in the Microsoft articles that have been corrected in this article.
Basic Steps for Creating a Web Service
About the Sample Application
Download size is 361 KB.
The zip file contains the web service and its related files. It also contains an installer to help you install the service easily on your server. Unzip the file to your hard disk. It will create a "WSUploadService" folder. You can unzip the file anywhere on your hard disk. There is no restriction on unzipping it to a particular folder. Run "UploadServiceCopier.exe" to install the service. Installer will ask you to select a SharePoint site where this service should be installed. Select your site from the drop down and keep the folder name as "bin" (second field: textbox) and click "Next".
To uninstall, run the "UploadServiceCopier.exe"
again. It will give you the following message:
Please run "UploadServiceCopier.exe" to
install/uninstall the service. Do not run "setup.exe" directly as it will not
install the service correctly.
1. The first step is to create an ASP.NET web service project in Visual Studio 2005. If you don't find a web service project template in visual studio, that means that you are still running an old version of Visual Studio 2005, the one without the service pack. You will have to download and install the Visual Studio 2005 Service Pack 1 Beta from the Microsoft. Here is the link:
It's a 371.9 MB download and let me tell you in advance that the installation is very slow and takes a lot of time.
On the File menu, click New Project.
2. In the Project Types box, select Visual C#.
3. In the Templates box, select ASP.NET Web Service Application.
4. In the Name box, type UploadService. In the Location box, type the following path:
You can also click the browse button to browse the folders and select the destination folder. This is the path where the project will be stored.
In the Solution Name box, type UploadService and check Create directory for solution checkbox.
5. Click OK.
6. In the Solution Explorer, right-click Service1.asmx and rename the file Files.asmx and then right click Files.asmx and click View Code.
7. Add a reference to the assembly for Microsoft Office SharePoint Server 2007 (Microsoft.SharePoint.dll). This assembly is located in the following directory:
C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\ISAPI
Please note that if you are developing on a machine that does not have SharePoint installed then you can copy the required files from the SharePoint machine to your development machine.
8. Make sure following using directives are included at the top:
9. Change your class name from Service1 to Files.
10. Comment out the web method definition. The commented out web method code will look like as follows:
11. Add following code (web method) in the class:
Change it to the following line:
13. Create a strong name for the class library. In Solution Explorer, right-click the web service project, and in the Properties dialog box, click Signing, select Sign the assembly, and select <New> in the box for choosing a strong name key file.
15. Compile the web service project.
16. As we are developing this web service on a machine that does not host SharePoint, therefore, we need to create a virtual directory in IIS. Click Start, point to Administrative Tools (You may have to go to the Control Panel first to select Administrative Tools), and then click Internet Information Services (IIS) Manager.
17. Expand the branch for the server computer to which you want to add a virtual directory. Under the server computer branch, expand the Web Sites folder, and right-click the Default Web Site and select New and then Virtual Directory.... If you don't want to use Default Web Site, you can create a new web site.
18. Click Next and enter an alias in the text box, for example, for this service you can enter UploadService.
19. Click Next and then click Browse... button to browse to the project folder (containing the .asmx file) and click Next.
20. Click Next again and then click Finish.
Generating and Modifying Static Discovery and WSDL Files
21. Use Disco.exe to generate .disco and .wsdl files. This command line utility is located in the following directory:
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin
Open command prompt and type the following line and press Enter:
Make sure you have entered the correct path in the command above otherwise you will get an error. If you created a virtual directory on a port other than the port 80, then you must mention the port number in the path (For example, http://localhost:8080/uploadservice/Files.asmx). This will generate the .disco and .wsdl files.
22. To register namespaces of the Windows SharePoint Services object model, open both the .disco and .wsdl files and replace the opening XML processing instruction -- <?xml version="1.0" encoding="utf-8"?> -- with instructions such as the following:
23. In the .disco file, modify the contract reference and SOAP address tags to be like the following example, which replaces literal paths with code generated paths through use of the Microsoft.SharePoint.Utilities.SPEncode class, and which replaces the method name that is specified in the binding attribute:
24. In the .wsdl file, make the following, similar substitution for the SOAP address that is specified:
Make the following substitution for the SOAP12 address:
25. Rename both files in the respective formats Filedisco.aspx and Fileswsdl.aspx so that your service is discoverable through SharePoint.
Deploying web service on the SharePoint server
Copy the Web service files to the _vti_bin virtual directory
26. Copy the web service files to the _vti_bin directory of the SharePoint server. Web service files that are to be copied are as following:
The _vti_bin virtual directory maps physically to the Local_Drive:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\ISAPI directory, which contains the default Web service files used in Windows SharePoint Services.
To include the Web service in the list of web services on the server
27. In Notepad, open the spsdisco.aspx file. spsdisco.aspx is located in the following directory (on the SharePoint server):
28. Add the following lines to the end of the file within the discovery element and save the file:
Copying the assembly to the correct Bin folder
29. I have seen blogs and forums where people have recommended to copy the assembly to the following folder:
Local_Drive:\program files\common files\microsoft shared\web server extensions\12\isapi\
Some people say it should be copied to the following folder:
bin folder is not there by default and has to be created but safest place to copy the assembly is the bin folder of the virtual directory of the web application where you intend to use the web service. Following path contains the virtual directories of web applications that you have created on your SharePoint server.
For example, if you want to use the web service in web application at port 81, then you should copy the assembly to the following folder:
Similarly, if you want to use the web service in web application at port 17316, then you should copy the assembly to the following folder:
I am not saying that you can not copy the assembly to the _vti_bin folder or wwwroot folder, of course you can but I have often seen people struggling with the service deployment. People often ask me where they should copy the assembly and what is the best place to put the assembly in. I tested my web service by putting the assembly file in all the recommended places and I found that bin folder of the virtual directory of the web application is the safest place where your web service is guaranteed to work.
Copy the assembly to the bin folder of the virtual directory of the web application of your choice. You will have to create the bin folder yourself. It is not there by default.
Adding web service to the GAC
30. You must add your assembly in the GAC on your SharePoint server. This is necessary otherwise you will get permissions error on the server. There are three ways to avoid this permissions error. One way is to add the assembly in the GAC. Second way is to change the trust level to medium in the web.config file and the third is to create a custom trust policy of your own. There is an article on Microsoft site that has all the details of Code Access Security (CAS) and it also shows how to create a custom policy file. Here is the link to that article if you are interested in exploring this topic:
Unfortunately, this is an old version and works only with SharePoint 2003. I am not sure if Microsoft has already released an updated version of this article or not. I intend to write an updated version of this article (at least the custom policy file part) for Office SharePoint Server 2007 and Windows SharePoint Services 3.0.
To add your assembly to the Global Assembly Cache (GAC), you can either drag and drop the assembly into the %windows%\assembly directory using 2 instances of Windows Explorer, or use the command line utility gacutil.exe that is installed with the .NET Framework SDK 2.0. This utility is located in the following folder:
To use gacutil.exe to copy the class library DLL into the GAC
Creating a Windows Application to Consume the Web Service
31. Create a new C# Windows Application in Visual Studio 2005.
32. In Solution Explorer, right-click References, and then click Add Web Reference.
If you installed the service on another port, for example, port 17316, then the
url would be:
35. Add following code to your application:
localhost is the name of the web reference that you added in previous step.
strPath contains the filename
that is to be uploaded. This is just a sample to show you how the service works,
that's why i have hard coded the filename but in a real life situation you may
want to add a text box and a browse button to select files from your hard disk.
strDestination contains the destination path. This should be the path
representing the document library where file is to be uploaded.
Q: I get "Could not create type" error message. What could be the reason?
Make sure your .asmx file has correct class name definition. Open your .asmx file and if class name is myFiles, change it to myService.myFiles!
<%@ WebService Language="C#" Class="myService.myFiles" %> (Correct)
<%@ WebService Language="C#" Class="myFiles" %> (Incorrect)
It's better that you use correct format in the first place but you can change the .asmx file after deployment as well. Go to C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\ISAPI folder and open your .asmx file in notepad (or any editor of your choice) and make the changes as mentioned above.
Q: I get "Server did not recognize the value of HTTP Header SOAPAction: ..." error?
This error occurs if you do not use correct web service namespace. Following three lines should be included in your code, just before the class defintion:
This error can occur even if you omit the trailing slash of http://tempuri.org/, http://tempuri.org will result in an error.
Q: I get "File not found." error?
This happens when SharePoint fails to find the assembly file. Make sure you have added the assembly in the correct bin folder. Also, make sure you have added the assembly in the GAC.
Q: I get "Unauthorized" error?
Make sure the user who is trying to use the web service has "Contributor" rights in the destination site or library. Also, make sure following lines are added to your client application:
Q: I get "SQL Server might not be started" error. I have double checked, my SQL Server is running. Why am i getting the error?
There could be several reasons for this. If you modified the web.config file, reverse the changes you made to the config file and then try again. The error has nothing to do with the SQL Server.
Q: I do not see my web service when i click "Web services on the local machine" in Add Web Reference?
Did you make changes in the spsdisco.aspx file? To include your web service in the list of web services on the SharePoint server, you must add reference to your web service in the spsdisco.aspx file (within the discovery element).
Q: Is it necessary to include the code in the code-behind?
No! You can write code in the myFiles.asmx (markup page) and delete the myFiles.asmx.cs file. Here is the myFiles.asmx code listing:
Language="C#" Class="myService.myFiles" %>