HOWTO: Debug ISAPI and Filter DLL Under IIS 4.0

ID: Q183480

The information in this article applies to:

Microsoft Internet Information Server 4.0

SUMMARY

Debugging of ISAPI Extensions and Filters under Internet Information Server (IIS) 4.0 is fully explained in the Windows NT 4.0 Option Pack (NTOP) documentation. This documentation can be found in the following location:


   Microsoft Internet Information Server
      Advanced Web Application Development
         Debugging Your Application
            Establishing a Debugging Environment

Please be aware that this documentation is not installed by the default installation option of NTOP.

MORE INFORMATION

Following are the steps for one method to debug an ISAPI Extension or Filter DLL. (It is assumed that Visual C++ is installed on the IIS computer.)

Build a debug version of the ISAPI DLL. By default, the Debug subdirectory of the project will now contain *.dll and two files with *.pdb extension (for example, c:\MyProj\debug directory).

Create a virtual root with execute permissions in the IIS Management Console and set its physical location to the project's debug directory (for example, "/MyProj" virtual root will be mapped to "c:\MyProj\Debug").

Make sure that W3SVC service is running. Start it, if necessary (you can use this command: "net start w3svc").

Start Microsoft Developer Studio. Go to the Build menu, click Start Debug, and click Attach Process. Select the Show System Processes option.

In the list of running processes, select INETINFO.

From the Project menu, click Settings. Click the Debug tab. From the Category drop-down box, select Additional DLLs. At this point, you should see the message stating that DLLs symbols were loaded.

Add your ISAPI extension or filter DLL to the list.

From the File menu, click Open and bring up the source file for the DLL. Set a breakpoint in the source code and submit a request to IIS from the browser (for example, http://server/myproj/mydll.dll). If the debugger beeps and refuses to set the break point, the reason for this may be a mismatch between the DLL and PDB files. Rebuilding the DLL should help in this situation.

NOTE 1: If the application is configured to run out-of-proc, then attaching debugger to Inetinfo.exe will not break execution of an Extension DLL. You will need to attach the debugger to the Mtx.exe process that hosts the ISAPI DLL. Because there may be more than one Mtx.exe process running at one time, you may need to add code to the ISAPI DLL that shows the process ID (PID) that the DLL is loaded in. After the PID is known, you can attach the debugger to the MTX with corresponding PID.

NOTE 2: It is possible to run Inetinfo.exe as a process in the debugger, with -e w3svc parameter. Technote 63, in the Visual C++ documentation explaining this process for IIS 3.0, does not apply to IIS 4.0, however. Please see the file named IIS_as_process.txt in \Inetpub\iissamples\sdk\components\ directory, which explains the procedure for IIS 4.0. Please note that the IIS 4.0 samples are not installed by default.

REFERENCES

Windows NT 4.0 Options Pack online documents

Additional query words:

Keywords : kbASP kbDebug iisapi
Version : WINNT:4.0
Platform : winnt
Issue type : kbhowto