How to: Use a Background Worker

Silverlight

The Silverlight BackgroundWorker¹ class provides an easy way to run time-consuming operations on a background thread. The BackgroundWorker¹ class enables you to check the state of the operation and it lets you cancel the operation.
When you use the BackgroundWorker¹ class, you can indicate operation progress, completion, and cancellation in the Silverlight user interface. For example, you can check whether the background operation is completed or canceled and display a message to the user.

Procedure

To use the BackgroundWorker class

At the class level, create an instance of the BackgroundWorker¹ class.
C#
BackgroundWorker bw = new BackgroundWorker();
Specify whether you want the background operation to allow cancellation and to report progress.
C#
bw.WorkerSupportsCancellation = true; bw.WorkerReportsProgress = true;
Create an event handler for the background worker's DoWork² event.
The DoWork² event handler is where you run the time-consuming operation on the background thread. Any values that are passed to the background operation are passed in the Argument³ property of the DoWorkEventArgs⁴object that is passed to the event handler.
To report progress back to the calling process, call the ReportProgress⁵ method and pass it a completion percentage from 0 to 100. Calling the ReportProgress⁵ method raises the ProgressChanged⁶ event, which you handle separately.

Note:

If the background worker's WorkerReportsProgress⁷ property is not set to true and you call the ReportProgress⁵ method, an exception will occur.

