ISAPI Extensions

IIS 6 has also improved certain elements of the underlying scripting and IIS integration. The custom error system is a part of this extension, but there are additional components that enable closer integration and cooperation between IIS and any scripts you are running.

The majority of these extensions are designed to improve the overall performance of your Web applications, whether that's actual throughput or it solves a previously complex problem.

Request Redirection (ExecuteURL)

Redirection is commonly used to redirect a user to an alternative page when a page has moved. With a new ISAPI extension, HSE_REQ_EXEC_URL, you can now redirect requests directly from within an application to another URL.

The redirection is not like the static redirection, but it is essentially equivalent to re-executing the request through an alternative URL. You can use this to chain ISPAI filters together to achieve a specific result.

For example, you might want to chain the basic application request, a formatting request, and a template request together?each using a different ISAPI filter. This used to require the production of a raw data reading ISAPI filter?in IIS 6 we can do this by calling the ExecuteURL function to pass off the output from the current, processed, request to another URL.

Wildcard Application Maps

Typically, the extension of a file in a request is used by IIS to determine which CGI application or ISAPI filter is used to process it. For example, a file with an .asp extension is an ASP script, whereas .pl is a Perl CGI and .plx is a Perl ISAPI document.

The problem with this approach is that it means that all elements within your site need to have a specific extension to allow them to run. If you want multiple extensions to parse the same document through the same ISAPI filter or CGI script, you have to set them up individually. It's also impossible to have all documents parsed by a specific filter, irrespective of their extension.

In IIS 6 you can create a wildcard application map?this maps all files matching a particular wildcard specification to an ISAPI filter. In turn, this enables you to automatically parse all content through an ISAPI filter. Used in combination with the ExecuteURL feature, it means that you can parse a request, and then use ExecuteURL to redirect the actual request on to a handler.

This can be used in a variety of environments where pre-parsing of the requested documents further aids the actual request. For example, in a banking or e-commerce site, you might use this to authenticate users before redistributing the request to the correct script to handle the actual response.

For another example of where this can be used, imagine a download site that enables you to download copies of a document in a variety of formats. Rather than keeping fixed copies of the document in the directory in all the different formats, you could create a wildcard application map that points to an ISAPI filter that builds the document dynamically.

When a user requests the report.html file, the wildcard request redirects the request to your ISAPI application, which then uses ExecuteURL to run the HTML generation and return the document in HTML format. When the user requests the report.doc, the same systems uses ExecuteURL to run the Microsoft Word document script.

Although we could do this by using a script and parameters to the script, using such a system makes it difficult to publicize specific URLs without making them complex?that is, is much easier to enter and remember than

You configure the wildcard mapping settings through the Application Configuration dialog box (see Figure 6.1).

Figure 6.1. Application configurations.


To get to this dialog box, use the following steps:

  1. Right-click the Web site or virtual directory that you want, and then click Properties.

  2. Change to the appropriate tab (Home Directory, Virtual Directory, or Directory).

  3. In the Application settings area, click Configuration, and then click the Mappings tab.

To install a new wildcard mapping:

  1. On the Mappings tab, click Insert. You will get the dialog box seen in Figure 6.2.

    Figure 6.2. Application/Extension mappings.


  2. Type the path to the DLL in the Executable text box or use the Browse button to open a file dialog and find it. Remember to click the Application Engine check box if the DLL is a script engine. Then click OK.

To edit or delete a wildcard application map:

  1. In the application extensions list, click the script map that you want to change.

  2. Click Edit to alter the script map, or click Remove to remove the script map.

The wildcard system works in a very specific way and is still subject to the same limitations as the rest of the ISAPI filters system. When executing a request, the impact and execution order of the ISAPI filters is as follows:

  1. The request is handled by any existing ISAPI filters on the root Web site, in the order in which they appear within the application extensions list.

  2. The request is sent to any wildcard application mapped applications, again in the order they appear. If wildcard maps exist at both the directory and site level, only the directory level maps are applied. If no directory specific maps exist, the site level maps are applied.

  3. The extension of the request is used to determine whether any further execution, according to the mapping, is applied through the normal ISAPI or CGI application.

Output Caching

Before IIS 6, if you had multiple buffers of data that needed to be written back to the client (template components, formatted data, generated HTML, and so on), you would have to separately call the WriteClient() function to submit each item back to the client.

With IIS 6, two new features, VectorSend and FinalSend, simplify the process. Now, you can just specify the buffer or file location with calls to VectorSend; this makes the IIS 6 kernel driver aware of the data. When you've completed the sequence, you use FinalSend to signify the end of the data.

This indicates to IIS 6 that the data should be collated and sent back to the client. Because IIS, not the ISAPI filter or application, is responsible for this writing, the worker process can go on to process the next request.

Custom Errors

One of the problems with ASP and other forms of dynamic elements is that you need to handle errors within the application itself. Although this is what you want sometimes?say, an invalid login or empty search results?other times, you want to raise a specific HTTP error.

Through the ExecuteURL system, it's now possible to pass off errors within your applications to the main error handling system within IIS 6, so your users get a consistent error message and view.

Worker Process Restarting

A new ISAPI extension, HSE_REQ_REPORT_UNHEALTHY, can be used by an extension to force the ISAPI application's worker process to be recycled. This is useful if the application has identified that the ISAPI filter has become unstable or unreliable, or if the system enters an unknown state. You can also supply a string that will be written to the Application log to highlight the reason for the error.


In order for the ISAPI call to actually initiate a recycle operation, health monitoring should be switched on in the application pool configuration. Recycle requests are ignored if health monitoring is not enabled.

COM+ Access

COM+ services are now exposed to the ASP service in a different manor. In previous versions, COM+ services used the WAM object in the COM+ configuration store to use a specific set of services that were to be used with specific COM components.

In IIS 6, COM+ can now be used independently of the COM components, allowing developers to access COM+ services directly.

In addition, the following services have been added since Windows 2000:

  • Fusion support? Enables ASP applications to use a specific version of a DLL or COM component. This is useful for backward compatibility with existing applications.

  • Partition Support? COM+ partitions can now be assigned a different configuration for different users, instead of a single configuration for a specific application.

  • Tracker support? Tracks when code is running within an ASP session; useful for debugging applications.