Debugging and Tracing Ajax Applications Overview

Article
12/04/2014

ASP.NET WebForms based applications contain a mix of server code and client code. The browser can also request additional data asynchronously. This can make debugging WebForms based applications that use Ajax challenging. This overview discusses some techniques and tools that can help you debug your code more easily.

Note

With the exception of Visual Studio and Internet Explorer, the programs mentioned in this topic are third-party tools and are not supported by Microsoft. Please see the tool's Web site for licensing and support information.

This topic contains:

Scenarios
Background
Class Reference

Scenarios

You can use the following approaches to debug a WebForms based application that uses Microsoft Ajax at different stages of development:

Enable debugging in the configuration file.
Use tracing on the server.
Use the methods of the Sys.Debug class to set breakpoints and handle trace output.
Enable debugging in your browser.
Attach the Visual Studio debugger to your Internet Explorer instance, or use external tools to debug in other browsers.
Use external tools to capture HTTP traffic.

Background

The Microsoft Ajax architecture provides a model for release and debug modes. Release mode provides error checking and exception handling that is optimized for performance, with minimized script size. Debug mode provides more robust debugging features, such as type and argument checking. If you create debug versions of client script files or script resources, ASP.NET runs the debug versions when the application is in debug mode. This enables you to throw exceptions in debug scripts but still keep the size of release code to a minimum.

A debug helper class, Sys.Debug, provides methods for displaying objects in readable form at the end of a Web page. It also shows trace messages, enables you to use assertions, and lets you break into the debugger. An extended Error object API provides helpful exception details with support for release and debug modes.

The following sections provide detail about the techniques and tools that you can use for debugging and tracing.

Configuring the Application for Debugging

To enable debugging, add a compilation element to the site's root Web.config file, and then set its debug attribute to true. For more information, see compilation Element (ASP.NET Settings Schema).

The following example shows a section from a Web.config file that has the debug attribute set for debugging.

<configuration>
  <system.web>
    <compilation debug="true">
      <!-- etc. -->
    </compilation>
  </system.web>
<configuration>

When debugging is enabled, ASP.NET uses a debug version of the Microsoft Ajax Library and debug versions of your custom client script files, if available.

Setting the Application from Debug to Release Mode for Deployment

When you deploy a release version of an WebForms application that uses Microsoft Ajax, set the application to release mode. This makes sure that ASP.NET uses the performance-optimized release version of the Microsoft Ajax libraries. If you have created debug and release versions of your custom script files and script resources, ASP.NET also uses the release versions. To set the application to release mode, do the following:

In the Web.config file, if the compilation element contains a debug attribute, make sure that the debug attribute is set to false.
Make sure that any Web page that contains a ScriptManager control has its ScriptMode property set to Release.

The debug attribute of the @ Page directive does not affect WebForms based applications that use Microsoft Ajax. The ScriptManager control uses only the settings in the Web.config file and in its IsDebuggingEnabled and ScriptMode properties to determine whether to render debug scripts.

Tracing on the Server

If you are using tracing on the server to debug Web pages that have partial-page rendering enabled, you should use the trace viewer (Trace.axd) to display trace output. You can append trace output to the end of the page, and it is displayed the first time the page is rendered. However, the trace display is not updated as a result of asynchronous postbacks, because only the contents of UpdatePanel controls that have to be refreshed will change. For more information about how to use the trace viewer, see ASP.NET Tracing Overview.

Note

Partial-page rendering is enabled when the page contains a ScriptManager control with its EnablePartialRendering property set to true. The page must also contain one or more UpdatePanel controls.

Debug Helper Class

ASP.NET provides the Sys.Debug class for debugging client applications. By calling methods of the Sys.Debug class, you can display objects in readable form at the end of the page, show trace messages, use assertions, and break into the debugger.

If you are using Visual Studio and Internet Explorer, you can attach the Visual Studio debugger to the browser and view debugger trace messages in the Output window. If you are not using Visual Studio, you can view debugger trace messages in Internet Explorer by creating a textarea element on the page and setting its ID to TraceConsole. In Mozilla Firefox, you can view debugger trace messages by using tools that are available as extensions. The Apple Safari and Opera browsers display trace messages in their respective debugging consoles.

The following table lists the methods of the Sys.Debug class.

Sys.Debug.assert(condition, message, displayCaller)
Checks for a condition, and if the condition is false, displays a message and prompts the user to break into the debugger.
Sys.Debug.clearTrace()
Clears all trace messages from the TraceConsole textarea element.
Sys.Debug.traceDump(object, name)
Dumps an object to the debugger console and to the TraceConsole textarea element, if available.
Sys.Debug.fail(message)
Displays a message in the debugger's output window and breaks into the debugger.
Sys.Debug.trace(text)
Appends a text line to the debugger console and to the TraceConsole textarea element, if available.

The following example shows how to call methods of the Sys.Debug class:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "https://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="https://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
    <title>Untitled Page</title>
<script language="javascript" type="text/javascript">
function btnAssert_onclick() {
    var n;
    // Insert code intended to set n to a positive integer.
    if (false) n = 3;
    // Assert if n is not greater than 0.
    Sys.Debug.assert(n > 0, "n must be set to a positive integer.");
}

function btnFail_onclick() {
    var n;
    // Insert code intended to set n to a numeric value.
    if (false) n = 3;
    // Fail if n is not numeric.
    if (isNaN(n)) Sys.Debug.fail("The value of n must be a number.");
}

function btnTrace_onclick() {
    v = form1.text1.value;
    Sys.Debug.trace("Name set to " + "\"" + v + "\".");
    alert("Hello " + v + ".");
}

function btnDump_onclick() {
    Sys.Debug.traceDump(form1.text1, "Name textbox");
    alert("Hello " + form1.text1.value + ".");
}

function btnClear_onclick() {
    Sys.Debug.clearTrace()
    alert("Trace console cleared.");
}
</script>
</head>
<body>
<form id="form1" runat="server">
    <h2>Sys.Debug Methods Test Page</h2>
    <asp:ScriptManager ID="ScriptManager1" 
        runat="server" />
    <p><b>Use these buttons to demonstrate the assert() and fail() 
    methods:</b><br />
    <input id="btnAssert" type="button" value="Assert" 
        style="width: 100px" 
        onclick="return btnAssert_onclick()" /> &nbsp
    <input id="btnFail" type="button" value="Fail" 
        style="width: 100px" onclick="return btnFail_onclick()" />
    </p><hr />
    <b>Use the textbox and buttons below to demonstrate tracing.</b>
    <br />
    <p>Enter your name here:<br />
    <input id="text1" maxlength="50" type="text" />
    <br />
    <br />
    <input id="btnTrace" type="button" value="Trace" 
        style="width: 100px" onclick="return btnTrace_onclick()" /><br />
    <input id="btnDump" type="button" value="TraceDump" 
        style="width: 100px" onclick="return btnDump_onclick()" /><br />
    <input id="btnClear" type="button" value="ClearTrace" 
        style="width: 100px" onclick="return btnClear_onclick()" /><br />
    <br /></p>
    View output in the TraceConsole textarea below.
    <br />
    <textarea id='TraceConsole' rows="10" cols="50" 
        title="TraceConsole"></textarea>
</form>
</body>
</html>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "https://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="https://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
    <title>Untitled Page</title>
<script language="javascript" type="text/javascript">
function btnAssert_onclick() {
    var n;
    // Insert code intended to set n to a positive integer.
    if (false) n = 3;
    // Assert if n is not greater than 0.
    Sys.Debug.assert(n > 0, "n must be set to a positive integer.");
}

function btnFail_onclick() {
    var n;
    // Insert code intended to set n to a numeric value.
    if (false) n = 3;
    // Fail if n is not numeric.
    if (isNaN(n)) Sys.Debug.fail("The value of n must be a number.");
}

function btnTrace_onclick() {
    v = form1.text1.value;
    Sys.Debug.trace("Name set to " + "\"" + v + "\".");
    alert("Hello " + v + ".");
}

function btnDump_onclick() {
    Sys.Debug.traceDump(form1.text1, "Name textbox");
    alert("Hello " + form1.text1.value + ".");
}

function btnClear_onclick() {
    Sys.Debug.clearTrace()
    alert("Trace console cleared.");
}
</script>
</head>
<body>
<form id="form1" runat="server">
    <h2>Sys.Debug Methods Test Page</h2>
    <asp:ScriptManager ID="ScriptManager1" 
        runat="server" />
    <p><b>Use these buttons to demonstrate the assert() and fail() 
    methods:</b><br />
    <input id="btnAssert" type="button" value="Assert" 
        style="width: 100px" 
        onclick="return btnAssert_onclick()" /> &nbsp
    <input id="btnFail" type="button" value="Fail" 
        style="width: 100px" onclick="return btnFail_onclick()" />
    </p><hr />
    <b>Use the textbox and buttons below to demonstrate tracing.</b>
    <br />
    <p>Enter your name here:<br />
    <input id="text1" maxlength="50" type="text" />
    <br />
    <br />
    <input id="btnTrace" type="button" value="Trace" 
        style="width: 100px" onclick="return btnTrace_onclick()" /><br />
    <input id="btnDump" type="button" value="TraceDump" 
        style="width: 100px" onclick="return btnDump_onclick()" /><br />
    <input id="btnClear" type="button" value="ClearTrace" 
        style="width: 100px" onclick="return btnClear_onclick()" /><br />
    <br /></p>
    View output in the TraceConsole textarea below.
    <br />
    <textarea id='TraceConsole' rows="10" cols="50" 
        title="TraceConsole"></textarea>
</form>
</body>
</html>

Configuring Internet Explorer for Debugging

By default, Internet Explorer ignores problems that it encounters in JavaScript. You can enable debugging by using the following procedure.

To enable debugging in Internet Explorer

In the Tools menu, click Internet Options.
In the Advanced tab, clear the Disable Script Debugging (Internet Explorer) check box and the Disable Script Debugging (Other) check box.
Select the Display a notification about every script error check box.
To turn off "friendly" error messages, clear the Show friendly HTTP error messages check box.