To determine if there is a pending request to cancel the background operation, check the CancellationPending⁸ property of the BackgroundWorker¹ object. If the property is true, the CancelAsync⁹ method was called. Set theBackgroundWorker¹ object's Cancel¹⁰ property to true and stop the operation.
To pass data back to the calling process, set the Result¹¹ property of the DoWorkEventArgs⁴ object that is passed to the event handler. This value can be read when the RunWorkerCompleted¹² event is raised at the end of the operation.
C#
private void bw_DoWork(object sender, DoWorkEventArgs e) { BackgroundWorker worker = sender as BackgroundWorker; for (int i = 1; (i <= 10); i++) { if ((worker.CancellationPending == true)) { e.Cancel = true; break; } else { // Perform a time consuming operation and report progress. System.Threading.Thread.Sleep(500); worker.ReportProgress((i * 10)); } } }
Create an event handler for the background worker's ProgressChanged⁶ event.
In the ProgressChanged⁶ event handler, add code to indicate the progress, such as updating the user interface.
To determine what percentage of the operation is completed, check the ProgressPercentage¹³ property of the ProgressChangedEventArgs¹⁴ object that was passed to the event handler.
C#
private void bw_ProgressChanged(object sender, ProgressChangedEventArgs e) { this.tbProgress.Text = (e.ProgressPercentage.ToString() + "%"); }
Create an event handler for the RunWorkerCompleted¹² event.
The RunWorkerCompleted¹² event is raised when the background worker has completed. Depending on whether the background operation completed successfully, encountered an error, or was canceled, update the user interface accordingly.
To determine whether an error occurred, check the Error¹⁵ property of the RunWorkerCompletedEventArgs¹⁶ object that was passed to the event handler. If an error occurred, this property contains the exception information.
If the background operation allows cancellation and you want to check whether the operation was canceled, check the Cancelled¹⁷ property of the RunWorkerCompletedEventArgs¹⁶ object that was passed to the event handler. If the property is true, the CancelAsync⁹ method was called.
C#
private void bw_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e) { if ((e.Cancelled == true)) { this.tbProgress.Text = "Canceled!"; } else if (!(e.Error == null)) { this.tbProgress.Text = ("Error: " + e.Error.Message); } else { this.tbProgress.Text = "Done!"; } }

Note:
If the background worker's WorkerReportsProgress⁷ property is not set to true and you call the ReportProgress⁵ method, an exception will occur.

Add the event handlers to the BackgroundWorker¹ instance's events.
The following example shows how to add the event handlers to the DoWork², ProgressChanged⁶, and RunWorkerCompleted¹² events.

bw.DoWork += 
    new DoWorkEventHandler(bw_DoWork);
bw.ProgressChanged += 
    new ProgressChangedEventHandler(bw_ProgressChanged);
bw.RunWorkerCompleted += 
    new RunWorkerCompletedEventHandler(bw_RunWorkerCompleted);

Start running the background operation by calling the RunWorkerAsync¹⁸ method.

private void buttonStart_Click(object sender, RoutedEventArgs e)
{
    if (bw.IsBusy != true)
    {
        bw.RunWorkerAsync();
    }
}

Cancel the background operation by calling the CancelAsync⁹ method.

private void buttonCancel_Click(object sender, RoutedEventArgs e)
{
    if (bw.WorkerSupportsCancellation == true)
    {
        bw.CancelAsync();
    }
}

Example

The following example shows how to use the BackgroundWorker¹ class. In the example, the background operation runs the Sleep¹⁹ method and reports progress to the user interface. The background worker is configured to allow cancellation.

using System.ComponentModel;
using System.Windows;
using System.Windows.Controls;

namespace SL_BackgroundWorker_CS
{
    public partial class Page : UserControl
    {
        private BackgroundWorker bw = new BackgroundWorker();

        public Page()
        {
            InitializeComponent();

            bw.WorkerReportsProgress = true;
            bw.WorkerSupportsCancellation = true;
            bw.DoWork += new DoWorkEventHandler(bw_DoWork);
            bw.ProgressChanged += new ProgressChangedEventHandler(bw_ProgressChanged);
            bw.RunWorkerCompleted += new RunWorkerCompletedEventHandler(bw_RunWorkerCompleted);
        }
        private void buttonStart_Click(object sender, RoutedEventArgs e)
        {
            if (bw.IsBusy != true)
            {
                bw.RunWorkerAsync();
            }
        }
        private void buttonCancel_Click(object sender, RoutedEventArgs e)
        {
            if (bw.WorkerSupportsCancellation == true)
            {
                bw.CancelAsync();
            }
        }
        private void bw_DoWork(object sender, DoWorkEventArgs e)
        {
            BackgroundWorker worker = sender as BackgroundWorker;

            for (int i = 1; (i <= 10); i++)
            {
                if ((worker.CancellationPending == true))
                {
                    e.Cancel = true;
                    break;
                }
                else
                {
                    // Perform a time consuming operation and report progress.
                    System.Threading.Thread.Sleep(500);
                    worker.ReportProgress((i * 10));
                }
            }
        }
        private void bw_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e)
        {
            if ((e.Cancelled == true))
            {
                this.tbProgress.Text = "Canceled!";
            }

            else if (!(e.Error == null))
            {
                this.tbProgress.Text = ("Error: " + e.Error.Message);
            }

            else
            {
                this.tbProgress.Text = "Done!";
            }
        }
        private void bw_ProgressChanged(object sender, ProgressChangedEventArgs e)
        {
            this.tbProgress.Text = (e.ProgressPercentage.ToString() + "%");
        }
    }
}

XAML

<UserControl x:Class="SL_BackgroundWorker_CS.Page"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    Width="400" Height="300">
    <Grid x:Name="LayoutRoot" Background="White">
        <StackPanel Height="30" Orientation="Horizontal" 
                    HorizontalAlignment="Left" VerticalAlignment="Top" 
                    Margin="10" >
            <Button x:Name="buttonStart" Content="Start" Click="buttonStart_Click"
                    Width="80" Height="30"/>
            <Button x:Name="buttonCancel" Content="Cancel" Click="buttonCancel_Click"
                    Width="80" Height="30"/>
        </StackPanel>
        <StackPanel Margin="10,50,0,0" Orientation="Horizontal">
            <TextBlock Text="Progress: "/>
            <TextBlock x:Name="tbProgress"/>
        </StackPanel>
    </Grid>
</UserControl>

XAML

<UserControl x:Class="SL_BackgroundWorker_VB.Page"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    Width="400" Height="300">
    <Grid x:Name="LayoutRoot" Background="White">
        <StackPanel Height="30" Orientation="Horizontal" 
                    HorizontalAlignment="Left" VerticalAlignment="Top" 
                    Margin="10" >
            <Button x:Name="buttonStart" Content="Start" Click="buttonStart_Click"
                    Width="80" Height="30"/>
            <Button x:Name="buttonCancel" Content="Cancel" Click="buttonCancel_Click"
                    Width="80" Height="30"/>
        </StackPanel>
        <StackPanel Margin="10,50,0,0" Orientation="Horizontal">
            <TextBlock Text="Progress: " />
            <TextBlock x:Name="tbProgress" />
        </StackPanel>
    </Grid>
</UserControl>

Xaml in : silverlight,Wpf, WinRt and Windows Phone

Published articles on other web sites*

Use a Background Worker

How to: Use a Background Worker

To use the BackgroundWorker class

No comments:

Post a Comment

Xaml in : silverlight,Wpf, WinRt and Windows Phone Headline Animator

Subscribers: