Introduction

Developers tend to visualize a project as a series of procedures and functions that execute in a given sequence, in reality these programs are event driven meaning the flow of execution is determined by occurrences called events.

An event is triggered by something that was expected to occur such as a user clicking a button which raises a Click event which has code to perform one or more actions or calls a method to perform one or more actions. Think of events similar to the radio or TV broadcaster, an event would be a signal to tell you that a show is starting or a signal to tell your DVR that it is time to start recording. Your DVR would listen for a “show is about to begin” event and choose whether or not to do anything in response to it. Put this together with a delegate and an event notifies subscribers that something happened by calling on the delegate to tell them about it.

Throughout this article an exploration will be to show how to create custom delegates and events for use in common operations ranging from monitoring reading files to form communications. Using this information will allow a developer to take code which is constrained to a Windows form to reside in a class which communicates back to a form or to allow a form to communicate back to a class.

Standard events

These are events which are built into controls where a common event is the Click event for a button. The following is a Click event generated by placing a button on a form followed by double clicking the button or by selecting the button, selecting the property windows, selecting the event tab then double clicking the Click event.

Private Sub ExitApplicationButton_Click(sender As Object, e As EventArgs) _
    Handles ExitApplicationButton.Click
 
    Close()
 
End Sub

Breaking down arguments in the Click event.

The sender and e arguments are the standard signature of event handlers. Sender is the object that raised the event and e contains the data of the event. All events in .NET contain such arguments. While in an event like the Click event place a breakpoint on the Close() method and when hit hover over sender and this will reveal sender is of type Button. In this case e does nothing for us generally speaking. In the case of a form's closing event shown below, FormClosingEventArgs provide the reason for the form closing. Besides determining the reason for form closing there is CancelEventArgs.Cancel property which gets or sets a value indicating whether the event should be canceled although depending on the reason setting e.Cancel = False but not be respected if the system is in a unstable state.

Private Sub Form1_FormClosing(sender As Object, e As FormClosingEventArgs) Handles Me.FormClosing
    If e.CloseReason = CloseReason.WindowsShutDown Then
        ' perform actions such as save data or window state,
    End If
End Sub

There may be a requirement for a class to allow cancelation, in this case the pattern shown below allow this. Later on there will be examples which will use a similar pattern of delegate and eventargs in real world examples so don't get hung up on this code, come back after finished reading through the article.

Public Event Announcing As EventHandler(Of AnnounceNavigateEventArgs)
 
Protected Sub OnAnnounce()
    Dim e As New AnnounceNavigateEventArgs
 
    RaiseEvent Announcing(Me, e)
 
    If Not e.Cancel Then
        ' Announce
    End If
End Sub
 
Public Class AnnounceNavigateEventArgs
    Inherits ComponentModel.CancelEventArgs
End Class


 Important
As code presented herein becomes more complicated consider taking time to first run code samples provided in the GitHub repository which were selected to be in line with what a developer may use as alternatives to non object oriented approach.

Visual Studio debugger may be used to step through code also to get a better understanding.

Custom events

Custom events are very useful with common operations but only when a developer understands delegates and events, otherwise developers gravitate to actions that are half-baked, violate OOP concepts.

Example 1 (form communications)

Simple example, the task is to open a new window with a countdown timer where the calling (main) form can start and stop the countdown. The common path is to access the timer component and invoke the Start and Stop method e.g. childForm.Timer1.Start. This is possible since the modifier property of the Timer is Friend. Implementing an event using a delegate the calling form can invoke an event to start/stop the timer without referencing the Timer in the main form.

Delegate and event in main form (Form1)
Public Class Form1
    ' Our delegate (which "points" at any method which takes an object and EventArgs)
    ' Look familiar? This is the signature of most control events on a form
    Public Delegate Sub SendMessage(obj As Boolean, e As EventArgs)
    ' Here is the event we trigger to send messages out to listeners
    ' in this case a Boolean which is used to start/stop a Timer.
    Public Event OnSendMessage As SendMessage

In the child form create an event of type SendMessage defined in the main form. This has one line to start/stop the Timer based on the Checked state of a CheckBox in the main (Form1) form.
Public Class Form2
    Public Sub MessageReceived(sender As Boolean, e As EventArgs)
        Timer1.Enabled = sender
    End Sub

