Click here to Skip to main content
13,797,945 members
Click here to Skip to main content
Add your own
alternative version


152 bookmarked
Posted 19 Jul 2002
Licenced CPOL

Threaded WebDownload class with Progress Call-backs

, 19 Jul 2002
Rate this:
Please Sign up or sign in to vote.
Implementation of a C# class that performs an asynchronous download of a file (over HTTP) providing call-backs with progress and when complete.

Download in progress


Ever wanted your application to download something from the Internet? Here is an implementation of a C# class that performs an asynchronous download of a file (over HTTP) providing call-backs for both progress and to indicate when the download is complete.


Recently I needed my application to be able to retrieve a graphic from a web-server. During the download the rest of the application should still operate with full functionality. Typically a placeholder graphic being used until the download had completed. As soon as the download is complete, the newly downloaded graphic would be used rather than the placeholder.

Because the interface can look a little weird until all the downloads are complete, the user really needs to be aware that this is something that will be rectified after the download is complete.

Framework Provided Solutions

Since .Net operates within a rich framework, there is a good chance that Microsoft have already provided a number of different classes to help:

The WebRequest and HttpWebResponse classes allows a really simple download function to be implemented in just a few lines of code. Indeed, the following code worked for a while:

public Image GetImage(string urlFile)
    WebRequest wreq = WebRequest.Create( urlFile );
    HttpWebResponse httpResponse = (HttpWebResponse) wreq.GetResponse();
    Stream stream = httpResponse.GetResponseStream();
    return Image.FromStream(stream);

The problem with the above code was that with a large download or a slow web-site, the GetImage function above both locks the main application thread of my program and provides no download progress to the user. Obviously, there were still some options:

  • Use a new thread to perform the download, thus leaving my main thread free to work;
  • Use the Asynchronous stream mechanisms;

Existing Implementations

I found a couple of VB.NET examples that implemented the Asynchronous download of the file, however they still had some problems:

  1. After starting the asynchronous download, they had to wait at a ManualResetEvent to await the download to complete;
  2. They did not display any download progress;
  3. The used the StringBuilder class to store the download.

The final point was my biggest problem, with the conversion from bytes to chars would render the download pointless, trimming out important information from the download making construction of the image impossible.

My Requirements

  1. Shall not block operation with application (including its functionality, not simply the user-interface);
  2. Shall be capable of providing some progress indication;
  3. Shall notify when the download is complete;
  4. Shall preserve all of the downloaded information;
  5. Shall cope with unknown file sizes (Note, all information is stored in memory, so there is a limit to file sizes);

The Solution

Shown below are the classes implemented to satisfy my requirements above.

The DownloadThread class simply wraps my download thread and provides a logical place to store the DownloadCompleteHandler. It is also responsible for instantiating the WebDownload class and calling its Download method.

The DownloadInfo class is a simple class storing the download information, this information can be passed around within the asynchronous calls, providing access to the overall download (not just the snip that the call-back is informed).

The WebDownload class wraps the asynchronous download functionality with two call-backs,

  • Download is the main function, it initiates the download and then waits for the download to complete. Depending on what type of buffers are used, this function may also construct a byte[] return type from the working buffer;
  • ResponseCallback is called by the .Net Framework when the initial response from the web-server has been received. At this point, it is possible to look at the HTTP headers and determine if the web-server has specified the size of the file. If so, a byte array (byte[]) is created of the correct size. This is flagged in the DownloadInfo class with useFastBuffers set to true. If the file size is not known, slow buffers are used (which is a System.Collection.ArrayList allowing the contents to grow during the download);
  • ReadCallback is called whenever the read-buffer (set to 1k) fills up, at this point, the master-buffer gains this new read-buffer and the progress call-back is called.


The included tester application simply uses the following to start a download.

if ( this.downloadUrlTextBox.Text != "" )
  this.outputGroupBox.Enabled = true;

  // Initialize all form information
  this.bytesDownloadedTextBox.Text = "";
  this.totalBytesTextBox.Text = "";
  this.progressBar.Minimum = 0;
  this.progressBar.Maximum = 0;
  this.progressBar.Value = 0;

  // Create the download thread (class) and populate with filename and callbacks
  DownloadThread dl = new DownloadThread();
  dl.DownloadUrl = this.downloadUrlTextBox.Text;
  dl.CompleteCallback += new DownloadCompleteHandler( DownloadCompleteCallback );
  dl.ProgressCallback += new DownloadProgressHandler( DownloadProgressCallback );

  // Start the download thread....
  System.Threading.Thread t = new System.Threading.Thread( 
    new System.Threading.ThreadStart(
      dl.Download ));

