Wrong documentation is worse than no documentation. I recently got to experience the frustration of following Microsoft’s instructions for an IIS configuration change, only to discover that the instructions were incorrect. I also learned the value of frequent IIS configuration backups. And why I generally hate doing system administration.
Strange Page Refresh Behavior
The situation came about because we were having problems with some of our data-driven ASP sites. We have a tool called the Logical Web Publisher (it runs this site, in fact), and like most content management tools, it gets its content from a database. That means there are only a few ASP pages that manage the entire site, and that query parameters control what is displayed.
In the past year, we moved all of our sites to a nice Windows 2003 dedicated server running IIS 6. After the move, we started having strange caching issues, where we’d make a change in the administration interface, but those changes would not show up in the public interface. At first I thought it was some kind of client caching issue, but clearing temporary Internet files did nothing.
I eventually decided that it was not a browser problem, so I assumed it could be something in the LWP (which does its own memory and disk caching). A recycle of the application pool would let the changes flow through, but doing a recycle every time I (or one of our hosted customers) made changes in the admin interface was not a practical solution.
Tracking the problem down further showed that the LWP was doing exactly what it always did to "publish" the new content, but that the cached pages were not being rebuilt. I finally realized that IIS must be caching the ASP pages itself, although I didn’t realize that was possible at the time. After all, it had never happened before.
ASP Page Cache
I did a little research and discovered that, yes indeed, IIS does cache ASP pages. It was an unexpected discovery because it makes little sense to me. Why create ASP pages unless they deliver dynamic content? And if the content is dynamic, why on earth would you cache it at the page level? Granted, IIS is smart enough to detect when the underlying ASP file changes, but that does you no good if your ASP page is really just a controller that drives the current view? The page file never changes, but the content does.
But all that ranting is just me imposing my view of ASP development on the situation. Obviously, other people must use ASP very differently. Okay, fine.
After researching the issue with Google and MSDN, I learned that IIS has application settings for controlling the caching of ASP pages. Well, cool. Now all I have to do is change the settings on the affected sites and I’ll be good to go.
Here’s what the instructions said to do:
Note the part I highlighted in red. It is amazing how one wrong phrase can send you merrily down the path to confusion. I’m one of those strange people who learn quickly by reading manuals. So, having a well-conditioned (and perhaps misguided) trust in documentation, I tried to follow the instructions as written.
Don’t Believe Everything You Read
I immediately ran into a simple but profound problem: There is no Cache Options tab.
Wow. What am I doing wrong? Do I have some other setting that is disabling the Cache Options tab? Do I need to do something to say that the site is an ASP site, not really a .NET site? How do I get the Cache Options tab back?
While searching around in the IIS console, I discovered that the ASP caching tab does exist at the "Web Sites" node level, but I generally try to set site settings at the site level. I’ve learned the hard way that tweaking settings at the global level can be dangerous, as I would later re-discover.
After much tearing of hair and loud cursing that scared the dogs out of my office, I tried to find evidence that others have the same problem. Picking the right terms to find that kind of thing online is a bit of an art, but I eventually found another frustrated user on MobyThreads who had the same question. Here was the response from an MS support person:
Are you right clicking on the web site name such as Default Web Site? If you are, you should be right clicking on Web Sites, choose Properties, choose the Home Directory tab, click on Configuration, then you will see a Cache Option tab. Hope this helps! Thank you, Jackie Jaynes [MSFT]
Microsoft IIS
Notice how she makes it sound like the poor user made the mistake? I see no mention of the fact that the docs are wrong. Deflecting blame back on the customer is an all-too-common MS support tactic that I find unfair and very annoying.
Fist shaking aside, I now had evidence that I really did need to change the settings at the global level because there is no other place to make them. Alrighty then, on with the show.
Global Disaster
Now that I knew what to do, making the change was easy. I went to the property settings on the Web Sites node and selected "Do not cache ASP files." Cool. No problem. I now had it on the authority of Jackie, vaunted member of the Microsoft IIS team, that this was the right thing to do.
In saving my change, I got an extra dialog that said something about how some of the sites override the settings I was saving. Part of my brain registered the reference to "script mappings," but since I didn’t change the script mappings, I assumed it was talking about the change I did make. I selected all of the listed sites and clicked OK.
Unfortunately, my poor brain must have been distracted by the MS documentation betrayal, because another thing I’ve learned over time is that you almost never want to allow IIS to replicate global setting changes down to existing Web sites. That’s a good way to break stuff. And break stuff I did.
What I had really done was tell IIS to set all of my sites back to .NET 1.1 and to remove all of the custom script mappings I had set up on various sites. That simple click killed about ten Web sites in an instant. She’s dead, Jim.
Isn’t it funny how an action that makes perfect sense just a moment before can suddenly seem like the stupidest thing you could have done? The words "script mappings" penetrated my fog of confusion about .5 seconds after I clicked OK. The color drained from my face. More cursing. The dogs which had been brave enough to return to my office after my earlier ranting ran out again.
In retrospect, I really should have known better. How could the individual sites override a setting that couldn’t be set at the site level? I think I was still clinging to the wording in the documentation that said it was possible to set cache options at the site level, but I somehow lacked the magic to do so.
At first, I tried to rectify my mistake by re-applying the correct settings to the individual sites. That worked okay for some sites, but I got very strange behavior from others, an IIS reset notwithstanding.
Backup Saves the Day
Fortunately, the horrifying crash of our previous Web server got me in the habit of regularly backing up IIS settings when I add a new site or make any significant changes. That practice saved my bacon. I was able to restore my IIS settings back to the way they were before the havoc began. I did get a few beads of sweat on my brow when IIS gave me dire warnings about how it could be a lengthy process to delete all my current settings and restart the service, but I had little choice in the matter. In reality, it took just a few seconds.
I re-applied the ASP cache option setting, and this time, did not select any sites when the script mapping override message appeared. I tested a few ASP sites and found that they were behaving the way they should, and that server caching did indeed appear to be off. Life was good again.
The Moral of the Story
Let this story be a lesson to all you developers who often find yourself wearing the IIS system administrator’s hat:
- Back up your IIS settings regularly. Do it particularly after setting up a new site and before making any changes at the global level. If the IIS metabase gets corrupted or you click OK when you shouldn’t, the backup can save you hours of re-configuration.
- Don’t believe everything you read. Even Microsoft gets it wrong at times.
