Author's Note: I realized that it may be best to just start at the ground level before I get started in an article series entitled, "Anatomy of a DNN web.config file" . There are a lot of new enthusiasts out there who may benefit from the background info before we jump in. So, without further adue...
This is the "pre-" first installment in a series that will cover the parts of the web.config file to give you an idea of how to manipulate and customize your DotNetNuke portal. The web.config file is one touchy little beast however, so you must tread easy when you're walking in its territory. One ill character could leave your site in a deadened state and fixing it can be trouble, especially, if you're not even aware of what you did to cause it.
I guess it is best to start at the beginning and cover some background info first. If you're brand new to development and to web.config files, you can check out some other articles on the site that can help. (Check the related links section on the right).
Web.config files are not specific to only DotNetNuke websites, but are used in .Net web applications in general. However, there are configuration settings that are specific to DotNetNuke found in your DNN web.config file that you won't find in non DNN sites.
What Exactly is a Web.Config File Anyway?
At the most basic definition, a web.config file is simply a XML structured file that lists settings used in your web application. It can be used to define settings such as connection strings to a database or authentication mode settings for example. Also, because config files are stored as XML files, any text based editor can be used to modify or create the file. No special software is required.
The .net config system is an extensible system that allows site developers to define specific configuration settings for websites that will guide how the entire site operates. Changes can be made to the web.config at any time with minimal impact on the operation of the site.
This allows you to make system changes on the fly without requiring you to reboot, recompile or redeploy the site. You can make changes on the server and hit save and the changes will take effect immediately.
Any time you make a change to the web.config file however, note that it will cause the website application pool to recycle itself which will cause a slightly longer load time the first time the site is hit after a change.
Order of Web.Config Operations
.Net websites can include many config files, so long as there is only one in any given directory. So for example, I can have a web.config file in the root directory of my website (c:\inetpub\wwwroot) and then another in (c:\inetpub\wwwroot\subdirectory).
The config file in my subdirectory can include specific settings that are only applied to the files found in that directory and will inherit the settings from my root web.config file, so I don't need to redefine those. Although, I can override those settings from the inherited web.config if I wanted to simply by redefining those in the subdirectory config file.
At the heart of every .net enabled web server is a file called machine.config. This file is located on the server at systemroot\Microsoft.NET\Framework\Version\CONFIG\Machine.config. This file is the granddaddy master of all the config files. It dictates how the entire server is configured and is also the file that all of the web.config files in all the root directories of all the websites on the server inherit from.
And More Benefits of Config Files
A couple of other things worth mentioning is that because the system is extensible, new sections and configuration parameters can be defined by YOU! You are not only limited to the sections defined in the Machine.config file.
Additionally, unlike javascript files, users can't browse to your .config file and view it. Windows IIS servers are configured so that they don't server requests for .config files. This is very important because we don't want our application settings exposed to the Curious George's of the worlds…especially things like connection string user id's and passwords.
Basic Format, or Structure, of a Config File
Config files contain a collection of settings formatted as a nested hierarchy of XML tag. The tags (and subtags) include attributes that actually specify the configuration settings.
Config files must be well-formed XML and are case sensitive. You'll realize this the first time you modify your web.config file and see the heart stopping yellow error screen of website death and aren't sure what in the world you just did to kill the site. One simple syntactical error or malformed tag will cause this to happen, so just keep that in mind when your working.
The first, or beginning, section of the .config file is the section and is the Root XML tag. All other sections are found in between this section. Inside of the section, there are two main areas: the configuration section HANDLER DECLARATION area and the configuration section SETTINGS area.
The handler declaration are appears at the top of the config file and in between the … tags. This is where you will notice many of the DNN specific settings. The declarations in this area must provide a corresponding section found later in the config file that define the specific configuration information as well as the class that processes the configuration data for that specific section.
Tag names and attributes are always camel cased. This means that the first character of the tag name is lowercase the first letter of any subsequent concatenated words are in uppercase like this: myCamelCasedTag.
Conversely, attribute values are Pascal cased. This means that the first character of the attribute is upper cased, as well as any subsequent concatenated word like this: MyAttributeIsPascalCased.
*the only exception to this are for the attributes "true" and "false", which are ALWAYS lowercase.
Putting it all together we would have a tag like this:
<myCamelCasedTag="true" myAttributeCasing="PascalCased" />
Whew! Is that just about enough for one day or what?
Ok, now that you have the quick (??) overview of the web.config file and what it means and provides for your site, you're ready to tackle the DotNetNuke specifics, which we'll begin covering in the next article, the real first article of the Anatomy of a DNN Web.config File series. Stay Tuned!