7/27/2019 10 Things ASP

1/17

10 Things ASP.NET Developers Should Know About

Web.config Inheritance and Overrides

TheASP.NET configuration systemis build around the idea of inheritance:

Each Web.config file applies configuration settings to the directory that it is in and to all of

the child directories below it. Settings in child directories can optionally override or modifysettings that are specified in parent directories. Configuration settings in a Web.config file can

optionally be applied to individual files or subdirectories by specifying a path in alocationelement.

The root of the ASP.NET configuration hierarchy is the

systemroot\Microsoft.NET\Framework\versionNumber\CONFIG\Web.config file, which includes settings

that apply to all ASP.NET applications that run a specific version of the .NET Framework. Because each

ASP.NET application inherits default configuration settings from the root Web.config file, you need to

create Web.config files only for settings that override the default settings.

For a lot of sites, you don't really need to know about that - you can get by with one Web.config file

for the site. But, knowing how the inheritance works - and how to control it - can really help out.

I've noticed that a lot of the questions I answer questions on forums, StackOverflow, and internal e-

mail lists can be solved by better understanding how ASP.NET configuration inheritance and overrideswork. And so, a bunch of tips about how ASP.NET configuration inheritance and overrides work! I'll

start with some basics, but there are some towards the end I'll bet most ASP.NET developers don't

know.

Tip 1: Using Web.config files in site subfolders

And ASP.NET website's Web.config is part of an inheritance chain. Your website's subfolders can have

Web.config - an example is the Web.config file in an ASP.NET MVC application's View folder which

does things like preventing directly viewing the View templates:

http://msdn.microsoft.com/en-us/library/ms178683.aspxhttp://msdn.microsoft.com/en-us/library/ms178683.aspxhttp://msdn.microsoft.com/en-us/library/ms178683.aspxhttp://msdn.microsoft.com/en-us/library/b6x6shw7.aspxhttp://msdn.microsoft.com/en-us/library/b6x6shw7.aspxhttp://msdn.microsoft.com/en-us/library/b6x6shw7.aspxhttp://msdn.microsoft.com/en-us/library/b6x6shw7.aspxhttp://msdn.microsoft.com/en-us/library/ms178683.aspx

7/27/2019 10 Things ASP

2/17

This allows for setting general settings at the site level and overriding them when necessary. Any

settings in the base Web.config that aren't overridden in the subfolder stay in effect, so the "child"

Web.config can be pretty small. You can continue to nest them, so sub-sub-subfolders can get their

own Web.config if needed. Some of the most common uses of subfolders are to restrict permission

(e.g. requiring authentication or restricting access to resources), but you can also use them to dothings like include default namespaces in Views, toggle handlers, etc.

Tip 2: Understand how your site Web.config inherits its

settings

But there's an inheritance chain above the site, too. Here's a simplified version from the MSDN docs:

Configuration

levelFile name File description

Server Machine.config

The Machine.config file contains the ASP.NET schema for all

of the Web applications on the server. This file is at the topof the configuration merge hierarchy.

IIS ApplicationHost.config

ApplicationHost.config is the root file of the IIS 7.0

configuration system. It includes definitions of all sites,

applications, virtual directories, and application pools, as well

as global defaults for the Web server settings. It is in the

following location:

http://www.flickr.com/photos/36836555@N00/6688643777/

7/27/2019 10 Things ASP

3/17

%windir%\system32\inetsrv\config

Root Web Web.config

The Web.config file for the server is stored in the same

directory as the Machine.config file and contains default

values for most of the system.web configuration sections. At

run time, this file is merged second from the top in the

configuration hierarchy.

Web site Web.config

The Web.config file for a specific Web site contains settings

that apply to the Web site and inherit downward through all

of the ASP.NET applications and subdirectories of the site.

ASP.NET

application root

directory

Web.config

The Web.config file for a specific ASP.NET application is

located in the root directory of the application and contains

settings that apply to the Web application and inherit

downward through all of the subdirectories in its branch.

ASP.NET

application

subdirectory

Web.config

The Web.config file for an application subdirectory contains

settings that apply to this subdirectory and inherit downward

through all of the subdirectories in its branch.

So your website's configuration's actually inherited a bunch of settings that were set at the server

level. That's nice for a few reasons:

1. It allows the ASP.NET / IIS teams to migrate settings that aren't commonly modified from the

