Accessing Controls from Worker Threads

[jmcilhinney]

VB version here.

While it is legal to access a control from threads other than the one it was created on, it is simply not a good idea. From VS 2005 onwards it is not allowed while debugging by default. Any call that accesses a control's Handle on a thread that does not own that handle will either fail or behave other than as expected. The way to safely access controls from worker threads is via delegation.

First you test the InvokeRequired property of the control, which will tell you whether or not you can safely access the control. InvokeRequired is one of the few members of the Control class that is thread-safe, so you can access it anywhere. If the property is True then an invocation is required to access the control because the current method is executing on a thread other than the one that owns the control's Handle.

The invocation is performed by calling the control's Invoke or BeginInvoke method. You create a delegate, which is an object that contains a reference to a method. It is good practice to make that a reference to the current method. You then pass that delegate to the Invoke or BeginInvoke method. That will essentially call the referenced method again, this time on the thread that owns the control's Handle.

So, the first step is to identify the control member you want to access. For a first example, let's use the ResetText method of a TextBox. That's nice and simple because there are no parameters and no return value. When starting out you can build up your solution in stages. The first stage is to write a simple method that accesses your control member as desired:

private void ResetTextBoxText()
{
    this.textBox1.ResetText();
}

Nice and easy. Ordinarily you could simply call that method and it would do what you wanted: reset the TextBox's Text property.

Now, the next stage is to test the control's InvokeRequired property and place the existing method body in the Else block:

private void ResetTextBoxText()
{
    if (this.textBox1.InvokeRequired)
    {
 
    }
    else
    {
        this.textBox1.ResetText();
    }
}

That now says that if an invocation is NOT required we can access the control member directly.

The next stage is to create the delegate and use it to invoke the current method on the appropriate thread. As I said, our method has no parameters and no return value so it's nice and easy. In that case you can create an instance of the existing MethodInvoker delegate:

private void ResetTextBoxText()
{
    if (this.textBox1.InvokeRequired)
    {
        this.textBox1.Invoke(new MethodInvoker(ResetTextBoxText));
    }
    else
    {
        this.textBox1.ResetText();
    }
}

If an invocation is required, this creates a MethodInvoker delegate and passes it a reference to the current method. That delegate is then passed to the control's Invoke method, which carries it across the thread boundary to the thread that owns the control's Handle and invokes it. To invoke a delegate means to execute the method it has a reference to.

So now you can simply call that method from any thread you like and rest assured that if you're not on the correct thread that the method itself will handle it for you. To see this in action, try creating a new project and add a Button and a TextBox to the form along with a BackgroundWorker. Now add the following code:

private void Form1_Load(object sender, EventArgs e)
{
    Thread.CurrentThread.Name = "UI Thread";
}

private void button1_Click(object sender, EventArgs e)
{
    this.ResetTextBoxText();

    this.backgroundWorker1.RunWorkerAsync();
}

private void backgroundWorker1_DoWork(object sender, DoWorkEventArgs e)
{
    Thread.CurrentThread.Name = "Worker Thread";

    this.ResetTextBoxText();
}

private void ResetTextBoxText()
{
    Debug.WriteLine(Thread.CurrentThread.Name, "ResetTextBoxText");

    if (this.textBox1.InvokeRequired)
    {
        this.textBox1.Invoke(new MethodInvoker(ResetTextBoxText));
    }
    else
    {
        this.textBox1.ResetText();
    }
}

Use the Properties window in the designer to attach the three event handlers to the appropriate events.

Now run the program, click the Button and watch the Output window. You'll see that the ResetTextBoxText method is executed three times. The first time is in the UI thread when it's called from the Button's Click event handler. The second time is in the worker thread when it's called from the DoWork event handler. The third time is in the UI thread again, when it's invoked via the delegate.

EDIT: I should also point out the difference between Invoke and BeginInvoke. Invoke is a synchronous method. That means that when you call it the background thread will block until the method invoked on the UI thread completes. BeginInvoke is asynchronous, so it will return immediately and the background thread will continue on its way while the method invoked on the UI thread executes.

[jmcilhinney]

