Making Asynchronous Requests
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

Making Asynchronous Requests

The System.Net classes use the .NET Framework's standard asynchronous programming model for asynchronous access to Internet resources. The BeginGetResponse and EndGetResponse methods of the WebRequest class start and complete asynchronous requests for an Internet resource.


Using synchronous calls in asynchronous callback methods can result in severe performance penalties. Internet requests made with WebRequest and its descendants must use Stream.BeginRead to read the stream returned by the WebResponse.GetResponseStream method.

The following sample code demonstrates how to use asynchronous calls with the WebRequest class. The sample is a console program that takes a URI from the command line, requests the resource at the URI, and then prints data to the console as it is received from the Internet.

The program defines two classes for its own use, the RequestState class, which passes data across asynchronous calls, and the ClientGetAsync class, which implements the asynchronous request to an Internet resource.

The RequestState class preserves the state of the request across calls to the asynchronous methods that service the request. It contains WebRequest and Stream instances that contain the current request to the resource and the stream received in response, a buffer that contains the data currently received from the Internet resource, and a StringBuilder that contains the complete response. A RequestStateis passed as the state parameter when the AsyncCallback method is registered with WebRequest.BeginGetResponse.

The ClientGetAsync class implements an asynchronous request to an Internet resource and writes the resulting response to the console. It contains the methods and properties described in the following list.

  • The allDone property contains an instance of the ManualResetEvent class that signals the completion of the request.

  • The Main() method reads the command line and begins the request for the specified Internet resource. It creates the WebRequest wreq and the RequestState rs, calls BeginGetResponse to begin processing the request, and then calls the allDone.WaitOne()method so that the application will not exit until the callback is complete. After the response is read from the Internet resource, Main() writes it to the console and the application ends.

  • The showusage() method writes an example command line on the console. It is called by Main() when no URI is provided on the command line.

  • The RespCallBack() method implements the asynchronous callback method for the Internet request. It creates the WebResponse instance containing the response from the Internet resource, gets the response stream, and then starts reading the data from the stream asynchronously.

  • The ReadCallBack() method implements the asynchronous callback method for reading the response stream. It transfers data received from the Internet resource into the ResponseData property of the RequestState instance, then starts another asynchronous read of the response stream until no more data is returned. Once all the data has been read, ReadCallBack() closes the response stream and calls the allDone.Set() method to indicate that the entire response is present in ResponseData.


    It is critical that all network streams are closed. If you do not close each request and response stream, your application will run out of connections to the server and be unable to process additional requests.

using System;
using System.Net;
using System.Threading;
using System.Text;
using System.IO;

// The RequestState class passes data across async calls.
public class RequestState
   const int BufferSize = 1024;
   public StringBuilder RequestData;
   public byte[] BufferRead;
   public WebRequest Request;
   public Stream ResponseStream;
   // Create Decoder for appropriate enconding type.
   public Decoder StreamDecode = Encoding.UTF8.GetDecoder();
   public RequestState()
      BufferRead = new byte[BufferSize];
      RequestData = new StringBuilder(String.Empty);
      Request = null;
      ResponseStream = null;

// ClientGetAsync issues the async request.
class ClientGetAsync 
   public static ManualResetEvent allDone = new ManualResetEvent(false);
   const int BUFFER_SIZE = 1024;

   public static void Main(string[] args) 
      if (args.Length < 1) 

      // Get the URI from the command line.
      Uri httpSite = new Uri(args[0]);

      // Create the request object.
      WebRequest wreq = WebRequest.Create(httpSite);
      // Create the state object.
      RequestState rs = new RequestState();

      // Put the request into the state object so it can be passed around.
      rs.Request = wreq;

      // Issue the async request.
      IAsyncResult r = (IAsyncResult) wreq.BeginGetResponse(
         new AsyncCallback(RespCallback), rs);

      // Wait until the ManualResetEvent is set so that the application 
      // does not exit until after the callback is called.


   public static void showusage() {
      Console.WriteLine("Attempts to GET a URL");
      Console.WriteLine("   ClientGetAsync URL");
      Console.WriteLine("   Example:");
      Console.WriteLine("      ClientGetAsync");

   private static void RespCallback(IAsyncResult ar)
      // Get the RequestState object from the async result.
      RequestState rs = (RequestState) ar.AsyncState;

      // Get the WebRequest from RequestState.
      WebRequest req = rs.Request;

      // Call EndGetResponse, which produces the WebResponse object
      //  that came from the request issued above.
      WebResponse resp = req.EndGetResponse(ar);         

      //  Start reading data from the response stream.
      Stream ResponseStream = resp.GetResponseStream();

      // Store the response stream in RequestState to read 
      // the stream asynchronously.
      rs.ResponseStream = ResponseStream;

      //  Pass rs.BufferRead to BeginRead. Read data into rs.BufferRead
      IAsyncResult iarRead = ResponseStream.BeginRead(rs.BufferRead, 0, 
         BUFFER_SIZE, new AsyncCallback(ReadCallBack), rs); 

   private static void ReadCallBack(IAsyncResult asyncResult)
      // Get the RequestState object from AsyncResult.
      RequestState rs = (RequestState)asyncResult.AsyncState;

      // Retrieve the ResponseStream that was set in RespCallback. 
      Stream responseStream = rs.ResponseStream;

      // Read rs.BufferRead to verify that it contains data. 
      int read = responseStream.EndRead( asyncResult );
      if (read > 0)
         // Prepare a Char array buffer for converting to Unicode.
         Char[] charBuffer = new Char[BUFFER_SIZE];
         // Convert byte stream to Char array and then to String.
         // len contains the number of characters converted to Unicode.
      int len = 
         rs.StreamDecode.GetChars(rs.BufferRead, 0, read, charBuffer, 0);

         String str = new String(charBuffer, 0, len);

         // Append the recently read data to the RequestData stringbuilder
         // object contained in RequestState.
            Encoding.ASCII.GetString(rs.BufferRead, 0, read));         

         // Continue reading data until 
         // responseStream.EndRead returns –1.
         IAsyncResult ar = responseStream.BeginRead( 
            rs.BufferRead, 0, BUFFER_SIZE, 
            new AsyncCallback(ReadCallBack), rs);
            //  Display data to the console.
            string strContent;                  
            strContent = rs.RequestData.ToString();
         // Close down the response stream.
         // Set the ManualResetEvent so the main thread can exit.
© 2015 Microsoft