Once you've installed ASP.NET Ajax, the easiest way to set up your application is to create a new web site with Visual Studio 2005 or Visual Web Developer using one of the ASP.NET Ajax site templates. To do this, open Visual Studio 2005 and select File → New Web Site, as shown in Figure 1.

Figure 1. Opening a new web site

Next, in the My Templates section of the Templates panel of the New Web Site dialog, shown in Figure 2, select ASP.NET Ajax Web Site. Choose your file system as the location for the web site by selecting File System from the Location drop-down list. Also, select VB.NET or C# from the Language drop-down list, whichever you prefer (we use C# in the examples). Click OK once you've made your selections.

Figure 2. Creating an ASP.NET Ajax-enabled web site

Once you've completed these steps, Visual Studio creates a new web site (AJAXEnabledWebSite1) with the folders, files, and resources you need to get started, as shown in Figure 3.

Figure 3. The folders, files, and other elements of an ASP.NET Ajax-enabled web site

In the following paragraphs, we explain each of these elements and show you the manual steps you need to take to do what the site creation wizard does automatically. If you need to ASP.NET Ajax-enable an existing site, the operations can't be done automatically.

The application's Web.config file in particular must include the following settings (here, we describe only the settings that are necessary for UpdatePanel, not other settings needed by other parts of ASP.NET Ajax). Open Web.config and add the following markup to the system.web section:

  <system.web>
    <pages>
      <controls>
        <add tagPrefix="asp" namespace="System.Web.UI"
assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"/>
      </controls>
    </pages>
    <compilation debug="false">
      <assemblies>
        <add assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"/>
      </assemblies>
    </compilation>

    <httpHandlers>
      <add verb="GET,HEAD" path="ScriptResource.axd"
type="System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions,
Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
validate="false"/>
    </httpHandlers>

    <httpModules>
      <add name="ScriptModule" type="System.Web.Handlers.ScriptModule,
System.Web.Extensions, Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"/>
    </httpModules>
  </system.web>

Finally, any page that needs to use an UpdatePanel must contain a ScriptManager control and a server form (see the section "The ScriptManager Control Dependency").

The general form of an UpdatePanel control is shown in the following pseudocode:

<asp:UpdatePanel EnableViewState="true|false" UpdateMode="Always|Conditional"
RenderMode="Block|Inline" ChildrenAsTriggers="true|false">
    <Triggers>
        <asp:AsyncPostBackTrigger ControlID="someID" EventName="someEventName" />
        <asp:PostBackTrigger ControlID="someID" />
    </Triggers>
    <ContentTemplate>
        <!-- HTML and ASP.NET content goes here -->
    </ContentTemplate>
</asp:UpdatePanel>

We explain the properties of the UpdatePanel tag in the following sections.