In the main form there is a button with the following click event. Which subscribes to MessageReceived in the child form. 
Private Sub ShowChildFormButton_Click(sender As Object, e As EventArgs) _
    Handles ShowChildFormButton.Click
 
    Dim child As New Form2()
 
    AddHandler OnSendMessage, AddressOf child.MessageReceived
 
    child.Show()
    child.Location = New Point(Left + (Width + 10), Top + 5)
 
End Sub

 Note
That the first argument to SendMessage delegate is not a Object as in common events found in events like a Button Click event, the developer can make this what is needed.

Screenshots are always helpful to visualize, the following shows the above in action.


Example 2 (forms communication)

In the first example the delegate and event were placed in the main form, a better idea is to place delegates in a code module, public if the module is in a different project such as a class project.

In the example the task is to open a child form and perform mocked data entry on two properties of a class, pressing ENTER will raise an event passing an instance of a concrete class (Person) to the calling form were the calling form will Validate the two properties are not empty and that this instance of a person is not present in a DataGridView with a BindingSource as the DataSource.

The following are part of this example
  • Delegates are declared in a code module.
  • Custom EventArgs are used and stored in a class.
  • An anonymous method is used as a predicate to a Lambda statement to keep an line of assertion easy to read
  • Child form overrides ProcessCmdKey to assist with moving from TextBox to TextBox.

The following delegate in a code module is used to pass information from child form to calling form.
Namespace Modules
    Public Module DelegatesModule
        Public Delegate Sub FormMessageHandler(
            sender As Object, args As FormMessageArgs)
    End Module
End Namespace