To invoke a method via a delegate, the delegate must have the same signature as the method. The example in the first post invokes a method that has no parameters and no return value. In that case you can use the existing MethodInvoker delegate. If you need to specify one or more parameters or get a return value though, you will have to declare your own delegate type.

Let's say that you want to set the Text property of a TextBox from a worker thread. From the first post we know the first step is to declare a method that does what we want:

private void SetTextBoxText(string text)
{
    this.textBox1.Text = text;
}

Now, that method has a parameter so we cannot use the MethodInvoker delegate. We must declare our own delegate type with the same signature. The signature is basically the parameter list and the return type. To create your delegate declaration you should copy the method declaration:

private void SetTextBoxText(string text);

then add the 'delegate' key word:

private delegate void SetTextBoxText(string text);

and finally change the name:

private delegate void SetTextBoxTextInvoker(string text);

Now that we have declared our new delegate type we can create instances of it just as we did with the MethodInvoker.

The next step from above was to add a test for the InvokeRequired property of our control:

private void SetTextBoxText(string text)
{
    if (this.textBox1.InvokeRequired)
    {
 
    }
    else
    {
        this.textBox1.Text = text;
    }
}

Finally we call the control's Invoke method and pass our delegate:

private void SetTextBoxText(string text)
{
    if (this.textBox1.InvokeRequired)
    {
        this.textBox1.Invoke(new SetTextBoxTextInvoker(SetTextBoxText),
                             text);
    }
    else
    {
        this.textBox1.Text = text;
    }
}

Notice that, while last time the only parameter passed to the Invoke method was the delegate, this time we pass the 'text' value as well. Any parameters passed to Invoke after the delegate will then be passed again to the method that gets invoked by the delegate. Our delegate will be invoking the SetTextBoxText method, which requires a 'text' parameter. That code gets the 'text' value passed in to the first call and propagates it to the second call via the Invoke method and the delegate.

The above example passes a single parameter but the very same mechanism can be used to pass multiple parameters. Here's a similar example that can be used to set the Text property of any control:

private delegate void SetControlTextInvoker(Control ctl, string text);
 
private void SetControlText(Control ctl, string text)
{
    if (ctl.InvokeRequired)
    {
        ctl.Invoke(new SetControlTextInvoker(SetControlText),
                   ctl,
                   text);
    }
    else
    {
        ctl.Text = text;
    }
}

Pass in the control and the text and the method handles the rest. It tests the InvokeRequired property and calls the Invoke method of the appropriate control, then sets the Text property of that same control.


EDIT: A note for those using .NET 1.x. The Control.Invoke method signature changed in .NET 2.0 to accept any number of individual parameters. Previous versions required any parameters to be passed within an array. That means that while this is fine in .NET 2.0 and above:

ctl.Invoke(new SetControlTextInvoker(SetControlText),
           ctl,
           text);

you would have to do this in .NET 1.x:

ctl.Invoke(new SetControlTextInvoker(SetControlText),
           new object[] {ctl,
                         text});

[jmcilhinney]

Getting a return value is no more difficult. One thing I haven't mentioned is that the Invoke method is a function. If the method invoked by the delegate returns a value then that is propagated by the Invoke method. Let's use an example of getting the Text property of a TextBox. Following the steps laid out already we first create a method to do the job:

private string GetTextBoxText()
{
    return this.textBox1.Text;
}

Next we declare a matching delegate:

private delegate string GetTextBoxTextInvoker();
 
private string GetTextBoxText()
{
    return this.textBox1.Text;
}

After that we test the InvokeRequired property:

private delegate string GetTextBoxTextInvoker();
 
private string GetTextBoxText()
{
    if (this.textBox1.InvokeRequired)
    {
 
    }
    else
    {
        return this.textBox1.Text;
    }
}

Finally we call the Invoke method and pass an instance of our delegate:

private delegate string GetTextBoxTextInvoker();
 
private string GetTextBoxText()
{
    if (this.textBox1.InvokeRequired)
    {
        return (string)this.textBox1.Invoke(new GetTextBoxTextInvoker(GetTextBoxText));
    }
    else
    {
        return this.textBox1.Text;
    }
}

