Share via


How to: Run an Operation in the Background

If you have an operation that will take a long time to complete, and you do not want to cause delays in your user interface, you can use the BackgroundWorker class to run the operation on another thread.

The following code example shows how to run a time-consuming operation in the background. The form has Start and Cancel buttons. Click the Start button to run an asynchronous operation. Click the Cancel button to stop a running asynchronous operation. The outcome of each operation is displayed in a MessageBox.

There is extensive support for this task in Visual Studio.

Walkthrough: Running an Operation in the Background
Walkthrough: Running an Operation in the Background
Walkthrough: Running an Operation in the Background
Walkthrough: Running an Operation in the Background

Example

Imports System
Imports System.ComponentModel
Imports System.Drawing
Imports System.Threading
Imports System.Windows.Forms

Public Class Form1
   Inherits Form

   Public Sub New()
      InitializeComponent()
   End Sub 


   Private Sub backgroundWorker1_DoWork( _
   sender As Object, e As DoWorkEventArgs) _
   Handles backgroundWorker1.DoWork

      ' Do not access the form's BackgroundWorker reference directly. 
      ' Instead, use the reference provided by the sender parameter. 
      Dim bw As BackgroundWorker = CType( sender, BackgroundWorker )

      ' Extract the argument. 
      Dim arg As Integer = Fix(e.Argument)

      ' Start the time-consuming operation.
      e.Result = TimeConsumingOperation(bw, arg)

      ' If the operation was canceled by the user,  
      ' set the DoWorkEventArgs.Cancel property to true. 
      If bw.CancellationPending Then
         e.Cancel = True 
      End If 

   End Sub    

   ' This event handler demonstrates how to interpret  
   ' the outcome of the asynchronous operation implemented 
   ' in the DoWork event handler. 
   Private Sub backgroundWorker1_RunWorkerCompleted( _
   sender As Object, e As RunWorkerCompletedEventArgs) _
   Handles backgroundWorker1.RunWorkerCompleted

      If e.Cancelled Then 
         ' The user canceled the operation.
         MessageBox.Show("Operation was canceled")
      ElseIf (e.Error IsNot Nothing) Then 
         ' There was an error during the operation. 
         Dim msg As String = String.Format("An error occurred: {0}", e.Error.Message)
         MessageBox.Show(msg)
      Else 
         ' The operation completed normally. 
         Dim msg As String = String.Format("Result = {0}", e.Result)
         MessageBox.Show(msg)
      End If 
   End Sub    

   ' This method models an operation that may take a long time  
   ' to run. It can be cancelled, it can raise an exception, 
   ' or it can exit normally and return a result. These outcomes 
   ' are chosen randomly. 
   Private Function TimeConsumingOperation( _
   bw As BackgroundWorker, _
   sleepPeriod As Integer) As Integer 

      Dim result As Integer = 0

      Dim rand As New Random()

        While Not bw.CancellationPending
            Dim [exit] As Boolean = False 

            Select Case rand.Next(3)
                ' Raise an exception. 
                Case 0
                    Throw New Exception("An error condition occurred.")
                    Exit While 

                    ' Sleep for the number of milliseconds 
                    ' specified by the sleepPeriod parameter. 
                Case 1
                    Thread.Sleep(sleepPeriod)
                    Exit While 

                    ' Exit and return normally. 
                Case 2
                    result = 23
                    [exit] = True 
                    Exit While 

                Case Else 
                    Exit While 
            End Select 

            If [exit] Then 
                Exit While 
            End If 
        End While 

      Return result
   End Function 

    Private Sub startButton_Click(ByVal sender As Object, ByVal e As EventArgs) Handles startBtn.Click
        Me.backgroundWorker1.RunWorkerAsync(2000)
    End Sub 

    Private Sub cancelButton_Click(ByVal sender As Object, ByVal e As EventArgs) Handles cancelBtn.Click
        Me.backgroundWorker1.CancelAsync()
    End Sub 

    ' <summary> 
    ' Required designer variable. 
    ' </summary> 
    Private components As System.ComponentModel.IContainer = Nothing 


    ' <summary> 
    ' Clean up any resources being used. 
    ' </summary> 
    ' <param name="disposing">true if managed resources should be disposed; otherwise, false.</param> 
    Protected Overrides Sub Dispose(ByVal disposing As Boolean)
        If disposing AndAlso (components IsNot Nothing) Then
            components.Dispose()
        End If 
        MyBase.Dispose(disposing)
    End Sub 'Dispose