The above delegate FormMessageHandler has a custom event args.
Namespace Classes
    Public Class FormMessageArgs
        Inherits EventArgs
 
        Protected _person As Person
        ''' <summary>
        ''' Expects a valid Person object with
        ''' First and Last name populated
        ''' </summary>
        ''' <param name="person"></param>
        Public Sub New(person As Person)
            _person = person
        End Sub
        ''' <summary>
        ''' Returns a Person object
        ''' </summary>
        ''' <returns></returns>
        Public ReadOnly Property Person() As Person
            Get
                Return _person
            End Get
        End Property
        ''' <summary>
        ''' Determines if the person object is populated
        ''' </summary>
        ''' <returns></returns>
        Public ReadOnly Property IsValidPerson() As Boolean
            Get
                Return _
                    Not String.IsNullOrWhiteSpace(_person.FirstName) AndAlso
                    Not String.IsNullOrWhiteSpace(_person.LastName)
            End Get
        End Property
    End Class
End NameSpace

Definition of the Person class used in the FormMessageArgs above.
Namespace Classes
    Public Class Person
        Public Property FirstName() As String
        Public Property LastName() As String
 
        Public Overrides Function ToString() As String
            Return $"{FirstName} {LastName}"
        End Function
    End Class
End Namespace

In the child form the following method determines if both TextBox controls have data and if so raises OnMessageInformationChanged event using the custom event arguments of type FormMesageArgs.

Private Sub ConditionallyAddPerson()
    Dim hasFirstName = Not String.IsNullOrWhiteSpace(FirstNameTextBox.Text)
    Dim hasLastName = Not String.IsNullOrWhiteSpace(LastNameTextBox.Text)
 
    If hasFirstName AndAlso hasLastName Then
        '
        ' Both TextBox controls have data, push to the main form
        ' which has subscribed to this event.
        '
        RaiseEvent OnMessageInformationChanged(Me, New FormMessageArgs(
            New Person() With
              {
                  .FirstName = FirstNameTextBox.Text,
                  .LastName = LastNameTextBox.Text
              }))
 
    End If
End Sub

The method above is triggered in ProcessCmdKey if the ENTER key was depressed while in the last name TextBox.
Protected Overrides Function ProcessCmdKey(
    ByRef msg As Message, keyData As Keys) As Boolean
    If msg.WParam.ToInt32() = Keys.Enter AndAlso ActiveControl.Name = "LastNameTextBox" Then
        ConditionallyAddPerson()
        SendKeys.Send("{Tab}")
        Return True
    ElseIf msg.WParam.ToInt32() = Keys.Enter AndAlso ActiveControl.Name = "FirstNameTextBox" Then
        SendKeys.Send("{Tab}")
        Return True
    End If
 
    Return MyBase.ProcessCmdKey(msg, keyData)
 
End Function

In the calling form when creating an instance of the child form the main form subscribes to OnMessageInformationChanged which is triggered in the child form CondiionallyAddPerson invoked in processCmdKey. A standard event is subscribed too also, form closing event of the child form as when the child form is shown the button which shows the child form is disabled so to reenable FormClosed event is used to re-enable the form show button.

Private Sub DisplayChildForm()
 
    If Not My.Application.IsFormOpen("ChildForm") Then
        _childForm = New ChildForm With {
            .Owner = Me
        }
 
        AddHandler _childForm.OnMessageInformationChanged, AddressOf GetNewPerson
        AddHandler _childForm.FormClosing, AddressOf ChildFormClosed
 
        _firstTime = True
 
    End If
 
    _childForm.Show()
    ShowChildFormButton.Enabled = False
 
    If _firstTime Then
        _childForm.Location = New Point(Left + (Width + 10), Top + 5)
        _firstTime = False
    End If
 
End Sub


 Note
When reviewing code note Person FirstName and person LastName properties are checked for empty strings in several places, one is sufficient, each developer will want this as they see fit so this allows the reader to use one of the several assertions.

Here is our visual.


Back in the main form, directly after creating the child form a AddHandler was done
AddHandler _childForm.OnMessageInformationChanged, AddressOf GetNewPerson

Where GetNewPerson event receives a person sent from the child form.
Private Sub GetNewPerson(sender As Object, args As FormMessageArgs)
    Dim people = CType(_bindingSource.DataSource, List(Of Person))
 
    If people.FirstOrDefault(Function(p) PersonValid(p, args.Person)) Is Nothing Then
        _bindingSource.Add(args.Person)
    Else
        MessageBox.Show($"{args.Person} exists.")
    End If
 
End Sub

Note the predicate in the above FirstOrDefault method which is shown below in the main form which shows how to create a predicate for one of two or both reasons.
  • Reusable
  • Takes a large assertion out of business code, now the code is easier to read
' Anonymous method
Public PersonValid As ValidPerson =
           Function(person1 As Person, person2 As Person)
               Return Not String.IsNullOrWhiteSpace(person1.FirstName) AndAlso
                      Not String.IsNullOrWhiteSpace(person1.LastName) AndAlso
                      person1.FirstName = person2.FirstName AndAlso
                      person1.LastName = person2.LastName
           End Function

Person1 is an instance of a iteration againsts the List of Person object in a BindingSource component which is the DataSource of a DataGridView while Person2 contains data from the child form.

Here is the entire code for the main form.
Imports FollowParent.Classes
Imports FollowParent.Modules
 
Public Class Form1
 
    Private ReadOnly _bindingSource As New BindingSource
 
    Private _childForm As ChildForm
    Private _firstTime As Boolean = True
 
    ' Anonymous method
    Public PersonValid As ValidPerson =
               Function(person1 As Person, person2 As Person)
                   Return Not String.IsNullOrWhiteSpace(person1.FirstName) AndAlso
                          Not String.IsNullOrWhiteSpace(person1.LastName) AndAlso
                          person1.FirstName = person2.FirstName AndAlso
                          person1.LastName = person2.LastName
               End Function
 
    Private Sub ShowChildFormButton_Click(sender As Object, e As EventArgs) _
        Handles ShowChildFormButton.Click
 
        DisplayChildForm()
 
    End Sub
    Private Sub Form1_FormClosing(sender As Object, e As FormClosingEventArgs) Handles Me.FormClosing
        If _childForm IsNot Nothing Then
            _childForm.Dispose()
        End If
    End Sub
    Private Sub DisplayChildForm()
 
        If Not My.Application.IsFormOpen("ChildForm") Then
            _childForm = New ChildForm With {
                .Owner = Me
            }
 
            AddHandler _childForm.OnMessageInformationChanged, AddressOf GetNewPerson
            AddHandler _childForm.FormClosing, AddressOf ChildFormClosed
 
            _firstTime = True
 
        End If
 
        _childForm.Show()
        ShowChildFormButton.Enabled = False
 
        If _firstTime Then
            _childForm.Location = New Point(Left + (Width + 10), Top + 5)
            _firstTime = False
        End If
 
    End Sub
 
    Private Sub ChildFormClosed(sender As Object, e As FormClosingEventArgs)
        ShowChildFormButton.Enabled = True
    End Sub
    ''' <summary>
    ''' Person passed in from child form
    ''' </summary>
    ''' <param name="sender"></param>
    ''' <param name="args"></param>
    ''' <remarks>
    '''
    ''' </remarks>
    Private Sub GetNewPerson(sender As Object, args As FormMessageArgs)
        Dim people = CType(_bindingSource.DataSource, List(Of Person))
 
        If people.FirstOrDefault(Function(p) PersonValid(p, args.Person)) Is Nothing Then
            _bindingSource.Add(args.Person)
        Else
            MessageBox.Show($"{args.Person} exists.")
        End If
 
    End Sub
 
    Private Sub Form1_LocationChanged(sender As Object, e As EventArgs) Handles Me.LocationChanged
        If Not _FirstTime Then
            _ChildForm.Location = New Point(Left + (Width + 10), Top + 5)
        End If
    End Sub
    Private Sub ExitApplicationButton_Click(sender As Object, e As EventArgs) _
        Handles ExitApplicationButton.Click
 
        Close()
 
    End Sub
    Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
 
        DataGridView1.AutoGenerateColumns = False
        _bindingSource.DataSource = New List(Of Person)
        DataGridView1.DataSource = _bindingSource
 
    End Sub
End Class

Entire code for child form.
Imports FollowParent.Classes
Imports FollowParent.Modules
 
Public Class ChildForm
 
    Public Event OnMessageInformationChanged As FormMessageHandler
 
    Private Sub cmdClose_Click(sender As Object, e As EventArgs) Handles cmdClose.Click
        Close()
    End Sub
    ''' <summary>
    ''' Event triggered in ProcessCmdKey event when ENTER is pressed
    ''' in the LastNameTextBox and both TextBox controls have values
    ''' </summary>
    Private Sub ConditionallyAddPerson()
        Dim hasFirstName = Not String.IsNullOrWhiteSpace(FirstNameTextBox.Text)
        Dim hasLastName = Not String.IsNullOrWhiteSpace(LastNameTextBox.Text)
 
        If hasFirstName AndAlso hasLastName Then
            '
            ' Both TextBox controls have data, push to the main form
            ' which has subscribed to this event.
            '
            RaiseEvent OnMessageInformationChanged(Me, New FormMessageArgs(
                New Person() With
                  {
                      .FirstName = FirstNameTextBox.Text,
                      .LastName = LastNameTextBox.Text
                  }))
 
        End If
    End Sub
 
    ''' <summary>
    ''' Ensures no beep on enter key pressed
    ''' Not practical for a typical data entry form.
    ''' </summary>
    ''' <param name="msg"></param>
    ''' <param name="keyData"></param>
    ''' <returns></returns>
    Protected Overrides Function ProcessCmdKey(ByRef msg As Message, keyData As Keys) As Boolean
        If msg.WParam.ToInt32() = Keys.Enter AndAlso ActiveControl.Name = "LastNameTextBox" Then
            ConditionallyAddPerson()
            SendKeys.Send("{Tab}")
            Return True
        ElseIf msg.WParam.ToInt32() = Keys.Enter AndAlso ActiveControl.Name = "FirstNameTextBox" Then
            SendKeys.Send("{Tab}")
            Return True
        End If
 
        Return MyBase.ProcessCmdKey(msg, keyData)
 
    End Function
