Andy De George
c0ba284473
* Merge winforms framework content to working branch (#14) * Breadcrumb / TOC / Move net5 to net folder (#15) * change path from net5 to net * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Mess with bread/toc * Add .net 5 winforms placeholder article (#16) * added some metadata and adjusted net5 placeholder * corrections * corrections * corrections * Test1 * Swapping landing page vs concept * fix links * Fix links * Fix desc
5.4 KiB
title, ms.date, dev_langs, helpviewer_keywords, ms.assetid
| title | ms.date | dev_langs | helpviewer_keywords | ms.assetid | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| How to: Download a File in the Background | 03/30/2017 |
|
|
9b7bc5ae-051c-4904-9720-18f6667388bd |
How to: Download a File in the Background
Downloading a file is a common task, and it is often useful to run this potentially time-consuming operation on a separate thread. Use the xref:System.ComponentModel.BackgroundWorker component to accomplish this task with very little code.
Example
The following code example demonstrates how to use a xref:System.ComponentModel.BackgroundWorker component to load an XML file from a URL. When the user clicks the Download button, the xref:System.Windows.Forms.Control.Click event handler calls the xref:System.ComponentModel.BackgroundWorker.RunWorkerAsync%2A method of a xref:System.ComponentModel.BackgroundWorker component to start the download operation. The button is disabled for the duration of the download, and then enabled when the download is complete. A xref:System.Windows.Forms.MessageBox displays the contents of the file.
[!code-csharpSystem.ComponentModel.BackgroundWorker.IsBusy#1] [!code-vbSystem.ComponentModel.BackgroundWorker.IsBusy#1]
Downloading the file
The file is downloaded on the xref:System.ComponentModel.BackgroundWorker component's worker thread, which runs the xref:System.ComponentModel.BackgroundWorker.DoWork event handler. This thread starts when your code calls the xref:System.ComponentModel.BackgroundWorker.RunWorkerAsync%2A method.
[!code-csharpSystem.ComponentModel.BackgroundWorker.IsBusy#3] [!code-vbSystem.ComponentModel.BackgroundWorker.IsBusy#3]
Waiting for a BackgroundWorker to finish
The downloadButton_Click event handler demonstrates how to wait for a xref:System.ComponentModel.BackgroundWorker component to finish its asynchronous task.
If you only want the application to respond to events and do not want to do any work in the main thread while you wait for the background thread to complete, just exit the handler.
If you want to continue doing work in the main thread, use the xref:System.ComponentModel.BackgroundWorker.IsBusy%2A property to determine whether the xref:System.ComponentModel.BackgroundWorker thread is still running. In the example, a progress bar is updated while the download is processing. Be sure to call the xref:System.Windows.Forms.Application.DoEvents%2A?displayProperty=nameWithType method to keep the UI responsive.
[!code-csharpSystem.ComponentModel.BackgroundWorker.IsBusy#2] [!code-vbSystem.ComponentModel.BackgroundWorker.IsBusy#2]
Displaying the result
The backgroundWorker1_RunWorkerCompleted method handles the xref:System.ComponentModel.BackgroundWorker.RunWorkerCompleted event and is called when the background operation is completed. This method first checks the xref:System.ComponentModel.AsyncCompletedEventArgs.Error%2A?displayProperty=nameWithType property. If xref:System.ComponentModel.AsyncCompletedEventArgs.Error%2A?displayProperty=nameWithType is null, then this method displays the contents of the file. It then enables the download button, which was disabled when the download began, and it resets the progress bar.
[!code-csharpSystem.ComponentModel.BackgroundWorker.IsBusy#4] [!code-vbSystem.ComponentModel.BackgroundWorker.IsBusy#4]
Compiling the Code
This example requires:
- References to the System.Drawing, System.Windows.Forms, and System.Xml assemblies.
Robust Programming
Always check the xref:System.ComponentModel.AsyncCompletedEventArgs.Error%2A?displayProperty=nameWithType property in your xref:System.ComponentModel.BackgroundWorker.RunWorkerCompleted event handler before attempting to access the xref:System.ComponentModel.RunWorkerCompletedEventArgs.Result%2A?displayProperty=nameWithType property or any other object that may have been affected by the xref:System.ComponentModel.BackgroundWorker.DoWork event handler.