Click here to Skip to main content
13,405,390 members (57,914 online)
Click here to Skip to main content
Add your own
alternative version


152 bookmarked
Posted 19 Jul 2002

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

Questionhey Dear Pin
Sama'a201226-Oct-12 21:36
memberSama'a201226-Oct-12 21:36 
GeneralNice Article Pin
Member 88425112-Jan-08 23:10
memberMember 88425112-Jan-08 23:10 
GeneralRe: Nice Article Pin
ddarko10011-Sep-09 11:23
memberddarko10011-Sep-09 11:23 
GeneralThanks! Pin
Seansms4-Jan-08 12:46
memberSeansms4-Jan-08 12:46 2.0 compatibility - Access Violation Exception Pin
connexion24-Jun-07 7:06
memberconnexion24-Jun-07 7:06 
QuestionResume? Pin
tomsmaily1236-Sep-06 12:32
membertomsmaily1236-Sep-06 12:32 
AnswerRe: Resume? Pin
Ray Hayes6-Sep-06 13:23
memberRay Hayes6-Sep-06 13:23 
GeneralInvokeRequired not handled properly, might be causing the OutOfMemoryException. Pin
cpark0311-Nov-05 5:55
membercpark0311-Nov-05 5:55 
GeneralRetrieving a list of Directories from a URL Pin
Leon v Wyk21-Oct-05 7:09
memberLeon v Wyk21-Oct-05 7:09 
GeneralRe: Retrieving a list of Directories from a URL Pin
Ray Hayes22-Oct-05 1:08
memberRay Hayes22-Oct-05 1:08 
GeneralExcellent Article Pin
Ryan Bost10-Oct-05 12:23
memberRyan Bost10-Oct-05 12:23 
GeneralProblems with proxy Pin
AlesBoldrik8-Aug-05 3:40
memberAlesBoldrik8-Aug-05 3:40 
GeneralRe: Problems with proxy Pin
Anonymous8-Aug-05 7:55
sussAnonymous8-Aug-05 7:55 
GeneralRe: Problems with proxy Pin
n_dru15-Oct-07 23:03
membern_dru15-Oct-07 23:03 
GeneralBeginInvoke Pin
M.C.K.8-Jun-05 1:49
memberM.C.K.8-Jun-05 1:49 
GeneralRe: BeginInvoke Pin
Ray Hayes8-Jun-05 2:01
memberRay Hayes8-Jun-05 2:01 
QuestionHow to implement with Compact Framework? Pin
TravisSmith23-Feb-05 23:27
memberTravisSmith23-Feb-05 23:27 
AnswerRe: How to implement with Compact Framework? Pin
Ray Hayes23-Feb-05 23:49
memberRay Hayes23-Feb-05 23:49 
QuestionFilename? Pin
TyronX8-Jan-05 13:23
memberTyronX8-Jan-05 13:23 
AnswerRe: Filename? Pin
Ray Hayes9-Jan-05 7:26
memberRay Hayes9-Jan-05 7:26 
GeneralRe: Filename? Pin
TyronX10-Jan-05 9:39
memberTyronX10-Jan-05 9:39 
AnswerRe: Filename? Pin
wefra29-Oct-05 21:00
memberwefra29-Oct-05 21:00 
GeneralRe: Filename? Pin
Daltonic2-Nov-05 2:01
memberDaltonic2-Nov-05 2:01 
GeneralDownload file from FTP site Pin
Casp14-Dec-04 5:18
memberCasp14-Dec-04 5:18 
GeneralXcelent Article: Some Improvement Suggestions Pin
Shay Ben-Sasson4-Dec-04 0:02
memberShay Ben-Sasson4-Dec-04 0:02 

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 | Terms of Use | Mobile
Web03 | 2.8.180221.1 | Last Updated 20 Jul 2002
Article Copyright 2002 by Ray Hayes
Everything else Copyright © CodeProject, 1999-2018
Layout: fixed | fluid