project template Web.config files to server defaults, keeping your Web.config files smaller and

more readable. For example,ASP.NET 4 migrated a bunch of handler registrations to

Machine.config, so the Empty ASP.NET Application Web.config is slimmed down to

about 8 lines.

2. You can override things at the server level as needed, and they'll take effect for allapplications. For example, you can seton production servers

to disable trace output and debug capabilities.

3. You can find a lot of useful information in the Machine.config default settings since

they're stored in plain text. For example, the ASP.NET Membership Provider has some defaults

set for password requirements and the membership database, and you can look them up by

looking in the appropriate .NET framework version's Machine.config. For a default installation

of ASP.NET 4, that's found in

C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Config\machine.config with a quick

search for .

Tip 3: Understand how your Web.config inherits IIS

configuration settingsThis overlaps a bit of Tip 2, but it bears repeating. Long-time ASP.NET developers (myself included)

are prone to thinking of ASP.NET and IIS configuration separately, but that all changed with IIS 7.

This is all pretty old news, as IIS 7 has been out for a while, but it hasn't been completely absorbed by

ASP.NET developers.

CarlosAg summed this up well in a post from 2006(!) which explainedThe New Configuration

System in IIS 7. I'm not going to rehash his post here - go read it. Some important takeaways are

http://weblogs.asp.net/scottgu/archive/2009/08/25/clean-web-config-files-vs-2010-and-net-4-0-series.aspxhttp://weblogs.asp.net/scottgu/archive/2009/08/25/clean-web-config-files-vs-2010-and-net-4-0-series.aspxhttp://weblogs.asp.net/scottgu/archive/2009/08/25/clean-web-config-files-vs-2010-and-net-4-0-series.aspxhttp://weblogs.asp.net/scottgu/archive/2009/08/25/clean-web-config-files-vs-2010-and-net-4-0-series.aspxhttp://weblogs.asp.net/scottgu/archive/2009/08/25/clean-web-config-files-vs-2010-and-net-4-0-series.aspxhttp://msdn.microsoft.com/en-us/library/ms228298.aspxhttp://msdn.microsoft.com/en-us/library/ms228298.aspxhttp://msdn.microsoft.com/en-us/library/ms228298.aspxhttp://blogs.msdn.com/b/carlosag/archive/2006/04/25/iis7configurationsystem.aspxhttp://blogs.msdn.com/b/carlosag/archive/2006/04/25/iis7configurationsystem.aspxhttp://blogs.msdn.com/b/carlosag/archive/2006/04/25/iis7configurationsystem.aspxhttp://blogs.msdn.com/b/carlosag/archive/2006/04/25/iis7configurationsystem.aspxhttp://blogs.msdn.com/b/carlosag/archive/2006/04/25/iis7configurationsystem.aspxhttp://blogs.msdn.com/b/carlosag/archive/2006/04/25/iis7configurationsystem.aspxhttp://msdn.microsoft.com/en-us/library/ms228298.aspxhttp://weblogs.asp.net/scottgu/archive/2009/08/25/clean-web-config-files-vs-2010-and-net-4-0-series.aspxhttp://weblogs.asp.net/scottgu/archive/2009/08/25/clean-web-config-files-vs-2010-and-net-4-0-series.aspxhttp://weblogs.asp.net/scottgu/archive/2009/08/25/clean-web-config-files-vs-2010-and-net-4-0-series.aspx

7/27/2019 10 Things ASP

4/17

that both the ApplicationHost.config and Machine.config feed into the configuration settings in your

site's Web.config, as shown in Carlos' diagram:

In addition to the understanding how things work part of it, this is also good to know because - based

on the info in Tip 2 - you can see what the base settings are, and how you can override them in your

application's Web.config. This is why you can do pretty advanced things like configure rules on for

theURL Rewrite Module in your application's web.config.

Of course, server administrators don't necessarily want to allow any application on the server to

modify settings via Web.config, so there are configurable policies in the ApplicationHost.config which

state whether individual applications can override settings. There's also anAdministration.config

filewhich controls things like Module registration.

There's one kind of new update to this list - using aspnet.config for Application Pool

tuning. It's found in the same directory as Machine.config, and it's been around since .NET 2.0.

However, as of ASP.NET 4 it's been expanded to handle things like concurrency and threading, as

