How to: Create Asynchronous Web Service Methods

Switch View

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Developer's Guide

How to: Create Asynchronous Web Service Methods

[Note: This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

This procedure describes how to convert a Web service method into a pair of methods designed for asynchronous access. It follows the .NET Framework asynchronous design pattern. The topic Asynchronous XML Web Service Methods explains how this procedure works, as well as how the Wsdl.exe tool generates client proxy classes that can asynchronously access Web service methods, even if they're designed for synchronous access..

To implement an asynchronous Web service method

Split a synchronous Web service method into two methods, each with the same base name, one with that name starting with Begin and the other End.
The parameter list for the Begin method contains all the in and by reference parameters for the method's functionality plus two additional parameters.
- By reference parameters are listed as in parameters.
- The second from the last parameter must be an AsyncCallback. The AsyncCallback parameter allows a client to supply a delegate, which is invoked when the method completes. When an asynchronous Web service method calls another asynchronous method, this parameter can be passed into the second from last parameter for that method.
- The last parameter is an Object. The Object parameter allows a caller to supply state information to the method. When an asynchronous Web service method calls another asynchronous method, this parameter can be passed into the last parameter for that method.
- The return value must be of type IAsyncResult.
The parameter list for the End method consists of an IAsyncResult followed by any out and by reference parameters specific to the method's functionality.
- The return value is the same type as the return value of a synchronous Web service method.
- By reference parameters are listed as out parameters.

Example

using System;
using System.Web.Services;

[WebService(Namespace="http://www.contoso.com/")]
public class MyService : WebService 
{
    public RemoteService remoteService;
    public MyService() 
    {
        // Create a new instance of proxy class for 
        // the Web service to be called.
        remoteService = new RemoteService();
    }
    // Define the Begin method.
    [WebMethod]
    public IAsyncResult BeginGetAuthorRoyalties(String Author,
        AsyncCallback callback, object asyncState) 
    {
        // Begin asynchronous communictation with a different XML Web
        // service.
        return remoteService.BeginReturnedStronglyTypedDS(Author,
            callback,asyncState);
    }
    // Define the End method.
    [WebMethod]
    public AuthorRoyalties EndGetAuthorRoyalties(IAsyncResult
        asyncResult) 
    {
        // Return the asynchronous result from the other Web service.
        return remoteService.EndReturnedStronglyTypedDS(asyncResult);
    }
}

Visual Basic

Imports System.Web.Services
<WebService(Namespace:="http://www.contoso.com/")> _
Public Class MyService
    Inherits WebService
    Public remoteService As RemoteService

    Public Sub New()
        MyBase.New()
        ' Create a new instance of proxy class for 
        ' the Web service to be called.
        remoteService = New RemoteService()
    End Sub

    ' Define the Begin method.
    <WebMethod()> _
    Public Function BeginGetAuthorRoyalties(ByVal Author As String, _
    ByVal callback As AsyncCallback, ByVal asyncState As Object) _
        As IAsyncResult
        ' Begin asynchronous communictation with a different XML Web
        ' service.
        Return remoteService.BeginReturnedStronglyTypedDS(Author, _
            callback, asyncState)
    End Function
    ' Define the End method.
    <WebMethod()> _
    Public Function EndGetAuthorRoyalties(ByVal asyncResult As _
        IAsyncResult) As AuthorRoyalties
        ' Return the asynchronous result from the other Web service.
        Return remoteService.EndReturnedStronglyTypedDS(asyncResult)
    End Function
End Class