Thoughts on Debugging IIS7

  • Article

Hmm... it seems that ever since I made the blog entry about how to install PHP on IIS7, I seem to have become the default tech-support for PHP/IIS7 issues. That'll teach me to ever post beta guidance again - I just get more "help, I've fallen and I can't get up" questions, especially the sort when the user ignores the directions or thinks that their "modifications" to my instructions are just as good. Sigh... ;-)

I mean, is it too much to expect that if you want to modify the configuration files by hand or commandline that you should have write access to the configuration files? The IIS7 UI automatically asks you for privilege elevation, but when you go on the commandline you are obviously on your own. Or that if I give instructions for configuring the PHP ISAPI handler to run using the ISAPI Module that you merely change the handler to run the PHP CGI EXE handler with the ISAPI Module (and not the CGI Module)?

However, this also makes me realize that if you think IIS6 is confusing and difficult to troubleshoot, IIS7 is even more open-ended and hence harder to troubleshoot. You really have to know how IIS7 operates and what you are configuring (and why) when you make IIS7 configuration changes... because one wrong step and the server will stop working, by-design due to its open extensibility.

For example, when it comes to requests not resulting in the proper response, my first question is "what handler generated the response - static file handler or arbitrary dynamic file handler" - because that determines the expected response behavior. However, it is clearly not how users think - users think of it as a file to download, HTML page with a CSS stylesheet, or ASP.Net web application not working. Unfortunately, given how configurable (and misconfigurable) IIS7 can be, using the user's view of the issue will not be sufficient to troubleshoot, and we cannot make it any better/easier - there are so many things to misconfigure!

All it means is that if you customize beyond the default set of supported IIS7 configurations, you will pretty much be on your own. We try our best to make many module combinations work, but it will always be possible to configure IIS7 modules into a non-functional state.

For example:

  • If you [accidentally] mangle the ordering of the StaticFileModule, DirectoryListingModule, and DefaultDocumentModule modules, IIS7 will either refuse to serve default documents (regardless of how you enabled/configured it), refuse to do 301 courtesy-redirect, or refuse to show a directory listing. If you just stare at the IIS7 configuration, you will tear your hair out trying to figure it out... and FREB or ETW tracing won't really help, either. You literally have to know how to order the modules to end up with expected IIS behavior, and requiring that knowledge is by-design. Similar dependencies exist for authentication and caching...
  • If you want to configure a "wildcard application mapping", you have to chant the magic incantation of a perfect handler configuration. I'll leave the exercise to the reader to come up with the spell. :-)
  • If you configure a handler AFTER the catch-all StaticFileHandler, it will NOT apply to any requests. If you just stare at the IIS7 configuration wondering why it is not running - it is there in the configuration section - you will go crazy unless you know how the handler section works.
  • If you configure an ISAPI DLL as a globalModule, reference a non-existing managed type as a module, or remove a referenced module from loading... good luck on the spotting the error! ;-)

In short, if you run IIS7 in non-default fashion, it will require either perfect instructions or the user has to really understand IIS7 processing and behavior. Maybe there is a way to lower the requirements of running/using IIS7, but I have not come up with any. What are your thoughts?

//David