HOW TO: Troubleshoot ASP.NET Web Applications (815166)


The information in this article applies to:

  • Microsoft ASP.NET (included with the .NET Framework) 1.0
  • Microsoft Windows 2000 Server
  • Microsoft Internet Information Server 5.0
  • Microsoft ASP.NET (included with the .NET Framework 1.1)

IN THIS TASK

SUMMARY

This step-by-step article describes how to troubleshoot ASP.NET Web applications. ASP.NET applications run differently than earlier Web applications. Therefore, ASP.NET applications require different techniques for isolating and for resolving problems. This article describes, at a high-level, the processes that you can use to identify and to troubleshoot issues that involve ASP.NET applications. These procedures apply only to ASP.NET applications that run on a Windows 2000 system with IIS 5.0 and the .NET Framework installed.

back to the top

Verify That ASP.NET Handles the Request

The first step to troubleshoot a problem with an ASP.NET application is to identify whether the request fails before ASP.NET begins to process that request. Then, you must make sure that ASP.NET is configured correctly to process the request. You must start by identifying a request URL that causes the error condition, such as /path/requestname.aspx.
  1. On the taskbar click start, point to Settings, and then click Control Panel.
  2. Double-click the Administrative Tools folder on the server and then double-click to run the Internet Services Manager tool.
  3. Expand the tree in the left pane and then identify the virtual server and the virtual folder that will handle the request.
  4. Right-click the virtual server or the virtual folder and then click Properties.
  5. Click the Home Directory or the Directory tab. Under Application Settings, click Configuration.
  6. On the App Mappings tab, scroll through the Application Mappings list to identify the extensions that are associated with the problematic request. If the extensions appear, verify that they are associated with %SystemRoot%\Microsoft.NET\Framework\%VersionNumber%\aspnet_isapi.dll. If the extensions do not appear, then the request is not handled by ASP.NET. If you want the request to be handled by ASP.NET, enable ASP.NET for that virtual directory.
  7. Click OK until you return to Internet Services Manager and then close Internet Services Manager

back to the top

View Detailed Error Information

After you determine that IIS can pass the request to ASP.NET, you must then determine the nature of the error. When <customErrors> is disabled, ASP.NET returns a browser-friendly page that describes the error. When <customErrors> is enabled, ASP.NET does not show detailed error information. To disable custom errors follow these steps:
  1. Create a backup copy of the Web.config file in the root directory of the application.

    You can restore this file after you troubleshoot the problem.
  2. Open the Web.config file in a text editor such as Notepad. The Web.config file is located in the root directory of the application.
  3. In the Web.config file locate the <customErrors> configuration element. If the <customErrors> element does not exist, add the <customErrors> element under the <system.web> element.
  4. Set the customErrors mode to off as follows:
    <system.web>
    <customErrors mode="Off">
    </customErrors> 
</system.web>
  5. Save the Web.config file.

    The ASP.NET application automatically restarts.
  6. When you run the problematic request, ASP.NET now returns a detailed error message that describes the specific nature of the problem. Make a note of this error.
  7. Reenable <customErrors>.

    You can do this if you restore the backup copy of the Web.config file that you created in step 1.

back to the top

View Trace Information

In most cases, when you view the detailed error information, this information is sufficient to identify the source of a problem. However, if the detailed error message does not isolate the problem, you can use trace information to identify the exact nature of the problem.
  1. Create a backup copy of the Web.config file in the root directory of the application.

    You can restore this file after you troubleshoot the problem.
  2. Open the dynamically-generated Application Trace page.

    You can do this by using your browser to request the dynamically-generated Trace.axd file from the root directory of the application. For example, if the root folder of the application is the virtual server myserver, then request http://myserver/trace.axd.
  3. Click Clear Current Trace in the upper-right corner of the Application Trace page.
  4. Open another browser window and then reexecute your problematic request.
  5. Return to the Application Trace page and then press F5 to refresh the window.
  6. Under Requests To This Application, identify the request that you issued and then click View Details.

    The Request Details page appears.
  7. Analyze the View Details page to determine the source of the problem. Carefully examine the Trace Information section for error messages that are reported by the application or by unhandled exceptions. The specific format of these messages may vary, but many ASP.NET applications report detailed information that is useful for troubleshooting problems. The error may also reveal problems that can only be resolved by a developer.
  8. Reenable <customErrors> by restoring the backup copy of the Web.config file that you created in step 1.

back to the top

REFERENCES

For more information about ASP.NET configuration, visit the following Microsoft Web site:

http://msdn.microsoft.com/library/en-us/cpguide/html/cpconaspnetconfiguration.asp

For additional information, click the following article number to view the article in the Microsoft Knowledge Base:

815175 HOW TO: Selectively Enable or Disable ASP.NET Functionality in IIS

back to the top
Modification Type:MajorLast Reviewed:5/29/2003
Keywords:kbConfig kbtshoot kbHOWTOmaster kbweb kbhowto KB815166 kbAudITPRO
©2002 Microsoft Corporation. All rights reserved.