The tester application also changes its appearance slightly when the progress call-back indicates that the total file size is unknown. It hides the progress bar and places "Total File Size Not Known" within the Total Bytes display. The Bytes Downloaded display still counts up with the progress so far.

Known Issues

An OutOfMemoryException is raised when very large files are downloaded (40Mb caused it in my case, although this corresponded with my system running out of virtual memory).


Currently, this class exists within quite a safe environment. It is hoped that by sharing the code here, not only will others benefit from my efforts but also, with wider testing, any bugs can be discovered sooner.


These classes have been developed for a prototype application only, if you use them, it is your responsibility to test them against your requirements.


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Ray Hayes
Product Manager
United Kingdom United Kingdom
No Biography provided

You may also be interested in...


Comments and Discussions

GeneralRe: Where is the downloaded file? Pin
fredza7-Dec-04 8:57
memberfredza7-Dec-04 8:57 
GeneralInvoke required for gui Pin
Johnno20-Jul-03 22:45
memberJohnno20-Jul-03 22:45 
GeneralRe: Invoke required for gui Pin
tabatabaye23-Feb-04 19:48
membertabatabaye23-Feb-04 19:48 
GeneralKristian Pin
kriki29-Jun-03 23:55
memberkriki29-Jun-03 23:55 
QuestionSeveral Threads ? Pin
Marc Schneider11-Jun-03 9:42
memberMarc Schneider11-Jun-03 9:42 
AnswerRe: Several Threads ? Pin
Ray Hayes11-Jun-03 23:47
memberRay Hayes11-Jun-03 23:47 
GeneralRe: Several Threads ? Pin
Anonymous12-Jun-03 0:58
memberAnonymous12-Jun-03 0:58 
GeneralRe: Several Threads ? Pin
Ray Hayes12-Jun-03 1:16
memberRay Hayes12-Jun-03 1:16 
GeneralRe: Several Threads ? Pin
Marc Schneider12-Jun-03 7:43
memberMarc Schneider12-Jun-03 7:43 
GeneralRe: Several Threads ? Pin
Jeffrey Scott Flesher9-Feb-04 10:02
memberJeffrey Scott Flesher9-Feb-04 10:02 
GeneralRe: Several Threads ? Pin
Ray Hayes9-Feb-04 22:57
memberRay Hayes9-Feb-04 22:57 
GeneralRe: Several Threads ? Pin
Jeffrey Scott Flesher10-Feb-04 7:55
memberJeffrey Scott Flesher10-Feb-04 7:55 
GeneralRe: Several Threads ? Pin
Ray Hayes12-Feb-04 0:15
memberRay Hayes12-Feb-04 0:15 
GeneralRe: Several Threads ? Pin
jeroenvw8-Jun-04 3:49
memberjeroenvw8-Jun-04 3:49 
AnswerRe: Several Threads ? Pin
James T. Johnson25-Jun-03 1:59
memberJames T. Johnson25-Jun-03 1:59 
GeneralRe: Several Threads ? Pin
Ray Hayes25-Jun-03 5:46
memberRay Hayes25-Jun-03 5:46 
GeneralThreaded Upload Pin
Vasudevan Deepak Kumar19-May-03 22:04
memberVasudevan Deepak Kumar19-May-03 22:04 
GeneralRe: Threaded Upload Pin
Ray Hayes20-May-03 8:36
memberRay Hayes20-May-03 8:36 
Generalchange the port Pin
AlexGnauck2-Apr-03 20:29
memberAlexGnauck2-Apr-03 20:29 
GeneralRe: change the port Pin
Ray Hayes2-Apr-03 22:51
memberRay Hayes2-Apr-03 22:51 
QuestionResume Feature? Pin
Anonymous10-Jan-03 9:33
memberAnonymous10-Jan-03 9:33 
QuestionWhy don't just use HttpWebRequest.BeginGetResponse and HttpWebRequest.EndGetResponse? Pin
Anonymous8-Nov-02 21:32
memberAnonymous8-Nov-02 21:32 
Questionwhy? Pin
Anonymous22-Jul-02 7:08
memberAnonymous22-Jul-02 7:08 
AnswerRe: why? Pin
Soliant23-Jul-02 17:33
memberSoliant23-Jul-02 17:33 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web02 | 2.8.181207.3 | Last Updated 20 Jul 2002
Article Copyright 2002 by Ray Hayes
Everything else Copyright © CodeProject, 1999-2018
Layout: fixed | fluid