Using the local Domain Name System (DNS) resolver in the operating system, the browser resolves the requested URL to an IP address and opens a socket. An HTTP packet travels over the wire to the given destination. The packet includes the form and all its fields. The request is captured by the Web server and typically forwarded to an internal module for further processing. At the end of the process, an HTTP response packet is prepared and the return value for the browser is inserted in the body. If the response contains an HTML page, the browser replaces the current contents entirely with the new chunk of markup.

While the request is being processed on the server, the “old” page is frozen but still displayed to the client user. As soon as the “new” page is downloaded, the browser clears the display and renders the page.

This model was just fine in the beginning of the Web age when pages contained little more than formatted text, hyperlinks, and some images. The success of the Web has prompted users to ask for increasingly more powerful features, and it has led developers and designers to create more sophisticated services and graphics. The net effect is that pages are heavy and cumbersome—even though we still insist on calling them “rich” pages. Regardless of whether they’re rich or just cumbersome, these are the Web pages of today’s applications. And nobody really believes that we’re going to return to the scanty and spartan HTML pages of a decade ago.

Given the current architecture of Web applications, each user action requires a complete redraw of the page. Subsequently, richer and heavier pages render slowly and, as a result, produce a good deal of flickering. Projected to the whole set of pages in a large, portal-like application, this mechanism is perfect for unleashing the frustrations of the poor end user.

The chief factor that enables Ajax functionality in a Web page is the ability to issue out-of-band HTTP requests. In this context, an out-of-band call indicates an HTTP request placed using a component different from the browser. This component is the XMLHttpRequest object.

Historically speaking, the first version of this object saw the light of day in 1998 as part of the Microsoft Outlook Web Access subsystem within Microsoft Exchange. Later on, the component was embedded as an ActiveX component in Internet Explorer 5 and then was integrated in other browsers.

XMLHttpRequest is a browser object that is scriptable through JavaScript. It sends a regular HTTP request to the specified URL and waits, either synchronously or asynchronously, for it to be fully served. When the response data is ready, the proxy invokes a user-defined JavaScript callback to refresh any portion of the page that needs updating. Figure 20-1 provides a graphical overview of the model.

Figure 20-1. Out-of-band calls are sent through a proxy component.

All browsers know how to replace an old page with a new page; until a few years ago, though, not all of them provided an object model to represent the current contents of the page. (Today, I can hardly mention a single modern, commercially available browser that doesn’t expose a read/write page DOM.) For browsers that supply an updatable object model for HTML pages, the JavaScript callback function can refresh specific portions of the old page, thus making them look updated, without a full reload.

There’s a World Wide Web Consortium (W3C) ratified standard for the updatable DOM you can find at http://www.w3.org/TR/DOM-Level-3-Core. A W3C document for the proxy component is currently being developed. It takes the form of the existing XMLHttpRequest object and is devised as an interface exposed by the browser to allow script code to perform HTTP client functionality, such as submitting form data or loading data from a remote Web site. The latest candidate recommendation is at http://www.w3.org/TR/XMLHttpRequest.

About ten years ago, with Internet Explorer 4.0, Microsoft introduced a proprietary object model named Dynamic HTML (DHTML) to enable page authors to update the current page dynamically using JavaScript. The success of DHTML led to the definition of a standard document object model—the W3C’s DOM. Quite obviously, the DOM evolved from DHTML and became much more generalized than DHTML.

Today most browsers support a mix of DOM and DHTML. Which one should you use? In particular, to update certain content, should you obtain a reference to the textual child node of the node that matches the intended HTML tag (the DOM way), or just grab a reference to a node and use the innerHTML property as you would do in the DHTML way? Likewise, to add a new element, should you create a new element or just stuff in a chunk of updated HTML via innerHTML? Admittedly, one of the most interesting debates in the community is whether to use DHTML to manipulate pages or opt for the cleaner approach propounded by the DOM API.

The key fact is that the DOM API is significantly slower than using innerHTML. If you go through the DOM to generate some user interface dynamically, you have to create every element, append each into the proper container, and then set properties. The alternative entails only that you define the HTML you want and render it into the page using innerHTML. The browser then does the rest by rendering your markup into direct graphics.

Overall, DHTML and DOM manipulation are both useful depending on the context. There are many Web sites that discuss performance tests, and DHTML is always the winner. Anyway, DOM is still perfectly fast as long as you use it the right way—that is, create HTML fragments and append them to the proper container only as the final step.

Created by Microsoft and adopted soon thereafter by Mozilla, the XMLHttpRequest object is fully supported these days by the majority of Web browsers. The implementation can vary from one browser to the next, even though the top-level interface is nearly identical. For this reason, a W3C committee is at work with the goal of precisely documenting a minimum set of interoperable features based on existing implementations. An excellent presentation on the component can be found here: http://developer.mozilla.org/en/docs/XMLHttpRequest.

Today, the XMLHttpRequest object is part of the browser object model and is exposed out of the window object. As a result, it can be instantiated through the classic new operator:

// The object name requires XML in capital letters
var proxy = new XMLHttpRequest();

When the browser is Internet Explorer (up to version 6.0), the XMLHttpRequest object must be instantiated using the ActiveXObject wrapper, as shown here:

var proxy = new ActiveXObject("Microsoft.XmlHttp");

Generally, Ajax frameworks (and JavaScript libraries with Ajax support, such as jQuery) check the current browser and then decide which route to take.

The XMLHttpRequest object is designed to perform one key operation: send an HTTP request. The request can be sent either synchronously or asynchronously. The following bit of code shows the programming interface of the object as it results from the W3C working draft at the time of this writing:

interface XMLHttpRequest
{
  function onreadystatechange;
  readonly unsigned short readyState;
  void open(string method, string url);
  void open(string method, string url, bool async);
  void open(string method, string url, bool async, string user);
  void open(string method, string url, bool async,
            string user, string pswd);
  void setRequestHeader(string header, string value);
  void send(string data);
  void send(Document data);
  void abort();
  string getAllResponseHeaders();
  string getResponseHeader(string header);
  string responseText;
  Document responseXML;
  unsigned short status;
  string statusText;
};

Using the component is a two-step operation. First, you open a channel to the URL and specify the method (GET, POST, or other) to use and specify whether you want the request to execute asynchronously. Next, you set any required header and send the request. If the request is a POST, you pass to the send method the body of the request.

The send method returns immediately in the case of an asynchronous operation. You write an onreadystatechange function to check the status of the current operation and, using that function, figure out when it is done. The following code shows how to carry on a POST request using the XMLHttpRequest object:

var xmlRequest, e;
try
{
    xmlRequest = new XMLHttpRequest();
}
catch(e)
{
    try
    {
        xmlRequest = new ActiveXObject("Microsoft.XMLHTTP");
    }
    catch(e)
    {
    }
}

// Prepare for a synchronous POST request
var body = null;  // An empty request body this time...
xmlRequest.open("POST", pageUrl, false);
xmlRequest.setRequestHeader("Content-Type",
                            "application/x-www-form-urlencoded");
xmlRequest.send(body);

In a synchronous call, the send method returns when the response has been fully downloaded and parsed by the object. You can access it as a plain string using the responseText property. If the response is an XML stream, you can have it exposed as an XML DOM object using the responseXml property.

In functional programming, the building block of code is the “function,” as opposed to the “class” in object-oriented programming and the “subroutine” in procedural programming. A function is a unit of code that describes only the operations to be performed on the input. A function gets some input and returns some output; everything else is hidden from view.

As a functional programmer, you build your applications by pipelining function calls to create a super function that just gets the program’s input and returns the program’s output. There’s typically no layer where you process the input, store state, arrange a sequence of statements, update the state, and decide about the next step. A function is a like a value, and it can be used as an argument and be passed to other functions as well as used in any other context where values can be used.

In JavaScript, anonymous functions are the pillar of functional programming. An anonymous function is a direct offshoot of lambda calculus or, if you prefer, a language adaptation of old-fashioned function pointers. Here’s an example:

function(x, y) {
   return x + y;
}

The only difference between a regular function and an anonymous function is in the name. In a functional context, you don’t strictly need to name a function, especially if you’re using it as a value that you pass around.

The jQuery library, which we’ll cover in the next chapter, more than ever called people’s attention to functional programming. In a Web environment, all you do is manipulate DOM elements. The jQuery library is effective because it allows you to manipulate DOM elements while enjoying the power (and to some extent the cleanness) of functional programming.

There’s a significant difference between objects in a qualified OOP language and JavaScript. In OOP languages, the class is a blueprint for actual objects you use. In JavaScript, you just have objects whose blueprint is that of a dictionary of data and functions. When you create a new object in JavaScript, you have an empty dictionary you can fill with anything you like.

Having said that, with a bit of work you can create (and reuse) custom objects and manage for them to inherit from existing objects and also behave polymorphically. This work is just what JavaScript object-oriented libraries do.

