HOWTO: Debug ISAPI DLLs Under IIS 4.0 and IIS 5.0

HOWTO: Debug ISAPI DLLs Under IIS 4.0 and IIS 5.0 Q183480
SUMMARY
Debugging of ISAPI Extensions and Filters under Internet Information Server (IIS) 4.0 is fully explained in the Microsoft Developer Network (MSDN) documentation. This documentation can be found in the following location: 


   Platform SDK
      Web Services
         Internet Information Services SDK
            Programmer's Guide
               Developing ISAPI Extension and Filters
                  Debugging ISAPI Extensions and Filters 
Please be aware that this documentation is not installed by the default installation option of NTOP or by adding IIS 5 to Windows 2000. However, it is available at the following link: 
MSDN Online



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 Windows 2000, sometimes no processes will appear in the process list (See Q235434 BUG: "Attach to Process" List Is Empty). You can attach a debugger to a particular process by right-clicking it within the Task Manager processes tab and choosing debug. 


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 in IIS 4.0 (or on IIS 5.0 with medium or high Application Protection), 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 (or DLLHOST.exe if using Windows 2000) that hosts the ISAPI DLL. Because there may be more than one MTX.exe (DLLHOST.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 (DLLHOST) with corresponding PID. You can use this code: 

 #define _WIN32_WINNT 0x0400

 #ifdef _DEBUG
 char szMessage [256];
 wsprintf (szMessage, "Please attach a debbuger to the process 0x%X (%s) and click OK",
           GetCurrentProcessId(), argv[0]);
 MessageBox(NULL, szMessage, "ISAPI/Filter Debug Time!",
                  MB_OK|MB_SERVICE_NOTIFICATION);
 #endif 

Also, please note that medium Application Protection is a default setting of the IIS 5.0. 

NOTE 2: For debugging purposes it may be either to configure IIS 5.0 application to run with low Application Protection. This will allow attaching debugger directly to inetinfo.exe process.