Debug and Release Scripts

ASP.NET AJAX ships with debug and release versions of client script files that drive functionality in AJAX-enabled pages. These scripts are installed at C:\Program Files\Microsoft ASP.NET\ ASP.NET 2.0 AJAX Extensions\[Version]\MicrosoftAJAXLibrary\System.Web .Extensions\[Version] on the web server. The debug scripts are placed in a folder named Debug, while the release scripts are placed in a folder named Release. Understanding how to switch between these different script versions can simplify the process of debugging ASP.NET AJAX applications and make it easier to step through Microsoft’s client script files as well as any custom script files you may write.

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.

Open table as spreadsheet

Member	Description
Auto	The client script files to use are determined at runtime based upon configuration settings in web.config and machine.config. If the deployment element’s retail attribute is set to false (the default) and the page element’s debug attribute is set to true, debug scripts are used. Otherwise, release scripts are used.
Inherit	When applied directly to the ScriptManager control, it is the same as using Auto. When applied to a ScriptReference object (nested in a ScriptManager control), the settings are inherited from the ScriptManager control’s ScriptMode property.
Debug	Debug versions of the client script files are loaded into an AJAX-enabled page and used by the framework. This setting is overridden if the deployment element’s retail attribute is set to true in machine.config, in which case release scripts are used.
Release	Release versions of the client script files are loaded into an AJAX-enabled page and used by the framework.

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 website 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 9-1.

Listing 9-1

<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 9-2.

Listing 9-2

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

Because the debug scripts in the ASP.NET AJAX Library 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 9-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.

Listing 9-3

<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 9-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 9-4 shows how ScriptMode settings can be inherited from the ScriptManager.

Listing 9-4

<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.