With the recent announcement of Sitecore 9 came a surge of new features and improvements. One of the features I’m most excited about is the new rules-based configuration for configuration files. If you haven’t already, make sure to read this excellent blog post by Kamruz Jaman, which details all of the new, shiny things we can do, along with some great examples.

Related: Three great reasons to use custom Sitecore icons.

Now that we have all these new great features, how does this change how we approach config files in Sitecore? How should we be structuring things? Below I’ll detail an approach that my team has landed on. It is not meant to be the end-all and be-all solution, just the standard I feel will work best for our needs.

Commonly Used Config Files


We normally do not deploy the web.config file as part of our builds, and even with these new changes, I still do not think deploying the web.config file is necessary. The risk is too high for the small amount of reward it brings. Instead, the web.config file can serve essentially as a record for what changes have been made in which environment. These will usually be AppSettings and server role configurations.

The web.config file can serve as a record for what changes have been made in which environment.

Yes, instead of relying on comments, we can use config transforms, but I opt for comments in this case for readability. Comments do get stale but the contents of this file will not change very often, if at all. I can see this potentially getting a little unwieldy for extremely large projects, but it has worked so far for us.


Sitecore is eating its own dog food and using server roles in their own config files. All you should need to do now is set the server role in the web.config. Because of this, SwitchMasterToWeb.config can go away entirely.


You may call it something different, but this file would house all of the settings in <sitecore><settings>. Previously, the values in this file were modified via config transforms, but since you can now define custom AppSettings keys, it will eliminate those pesky transformations.


Again, you might call it something different, but this file would contain the configuration for the various <site> nodes. Just like our settings config file, this would routinely get modified by config transforms. These transforms can again be eliminated to leave us with one file like the one below.


This config file, introduced in Sitecore 9, controls the order in which configuration files load.

This config file, introduced in Sitecore 9, controls the order in which configuration files load. Everyone might not have a need to modify this file, but since we regularly use our open source development accelerator, Elision, we need to manage the contents of this file between layers. This was especially crucial for us since we have each feature split out into its own NuGet package. Our plan is to have the Layers.config file be a part of each client solution, with the foundation layer and each feature patching the file in the solution as necessary via PowerShell. Stay tuned for a blog post going into further detail on how we accomplish this.


Site search is a requested feature on virtually every site. We normally set up two separate indexes, one for the CM server and one for the CD server. In the past. we put the configuration for these two indexes in a file called Index.Site.config and updated SwitchMasterToWeb.config to exclude the index for use on our CM. With the deprecation of SwitchMasterToWeb.config, this made me take another look for how we set up these indexes.

We have now split our indexes into two separate files, one for the master database and one for the web. In each file we can utilize server roles and search:require syntax, which accounts for the loss of SwitchMasterToWeb.config and even allows us to deploy our master index file to our CD servers!

Master Index:

Web Index:

Folder Structure

Given these changes, what does the familiar App_Config/Include look like? Here’s the structure I envision us working with now:

  • App_Config
    • Include
      • Foundation
        • Foundation
          • Foundation.*.config
      • Feature
        • Feature.*
          • Feature.*.config
      • Project
        • [Project A]
          • Project A config files
        • [Project B]
          • Project B config files

You may have noticed the environment folder is missing. Why? With the new server roles, and ability to define environment attributes, I simply do not think this folder is necessary 9/10 times. The purpose of this folder is for environment-specific config settings, like for a UAT or QA.

With the new server roles, and ability to define environment attributes, the environment folder isn’t necessary 9/10 times.

To me, it seems like environment-specific config changes should be made in the configuration files themselves. For example, if you need to change an API key for your UAT environment, it makes more sense to utilize an environment attribute (env:require=”UAT”) instead. That way, you’re editing just one file in a consistent place across all environments, rather than wondering if there is another config loading later on which is modifying your expected value.

Questions? Let me know in the comment section below.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>