|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer|
Debugging and Tracing AJAX Applications Overview
AJAX-enabled ASP.NET 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 AJAX-enabled ASP.NET 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 2008 debugger to your Internet Explorer instance, or use external tools to debug in other browsers.
Use external tools to capture HTTP traffic.
The ASP.NET 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 AJAX-enabled ASP.NET application, set the application to release mode. This makes sure that ASP.NET uses the performance-optimized release version of the 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.
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 Overview.
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.
The following example shows how to call methods of the Sys.Debug class:
Configuring Internet Explorer for Debugging
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.
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 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 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.
IIS 7.0 Known Issues
When you run ASP.NET AJAX-enabled pages 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
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 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.