Walkthrough: Creating a Custom ASP.NET Web Service

In Visual Studio, click File, point to New, and then select Web Site.

In the New Web Site dialog box, select .NET Framework 3.5 as the target framework, select Visual Basic or Visual C# as the programming language under Installed Templates, select the ASP.NET Web Service template, select File System in the Web location box, specify a location for the project, and then click OK.

Within the new Web service solution, create a separate class library project to contain the Web service logic. To create the project, click File, point to New, and then select Project.

In the New Project dialog box, expand either Visual Basic or Visual C# under Installed Templates, select Class Library as the template, provide a name and location for the project, select Add to Solution in the Solution box, and then click OK.

Add a reference to the System.Web.Services namespace in the class library project. Right-click the project in Solution Explorer, click Add Reference, select System.Web.Services on the .NET tab of the Add Reference dialog box, and then click OK.

Replace the default class file in the class library project with the default service class file that Visual Studio provides in the App_Code folder of the Web service.

To replace the class file with the service class file

1. In Solution Explorer, drag the Service.cs or Service.vb file to the top node in the class library project.

2. Delete the Class1.cs or Class1.vb file, and also delete the Service.cs or Service.vb file that remains in the App_Code folder.

Create a strong name for the class library:

1. In Solution Explorer, right-click the class library project, and then click Properties.

2. In the Properties dialog box, click Signing, select Sign the assembly, and then select <New> in the Choose a strong name key file list.

3. In the Create Strong Name Key dialog box, provide a file name for the key, clear the Protect my key file with a password check box, and then click OK.

To build only the class library project, right-click the project in Solution Explorer, and then click Build.

To add your assembly to the global assembly cache (GAC), you can either drag the assembly into the %windows%\assembly directory using two instances of Windows Explorer, or use gacutil.exe, the command-line utility that is installed with theMicrosoft .NET Framework 2.0 Software Development Kit.

To use gacutil.exe to copy the class library DLL into the GAC

1. To open the Visual Studio command prompt, click Start, click All Programs, click Microsoft Visual Studio 2010, click Visual Studio Tools, right-click Visual Studio Command Prompt (2010), and click Run as administrator.

2. At the command prompt, type a command in the following form, and press ENTER.

   gacutil.exe -if "<Full file system path to DLL>".

Now you are ready to modify the assembly information in the default Service.asmx file of the Web service by using information about the DLL that can be found in the GAC. To get information from the GAC, open the %windows%\assembly directory in Windows Explorer, right-click your assembly, and click Properties.

To open Service.asmx in Solution Explorer, right-click the file and click Open.

Remove the CodeBehind attribute from the page directive in Service.asmx, and modify the contents of the Class attribute so that the directive matches the following format, where the assembly name "MyServiceAssembly" and the public key token are values specified in the Properties dialog box that you opened in step 10.

<%@ WebService Language="C#" Class="Service, MyServiceAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8f2dca3c0f2d0131" %>

In Visual Basic, include the namespace to identify the class, for example, Class="MyServiceNamespace.Service, MyServiceAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8f2dca3c0f2d0131".

Rename your .asmx file appropriately, and then save your changes.

In Windows Explorer, copy the .asmx file of your Web service to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS.

Run Disco.exe at the command prompt from the LAYOUTS directory to generate .disco and .wsdl files. Run a command in the following format to generate the files in \LAYOUTS:

disco http://MyServer/_layouts/MyCustomWebService.asmx

To register namespaces of the SharePoint Foundation 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.

<%@ Page Language="C#" Inherits="System.Web.UI.Page" %> 
<%@ Assembly Name="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> 
<%@ Import Namespace="Microsoft.SharePoint.Utilities" %> 
<%@ Import Namespace="Microsoft.SharePoint" %>
<% Response.ContentType = "text/xml"; %>

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.SPHttpUtility class, and which replaces the method name that is specified in the binding attribute.