End Class

 Note
There is a good deal to consume in the above code sample, it's highly recommended to take time to study the code rather than simply attempting to implement in an existing project.


Example 3 (read delimited file part 1)

A common operation is reading delimited files by tab, comma or positional into another data source which is usually a database table direct or into a relational database. It's also common for developers to write code within a form either because they don't know how to write code outside a form or they are the type to just code because they don't know better or lazy.

Consider a delimited text file with eight comma delimited columns where in this case the data is perfect in that all fields are of type string so there is no problem with need to convert to other types and once converted determine if they are within specifications.

The file name is hard coded, in the wild a user might pick the file with a FileOpenDialog.
Imports System.IO
Public Class Form1
    Private FileName As String = Path.Combine(
        AppDomain.CurrentDomain.BaseDirectory, "Data.txt")
 
    Private Sub ReadFileButton_Click(sender As Object, e As EventArgs) _
        Handles ReadFileButton.Click
 
        ReadFileAndPopulateDataGridView()
 
    End Sub
    Private Async Sub ReadFileAndPopulateDataGridView()
        Dim lineIndex = 1
 
        Dim currentLine As String
 
        Using reader As StreamReader = File.OpenText(FileName)
 
            While Not reader.EndOfStream
 
                Await Task.Delay(10)
 
                currentLine = Await reader.ReadLineAsync()
                StatusLabel.Text = $"Reading line {lineIndex}"
 
                Dim parts = currentLine.Split(","c)
 
                Dim person = New Person With
                        {
                            .FirstName = parts(0),
                            .MiddleName = parts(1),
                            .LastName = parts(2),
                            .Street = parts(3),
                            .City = parts(4),
                            .State = parts(5),
                            .PostalCode = parts(6),
                            .EmailAddress = parts(7)
                        }
 
                DataGridView1.Rows.Add(person.FieldArray())
 
                lineIndex += 1
 
            End While
        End Using
 
    End Sub
