Sitecore Blog: @sitecorejohn blog

All About Web.config Include Files with the Sitecore ASP.NET CMS

By John West, May 30, 2011 | Rating:  | Comments (18)

The Patch LinkManager in include and What patch: attributes are available in included .config files threads on the Sitecore Developer Network (SDN) forums prompted me to write this blog post that contains or links to everything I could find or think of regarding web.config include files with the Sitecore ASP.NET CMS.

When processing the web.config file, Sitecore includes configuration files specified by <sc:include> elements as well as those in the /App_Config/Include subdirectory. This allows administrators to define module-specific, feature-specific, solution-specific, instance-specific and other specific configuration in files separate from the main web.config file, which can simplify configuration, release management, and other aspects of the system.

The /App_Config/Include subdirectory contains examples that you can investigate with the .example extension. To enable the configuration in one of these example files, rename it with the .config extension.

The structure of web.config include file mimics the structure of the web.config file including the /configuration/sitecore element. Unfortunately, you can only patch elements within the /configuration/sitecore element.

Include config files can lead to some confusion when a developer only evaluates the main web.config file, ignoring web.config include files that define additional configuration. You can use the /sitecore/admin/showconfig.aspx page to evaluate the results of processing web.config include files, but you may have to grant permissions to the /sitecore/admin subdirectory in IIS. In production environments, you should require authentication to access the /sitecore/admin subdirectory, and/or restrict the IP range with access. The Detailed Config Report Sitecore Shared Source module enhances this functionality by indicating which include file overrides.

Jens Mikkelson recently suggested on twitter that one might make the entire /configuration/sitecore section an include file, to separate Sitecore default configuration from ASP.NET default configuration.

An element within the /configuration/sitecore element in a web.config include file can use an element in any namespace (such as x: or patch:) to indicate its location relative to existing elements in the web.config file or files processed previously, or to specify an existing element replace, update or delete. For example, to add a /configuration/sitecore/sites/site element before the default managed site named website:

<configuration xmlns:patch="">
      <site patch:before=”*[@name='website']” name=”mysite” ... />

You can use the following elements in the x: for the attribute:

  • -patch:before: Insert the element before the specified element.
  • -patch:after: Insert the element after the specified element.
  • -patch:instead: Replace the specified element.
  • -patch:delete: Remove the specified element.
  • -patch:attribute: Define or replace the specified attribute.

In addition to the How to auto-include configuration files? entry on SDN, the following blogs contain more detailed information on the topic of web.config include files:

For information about how Sitecore instantiates objects defined in web.config files, see my blog post The Sitecore ASP.NET CMS Configuration Factory.

Please comment on this blog post to provide additional additional information about web.config include files or to provide URLs of additional resources on this topic.

More posts All About the Sitecore ASP.NET CMS

Tags: Architecture, Infrastructure


  • Hey, John - can you give a quick example of using patch:delete?

    - Kevin Williams
    August 24, 2011 at 9:19 AM

  • Was it confirmed that "patch:delete" works?

    - Dwight Sands
    December 30, 2011 at 10:43 AM

  • @Kevin and @Dwight: Sorry for the late response. Did you already resolve this? Do you need to remove an element, or an attribute? I think I can remove for example the /sitecore/hooks/hook[@type="Sitecore.Diagnostics.MemoryMonitorHook, Sitecore.Kernel"]/AdjustLoadFactor element with the following, but I am not sure about attributes yet: <configuration xmlns:patch=""> <sitecore> <hooks> <hook type="Sitecore.Diagnostics.MemoryMonitorHook, Sitecore.Kernel"> <AdjustLoadFactor> <patch:delete /> </AdjustLoadFactor> </hook> </hooks> </sitecore> </configuration>

    - John West
    April 26, 2012 at 1:24 PM

  • Thank you for responding, John. I don't remember what my exact need was now, but I'm sure we just deleted it from the web.config directly since I couldn't figure out how to remove it using patch:delete. I will definitely give this a try next time I need to do something like this, though!

    - Kevin Williams
    April 28, 2012 at 7:03 PM

  • Sitecore processes Web.config include files in alphabetical order (technically, the order returned by the Directory.GetFiles() method). If you need to use a Web.config include file to override something in another Web.config include file, the name of the overriding file should sort after the name of the overridden file.

    - John West
    August 15, 2012 at 7:29 AM

  • is it possible to have solution configuration specific configs? In the case where development and production settings are different? or should I be using the VS2010 transfoms to achieve this?

    - ben ben
    August 16, 2012 at 2:12 AM

  • Hi john, i want to show a popup when clicking on linkbutton like top of your blog (+ share this Page). plz send me the source code for this. thanks in advance.

    - Sivakrishna bhatraju
    October 15, 2012 at 7:33 PM

  • Hi Sivakrishna, Sorry, I am not much good with markup (someone else built the site). I would try not to look at this question as specific to Sitecore, but a general HTML/web development question (maybe even view source on this page and try to see how they did it). If there is some specific Sitecore aspect to it, such as that link must appear in a rich text editor, then I would consider it a Sitecore question. Regards, -John

    - John West
    October 16, 2012 at 7:19 AM


    - John West
    January 23, 2013 at 1:07 PM

  • Elements not appearing in expected order when using <sc:include>:

    - John West
    August 27, 2013 at 7:11 AM


    - John West
    December 30, 2013 at 11:25 AM


    - John West
    February 20, 2015 at 1:03 PM


    - John West
    April 03, 2015 at 1:21 PM

  • One should add that the custom HtmlCacheClearer needs to have a list of all sites that need to be cleared. I expected the default to be "clear all caches on all sites", but found it wasn't. As it's more trouble to update documantation for adding a site than changing the HtmlCacheClearer, I changed the HtmlCacheClearer - just us SiteManager.GetSites().ToArray() to get the data the original one gets from the config and adapt the code, about 5 minutes of work. In "Professional Sitecore Development" I found no clue that caching needs extra attention in multi-site-instances, I hope you can add a note in the new book.

    - Jan Bühler
    June 09, 2015 at 5:33 PM

  • @Jan: Sorry, I am not holding my breath for a new book! See and maybe

    - John West
    June 09, 2015 at 6:38 PM

  • Sorry, I was too frustrated with thedefault behaviour that I commented the wrong post. Should have been

    - Jan Bühler
    June 10, 2015 at 4:07 PM


    - Brad Christie
    August 18, 2015 at 3:06 PM


    - John West
    November 09, 2015 at 4:28 PM

*{0} must be filled in.
*{0} must be filled in.
*{0} must be filled in.