The AsyncRendering property on the ASP.Net ReportViewer control is one of the most misunderstood properties on the ReportViewer.  And that’s our fault.  There are a lot of side effects to setting this property that you wouldn’t expect from the name.  In fact, most of the time that I see users setting this property they are doing it for the side effects rather than for its true intention.  Those side effects are gone in Visual Studio 2010 because you can get the effects you want in either mode.  But to understand how things have changed, let’s first go through some background information.

The intention of AsyncRendering

Traditionally, the HTML of a web page is not sent to the browser until all of the web controls on the page have generated their content.  For controls such as text boxes and buttons, this makes perfect sense.  But the ReportViewer is much more complicated than that.  It can take the viewer a long time to generate the HTML for a report.  In most cases, it makes more sense to send the rest of the page back to the browser and then make another request to get the report content asynchronously.  This allows the user to interact with the rest of the page as well as see a "loading indicator" so that they know the server is doing something.  This is the default behavior - AsyncRendering = true.

But there are also cases where you want the block the entire page until the report is processed.  A good example is a dashboard type of page that is rendering several small reports, perhaps each one containing a single chart or small table.  In this case, you may not want the user to be bombarded with multiple wait indicators.  If you know the reports are quick to process, blocking the page for a short time may be a better overall experience.  This is the intention of AsyncRendering = false.

Asynchronous mode in Visual Studio 2005 and 2008

The mode you choose has a significant effect on the HTML that is ultimately generated.  The ReportViewer control was originally designed long before the appearance of ASP.Net AJAX.  When you render a report synchronously, the HTML for the report content is embedded directly in the entire page.  But when you render asynchronously, the ReportViewer uses a frame.  The frame content is retrieved by the browser separately from the main page, so it allows the main page to be visible while the report is generated in a separate request to the web server.

Frames are at the root of all of the side effects to AsyncRendering.  The use of frames results in the following differences between the two modes:

  • The document map is only visible in asynchronous mode, in part because it relies on frames to handle resizing relative to the report area.
  • Because the report is rendered in a frame and not part of the ASP.Net page that hosts the viewer, there is no chance for developers to handle events that occur while processing the report.  The most frequent complaint we receive in this area is the inability to handle the ReportError event when rendering asynchronously.
  • The size of the frame is difficult for the viewer to calculate and is therefore usually wrong.  It’s based on the sizing mode of the viewer (percentage or fixed size), the height of the toolbar, and the existence of parameters.  This is the leading cause to seeing an excessive number of scrollbars in the viewer, particularly when using standards mode or non-IE browsers.  Developers often switch to synchronous rendering to alleviate this.
  • Along a similar line to sizing of the frame is the fact that the SizeToReportContent property is ignored in asynchronous mode.  The frame does not adjust its size based on the content, so there is no easy way to show an arbitrary report embedded in a page without scrollbars, unless you switch to synchronous mode.

These side effects tend to rank higher in terms of requirements when building an application than whether the report shows up synchronously.  So it’s no surprise that these issues became the driving factor in which mode developers choose.

The Story in Visual Studio 2010

One of the biggest features of the ASP.Net ReportViewer in VS 2010 is the fact that it relies heavily on ASP.Net AJAX.  By default, the viewer will use asynchronous postbacks for all of its operations.  This means that we no longer need to rely on frames to retrieve report data asynchronously from the rest of the ASP.Net page.  With VS 2010, once a report has finished loading, the HTML displayed in the browser will be the same, regardless of whether you use synchronous or asynchronous rendering.

All of the previous side effects of AsyncRendering are now gone.  Both modes support the document map.  Both modes support the SizeToReportContent property.  Asynchronous postbacks are generally treated the same as traditional postbacks, so you can handle events that occur during report processing.  And because of the extensive work we’ve put into this release for standards mode HTML and Firefox and Safari rendering, you should never see double (or triple!) scrollbars in the viewer.

With VS 2010, AsyncRendering has returned to its true intention – it controls whether the initial processing of the report blocks the entire ASP.Net page, and nothing else.