Saturday, November 12, 2011

Easy incremental status updates for long requests

A problem that has always plagued web developers has been providing detailed progress indication for server-side tasks. The stateless nature of the HTTP protocol makes implementing a mechanism for constant, stateful progress information cumbersome. The main problem is that a given group of server side tasks will generally only result in one, aggregate response from the server.

In the ASP.NET community, several solutions have been offered. Some even provide an entire framework for monitoring the status of tasks in progress. However, they are convoluted and depend on constant server polling. I find polling for progress indication to be an inefficient approximation, when exact data is readily available.

With that in mind, I’d like to share an alternate method that I’ve used in the past with great success.
Note: While this example is written in ASP.NET and C#, the technique I’m going to describe is very easily portable to any language and platform.

Worse than watching paint dry

Suppose you had a long running group of tasks, such as these:

public void PrepareReport()
  // Initialization.
  // Gather data.
  // Process data.
  // Clean up.

That’s 40 seconds we’re hoping the user will patiently wait on some sign of life from the server. Assuming that something went wrong, users are likely to give up and navigate away during something that runs this long.
Constant, granular progress feedback is exactly what’s needed to keep the user engaged while the tasks complete.

Asynchronously executing the tasks

The first thing we need to do is get away from the HTTP request/response cycle, by using some sort of asynchronous execution model. By doing that, the browser is still available to update the UI throughout the process execution. Rather than use formal AJAX, I chose to do something even easier.

Iframes: They’re underused, given the power and flexibility they provide, but not today. In this scenario, using an iframe is a great way to asynchronously execute the long running process, without being dependent on any particular AJAX framework and without tying up an XMLHttpRequest.

<input type="submit" value="Start Long Running Process" 
  id="trigger" onclick="BeginProcess(); return false;" />
<script type="text/javascript">
  function BeginProcess()
    // Create an iframe.
    var iframe = document.createElement("iframe");
    // Point the iframe to the location of
    //  the long running process.
    iframe.src = "LongRunningProcess.aspx";
    // Make the iframe invisible. = "none";
    // Add the iframe to the DOM.  The process
    //  will begin execution at this point.

When the button is clicked, an invisible iframe is dynamically generated and used to execute LongRunningProcess.aspx in the background. Next, let’s take a look at exactly what goes on when LongRunningProcess.aspx is executed.

Streaming update information during the process

In LongRunningProcess.aspx.cs’s Page_Load, I’m going to include the same set of tasks as before, but I’m also going to stream constant updates about what stage of the process is executing.
protected void Page_Load(object sender, EventArgs e)
  // Padding to circumvent IE's buffer*
  Response.Write(new string('*', 256));  
  // Initialization
  UpdateProgress(0, "Initializing task.");
  // Gather data.
  UpdateProgress(25, "Gathering data.");
  // Process data.
  UpdateProgress(40, "Processing data.");
  // Clean up.
  UpdateProgress(90, "Cleaning up.");
  // Task completed.
  UpdateProgress(100, "Task completed!");
protected void UpdateProgress(int PercentComplete, string Message)
  // Write out the parent script callback.
    PercentComplete, Message));
  // To be sure the response isn't buffered on the server.

For each step of the process, this outputs a JavaScript callback to the page that opened the iframe. Using the combination of Response.Write and Response.Flush ensures that the callbacks are emitted in real-time, as the tasks are completed.

Since the relative run time of my example tasks are known in advance, I included completion percentages as well as the status messages. The raw output will look something like this:

<script>parent.UpdateProgress(0, 'Initializing task.');script>
<script>parent.UpdateProgress(25, 'Gathering data.');script>
<script>parent.UpdateProgress(40, 'Processing data.');script>
<script>parent.UpdateProgress(90, 'Cleaning up.');script>
<script>parent.UpdateProgress(100, 'Task completed!');script>
*Note: Internet Explorer buffers the first 256 bytes of any response. To circumvent that behavior, it’s important that you push 256 characters down the response before anything else. Otherwise, the first few status updates will be buffered and the callbacks won’t be executed at the correct time (or at all, visibly) for users running IE.

Handling the callbacks and displaying status updates

The final step is to create a client side function to handle the callbacks coming from the iframe. To keep things simple, we’ll use the submit button’s text value to display the status updates.
function UpdateProgress(PercentComplete, Message)
  document.getElementById('trigger').value = 
    PercentComplete + '%: ' + Message;
Now, the submit button’s text will continuously update throughout the process, to reflect the current status of the process in real-time.

We’ve only just begun (and by we, I mean you)

I purposely kept the presentation very simple in this example, so that the underlying mechanism isn’t obscured by DHTML code.

However, if updating the button’s text isn’t visually stimulating enough for you, it’s easy to dress this technique up any way you want. For example, if you return percentages in your implementation, jsProgressBarHandler would be trivial to integrate with this technique and provides an excellent visualization.

You could do something similar to this, without an iframe, by using a sequence of page method or web service calls that had progress updates in between. The problem is that you’d have to move a lot of your logic into the presentation layer to do that. I would strongly advise against going down that road, when avoidable.

In real world use, you’re probably going to want to specify parameters to the long running process. Loading it in the Session is one way do to that. Even better, if you can manage it, is to provide arguments on the QueryString when setting the iframe’s src attribute. Then, you can check those parameters in LongRunningProcess.aspx.cs and respond accordingly.

Download Source

As always, taking the source code for a spin is the best way to get a feel for it.

Author: Dave Ward