Documentation for: ASP.NET Ajax Version 1.0

This documentation is for a previous version. For the current released version, see the ASP.NET Ajax documentation on MSDN.








ASP.NET AJAX Debugging and Tracing Overview


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


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:


You can use the following approaches to debug an ASP.NET AJAX application 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.

Back to top


The ASP.NET AJAX architecture provides a model for release and debug modes. Release mode provides error checking and exception handling 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 your client scripts 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 while minimizing the size of release code.

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

    <compilation debug="true">
      <!-- etc. -->

When debugging is enabled, ASP.NET AJAX uses a debug version of the client libraries.

Setting the Application from Debug to Release Mode for Deployment

When you deploy a release version of an AJAX-enabled ASP.NET application, make sure that it is set to release mode. This makes sure that ASP.NET uses the performance-optimized release version of the ASP.NET AJAX libraries. If you have created debug and release versions of your custom scripts 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 ASP.NET AJAX applications. 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.


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

Microsoft AJAX Library 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.


Clears all trace messages from the TraceConsoletextarea element.

Sys.Debug.traceDump(object, name)

Dumps an object to the debugger console and to the TraceConsoletextarea element, if available.

Displays a message in the debugger's output window and breaks into the debugger.


Appends a text line to the debugger console and to the TraceConsoletextarea element, if available.

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

Configuring Internet Explorer for Debugging

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

To enable debugging in Internet Explorer

  1. In the Tools menu, click Internet Options.

  2. In the Advanced tab, clear the Disable Script Debugging (Internet Explorer) check box and the Disable Script Debugging (Other) check box.

  3. Select the Display a notification about every script error check box.

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


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 ASP.NET AJAX applications 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 Visual Studio Script Explorer window. (To display this window, in the Debug menu, click Windows, and then click Script Explorer). The ASP.NET AJAX client library will appear as a resource starting with ScriptResource.axd?..., which the server generates dynamically from the ASP.NET AJAX assembly. A known bug 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 method. When you call this method, the debugger will stop on the call to 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 AJAX uses. 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.

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:

  • Fire B ug 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 running on port 8888 on the local computer. For more information, see the "Configuring Clients" page on the Fiddler Web site.

Back to top

Class Reference

Debug Class

Provides methods that define breakpoints and handle trace output.