Playing with Sitecore Include files

Sitecores include files which are stored in the /App_Config/Include/ folder are a nifty way of alter configurations without editing the web.config file. However sometimes you find yourself questioning how you would write the configurations in the include file.

Unfortunately there’s a lack of good documentations so most of the time you will have to go with the trial and error approach. The only useful documentation I’ve found is this and some forum posts.
As your help you have the tool for showing the merged web.config file at your side. Which can be found at /sitecore/admin/showconfig.aspx

I’ve been poking around in the Sitecore.Xml.Patch.XmlPatchUtils class and found out that the following attributes are available when writing your configuration file.

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

Most often you don’t need to write that complicated configurations like when you want to add a processor into a pipeline before or after a specific processor. The most basic is just adding at the last position like this example where we add a command at the last position.

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
    <sitecore>
        <commands>
            <command name="test:mycommand" type="MyClasses.MyCommand, MyAssembly"/>            
        </commands>
    </sitecore>
</configuration>

Sometimes you need do add it at a specific position, like before or after a processor. The following example will add the “MyClasses.DoMyStuffProcessor, MyAssembly” processor after the “Sitecore.Pipelines.HttpRequest.ItemResolver, Sitecore.Kernel” processor in the httpRequestBegin pipeline.

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
    <sitecore>
        <pipelines>
            <httpRequestBegin>
                <processor patch:after="*[@type='Sitecore.Pipelines.HttpRequest.ItemResolver, Sitecore.Kernel']" type="MyClasses.DoMyStuffProcessor, MyAssembly" method="SomeProcess"/>
            </httpRequestBegin>
        </pipelines>
    </sitecore>
</configuration>

Often you want to change the value of an element like a Sitecore setting, like changing the MailServer value. This is done like this.

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
    <sitecore>
        <settings>
            <setting name="MailServer">
                <patch:attribute name="value">localhost</patch:attribute>
            </setting>
        </settings>
    </sitecore>
</configuration>

Or maybe remove one which is done like this

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
    <sitecore>
        <settings>
            <setting name="SomeSetting">
                <patch:delete/>
            </setting>
        </settings>
    </sitecore>
</configuration>

However sometimes you want to alter some more complex structure like when changing the interval of the task agent for the master database. Since this configuration looks allot like the one for the core database, where the only difference is the value of the sub element like you can see below.

<agent type="Sitecore.Tasks.DatabaseAgent" method="Run" interval="00:10:00">
	<param desc="database">core</param>
	<param desc="schedule root">/sitecore/system/tasks/schedules</param>
	<LogActivity>true</LogActivity>
</agent>
<!-- Agent to process schedules embedded as items in a database -->
<agent type="Sitecore.Tasks.DatabaseAgent" method="Run" interval="00:10:00">
	<param desc="database">master</param>
	<param desc="schedule root">/sitecore/system/tasks/schedules</param>
	<LogActivity>true</LogActivity>
</agent>

Here we only want to change the agent for the master database. What I did was using the patch:instead attribute and replaced the entire configuration like this.

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
    <sitecore>
        <scheduling>
            <agent patch:instead="*[@type='Sitecore.Tasks.DatabaseAgent' and contains(.,'master')]" method="Run" type="Sitecore.Tasks.DatabaseAgent" interval="00:30:00">
                <param desc="database">master</param>
                <param desc="schedule root">/sitecore/system/tasks/schedules</param>
                <LogActivity>true</LogActivity>
            </agent>
        </scheduling>
    </sitecore>
</configuration>

As you can see I used a little xpath where i look for an agent of the type ‘Sitecore.Tasks.DatabaseAgent’ and which contains the string ‘master’ somewhere inside.

You can probably alter any Sitecore configuration using include files, but some alterations will probably have you use more complex xpath queries.

I hope this little playtime with Sitecores include file was helpful.