The web.config that comes with Sitecore is quite impressive, its arround 3.000 lines of configuration. One thing is to be able to know what the different sections does, another thing is to keep track of what changes you have made to the web.config file. Sitecore has implemented a nice feature for this purpuse, its call config include files. It gives you the ability to patch the web.config file by adding custom config files, that overwrites the original settings. This means that you will contain the original web.config file, and your changes will be extracted to seperate files, that are easy to maintain.

The restrictions the feature is that you are only able to patch settings found in the <sitecore> element of the web.config.

How it works

Basicly it works by addign a .config file to the /App_config/Include folder, and Sitecore will merge the file at runtime. A common and simple example is to patch the default datafolder location. this can be done by adding a .config file called datafolder.config(name can be anything), containing the following lines:

<configuration xmlns:patch="">
    <sc.variable name="dataFolder">
      <patch:attribute name="value">c:\sitecore\data</patch:attribute>

The above config file will patch the attribute called value of the sc:variable with the name dataFolder.

The patching mechanisme supports 5 tyes:

  • patch:before
  • patch:after
  • patch:instead
  • patch:delete
  • patch:attribute

The patching mechanime is for altering existing configurations in the web.config the before and after are usefull when adding code to pipelines, so they are placed in the correct order.

An example would be to add a processor the the renderField pipeline, this would be done like this, the processor is added before the AddBeforeAnAfterValues processor:

     <processor type="MikkelHm.CustomCode.RenderFieldCustom,MikkelHm.CustomCode" patch:before="processor[@type='Sitecore.Pipelines.RenderField.AddBeforeAndAfterValues, Sitecore.Kernel']" />

If you are to simply add a configuration line to the config file, you dont have to use the patchin mechanisme, you just write the line of configuration in the include file like this:

     <fieldType name="Custom Field" type="MikkelHm.CustomCode.CustomField,MikkelHm.CustomCode" />

Other blogs with references to the Sitecore include file