Using Task Instead of BackgroundWorker to Update UI

The BackgroundWorker component allows for convenient access to a thread. It supports

• Reporting Progress
• Error Handling
• Returning a Result
• Cancellation

Updating the UI is a common action in GUI applications that perform a time consuming task. A background worker allows for a simple implementation of updating the UI thread and for the UI thread to control the background worker.

A Task is another way to implement a separate worker thread. I will demonstrate how to transform all the actions performed in a background worker into the context of a Task.

I have used the following resources for Tasks

• async-and-await.html 
• async-in-4-5-enabling-progress-and-cancellation-in-async-apis/
• http://www.jeremybytes.com/Downloads.aspx#Tasks
• task-and-await-consuming-awaitable.html

The example I am using is from the Windows Forms 2.0 book by Chris Sells.

Calculate Pi Example

 The calculations for Pi are a mystery, but they take time.

    void CalcPi(int digits) {
      StringBuilder pi = new StringBuilder("3", digits + 2);

      if( digits > 0 ) {
        pi.Append(".");
     
        for( int i = 0; i < digits; i += 9 ) {
          int nineDigits = NineDigitsOfPi.StartingAt(i + 1);
          int digitCount = Math.Min(digits - i, 9);
          string ds = string.Format("{0:D9}", nineDigits);
          pi.Append(ds.Substring(0, digitCount));
      }
    }

A method encapsulates access to the UI.

    void ShowProgress(string pi, int totalDigits, int digitsSoFar) {
      // Display progress in UI
      this.resultsTextBox.Text = pi;
      this.calcToolStripProgressBar.Maximum = totalDigits;
      this.calcToolStripProgressBar.Value = digitsSoFar;
    }
 
A custom class is used to encapsulate data that is passed to the UI.

    class CalcPiUserState {
      public readonly string Pi;
      public readonly int TotalDigits;
      public readonly int DigitsSoFar;

      public CalcPiUserState(string pi, int totalDigits, int digitsSoFar) {
        this.Pi = pi;
        this.TotalDigits = totalDigits;
        this.DigitsSoFar = digitsSoFar;
      }
    }

Helper methods are used to control modify the appearance of the UI.

        void SetUIReady()
        {
            // Reset progress UI
            this.calcToolStripStatusLabel.Text = "Ready";
            this.calcToolStripProgressBar.Visible = false;
        }

        void SetUIBusy()
        {
            // Set calculating UI
            this.calcToolStripProgressBar.Visible = true;
            this.calcToolStripStatusLabel.Text = "Calculating...";
        }

Starting a Worker Thread that Reports Progress

BackgroundWorker

Handle the DoWork event

    void backgroundWorker_DoWork(object sender, DoWorkEventArgs e) {
        CalcPi((int)e.Argument);
    }

Set  WorkerSupportsProgress property
Handle ReportProgress event

    void backgroundWorker_ProgressChanged(object sender, ProgressChangedEventArgs e) {
      // Show progress
      CalcPiUserState progress = (CalcPiUserState)e.UserState;
      ShowProgress(
        progress.Pi, progress.TotalDigits, progress.DigitsSoFar);
    }

Call RunWorkerAsync

    void calcButton_Click(object sender, EventArgs e) {
      SetUIBusy();

      // Begin calculating pi asynchronously
      this.backgroundWorker.RunWorkerAsync(
        (int)this.decimalPlacesNumericUpDown.Value);
    }

 Handle RunWorkerCompleted event

    void backgroundWorker_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e)
   {
       SetUIReady();  
   }

Modify the CalcPi method so that it reports progress regularly.

    void CalcPi(int digits) {
      StringBuilder pi = new StringBuilder("3", digits + 2);

      CalcPiUserState state = new CalcPiUserState(pi.ToString(), digits, 0);
      // Report initial progress
      this.backgroundWorker.ReportProgress(0, state);

      if( digits > 0 ) {
        pi.Append(".");

        for( int i = 0; i < digits; i += 9 ) {
          int nineDigits = NineDigitsOfPi.StartingAt(i + 1);
          int digitCount = Math.Min(digits - i, 9);
          string ds = string.Format("{0:D9}", nineDigits);
          pi.Append(ds.Substring(0, digitCount));

          // Report continuing progress
          state = new CalcPiUserState(pi.ToString(), digits, i + digitCount);
          this.backgroundWorker.ReportProgress(0, state);

          // Check for cancelation
          if (this.backgroundWorker.CancellationPending) { return; }         
        }
      }
    }