Let's clean that up a little so we only have one Return statement, which is widely considered to be best practice:

private delegate string GetTextBoxTextInvoker();
 
private string GetTextBoxText()
{
    string text;
 
    if (this.textBox1.InvokeRequired)
    {
        text = (string)this.textBox1.Invoke(new GetTextBoxTextInvoker(GetTextBoxText));
    }
    else
    {
        text = this.textBox1.Text;
    }
 
    return text;
}

Notice that in this case we are actually returning the result of the Invoke method, which is the same value as was returned by the method that was invoked. This is how you get a value back onto your worker thread from the UI thread.

Notice also that the return value from the invoke method must be cast as the appropriate type. Invoke can be used to invoke any method at all, so it could return any value at all. That means that its actual return type is Object. You must therefore cast each returned object as its actual type.

Now to show that this method can be generalised to any control too, as well as combine the passing of parameters and returning a value, here's an extended example based on what we've already seen:

private delegate string GetControlTextInvoker(Control ctl);
 
private string GetControlText(Control ctl)
{
    string text;
 
    if (ctl.InvokeRequired)
    {
        text = (string)ctl.Invoke(new GetControlTextInvoker(GetControlText),
                                  ctl);
    }
    else
    {
        text = ctl.Text;
    }
 
    return text;
}

[MaslowB]

This extension takes care of the checking for invoke required part

public static void InvokeSafe<T>(this T c, Action<T> DoWhat)
	where T : System.Windows.Forms.Control
		{
			 
			Action d = delegate() { DoWhat(c); };
			if (c.InvokeRequired)
				c.Invoke(d);
			else
				DoWhat(c);

		 

		}

[jmcilhinney]

Here's the last example from post #1 redone for WPF:

private BackgroundWorker worker = new BackgroundWorker();
 
private void Window_Loaded(object sender, RoutedEventArgs e)
{
    Thread.CurrentThread.Name = "UI Thread";
 
    this.worker.DoWork += new DoWorkEventHandler(worker_DoWork);
}
 
private void button1_Click(object sender, RoutedEventArgs e)
{
    this.ResetTextBoxText();
 
    this.worker.RunWorkerAsync();
}
 
private void worker_DoWork(object sender, DoWorkEventArgs e)
{
    Thread.CurrentThread.Name = "Worker Thread";
 
    this.ResetTextBoxText();
}
private void ResetTextBoxText()
{
    Debug.WriteLine(Thread.CurrentThread.Name, "ResetTextBoxText");
 
    if (this.textBox1.Dispatcher.Thread == Thread.CurrentThread)
    {
        this.textBox1.Clear();
    }
    else
    {
        this.textBox1.Dispatcher.Invoke(new Action(ResetTextBoxText));
    }
}

[anton2k]

Very use full once i started reading it, makes perfect sense thanks for the learning materials.

[Winanjaya]

Hmmm .. but ToolStripProgressBar does not have Invoke and or InvokeRequired ?

please advise

thanks

[jmcilhinney]

Hmmm .. but ToolStripProgressBar does not have Invoke and or InvokeRequired ?

please advise

thanks

The ToolStripProgressBar class inherits the ToolStripControlHost class. The ToolStripControlHost class itself has a Control property, which exposes the control being hosted. That allows you to host any control at all in a ToolStrip. Classes derived from ToolStripControlHost generally add another property that exposes a specific type of control as its own type. In that vein, the ToolStripProgressBar class has a ProgressBar property that exposes the ProgressBar control being hosted. You can get that ProgressBar control from that property and use its Invoke and InvokeRequired members.

Alternatively, you can just use the form's Invoke and InvokeRequired members. It really doesn't matter which control you use. The purpose of the InvokeRequired property is to determine whether you're currently on the thread that owns a control's handle. The purpose of the Invoke method is to take you to that thread and execute a method. If all your controls are created on the main thread then all Invoke and InvokeRequired members will have exactly the same effect.

[Tobiasgar]

Hmmm.. now everything is simple and clear)) thanx