If "friendly" error message are enabled and if an HTTP 500 error response from the server is less than 513 bytes long, Internet Explorer masks the content. In place of the error information, Internet Explorer displays a message that is meant for end users, not developers.

Attaching the Visual Studio Debugger to Internet Explorer

To debug client script, you must attach a debugger to Internet Explorer. In Visual Studio, if you start your application for debugging (by pressing F5 or using the Start Debugging command in the Debug menu), the debugger is attached automatically.

You can also attach the Visual Studio debugger to Internet Explorer when the application is already running. To do so, in the Debug menu, click Attach to Process.... In the Attach to Process dialog box, select the instance of Internet Explorer (iexplore.exe) that you want to attach the debugger to.

Note

If Internet Explorer is configured for debugging, the Type column for the relevant instance of Internet Explorer displays Script, x86. If you see only x86 in the Type column, make sure that Internet Explorer is configured for debugging.

If Internet Explorer encounters a script error and is configured for script debugging, but it is not currently attached to a debugger, the browser prompts you to select a debugger. You can either continue without debugging or attach a debugger and step through the code.

Internet Explorer Known Debugging Issues and Workarounds

When you debug WebForms based applications that use Microsoft Ajax that use Internet Explorer, be aware of the following issues and workarounds:

After the Visual Studio debugger is attached to Internet Explorer, you can see a list of the scripts that are being debugged in the Script Explorer window. (To display this window, in the Debug menu, click Windows, and then click Script Explorer). The Microsoft Ajax Library will appear as a resource starting with ScriptResource.axd?..., which the server generates dynamically from the Microsoft Ajax assembly. A known issue in Visual Studio might prevent you from opening the file. If Visual Studio displays an error message to that effect, or if it ignores clicks on the file name, close all script files that are open. You can then open the page and select the script files that you want to debug.
You cannot set breakpoints in JavaScript code inside script elements in an ASP.NET page until after the debugger has stepped into JavaScript code on that page. To work around this issue, set the breakpoint on the function that the call comes from, and step into the code on the ASP.NET Web page. After the debugger has stopped on a line of JavaScript code in the page, you can set breakpoints as usual. Another way to have the debugger recognize scripts in an ASP.NET page is to create a method in the ASP.NET page file that calls the Sys.Debug.fail method. When you call this method, the debugger will stop on the call to Sys.Debug.fail and let you set breakpoints elsewhere. A third alternative is to put all your custom code in external JavaScript files.
Visual Studio enables you to set breakpoints on the first line of a regular JavaScript function, but not on the first line of anonymous methods, which ASP.NET uses in AJAX libraries. If an anonymous method contains only one line of code, or if you must set a breakpoint on the first line of an anonymous method, insert a dummy line of code. You can then set the breakpoint on the second line of the method.

IIS 7.0 Known Issues

When you run WebForms based pages that use Microsoft Ajax by using IIS 7.0 on Windows Vista, and when the managed pipeline mode is set to Integrated, the scripts processed by the ScriptResourceHandler class are not cached. However, the scripts are cached when the managed pipeline mode is set to Classic.

For more information about the managed pipeline mode of IIS 7.0, see Upgrading ASP.NET Applications to IIS 7.0: Differences between IIS 7.0 Integrated Mode and Classic Mode.

Capturing HTTP Traffic

When you develop Web applications, it is often useful to monitor the HTTP traffic between the server and the client. A tool that can perform this task is Fiddler, which you can get from the Fiddler PowerToy page on the MSDN Web site. Fiddler runs as a proxy that logs all HTTP traffic. It supports Internet Explorer and other browsers. By using Fiddler, you can examine each request and response, which includes headers, cookies, and message contents.

Debugging in Mozilla Firefox

Mozilla Firefox is not integrated with the Visual Studio debugger. As a result, you cannot use the Visual Studio debugger to step through client code that is running in Firefox. However, Firefox supports some debugging functionality, such as a JavaScript console. You can also install the following extensions available from Mozilla that can enhance your debugging capabilities:

FireBug enables you to step through client script and examine HTML DOM elements. It also provides a script console, a command line, and other tools.
The JavaScript Debugger (also known as "Venkman") provides a JavaScript debugging environment that includes a source-code browser and other features.
The Web Developer extension enables you to inspect the DOM and CSS styles.

Fiddler also works with Firefox. However, you must configure Firefox to route HTTP requests through the proxy that is running on port 8888 on the local computer. For more information, see the "Configuring Clients" page on the Fiddler Web site.

Class Reference

Sys.Debug Class
Provides methods that define breakpoints and handle trace output.

Debugging and Tracing Ajax Applications Overview

Scenarios

Background

Configuring the Application for Debugging

Setting the Application from Debug to Release Mode for Deployment

Tracing on the Server

Debug Helper Class

Configuring Internet Explorer for Debugging

To enable debugging in Internet Explorer

Attaching the Visual Studio Debugger to Internet Explorer

Internet Explorer Known Debugging Issues and Workarounds

IIS 7.0 Known Issues

Capturing HTTP Traffic

Debugging in Mozilla Firefox

Class Reference

See Also

Tasks

Concepts

Other Resources

Additional resources