Walkthrough: Building a Basic XML Web Service Using ASP.NET

Article
02/13/2011

This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.

Developing an XML Web service using ASP.NET starts with the following steps:

Create a file with an .asmx file name extension and declare a Web service in it using an @WebService directive
Create a class that implements the Web service. The class can optionally derive from the WebService class.
Optionally, apply the WebServiceAttribute attribute to the class implementing the Web service.
Define the Web service methods that compose the functionality of the Web service.

Declaring a Web Service

When you create an XML Web service in ASP.NET, you place the required @ WebService directive at the top of a text file with an .asmx file name extension. The presence of the .asmx file and the @ WebService directive correlate the URL address of the XML Web service with its implementation. Next, you implement the XML Web service class that defines the methods and data types visible by XML Web service clients. Finally, you add your XML Web service logic to those methods in order to process XML Web service requests and send back responses. The XML Web service class you define can be included directly in the .asmx file, or in a separate file. If you use a separate file, it must be compiled into an assembly. Optionally, you can apply a WebService attribute to the class implementing the XML Web service. The class that implements the XML Web service can derive from the WebService class.

To declare a Web service whose implementation resides in the same file

Add an @ WebService directive to the top of a file with an .asmx file name extension, specifying the class that implements the Web service and the programming language that is used in the implementation.

The Class attribute can be set to a class that resides in the same assembly as the @ WebService directive or to a class within a separate assembly. If the class resides in a separate assembly, it must be placed in the \Bin directory under the Web application where the Web service resides. The Language attribute can be set to C#, VB, and JS, which refer to C#, Visual Basic .NET, and JScript .NET, respectively.

The following code example sets the Language attribute of the @ WebService directive, and sets the Class attribute to Util, which resides in the same file.
```
<%@ WebService Language="C#" Class="Util" %>
```
```
<%@ WebService Language="VB" Class="Util" %>
```

To declare a Web service whose implementation resides in an assembly

Add an @ WebService directive to the top of a file with an .asmx extension, specifying the class that implements the Web service, the assembly that contains the implementation, and the programming language that is used in the implementation. If you use a separate file, it must be compiled into an assembly.

The following @ WebService directive is the only line in a file with an .asmx extension, specifying that the MyName.MyWebService class resides in the MyAssembly assembly within the \Bin directory of the Web application that is hosting the Web service.
```
<%@ WebService Language="C#" Class="MyName.MyWebService,MyAssembly" %>
```
```
<%@ WebService Language="VB" Class="MyName.MyWebService,MyAssembly" %>
```
Note

If you do not specify an assembly within the @ WebService directive, then ASP.NET searches through the list of assemblies in the \Bin directory of the Web application that is hosting the Web service the first time the Web service is accessed. Therefore, you will improve performance on the first access by providing the assembly name.

Deriving from the WebService Class

Classes that implement a Web service that was created using ASP.NET can optionally derive from the WebService class to gain access to the common ASP.NET objects, such as Application, Session, User, and Context.

To derive from the WebService class and access common ASP.NET objects

<%@ WebService Language="C#" Class="Util" %>
using System;
using System.Web.Services;

public class Util: WebService

<%@ WebService Language="VB" Class="Util" %>
Imports System
Imports System.Web.Services

Public Class Util
   Inherits WebService

Applying the WebService Attribute

Apply the optional WebService attribute to a class that implements a Web service to set the default XML namespace for the Web service, which originally is http://tempuri.org, along with a string to describe the Web service.

It is highly recommended that this default namespace, which is http://tempuri.org, be changed before the XML Web service is made publicly consumable. This is important because the XML Web service must be distinguished from other XML Web services that might inadvertently use the namespace as the default (<http://tempuri.org/>).

To set the XML namespace of which a Web service is a member

Apply a WebService attribute to the class that is implementing the Web service, setting the Namespace property.

The following code example sets the XML namespace to https://www.contoso.com/.

<%@ WebService Language="C#" Class="Util" Debug=true%>
using System.Web.Services;
using System;

[WebService(Namespace="https://www.contoso.com/")]
public class Util: WebService

<%@ WebService Language="VB" Class="Util"%>
Imports System.Web.Services
Imports System

<WebService(Namespace:="https://www.contoso.com/")> _
Public Class Util
    Inherits WebService

Defining Web Service Methods

Methods of a class that implements a Web service do not automatically have the ability to be communicated with over the Web, but with Web services created using ASP.NET, it is very simple to add that capability. To add this capability, apply a WebMethod attribute to public methods. Methods of a Web service that can be communicated with over the Web are called Web service methods.

To declare a Web service method

Add public methods to the class that is implementing the Web service.
Apply the WebMethod attribute to the public methods that you want to be mapped to Web service operations.

The following code example has two public methods, one of which is a Web service method. The Multiply method is a Web service method, because it has a WebMethod attribute applied to it.

<%@ WebService Language="C#" Class="Util" %>
using System.Web.Services;
using System;

[WebService(Namespace="https://www.contoso.com/")]
public class Util: WebService 
{
    [ WebMethod]    public long Multiply(int a, int b) 
    {
        return a * b;
    }
}

<%@ WebService Language="VB" Class="Util" %>

Imports System.Web.Services
Imports System

<WebService(Namespace:="https://www.contoso.com/")> 
Public Class Util 
    Inherits WebService
    < WebMethod()> _    Public Function Multiply(a As Integer, b As Integer) As Long
        Return a * b
    End Function
End Class

Walkthrough: Building a Basic XML Web Service Using ASP.NET

Declaring a Web Service

To declare a Web service whose implementation resides in the same file

To declare a Web service whose implementation resides in an assembly

Deriving from the WebService Class

To derive from the WebService class and access common ASP.NET objects

Applying the WebService Attribute

To set the XML namespace of which a Web service is a member

Defining Web Service Methods

To declare a Web service method

See Also

Reference

Concepts

Other Resources

Additional resources