LibrarySites.Banner

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

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="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <sites>
      <site patch:before=”*[@name='website']” name=”mysite” ... />
    </sites>
  </sitecore>
</configuration>

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