ISAPI Extension Architecture

This topic outlines architectural features of ISAPI extensions.

ISAPI Processes and Threads

The ISAPI model, unlike other Web content development technologies, does not require a separate process for every request to an HTTP server. ISAPI uses threads to isolate work items in a process. Because IIS employs multiple threads to synchronize work, it makes more efficient use of system resources than the Common Gateway Interface (CGI) model or other models based on process isolation.

Each client request to an ISAPI extension initiates the creation of an EXTENSION_CONTROL_BLOCK data structure. Creating and maintaining a data structure is much easier and faster than initiating a new process. The EXTENSION_CONTROL_BLOCK structure and the extension usually run in the same process as IIS, therefore the server can process requests faster and accommodate a higher number of them.

As with other DLLs, Web server applications must be thread-safe. Because more than one client will be running the same function simultaneously, the code must follow safety procedures when modifying global or static variables.

ISAPI extensions can be kept thread-safe with the use of appropriate synchronization techniques, such as creating critical sections and semaphores. For additional information about writing thread-safe DLLs, see Synchronization Techniques in the Windows DDK.

Support for Process Isolation

IIS supports process isolation for ISAPI DLLs and scripts. It uses custom, high-speed methods to establish communication between the server process and the surrogate process that houses the DLLs, thus providing robustness with high performance. ISAPI extensions are implemented as DLLs that are loaded either into the IIS process or, if they are part of an out-of-process application, into a separate process. Like ASP and HTML pages, IIS uses the virtual location of the DLL file in the file system to map the ISAPI extension into the URL namespace served by IIS.

By default, IIS is configured to cache ISAPI extensions. When it receives a request that maps to an ISAPI extension, it first checks to see if the DLL is already loaded. If it is not, IIS loads it. Once this is done, the entire request is managed by the extension, with IIS acting as an efficient intermediary and helper.

ISAPI can also control an entire namespace. If you use an asterisk (*) as your extension, all requests to that namespace are handled by the specified ISAPI.

Separate Server Process

It is possible to isolate an Internet Server Application Programming Interface (ISAPI) extension by running it in a separate server process. To do this, choose the Run in separate memory space option in the Internet Information Services (IIS) user interface when creating an extension.

Some ISAPI extension DLLs might not be suitable for running in a separate process, for any of the following reasons:

• File access can break if an instance of an ISAPI DLL in one process opens a file exclusively, locking it from being used by another instance of the same ISAPI DLL in another process.

• Security access is different for an ISAPI running out-of-process than for an ISAPI running in-process.

• Combining ISAPI extension functionality and filter functionality in a single DLL does not work if you mark the extension as running in a separate process because an instance of the ISAPI DLL cannot exist in both Inetinfo.exe (in-process for the filter), and DLLHost.dll (out-of-process for the extension). IIS versions 5.0 and above detect when the same ISAPI DLL is configured as an extension and a filter, and forces the extension to run in-process.

• Performance can slow down because the ISAPI needs to perform cross-process communication between DLLHost.dll and Inetinfo.exe. Also, if the ISAPI DLL uses its own caching scheme, each instance of the DLL has its own cache, using up memory. Finally, if the ISAPI DLL has a long initialization period, that initialization has to happen for each instance of the DLL (for each process).

• Unexpected behavior can occur if an ISAPI DLL is configured to run in a separate process because the different instances of that ISAPI will not know about each other.

For servers running in IIS 5.0 isolation mode, you can use the metabase property InProcessIsapiApps to specify a list of all ISAPI DLLs you want to run in the same server process as IIS. Requests for these DLLs are routed to the default application root in IIS (/LM/W3SVC). The default application root is marked in-process only, which guarantees that all such requests will run in-process. Setup will create the InProcessIsapiApps property and populate it with Ssinc.dll and Httpodbc.dll, which must run in the same process as IIS. For more information about IIS 5.0 isolation mode, see IIS Process Models for ISAPI below.

Note

A software error in an ISAPI DLL causes the server to stop. Therefore, unless you are sure your DLL will never run out-of-process, do not add it to this list.

ISAPI and Process Recycling

Starting with IIS 6.0, IIS supports two distinct application isolation modes: worker process isolation mode, and IIS 5.0 isolation mode. Worker process isolation mode can be configured to recycle processes. When applications are recycled, it is possible for session state to be lost. During an overlapped recycle, the occurrence of multi-instancing is also a possibility.

It is recommended that ISAPI applications persist any states externally, such as in an SQL database. If an ISAPI application?s state management code cannot be modified, IIS should be configured to run in a manner that prevents state loss. This includes disabling recycling functionality and the idle time-out of worker processes. Disabling these features is a better alternative than running IIS in IIS 5.0 isolation mode. Also, disabling pinging functionality is recommended if an ISAPI in the pool uses the HSE_REQ_REPORT_UNHEALTHY structure, as do ASP and ASP.NET, because the worker process is recycled after a ping is sent in.

Multi-instancing can cause problems for ISAPI extensions that are not specifically coded to handle this execution environment. For example, if an ISAPI application implements its own logging to a file, it must be able to handle the log file being accessed by threads outside of its own process, which might use different credentials or lock the file. If an application uses kernel objects such as events, it needs to take into account that these objects will be signaled by threads in other processes, and not necessarily within their own.

For more information, see IIS Process Recycling.

IIS 5.1 and earlier: Worker process isolation mode, process recycling, and application pools are not available.

Support for HTTP 1.1

ISAPI supports HTTP 1.1. Two areas in which this has potential impact on ISAPI extension and filter developers are support for pipelined requests and support for the transfer encoding header.

The transfer encoding header tells the client if a transformation has been applied to the body of the message being sent. For example, if the client supports HTTP 1.1, IIS can specify a transfer-encoding value of "chunked." When the chunked transformation is applied, the message is broken into chunks of varying sizes, each of which contains its own size indicator and optional footers for specifying header fields. Chunking is more efficient than non-chunked connections in terms of internal application processing, especially for streaming data sources and very large data sets.