explained in Scott Forsyth's post,Setting an aspnet.config File per Application Pool. While not

something most ASP.NET developers will need to use, it's good to know that you can control things

like maxConcurrentRequestsPerCPU, maxConcurrentThreadsPerCPU and requestQueueLimit at the

application pool level.

Tip 4: Location, locationWhile it's nice to be able to override settings in a subfolder using nested Web.config files, that can

become hard to manage. In a large application, it can be difficult to manage settings because you

can't see the effective permissions in one place. Another option is to use the elementto

target settings to a specific location. For example, I previously showed how to use this toallow large

file uploads to a specific directory in an ASP.NET applicationusing the location element:

?

1

2

3

4

5

6

7

Tip 5: Clearing parent settings when adding to a

collection

Sometimes you want to remove all inherited settings and start fresh. A common place you'll see this is

in handler, module, connection string and provider registration - places where configuration is used to

http://learn.iis.net/page.aspx/465/url-rewrite-module-configuration-reference/http://learn.iis.net/page.aspx/465/url-rewrite-module-configuration-reference/http://learn.iis.net/page.aspx/465/url-rewrite-module-configuration-reference/http://blogs.iis.net/davcox/archive/2009/12/02/what-is-administration-config-for-iis.aspxhttp://blogs.iis.net/davcox/archive/2009/12/02/what-is-administration-config-for-iis.aspxhttp://blogs.iis.net/davcox/archive/2009/12/02/what-is-administration-config-for-iis.aspxhttp://blogs.iis.net/davcox/archive/2009/12/02/what-is-administration-config-for-iis.aspxhttp://weblogs.asp.net/owscott/archive/2011/12/01/setting-an-aspnet-config-file-per-application-pool.aspxhttp://weblogs.asp.net/owscott/archive/2011/12/01/setting-an-aspnet-config-file-per-application-pool.aspxhttp://weblogs.asp.net/owscott/archive/2011/12/01/setting-an-aspnet-config-file-per-application-pool.aspxhttp://msdn.microsoft.com/en-us/library/b6x6shw7.aspxhttp://msdn.microsoft.com/en-us/library/b6x6shw7.aspxhttp://msdn.microsoft.com/en-us/library/b6x6shw7.aspxhttp://weblogs.asp.net/jgalloway/archive/2008/01/08/large-file-uploads-in-asp-net.aspxhttp://weblogs.asp.net/jgalloway/archive/2008/01/08/large-file-uploads-in-asp-net.aspxhttp://weblogs.asp.net/jgalloway/archive/2008/01/08/large-file-uploads-in-asp-net.aspxhttp://weblogs.asp.net/jgalloway/archive/2008/01/08/large-file-uploads-in-asp-net.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2008/01/08/large-file-uploads-in-asp-net.aspxhttp://weblogs.asp.net/jgalloway/archive/2008/01/08/large-file-uploads-in-asp-net.aspxhttp://msdn.microsoft.com/en-us/library/b6x6shw7.aspxhttp://weblogs.asp.net/owscott/archive/2011/12/01/setting-an-aspnet-config-file-per-application-pool.aspxhttp://blogs.iis.net/davcox/archive/2009/12/02/what-is-administration-config-for-iis.aspxhttp://blogs.iis.net/davcox/archive/2009/12/02/what-is-administration-config-for-iis.aspxhttp://learn.iis.net/page.aspx/465/url-rewrite-module-configuration-reference/

7/27/2019 10 Things ASP

5/17

populate a collection.Scott Guthrie blogged about an example in which just adding a new

Membership Provider causes problems, because you end up with two providers - the default, and

the one you just added. It's important to clear the collection before adding your new provider

using the element, like this:

?

1

2

3

4

5

6

7

8

9

10

11

12

13

14

As Scott explains, failure to the collection first results in both providers attempting to handle

membership, which probably isn't what you intended.

Tip 6: Locking settings with with allowOverride and

inheritInChildApplications

You may need to prevent sub-applications from overriding or extending settings. You can do that with

the allowOverride attribute, which does exactly what the name suggests - the same way a sealed class

prevents changes via a derived class. TheMSDN documentationsummarizes this well:

You can lock configuration settings in ASP.NET configuration files (Web.config files) by adding anallowOverride attribute to a location element and setting the allowOverride attribute to false. Then