Task

Create a helper method to update the UI from the custom state class.

        void ShowProgressState(CalcPiUserState state)
        {
            try
            {
                // Display progress in UI
                this.resultsTextBox.Text = state.Pi;
                this.calcToolStripProgressBar.Maximum = state.TotalDigits;
                this.calcToolStripProgressBar.Value = state.DigitsSoFar;
            }
            catch (Exception e)
            {
                Console.WriteLine("{0} in ShowProgressState", e.Message);
                throw e;
            }
        }

Create a method with return type Task that encapsulates the work. In order to report progress, create an Progress delegate with an Action that reports progress. CalcPiWithProgress is CPU-bound, so call it with Task.Run. The async keyword in the signature means that await is a keyword in the body of the method.

        async Task DoWork()
        {
            //Any method that is an Action, has one parameter of the gerenic type and returns void.
            Action actionProgress = ShowProgressState;
            //The Action and the Progress must have the same generic type.
            IProgress progress = new Progress(actionProgress);
            await Task.Run(() => CalcPiWithProgress(
                  (int)this.decimalPlacesNumericUpDown.Value, progress)
                );

        }

Start task. The await keyword causes the method to start asynchronously. When the thread completes, the code after the await will be run in the same thread context. The handler does not block: SetUIReady is called, but only after the thread completes, and well after the handler completes.

        async void calcButton_Click(object sender, EventArgs e)
        {
            SetUIBusy();

            // Begin calculating pi asynchronously
            await DoWork();

            SetUIReady();
        }

A special method is not needed to catch the completion of the thread, as with a background worker.

Modify the CalcPi method so it reports progress.

    void CalcPiWithProgress(int digits, IProgress progress,) {
      StringBuilder pi = new StringBuilder("3", digits + 2);

      CalcPiUserState state = new CalcPiUserState(pi.ToString(), digits, 0);
      // Report initial progress
      if (progress != null)
                progress.Report(state);

      if( digits > 0 ) {
        pi.Append(".");

        for( int i = 0; i < digits; i += 9 ) {
          int nineDigits = NineDigitsOfPi.StartingAt(i + 1);
          int digitCount = Math.Min(digits - i, 9);
          string ds = string.Format("{0:D9}", nineDigits);
          pi.Append(ds.Substring(0, digitCount));

          // Report continuing progress
          state = new CalcPiUserState(pi.ToString(), digits, i + digitCount);
          if (progress != null)
                progress.Report(state);  
        }
      }
    }

Catch Exceptions

Background Worker

Test the Error property in the RunWorkerCompletedEventArgs in the RunWorkerCompleted handler.

void backgroundWorker_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e) {
  
      SetUIReady();

      // Was there an error?
      if( e.Error != null ) {
        this.resultsTextBox.Text = e.Error.Message;
        return;
      }

    }

Task 

With Task, the code after the await is run on the UI thread. The code after the await is executed after the thread completes. The handler would have completed long ago.

Catch the exception and reset the UI.

        async void calcButton_Click(object sender, EventArgs e)
        {
            try
            {
                SetUIBusy();

                // Begin calculating pi asynchronously
                await DoWork();

            }
            catch (Exception ex)
            {
                this.resultsTextBox.Text = ex.Message;
            }
            finally
            {
                SetUIReady();
            }
        }

Return a Result from the Thread 

Background Worker

Set the result of the thread in the DoWorkEventArgs in the DoWork handler.

  void backgroundWorker_DoWork(object sender, DoWorkEventArgs e) { 
      // Track start time
      DateTime start = DateTime.Now;

      CalcPi((int)e.Argument);     

      // Return elapsed time
      DateTime end = DateTime.Now;
      TimeSpan elapsed = end - start;
      e.Result = elapsed;
  }

Retrieve the result from the RunWorkerCompletedEventArgs in the RunWorkerCompleted handler.

void backgroundWorker_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e)
{
  
      SetUIReady();

      // e.Result will cause an error if the thread threw an exception
      if( e.Error != null ) {
        this.resultsTextBox.Text = e.Error.Message;
        return;
      }

      // Show elapsed time
      TimeSpan elapsed = (TimeSpan) e.Result;
      MessageBox.Show("Elapsed: " + elapsed.ToString());
}

