ISAPI Filter Design Issues

  • Article

The following developer notes provide additional information about the interaction between ISAPI filters and IIS.

Language and Framework Choice

Consider using the MFC library to develop ISAPI filters. The IIS SDK assumes that the Microsoft Foundation Class (MFC) library is not in use. The MFC library provides an object model, as well as a wizard, that can be useful in creating ISAPI filters. Classes such as CHttpFilter and CHttpFilterContext are provided. For more information about MFC, see the Microsoft Foundation Class Library and the Visual C++ SDK.

Choice of Notifications

Care is recommended when choosing which notifications to handle. The following issues should be considered:

  • Do not register for a notification unless it is necessary: Filters should be registered to be notified of only those events needed for processing. Some filter notifications are very costly in terms of CPU resources and I/O throughput (most notably SEND_RAW_DATA), and can have a significant impact on the speed and scalability of IIS.

  • Register for SF_NOTIFY_END_OF_NET_SESSION: Most filters should be registered for SF_NOTIFY_END_OF_NET_SESSION, as it is a good time to perform session-level resource maintenance such as buffer recycling. For performance reasons, most filters keep a pool of filter buffers, allocating or freeing them only when the pool is empty or becomes too large to save on the overhead of the memory management.

  • Do not attempt to change the notification flags in the metabase: The metabase property FilterFlags contains flags that indicate to IIS which notification types a particular ISAPI filter can support. However, this property is populated by IIS from the bit flags passed in the HTTP_FILTER_VERSION structure from the GetFilterVersion function. FilterFlags should be considered read-only.

Proper Use of Notifications and Filters

Using the different event notification types properly is important. The following issues should be considered:

  • Avoid extended or extraneous processing within filters: Filter notifications that require connection state information from the IIS server are costly to perform and should be avoided within ISAPI filters, if possible. Also, in most cases, an ISAPI filter should return data to the client only when handling an exception case, such as the denial of a request or the generation of an error.

  • Avoid buffering or altering the entity body of a request in a filter: Filters are not designed to process POST data (or "form" data), and significant limitations will occur if the attempt is made.

  • Use SF_NOTIFY_AUTHENTICATE only to map credentials to a Windows 2000 account, not to deny access: Because SF_NOTIFY_AUTHENTICATE is sent by IIS only on the first request of each session, developers should not perform sole validation checking within the handler for this notification, as the handler is always called. Instead, SF_NOTIFY_AUTHENTICATE should be used only for notification handlers that authenticate user names and passwords.

  • Take care to prevent recursion when accessing certain server variables: If a filter retrieves the PATH_TRANSLATED or PATH_INFO server variables within the SF_NOTIFY_URL_MAP notification, the filter is called recursively with the SF_NOTIFY_URL_MAP notification to do the physical translation for the variable.

  • Do not change a request from static to dynamic, or vice versa, within SF_NOTIFY_URL_MAP: If a request must be translated from a dynamic file to a static file or vice versa, it should be done from within an SF_NOTIFY_PREPROC_HEADERS handler, not an SF_NOTIFY_URL_MAP handler.

  • Use the AllocMem callback function with care: If the AllocMem callback function is used with the HTTP_FILTER_CONTEXT structure to allocate memory, the allocated memory is automatically freed when the communication with the client is ended. Managing memory this way can have a negative impact on performance, because memory allocated by IIS in response to calls to AllocMem comes from the global IIS process heap. It might be preferable to create a memory pool and adjust it only as necessary. This can reduce the overhead caused by allocating and de-allocating memory from the global IIS process heap.

  • Assign the correct priority to the filter: Some IIS functionality makes use of bundled ISAPI filters. In general, unless there is a compelling reason to do otherwise, it is best to avoid designating your filters as high priority to avoid conflict with the system filters.

Raw Data Filters

A raw data filter is one that is registered for the SF_NOTIFY_READ_RAW_DATA event notification. When developing raw data filters, there are a number of additional complexities and considerations to keep in mind, including the following:

  • Filters that register for the SF_NOTIFY_READ_RAW_DATA event must be assigned at the Web service level: They cannot be assigned to an individual Web site.

  • Raw data filters should be selective about the types of content they process, if possible: For instance, if a filter performs processing only on HTML files, other files should be ignored early in the notification sequence. If the filter determines that the file is not of the appropriate type, it can use the SF_REQ_DISABLE_NOTIFICATIONSServerSupportFunction to disable all further notifications for that request.

In IIS 5.0, ISAPI filters run as the LocalSystem account in the Inetinfo.exe process and are guaranteed to be single-instanced. This is no longer the case in worker process isolation mode. For more information, see Creating ISAPI Filters.

ms525159.alert_caution(en-us,VS.90).gifImportant Note:

It is vital that the work performed by ISAPI filters is minimized, because the effects on scalability and performance are potentially quite severe. For example, if a filter implements a custom encryption scheme, the encryption and decryption should take place within the ISAPI filter code, but the reading and writing of the data should be handled by IIS.