How to debug ISAPI DLLs in IIS 4.0, IIS 5.0, IIS 5.1, and IIS 6.0

Article translations Article translations
Article ID: 183480 - View products that this article applies to.
This article was previously published under Q183480
We strongly recommend that all users upgrade to Microsoft Internet Information Services (IIS) version 7.0 running on Microsoft Windows Server 2008. IIS 7.0 significantly increases Web infrastructure security. For more information about IIS security-related topics, visit the following Microsoft Web site:
http://www.microsoft.com/technet/security/prodtech/IIS.mspx
For more information about IIS 7.0, visit the following Microsoft Web site:
http://www.iis.net/default.aspx?tabid=1
Expand all | Collapse all

On This Page

INTRODUCTION

This article describes one method that you can use to debug an Internet Server API (ISAPI) Extension or a filter DLL file. You must have Microsoft Visual C++ installed on the computer that is running Microsoft Internet Information Services (IIS).

MORE INFORMATION

How to debug ISAPI DLLs in IIS 4.0, IIS 5.0, and IIS 5.1

  1. Build a debug version of the ISAPI DLL. By default, the Debug subdirectory of the project will now contain *.dll and two files with a *.pdb extension (for example, c:\MyProj\debug directory).
  2. Create a virtual root with execute permissions in the IIS Management Console, and then set its physical location to the project's Debug directory (for example, /MyProj virtual root will be mapped to c:\MyProj\Debug).
  3. Make sure that W3SVC service is running. Start it if it is not (you can use this command: net start w3svc).
  4. Start Microsoft Developer Studio. On the Build menu, click Start Debug, and then click Attach Process. Select the Show System Processes option. On a Microsoft Windows 2000-based computer, sometimes no processes will appear in the process list.

    For additional information about this issue, click the following article number to view the article in the Microsoft Knowledge Base:
    235434 FIX: "Attach to process" list is empty
    To attach a debugger to a particular process, click the Task Manager processes tab, right-click the process that you want, and then click debug.
  5. In the list of running processes, select INETINFO.
  6. On the Project menu, click Settings, and then click the Debug tab. In the Category list, click Additional DLLs.

    At this point, you should see the message that states that the DLL symbols were loaded.
  7. Add your ISAPI extension or filter DLL to the list.
  8. On the File menu, click Open, and then bring up the source file for the DLL. Set a breakpoint in the source code, and then 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. Rebuild the DLL to troubleshoot this situation.
NOTE: If the application is configured to run out-of-proc in IIS 4.0 (or on IIS 5.0 or IIS 5.1 with an Application Protection setting of medium or high), by attaching the debugger to Inetinfo.exe, this will not break execution of an extension DLL. You must attach the debugger to the MTX.exe process (or Dllhost.exe on a Windows 2000 or Microsoft Windows XP-based system) that hosts the ISAPI DLL. Because there may be more than one MTX.exe (Dllhost.exe) process running at one time, you may have to add code to the ISAPI DLL that shows the process ID (PID) in which the DLL is loaded. After the PID is known, you can attach the debugger to the MTX (DLLHOST) with the corresponding PID. To do this, use the following code:
#define _WIN32_WINNT 0x0400

#ifdef _DEBUG
char szMessage [256];
wsprintf (szMessage, "Please attach a debugger to the process 0x%X and click OK", 
										GetCurrentProcessId());
MessageBox(NULL, szMessage, "ISAPI/Filter Debug Time!",
                 MB_OK|MB_SERVICE_NOTIFICATION);
#endif
				
Also, note that the Application Protection setting of medium is the default setting of IIS 5.0.

How to debug an ISAPI DLL in IIS 6

If you run IIS 6 in IIS 5 Isolation Mode, extensions and filters are loaded by Inetinfo.exe. You can use the steps in the "How to debug ISAPI DLLs in IIS 4.0, IIS 5.0, and IIS 5.1" section to debug an ISAPI Extension or a filter DLL file when IIS 6 runs in IIS 5 Isolation Mode.

If you run IIS 6 in Worker Process Isolation Mode, extensions and filters are loaded by W3wp.exe. To debug an ISAPI Extension or a filter DLL in Microsoft Visual C++ .NET, follow these steps:
  1. Click Start, click Run, type Cmd, and then click OK.
  2. At the command prompt, type net stop W3svc, and then press ENTER.
  3. Open your ISAPI Extension or a filter DLL project in Visual C++ .NET.
  4. On the Project menu, click Properties.
  5. Click Debugging, and then type the path to the W3wp.exe file on your computer in the Command box.
  6. Type -debug in the Command Arguments box, and then click OK.
  7. Set the breakpoints in the project.
  8. On the Debug menu, click Start.
Note This debugging method runs W3wp.exe in the security context of the user. This is not the security context in which W3wp.exe normally runs.

REFERENCES

The process to debug ISAPI extensions and filters under IIS is fully explained in the Microsoft Developer Network (MSDN) documentation. This documentation can be found in the following location:
   Web Development
      Server Technologies
         Internet Information Services (IIS)
            SDK Documentation
               Internet Information Services 5.1
                  Programmer's Guide
                     Developing ISAPI Extension and Filters
                        Debugging ISAPI Extensions and Filters
				
Note that this documentation is not installed by the default installation option of NT Option Pack or by adding IIS to Windows 2000 or Windows XP. To obtain this documentation, visit the following MSDN Web site:
http://msdn.microsoft.com/library
You can also download this documentation in compiled Help format to your local hard disk. To do this, visit the following Microsoft download site:
http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm

Properties

Article ID: 183480 - Last Review: July 7, 2008 - Revision: 7.2
APPLIES TO
  • Microsoft Internet Information Services version 5.1
  • Microsoft Internet Information Services 5.0
  • Microsoft Internet Information Server 4.0
  • Microsoft Internet Information Services 6.0
Keywords: 
kbtshoot kbbug kbdebug kbhowtomaster KB183480

Give Feedback

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com