Task 

Instead of using Task, use Task. The async command  changes the meaning of the method signature. It does not mean that the method returns Task, it means that the method has a call to await and returns type T.

        async Task DoWork()
        {
            // Track start time
            DateTime start = DateTime.Now;

            //Any method that is an Action, has one parameter of the gerenic type and returns void.
            Action actionProgress = ShowProgressState;
            //The Action and the Progress must have the same generic type.
            IProgress progress = new Progress(actionProgress);
            await Task.Run(() => CalcPiWithProgress(
                  (int)this.decimalPlacesNumericUpDown.Value, progress)
                );

            // Return elapsed time
            DateTime end = DateTime.Now;
            TimeSpan elapsed = end - start;
            return elapsed;
        }

The result will be assigned from the await command.

        async void calcButton_Click(object sender, EventArgs e)
        {
            try
            {
                SetUIBusy();

                // Begin calculating pi asynchronously
                TimeSpan elapsed = await DoWork();

                // Show elapsed time
                MessageBox.Show("Elapsed: " + elapsed.ToString());

            }
            catch (Exception ex)
            {
                this.resultsTextBox.Text = ex.Message;
            }
            finally
            {
                SetUIReady();
            }
        }

Adding the Ability to Cancel

Background Worker

Set the WorkerSupportsCancellation property

Signal that the thread should stop.

void calcButton_Click(object sender, EventArgs e) {
      // Don't process if cancel request pending
      // (Should not be called, since we disabled the button...)
      if( this.backgroundWorker.CancellationPending ) { return; }

      // If worker thread currently executing, cancel it
      if( this.backgroundWorker.IsBusy ) {
        this.calcButton.Enabled = false;
        this.backgroundWorker.CancelAsync();
        return;
      }

      SetUIBusy();

      // Begin calculating pi asynchronously
      this.backgroundWorker.RunWorkerAsync(
        (int)this.decimalPlacesNumericUpDown.Value);
    }

The thread monitors the flag for cancellation. When requested, the thread stops working.

  void CalcPi(int digits)
  {
      StringBuilder pi = new StringBuilder("3", digits + 2);

      CalcPiUserState state = new CalcPiUserState(pi.ToString(), digits, 0);
      // Report initial progress
      this.backgroundWorker.ReportProgress(0, state);

      // Check for cancelation
      if (this.backgroundWorker.CancellationPending) { return; }

      if( digits > 0 ) {
        pi.Append(".");

        for( int i = 0; i < digits; i += 9 ) {
          int nineDigits = NineDigitsOfPi.StartingAt(i + 1);
          int digitCount = Math.Min(digits - i, 9);
          string ds = string.Format("{0:D9}", nineDigits);
          pi.Append(ds.Substring(0, digitCount));

          // Report continuing progress
          state = new CalcPiUserState(pi.ToString(), digits, i + digitCount);
          this.backgroundWorker.ReportProgress(0, state);

          // Check for cancelation
          if (this.backgroundWorker.CancellationPending) { return; }         
        }
      }
    }

In the RunWorkerCompleted handler check the Cancelled property in the event args.

