The first step is to create a new BackgroundWorker object, specify the appropriate settings, and rig the instance up with event handlers. Table 37.1 shows the important members of the BackgroundWorker class.

You can create BackgroundWorker programmatically or by dragging it onto your form from the Components tab of the Visual Studio toolbox. The example in this chapter shows programmatic instantiation and configuration. The following code shows how to instantiate the BackgroundWorker.

backgroundWorker = new BackgroundWorker();
backgroundWorker.WorkerReportsProgress = true;
backgroundWorker.WorkerSupportsCancellation = true;

backgroundWorker.DoWork += new DoWorkEventHandler(backgroundWorker_DoWork);

backgroundWorker.ProgressChanged += new ProgressChangedEventHandler
(backgroundWorker_ProgressChanged);

backgroundWorker.RunWorkerCompleted += new RunWorkerCompletedEventHandler
(backgroundWorker_RunWorkerCompleted);

The DoWork event provides an instance of DoWorkEventArgs as a parameter, which handles the input, output, and cancellation properties of the worker thread. Table 37.2 shows the properties of DoWorkEventArgs.

The following code shows the implementation behind the DoWork event for the Fibonacci calculator. Notice the exception that is thrown when the compute number has an invalid value. This is because any values higher than 91 will result in an overflow with the long data type.

private void backgroundWorker_DoWork(object sender, DoWorkEventArgs e)
{
    if (((int)e.Argument < 0) || ((int)e.Argument > 91))
    {
        throw new ArgumentException("Compute number must be >= 0 and <= 91");
    }
    e.Result = ComputeFibonacci((int)e.Argument, (BackgroundWorker)sender, e);
}

The following code shows the actual processing logic behind the Fibonacci calculations. This logic is in its own method because it calculates the numbers using recursion.

private long ComputeFibonacci(int computeNumber,
                              BackgroundWorker worker,
                              DoWorkEventArgs e)
{
     long result = 0;
     if (worker.CancellationPending)
     {
         e.Cancel = true;
     }
     else
     {
         if (computeNumber < 2)
         {
             result = 1;
         }
         else
         {
             result = ComputeFibonacci(computeNumber - 1, worker, e) +
                      ComputeFibonacci(computeNumber - 2, worker, e);
         }
         int percentComplete = (int)((float)computeNumber /
                                                  (float)((int)e.Argument) * 100);
         if (percentComplete > percentageReached)
         {
             percentageReached = percentComplete;
             worker.ReportProgress(percentComplete);
         }
     }
     return result;
}

The ProgressChanged is used to report status to the user interface. This event is fired whenever the ReportProgress method is invoked.

The PercentageProgress property of the ProgressChanged event arguments will return the percentage completed value, set by the ReportProgress method. You can also access the user state within the ProgressChanged event handler arguments. The following code shows the implementation details for the progress changed event.

private void backgroundWorker_ProgressChanged(object sender,
ProgressChangedEventArgs e)
{
    OperationProgressBar.Value = e.ProgressPercentage;
    ResultLabel.Text = String.Format("Calculating: {0}%",
                                      e.ProgressPercentage.ToString());
}

BackgroundWorker events are not marshaled across AppDomain boundaries; therefore you must not use BackgroundWorker to process tasks in more than one AppDomain. You must be careful not to manipulate the user interface in your DoWork event handler. The proper way is to communicate with the user interface through the ProgressChanged and RunWorkerCompleted events.

Allowing the user to cancel the progressing task is extremely easy. Just invoke the CancelAsync method on the BackgroundWorker instance and then handle the CancellationPending property in the DoWork event appropriately.

private void CancellationButton_Click(object sender, EventArgs e)
{
    backgroundWorker.CancelAsync();
    CancellationButton.Enabled = false;
}

BackgroundWorker executes the DoWork event in a separate thread so the user interface remains responsive. Executing the worker thread is very easy; it’s done by invoking the RunWorkerAsync method on the BackgroundWorker. This method optionally allows you to pass in an argument that the worker logic can use during processing. The following code shows the implementation details behind the demo that is available on the Companion Web site for this book.

private void ComputeButton_Click(object sender, EventArgs e)
{
    ResultLabel.Text = string.Empty;
    ComputeNumberField.Enabled = false;
    ComputeButton.Enabled = false;
    CancellationButton.Enabled = true;
    int computeNumber = (int)ComputeNumberField.Value;
    percentageReached = 0;
    backgroundWorker.RunWorkerAsync(computeNumber);
}

No matter how the DoWork event completes, whether successfully or in an erroneous manner, the RunWorkerCompleted event will always fire, providing an instance of RunWorkerCompletedEventArgs that contains the status and result of the operation. This event will allow you to respond appropriately to whatever result is returned by the worker thread. When an error occurs, you can retrieve the exception object from the Error property. This property will be null if no errors occurred during processing. When a cancellation occurs at the request of the user, the Cancellation property will be set to true. Otherwise, you can retrieve the result from the Result property if there is one. The following code shows the completed event handler that is fired when the processing task is finished.

private void backgroundWorker_RunWorkerCompleted(object sender,
                                                   RunWorkerCompletedEventArgs e)
{
    if (e.Error != null)
    {
        ResultLabel.Text = String.Format("Error: {0}", e.Error.Message);
    }
    else if (e.Cancelled)
    {
        ResultLabel.Text = "Cancelled";
    }
    else
    {
        ResultLabel.Text = e.Result.ToString();
    }
    ComputeNumberField.Enabled = true;
    ComputeButton.Enabled = true;
    CancellationButton.Enabled = false;
}

Creating a user interface that is responsive is not that difficult, provided that you know the techniques required to do so. Your code must divide time between processing a long-running task and interacting with the user; one should not be sacrificed for the other. You cannot think in a linear fashion when building a long-running task; your application cannot wait around for the task to complete. Think about a good place in the processing logic to stop and report status back to the user. Thankfully, you do not have to worry about processing application events while using the BackgroundWorker object, because this is done behind the scenes for you.

Figure 37.1 shows a screenshot of the demo application provided on the Companion Web site.

Figure 37.1. Screenshot of the demo application on the Web site.

Asynchronous processing can drastically improve the responsiveness of your application. However, do not assume that an asynchronous model is always the best approach; sometimes a synchronous model is a better choice. Thankfully, .NET 2.0 simplifies the tasks related to using either execution model.