within the location element, you can define the configuration section that you want to lock. ASP.NET

will throw an exception if another configuration file attempts to override any configuration section that

is defined within this locked location element.

Using a location element with an allowOverride=false attribute locks the entire configuration section.

You can also lock individual configuration elements and attributes using lockItem, lockElements,

lockAttributes, lockAllAttributesExcept, and lockAllElementsExcept.

That last part there - using attributes on sections - works because those lock attributes are among

thegeneral attributes inherited by section elements.

Tip 7: Disinheriting your child applications with

inheritInChildApplications="false"

If you've got settings that should only apply to the parent application and shouldn't be inherited, you

can use the inheritInChildApplications attribute on any section or location element. That makes

the settings at the current level, but inheriting applications and subfolders don't have to bother with

clearing and rebuilding configuration just to remove those settings.

This came up in a recent question on StackOverflow: Unloading parts of a web.config file from a

child application

http://weblogs.asp.net/scottgu/archive/2006/11/20/common-gotcha-don-t-forget-to-clear-when-adding-providers.aspxhttp://weblogs.asp.net/scottgu/archive/2006/11/20/common-gotcha-don-t-forget-to-clear-when-adding-providers.aspxhttp://weblogs.asp.net/scottgu/archive/2006/11/20/common-gotcha-don-t-forget-to-clear-when-adding-providers.aspxhttp://weblogs.asp.net/scottgu/archive/2006/11/20/common-gotcha-don-t-forget-to-clear-when-adding-providers.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://msdn.microsoft.com/en-us/library/ms178693.aspxhttp://msdn.microsoft.com/en-us/library/ms178693.aspxhttp://msdn.microsoft.com/en-us/library/ms178693.aspxhttp://msdn.microsoft.com/en-us/library/ms228167.aspxhttp://msdn.microsoft.com/en-us/library/ms228167.aspxhttp://msdn.microsoft.com/en-us/library/ms228167.aspxhttp://stackoverflow.com/questions/8536091/unloading-parts-of-a-web-config-file-from-a-child-applicationhttp://stackoverflow.com/questions/8536091/unloading-parts-of-a-web-config-file-from-a-child-applicationhttp://stackoverflow.com/questions/8536091/unloading-parts-of-a-web-config-file-from-a-child-applicationhttp://stackoverflow.com/questions/8536091/unloading-parts-of-a-web-config-file-from-a-child-applicationhttp://stackoverflow.com/questions/8536091/unloading-parts-of-a-web-config-file-from-a-child-applicationhttp://msdn.microsoft.com/en-us/library/ms228167.aspxhttp://msdn.microsoft.com/en-us/library/ms178693.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/scottgu/archive/2006/11/20/common-gotcha-don-t-forget-to-clear-when-adding-providers.aspxhttp://weblogs.asp.net/scottgu/archive/2006/11/20/common-gotcha-don-t-forget-to-clear-when-adding-providers.aspx

7/27/2019 10 Things ASP

6/17

Dave Mroz

329

Unloading parts of a web.config file from a child application6 Votes

We have a large content management system configured as the main site in IIS. We also have a handful

of independent applications that are configured as applications under IIS 7.5. The issue that were

running into is that the child applications are inheriting the web.config file from the parent application even

though they are completely independent applications and share next to no configuration settings. Ideally,

wed like to stop the child applications from inheriting the web.config file at all. Is that possible?

If not, wed like to tell the child applications not to inherit parts of the master web.config file. Weve tried

editing the child web.config files and adding directives to the configuration file, but that doesnt seem to be

working.

I understand that we can modify the parent web.config file to add in directives to effectively restrict the

inheritance; howeverwere hesitant to do this because were not sure how that will impact the CMS. The

web.config file in question is also about 1000 lines long and were not sure how many changed wed need

to make. We can, of course, move forward with this solution and test thoroughly, but Id rather find one

that doesnt require modifying the parent application.

Weve also tried updating the child web.config files to manually remove certain elements of the parent

web.config and weve had mixed results. We can unload HTTP handlers and things like that, but we cant

seem to unload any of the references to the App_Code folder.

In short, is it possible to have a child application NOT inherit any part of the web.config file? If not, is it

possible to overwrite or otherwise force the child to ignore settings in the parent web.config file?

Thanks

Dave

.net

inheritance

web-config

Jon Galloway

