Delphi, ISAPI, NT and IIS 4.0 and 5.0

Introduction

IIS 4.0 is the web server of choice for many Delphi programmers. It has the advantage to be free (well, once you have downloaded it, that is), easy to install and customize. The problem is that it may be a bit too easy to install and customize on the day-to-day basis: Most developers never take the time to understand what it does and how it's components interacts. This is the cause of a large number of very commonly encountered problems.

In this little tutorial, I will try to explain the causes and how to address most of those problems. It is by no mean a complete manual of the product nor will it dispense you to look for further documentation. Please see the credits for the people that sent me additional information, pointed at mistakes or helped in any way to have this page up and running.

Conventions:

White, Italic text: Command lines.

Yellow, italic text: Tips, hints.

Blue text only apply to a specific version of IIS

What you should have/know

Well, First off, you must have Delphi and IIS 4.0 (obviously).

I wouldn't recommend developing on a windows 9x machine because it lakes several of the key features that makes IIS 4.0 both tricky and powerful. Therefore, I'll also assume that you are using Windows NT 4.0 (workstation or server, it doesn't matter).

You should also have at least a good idea about how to manage IIS: How to launch the Internet services manager and how to use the MMC.

Some basic things about the web server

One very important difference between a normal application and IIS is that it doesn't run as a standard NT process. Instead, it runs as what is called a service. A service is a very special kind of application: It starts before any users has logged on the station and does not stop until the computers is shut down (or you stop it manually using the service control panel or the "net stop" command line). Because it starts before any user has logged on, a service has a series of limitations:

A service application cannot normally access the user's desktop: Any window and dialog it creates will shows up in an invisible desktop shared by most services and be inaccessible to the interactive user. (See "The web service hangs")
A service application has a very special set of privileges: It will run under a special security profile known as "system user". This user has all right enabled on the local workstation but no rights on any remote, securable objects (i.e.: it cannot access the local network using LANmanager or NetWare functions). Actually, that is not exactly the case when running an IIS extension. You will be logged as IUSR_<computer name>. This user has actually less rights than the standard system user: it cannot write to the local file system or to the registry. Note that you can also safely use the TCP/IP protocol as it is not a securable in NT.
A service application doesn't has access to the whole registry database: That is, the entire HKEY_CURRENT_USER registry branch is unavailable. It's quite normal since there is no current user logged on for the service. The HKEY_USERS\.default branch is used for services so, if you want to set something you absolutely need in the HL_CU branche, put it in here.

Another good thing to know about IIS is that it's actually composed of several different services:

W3SVC (World Wide Web Publishing Service): This is the service responsible for delivering web pages and managing connections.
MSFTPSVC (FTP Publishing Service): This is the FTP server. Like w3svc, it is responsible for delivering the files to the user as well as managing connections.
IISADMIN (IIS Admin Service): This is the main IIS service and the two other depends on it. It is responsible for checking security, loading files from the file system and loading custom plug-ins as well as cache management. This service is only present since version 4 of IIS.

There is actually some other services that can be part of IIS (depending on your installation) like NNTP, SMTP and others but they will not be part of our discussion and actually only are available on NT server.

Ok, but what about Delphi ?

Well, now that you realize that IIS is not just another application like WinWord or excel, you may also understand that some simple things do not apply to it. For example, there is no simple way to shut it down except going to the services control panel and stop it from there.

This leads to two, very common, questions:

1) "How do I unload my ISAPI DLL/filter/ASP component once I called it?"

In IIS 3.0, all you had to do was closing the w3svc service ("net stop w3svc") and you could delete your file. Now, since in the 4.0 version the file is actually loaded and executed by the IISADMIN service, you must stop this one also. And since all IIS services depends on this one, you must completely shut down all IIS services:

The "net stop" and "net start" commands are used to control a service from the command line. To list the currently running services, use "net start" with no other arguments.
Services can be accessed using two different names: The short name and an optional long name. If you want to use the long service name (as shown by the "net start" command), you should include it between double-quotes (").

Net start "World Wide Web Publishing Service"

[StopIIS.cmd file]
@echo off
Net stop iisadmin /y

and to restart it:

[StartIIS.cmd file]
@echo off
Net start msftpsvc
Net start w3svc
[.. start other IIS-related services you wish to use...]

2) "When I call my ISAPI DLL, the web service hangs and I cannot restart (or stop) it without rebooting"

Actually, the service did not hang. What happened is that, for some reason, the service displayed a modal window (usually an error message telling you that you messed things up somewhat). Since IIS is a service, that message box actually never get displayed on your desktop and you cannot click on it's "OK" button...

