Visual Basic Concepts

Debugging your IIS Application

See Also

You debug an IIS application in the same way you do any other Visual Basic application — by entering run mode from Visual Basic. Visual Basic loads the webclass run time, creates the virtual root from which to run the .asp file for the application, if necessary, and launches the system's default browser with an HTTP reference to the .asp file. The .asp file, in turn, launches the webclass.

Note   Although you can view the .htm files associated with your application in the browser by opening them from the browser's File menu, this is not debugging your application. You must use the Start option from Visual Basic to enter debugging mode.

When you debug, you have the full Visual Basic development environment at your disposal. You can use all the tools available in Visual Basic — breakpoints, watch variables, debug statements, and so on — to debug your project.

Visual Basic prompts you when you debug that it is going to create a virtual directory for your project. A virtual directory is a directory outside your Web server's home directory that appears to browsers as a subdirectory of the home directory. It allows you to publish contents to the Web from directories outside the home directory structure. You cannot change the location of the virtual directory Visual Basic creates for the webclass.

The Project Properties dialog box's Debugging panel settings determine whether the system waits for you to tell it what to do when you go into run mode or automatically starts the webclass you specify. When you choose to automatically start the webclass, Visual Basic launches Internet Explorer, navigates to the URL for your application, and fires the webclass's BeginRequest event.

Visual Basic deletes all temporary files when it comes out of run mode. In addition, it destroys the instance of the Webclass Designer and restarts the designer in design mode.

Debugging Tips

Follow these tips when debugging, for best results:

• When you are debugging and the application hits a breakpoint, pressing F5 to continue does not return focus to Internet Explorer. You must switch to Internet Explorer manually to continue from the breakpoint.
  
  
• Avoid running multiple instances of the Web browser when debugging. If more than one browser instance is open, Visual Basic does not keep track of which browser is running the project, and all instances will be affected when you end your debugging session.

In addition, there are several differences between the behavior of the webclass during debugging and the behavior of the compiled application. You should be aware of these differences and keep the compiled behavior in mind when building your project. The following are a few key areas in which you must tailor your application to the behavior of the compiled application:

• In debug mode the webclass will run in the same thread, and static and global variables will not be set. When compiled, the application will be accessed from multiple threads.
  
  
• Although you will see message prompts in debug mode, the compiled webclass writes all errors as entries in the Windows NT event log or in a log file created in the Windows directory.
  
  
• Do not use an Access database on a remote computer in your project. While this will work in debug mode, it will not work when the application is compiled.
  
  
• Use only system DSNs in your project. Although nonsystem DSNs will work in debug mode, they will not work in the final project.
  
  
• Do not allow the webclass to add itself or other Visual Basic components to the Active Server Pages' Application object. While this may work in debug mode, it will generate an error when you run the compiled application.

For More Information   See "Debugging Your Code and Handling Errors" in the Programmer's Guide for more information on how to test and debug your IIS application.

Errors in Webclasses

You can use Visual Basic's error-handling features in your IIS applications to trap errors and take corrective action. When an error occurs, Visual Basic sets the various properties of the error object, Err, such as an error number or a description. You can use the Err object and its properties in an error-handling routine so that your application can respond intelligently to an error situation.

In addition to standard error handling, IIS applications allow you to use two special features to handle errors:

• You can use the Trace method to debug your application on the production computer.
  
  
• You can use the FatalErrorResponse event to respond to serious run-time errors.

For More Information   The basics of error handling are discussed in "Debugging Your Code and Handling Errors," in the Programmer's Guide. For information specific to ActiveX projects, see "Generating and Handling Errors in ActiveX Components", in "Building Code Components," in the Components Tools Guide.

Using the Trace Method

You can use the Trace method to help identify errors during the debug process and to track performance and statistical data. The Trace method sends a specified string to the Win32 OutputDebugString API. The string can then be captured to a suitable debugging tool such as DBMON.

Using the Trace method can allow you to debug on your production server computer and record useful information such as information about the execution of the application, error messages that occur, and any other information you need.

For More Information   See "Trace Method" in the Language Reference for more information on using this method in your error handling.

Handling Fatal Errors

A fatal error on a webclass is one from which the application cannot recover or restore the appropriate webitem. For example, a fatal error might be an unhandled error within a webclass event, a structural error, or an unexpected error within the run-time DLL. Following such an error, the webclass run time fires the FatalErrorResponse event. The application is terminated and the instance of the webclass is destroyed.

When a fatal error occurs, the application can write a message to the Response object in the handler for the FatalErrorResponse event. This message can be one that you write, or it can be the default message for the .asp file associated with the webclass. To write your own message, use the Response object, then set the senddefault argument of the FatalErrorResponse event to False. To use the default error message, leave the senddefault argument set to True.

Note   The webclass run time provides an Error property that is only available from within the FatalErrorResponse event. This property returns an object that describes the error that caused the webclass to terminate.

The webclass run time also logs fatal errors to the Windows NT event log. On Windows 95 (or later) systems, the run-time DLL creates a log file in the Windows directory and logs the error there.

For More Information   See "FatalErrorResponse Event" in the Language Reference for more information on handling nonrecoverable errors.