25664

Answer 18 Votes

In addition to using or overwriting the settings in the child web.config, you can use theinheritInChildApplications setting in conjunction with in the parent web.config.

Example:

http://stackoverflow.com/users/1102128http://stackoverflow.com/users/1102128http://stackoverflow.com/questions/8536091http://stackoverflow.com/users/5http://stackoverflow.com/users/5http://stackoverflow.com/questions/8536091#8548245http://stackoverflow.com/questions/8536091#8548245http://stackoverflow.com/users/5http://stackoverflow.com/questions/8536091http://stackoverflow.com/users/1102128http://www.stacktack.com/http://www.stacktack.com/

7/27/2019 10 Things ASP

7/17

You can wrap the location around the entire or just around specific sections.

Some links for more info:

inheritInChildApplications on MSDN(read the community content at the bottom for more)

StackOverflow:Avoid web.config inheritance in child web application using

inheritInChildApplications Blog post:Stopping web.config inheritance

+ More Answers

Since Web.config is so heavily built on the concept of inheritance, it's not surprising that turning it off

for a section can have some side effects. The aptly self-named "Run Things Proper Harry," a.k.a.

rtpHarry, has written up two good posts covering usage and important things to be aware of.

SOLVED: Breaking parent web.config dependencies in sub applications

SOLVED: IIS7, validateIntegratedModeConfiguration and inheritInChildApplicationsclash

Tip 8: Use configSource to separate configuration into

separate files

While I've been discussing modification of Web.config settngs through inheritance, it only makes sense

to mentions some useful ways to handle overriding Web.config settings.

Any Web.config section can be moved to a separate file by setting theconfigSource

attributeto a file reference. I've mostly used this for handling connection strings, since it allows

you a lot more flexibility over versioning and and deployment. Instead of having different Web.config

files for each environment ("Oops! Just deployed the staging Web.config to production!!!"). It looks

like this:

?1

2

3

...

Then your connectionStrings.config file only needs to change between environments, and can contain

specific settings. It holds the contents of the element you're referring to, so it looks like this:

?

1

2

3

4

Another way I've seen this done is to have differently named connection strings config files for each

environment (e.g. dev.config, staging.config, production.config). That allows you to check them all in

to source control and not worry about getting files with the same name but different contents mixed

up, but the tradeoff is that your Web.config in each environment needs to be updated to point to the

right config source.

So, this is a handy trick, but isn't quite perfect. A better option is to use Web.config File

Transformations.

http://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.inheritinchildapplications%28v=VS.90%29.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.inheritinchildapplications%28v=VS.90%29.aspxhttp://stackoverflow.com/questions/782252/avoid-web-config-inheritance-in-child-web-application-using-inheritinchildapplichttp://stackoverflow.com/questions/782252/avoid-web-config-inheritance-in-child-web-application-using-inheritinchildapplichttp://stackoverflow.com/questions/782252/avoid-web-config-inheritance-in-child-web-application-using-inheritinchildapplichttp://stackoverflow.com/questions/782252/avoid-web-config-inheritance-in-child-web-application-using-inheritinchildapplichttp://www.kowitz.net/archive/2007/05/16/stopping-asp-net-web-config-inheritancehttp://www.kowitz.net/archive/2007/05/16/stopping-asp-net-web-config-inheritancehttp://www.kowitz.net/archive/2007/05/16/stopping-asp-net-web-config-inheritancehttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://runtingsproper.blogspot.com/2010/04/solved-breaking-parent-webconfig.htmlhttp://runtingsproper.blogspot.com/2010/04/solved-breaking-parent-webconfig.htmlhttp://runtingsproper.blogspot.com/2010/04/solved-iis7-validateintegratedmodeconfi.htmlhttp://runtingsproper.blogspot.com/2010/04/solved-iis7-validateintegratedmodeconfi.htmlhttp://runtingsproper.blogspot.com/2010/04/solved-iis7-validateintegratedmodeconfi.htmlhttp://runtingsproper.blogspot.com/2010/04/solved-iis7-validateintegratedmodeconfi.htmlhttp://runtingsproper.blogspot.com/2010/04/solved-iis7-validateintegratedmodeconfi.htmlhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://runtingsproper.blogspot.com/2010/04/solved-iis7-validateintegratedmodeconfi.htmlhttp://runtingsproper.blogspot.com/2010/04/solved-iis7-validateintegratedmodeconfi.htmlhttp://runtingsproper.blogspot.com/2010/04/solved-breaking-parent-webconfig.htmlhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://www.kowitz.net/archive/2007/05/16/stopping-asp-net-web-config-inheritancehttp://stackoverflow.com/questions/782252/avoid-web-config-inheritance-in-child-web-application-using-inheritinchildapplichttp://stackoverflow.com/questions/782252/avoid-web-config-inheritance-in-child-web-application-using-inheritinchildapplichttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.inheritinchildapplications%28v=VS.90%29.aspx