Sadly, there is no simple solution to that but killing the web server. The application's exe name is "inetinfo.exe" and you should see it in the task manager (shift + control + escape). If you try to kill the task from there, you'll receive an "access denied" warning. The reason is simple: To open a service process, you need to have the seTcbPrivilege enabled (if you don't know what it is, don't worry, it's not important here). If you have the NT 4.0 resource kit, you'll find a "kill.exe" application in there that can kill the IIS process:

Kill -f inetinfo.exe

If you do NOT have the Resource kit or any other application that can replace it, here is another workaround: Download enable.exe and run it like that:

enable.exe Taskmgr.exe

It will launch the task manager with the correct rights enabled and you will be able to kill the inetinfo.exe task from it. Be careful with it because killing the wrong task (like services.exe, for example) will most likely hang your system.

Debugging IIS add-ons with Delphi

For doing that, we need to change a few things. First off, since IIS is a service and not a regular application, Delphi will not be able to attach to it and debug it while it's running. And since a service needs to be launched by the OS to work, you can't simply use it as a host application for your project. We need to change it's configuration so that it runs as a normal process and THEN use it as a host application. For that, we'll need to change some keys in the registry. Since it's a bit tiresome, Microsoft wrote wrote a couple of .reg files that do all the necessary changes for you (they come from the Windows NT Option pack ¹).

To run IIS as a process: IISprocess.reg

To restore it as a service: IISservice.reg

Another problem is that IIS, during it's startup process, uses a certain number of functions that are not available to normal users (including admins) due to missing security privileges. You must therefore enable the "Act as part of the operating system" privilege in the user's manager user rights dialog.

The "Home directory" parameter screen under IIS 5.0

The version of IIS that comes with windows 2000 (IIS 5) requires you to take one additional step before you can successfully debug applications on it. One added feature of that version is a stronger web application insulation system: web applications can either run in the main web server context (inetinfo.exe), in a separate process (mtx.exe) or each in it's own, insulated process (additional instances of mtx.exe). Since you can't debug spawned process, you need to set IIS up so that web application will run in the context of the main web server instance.

For doing that, open the "Internet Service Manager", select your web site (it should be called "Default Web Site"), open it's properties, select the "Home Directory" tab and change the "Application protection" Dropdown to "low".(²)

Now, we set up the debugger to use the inetinfo.exe program as a host for your ISAPI. In the run->parameter menu, enter:

$[image]Configuring the delphi debugger. Host: C:\WINNT\SYSTEM32\inetsrv\inetinfo.exe Parameters: -e w3svc$

Run parameter dialog box screenshot

Host: C:\WINNT\SYSTEM32\inetsrv\inetinfo.exe (or wherever you installed it)

parameter: -e w3svc

Now, hit the "run" button and wait a few seconds for the compiler to finish compiling and the web server to start and you can navigate to your page on the local machine... To stop the debugger, hit Ctrl + F2

A simpler configuration

This is very nice, but you may need to be able to overwrite the DLL without restarting the web server. With IIS 4.0 you can also do that.

Open the Internet service manager, select the virtual folder where you DLL is, select "properties", and hit the "Create" button in the "Application settings" zone. Once that is done, click on the "configuration" button and uncheck "Cache ISAPI Applications" in the "App Mappings" tab. Once that is done, your DLL will be unloaded as soon as it terminates at the cost of performances.

Other operating systems

First of all, I'm not going to talk about Linux/BeOS and the like. At this time, Delphi 2+ cannot produce executable that can run on any OS but full win32 and there is no way to change that except wait for a port.

This chapter is about two others OSs that you are likely to encounter: windows 95/98.

95 and 98 are completely similar in architecture. They fail to implement several functionalities that are heavily used by web applications (securities, system services, etc.) and is therefore ill-suited as development platform. There is, however, some circumstances where you wish to debug IIS on 9x. In those rare cases, almost nothing you read on this page does apply. There is, however, one trick that may help you: in order to have PWS for windows 9x release an ISAPI dll, stopping the service is not enough: you must open it's properties page. This sounds strange, but it seems to be the only way short of killing the web server app.

(¹): In a previous version of this page, I stated that I wrote those reg files myself. I did not and I'm very sorry for this mistake. It was not my intention to steal the work of other or to pretend I did something I did not, merely an error made at the time of the initial writing and that slipped through corrections.

(²): Many thanks to Kyle Miller for his insightful information about that subject.

Problem ? Question ? Ask the webmaster: [email protected] or see the IIS mini FAQ