End Class
Public Class Person
    Public Property FirstName As String
    Public Property MiddleName As String
    Public Property LastName As String
    Public Property Street() As String
    Public Property City As String
    Public Property State As String
    Public Property PostalCode As String
    Public Property EmailAddress As String
    Public Function FieldArray() As String()
        Return New String() {FirstName, MiddleName, LastName, Street, City, State, PostalCode, EmailAddress}
    End Function
End Class

Problems
  • If the file contains thousands of rows the form will not respond until processing has completed.
  • The Await Task.Delay(10) is for this sample in that there are only several hundred records so this permits seeing records being added. Without this the form becomes unresponsive.
  • There are no provisions for say reporting blank rows (we will cover this in the next example).
  • If the file was not perfect there are no way to report issues back to the form.
  • The Person class can only be used in this form.


Example 3 (read delimited file part 2)

In this version the form is basically the same with two labels for reporting progress which is done through events.



Here is the project layout which is more involved that the latter code sample.


 Changed mindset
Many developers want to code with the the fewest lines of code possible and when seeing a solution such as this one will indicate it's over their head. A true developer will pick the proper path, in some cases less code is better while in other cases more is better.


Running through code logic

There are two delegates, one for reporting progress by the current line number plus the Person instance read from a line. The second delegate will be used to report empty lines and count them.

Imports ReadingDelimitedFile2.Classes
Namespace Modules
    Public Module DelegatesModule
        Public Delegate Sub FileHandler(sender As Object, args As LineArgs)
        Public Delegate Sub EmptyLineHandler(sender As Object, args As EmptyLineArgs)
    End Module
End Namespace

A class is used to read the text file where events are setup to match the delegates above.
Imports System.IO
Imports ReadingDelimitedFile2.Modules
 