<contractRef ref=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request) + "?wsdl"),Response.Output); %> 
docRef=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> 
xmlns="http://schemas.xmlsoap.org/disco/scl/" />
<soap address=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> 
xmlns:q1="http://tempuri.org/" binding="q1:HelloWorld" xmlns="http://schemas.xmlsoap.org/disco/soap/" />
<soap address=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> 
xmlns:q2="http://tempuri.org/" binding="q2:ServiceSoap12" xmlns="http://schemas.xmlsoap.org/disco/soap/" />

In the .wsdl file, make the following similar substitution for the SOAP address that is specified.

<soap:address location=<% SPHttpUtility.AddQuote(SPHttpUtility.HtmlEncode(SPWeb.OriginalBaseUrl(Request)),Response.Output); %> />

Rename both files in the respective formats MyCustomWebServicedisco.aspx and MyCustomWebServicewsdl.aspx so that your service is discoverable through SharePoint Foundation.

Open Visual Studio, and on the File menu, point to New, and then click Project.

In the New Project dialog box, select Visual C# or Visual Basic, and then select the Windows Forms Application template.

Type a name for the application in the Name box, specify a location for the project files in the Location box, and then click OK.

In Solution Explorer, right-click the project, and then click Add Service Reference.

In the Add Service Reference dialog box, click Advanced, and in the Service Reference Settings box, click Add Web Reference.

In the address bar of the Add Web Reference browser, type the URL for the site to apply the service to, as follows,

http://Server_Name/[sites/][Site_Name/]_vti_bin/MyCustomWebService.asmx

and then press ENTER.

Click Add Reference to download the service contract for the Web service.

Open Form1 in Design view, display the Toolbox, and then drag a button onto the form.

Double-click the Button1 control on Form1 to display the code-behind file in the code editor, and add the following code that calls your custom method.

Dim MyCustomService As New Web_Reference_Folder.MyServiceClass()
MyCustomService.UseDefaultCredentials = True
MessageBox.Show(MyCustomService.HelloWorld())

Web_Reference_Folder.MyServiceClass MyCustomService = new Web_Reference_Folder.MyServiceClass();
MyCustomService.UseDefaultCredentials = true;
MessageBox.Show(MyCustomService.HelloWorld());

Press F5 to compile and run the project and see a message box that displays "Hello World".

Add a reference to the Microsoft.SharePoint assembly. Right-click the class library project in Solution Explorer, click Add Reference, select SharePoint Foundation, and then click OK.

In your project Service.cs or Service.vb file, you must import the appropriate namespaces in the object model. For example, to use types and members of the Microsoft.SharePoint and Microsoft.SharePoint.Utilities namespaces, add the following directives.

Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.Utilities

using Microsoft.SharePoint;
using Microsoft.SharePoint.Utilities;

Rename the method in Service.cs or Service.vb. For example, change the name from HelloWorld to GetSiteListCount.

Add the following code to display the name of the Web site and the number of lists that it contains.

Dim myWebSite As SPWeb = SPContext.Current.Web
Dim lists As SPListCollection = myWebSite.Lists

Return myWebSite.Title + " contains " + lists.Count.ToString() + 
" lists."

SPWeb myWebSite = SPContext.Current.Web;
SPListCollection lists = myWebSite.Lists;

return (myWebSite.Title + " contains " + lists.Count.ToString() + 
" lists.");

Note
If your code modifies SharePoint Foundation data in some way during an HttpGet request, you may need to allow unsafe updates on the Web site, which you can do by setting the AllowUnsafeUpdates property.

To rebuild the class library DLL and copy it to the GAC, repeat steps 8 and 9 in "To create an ASP.NET Web service."

Reset Internet Information Services (IIS) for changes in the DLL to take effect.

To generate new versions of the .disco and .wsdl files, repeat the steps in "To generate the static discovery and WSDL files," but change the method binding name in the .disco file as appropriate, for example, to GetSiteListCount.

Copy the new versions of the MyCustomWebServicedisco.aspx and MyCustomWebServicewsdl.aspx files to the ISAPI folder.

Open the Windows application that you created previously, delete the previous Web service reference for the Hello World example, change the method name as appropriate, and add a new Web reference to the revised Web service.

Press F5 to compile and run the project and see a message box that displays the Web site name and the number of lists that it contains.