Why Wildcard application mapping can disable Default Document resolution

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. 🙂


Comments (9)

  1. DAvid says:

    Ok, thats the problem any ideas on the fix ?

  2. David.Wang says:

    David – I presume you are referring to ASP.Net 1.1. Since the behavior is by-design, there is really nothing to "fix".

    For example, you may try to configure ASPNET_ISAPI.DLL to be an ISAPI Filter (even though it isn’t an ISAPI Filter) and find that IIS6 now returns 503. Since ASPNET_ISAPI.DLL is not an ISAPI Filter, the behavior is by-design and there is nothing to "fix".

    Similarly, you may try to configure ASPNET_ISAPI.DLL to be a wildcard application mapping (even though it was never written to be one) and find that some URL processing does not work correctly on IIS6. Since ASPNET_ISAPI is never written to be a Wildcard application mapping, the behavior is by-design and there is nothing to "fix".

    If you are asking for a "work-around" – as URLs in the blog entry show, since ASPNET_ISAPI.DLL is unable to hand the request back to IIS for DefaultDocument resolution, that resolution has to happen somewhere else. Some people have added hard-coded redirections into their HttpModules to identify these DefaultDocument redirections and handle it, but it is certainly not the only way. You’ve got the details now; figure it out.


  3. David says:


    I think i typed it more in hope than in anything else. Im not a boffin im afraid. I do know that I did not knowingly install anything to bring about this problem on the server e.g no application mapping or what not. I have uninstalled iis and re installed it etc. but im left with the same problem. I think my symptoms are the same but the problem is different.

    Thank you .


  4. David.Wang says:

    David – the key message is that you should not ask for a "fix" for something that is not broken. And you need to describe your problem thoroughly if you need assistance.

    What is described here is not default behavior. So, you have either knowingly or unknowingly made a server configuration change to result in this state. Possibilities include:

    1. Custom ISAPI Filter

    2. Custom ISAPI Extension configured as Wildcard Application Mapping

    3. Misconfigured IIS HttpRedirection

    4. global.asa or global.asax with misconfigured HTTP Redirection


  5. Scott says:

    Fix or no fix many applications rely on the ability to send all requests to asp.net where they’re processed. While its not recommended or supported it very neccessary and since its changed it means that migrating applications from 1.1 to 2.0 is taking far longer than hoped.

    For me the requirements were:

    o) Have 2 web apps



    o) Configure subapp with wildcard to pass all requests to asp.net

    o) Add handler mapping to webapp’s web.config


     <add verb="*" path="*" type="MyBrowseHandler, Application" />


    o) Add handler code to redirect as required.

    None of the files or directories that are called exist and all the responses are generated on the fly.

    This is a fundamental requirement for my application but to do this now is difficult bordering on impossible.

    I’ve tried to configure this for the subapp but it is still passing back 404 errors.

    IIS 6.0 does not serve unknown MIME types


    Any help or suggestions are most appreciated.


    Frustrated Developer trying to convert applications from ASP.Net 1.1 to 2.0

  6. David.Wang says:

    Scott – What you are describing is a common failure pattern for users that configured ASP.Net 1.1 as a wildcard application mapping and then upgrade to ASP.Net 2.0 on IIS6.

    In the near future, I will be posting a blog entry about:

    1. What is actually going on

    2. Why it broke on upgrade

    3. How to do the necessary configuration to get similar behavior

    Since this is ultimately not an officially supported scenario of ASP.Net 1.1 and ASP.Net 2.0, you will find that things will again break when you upgrade from IIS6 to IIS7. I can only suggest that you learn and understand what is actually going on… which is what I am going to blog. 🙂


  7. Nathan Ridley says:

    @John and Joel

    Set your web application to have a wildcard mapping as per usual. Then for your images directory (and whatever other directory you want), in IIS make that folder a virtual directory via the ‘Create Application’ button in the ‘Home Directory’ tab. Then click ‘Configuration’ and remove the wildcard mapping. The change will apply only to that virtual directory and not the root web application, thus causing all requests in that directory to get processed normally.

  8. John Bailo says:

    I am having a problem setting up a wildcard mapping for a Web Site.

    I can set it up (aspnet_isapi.dll) for a virtual directory, but when I configure it for a Web Site, the mapping doesn’t fire (I get a page not found, 404 error, when it should be running my URLRewrite HttpModule).

    Any suggestions?

  9. David.Wang says:

    John – You most likely have custom ScriptMaps set on virtual directories themselves which will override any ScriptMaps (including wildcard) set at the Web Site level.

    In other words, global wildcard application mapping works… unless a virtual directory redefines its Application Mapping such that it does not contain that wildcard application mapping.


Skip to main content