Namespace Classes
    Public Class FileOperation
 
        ''' <summary>
        ''' Event for reporting progress and passing a just read Person
        ''' to the calling form for adding to a DataGridView
        ''' </summary>
        Public Event OnLineRead As FileHandler
        ''' <summary>
        ''' Event for monitoring empty lines
        ''' </summary>
        Public Event OnEmptyLineRead As EmptyLineHandler

The following property sets/gets a Boolean to continue or cancel processing lines.
Public Property CancelRead() As Boolean

The following method is asynchronous by using ReadLineAsync while the last version for reading lines was synchronous which used ReadLine. Asynchronous operations should be used when needed and not when it looks cool as there are more considerations from interacting with form controls when done wrong to proper cancellation of an operation.

Note the two RaiseEvent, the first passes the current line index and the person data read back to the form which has subscribed to the OnLineRead event and the other for reporting back empty line indexes back in the form here.
 Public Async Function ReadFileAndPopulateDataGridView() As Task
    Dim currentLineIndex = 1
 
    Dim currentLine As String
 
    Using reader As StreamReader = File.OpenText(FileName)
 
        While Not reader.EndOfStream
 
            Await Task.Delay(2)
 
            currentLine = Await reader.ReadLineAsync()
 
            ' avoid empty lines
            If Not String.IsNullOrWhiteSpace(currentLine) Then
 
                Dim currentLineParts = currentLine.Split(","c)
 
                ' only add if there are 8 elements in the array
                If currentLineParts.Length = 8 Then
 
                    Dim person = New Person With
                            {
                                .FirstName = currentLineParts(0),
                                .MiddleName = currentLineParts(1),
                                .LastName = currentLineParts(2),
                                .Street = currentLineParts(3),
                                .City = currentLineParts(4),
                                .State = currentLineParts(5),
                                .PostalCode = currentLineParts(6),
                                .EmailAddress = currentLineParts(7)
                            }
 
                    RaiseEvent OnLineRead(Me, New LineArgs(currentLineIndex, person))
 
                End If
            Else
                RaiseEvent OnEmptyLineRead(Me, New EmptyLineArgs(currentLineIndex))
            End If
 
 
            ' increment line number used in callback
            currentLineIndex += 1
 
            ' watch for user cancellation
            If CancelRead Then
                Exit Function
            End If
 
        End While
    End Using
End Function

Form code
In the form there is zero code that interacts with the text file, all work is done by clicking a button then listening for information returning in subscribed events. Special note to the button which uses the key word Async as the method invoked from FileOperations is asynchronous. Also note there is no need for InvokeRequired as the two events are not in another thread which would be needed if done from the Button Click event which is another benefit of using events which is similar to using Iterator with Yield statement. 
 
Imports System.IO
Imports ReadingDelimitedFile2.Classes
 
Public Class Form1
    ''' <summary>
    ''' Exiting file to read
    ''' </summary>
    Private ReadOnly _fileName As String = Path.Combine(
        AppDomain.CurrentDomain.BaseDirectory, "Data.txt")
 
    Private _operations As New FileOperation
 
    ''' <summary>
    ''' Used to display count of empty rows while reading a file
    ''' </summary>
    Private _emptyLineCount As Integer = 0
    ''' <summary>
    ''' Used to store line indices for empty lines when reading a file
    ''' </summary>
    Private _emptyLineList As New List(Of Integer)
    ''' <summary>
    ''' Provides functionality to read a file asynchronously with
    ''' callbacks for populating a DataGridView, report progress
    ''' by line number and also using a callback to report empty lines
    ''' </summary>
    ''' <param name="sender"></param>
    ''' <param name="e"></param>
    Private Async Sub ReadFileButton_Click(sender As Object, e As EventArgs) _
        Handles ReadFileButton.Click
 
        _emptyLineCount = 0
        _emptyLineList = New List(Of Integer)()
 
        _operations = New FileOperation(_fileName)
 
        AddHandler _operations.OnLineRead, AddressOf LineRead
        AddHandler _operations.OnEmptyLineRead, AddressOf EmptyLineRead
 
        Await _operations.ReadFileAndPopulateDataGridView()
 
        EmailColumn.AutoSizeMode = DataGridViewAutoSizeColumnMode.Fill
 
        If _emptyLineList.Count > 0 Then
            Dim lineIndices = String.Join(",", _emptyLineList.ToArray())
            MessageBox.Show($"The following lines where empty {lineIndices}")
        End If
 
    End Sub
    ''' <summary>
    ''' Report back an empty line with it's index.
    ''' </summary>
    ''' <param name="sender"></param>
    ''' <param name="args"></param>
    Private Sub EmptyLineRead(sender As Object, args As EmptyLineArgs)
        _emptyLineCount += 1
 
        EmptyLinesLabel.Text = _emptyLineCount.ToString()
        _emptyLineList.Add(args.RowIndex)
 
    End Sub
 
    ''' <summary>
    ''' Update status label
    ''' Add new row to DataGridView
    ''' </summary>
    ''' <param name="sender"></param>
    ''' <param name="args"></param>
    Private Sub LineRead(sender As Object, args As LineArgs)
 
        StatusLabel.Text = $"Read line {args.RowIndex}"
 
        If Not _operations.CancelRead Then
            DataGridView1.Rows.Add(args.Person.FieldArray())
        End If
 
    End Sub
    Private Sub ExitApplicationButton_Click(sender As Object, e As EventArgs) _
        Handles ExitApplicationButton.Click
 
        Close()
 
    End Sub
    Private Sub Form1_FormClosing(sender As Object, e As FormClosingEventArgs) _
        Handles Me.FormClosing
 
        _operations.CancelRead = True
 
    End Sub
    Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
 
        StatusLabel.Text = ""
        EmptyLinesLabel.Text = ""
 
    End Sub
