Users frequently configure ISAPIs like ASPNET_ISAPI.DLL as a wildcard application mapping on IIS6 to route all requests into ASP.Net for processing (for example, to apply ASP.Net Forms authentication onto non-ASP.Net resources like a JPG or HTML).

However, as soon as they do this, they may notice that some IIS features such as default document resolution, application mapping resolution, and directory browsing stop working. Why?

Is this a problem with IIS6, a bug in the ISAPI configured as the wildcard application mapping, or maybe it is by-design?


On IIS6 I have configured a wildcard application mapping, but now when I just browse to a URL or an IP without specifying a document, it does not add the "default document" anymore. Is it a bug in IIS 6.0 ?

Does anyone know a workaround? Or does anyone have code to replace the "default document settings" in an isapifilter? I don't have any clue how to do that.

Any help would be very much appreciated



This is definitely not a bug in IIS6, and depending on the ISAPI, it may not even be a bug... so let me explain what is going on here.

  • The reason it is not a bug in IIS6 is because of how the IIS6 Request Processing functions.
  • If the ISAPI is not written as a proper wildcard application mapping, configuring it as a wildcard application mapping can also result in this behavior and that is totally by-design.
  • If the ISAPI is written to be a proper wildcard application mapping AND it does not allow Default Document without a good design reason, then it is probably a bug in the ISAPI.

However, since almost all existing ISAPI DLLs are not written to function as a proper wildcard application mapping, I consider your observations to be "by-design" behavior. In particular, if you configure ASPNET_ISAPI.DLL from ASP.Net 1.0 or ASP.Net 1.1 to be a wildcard application mapping on IIS6, the behavior you observe is totally by-design.

In other words, just because you can configure something as a wildcard application mapping does not make it correct, even if some things appear to work.

  • For example, you can configure random Win32 DLLs to be application mappings or even ISAPI Filters, but there is no expectation that it even works (the DLL likely will not export the necessary function signatures so IIS will not even load it).
  • Likewise, you can configure random ISAPI DLLs to be wildcard application mappings, but there is no expectation that it functions correctly - it was never designed to function that way.

Wildcard Application Mappings and IIS6

At a high level, IIS goes through a straight forward process to determine which handler(s) should handle generating the response for a given request. Please read the IIS6 Request Processing Basics URL for details.

Now, suppose you configured ASPNET_ISAPI.DLL from ASP.Net 1.1 as a wildcard application mapping. What happens?

Well, according to the "IIS6 Request Processing Basics" URL, wildcard application mappings can intercept the determination of a request handler right at the beginning, so it can definitely step in before the Courtesy 302 Redirection or the DefaultDoc determination happens.

Now, the million dollar question:

What do you think happens if the wildcard application mapping returns "I AM handling the request" and short-circuits the rest of normal request processing?

Yup, you guessed it. Look at the havoc and weird behaviors that can happen with a misbehaving wildcard application mapping:

  1. Application Mappings are not resolved. This means that ASP pages stop being executed by ASP.DLL whan you wildcard scriptmap ASPNET_ISAPI.DLL
  2. Courtesy 302 redirection is not sent by IIS.
  3. DefaultDoc resolution is not done by IIS.
  4. DirBrowsing is not done by IIS.
  5. Static File is not sent by IIS. This means that static files are not cached according to ActivityPeriod in the kernel response cache.
  6. Custom Error is not sent by IIS.
  7. Etc...

Clearly, like any ISAPI, a wildcard application mapping can prevent IIS from functioning properly to the user's usual expectations. Allowing ISAPI to have this power is by-design - an ISAPI controls exactly how the server behaves, for good and for bad. The ISAPI can certainly handle all those broken usage cases above, but it is up to the ISAPI to do so, not IIS, since it is supposed to "handle" the request.

Now, what is special about IIS6 is that it introduces the HSE_REQ_EXEC_URL ISAPI ServerSupportFunction call, which basically allows an ISAPI to return "I am NOT handling the request". This, in combination with wildcard application mapping's placement at the front of IIS determination of request handler, allows IIS to execute ISAPI DLLs for the side effect of "filtering a request" yet not own handling the request. Correspondingly, the end result is a lot nicer because IIS got to handle the request as it wanted; the ISAPI merely filtered the request for side effect.

This, in a nutshell, is how a ISAPI can function as a proper wildcard application mapping... and why existing ISAPIs cannot properly function as a wildcard application mapping. They do not call HSE_REQ_EXEC_URL.

Now, ASPNET_ISAPI.DLL of ASP.Net 2.0 is a different story. It does have functionality to call HSE_REQ_EXEC_URL, controllable via managed code. This allows managed code to filter yet not own handling the request, allowing for scenarios like ASP.Net Forms Auth applying to ASP pages... and that is a whole other topic on its own. :-)