IIS Home @ it-notebook.org

Using server side include directives in .html pages, and its caveats

(Kristofer Gafvert, August 29, 2007)


At one time or another, many websites change technology to process and show the pages. The reason for this can be several; a complete new website, or an update to the old website to make it easier to maintain. Any website administrator that has been using pure HTML knows about the problem that exists when adding a new menu item to the navigational menu. All old pages must be updated with this new menu item, a not so fun job to do. A common way to solve this is to include the menu with a server side include (SSI) statement, but that means that there are code that must be processed on the server. The usual extension for files that include SSI statements is either .shtml or .shtm, because this extension tells the web server to process the file before sending it to the client.

Changing the extension on all files in a website is however not something you would like to do, for several reasons. First of all, we have all the work to change the extension, which admittedly can be done fairly easy with a script. Second, you will also break all links, both on your own website (which you have control over, so you can fix it), and on other websites (which you do not have control over, and cannot fix). And the third point, search engines will have to re-index your website, which may affect ranking and of course also traffic patterns.

Mapping .html to ssinc.dll - not the best solution

What many people do not know, or realize, is that the extension does not actually need to be tied to a specific server side processing technology. We can treat .html as ASP files, .asp as ASP.NET and even .php as ASP.NET. This is exactly what we want to do, we want to tell the web server to process the code in the file, without changing the existing extension.

Most people with enough knowledge about IIS to be able to map extensions to different ISAPI applications, would tell you to map .html (or .htm, for the rest of this article, .html refers to both extensions) to the ssinc.dll ISAPI application, without even thinking of its consequences. Other people, with a little more knowledge will think twice before doing it.

Mapping .html to the ssinc.dll ISAPI application is perfectly fine to solve the problem. But we must be aware of that .html are processed as static files on IIS (by default), thus cacheable and very performant. When you change .html to be processed as SHTML by ssinc.dll, you also change this behavior. All .html files will now require server-side processing and is not cacheable.

Since the files are not cacheable, the CPU usage will increase. Mapping .html to ssinc.dll also means we have a new security risk - all html pages will be processed on the server by ssinc.dll. So any security bug in ssinc.dll may affect the security of the website, and since SSI technology is quite old, bugs in it may not be prioritized.

Mapping .html to asp.dll - a better solution

A better approach to process SSI directives in .html files is to map the .html extension to the ASP.dll ISAPI application. It has better caching functionality (it is aware of html files that has no server-side code and can handle them more optimally than the ssinc.dll), it is more widely used (so expect any bugs in it to be fixed faster) and it offers more functionality in case you need/want to expand with more code later on. And of course, it can also process SSI directives, not just ASP code.

As a conclusion, how to actually map .html files to the ASP.dll ISAPI application.

  • In IIS Manager, right click the website and click Properties
  • Click on the Home Directory tab, and then click on the Configuration button
  • Click the Add button, type "C:\WINDOWS\system32\inetsrv\asp.dll" in the Executable field and either .html or .htm in the extension field (depending on which extension you want to be mapped)
  • Click OK
Mapping .html extension to the asp.dll in IIS Manager

Applies to [?]

IIS 6.0


IIS Server-Side Include Directives
Using Server-Side Include Directives