End Class

Progress(Of T) Asynchronous

Progress(Of T) provides IProgress(Of T) Interface a way to invoke callbacks for each reported progress which in the wild allows an operation such as downloading files from the web or reading a delimited file from disk in a form or a class called from a form to report current progress. For example, when reading a file report the current line of total lines in a label rather than a progressbar.

Example 1

Starting off simple by executing a Do While statement 10,000 times, within the Do While construct a callback of type TaskProgressReport, pass the current index, total (10,000) and a string message.

TaskProgressReport class
Namespace Classes
    Public Class TaskProgressReport
        'current progress
        Public Property CurrentProgressAmount() As Integer
        'total progress
        Public Property TotalProgressAmount() As Integer
        'some message to pass to the UI of current progress
        Public Property CurrentProgressMessage() As String
    End Class
End Namespace

Worker method
Private Async Function WorkerAsync(delay As Integer, progress As IProgress(Of TaskProgressReport)) As Task
 
    Dim totalAmount As Integer = 10000
 
    Dim currentIterator As Integer = 0
 
    Do While currentIterator <= totalAmount
 
        Await Task.Delay(delay)
 
        progress.Report(New TaskProgressReport With
                           {
                               .CurrentProgressAmount = currentIterator,
                               .TotalProgressAmount = totalAmount,
                               .CurrentProgressMessage = $"Current message: {currentIterator}"
                           })
 
        currentIterator += delay
 
    Loop
End Function

The worker class is called from a Button Click event. Note AddressOf ReportProgress, this is our callback.
Private Async Sub StartButton_Click(sender As Object, e As EventArgs) Handles StartButton.Click
 
    Dim progress = New Progress(Of TaskProgressReport)(AddressOf ReportProgress)
    Await WorkerAsync(100, progress)
 
End Sub

Callback
Private Sub ReportProgress(progress As TaskProgressReport)
    StatusLabel.Text = progress.CurrentProgressMessage
    ProgressTextBox.Text = $"{progress.CurrentProgressAmount} of {progress.TotalProgressAmount}"
End Sub

Screenshot in progress.


Although the provides feedback for an operation there are two issues, the first is the operation resides in the form rather than in a class and secondly no canceling of the operation if the user decided to cancel. The next example will provide a method to not only cancel but start the process over again while many code samples on the web simply show how to cancel but missing an important element, restart the process, not resume which can be done also yet this is to be considered a foundation for more complex operations.

Example 2

Going with cancellation keeping the operation in the form, the third example will move away from the form to a class. Rather than using a class for the callback this example uses a Integer. The key to cancel option is CancellationTokenSource. A CancellationTokenSource object is setup a form level scope as a private variable. The Token of the CancellationTokenSource is passed to a callback which is the worker of the operation, in this case a do-nothing method.

In the worker method an assertion is done to see if the CancellationTokenSource.IsCancellationRequested is true (meaning a cancel to request has been issued) then invoke ThrowIfCancellationRequested of the CancellationTokenSource object which will throw an exception which means the call to the worker method must be in a Try-Catch statement. In this example the only exception watched is OperationCanceledException but for an application in production there should also be a second catch for general exceptions as the last catch. To cancel the operation Cancel method is invoked on the CancellationTokenSource object.

Important: To reuse the CancellationTokenSource object to restart the object must first be disposed then recreated.

Imports System.Threading
 
