This documentation is archived and is not being maintained.

Code Model for XML Web Services in Managed Code 

XML Web services consist of two parts: the XML Web service entry point and the code that implements the XML Web service functionality. In ASP.NET, the .asmx file is a text file that serves as the addressable entry point for the XML Web service. It references code in pre-compiled assemblies, a code-behind file, or code contained in the .asmx file itself.

NoteNote

If the code is contained in the .asmx file directly, then ASP.NET will compile it on demand on the server.

The WebService processing directive at the top of the .asmx file determines where to find the implementation of the XML Web service. By default, Visual Studio uses code-behind files, such as Service1.asmx.vb or Service1.asmx.cs, when you create an XML Web service with the ASP.NET Web Service project template.

NoteNote

Visual Studio does not support cross-language compiling. For example, it is not possible to include a Visual C# XML Web service in a Visual Basic ASP.NET Web Application project, and vice versa.

When you build an XML Web service in managed code, ASP.NET automatically provides the infrastructure and handles the processing of XML Web service requests and responses, including the parsing and creation of SOAP messages.

WebService Processing Directive

At the top of the .asmx page is a WebService processing directive, which includes information in the form of attributes regarding the implementation of the XML Web service. This processing directive provides necessary information to the ASP.NET environment, such as which class implements the XML Web service functionality. An example of the WebService processing directive follows:

[Visual Basic]
<%@ WebService Language="vb" Codebehind="Service1.asmx.vb"
    Class="WebService1.Service1" %>


[C#]
<%@ WebService Language="c#" Codebehind="Service1.asmx.cs"
    Class="WebService1.Service1" %>

The Language attribute indicates the programming language used to develop the XML Web service. You can create XML Web services in any .NET-compatible language, such as Visual Basic .NET or Visual C#.

When creating XML Web services in managed code using Visual Studio .NET, the implementation of the XML Web service resides in a code-behind file. The code-behind file is associated with the .asmx page using the Codebehind attribute.

NoteNote

This attribute helps Visual Studio to manage your XML Web service project and is not required at runtime.

When using the ASP.NET Web Service project template, the Class attribute indicates which class in the code-behind file implements the functionality of the XML Web service.

Visual Studio .NET inserts this processing directive automatically into the .asmx file when you use the ASP.NET Web Service project template.

NoteTip

If you choose to rename the class, be sure to change the class name in the Class attribute of the WebService directive.

NoteNote

To view the contents of the .asmx file, in Solution Explorer, right-click the .asmx file and click Open With on the shortcut menu. In the Open With dialog box, select Source Code (Text) Editor and then click Open.

For more information, see Walkthrough: Building a Basic XML Web Service Using ASP.NET.

System.Web.Services.WebService Class

The System.Web.Services.WebService class, which defines the optional base class for XML Web services, provides direct access to common ASP.NET objects, such as those for application and session state. By default, XML Web services created in managed code using Visual Studio inherit from this class. The XML Web service can inherit from this class to gain access to ASP.NET's intrinsic objects, such as Request and Session. For more information, see WebService Class.

If the XML Web service does not inherit from this class, it can access the ASP.NET intrinsic objects from System.Web.HttpContext.Current. The class implementing the XML Web service must be public and must have a public default constructor (a constructor without parameters). This makes it possible for ASP.NET to create an instance of the XML Web service class to process incoming XML Web service requests. For more information, see HttpContext.Current Property.

[Visual Basic]
Imports System.Web.Services
Public Class Service1
   Inherits System.Web.Services.WebService
   ' Implementation code.
End Class


[C#]
using System.Web.Services;
public class Service1 : System.Web.Services.WebService
{
   // Implementation code.
}

For more information, see Inheriting from the WebService Class.

WebService Attribute

Each XML Web service requires a unique namespace, which makes it possible for client applications to differentiate among XML Web services that might use the same method name. The default namespace for XML Web services created in Visual Studio .NET is "http://tempuri.org/WebService1/Service1" where WebService1 is the project name and Service1 is the class name. Although the namespace resembles a typical URL, you should not assume that it is viewable in a Web browser, it is merely a unique identifier.

NoteNote

You may want to provide a Web page at that location that contains information about XML Web services you provide.

Using the WebService attribute, you can specify the namespace and provide a brief description for the XML Web service. The brief description will appear on the Service help page when you call the XML Web service from a browser without specifying a query string:

[Visual Basic]
<System.Web.Services.WebService( _ 
   Namespace:="http://tempuri.org/WebService1/Service1", _ 
   Description:="A short description of the XML Web service.")> _
Public Class Service1
   Inherits System.Web.Services.WebService
   ' Implementation code.
End Class


[C#]
[System.Web.Services.WebService( 
   Namespace="http://tempuri.org/WebService1/Service1",  
   Description="A short description of the XML Web service.")] 
public class Service1 : System.Web.Services.WebService
{
   // Implementation code.
}

For more information, see WebServiceAttribute Class and Using the WebService Attribute.

Applying the WebMethod Attribute

To expose a method as part of an XML Web service, you must place a WebMethod attribute before the declaration of each public method you want to expose. For more information, see Creating an XML Web Service Method.

[Visual Basic]
<System.Web.Services.WebMethod()> _
Public Function MyString(ByVal x as string) As String
   ' Implementation code.
End Function


[C#]
[System.Web.Services.WebMethod()] 
public string MyString(string x) 
{
   //implementation code
}

The WebMethod attribute contains several properties for configuring the behavior of the XML Web service. For more information, see WebMethodAttribute Class and Using the WebMethod Attribute. For example, you can use this attribute to provide a brief description that will appear on the associated Service help page:

[Visual Basic]
<System.Web.Services.WebMethod( _ 
   Description:="A short description of this method.")> _
Public Function MyString(ByVal x as string) As String
   ' Implementation code.
End Function


[C#]
[System.Web.Services.WebMethod( 
   Description="A short description of this method.")] 
public string MyString(string x) 
{
   // Implementation code.
}

Separate multiple properties with a comma. For example, to provide a description and to cache the results of an XML Web service for 60 seconds:

[Visual Basic]
<System.Web.Services.WebMethod( _ 
   Description:="A short description of this method.", _ 
           CacheDuration:=60)> _
Public Function MyString(ByVal x as string) As String
   ' Implementation code.
End Function


[C#]
[System.Web.Services.WebMethod( 
   Description="A short description of this method.", 
   CacheDuration=60)] 
public string MyString(string x) 
{
   // Implementation code.
}

Summary

Each XML Web service consists of an .asmx file and an XML Web service class. The .asmx file contains a WebService processing directive that references the class. The XML Web service class is public, has a public default constructor, and contains one or more public methods marked with the WebMethod attribute. The following diagram shows the relationship between the project, the class, its methods, and the resulting XML Web service.

WebService Classes and Resulting Items
Web Service Project Deployment Items

See Also

Show: