The Developer’s Guide to Configuration Files, Part One

XML Configuration files for ASP.NET and IIS

Welcome to the .Config Jungle!

Every .NET developer knows about basic configuration files; web.Config for web sites, applicationHost.Config for IIS, machine.Config for global settings and app.Config for applications. This blog entry here is an in depth exploration of the different configuration files for IIS and ASP.NET, the way IIS 7.0 uses them, and what they contain.

This is not in any way an exhaustive list of .Config files. Do a search for “*.Config” on your server, and you will get a glimpse of what I am referring to.

Luckily  most are app.Config files for any given application. Still, there are other configuration files out there.

Web.Config

Web.Config is the file that 99.99% of all ASP.NET developers out there relate to. It is the meat and staple of the framework, the place where you fine tune your application and where the CLR looks for information on how to behave. In a later entry in this blog we will perform an autopsy on it, but right now: Let’s explore the hierarchy of web.Config files on the server.

Web.Config can be found on several levels throughout the web server. The primary location for the configuration file of any web application is in the virtual directory of the site itself. So if your site is located at c:\inetpub\sitename the web.Config of your web application will also be located in that folder. Furthermore you can place web.Config files in subdirectories to override behavior for files placed in those folders.

There is also a root web.Config in the same folder as machine.Config, as outlined below. If you want to make machine wide settings, but only for your web applications, this is the place to do it! Note that the site’s and subsites’ web.Config settings will override those of the machine level web.Config (and those of machine.Config)

Machine.Config

Base path: %systemroot%\Microsoft.NET\Framework\versionNumber\CONFIG\Machine.config

Examples for framework version 2 and 4:

.NET 2.0: %systemroot%\Microsoft.NET\Framework\v2.0.50727\CONFIG

.NET 4.0: %systemroot%\Microsoft.NET\Framework\v4.0.30319\Config

At this location you find the root configuration file for all web.Config and app.Config files on the machine. Changes made to this file will affect all CLR reliant applications and web applications on the server (using the targeted version of the framework, for instance 2.0 or 4.0), unless local configuration files override that particular section you modified.

When you create a new web.Config file, it copies settings from machine.Config. In a way, machine.Config can be considered a "super class" (java lingo) or "base class" of config files. ^^ 

An example:

A web application targeting .NET 2.0 will use machine.Config settings if, and only if, there are no web.Config rules in the root directory of the web app (i.e. c:\inetpub\myWebSite\web.Config) or in an appropriate subdirectory. So, given the ASP.NET page myConfigUseTest.aspx, located at c:\inetpub\myWebSite\someSubDirectory\ it will first use web.Config settings from c:\inetpub\myWebSite\someSubDirectory\ (if any web.Config file exists there), then from c:\inetpub\myWebSite\ and then, if the root directory web.Config does not provide information, it will look in web.Config and machine.Config, in that order, at %systemroot%\Microsoft.NET\Framework\v2.0.50727\CONFIG.

ApplicationHost.Config

ApplicationHost.Config is IIS, Internet Information Server’s, very own configuration file. When you work in IIS manager, clicking all those fancy buttons, the purely IIS specific info will wind up in ApplicationHost.Config. This means that IIS Manager is nothing but an application using .NET framework’s own configuration management classes to present and change information within web.Config, machine.Config and applicationHost.Config files.

ApplicationHost.Config can be found at %systemroot%\System32\inetsrv\config, which is IIS own folder location on the server. Note that inetmgr.exe is also there, the very executable that is IIS Manager itself.

So, by using IIS Manager the buttons and settings under IIS will make it’s way into applicationHost.Config, but the story does not end there.

Changing any of the ASP.NET settings will change web.Config for the site you have currently selected. That’s right, IIS manager knows which site you are on and changes the appropriate web.Config based on that.

If you are positioned on the IIS server site node itself, those settings will be persisted in the root level web.Config found in the same folder as machine.Config.

Changes to application pools and site bindings will be persisted in applicationHost.Config.