Public Class Form1
    Private _cts As New CancellationTokenSource()
 
    Private Async Function AsyncMethod(progress As IProgress(Of Integer), ct As CancellationToken) As Task
 
        For index As Integer = 0 To 20
            'Simulate an async call that takes some time to complete
            Await Task.Delay(500)
 
            If ct.IsCancellationRequested Then
                ct.ThrowIfCancellationRequested()
            End If
 
            'Report progress
            If progress IsNot Nothing Then
                progress.Report(index)
            End If
 
        Next
 
    End Function
 
    Private Async Sub StartButton_Click(sender As Object, e As EventArgs) Handles StartButton.Click
        '
        ' Reset if needed, if was ran and cancelled before
        '
        If _cts.IsCancellationRequested = True Then
            _cts.Dispose()
            _cts = New CancellationTokenSource()
        End If
 
        'Instantiate progress indicator.
        'In this example this reports an Integer as progress, but
        'we could actually report a complex object providing more
        'information such as current operation
        Dim progressIndicator = New Progress(Of Integer)(AddressOf ReportProgress)
        Try
            'Call async method, pass progress indicator and cancellation token as parameters
            Await AsyncMethod(progressIndicator, _cts.Token)
        Catch ex As OperationCanceledException
            lblStatus.Text = "Cancelled"
        End Try
 
    End Sub
    Private Sub CancelButton_Click(sender As Object, e As EventArgs) Handles CancelButton.Click
        _cts.Cancel()
    End Sub
    Private Sub ReportProgress(value As Integer)
        lblStatus.Text = value.ToString()
    End Sub
 
End Class

Screenshot

Example 3

In this example a class is used for reporting, similar to example 1. The same cancellation method is used as in example 2. The main difference this time is that the worker method resides outside a form in a class.

The work simply reads lines from a file and displays the line index and the string contents of each line,
Imports System.IO
Imports System.Threading
 
Namespace Classes
    Public Class Operations
        Private ReadOnly _fileName As String = Path.Combine(
            AppDomain.CurrentDomain.BaseDirectory, "Data.txt")
        Public Async Function AsyncMethod(progress As IProgress(Of Line), ct As CancellationToken) As Task
            Dim currentLine As New Line
 
            Dim lines = File.ReadAllLines(_fileName)
 
            For index As Integer = 0 To lines.Length - 1
 
                Await Task.Delay(300)
                currentLine = New Line() With {.Index = index, .Data = lines(index)}
 
                If ct.IsCancellationRequested Then
                    ct.ThrowIfCancellationRequested()
                End If
 
                'Report progress
                If progress IsNot Nothing Then
                    progress.Report(currentLine)
                End If
 
            Next
 
        End Function
 
    End Class
End Namespace

Form code
Imports System.Threading
Imports Progress3.Classes
 
Public Class Form1
    Private _cts As New CancellationTokenSource()
    Private operations As New Operations
    Private Async Sub StartButton_Click(sender As Object, e As EventArgs) Handles StartButton.Click
        '
        ' Reset if needed, if was ran and cancelled before
        '
        If _cts.IsCancellationRequested = True Then
            _cts.Dispose()
            _cts = New CancellationTokenSource()
        End If
 
        'Instantiate progress indicator, unlike the last two examples
        'In this example this reports a class as progress, but
        Dim progressIndicator = New Progress(Of Line)(AddressOf ReportProgress)
 
        Try
            Await operations.AsyncMethod(progressIndicator, _cts.Token)
        Catch ex As OperationCanceledException
            lblStatus.Text = "Cancelled"
        End Try
 
    End Sub
    Private Sub CancelButton_Click(sender As Object, e As EventArgs) Handles CancelButton.Click
        _cts.Cancel()
    End Sub
    Private Sub ReportProgress(value As Line)
        lblStatus.Text = value.ToString()
    End Sub
 
End Class

Screenshot


There is no processing of lines as to not lose focus of working from a form to a class.

Summary

Two common tasks have been presented for consideration to understand delegates and events without digging deep into the mechanics of delegates/events which is intentional as many developers learn by example and then will read Microsoft documentation to then get a firm understanding of delegates and events. Reading Microsoft documentation will provide the why’s and also provide more such as memory conservation with delegates and events. The main thing here was to show specifically how to use custom event arguments and to do this with common task such as form communications and reading files. Also presented, how to work with progress asynchronously with options for callbacks from simple type to complex types.

See also

VB.NET: Invoke Method to update UI from secondary threads
Delegates
C# Event handling in an MVVM WPF application

Source code

https://github.com/karenpayneoregon/CallbacksVisualBasic