When it comes to adding layers to JavaScript to make it closer to a qualified OOP language and gain some more programming power and code reusability, you have to choose from two main approaches for extending the capabilities of the native JavaScript objects: closures and prototypes.

Before we get to that, however, a few words about the native Object type in JavaScript and its usage. You can use the new keyword to create a new dictionary-like object in JavaScript.

Next, you stuff data into it, and you can add methods by wiring functions to property names. Here’s an example:

var person = new Object();
person.Name = "Dino";
person.LastName = "Esposito";
person.BirthDate = new Date(1992,10,17)
person.getAge = function() {
  var today = new Date();
  var thisDay = today.getDate();
  var thisMonth = today.getMonth();
  var thisYear = today.getFullYear();
  var age = thisYear-this.BirthDate.getFullYear()-1;
  if (thisMonth > this.BirthDate.getMonth())
      age = age +1;
  else
  if (thisMonth == this.BirthDate.getMonth() &&
      thisDay >= this.BirthDate.getDate())
      age = age +1;
  return age;
}

What we have is an object modeled after a person; we don’t have a Person object. A possible way to define the layout of a type is to create a new, all-encompassing function that exposes just the members we like. In addition, in JavaScript all intrinsic objects have a read-only property named prototype. You can use the prototype property to provide a base set of functionality shared by any new instance of an object of that type. These two are the mechanisms to leverage for using OOP in JavaScript.

A closure is a general concept of programming languages. Applied to JavaScript, a closure is a function that can have variables and methods defined together within the same context. In this way, the outermost (anonymous or named) function “closes” the expression. Here’s an example of the closure model for a function that represents a Person type:

var Person = function(name, lastname, birthdate)
{
   this.Name = name;
   this.LastName = lastname;
   this.BirthDate = birthdate;

   this.getAge = function() {
      var today = new Date();
      var thisDay = today.getDate();
      var thisMonth = today.getMonth();
      var thisYear = today.getFullYear();
      var age = thisYear-this.BirthDate.getFullYear()-1;
      if (thisMonth > this.BirthDate.getMonth())
          age = age +1;
      else
         if (thisMonth == this.BirthDate.getMonth() &&
             thisDay >= this.BirthDate.getDate())
             age = age +1;
      return age;
   }
}

As you can see, the closure is nothing more than the constructor of the pseudo-class. In a closure model, the constructor contains the member declarations and members are truly encapsulated and private to the class. In addition, members are instance based, which increases the memory used by the class. Here’s how you use the object:

var p = new Person("Dino", "Esposito", new Date( ... );
alert(p.Name + " is " + p.getAge());

The closure model gives full encapsulation, but nothing more. To compose objects, you can only resort to aggregation.

The prototype model entails that you define the public structure of the class through the JavaScript prototype object. The following code sample shows how to rewrite the preceding Person class to avoid a closure:

// Pseudo constructor
var Person = function(name, lastname, birthdate)
{
    this.initialize(name, lastname, birthdate);
}

// Members
Person.prototype.initialize(name, lastname, birthdate)
{
    this.Name = name;
    this.LastName = lastname;
    this.BirthDate = birthdate;
}

Person.prototype.getAge = function()
{
    var today = new Date();
    var thisDay = today.getDate();
    var thisMonth = today.getMonth();
    var thisYear = today.getFullYear();
    var age = thisYear-this.BirthDate.getFullYear()-1;
    if (thisMonth > this.BirthDate.getMonth())
        age = age +1;
    else
       if (thisMonth == this.BirthDate.getMonth() &&
           thisDay >= this.BirthDate.getDate())
           age = age +1;
    return age;
}

In the prototype model, the constructor and members are clearly separated and a constructor is always required. As for private members, you just don’t have them. The var keyword that would keep them local in a closure doesn’t apply in the prototype model. So you can define getter/setter for what you intend to be properties, but the backing field will remain accessible from the outside, anyway. You can resort to some internal (and documented) convention, such as prefixing with an underscore the name of members you intend as private. That’s just a convention, however.

By using the prototype feature, you can achieve inheritance by simply setting the prototype of a derived object to an instance of the “parent” object:

Developer = function Developer(name, lastname, birthdate)
{
   this.initialize(name, lastname, birthdate);
}
Developer.prototype = new Person();

Note that you always need to use this to refer to members of the prototype from within any related member function.

In the prototype model, members are shared by all instances as they are invoked on the shared prototype object. In this way, the amount of memory used by each instance is reduced, which also provides for faster object instantiation. Aside from syntax peculiarities, the prototype model makes defining classes much more similar to the classic OOP model than the closure model.

The choice between closure and prototype should also be guided by performance considerations and browser capabilities. Prototypes have a good load time in all browsers; indeed, they have excellent performance in Firefox. (In contrast, closures have a better load time than prototypes in Internet Explorer.) Prototypes provide better support for IntelliSense, and they allow for tool-based statement completion when used in tools that support this feature, such as Microsoft Visual Studio. Prototypes can also help you obtain type information by simply using reflection. You won’t have to create an instance of the type to query for type information, which is unavoidable if closures are used. Finally, prototypes allow you to easily view private class members when debugging. Debugging objects derived using the closure model requires a number of additional steps.

For security reasons, all XMLHttpRequest calls within all browsers are restricted to the Same Origin Policy (SOP). In other words, all browsers proceed with an XMLHttpRequest call only if the destination URL is within the same origin as the calling page. Because XMLHttpRequest uploads cookies, a user authenticated on a site (say, contoso.com) might end up on another site (say, thebadguy.com) and leave there her authentication cookie. At this point, from the thebadguy.com site an attacker could make an XMLHttpRequest request to contoso.com and behave as if it were the original user. In a nutshell, script-led cross-domain calls are forbidden.

The problem is that sometimes cross-domain calls are useful and entirely legitimate. How to work around the limitation? Generally speaking, there are four possible approaches:

These are the various options you might want to consider first as a software architect. These are the options that would work without requiring each user to tweak security settings on her browser.

Note, however, that most browsers let you disable the SOP policy through the dialog box for the security settings. If you, as a user, proceed with and enable cross-domain calls, all XMLHttpRequest calls magically work, regardless of their final destination. From a design perspective, however, this solution has a strong prerequisite: it requires you to exercise strict control over all possible machines that will be using the site. For Internet Explorer, you select the Security tab from the Internet Options dialog box and then scroll down to the Miscellaneous section, as shown in Figure 20-2.

Be aware that a similar option might not exist for other browsers.

I’ll return to cross-domain calls in the next chapter with a few concrete examples. For now, suffice it to say that two approaches are the most commonly used today: server-side proxies and JSON with Padding (JSONP) over the <script> tag.

Figure 20-2. Tweaking the cross-domain call setting of Internet Explorer.

The ScriptManager control features a number of properties for you to configure its expected behavior. Table 20-1 details the supported properties.

The script manager is the nerve center of any ASP.NET AJAX pages and does all the work that is necessary to make AJAX features function as expected. Enabling AJAX features mostly means injecting the right piece of script in the right place. The script manager saves ASP.NET developers from dirtying their hands with JavaScript.

Table 20-2 lists the methods defined on the ScriptManager control.

All static methods emit some form of script and markup in the client page. These static methods are the AJAX counterpart of similar methods defined on the page’s ClientScript object that you should know from earlier versions of ASP.NET. The static RegisterXXX methods on the ScriptManager class ensure that the given piece of script and markup is properly emitted only once in each partial update of the ASP.NET AJAX page. Similarly, other nonstatic RegisterXXX methods should be seen as tools to emit proper script code in ASP.NET AJAX pages—especially script code that is associated with custom controls.

Table 20-3 details the events fired by the ScriptManager control.

These events are much more than mere notifications of something that has happened on the server. Both give you good chances to intervene effectively in the course of the application. For example, by handling the ResolveScriptReference event, you can change the location from where the script is going to be downloaded on the client:

protected void ResolveScript(object sender, ScriptReferenceEventArgs e)
{
    // Check Path or Name on the e.Script object based on what you've put in Scripts.
    // Next, you specify the real file to load
    if (String.Equals(e.Script.Path, "personal.js", StringComparison.OrdinalIgnoreCase))
         e.Script.Path = "person.js";
}

By handling the AsyncPostBackError event, you can edit the error message being returned to the client during a partial rendering operation. Here’s an example:

protected void AsyncPostBackError(object sender, AsyncPostBackErrorEventArgs e)
{
        ScriptManager sm = sender as ScriptManager;
        if (Request.UserHostAddress == "127.0.0.1")
        {
            sm.AsyncPostBackErrorMessage = String.Format(
                "<b>An error occurred. <br/>{0}<b>",
                e.Exception.Message);
        }
        else
        {
            sm.AsyncPostBackErrorMessage = String.Format(
                "<b>An error occurred. <br/>{0}<b>",
                "Please contact your Web master.");
        }
}

What if you want to redirect the user to an error page instead?

In this case, you configure the page to use the traditional error-handling mechanism for ASP.NET pages. You configure the <customErrors> section in the web.config file and indicate HTML error pages to reach in case of specific errors. This behavior can be disabled by setting to false the value of the AllowCustomErrorRedirects property of the ScriptManager object.

Only one instance of the ScriptManager control can be added to an ASP.NET AJAX page. However, there are two ways in which you can do this. You can add it directly on the page using the <asp:ScriptManager> tag or indirectly by importing a component that already contains a script manager. Typically, you can accomplish the second alternative by importing a user control, creating a content page for a master page, or authoring a nested master page.

What if a content page needs to add a new script reference to the manager? In this case, you need a reference to the script manager. Although it’s defined in the master page (or in a user control), the script manager might not be publicly exposed to the content page. You can use the static method GetCurrent on the class ScriptManager to get the right instance:

// Retrieve the instance of the ScriptManager active on the page
var manager = ScriptManager.GetCurrent(this.Page);

The ScriptManagerProxy class saves you from this sort of coding. In general, in cases where you need features of the ScriptManager control but lack a direct reference to it, you can instead include a ScriptManagerProxy control in the content page.

You can’t have two script managers in the context of the same page; however, you can have a script manager and a proxy to retrieve it. The ScriptManagerProxy control enables you to add scripts and services to nested components, and it enables partial page updates in user controls and nested master pages. When you use the proxy, the Scripts and Services collections on the ScriptManager and ScriptManagerProxy controls are merged at run time.

By extensively relying on client capabilities, an Ajax page requires a lot of script code. The framework itself links a lot of code, as do custom controls and actual user pages. The only HTML-supported way of linking script files is the <script> tag and its src attribute. The ScriptManager control can be used to save you from having to directly manipulate quite a few <script> tags and also to obtain richer features, such as built-in management of localized scripts.

You use the Scripts collection to tell the ScriptManager about the scripts you want to add to the page. The collection can be accessed either declaratively or programmatically. In addition to the user-requested scripts, the ScriptManager control automatically emits in the client page any ASP.NET AJAX required script. The following example illustrates the script loading model you can use to load optional and custom scripts, even when the script is embedded in an assembly:

<asp:ScriptManager runat="server" ID="ScriptManager1">
  <Scripts>
    <asp:ScriptReference
         Name="YourCompany.ScriptLibrary.CoolUI.js"
         Assembly="YourCompany.ScriptLib" />
    <asp:ScriptReference
         Path="~/Scripts/MyLib.js" />
  </Scripts>
</asp:ScriptManager>

Table 20-4 lists the properties of the ScriptReference class by means of which you can control the loading of scripts.

You can reference script files from an assembly or from a disk file. There’s a benefit in using disk files. You gain something in performance because less work is required to load the script in memory directly from a file.

Script references obtained from embedded Web resources are served by the ScriptResource.axd HTTP handler. In ASP.NET, this handler replaces an old acquaintance, the WebResource.axd handler—a native component of ASP.NET. What’s the difference? In addition to serving script references, the ScriptResource.axd handler also appends any localized JavaScript resource types for the file and supports composite scripts.

ScriptManager allows you to combine in a single download multiple JavaScript files that you register through the <compositescript> section of the control’s markup:

<asp:ScriptManager ID="ScriptManager1" runat="server">
     <CompositeScript>
        <Scripts>
           <asp:ScriptReference Path="~/Scripts/Script1.js" />
           <asp:ScriptReference Path="~/Scripts/Script2.js" />
           <asp:ScriptReference Path="~/Scripts/Script3.js" />
        </Scripts>
    </CompositeScript>
</asp:ScriptManager>

Composite scripts reduce the number of browser requests and result in faster download time and less workload on the Web server.

One of the additional free services offered by ScriptManager that isn’t offered by the classic <script> tag is the ability to automatically link debug or release script files, as appropriate. ASP.NET uses a special naming convention to distinguish between debug and release script files. Given a release script file named script1.js, its debug version is expected to be filed as script1.debug.js.

In general, the main difference between debug and release scripts is that the release scripts remove unnecessary blank characters, comments, trace statements, and assertions. Normally, the burden of switching the links to debug and release scripts is left to the developer.

The ScriptManager control takes on this burden and, based on the aforementioned naming convention, distinguishes between debug and release scripts. The ScriptManager control picks debug scripts when the debug attribute of the <compilation> section in the web.config file is true.

Globalization is a programming feature that refers to the code’s ability to support multiple cultures. A request processed on the server has a number of ways to get and set the current culture settings. For example, you can use the Culture attribute on the @Page directive, the Culture property on the Page class, or perhaps the <globalization> section in the web.config file. How can you access the same information on the client from JavaScript?

When the EnableScriptGlobalization property is true, the ScriptManager emits proper script code that sets up a client-side global Sys.CultureInfo object that JavaScript classes can consume to display their contents in a culture-based way. Only a few methods and a few JavaScript objects support globalization. In particular, it will work for the localeFormat method of Date, String, and Number types. Custom JavaScript classes, though, can be made global by simply calling into these methods or accepting a Sys.CultureInfo object in their signatures.

The UpdatePanel control is a container control defined in the System.Web.Extensions assembly. It belongs specifically to the System.Web.UI namespace. Although it’s logically similar to the classic ASP.NET Panel control, the UpdatePanel control differs from the classic panel control in a number of respects. In particular, it doesn’t derive from Panel and, subsequently, it doesn’t feature the same set of capabilities as ASP.NET panels, such as scrolling, styling, wrapping, and content management.

The UpdatePanel control derives directly from Control, meaning that it acts as a mere Ajax-aware container of child controls. It provides no user-interface-related facilities. Any required styling and formatting should be provided through the child controls. In contrast, the control sports a number of properties to control page updates and also exposes a client-side object model. Consider the following classic ASP.NET code:

<asp:GridView ID="GridView1" runat="server"
     DataSourceID="ObjectDataSource1"
     AllowPaging="True"
     AutoGenerateColumns="False">
    <Columns>
        <asp:BoundField DataField="ID" HeaderText="ID" />
        <asp:BoundField DataField="CompanyName" HeaderText="Company" />
        <asp:BoundField DataField="Country" HeaderText="Country" />
    </Columns>
</asp:GridView>
<asp:ObjectDataSource ID="ObjectDataSource1" runat="server"
     TypeName="YourApp.DAL.Customers"
     SelectMethod="LoadAll" />

This code causes a postback each time you click to view a new page, edit a record, or sort by a column. As a result, the entire page is redrawn even though the grid is only a small fragment of it. With partial rendering, you take the preceding markup and just wrap it with an UpdatePanel control, as shown here:

<asp:UpdatePanel ID="UpdatePanel1" runat="server">
    <ContentTemplate>
       ...
    </ContentTemplate>
</asp:UpdatePanel>

In addition, you need to add a ScriptManager control to the page. That’s the essence of partial rendering. And it magically just works. Well, not just magically, but it works.

Table 20-5 details the properties defined on the UpdatePanel control that constitute the aspects of the control’s behavior that developers can govern.

A bit more explanation is needed for the IsInPartialRendering read-only Boolean property. It indicates whether the contents of an UpdatePanel control are being updated. From this description, it seems to be a fairly useful property. Nonetheless, if you read its value from within any of the handlers defined in a code-behind class, you’ll find out that the value is always false.

As mentioned, IsInPartialRendering is a property designed for control developers only. So it is assigned its proper value only at rendering time—that is, well past the PreRender event you can capture from a code-behind class. Developers creating a custom version of the UpdatePanel control will likely override the Render method. From within this context, they can leverage the property to find out whether the control is being rendered in a full-page refresh or in a partial rendering operation.

As a page author, if you just need to know whether a portion of a page is being updated as a result of an AJAX postback, you use the IsInAsyncPostBack Boolean property on the ScriptManager control.

The content of an updatable panel is defined through a template property—the ContentTemplate property. Just like any other template property in ASP.NET controls, ContentTemplate can be set programmatically. Consider the following page fragment:

<asp:ScriptManager ID="ScriptManager1" runat="server" />
<asp:UpdatePanel ID="UpdatePanel1" runat="server">
    <%-- Left empty deliberately. Will be filled out programmatically --%>
</asp:UpdatePanel>

In the PreInit event of the code-behind page, you can set the ContentTemplate programmatically, as shown here:

protected void Page_PreInit(object sender, EventArgs e)
{
    // You could also read the URL of the user control from a configuration file
    string ascx = "customerview.ascx";
    UpdatePanel1.ContentTemplate = this.LoadTemplate(ascx);
}

You are not allowed to set the content template past the PreInit event. However, at any time before the rendering stage, you can add child controls programmatically. In ASP.NET, to add or remove a child control, you typically use the Controls property of the parent control, as shown here:

UpdatePanel1.Controls.Add(new LiteralControl("Test"));

If you try to add a child control programmatically to the Controls collection of an UpdatePanel—as in the preceding code snippet—all that you get is a run-time exception. You should use the ContentTemplateContainer property instead. The reason is that what you really want to do is add or remove controls to the content template, not to the UpdatePanel directly. That’s why Controls doesn’t work and you have to opt for the actual container of the template. The following code shows how to populate the content template programmatically:

public partial class _Default : System.Web.UI.Page
{
    private Label Label1;

    protected void Page_Load(object sender, EventArgs e)
    {
        var updatePanel = new UpdatePanel();
        updatePanel.ID = "UpdatePanel1";

        // Define the button
        var button1 = new Button();
        button1.ID = "Button1";
        button1.Text = "What time is it?";
        button1.Click += new EventHandler(Button1_Click);

        // Define the literals
        var lit = new LiteralControl("<br>");

        // Define the label
        var label1 = new Label();
        label1.ID = "Label1";
        label1.Text = "[time]";

        // Link controls to the UpdatePanel
        updatePanel.ContentTemplateContainer.Controls.Add(button1);
        updatePanel.ContentTemplateContainer.Controls.Add(lit);
        updatePanel.ContentTemplateContainer.Controls.Add(label1);

        // Add the UpdatePanel to the list of form controls
        this.Form.Controls.Add(updatePanel);
    }

    protected void Button1_Click(object sender, EventArgs e)
    {
        Label1.Text = DateTime.Now.ToShortTimeString();
    }
}

You can add an UpdatePanel control to the page at any time in the life cycle. Likewise, you can add controls to an existing panel at any time. However, you can’t set the content template programmatically past the page’s PreInit event.

You can safely use UpdatePanel controls from within master pages. Most of the time, the use of updatable panels is easy and seamless. There are a few situations, though, that deserve a bit of further explanation.

If you add a ScriptManager control to a master page, partial rendering is enabled by default for all content pages. In addition, initial settings on the script manager are inherited by all content pages. What if you need to change some of the settings (for example, add a new script file or switch on script localization) for a particular content page? You can’t have a new script manager, but you need to retrieve the original one defined on the master page.

In the content page, you can declaratively reference a ScriptManagerProxy and change some of its settings. The proxy retrieves the script manager currently in use and applies changes to it.

The ScriptManagerProxy control, though, is mostly designed to let you edit the list of scripts and services registered with the manager in a declarative manner, and it doesn’t let you customize, say, error handling or script localization. You can do the same (and indeed much more) by programmatically referencing the script manager in the master page. Here’s how:

protected void Page_Init(object sender, EventArgs e)
{
    // Work around the limitations in the API of the ScriptManagerProxy control
    ScriptManager.GetCurrent(this).EnableScriptLocalization = true;
}

In the content page, you create a handler for the page’s Init event, retrieve the script manager instance using the static GetCurrent method on the ScriptManager class, and apply any required change.

By default, all updatable panels in a page are synchronized and refresh at the same time. To make each panel refresh independently from the others, you change the value of the UpdateMode property. The default value is Always, meaning that the panel’s content is updated on every postback that originates from anywhere in the page, from inside and outside the updatable region.

By changing the value of the UpdateMode property to Conditional, you instruct the updatable panel to update its content only if it is explicitly ordered to refresh. This includes calling the Update method, intercepting a postback from a child control, or handling any of the events declared as triggers.

Normally, any control defined inside of an UpdatePanel control acts as an implicit trigger for the panel. You can stop all child controls from being triggers by setting the value of ChildrenAsTriggers to false. In this case, a button inside an updatable panel, if clicked, originates a regular full postback.

What if you want only a few controls within an UpdatePanel to act as triggers? You can define them as triggers of a particular UpdatePanel, or you can use the RegisterAsyncPostBackControl method on the ScriptManager class.

The RegisterAsyncPostBackControl method enables you to register controls to perform an asynchronous postback instead of a synchronous postback, which would update the entire page. Here is an example of the RegisterAsyncPostBackControl method:

protected void Page_Load(Object sender, EventArgs e)
{
    ScriptManager1.RegisterAsyncPostBackControl(Button1);
}

The control object you pass as an argument will be a control not included in any updatable panels and not listed as a trigger. The effects of the postback that originates from the control differ with regard to the number of UpdatePanel controls in the page. If there’s only one UpdatePanel in the page, the script manager can easily figure out which one to update. The following code shows a page whose overall behavior might change if one or two UpdatePanel controls are used:

protected void Button1_Click(Object sender, EventArgs e)
{
    // If there's only one UpdatePanel in the page, and it includes this Label control,
    // the panel is refreshed automatically.
    Label1.Text = "Last update at:  " + DateTime.Now.ToLongTimeString();

    // This Label control, not included in any UpdatePanel, doesn't have its UI
    // refreshed. Its state, though, is correctly updated.
    Label2.Text = "Last update at:  " + DateTime.Now.ToLongTimeString();
}

When multiple panels exist, to trigger the update you have to explicitly invoke the Update method on the panel you want to refresh:

protected void Button1_Click(object sender, EventArgs e)
{
    Label1.Text = "Last update at:  " + DateTime.Now.ToLongTimeString();
    UpdatePanel1.Update();
}

All controls located inside of an UpdatePanel control are automatically passed as an argument to the RegisterAsyncPostBackControl method when ChildrenAsTriggers is true.

I’ve already mentioned the Update method quite a few times. It’s time to learn more about it, starting with its signature:

public void Update()

The method doesn’t take any special action itself, but is limited to requiring that the child controls defined in the content template of the UpdatePanel control be refreshed. By using the Update method, you can programmatically control when the page region is updated in response to a standard postback event or perhaps during the initialization of the page.

An invalid operation exception can be thrown from within the Update method in a couple of well-known situations. One situation is if you call the method when the UpdateMode property is set to Always. The exception is thrown in this case because a method invocation prefigures a conditional update—you do it when you need it—which is just the opposite of what the Always value of the UpdateMode property indicates. The other situation in which the exception is thrown is when the Update method is called during or after the page’s rendering stage.

So when should you use the Update method in your pages?

You resort to the method if you have some server logic to determine whether an UpdatePanel control should be updated as the side effect of an asynchronous postback—whether it is one that originated from another UpdatePanel in the page or a control registered as an asynchronous postback control.

As mentioned, you can associate an UpdatePanel control with a list of server-side events. Whenever a registered event is triggered over a postback, the panel is updated. Triggers can be defined either declaratively or programmatically. You add an event trigger declaratively using the <Triggers> section of the UpdatePanel control:

<asp:UpdatePanel runat="server" ID="UpdatePanel1">
   <ContentTemplate>
      ...
   </ContentTemplate>
   <Triggers>
      <asp:AsyncPostBackTrigger
           ControlID="DropDownList1"
           EventName="SelectedIndexChanged" />
   </Triggers>
</asp:UpdatePanel>

You need to specify two pieces of information for each trigger: the ID of the control to monitor, and the name of the event to catch. Note that the AsyncPostBackTrigger component can catch only server-side events. Both ControlID and EventName are string properties. For example, the panel described in the previous code snippet is refreshed when any of the controls in the page posts back (that is, its UpdateMode property defaults to Always) or when the selection changes on a drop-down list control named DropDownList1. (Obviously, the DropDownList1 control must have the AutoPostBack property set to true.)

By default, all child controls of an UpdatePanel that post back operate as implicit asynchronous postback triggers. You can prevent all of them from triggering a panel update by setting ChildrenAsTriggers to false. Note that when ChildrenAsTriggers is false, postbacks coming from child controls are processed as asynchronous postbacks and they modify the state of involved server controls, but they don’t update the user interface of the panel.

There might be situations in which you need to perform full, regular postbacks from inside an UpdatePanel control in response to a control event. In this case, you use the PostBackTrigger component, as shown here:

<asp:UpdatePanel runat="server" ID="UpdatePanel1">
   <ContentTemplate>
      ...
   </ContentTemplate>
   <Triggers>
      <asp:AsyncPostBackTrigger ControlID="DropDownList1"
           EventName="SelectedIndexChanged" />
      <asp:PostBackTrigger ControlID="Button1" />
   </Triggers>
</asp:UpdatePanel>

The preceding panel features both synchronous and asynchronous postback triggers. The panel is updated when the user changes the selection on the drop-down list; the whole host page is refreshed when the user clicks the button.

A PostBackTrigger component causes referenced controls inside an UpdatePanel control to perform regular postbacks. These triggers must be child elements of the affected UpdatePanel.

The PostBackTrigger object doesn’t support the EventName property. If a control with that name is causing the form submission, the ASP.NET AJAX client script simply lets the request go as usual. The ASP.NET runtime then figures out which server postback event has to be raised for the postback control by looking at its implementation of IPostBackEventHandler.

The UpdateProgress control is designed to provide any sort of feedback on the browser while one or more UpdatePanel controls are being updated. If you have multiple panels in the page, you might want to find a convenient location in the page for the progress control or, if possible, move it programmatically to the right place with respect to the panel being updated. You can use cascading style sheets (CSSs) to style and position the control at your leisure.

The user interface associated with an UpdateProgress control is displayed and hidden by the ASP.NET AJAX framework and doesn’t require you to do any work on your own. The UpdateProgress control features the properties listed in Table 20-6.

An UpdateProgress control can be bound to a particular UpdatePanel control. You set the binding through the AssociatedUpdatePanelID string property. If no updatable panel is specified, the progress control is displayed for any panels in the page. The user interface of the progress bar is inserted in the host page when the page is rendered. However, it is initially hidden from view using the CSS display attribute.

When set to none, the CSS display attribute doesn’t display a given HTML element and reuses its space in the page so that other elements can be shifted up properly. When the value of the display attribute is toggled on, existing elements are moved to make room for the new element.

If you want to reserve the space for the progress control and leave it blank when no update operation is taking place, you just set the DynamicLayout property to false.

The control displays the contents of the ProgressTemplate property while waiting for a panel to update. You can specify the template either declaratively or programmatically. In the latter case, you assign the property any object that implements the ITemplate interface. For the former situation, you can easily specify the progress control’s markup declaratively, as shown in the following code:

<asp:UpdateProgress runat="server" ID="UpdateProgress1">
    <ProgressTemplate>
        ...
    </ProgressTemplate>
</asp:UpdateProgress>

You can place any combination of controls in the progress template. However, most of the time, you’ll probably just put some text there and an animated GIF. (See Figure 20-3.)

Figure 20-3. A progress template informing users that some work is being done.

Note that the UpdateProgress control is not designed to be a gauge component, but rather a user-defined panel that the ScriptManager control shows before the panel refresh begins and that it hides immediately after its completion.

Each asynchronous postback is triggered on the client via script. The entire operation is conducted by the PageRequestManager client object, which invokes, under the hood, the XMLHttpRequest object. What kind of control do developers have on the underlying operation? If you manage XMLHttpRequest directly, you have full control over the request and response. But when these key steps are managed for you, there’s not much you can do unless the request manager supports an eventing model.

The Sys.WebForms.PageRequestManager object provides a few events so that you can customize the handling of the request and response. Table 20-7 lists the supported events that signal the main steps around an Ajax postback that partially update a page. The events are listed in the order in which they fire to the client page.

To register an event handler, you use the following JavaScript code:

var manager = Sys.WebForms.PageRequestManager.getInstance();
manager.add_beginRequest(OnBeginRequest);

The prototype of the event handler method—OnBeginRequest in this case—is shown here:

function beginRequest(sender, args)

The real type of the args object, though, depends on the event data structure. By using any of these events, you can control in more detail the steps of an asynchronous request. Let’s dig out more.

The initializeRequest event is the first in the client life cycle of an asynchronous request. The life cycle begins at the moment a postback is made that is captured by the UpdatePanel’s client-side infrastructure. You can use the initializeRequest event to evaluate the postback source and do any additional required work. The event data structure is the InitializeRequestEventArgs class. The class features three properties: postBackElement, request, and cancel.

The postBackElement property is read-only and evaluates to a DomElement object. It indicates the DOM element that is responsible for the postback. The request property (read-only) is an object of type Sys.Net.WebRequest and represents the ongoing request. Finally, cancel is a read-write Boolean property that can be used to abort the request before it is sent.

Immediately after calling the initializeRequest handler, if any, the PageRequestManager object aborts any pending async requests. Next, it proceeds with the beginRequest event and then sends the packet.

When the response arrives, the PageRequestManager object first processes any returned data and separates hidden fields, updatable panels, and whatever pieces of information are returned from the server. Once the response data is ready for processing, the PageRequestManager object fires the pageLoading client event. The event is raised after the server response is received but before any content on the page is updated. You can use this event to provide a custom transition effect for updated content or to run any clean-up code that prepares the panels for the next update. The event data is packed in an instance of the class PageLoadingEventArgs. The class has three properties: panelsUpdating, panelsDeleting, and dataItems. The first two are arrays and list the updatable panels to be updated and deleted, respectively.

The pageLoaded event is raised after all content on the page is refreshed. You can use this event to provide a custom transition effect for updated content, such as flashing or highlighting updated contents. The event data is packed in the class PageLoadedEventArgs, which has three properties: panelsUpdated, panelsDeleted, and dataItems. The first two are arrays and list the updatable panels that were just updated and deleted, respectively.

The endRequest event signals the termination of the asynchronous request. You receive this event regardless of the success or failure of the asynchronous postback.

If you want to prevent users from generating more input while a partial page update is being processed, you can also consider disabling the user interface—all or in part. To do so, you write handlers for beginRequest and endRequest events:

<script type="text/javascript">
function pageLoad()
{
   var manager = Sys.WebForms.PageRequestManager.getInstance();
   manager.add_beginRequest(OnBeginRequest);
   manager.add_beginRequest(OnEndRequest);
}
</script>

You typically use the beginRequest event to modify the user interface as appropriate and notify the user that the postback is being processed:

// Globals
var currentPostBackElem;

function OnBeginRequest(sender, args)
{
    // Get the reference to the button click (i.e., btnStartTask)
    currentPostBackElem = args.get_postBackElement();
    if (typeof(currentPostBackElem) === "undefined")
        return;
    if (currentPostBackElem.id.toLowerCase() === "btnStartTask")
    {
        // Disable the button
        $get("btnStartTask").disabled = true;
    }
}

The beginRequest handler receives event data through the BeginRequestEventArgs data structure—the args formal parameter. The class features only two properties: request and postBackElement. The properties have the same characteristics of analogous properties on the aforementioned InitializeRequestEventArgs class.

In the preceding code snippet, I disable the clicked button to prevent users from repeatedly clicking the same button.

At the end of the request, any temporary modification to the user interface must be removed. So animations must be stopped, altered styles must be restored, and disabled controls must be re-enabled. The ideal place for all these operations is the endRequest event. The event passes an EndRequestEventArgs object to handlers. The class has a few properties, as described in Table 20-8.

As you can see, when the endRequest event occurs there’s no information available about the client element that fired the postback. If you need to restore some user interface settings from inside the endRequest event handler, you might need a global variable to track which element caused the postback:

function OnEndRequest(sender, args)
{
    if (typeof(currentPostBackElem) === "undefined")
        return;
    if (currentPostBackElem.id.toLowerCase() === "btnStartTask")
    {
        $get("btnStartTask").disabled = false;
    }
}

Wouldn’t it be nice if you could visually notify users that a certain region of the screen has been updated? As you’ve seen, partial rendering improves the user experience with pages by eliminating a good number of full refreshes. If you look at it from the perspective of the average user, though, a partial page update doesn’t have a clear start and finish like a regular Web roundtrip. The user doesn’t see the page redrawn and might not notice changes in the user interface. A good pattern to employ is to use a little animation to show the user what has really changed with the latest operation. You can code this by yourself using the pair of beginRequest and endRequest events, or you can resort to a specialized component—an UpdatePanel extender control—as you’ll see in a moment.

A really user-friendly system always lets its users cancel a pending operation. How can you obtain this functionality with an UpdateProgress control? The progress template is allowed to contain an abort button. The script code injected in the page will monitor the button and stop the ongoing asynchronous call if it’s clicked. To specify an abort button, you add the following to the progress template:

<input type="button" onclick="abortTask()" value="Cancel" />

In the first place, the button has to be a client-side button. So you can express it either through the <input> element or the <button> element for the browsers that support this element. If you opt for the <input> element, the type attribute must be set to button. The script code you wire up to the onclick event is up to you, but it will contain at least the following instructions:

<script type="text/JavaScript">
function abortTask()
{
    var manager = Sys.WebForms.PageRequestManager.getInstance();
    if (manager.get_isInAsyncPostBack())
        manager.abortPostBack();
}
</script>

You retrieve the instance of the client PageRequestManager object active in the client page and check whether an asynchronous postback is going on. If so, you call the abortPostBack method to stop it.

Partial rendering doesn’t support concurrent asynchronous postbacks. This means that you are not allowed to have two asynchronous postbacks going on at the same time. Partial rendering ultimately works by bypassing the standard browser mechanism that handles an HTTP request. It hooks up the submit event of the form, cuts out the standard browser handler, and places the HTTP request using XMLHttpRequest.

The request that reaches the Web server differs from a regular ASP.NET request only because it has an extra HTTP header. The request sends in the contents of the posting form, including the view-state hidden field. The response is not pure HTML but represents a text record where each field describes the new status of a page element—update panels, hidden fields, and scripts to run on loading.

As you can see, the underlying model of partial rendering is still the model of classic ASP.NET pages. It is a sort of stop-and-go model where the user posts back, waits for a while, and then receives a new page. While waiting for the next page, there’s not much the user can do. Only one server operation per session occurs at a time. Partial rendering is only a smarter way of implementing the old model.

From a technical standpoint, the major factor that prevents multiple asynchronous postbacks is the persistence of the view-state information. When two requests go, both send out the same copy of the view state, but each reasonably returns a different view state. Which one is good for the page, then? Partial rendering takes a defensive approach, and it silently kills the ongoing request whenever a new request is placed—a last-win discipline.

By writing some JavaScript code around the BeginRequest client event, you can turn the discipline into a first-win approach, at the cost of losing the new request. It is your responsibility to queue the stopped request and run it later. This is just what some commercial Ajax frameworks do.

This fact has a clear impact on developers. In fact, you should always modify the user interface to ensure that users can’t start a second operation before the first is terminated. Otherwise, the first operation is aborted in favor of the second. This happens in any case, even when the two operations are logically unrelated.

Among other things, Ajax pages are popular because they can retrieve the client information in a timely manner. A page starts polling a remote URL, grabs fresh information, and returns it to the client for the actual display. Implemented via partial rendering, polling is subject to being interrupted when the user starts a new partial rendering operation to restart automatically at the end.

If this is not a problem for you, you can use the new Timer server control, as shown here:

<asp:Timer ID="Timer1" runat="server" Enabled="true" Interval="1000" ontick="Timer1_Tick" />
<asp:Button ID="Button1" runat="server" Text="Start task" onclick="Button1_Click" />
<asp:UpdateProgress ID="UpdateProgress1" runat="server" DynamicLayout="false">
    <ProgressTemplate>
        <img src="loading.gif" />
    </ProgressTemplate>
</asp:UpdateProgress>

<asp:UpdatePanel ID="UpdatePanel1" runat="server">
    <ContentTemplate>
        <asp:Label ID="Label1" runat="server" />
    </ContentTemplate>
    <Triggers>
        <asp:AsyncPostBackTrigger ControlID="Button1" EventName="Click" />
    </Triggers>
</asp:UpdatePanel>

<hr />

<asp:UpdatePanel ID="UpdatePanel2" runat="server">
    <ContentTemplate>
        <asp:Label ID="lblClock" runat="server" />
    </ContentTemplate>
    <Triggers>
        <asp:AsyncPostBackTrigger ControlID="Timer1" EventName="Tick" />
    </Triggers>
</asp:UpdatePanel>

The Timer control is the server counterpart of a client timer created using the window.setTimeout method. In the preceding code, the Timer control causes a postback every second as specified by the Interval property. The postback fires the Tick event. By using the timer as the trigger of an updatable panel, you can refresh the content of the panel periodically. In the code, the second UpdatePanel control just renders out a digital clock:

protected void Timer1_Tick(Object sender, EventArgs e)
{
    // Update the client UI to reflect server changes
    ...
}

The downside is that a timer-based polling system implemented over the partial rendering engine is still subject to concurrent calls and can be stopped at any time.

The HTTP façade is the list of public URLs known to, and managed by, the Ajax presentation layer. In an Ajax scenario, the presentation layer is made of only JavaScript code. All the logic you can’t or don’t want to code in JavaScript must be referenced on the server.

Public HTTP endpoints are the only point of contact between Ajax clients and server applications. You can write endpoints callable by Ajax clients using a number of technologies.

To start off, an AJAX-callable endpoint can be an .asmx ASP.NET Web service. If this is your choice, you need to configure the server ASP.NET application so that its hosted Web services can accept JSON calls in addition to, or instead of, SOAP calls.

You can also use a Windows Communication Foundation (WCF) service to contain all the logic you want to expose to Ajax clients. As you’ll see later in the chapter, though, you get only the Web WCF programming interface and, as such, only a subset of the typical WCF features. In particular, the area of security is thinned down. A common solution for ASP.NET Web Forms Ajax-enabled applications is hosting WCF services and interacting with them via JSON payloads.

If you don’t want to add WCF to your application but still need a service, you can then opt for a custom, handmade HTTP handler. An HTTP handler is just a public URL exposed by a Web application, so it can reliably serve any purpose the presentation needs to address. Compared to WCF services, plain HTTP handlers lack a lot of facilities, including the automatic JSON serialization of input and output data. (You can use the same tools that WCF uses, but that’s just not…automatic.)

A WCF services is exposed as an .svc endpoint. To be invoked from within an ASP.NET Ajax page, a service must meet a number of requirements, the strictest of which relate to the location of the endpoint and underlying platform. Ajax-enabled services must be hosted in the same domain from which the call is made. If we consider using WCF services to back an Ajax front end, the service must be hosted in an Internet Information Services (IIS) application on the same Web server as the ASP.NET application.

To support Ajax calls, you also need to expose service methods through HTTP requests and subsequently map methods to URLs. This is just what the WCF Web programming model has to offer. The WCF Web programming model enables services to support plain-old XML (POX) style messaging instead of SOAP, which is the key step to enabling the JSON calls that are typical of ASP.NET AJAX clients.

The following code snippet shows how to use the new WebGet attribute in the definition of a service contract:

[ServiceContract]
public interface ICalculator {
  [OperationContract]
  [WebGet]
  long Add(long x, long y);

  [OperationContract]
  [WebGet(UriTemplate="Sub?p1={x}&p2={y}")]
  long Subtract(long x, long y);
}

The WebGet attribute qualifies a method as a retrieval operation and enables callers to use the HTTP GET verb to invoke it. The WebGet attribute also features the UriTemplate property. You use this property to specify which URL format is accepted to invoke the method. If not otherwise specified via an explicit UriTemplate property, the URI template for a WebGet method like the aforementioned Add is the following:

theService.svc/Add?x=1&y=2

The service name is followed by the method name, and formal parameters follow in order, each with its own actual value. You can change this standard URI template by changing the method name and formal parameter names.

The WebInvoke attribute indicates that a given method has to be considered as a logical invoke operation that can be invoked using any HTTP verb, but typically the POST verb is called upon:

[ServiceContract]
public interface ICalculator {
  [OperationContract]
  [WebInvoke(Method="Post",
    RequestFormat=WebMessageFormat.Xml,
    ResponseFormat=WebMessageFormat.Json)]
  long Add(long x, long y);
}

Through the WebInvoke attribute, you can set the URI template, the method to be used to invoke the method, as well as the format for the request and response text.

To be invoked from an AJAX client, a WCF service can be configured with a specific binding model—the webHttpBinding model. The webHttpBinding model is a basic HTTP binding except that it doesn’t use SOAP. The webHttpBinding binding model is specifically created for REST scenarios. Here’s an excerpt from a sample configuration script for an AJAX-enabled WCF service:

<system.serviceModel>
  <behaviors>
    <endpointBehaviors>
      <behavior name="ajaxBehavior">
        <enableWebScript />
      </behavior>
    </endpointBehaviors>

    <serviceBehaviors>
      <behavior name="metadataBehavior">
        <serviceMetadata httpGetEnabled="true" />
      </behavior>
    </serviceBehaviors>
  </behaviors>
  ...
</system.serviceModel>

When webHttpBinding is turned on, you can also use the optional enableWebScript element, which enables the run time to generate the JavaScript proxy for the service. The proxy is a JavaScript class that makes it particularly easy to invoke the service endpoints. To invoke a service, a proxy is not strictly required, as you’ll see in the next chapter about jQuery. In addition, you might also want to publish service metadata for retrieval using an HTTP GET request.

The services hosted by the Web application must be specially configured to use the Web HTTP-specific binding model, as shown here:

<system.serviceModel>
  ...
  <services>
    <service name="Samples.TimeService"
             behaviorConfiguration="metadataBehavior">
      <endpoint contract="Samples.ITimeService"
                binding="webHttpBinding"
                behaviorConfiguration="ajaxBehavior" />
    </service>
  </services>
</system.serviceModel>

The configuration of a WCF service specifies key pieces of information—the binding model (mandatory), contract, and behavior. The binding indicates how the call is going to happen—essentially whether it will use a REST approach, a SOAP approach, or both. The contract attribute indicates which contract the endpoint is exposing. If the service class implements a single contract type, the contract attribute can be omitted in the endpoint section. Finally, the behaviorConfiguration attribute contains the name of the behavior to be used in the endpoint.

<%@ ServiceHost
    Factory="System.ServiceModel.Activation.WebScriptServiceHostFactory"
    Service="Samples.Services.TimeService" %>

The definition of the service contract for an AJAX-enabled WCF service is not different from that of any other WCF services. You use the OperationContract attribute to qualify a method as a public service method, and you use the optional WebGet and WebInvoke attributes to configure the URL template. Here’s an example:

[ServiceContract(Namespace="Samples.Services", Name="TimeService")]
public interface ITimeService
{
    [OperationContract]
    DateTime GetTime();
    [OperationContract]
    string GetTimeFormat(string format);
}

public class TimeService : ITimeService
{
    public DateTime GetTime()
    {
       return DateTime.Now;
    }
    ...
}

You should be sure to give meaningful values to the Namespace and Name properties of the ServiceContract attribute. The reason is that the concatenation of those values determines the name of the JavaScript proxy class used to access the WCF service. If you leave them blank, the JavaScript proxy for the preceding service will be named tempuri.org.ITimeService. Not really a nice or helpful name!

For AJAX-enabled WCF services, the data contract—namely, the agreement between the service and client that describes the data to be exchanged—is defined in the canonical way. You use an implicit contract for serialization, and deserialization is used for collections, primitive types, dates, enumerations, and the GUID; an explicit contract is required for custom complex types. In this case, you use the DataContract and DataMember attributes on class members to determine which members go into the serialization stream.

The primary reason for choosing ASP.NET Web services instead of WCF as the technology for building your HTTP façade is backward compatibility. You can call ASP.NET Web services from AJAX clients as long as your Web server runs the Microsoft .NET Framework 2.0 plus AJAX Extensions 1.0. For WCF services, ASP.NET 3.5 or a newer version is required.

A Web service made to measure for an ASP.NET AJAX application is similar to any other ASP.NET Web service you might write for whatever purposes. Just one peripheral aspect, though, marks a key difference. You must use a new attribute to decorate the class of the Web service that is not allowed on regular ASP.NET Web services—the ScriptService attribute. Here’s how to use it:

namespace Samples.WebServices
{
    [ScriptService]
    [WebService(Namespace = "urn:aspnet4.book/")]
    public class TimeService : System.Web.Services.WebService, ITimeService
    {
        [WebMethod]
        public DateTime GetTime()
        {
            return DateTime.Now;
        }
        ...
    }
}

Note that the ScriptService attribute simply enables AJAX callers to connect to the service; it doesn’t prevent SOAP callers from sending their packets. As a result, an ASP.NET AJAX Web service might have a double public interface: the JSON-based interface consumed by the hosting ASP.NET AJAX application, and the classic SOAP-based interface exposed to any clients, from any platforms, that can reach the service URL.

When you write an AJAX-enabled ASP.NET Web service, you have no need for a contracted interface as with WCF services. However, extracting an interface from the service class is rarely a bad idea.

public class TimeService : System.Web.Services.WebService, ITimeService
{
    [WebMethod]
    public DateTime GetTime()
    {
        return DateTime.Now;
    }
    ...
}

Public methods of the Web service class decorated with the WebMethod attribute can be invoked from the AJAX page. Any method is invoked using the HTTP POST verb and returns any value as a JSON object. You can change these default settings on a per-method basis by using an optional attribute—ScriptMethod. In particular, through the ScriptMethod attribute you can enable HTTP GET calls and use XML instead of JSON as the serialization format.

Enabling the use of the HTTP GET verb opens security holes: the service method can be invoked through a cross-site scripting attack that attaches an external script to the <script> or <img> HTML tags. These HTML elements are the sole elements allowed to access resources from outside the current domain. However, they always operate through a GET verb. This means that by keeping the HTTP GET verb disabled on your Web service method you prevent at the root any possible cross-site scripting attacks. More in general, my opinion is that you should have very good reasons to use the ScriptMethod attribute, anyway.

Finally, deriving the Web service class from System.Web.Services.WebService is not mandatory either. If you use that class as a parent, all that you gain is that you enable the service to access ASP.NET intrinsics directly without using the HttpContext.Current object as an intermediary.

Any security barrier you place around the HTTP façade at the network level (for example, a firewall) to filter outsiders would likely stop legitimate calls too. When all calls come from a plain Web browser and from the Internet, you need a reliable way to welcome legitimate users and reject outsiders.

To do so, you have to identify a piece of information that only legitimate users can easily provide. The simplest and most effective piece of information is an authentication cookie generated by the ASP.NET Forms authentication.

To protect critical services in the HTTP façade, you isolate in a reserved area of the site any ASP.NET pages that invoke a sensitive service method and any services to protect. After pages and services are placed in a protected area of the site, access to them requires that users go through a login page.

The login page gets credentials from the user and verifies whether the user is authorized to visit the page. If all is fine, the request is authorized and an authentication cookie is generated and attached to the response. From now on, any requests the user makes to the application, including requests directed at services in the HTTP façade, will bring the cookie. (See Figure 20-5.)

Figure 20-5. Legitimate users and outsiders around the HTTP façade.

In ASP.NET, login pages require that Forms authentication be turned on. Furthermore, anonymous users should be denied access to any resources within the protected area. Here’s a sample configuration script you can use:

<location path="ProtectedAreaOfTheSite">
    <system.web>
        <authorization>
            <deny users="?" />
        </authorization>
    </system.web>
</location>

If necessary, login pages can be placed on a different server and work over HTTPS. This solution, however, has no impact on the security of the HTTP façade.

Outsiders can still try to access the services via the public URL. In this case, though, because the service IIS endpoint is also placed behind an authorization section, they will receive an HTTP 401 error code (unauthorized access). The outsider call will pass only if the outsider can show a valid authentication cookie. But this can happen only if a cookie theft has occurred previously. However, this is all another problem that relates to the security of the Web site rather than to the security of the services in the HTTP façade.

The only viable alternative to using cookies and ASP.NET Forms authentication is to install client certificates on all client machines.

Should WCF and Web services do something on their own to keep outsiders off the site? If you place service endpoints behind a protected area of the site, you’re as safe as with any other ASP.NET pages based on Forms authentication. To give you an idea, if you combine Forms authentication with HTTPS you have the same security level currently used by online banking applications and payment sites.

It’s therefore safe for the middle tier to trust the upper HTTP façade and accept any calls coming down the way. However, nothing prevents you from implementing an extra check for authorization within the body of service methods. In this case, though, you need to access credentials information from within the service.

AJAX-enabled services can carry this information only via the authentication cookie or client certificates. Programmatically, a service gets user credentials via intrinsic objects of the run-time platform. ASP.NET XML Web services live within the ASP.NET runtime and have full access to the ASP.NET intrinsics, including the User object.

By default, instead, WCF service calls are processed by the WCF runtime, which lives side by side with ASP.NET, but it’s not a part of it. As a result, a WCF service method can’t access the HTTP request context and put its hands on the User object. The only possible workaround is running all the WCF services hosted by the site in ASP.NET compatibility mode.

You turn compatibility mode on in the configuration file, as shown here:

<system.serviceModel>
    <serviceHostingEnvironment aspNetCompatibilityEnabled="true" />
    ...
</system.serviceModel>

In addition, each service is required to express its explicit approval of the model. A service does this by decorating the service class—not the service contract—with the AspNetCompatibilityRequirements attribute, as shown here:

[AspNetCompatibilityRequirements(
        RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)]
public class TimeService : ITimeService
{
    ...
}

Note that, by default, a WCF service has the RequirementsMode property set to NotAllowed. If this value is not changed to either Allowed or Required, you get a run-time exception as you attempt to make a call to the service.

JSON is a text-based format specifically designed to move the state of an object across tiers. It’s natively supported by JavaScript in the sense that a JSON-compatible string can be evaluated to a JavaScript object through the JavaScript eval function. However, if the JSON string represents the state of a custom object, it’s your responsibility to ensure that the definition of the corresponding class is available on the client.

The JSON format describes the state of the object, an example of which is shown here:

{"ID"="ALFKI", "Company":"Alfred Futterkiste"}

The string indicates an object with two properties—ID and Company—and their respective, text-serialized values. If a property is assigned a nonprimitive value—say, a custom object—the value is recursively serialized to JSON, as in the code snippet shown here:

{"ID"="ALFKI",
  "Company":"Alfred Futterkiste",
  "Address":{"Street="543 Oberstr", "City"="Berlin", "Country":"Germany"} }

Services in the HTTP façade preferably receive and return HTTP packets with JSON content.

On the client, creating a JSON representation of data is your responsibility. You can either manually build the string or use some facilities to serialize a JavaScript object to JSON. Some browsers support native JSON parsing through a JSON object exposed out of the window object. Specifically, these browsers are Internet Explorer 8, Firefox 3.5, Safari 4, Chrome, Opera 10, and their newer versions. Alternatively, you can download the file json2.js, which provides analogous capabilities, from http://www.json.org.

On the server, you typically rely on the serialization capabilities of some classes in the .NET Framework to get a JSON string. You can use the JavaScriptSerializer class or the newer DataContractJsonSerializer class. Although they do it through different APIs, both classes take a .NET object and convert it to a JSON string. This step, however, is transparently performed by the WCF infrastructure after you have defined the data contracts for the service interface.

Any nonprimitive data to be sent or received via WCF methods must be marked with the DataContract attribute. Imagine you have the following service:

[ServiceContract(Namespace = "Services.Wcf")]
[AspNetCompatibilityRequirements(
        RequirementsMode = AspNetCompatibilityRequirementsMode.Allowed)]
public class CustomerService
{
    [OperationContract]
    public CustomerDTO LookupCustomer(String id)
    {
        var context = new NorthwindDataContext();
        var data = (from c in context.Customers
                    where c.CustomerID == id
                    select c).SingleOrDefault();
        if (data != null)
        {
             var dto = new CustomerDTO((Customer)data);
             return dto;
        }
        return new MissingCustomerDTO();
    }
}

The method LookupCustomer is expected to return a custom object. This object must be decorated with ad hoc DataContract attribute:

namespace Services.Wcf
{
    [DataContract]
    public class CustomerDTO
    {
        private Customer _customer;
        public CustomerDTO(Customer customer)
        {
            _customer = customer;
        }

        [DataMember]
        public string CustomerID
        {
            get { return _customer.CustomerID; }
            set { _customer.CustomerID = value; }
        }
        ...
    }
}

In this particular case, the class being used over WCF is a data-transfer object (DTO)—that is, a helper class that moves the content of domain model objects across tiers.

For years, XML has been touted as the lingua franca of the Web. Now that Ajax has become a key milestone for the entire Web, XML has been pushed to the side in favor of JSON as far as data representation over the Web is concerned.

Why is JSON preferable to XML in Ajax scenarios?

The main reason for dropping XML and SOAP in favor of JSON is that JSON is much easier to handle from within a JavaScript-powered client than any XML-based format. JSON is slightly simpler and more appropriate for the JavaScript language to process than XML. Although JSON might not be easier for humans to understand than XML—this is just my thought, by the way—it’s certainly easier for a machine to process than XML. Nothing like an XML parser is required for JSON. Everything you need to parse the text is built into the JavaScript language. JSON is also less verbose than XML, and less ambitious too. JSON, in fact, is not as good as XML for interoperability purposes.

The JSON syntax is not perfect either. The industrial quantity of commas and quotes it requires makes it a rather quirky format. But can you honestly say that XML is more forgiving?

With JSON, you also gain a key architectural benefit at a relatively low cost. You always reason in terms of objects instead of dealing with untyped Document Object Model (DOM) trees. On the server, you define your entities and implement them as classes in your favorite managed language. When a service method needs to return an instance of any class, the state of the object is serialized to JSON and travels over the wire. On the client, the JSON string is received and processed, and its contents are loaded into an array, or a kind of mirror JavaScript object, with the same interface as the server class. The interface of the class is inferred from the JSON stream. In this way, both the service and the client page code use the same logical definition of an entity.

Obviously, from a purely technical standpoint, the preservation of the data contract doesn’t strictly require JSON to be implemented. You could get to the same point using XML as well. In that case, though, you need to get yourself an XML parser that can be used from JavaScript.

Parsing some simple XML text in JavaScript might not be an issue, but getting a full-blown parser is another story completely. Performance and functionality issues will likely lead to a proliferation of similar components with little in common. And then you must decide whether such a JavaScript XML parser should support things such as namespaces, schemas, white spaces, comments, and processing instructions.

As I see it, for the sake of compatibility you will end up with a subset of XML limited to nodes and attributes. At that point, it’s merely a matter of choosing between the angle brackets of XML and the curly brackets of JSON. Additionally, JSON has a free parser already built into the JavaScript engine—the aforementioned function eval.

Also labeled as the fat-free alternative to XML, JSON has ultimately been a very convenient choice for architects of Web frameworks and is today the real currency exchanged by browsers and Ajax-enabled services.

When you add a Web or WCF service to a classic Web application project or to a Windows Forms project, you go through a Visual Studio wizard, indicate the URL of the service, specify the desired namespace, and finally have the wizard generate a proxy class and add it in the folds of the project solution.

When you add a reference to Web or WCF services to an ASP.NET AJAX page, no Visual Studio wizard will be there to silently invoke an SDK tool that automagically creates the proxy class. In the first place, you don’t add a service reference through the Web project. Instead, you programmatically add the service reference to the ASP.NET page, as shown here:

<asp:ScriptManager ID="ScriptManager1" runat="server">
    <Services>
        <asp:ServiceReference Path="appAjaxLayer.svc" />
        ...
    </Services>
</asp:ScriptManager>

The script manager emits the following markup:

<script src="appAjaxLayer.svc/js" type="text/javascript"></script>

If you’re testing your page and have debug mode set in the web.config file, the suffix to the service URL will be /jsdebug instead of /js.

The /js suffix is the magic word that instructs the service infrastructure to generate a JavaScript proxy class for the client code to call the service. In particular, for WCF services the enableWebScript attribute of the endpoint behavior enables the generation of the proxy; subsequently, it enables the service to be scripted from an Ajax client.

The JavaScript proxy class is named according to different rules for Web and WCF services. For Web services, the proxy gets the exact fully qualified name of the class behind the .asmx endpoint. For WCF services, the name of the proxy class is determined by the concatenation of the Namespace and Name properties specified in the ServiceContract attribute you’re targeting. Note, therefore, that when you call a WCF service method you’re actually calling a method defined on a contract. To invoke a WCF service, it’s the contract that matters, not the class that implements it. In fact, the same service class can implement multiple contracts.

After you have the JavaScript proxy, invoking the Web or WCF service is nearly the same thing. The proxy object comes as a singleton and exposes the same set of contracted methods you have on the original service. The communication model is asynchronous and requires you to specify at least a callback function to use in case of successful execution. Here’s an example:

// Async call of method GetQuotes with a callback
Samples.Services.FinanceInfoService.GetQuotes(symbols, onDataAvailable);

The code can refer to a Web service as well as a WCF service. If it refers to a Web service, the Web service class is named Samples.Services.FinanceInfoService; if it refers to a WCF service, the namespace of the service contract might be Samples.Services and the name of the contract might be FinanceInfoService. The preceding code snippet invokes the method GetQuotes.

In addition to the regular list of parameters for the service method, each proxy method can take up to three extra parameters. The first extra parameter is mandatory and represents the callback to invoke if the method execution is successful. The second and third optional parameters indicate, respectively, the callback to use in case of failure and a state object to pass to both callbacks. In the code snippet just shown, the onDataAvailable parameter refers to a JavaScript callback to call only if the method executes successfully.

The signature of the success and failure callbacks is similar, but the internal format of the results parameter can change quite a bit. Here’s the callback signature:

function method(results, context, methodName)

Table 20-9 provides more details about the various arguments.

The JavaScript proxy exposes a number of properties and methods for you to configure. The list is presented in Table 20-10.

If you set a “default succeeded” callback, you don’t have to specify a “succeeded” callback in any successive call as long as the desired callback function is the same. The same holds true for the failed callback and the user context object. The user context object is any JavaScript object, filled with any information that makes sense to you, that gets passed automatically to any callback that handles the success or failure of the call.

If you don’t feel like using Web or WCF services, a quick solution to expose Ajax-callable endpoints is based on page methods. Page methods are simply public, static methods exposed by the code-behind class of a given ASP.NET page. The run-time engine for page methods and Ajax-enabled Web services is nearly the same. Using page methods saves you from the burden of creating and publishing a service; at the same time, though, it binds you to having page-scoped methods that can’t be called from within a page different from the one where they are defined.

Public and static methods defined on a page’s code-behind class and flagged with the WebMethod attribute transform an ASP.NET page into a Web service. Here’s a sample page method:

public class TimeServicePage : System.Web.UI.Page
{
    [WebMethod]
    public static DateTime GetTime()
    {
        return DateTime.Now;
    }
}

You can use any data type in the definition of page methods, including .NET Framework types as well as user-defined types. All types will be transparently JSON-serialized during each call.

Alternatively, you can define Web methods as inline code in the .aspx source file as follows (and if you use Visual Basic, just change the type attribute to text/VB):

<script type="text/C#" runat="server">
    [WebMethod]
    public static DateTime GetTime()
    {
        return DateTime.Now;
    }
</script>

Page methods are specific to a given ASP.NET page. Only the host page can call its methods. Cross-page method calls are not supported. If they are critical for your scenario, I suggest that you move to using Web or WCF services.

When the code-behind class of an ASP.NET AJAX page contains WebMethod-decorated static methods, the run-time engine emits a JavaScript proxy class nearly identical to the class generated for a Web or WCF service. You use a global instance of this class to call server methods. The name of the class is hard-coded to PageMethods. Its usage is nearly identical to the proxy for Web or WCF services.

function getTime()
{
    PageMethods.GetTime(methodCompleted);
}
function methodCompleted(results, context, methodName)
{
    // Format the date-time object to a more readable string
    var displayString = results.format("ddd, dd MMMM yyyy");
    document.getElementById("Label1").innerHTML = displayString;
}

Note, however, that page methods are not enabled by default. In other words, the PageMethods proxy class that you use to place remote calls is not generated unless you set the EnablePageMethods property to true in the page’s script manager:

<asp:ScriptManager runat="server" ID="ScriptManager1" EnablePageMethods="true" />

For the successful execution of a page method, the ASP.NET AJAX application must have the ScriptModule HTTP module enabled in the web.config file:

<httpModules>
  <add name="ScriptModule"
     type="System.Web.Handlers.ScriptModule, System.Web.Extensions" />
</httpModules>

For page method calls, therefore, there’s no page life cycle and child controls are not initialized and processed.