The ISAPI Execution Environment

This document bases on information and testing done with IIS 1.0. We have not re-tried it with later versions. However, we feel very comfortable with the information contained herein and think that it still is correct. There is just one exception: if you create an application in MMC under IIS 4.0, your ISAPI extension is run in a separate process space (as far as we know under MTS control). In this case, you obviously do not run in the process space of IIS (that's why it is called process isolation). As far as your extension is concerned, that should make no big difference. When we first started developing isapi apps, things were first very clear to us. However, as soon as we hit the field of "real" IIS application with multiple concurrent requests and multiple extensions being loaded, things became quite more complicated. All of a sudden, some things looked really confusing. We found that the key to order this things at get a productive application out of our coding is understanding what IIS really does and how an extension is executed. This is what we call the ISAPI Execution Environmen and this is what this document is all about. We hope it will save you some valuable time when first starting isapi development. In order to allow easy offline storage and printout, we have created just this single, relativly large document. People with slow links and/or not-so-current browsers, please forgive us. We think it is the best compromise available. If you find anything to add, correct or otherwise change in this document, please do not hesitate to

When w3svc starts, it does its initialization work. During its initialization, it checks the registry for installed isapi filters and initializes them (note: the life of an isapi filter won't be discussed any further). W3svc also loads and initializes some other WOSA services, like Windows sockets and ODBC (for logging purposes).

During its initialization phase IIS creates a number of threads that later on will be used to serve clients. If you look with the process viewer application at an just started-up IIS, there are usually between 12 and 14 threads in its process space, a lot of them without any processing so far. We think these threads build a pool of "worker threads". However, we found no documentation on that so far.

Being started up, IIS listens for HTTP-requests. As soon as one comes in, IIS assigns a worker thread (usually the same that's the shortest one finished) to the request and carries on processing (we think - but have not verified - that the number of worker threads is extensible as more concurrent requests come in).

The worker thread then analyses the type of request. It uses the configuration settings supplied by Internet Service Manager to decide on what to do next. Choices are "web file services" (just deliver the need file more or less unprocessed) or call an extension. In the later case there can be numerous extensions to call - basically they are all the same: call an isapi extension. This is even true with IDC, in which case the IDCODBC.DLL isapi extension is called.

Now we get into business. Let's think the worker thread has requested that our app is to call.

If not already loaded, IIS then first loads our DLL. As usual, this triggers the execution of our DllMain entry point. Here is the right place to do any global initialization of our extension. There is nothing IIS specific at this stage of execution!

Soon after loading the DLL, IIS requests our extension to register with IIS. This is done by calling our routine GetExtensionVersion. Here we have to supply a little information about ourselvs: like our name and the isapi version we are developed for. Please note that GetExtensionVersion is only called once. It won't get called further on, not because we are executed by another worker thread or for whatever other reason. The only case in which an isapi extension's GetExtensionVersion will be called again is after unloading and reloading the DLL (as the whole process starts from scratch). For now we can remind: GetExtensionVersion will only once be called in the lifecycle of our app.

Now IIS is in business with us. It knows how to handle us (depending on isapi version) and now starts activating us. For any further http request, IIS starts at this very point, skipping all extension initialization work.

Now our main entry point - HttpExtensionProc- is called by the worker thread. IIS supplies us with the input data stream and allows us to write to the client. Please note the multiple concurrent http requests for our application result in multiple worker threads calling our app concurrently. So at any given time, our code might be executed by numerous worker threads simultaneously. As soon as our processing is done (HttpExtensionProc returns), IIS begins to finish processing. Our DLL remains loaded.

The worker thread now does everything need to complete the request. After that, it is available for usage by another request and put on hold until such a requests reactivates it. We do not know if worker threads will be reduced when IIS' workload is reduced. However, we do expect it (another nice thing worth tracing).

More important than that is what happened to our DLL: This one is still sitting in IIS' process space waiting for any other requests hitting it. It has not been unloaded, resulting in possible very low overhead for each additional call (this is one of the performance strength of isapi).

However, the server might decide to remove our DLL at any given time. Again, we do not know the details. But it might happen. In this case, IIS calls UnloadLibrary and thus our DllMain procedure is hit again. Now is the right time to clean up any resources globally allocated (free any handles, heap memory structures etc.). After that, our extension is in an uninitialized (unregistered to IIS) state. If we get another request, the whole initialization process starts again (thus IIS tries to avoid unloading extensions).