How to debug ISAPI DLL's on Windows 2000 with IIS5

By: Corbin Dunn

Abstract: Debugging Internet Information Server 5 ISAPI DLL's with Delphi

How to debug ISAPI DLL's on Windows 2000 with IIS 5
by Corbin Dunn

1. In the "Administrative Tools" portion of the "Control Panel", start the "Internet Services Manager." Right click on your website and select "Properties":

IIS Screen shot - selecting properties

2. On the "Home Directory" tab, set "Application Protection" to "Low (IIS Process)":

IIS Process

This causes IIS load ISAPI DLL's inside of its process, allowing you to debug them. Close this dialog, but not the IIS Manager program.

3. Expand your website and right click on the "Scripts" virtual directory (or, whatever directory your ISAPI DLL's will be put into). Again, set the "Application Protection" to "Low (IIS Process)" for the virtual directory (similar to step 2). Important - if you don't do this you will probably not be able to load your ISAPI DLL. You can now close the IIS Manager.

4. In the "Administrative Tools" portion of the "Control Panel" select click on the "Services" and for each of the following services, make sure that they are "Stopped" and that the "Startup Type" is set to Manual:

  • Simple Mail Transport Protocol (SMTP)
  • World Wide Web Publishing Service
  • FTP Publishing Service
  • IIS Admin Service
Close the Services Window.
If after you reboot the IIS Admin Service has started, then try making the Startup Type be Disabled - then reboot and make sure that it has not started. If it has, you won't be able to debug.

5. Run "Local Security Policy" from the "Administrative Tools" folder. Expand "Local Policies", and then click on "User Rights Assignment". In the right hand panel, you should see "Act as part of the operating system". Double click on it, and select "Add..." to add a user to the list. Add your current user to the list that you intend to debug with (for example, I added the user cdunn, which is my main login to my Windows 2000 machine). Close this window after adding the user.

Set OS stuff

6. Reboot to make the previous step take effect.

7. Merge the file IISProcess.reg to merge the proper registry settings that make IIS run as a process on your system (so you can debug). Important: If you installed IIS into somewhere other than the default directory, you will have to modify this file. The default location is: C:\WinNT\system32\inetsrv". Use IISService.reg to set the registry settings back as a service.

NOTE: These files are on code central as a zip file, but, if you download them individually, you will have to rename the downloaded file to the right name. It may prompt you to name it "getfile.reg", but rename this to "IISService.reg" or "IISProcess.reg".

In Delphi:

1. In your ISAPI DLL project, go to the "Project Options" and on the "Directories/Conditionals" tab, set the "Output directory" to be "C:\Inetpub\Scripts" or whatever directory you put your ISAPI dll's in. Also, make sure you have all debugging information turned on.

2. Select Run->Parameters from the IDE menu. Set the Host Application to be: "c:\winnt\system32\inetsrv\inetinfo.exe" (without the quotes - assuming this is where you installed IIS). Set the Parameters to be "-e w3svc" (without the quotes).

3. You should now be able to select "Run" and have Delphi start in debug mode. Put a breakpoint somewhere in your source code. Now, using a web browser, browse to your ISAPI DLL (such as https://localhost/scripts/project1.dll), and it should stop on the breakpoint.

4. Use Ctrl-F2 to stop the web server and end a debugging session.

Trouble shooting

If you get an error about: "A required privilege is not held by the client." then you probably haven't done step 3, or you are trying to debug in a scripts directory that hasn't had step 3 done on it. Or, you have not rebooted at some point.

If the debugger starts and stops right away, then you probably have inetinfo.exe running. Run the Task Manager and look for inetinfo.exe running. Try to kill it. If you can't it is currently running as a service. Try shutting it down in the services. If it is stuck on "Starting" the service, then run IISService.reg and reboot. After rebooting, stop the service. Then run IISProcess.reg and try debugging.

When releasing your ISAPI DLL application, be sure to undo what you did in these steps to not hinder performance on your DLL.

Server Response from: ETNASC04