7/27/2019 10 Things ASP

8/17

Tip 9: Use Web.config Transforms to handle

environmental differences

I don't hear as much about Web.config Transforms as I'd expect. Maybe they just work and everyone

just quietly uses them and doesn't talk about it. But from the questions I see coming up over and over

again, I'm not sure that's the case.

I love Web.config Transforms. At my first ASP.NET MVP summit, I was part of a feedback group

discussing frustrations with deploying ASP.NET applications. Two themes that came up over and over

were difficulties with packaging and managing configuration. That team later produced Web

Deployment Packages (a nice format that packages files and settings for a site in a way that can be

inspected and modified during installation) and Web.config Transforms.

All the new ASP.NET projects have Web.config transforms already set up - if you expand the

Web.config node, you'll see that it's configured to create different settings for Debug and Release

mode.

It's really easy to use - your main Web.config has the base settings for your site, and

whenever you build, the transforms for the appropriate build configuration (e.g. Debug or

Release) are automatically applied. If you had a Test database that you wanted to use by default,

but wanted your Release builds to run against the Production database, you could set it up so that

your base Web.config connection string points to the Test Database connection string, like this:

?

1

2

3

4

Then your Web.Release.config overwrites that to point at the Production database, like this:

?

1

http://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://www.flickr.com/photos/36836555@N00/6716902571/http://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspxhttp://weblogs.asp.net/jgalloway/archive/2012/01/17/10-things-asp-net-developers-should-know-about-web-config-inheritance-and-overrides.aspx

7/27/2019 10 Things ASP

9/17

2

3

4

5

6

7

8

The syntax is pretty straightforward, but you don't need to worry about that because the comments in

the Web.Release.config file already show how to do that.

To be clear: unlike the other examples, this is something that happens at build time, not

runtime.

I recently ran into an issue where I wanted to deploy something to AppHarbor and wanted to switch

between a local SQL Compact database and the hosted database server, and Web.config Transforms

worked just great there.

There's a lot more to talk about with Web.config Transforms that's beyond the scope here, such as:

You can create as many build configurations as you want, with different transforms foreach configuration. This makes it simple to switch between different settings in your

development environment - say, switching between several development databases or other

application settings.

You can use the configuration transformation system with any XML file using

theSlowCheetah Visual Studio extension. Scott Hanselman's written a post with more

information on that here:SlowCheetah - Web.config Transformation Syntax now

generalized for any XML configuration file