The UpdatePanel control specifies regions within a page that can be refreshed in isolation. It can contain a Triggers collection (which we'll discuss shortly), and needs a ContentTemplate property. The ContentTemplate property defines the area of the page that can be updated asynchronously from the browser, as shown in the following:

<asp:UpdatePanel runat="server" ID="updatePanel">
    <ContentTemplate>
    <!-- HTML and ASP.NET content goes here -->
    </ContentTemplate>
</asp:UpdatePanel>

The runat="server" attribute, as ASP.NET developers know, tells the parser that this is a server control, while the ID attribute is necessary for Visual Studio to switch to design view and is very useful for easily referencing the control from the code.

The contents of the template can appear on the page as if the UpdatePanel control weren't around it, without disrupting the page's layout (see the section "The RenderMode Attribute"). This means you can add an UpdatePanel control to an existing page without altering the appearance of the page. We recommend you give it a meaningful ID, as you would for any server control.

When a postback is initiated from the browser, it normally causes the page to refresh completely. The UpdatePanel control necessitates that the postback be handled asynchronously from JavaScript running in the web browser, and avoids the usual interruption. Instead of sending the entire page's content back to the client, it sends back only the HTML rendered within the areas defined by a ContentTemplate property. This new markup is accompanied by the updated viewstate data, header, and scripts. Then the ASP.NET Ajax JavaScript code running in the browser dynamically replaces the target areas of the page directly in the browser's DOM (Document Object Model).

UpdatePanel controls can be added to existing pages without the need to redesign an application or write custom JavaScript. Multiple UpdatePanel controls can be used in a single page, which allows you to isolate updates to the page area that need to change to reflect users' actions. Event handlers do not need to be modified to account for the use of the UpdatePanel control. During the asynchronous server-side postback, the viewstate information is restored to the controls on the page, so controls within the UpdatePanel can rely on the property values of controls anywhere else on the page.

The UpdatePanel control requires that a ScriptManager control also be present on the page. If no ScriptManager control is present, UpdatePanel throws an exception and the page does not finish executing. As part of this dependency, the ScriptManager must appear before the UpdatePanel in the page. We recommend placing it at the top of the form before any other controls. The ScriptManager control coordinates the distribution of ASP.NET Ajax JavaScript to the browser along with other JavaScript registered by controls on the page. Multiple UpdatePanel controls can be on a page, but there can be only a single ScriptManager. Here's the simplest ScriptManager tag you can write to enable UpdatePanel controls on a page:

<asp:ScriptManager EnablePartialRendering="true" runat="server" ID="manager" />

The EnablePartialRendering property of the ScriptManager control indicates that additional JavaScript needs to be included on the page to change how postbacks are handled.

This updated version traps the postback on the client and performs the operation asynchronously. There is no user interruption or browser flash. The ScriptManager is also signaled to intercept key phases of the page's lifecycle during the asynchronous postback. The controls within the UpdatePanel control do not need to be aware that they are in an UpdatePanel in most situations, and behave no differently than they otherwise would. The ScriptManager control isolates the updated viewstate data for the page and the rendering from all UpdatePanel control contents that need to be refreshed. This data is the return result of the asynchronous postback. The fact that the ScriptManager and UpdatePanel work together to do partial rendering updates on the client is completely transparent to the controls on the page.

In many cases, you do not need to refresh the contents of an UpdatePanel control on every postback to the server. The UpdatePanel control provides an UpdateMode property you can use control when the refresh should occur. UpdateMode can be set to Always or Conditional. By default, the contents of the UpdatePanel are always refreshed. If UpdateMode is set to Conditional, the UpdatePanel relies on its Triggers collection and on the position of the control that triggered the asynchronous postback to determine when the contents are updated. If the control responsible for the postback is inside the panel or is referenced by one of the triggers, the panel is always refreshed. The Triggers and ContentTemplate elements are the only elements allowed as direct children of the UpdatePanel:

<asp:UpdatePanel UpdateMode="Conditional" >
    <Triggers>
        <!--Trigger elements go here -->
    </Triggers>
    <ContentTemplate>
        <!-- HTML and ASP.NET content goes here -->
    </ContentTemplate>
</asp:UpdatePanel>

Individual event triggers can specify events from other controls whose changes should be monitored. When the event is fired, the rendering is captured from the UpdatePanel and sent back from the server to the browser.

<asp:ControlEventTrigger ControlID="Button1" EventName="Click" />

When the page is rendered, an UpdatePanel control renders as either a SPAN or a DIV element within the page. The ID of the UpdatePanel is included on this element and is later used by the JavaScript as the location where content is updated. If you don't specify an ID, one is generated for you, but we recommend you specify a meaningful ID, at least to make debugging easier. The RenderMode property tells the UpdatePanel which element to use as the container for the markup that is refreshed. The default RenderMode value is Block, which means a DIV HTML element is used. When the property is set to Inline, the SPAN element is used. Block should be used when the contents of the panel can take up all the space on the current line, and Inline should be used when the contents of the panel should not disrupt the flow of the text. It should also be noted that, as XHTML tags, SPAN and DIV are not allowed in all contexts because the former is an inline element and the latter is a block element, which may affect your choice for RenderMode.

The following example shows an UpdatePanel control that displays as a SPAN:

<asp:UpdatePanel RenderMode="Inline">
    <ContentTemplate>
        <!-- HTML and ASP.NET content goes here -->
    </ContentTemplate>
</asp:UpdatePanel>

When interacting with the server using navigation or postbacks, the browser typically displays some animation, such as a flapping Windows flag, that tells the user it's working and that he should wait for the server to respond (See Figure 4.)

Figure 4. Animation on the browser shows that it is communicating with the server

When you use AJAX technologies, communication with the server is done with XmlHttp, which doesn't trigger any animation on the browser. UpdatePanel is no exception to that; if the server does not respond instantaneously, the user may think that his action did not have any consequence. He may react by frantically clicking the same button over and over, which will only increase the strain on the server. This is clearly not a good user experience.

A basic UI design principle is that the user should get immediate feedback for any action. In the case of an asynchronous operation that may take a long time to complete, such as a server interaction, this immediate feedback can be a simple wait message, but web applications usually add an animated GIF next to the text message.

For operations that are likely to take an especially long time to complete, the application may even provide a Cancel button. Note that you can cancel only the update to the page, and it is likely that the request will reach the server anyway and side effects will occur. For example, canceling a save operation won't necessarily prevent the data from being saved but will prevent the feedback from coming back and updating the page. This should be seen as a way to retake control of the application and not as an actual cancellation of an operation that may have already reached the server.

ASP.NET Ajax introduces an UpdateProgress control, which makes it easy to add progress indications to an ASP.NET 2.0 page. The UpdateProgress control is templated, which means that the look of your progress notification is completely customizable. The control with its design-time smart tag is shown in Figure 5.

Figure 5. The UpdateProgress control in the Visual Studio designer

In the Visual Studio designer, a default template can be created by clicking in the control design surface, as shown in Figure 6.

Figure 6. The default template for UpdateProgress in the Visual Studio designer

The Abort Request button is an input type="button" element with a click client-side
event that aborts the async postback: <input type="button" onclick="abortPostback"
value="Abort request"/>

The abortPostback function in this example is a global function that you can define this way:

function abortPostback(e) {
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    if (prm.get_isInAsyncPostBack()) {
        prm.abortPostBack();
    }
}

The function gets the client-side instance of the page request manager, which is the object that manages UpdatePanel controls on the client-side. Then, it asks this object if it is currently doing an asynchronous update and aborts it if it's the case. We'll have more opportunities to explore PageRequestManager in the following sections.

The UpdateProgress control is not visible on the page when it first loads in the browser, but whenever an asynchronous postback takes place, it is automatically displayed until the response comes back from the server or the request is canceled. Figure 7 shows a typical control.

Figure 7. The default UpdateProgress template at runtime

The UpdateProgress control is not associated with a particular UpdatePanel control by default and any asynchronous update will trigger the appearance of the UpdateProgress control for the duration of the asynchronous postback. Even though the update is triggered by one particular panel, it may affect more than one or even all of them. However, in some scenarios, you may want to associate different UpdateProgress controls to different triggers on the page. This can be done by setting the AssociatedUpdatePanelID property.

If a control is not inside an UpdatePanel control and is not registered as a trigger for an UpdatePanel control, it will trigger a regular ASP.NET 2.0 postback.

You may want to force a control (such as a button) to trigger an asynchronous postback instead. You can do this by calling the RegisterAsyncPostBackControl method on the ScriptManager control.

This method is also used by triggers under the hood.

One of the most common applications of UpdatePanel is to update a specific part of the page at regular intervals. While there is a cost to this in terms of the application's scalability, such applications do exist and using UpdatePanel is a good way to work around the disconnected nature of HTTP and replace information pushing with polling.

ASP.NET Ajax introduces the TimerControl, which makes this very easy to set up. It is important to note that the actual ticking of the TimerControl happens client-side, not server-side. When added to a page, it creates a client-side timer that triggers a postback on each tick.

While TimerControl is not absolutely tied to the UpdatePanel control, it is especially useful when both are combined and the timer's tick event is used as the trigger of an UpdatePanel control. The postbacks then become asynchronous and can be used to regularly update a specific part of the page.

It is important to realize that the TimerControl can be a big obstacle when it comes to scaling your application. The number of users you anticipate and the kinds of operations you execute during the tick event should be carefully balanced against the interval you choose for the timer. The interval should not be significantly smaller than the typical update frequency of the data being displayed. For example, refreshing a list of blog posts every second seems excessive; an interval of several minutes is probably more appropriate. Conversely, a chat application would typically update every few seconds, though we don't recommend you develop a chat client using AJAX technologies.

The default interval of TimerControl is 60 seconds, which should not be too much of a strain on a typical application.

Example 1 shows how you can use TimerControl to update the time on the page every five seconds.

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Clock</title>
</head>
<body>
    <form id="form1" runat="server">
    <asp:ScriptManager runat="server" ID="SM1" />
    <div>
    <asp:TimerControl runat="server" ID="Time" Interval="5000" Enabled="true" />
    <asp:UpdatePanel runat="server" ID="TimePanel">
        <Triggers>
            <asp:AsyncPostBackTrigger ControlID="Time" EventName="Tick" />
        </Triggers>
        <ContentTemplate>
            <%= DateTime.Now.ToLongTimeString() %>
        </ContentTemplate>
    </asp:UpdatePanel>
    </div>
    </form>
</body>
</html>

In Example 1, the tick event is used only as a trigger for the UpdatePanel control, but it is an ordinary server event despite the fact that the timing itself happens client-side. It is of course perfectly possible to handle this tick event server-side and do some work from there.

During an asynchronous postback, the page is in a state that is close to that of a regular postback. For instance, Page.IsPostback is true during an asynchronous postback.

It can be useful to determine if the postback is a regular postback or an asynchronous one. This can be done by inspecting ScriptManager's IsInAsyncPostBack property.

Sometimes, it is even necessary to determine if a specific UpdatePanel control will be updated or not. The IsInPartialRendering property of UpdatePanel does exactly that, but it's impossible for the framework to determine that information reliably before Render. For that reason, this property always returns false until Render and is not suitable for consumption by page developers. It's really only there for component developers and should only be trusted during Render.

Finally, the specific control that triggered the partial update can be identified by using the AsyncPostBackSourceElementID property of ScriptManager, which returns the unique ID of the control on the page. A reference to that control can then be retrieved using Page.FindControl.