Walkthrough: Multithreading with the BackgroundWorker Component (C# and Visual Basic)
This walkthrough demonstrates how to create a multithreaded application that searches a text file for occurrences of a word. It demonstrates:
To create the user interface
Open a new Visual Basic or C# Windows Application project, and create a form named Form1.
Add two buttons and four text boxes to Form1.
Name the objects as shown in the following table.
First text box
Second text box
Third text box
Fourth text box
Add a label next to each text box. Set the Text property for each label as shown in the following table.
To create a BackgroundWorker component and subscribe to its events
Add a BackgroundWorker component from the Components section of the ToolBox to the form. It will appear in the form's component tray.
Set the following properties for the BackgroundWorker1 object in Visual Basic or the backgroundWorker1 object in C#.
In C# only, subscribe to the events of the backgroundWorker1 object. At the top of the Properties window, click the Events icon. Double-click the RunWorkerCompleted event to create an event handler method. Do the same for the ProgressChanged and DoWork events.
To define the method that will run on a separate thread
From the Project menu, choose Add Class to add a class to the project. The Add New Item dialog box is displayed.
Select Class from the templates window and type Words.vb or Words.cs in the name field.
Click Add. The Words class is displayed.
Add the following code to the Words class:
Public Class Words ' Object to store the current state, for passing to the caller. Public Class CurrentState Public LinesCounted As Integer Public WordsMatched As Integer End Class Public SourceFile As String Public CompareString As String Private WordCount As Integer = 0 Private LinesCounted As Integer = 0 Public Sub CountWords( ByVal worker As System.ComponentModel.BackgroundWorker, ByVal e As System.ComponentModel.DoWorkEventArgs ) ' Initialize the variables. Dim state As New CurrentState Dim line = "" Dim elapsedTime = 20 Dim lastReportDateTime = Now If CompareString Is Nothing OrElse CompareString = System.String.Empty Then Throw New Exception("CompareString not specified.") End If Using myStream As New System.IO.StreamReader(SourceFile) ' Process lines while there are lines remaining in the file. Do While Not myStream.EndOfStream If worker.CancellationPending Then e.Cancel = True Exit Do Else line = myStream.ReadLine WordCount += CountInString(line, CompareString) LinesCounted += 1 ' Raise an event so the form can monitor progress. If Now > lastReportDateTime.AddMilliseconds(elapsedTime) Then state.LinesCounted = LinesCounted state.WordsMatched = WordCount worker.ReportProgress(0, state) lastReportDateTime = Now End If ' Uncomment for testing. 'System.Threading.Thread.Sleep(5) End If Loop ' Report the final count values. state.LinesCounted = LinesCounted state.WordsMatched = WordCount worker.ReportProgress(0, state) End Using End Sub Private Function CountInString( ByVal SourceString As String, ByVal CompareString As String ) As Integer ' This function counts the number of times ' a word is found in a line. If SourceString Is Nothing Then Return 0 End If Dim EscapedCompareString = System.Text.RegularExpressions.Regex.Escape(CompareString) Dim regex As New System.Text.RegularExpressions.Regex( EscapedCompareString, System.Text.RegularExpressions.RegexOptions.IgnoreCase) Dim matches As System.Text.RegularExpressions.MatchCollection matches = regex.Matches(SourceString) Return matches.Count End Function End Class
To handle events from the thread
Add the following event handlers to your main form:
Private Sub BackgroundWorker1_RunWorkerCompleted( ByVal sender As Object, ByVal e As System.ComponentModel.RunWorkerCompletedEventArgs ) Handles BackgroundWorker1.RunWorkerCompleted ' This event handler is called when the background thread finishes. ' This method runs on the main thread. If e.Error IsNot Nothing Then MessageBox.Show("Error: " & e.Error.Message) ElseIf e.Cancelled Then MessageBox.Show("Word counting canceled.") Else MessageBox.Show("Finished counting words.") End If End Sub Private Sub BackgroundWorker1_ProgressChanged( ByVal sender As Object, ByVal e As System.ComponentModel.ProgressChangedEventArgs ) Handles BackgroundWorker1.ProgressChanged ' This method runs on the main thread. Dim state As Words.CurrentState = CType(e.UserState, Words.CurrentState) Me.LinesCounted.Text = state.LinesCounted.ToString Me.WordsCounted.Text = state.WordsMatched.ToString End Sub
To start and call a new thread that runs the WordCount method
Add the following procedures to your program:
Private Sub BackgroundWorker1_DoWork( ByVal sender As Object, ByVal e As System.ComponentModel.DoWorkEventArgs ) Handles BackgroundWorker1.DoWork ' This event handler is where the actual work is done. ' This method runs on the background thread. ' Get the BackgroundWorker object that raised this event. Dim worker As System.ComponentModel.BackgroundWorker worker = CType(sender, System.ComponentModel.BackgroundWorker) ' Get the Words object and call the main method. Dim WC As Words = CType(e.Argument, Words) WC.CountWords(worker, e) End Sub Sub StartThread() ' This method runs on the main thread. Me.WordsCounted.Text = "0" ' Initialize the object that the background worker calls. Dim WC As New Words WC.CompareString = Me.CompareString.Text WC.SourceFile = Me.SourceFile.Text ' Start the asynchronous operation. BackgroundWorker1.RunWorkerAsync(WC) End Sub
Call the StartThread method from the Start button on your form:
To implement a Cancel button that stops the thread
Call the StopThread procedure from the Click event handler for the Cancel button.
You can now test the application to make sure it works correctly.
To test the application
Press F5 to run the application.
When the form is displayed, enter the file path for the file you want to test in the sourceFile box. For example, assuming your test file is named Test.txt, enter C:\Test.txt.
In the second text box, enter a word or phrase for the application to search for in the text file.
Click the Start button. The LinesCounted button should begin incrementing immediately. The application displays the message "Finished Counting" when it is done.
To test the Cancel button
Press F5 to start the application, and enter the file name and search word as described in the previous procedure. Make sure that the file you choose is large enough to ensure you will have time to cancel the procedure before it is finished.
Click the Start button to start the application.
Click the Cancel button. The application should stop counting immediately.