Overview

A ProgressBar can be associated with a server side task and updates accordingly when the server side task progresses.

The following table lists the most important properties/events related to this feature:

Getting Started

The following section describes hows a server side task is carried out through a ProgressBar control:

1. A server side task can be started by user clicking StartTaskButton or via a client side Javascript call to the ProgressBar's startTask method;
2. The ProgressBar raises server side event RunTask. You should perform your long running task inside this handler. While running the task, your code should frequently:
   • Checks whether the task has been stopped via ProgressTaskEventArgs.IsStopped. This property is updated when the task has been stopped from the client side, either by user clicking StopTaskButton or call stopTask programmmatically;
   • Calls ProgressTaskEventArgs.UpdateProgress to update progress information. Information passed to this function will be passed to the client side to update the progress bar;
3. A stop notification is sent to the server when one of the following occurs:
   • End user clicks StopTaskButton, or
   • stopTask is called, or
   • End user navigates to another page thus causes the current page to be unloaded;

   The server updates ProgressTaskEventArgs.IsStopped after it receives the stop notification. In this case your code inside RunTask should exit the long running task as soon as possible;

4. If the task is not interrupted, it can continue to run until it finishes. You can provide a client side event handler via ClientSideOnTaskDone property to be notified when the task finishes.

Below is an example of a simple long running task that does nothing but calling System.Threading.Thread.Sleep:

private void ProgressBar1_RunTask(object sender, 
    EO.Web.ProgressTaskEventArgs e)
{
    for (int i = 0; i < 100; i++)
    {
        //Check whether the task has been stopped
        if (e.IsStopped)
            break;
    
        //Perform some work
        System.Threading.Thread.Sleep(1000);
        
        //Update client side progress
        e.UpdateProgress(i, null);
    }
}

Private Sub ProgressBar_RunTask(ByVal sender As System.Object, 
    ByVal e As EO.Web.ProgressTaskEventArgs) Handles ProgressBar1.RunTask
    
    Dim i As Integer
    For i = 0 To 99
        'Stop the task as soon as we can if the user has
        'stopped it from the client side
        If e.IsStopped Then
            Exit For
        End If 
        
        'Here we call Thread.Sleep just for demonstration
        'purpose. You should replace this with code that
        'performs your long running task.
        System.Threading.Thread.Sleep(500)
            
        'You should frequently call UpdateProgress in order
        'to notify the client about the current progress
        e.UpdateProgress(i)
    Next i
End Sub

Multi-CPU/Web farm Considerations

In a multi-CPU/Web farm environment, it is possible that the "start notification" is sent to one server and the "stop notification" is sent to another server. In this case ProgressTaskEventArgs.IsStopped will not be correctly updated. In order to avoid this situation, you should call RegisterTaskNotify to register your own event handlers to handle task stop event and add additional logic into your RunTask handler accordingly to determine whether the task is stopped. For example, you can:

• Maintain a "RunningTask" table in your database;
• Update this table when you receive a task stop event;
• Inside your RunTask event handler, you can query this table to determine whether the task is stopped instead of relying on ProgressTaskEventArgs.IsStopped.

Session Variable Considerations

By default, while your code is running, ASP.NET locks the session object. In this case if user tries to navigate to another page that needs to access session variables without first stopping the task, ASP.NET will not be able to process the request, because it is unable to acquire a lock on the session variable due to the lock is already being held by the page where the task is running.

To avoid this problem, considering adding EnableSessionState="false" or EnableSessionState="ReadOnly" into your @Page directive. Set it to ReadOnly if you still wish to read session variables, but do not want to change it. Set it to false if you do not need to access any session variables at all.