#Region "Windows Form Designer generated code" 


    ' <summary> 
    ' Required method for Designer support - do not modify 
    ' the contents of this method with the code editor. 
    ' </summary> 
    Private Sub InitializeComponent()
        Me.backgroundWorker1 = New System.ComponentModel.BackgroundWorker()
        Me.startBtn = New System.Windows.Forms.Button()
        Me.cancelBtn = New System.Windows.Forms.Button()
        Me.SuspendLayout()
        '  
        ' backgroundWorker1 
        '  
        Me.backgroundWorker1.WorkerSupportsCancellation = True 
        '  
        ' startButton 
        '  
        Me.startBtn.Location = New System.Drawing.Point(12, 12)
        Me.startBtn.Name = "startButton" 
        Me.startBtn.Size = New System.Drawing.Size(75, 23)
        Me.startBtn.TabIndex = 0
        Me.startBtn.Text = "Start" 
        '  
        ' cancelButton 
        '  
        Me.cancelBtn.Location = New System.Drawing.Point(94, 11)
        Me.cancelBtn.Name = "cancelButton" 
        Me.cancelBtn.Size = New System.Drawing.Size(75, 23)
        Me.cancelBtn.TabIndex = 1
        Me.cancelBtn.Text = "Cancel" 
        '  
        ' Form1 
        '  
        Me.AutoScaleDimensions = New System.Drawing.SizeF(6.0F, 13.0F)
        Me.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font
        Me.ClientSize = New System.Drawing.Size(183, 49)
        Me.Controls.Add(cancelBtn)
        Me.Controls.Add(startBtn)
        Me.Name = "Form1" 
        Me.Text = "Form1" 
        Me.ResumeLayout(False)
    End Sub

#End Region

    Private WithEvents backgroundWorker1 As System.ComponentModel.BackgroundWorker
    Private WithEvents startBtn As System.Windows.Forms.Button
    Private WithEvents cancelBtn As System.Windows.Forms.Button
End Class  


Public Class Program

    Private Sub New()

    End Sub 

    ' <summary> 
    ' The main entry point for the application. 
    ' </summary>
    <STAThread()> _
    Shared Sub Main()
        Application.EnableVisualStyles()
        Application.Run(New Form1())
    End Sub 


End Class
using System;
using System.ComponentModel;
using System.Drawing;
using System.Threading;
using System.Windows.Forms;