Sayed (the Microsoft developer who's worked on both Web.config Transforms and theSlowCheetah extension) has also built aPackage Once Publish AnywhereNuGet package

which allows you to defer running the transforms until later, using a PowerShell

command. That means you can build one Web Deployment Package with all the transforms

included, and run them when you're going to deploy to a specific environment.

There's some good information on MSDN about Web.config Transforms:

Web.config File Transformationsection in the Web Application Project DeploymentOverview

Web.config Transformation Syntax for Web Application Project Deployment

Scott Hanselman:Web Deployment Made Awesome: If You're Using XCopy, You'reDoing It Wrong

Tip 10: Managing Application Restarts on Configuration

Changes

There are a lot of moving parts in figuring out the configuration for a website, as illustrated above. For

that reason, ASP.NET computes the effective settings for the site and caches them. It only recomputes

them (and restarts the application) when a file in the sites configuration hierarchy is modified. You can

control that on a section by section level using therestartOnExternalChanges property.

One place where configuration changes don't automatically get recomputed is for external config files

set using configSource (as shown in Tip 8). You can control that bysetting

restartOExternalChanges="true" for that section. There's anexample on MSDNthat shows this

in more detail by creating an external configuration file which is loaded via the configuration API (not

http://visualstudiogallery.msdn.microsoft.com/69023d00-a4f9-4a34-a6cd-7e854ba318b5http://visualstudiogallery.msdn.microsoft.com/69023d00-a4f9-4a34-a6cd-7e854ba318b5http://visualstudiogallery.msdn.microsoft.com/69023d00-a4f9-4a34-a6cd-7e854ba318b5http://www.hanselman.com/blog/SlowCheetahWebconfigTransformationSyntaxNowGeneralizedForAnyXMLConfigurationFile.aspxhttp://www.hanselman.com/blog/SlowCheetahWebconfigTransformationSyntaxNowGeneralizedForAnyXMLConfigurationFile.aspxhttp://www.hanselman.com/blog/SlowCheetahWebconfigTransformationSyntaxNowGeneralizedForAnyXMLConfigurationFile.aspxhttp://www.hanselman.com/blog/SlowCheetahWebconfigTransformationSyntaxNowGeneralizedForAnyXMLConfigurationFile.aspxhttp://sedodream.com/2011/12/24/PackageOncePublishAnywhere.aspxhttp://sedodream.com/2011/12/24/PackageOncePublishAnywhere.aspxhttp://msdn.microsoft.com/en-us/library/http://msdn.microsoft.com/en-us/library/http://msdn.microsoft.com/en-us/library/dd465326.aspxhttp://msdn.microsoft.com/en-us/library/dd465326.aspxhttp://www.hanselman.com/blog/WebDeploymentMadeAwesomeIfYoureUsingXCopyYoureDoingItWrong.aspxhttp://www.hanselman.com/blog/WebDeploymentMadeAwesomeIfYoureUsingXCopyYoureDoingItWrong.aspxhttp://www.hanselman.com/blog/WebDeploymentMadeAwesomeIfYoureUsingXCopyYoureDoingItWrong.aspxhttp://www.hanselman.com/blog/WebDeploymentMadeAwesomeIfYoureUsingXCopyYoureDoingItWrong.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.restartonexternalchanges.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.restartonexternalchanges.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.restartonexternalchanges.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/ms228057.aspxhttp://msdn.microsoft.com/en-us/library/ms228057.aspxhttp://msdn.microsoft.com/en-us/library/ms228057.aspxhttp://msdn.microsoft.com/en-us/library/ms228057.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.configsource.aspxhttp://msdn.microsoft.com/en-us/library/system.configuration.sectioninformation.restartonexternalchanges.aspxhttp://www.hanselman.com/blog/WebDeploymentMadeAwesomeIfYoureUsingXCopyYoureDoingItWrong.aspxhttp://www.hanselman.com/blog/WebDeploymentMadeAwesomeIfYoureUsingXCopyYoureDoingItWrong.aspxhttp://msdn.microsoft.com/en-us/library/dd465326.aspxhttp://msdn.microsoft.com/en-us/library/http://sedodream.com/2011/12/24/PackageOncePublishAnywhere.aspxhttp://www.hanselman.com/blog/SlowCheetahWebconfigTransformationSyntaxNowGeneralizedForAnyXMLConfigurationFile.aspxhttp://www.hanselman.com/blog/SlowCheetahWebconfigTransformationSyntaxNowGeneralizedForAnyXMLConfigurationFile.aspxhttp://visualstudiogallery.msdn.microsoft.com/69023d00-a4f9-4a34-a6cd-7e854ba318b5

7/27/2019 10 Things ASP

10/17

referenced via configSource), then toggling the restartOnExternalChanges property and showing the

differences in operation.

Summary

The ASP.NET Configuration system does quite a bit - I didn't even mention big topics like using the

API for reading and writing values to both local and external config files or creating custom

configuration sections. This post focuses on one aspect: getting things done by understanding and

leveraging inheritance and overrides. Hopefully this gives you both some new tools for effectively

handling configuration and some background that helps in troubleshooting when configuration is

working as you'd like.

Are there any essential tips that I missed?

ASP.NET - Configuration

Advertisements

The behavior of an ASP.Net application is affected by different settings in the configuration files:

machine.config

web.config

The machine.config file contains default and the machine-specific value for all supported settings. Themachine settings are controlled by the system administrator and applications are generally not given accessto this file.

An application however, can override the default values by creating web.config files in its roots folder. Theweb.config file is a subset of the machine.config file.

If the application contains child directories, it can define a web.config file for each folder. Scope of eachconfiguration file is determined in a hierarchical top-down manner.

Any web.config file can locally extend, restrict or override any settings defined on the upper level.

Visual Studio generates a default web.config file for each project. An application can run without aweb.config file, however, you cannot debug an application without a web.config file.

The following figure shows the Solution Explorer for the sample example used in the web services tutorial:

http://www.addthis.com/bookmark.phphttp://www.tutorialspoint.com/asp.net/asp.net_deployment.htmhttp://www.tutorialspoint.com/asp.net/asp.net_multi_threading.htmhttp://www.addthis.com/bookmark.phphttp://www.tutorialspoint.com/asp.net/asp.net_deployment.htmhttp://www.tutorialspoint.com/asp.net/asp.net_multi_threading.htmhttp://www.addthis.com/bookmark.phphttp://www.tutorialspoint.com/asp.net/asp.net_deployment.htmhttp://www.tutorialspoint.com/asp.net/asp.net_multi_threading.htm

7/27/2019 10 Things ASP

11/17

In this application there are two web.config files for two projects i.e., the web service and the web sitecalling the web service.

The web.config file has the configuration element as the root node. Information inside this element is

grouped into two main areas: the configuration section-handler declaration area, and the configuration

section settings area.

The following code snippet shows the basic syntax of a configuration file:

The Configuration Section Handler declarations:

7/27/2019 10 Things ASP

12/17

The configuration section handlers are contained within the tags. Each configurationhandler specifies name of a configuration section, contained within the file, which provides someconfiguration data. It has the following basic syntax:

It has the following elements:

Clear - it removes all references to inherited sections and section groups.

Remove - it removes a reference to an inherited section and section group.

Section - it defines an association between a configuration section handler and a configurationelement.

Section group - it defines an association between a configuration section handler and aconfiguration section.

The Application Settings:

The application settings allow storing application-wide name-value pairs for read-only access. For example,you can define a custom application setting as:

For example, you can store the name of a book and its ISBN number:

The Connection Strings:

The connection strings shows which database connection strings are available to the website. For example:

7/27/2019 10 Things ASP

13/17

connectionString="Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\ \databinding\App_Data\books.mdb"

providerName="System.Data.OleDb" />

The System.Web Element:

The system.web element specifies the root element for the ASP.NET configuration section and containsconfiguration elements that configure ASP.NET Web applications and control how the applications behave.

It holds most of the configuration elements needed to be adjusted in common applications. The basic syntaxfor the element:

The following table provides brief description of some of common sub elements of thesystem.web element:

anonymousIdentification:

This is required to identify users who are not authenticated when authorization is required.

7/27/2019 10 Things ASP

14/17

authentication:

It configures the authentication support. Basic syntax:

...

authorization

It configures the authorization support.Basic syntax:

caching:

Configures the cache settings.Basic syntax:

............

customErrors:

Defines custom error messages. Basic syntax:

deployment:

Defines configuration settings used for deployment. Basic syntax:

hostingEnvironment:

Defines configuration settings for hosting environment.Basic syntax:

7/27/2019 10 Things ASP

15/17

/>

identity:

Configures the identity of the application. Basic syntax:

machineKey:

Configures keys to use for encryption and decryption of Forms authentication cookie data.

It also allows configuring a validation key that performs message authentication checks on view-state dataand Forms authentication tickets. Basic syntax:

membership:

This configures parameters of managing and authenticating user accounts.Basic syntax:

...

pages:

Provides page-specific configurations. Basic syntax:

7/27/2019 10 Things ASP

16/17

pageParserFilterType="string"smartNavigation="[True|False]"styleSheetTheme="string"theme="string"userControlBaseType="typename"validateRequest="[True|False]"viewStateEncryptionMode="[Always|Auto|Never]"

>............

profile:

Configures user profile parameters. Basic syntax:

......

roleManager:

Configures settings for user roles. Basic syntax:

enabled="true|false"maxCachedResults="maximum number of role names cached"...

securityPolicy:

Configures the security policy. Basic syntax:

urlMappings:

7/27/2019 10 Things ASP

17/17

Defines the mappings for hiding the actual URL and providing a more user friendly URL. Basic syntax:

webControls:

It provides the name of shared location for client scipts. Basic syntax:

webServices:

This configures the web services.