15.1. Debug and Release Scripts

ASP.NET 3.5 ships with debug and release versions of client script files that drive functionality in AJAX-enabled pages. The scripts are embedded in the System.Web.Extensions.dll assembly (which is installed in the Global Assembly Cache) as resources. Figure 15-1 shows what the script resources look like when viewed in Reflector (download Reflector from www.red-gate.com/products/reflector/index.htm).

Understanding how to switch between debug and release scripts can simplify the process of debugging ASP.NET AJAX applications and make it easier to step through Microsoft's client-side script files as well as any custom script files you may write.

Figure 15-1. Figure 15-1

To tell the ASP.NET AJAX framework which version of the library scripts you want to use, you have to set the ScriptManager's ScriptMode property to one of four values defined in a ScriptMode enumeration, as shown in the following table.

If you don't specify a value for the ScriptManager's ScriptMode property, it defaults to Auto. In this case, the control looks at the compilation element's debug attribute value in web.config as well as the deployment element's retail attribute value in machine.config. The following example shows how to define the compilation element and associated debug attribute in web.config.

<system.web>
    <! --  Debug scripts will be used when ScriptMode is Auto  -- >
    <compilation debug="true" />
</system.web>

By letting the ScriptManager controls within a Web site default to Auto, you can easily control which client scripts are loaded by simply changing the debug attribute in web.config. When the ScriptMode property is set to Auto and the debug attribute in web.config is set to true, debug versions of client scripts will be loaded and used. When debug is set to false, release versions of the client script files will be loaded and used.

You can force release scripts to be loaded even when the debug attribute is set to true in web.config by changing the ScriptMode to Release, as shown in Listing 15-1.

Example 15-1. Using the ScriptMode property to load release scripts

<asp:ScriptManager ID="ScriptManager1" runat="server" ScriptMode="Release">
      <scripts>
         <asp:ScriptReference Path="~/Scripts/Album.js" />
      </scripts>
</asp:ScriptManager>

Conversely, debug scripts can be loaded regardless of the debug value in web.config by setting the ScriptMode to Debug, as shown in Listing 15-2.

Example 15-2. Using the ScriptMode property to load debug scripts

<asp:ScriptManager ID="ScriptManager1" runat="server" ScriptMode="Debug">
      <scripts>
         <asp:ScriptReference Path="~/Scripts/Album.js" />
      </scripts>
</asp:ScriptManager>

Because the ASP.NET AJAX debug scripts have nicely formatted code that is easy to read and step through, you'll want to set the ScriptMode to Debug (or Auto and change the debug attribute in web.config to true) while working through application problems. Although you can use the release client scripts during development, they have all formatting stripped out and are more difficult to use for debugging purposes.

In addition to loading ASP.NET AJAX client script files, the ScriptManager control can be used to load custom script files. This is done using the ScriptManager's Scripts property, as shown in Listing 15-3. Custom scripts are loaded by adding a ScriptReference component within a Scripts tag inside of the ScriptManager control. ScriptReference defines the path to the script as well as the ScriptMode. One key advantage of loading script code this way is to let you load different scripts depending on whether the application is running in Debug mode or not.

Example 15-3. Using the ScriptMode property to load the debug version of a custom script

<asp:ScriptManager ID="ScriptManager1" runat="server">
      <Scripts>
         <asp:ScriptReference Path="~/Scripts/Album.js" ScriptMode="Debug" />
      </Scripts>
</asp:ScriptManager>

If you're loading custom scripts using the ScriptReference component, you must notify the ScriptManager when the script has finished loading by adding the following code at the bottom of the script:

if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded ();

Because the ScriptMode attribute is set to a value of Debug in Listing 15-3, the ScriptManager control will automatically look for a file named Album.debug.js instead of Album.js. If the file is not found, an error will be raised.

Having both release and debug versions of a script can be useful in some situations. For example, the release version of the script may have all whitespace stripped out of it to minimize its size, while the debug script may be formatted nicely to make it easy to step through; plus, it may contain additional debugging statements to help you isolate problems. Microsoft follows this practice with the client scripts used in the ASP.NET AJAX Library.

When the ScriptMode property is set to Inherit on the ScriptReference component, the correct version of the custom script to load (debug or release) will be determined by the value defined on the ScriptManager's ScriptMode property. In other words, the ScriptReference's ScriptMode value will be inherited from the ScriptManager's ScriptMode. Listing 15-4 shows how ScriptMode settings can be inherited from the ScriptManager.

Example 15-4. Using the ScriptMode property's Inherit member

<asp:ScriptManager ID="ScriptManager1" runat="server" ScriptMode="Debug">
      <Scripts>
         <asp:ScriptReference Path="~/Scripts/Album.js" ScriptMode="Inherit" />
      </Scripts>
</asp:ScriptManager>

Now that you've seen how debug and release client scripts can be loaded, let's examine the ASP.NET AJAX Library classes that can be used in various debugging situations.