void backgroundWorker_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e) {
      // Reset progress UI
      this.calcButton.Text = "Calculate";
      this.calcButton.Enabled = true;
      this.calcToolStripStatusLabel.Text = "Ready";
      this.calcToolStripProgressBar.Visible = false;

      // Was the worker thread cancelled?
      if (e.Cancelled)
      {
          this.resultsTextBox.Text = "Cancelled";
      }
      else
      {
          // Show elapsed time
          TimeSpan elapsed = (TimeSpan)e.Result;
          MessageBox.Show("Elapsed: " + elapsed.ToString());
      }

Task

As the thread is asked to respond in more ways, it is useful separate the actions performed when the thread ends. As part of the Task class, use the Continue with to specify a method that has the format for Action. Action, Func and Func can also be configured. If the UI will be accessed, then continue from the current context.

        async void calcButton_Click(object sender, EventArgs e)
        {

            SetUIBusy();

            // Begin calculating pi asynchronously
            await DoWork().ContinueWith(WorkCompleted,
                TaskScheduler.FromCurrentSynchronizationContext());

        }




Many states of the task can be inspected. This version does the same as the earlier version of the application. Next, cancellation will be added.

        private void WorkCompleted(Task task)
        {
            switch (task.Status)
            {
                case TaskStatus.Canceled:
                    break;
                case TaskStatus.Faulted:
                    this.resultsTextBox.Text = task.Exception.ToString();
                    break;
                case TaskStatus.RanToCompletion:
                    MessageBox.Show("Elapsed: " + task.Result.ToString());
                    break;
                default:
                    break;
            }
            SetUIReady();
        }

For cancellation, CancellationTaskSource is used. It contains a token that can be set. The token can be monitored by the thread.

        CancellationTokenSource tokenSource;
        CancellationToken token;

        public MainForm() {
            InitializeComponent();
            tokenSource = new CancellationTokenSource();
            token = tokenSource.Token;
            SetUIReady();
        }

A new helper will be added to report progress and check for cancellation, with the ThrowIfCancellationRequested() method of the token.

        void ProgressTestCancel(
            IProgress progress, CancellationToken token, CalcPiUserState state)
        {
            // Report progress
            if (progress != null)
                progress.Report(state);
            token.ThrowIfCancellationRequested();    
        }

The worker thread reports progress and tests for cancellation at regular intervals.

    void CalcPiWithProgress(
          int digits, IProgress progress, CancellationToken token) 
   {
      StringBuilder pi = new StringBuilder("3", digits + 2);

      CalcPiUserState state = new CalcPiUserState(pi.ToString(), digits, 0);
      // Report initial progress
      ProgessTestCancel(progess, token, state);

      if( digits > 0 ) {
        pi.Append(".");

        for( int i = 0; i < digits; i += 9 ) {
          int nineDigits = NineDigitsOfPi.StartingAt(i + 1);
          int digitCount = Math.Min(digits - i, 9);
          string ds = string.Format("{0:D9}", nineDigits);
          pi.Append(ds.Substring(0, digitCount));

          // Report continuing progress
          state = new CalcPiUserState(pi.ToString(), digits, i + digitCount);
          ProgessTestCancel(progess, token, state); 
        }
      }
    }

Pass the token into the method that does the asynchronous work. The task will be needed in other parts of the application to improve the interaction of the UI, so the task is added as an instance variable. Does this remind you of background worker???

         //Needed in order to test if Task is busy in other methods
        Task piTask = null;
        async Task DoWork()
        {
            // Track start time
            DateTime start = DateTime.Now;

            //Any method that is an Action, has one parameter of the gerenic type and returns void.
            Action actionProgress = ShowProgressState;
            //The Action and the Progress must have the same generic type.
            IProgress progress = new Progress(actionProgress);
            piTask = new Task(() =>
                 TimePiThread(
                    (int)this.decimalPlacesNumericUpDown.Value, progress, tokenSource.Token)
                 , tokenSource.Token);
            piTask.Start();
            return await piTask;
         
        }

The button handler will have two possible states: ready to run, ready to cancel. Update the UI based on the state of the task. If the task is running, cancel it on click.

        async void calcButton_Click(object sender, EventArgs e)
        {
            // Don't process if cancel request pending
            // Should not happen, since button will be disabled
            if (this.tokenSource.IsCancellationRequested) { return; }

            if (piTask != null && !piTask.IsCompleted)
            {
                this.calcButton.Enabled = false;
                tokenSource.Cancel();
            }
            else
            {

                SetUIBusy();

                // Begin calculating pi asynchronously
                await DoWork().ContinueWith(WorkCompleted,
                    TaskScheduler.FromCurrentSynchronizationContext());
            }

        }

The helpers for updating the UI need modification, too:

        void SetUIReady()
        {
            // Reset progress UI
            this.calcToolStripStatusLabel.Text = "Ready";
            this.calcToolStripProgressBar.Visible = false;
            this.calcButton.Text = "Calculate";
            this.calcButton.Enabled = true;
        }

        void SetUIBusy()
        {
            // Set calculating UI
            this.calcToolStripProgressBar.Visible = true;
            this.calcButton.Text = "Cancel";
            this.calcToolStripStatusLabel.Text = "Calculating...";
        }

Conclusion

For updating the UI, I still like background worker. In large part, this is due to my understanding of background worker. Task is new to me. It has more power than background worker for other tasks, but background worker is tailored for interacting with the UI. While writing this article, I was frustrated multiple times with the syntax of lambda functions and the .NET delegates. Background worker hides the details, but allows all the necessary features for interacting with the UI.