namespace BackgroundWorkerExample
{
    public class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }

        private void backgroundWorker1_DoWork(object sender, DoWorkEventArgs e)
        {
            // Do not access the form's BackgroundWorker reference directly. 
            // Instead, use the reference provided by the sender parameter.
            BackgroundWorker bw = sender as BackgroundWorker;

            // Extract the argument. 
            int arg = (int)e.Argument;

            // Start the time-consuming operation.
            e.Result = TimeConsumingOperation(bw, arg);

            // If the operation was canceled by the user,  
            // set the DoWorkEventArgs.Cancel property to true. 
            if (bw.CancellationPending)
            {
                e.Cancel = true;
            }
        }

        // This event handler demonstrates how to interpret  
        // the outcome of the asynchronous operation implemented 
        // in the DoWork event handler. 
        private void backgroundWorker1_RunWorkerCompleted(
            object sender, 
            RunWorkerCompletedEventArgs e)
        {   
            if (e.Cancelled)
            {
                // The user canceled the operation.
                MessageBox.Show("Operation was canceled");
            }
            else if (e.Error != null)
            {
                // There was an error during the operation. 
                string msg = String.Format("An error occurred: {0}", e.Error.Message);
                MessageBox.Show(msg);
            }
            else
            {
                // The operation completed normally. 
                string msg = String.Format("Result = {0}", e.Result);
                MessageBox.Show(msg);
            }
        }

        // This method models an operation that may take a long time  
        // to run. It can be cancelled, it can raise an exception, 
        // or it can exit normally and return a result. These outcomes 
        // are chosen randomly. 
        private int TimeConsumingOperation( 
            BackgroundWorker bw, 
            int sleepPeriod )
        {
            int result = 0;

            Random rand = new Random();

            while (!bw.CancellationPending)
            {
                bool exit = false;

                switch (rand.Next(3))
                {
                    // Raise an exception. 
                    case 0:
                    {
                        throw new Exception("An error condition occurred.");
                        break;
                    }

                    // Sleep for the number of milliseconds 
                    // specified by the sleepPeriod parameter. 
                    case 1:
                    {
                        Thread.Sleep(sleepPeriod);
                        break;
                    }

                    // Exit and return normally. 
                    case 2:
                    {
                        result = 23;
                        exit = true;
                        break;
                    }

                    default:
                    {
                        break;
                    }
                }

                if( exit )
                {
                    break;
                }
            }

            return result;
        }

        private void startBtn_Click(object sender, EventArgs e)
        {
            this.backgroundWorker1.RunWorkerAsync(2000);
        }

        private void cancelBtn_Click(object sender, EventArgs e)
        {
            this.backgroundWorker1.CancelAsync();
        }

        /// <summary> 
        /// Required designer variable. 
        /// </summary> 
        private System.ComponentModel.IContainer components = null;

        /// <summary> 
        /// Clean up any resources being used. 
        /// </summary> 
        /// <param name="disposing">true if managed resources should be disposed; otherwise, false.</param>
        protected override void Dispose(bool disposing)
        {
            if (disposing && (components != null))
            {
                components.Dispose();
            }
            base.Dispose(disposing);
        }

        #region Windows Form Designer generated code

        /// <summary> 
        /// Required method for Designer support - do not modify 
        /// the contents of this method with the code editor. 
        /// </summary> 
        private void InitializeComponent()
        {
            this.backgroundWorker1 = new System.ComponentModel.BackgroundWorker();
            this.startBtn = new System.Windows.Forms.Button();
            this.cancelBtn = new System.Windows.Forms.Button();
            this.SuspendLayout();
            //  
            // backgroundWorker1 
            //  
            this.backgroundWorker1.WorkerSupportsCancellation = true;
            this.backgroundWorker1.DoWork += new System.ComponentModel.DoWorkEventHandler(this.backgroundWorker1_DoWork);
            this.backgroundWorker1.RunWorkerCompleted += new System.ComponentModel.RunWorkerCompletedEventHandler(this.backgroundWorker1_RunWorkerCompleted);
            //  
            // startBtn 
            //  
            this.startBtn.Location = new System.Drawing.Point(12, 12);
            this.startBtn.Name = "startBtn";
            this.startBtn.Size = new System.Drawing.Size(75, 23);
            this.startBtn.TabIndex = 0;
            this.startBtn.Text = "Start";
            this.startBtn.Click += new System.EventHandler(this.startBtn_Click);
            //  
            // cancelBtn 
            //  
            this.cancelBtn.Location = new System.Drawing.Point(94, 11);
            this.cancelBtn.Name = "cancelBtn";
            this.cancelBtn.Size = new System.Drawing.Size(75, 23);
            this.cancelBtn.TabIndex = 1;
            this.cancelBtn.Text = "Cancel";
            this.cancelBtn.Click += new System.EventHandler(this.cancelBtn_Click);
            //  
            // Form1 
            //  
            this.AutoScaleDimensions = new System.Drawing.SizeF(6F, 13F);
            this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
            this.ClientSize = new System.Drawing.Size(183, 49);
            this.Controls.Add(this.cancelBtn);
            this.Controls.Add(this.startBtn);
            this.Name = "Form1";
            this.Text = "Form1";
            this.ResumeLayout(false);

        }

        #endregion

        private System.ComponentModel.BackgroundWorker backgroundWorker1;
        private System.Windows.Forms.Button startBtn;
        private System.Windows.Forms.Button cancelBtn;
    }

    public class Program
    {
        private Program()
        {
        }

        /// <summary> 
        /// The main entry point for the application. 
        /// </summary>
        [STAThread]
        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new Form1());
        }
    }
}

Compiling the Code

This example requires:

  • References to the System, System.Drawing and System.Windows.Forms assemblies.

For information about building this example from the command line for Visual Basic or Visual C#, see Building from the Command Line (Visual Basic) or Command-line Building With csc.exe. You can also build this example in Visual Studio by pasting the code into a new project. How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio
How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio
How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio
How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio

See Also

Tasks

How to: Implement a Form That Uses a Background Operation

Reference

BackgroundWorker

DoWorkEventArgs

Other Resources

BackgroundWorker Component