dougzuck.com

This is the simplest way to execute work in a separate thread and have it report back to the UI thread

When you’re creating a Windows Form Application using Visual C# 2008, there are some tricky threading issues that need to be dealt with in order to keep your application running smoothly.  Specifically, you have to be very aware of how your application does work.  If you simply create a worker function and then call it, it’s going to execute in the current thread, which is also the thread that’s handling the user interface.  The result really stinks because your UI will completely lock up until the worker thread is finished executing.  This is unacceptable in nearly all situations.

I want to show you what I believe is the absolute simplest way for executing a worker function in a separate thread while still allowing that separate thread to send information back to the main UI thread, whether it be to update a text box, a label, or a field in a datagridview.

In this example we’re going to click a button to launch our worker function, which will count from 1 to 15.  Our user interface will display each number as it counts. 

Also, please pardon the fact that I use ‘function’ and ‘method’ interchangeably in this post.  Technically, I should just be saying ‘method,’ but ‘function’ always slips out.

Download the entire Visual Studio project here: UI_Threading_Example_CSharp.zip

Let’s take a look at the code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

using System;
using System.Windows.Forms;
using System.Threading;
 
namespace UI_Threading_Example
{
    //declare the delegate that we'll use to launch our worker function in a separate thread
    public delegate void workerFunctionDelegate(int totalSeconds);
 
    //declare the delegate that we'll use to call the function that displays text in our text box
    public delegate void poplateTextBoxDelegate(string text);
 
    public partial class Form1 : Form
    {
       public Form1()
       {
          InitializeComponent();
       }
 
       //this function will simply write text to our text box
       //this function will later be called from a worker thread through the use of a delegate using the Invoke method on the form
       void populateTextBox(string text)
       {
          textBox1.Text = textBox1.Text + " " + text;
       }
 
       //this function simulates "work" by simply counting from 1 to totalSeconds
       void workerFunction(int totalSeconds)
       {
          for (int count = 1; count <= totalSeconds ; count++)
          {
             //we use this.Invoke to send information back to our UI thread with a delegate
             //if we were to try to access the text box on the UI thread directly from a different thread, there would be problems
             this.Invoke(new poplateTextBoxDelegate(populateTextBox), new object[] { count.ToString() });
             Thread.Sleep(1000);
          }
       }   
 
       //this function is executed when we click the first button in the windows form
       //this is the PROPER WAY to do work in a UI situation
       //the worker function is launched in a separate thread so that our UI will remain responsive while it does work
       private void buttonNewThread_Click(object sender, EventArgs e)
       {
          workerFunctionDelegate w = workerFunction;
          w.BeginInvoke(15, null, null);
       }
 
       //this function is executed when we click the second button in the windows form
       //it's an example of WHAT NOT TO DO because if we click this button
       //the UI will become completely unresponsive for 15 seconds while the worker fucntion is executed
       private void buttonCurrentThread_Click(object sender, EventArgs e)
       {
          workerFunction(15);
       }
 }

OK, so here’s what we’ve got.  In Visual Studio (I’m using Visual C# 2008) I’ve created a new Windows Form Application and then in the designer window I added a text box (called textBox1) plus two buttons (called buttonNewThread and buttonCurrentThread).

In the code window I created two functions:

1
2

void populateTextBox(string text)
void workerFunction(int totalSeconds)

plus a delegate for each function:

1
2

public delegate void poplateTextBoxDelegate(string text);
public delegate void workerFunctionDelegate(int totalSeconds);

The first function is responsible for writing text to our text box.  The second function is responsible for doing “work,” which in this case is just counting from 1 to 15 and calling the function (using a delegate) to display the count in our text box.  Additionally there are two other functions (buttonCurrentThread_Click and buttonNewThread_Click) which handle the button clicks from our UI:

What’s the deal with delegates in this example?

In order to launch a worker function in a separate thread we have to declare a delegate for that function.  The delegate declaration must be outside the class declaration, and the delegate for each function must have the same format as the function that it’s going to be used to call.  So for example, if your worker function has 3 parameters, your delegate must also have 3 parameters.  And in this example, we not only need a delegate to handle launching our worker function in a new thread, but we also need to declare a delegate that we’ll use from within the worker thread to call a function to update the text box on the UI thread.  It is NOT ok to try to update a text box in the UI from a different thread without the use of a delegate.  If you don’t believe me then give it a shot and you’ll see for yourself that the results are funky.

The WRONG way to execute the worker function (using the UI thread)

When you click the button to execute the worker function in the current thread, which is the same thread that handles the UI, then you’ll see that for 15 seconds you can’t do anything with the UI or even move the form window to a new location.  At the end of 15 seconds the UI becomes responsive again and you see a “15″ in the text box.

1
2
3
4
5

//This is the WRONG way to do it
private void buttonCurrentThread_Click(object sender, EventArgs e)
{
   workerFunction(15);
}

The RIGHT way to execute the worker function (using a separate thread)

When you click the button to execute the worker function in a new thread, you watch the count from 1 to 15 displayed in the text box and the UI is not frozen.

Note that the null values are required by the BeginInvoke method.  If you have a function that requires more than one parameter, you would still pass all your parameters in first, followed by the two nulls.  In this example we’re effectively passing the value 15 to the worker function which will then execute for 15 seconds.

1
2
3
4
5
6

//This is the RIGHT way to do it
private void buttonNewThread_Click(object sender, EventArgs e)
{
   workerFunctionDelegate w = workerFunction;
   w.BeginInvoke(15, null, null);
}

The proper way to update the text box in the UI from the worker thread using the Invoke method of the main form

The format can definitely get a little confusing, but hopefully you can follow along and mimic it for your application.  Instead of accessing the text box directly from the worker thread, which will cause problems, we instead invoke a method (using a delegate) that accesses the text box. Note that our populateTextBox function has one parameter, which is a string.  We want to write the current count to the text box using that function, so we have to convert it to a string.  If we were passing multiple variables to the populateTextBox function, the format would still look the same, and we’d simply separate the variables inside the curly braces by a comma.

1
2
3
4
5
6
7
8
9

//update the text box by using a delegate to call a function on the UI thread that will do the update
void workerFunction(int totalSeconds)
{
   for (int count = 1; count <= totalSeconds ; count++)
      {
         this.Invoke(new poplateTextBoxDelegate(populateTextBox), new object[] { count.ToString() });
         Thread.Sleep(1000);
      }
}