New in IIS 7.0 is the integrated pipeline. In older versions of IIS, the so called classic pipeline was used. It loaded an execution pipeline for IIS, then one for ASP.NET. Problem with this model is that some things, like authentication, happened twice. Once for IIS, then again for ASP.NET. The new integrated pipeline runs everything in one pipeline, which means that authentication and such things happens only once. All of this naturally means that the ISAPI filter that hosted ASP.NET is gone, bye bye aspnet_isapi.dll. ASP.NET is now a first class citizen of the pipeline, and ASP.NET modules can be called before, or after, or in between, IIS modules when the pipeline initially loads. This also means that since ASP.NET is integrated into the pipeline, it’s features can be used on the non-ASP.NET elements in the pipeline as well. For example: You can use ASP.NET authentication to protect older IIS resources in the pipeline, like your company’s legacy ASP pages.

Extending IIS has never been easier. Those horrid ISAPI filters of the past are gone, and in their place are two brand new APIs for injecting company specific behavior into the integrated pipeline.

The first API is a native code C++ API, the second is a managed code .NET API.

Want to change the modules loaded in the integrated pipeline? 

Well, you do that in web.Config, silly!  

So, to the SharePointers out there: web.Config is what loads all those SharePoint specific dll's, and makes SharePoint available to some web applications but not others. 

For the purpose of demonstration I will lastly show the contents of an applicationHost.Config file.

I will not show the whole shebang, but rather a site binding section for a SharePoint portal located under <System.ApplicationHost> and <Sites> 


<site name="SharePoint - 80" id="267757848" serverAutoStart="true">
<application path="/" applicationPool="SharePoint_80_b25de04f0d124507b3da5c56bdfad000">
<virtualDirectory path="/" physicalPath="C:\inetpub\wwwroot\wss\VirtualDirectories\80" />
<virtualDirectory path="/_vti_bin" physicalPath="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\isapi" />
<virtualDirectory path="/_layouts" physicalPath="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\template\layouts" />
<virtualDirectory path="/_wpresources" physicalPath="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\wpresources" />
<virtualDirectory path="/_controltemplates" physicalPath="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\template\controltemplates" />
</application>
<application path="/_layouts/images" applicationPool="SharePoint_80_b25de04f0d124507b3da5c56bdfad000">
<virtualDirectory path="/" physicalPath="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\template\images" />
</application>
<application path="/_layouts/inc" applicationPool="SharePoint_80_b25de04f0d124507b3da5c56bdfad000">
<virtualDirectory path="/" physicalPath="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\template\layouts\inc" />
</application>
<bindings>
<binding protocol="http" bindingInformation=":80:" />
</bindings>
<logFile logFormat="W3C" />
<limits connectionTimeout="00:04:00" />
</site>

 Note the following:

• The configuration file binds a specific application pool to a site
• This is where the SharePoint web site is mapped to it's SharePoint Root (12 HIVE) folders
• If you want a custom virtual directory to place resources in (other than the customary \templates\images etc folders, you could link one up in applicationHost.Config (goes for everyone, not only SharePointers)
• this is one of the myriad places in which timeout settings can be found

  Trivia:

• Did you know that the /_vti_bin folder name comes from "Vermeer Technologies Incorporated binary folder". Vermeer was v1.0 of FrontPage Extension, the name it had in the pre-Microsoft days, and as we all know, FP Extensions later became SharePoint Designer. This exiting folder has, among other things, native code DLLs that you can use to rape, errr, communicate with SharePoint (These DLLs bypass all security and force changes upon ONET.XML and other SharePoint files, sort of in a backdoor manner). I am planning a later article called "Integrating With SharePoint", in which I will give code examples on several ways to integrate with SharePoint, and the _vti_bin folder dll's will most certainly be covered!

References:
For the blog entries on configuration files I use the following literature:

• CLR via C#, by Jeffrey Richter
• Professional ASP.NET 3.5 In C# and VB, by Evjen et al.
• msdn .NET Framework documentation