Declaring an XML Web Service

Article
10/17/2014

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 implementing the XML Web service can derive from the WebService class.

To declare an XML Web service whose implementation resides in the same file

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

The Class attribute can be set to a class residing 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 XML 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 to C# and the Class attribute to MyMath, which resides in the same file.
```
<%@ WebService Language="C#" Class="MyMath" %>
using System.Web.Services;
public class MyMath {
     [ WebMethod ]
     public int Add(int num1, int num2) {
          return num1+num2;
     }
}
```

To declare an XML 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 implementing the XML Web service, the assembly containing the implementation, and the programming language used in the implementation.

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 hosting the XML Web service.
```
<%@ WebService Language="C#" Class="MyName.MyWebService,MyAssembly" %>
[Visual Basic]
<%@ 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 hosting the XML Web service the first time the XML Web service is accessed. Therefore, you will improve performance on the first access by providing the assembly name.

Applying the WebService Attribute

By applying the optional WebService attribute to a class implementing an XML Web service, you can set the default XML namespace for the XML Web service along with a string to describe the XML 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 an XML Web service is a member

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

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

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

[WebService(Namespace="https://www.contoso.com/")]
public class Math {
     [ WebMethod ]
     public int Add(int num1, int num2) {
         return num1+num2;
         }
 }
[Visual Basic]
<%@ WebService Language="VB" Class="Math"%>
Imports System.Web.Services
Imports System

<WebService(Namespace:="https://www.contoso.com/")> _
Public Class Math
  <WebMethod()> _
   Public Function Add(num1 As Integer, num2 As Integer) _
                   As Integer
        Return num1 + num2
    End Function 
End Class

Deriving from the WebService Class

Classes implementing an XML Web service 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. The Application and Session properties provide access to storing and receiving state across the lifetime of the Web application or a particular session. For more information on state management, see Managing State in XML Web Services Created Using ASP.NET. The User property contains the identity of the caller, if authentication is enabled, for the XML Web service. With the identity, an XML Web service can determine whether the request is authorized. For more information on authentication, see Securing XML Web Services. The Context property provides access to all HTTP-specific information about the XML Web service client's request. For more information on the Context property, see WebService.Context Property.

The following code example uses the Context property to obtain the time of the request on the server.

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

public class Util: WebService {
   [ WebMethod(Description="Returns the time as stored on the Server",
               EnableSession=false)]
   public string Time() 
   {
      return Context.Timestamp.TimeOfDay.ToString();
   }
 } 
[Visual Basic]
<%@ WebService Language="VB" Class="Util" %>
Imports System
Imports System.Web.Services

Public Class Util
   Inherits WebService
   
   <WebMethod(Description := "Returns the time as stored on the Server", _
              EnableSession := False)> _
   Public Function Time() As String
        Return Context.Timestamp.TimeOfDay.ToString()
   End Function
End Class

Declaring an XML Web Service

Applying the WebService Attribute

Deriving from the WebService Class

See Also

Additional resources