Sitecore Experience Manager

Configuration

Abstract

Describes how to configure Sitecore Host.

You use the following types of file-based configuration to configure Sitecore Host:

  • Host configuration - configuration of Sitecore Host itself. This is mainly for low-level settings.

  • Plugin configuration - optional configuration for plugins.

  • Application configuration - main configuration of the application. Here you can also override plugin configuration values.

You use configuration patching to override settings.

Host configuration

When you start a Sitecore Host application, the first thing it does is to look for a sitecorehost.xml file. This file contains low-level settings such as logging setup or service registration, because these settings are processed before the application is fully loaded.

Host configuration consists of the following steps:

  • Provide configuration for each environment.

    You can provide a environment specific version of the host configuration if needed:

    SitecoreHostApplication (Root)
    ├── sitecoreruntime
    │   └── <env>
    │       └── sitecorehost.xml
    ├── sitecorehost.xml
    └── sitecorehost.<env>.xml

    If there is an environment-specific configuration file (for example, sitecorehost.production.xml), this file is used to patch the configuration that has already been loaded.

    If you configure an environment under the sitecoreruntime folder, it can contain a sitecorecorehost.xml file. If it does, this file is used to patch the configuration that has already been loaded.

  • Access host configuration in code.

    Host configuration loads the data from the sitecorehost.xml file into the ISitecoreHostingEnvironment object. You can access any value through the Configuration property.

Application and plugin configuration

Plugins can provide configuration by adding xml files to a config folder. Applications can also provide a config folder, where they can override configuration values from a plugin.

If you configure an environment under the sitecoreruntime folder, this environment can also provide a config folder to override configuration values.

When Sitecore loads configurations from a plugin config folder, it loads all *.xml files in name order. It then checks the config folder for a folder which matches the name of the current environment. If one is found, the *.xml files in this folder are also loaded in name order. This is then repeated for the host config folder, if this folder exists. Finally, the sitecoreruntime folder is checked. If a config folder exists here, the process is repeated:

SitecoreHostApplication (Root)
├── config
│   ├── config1.xml
│   ├── config2.xml
│   └── <env>
│       └── config.xml
├── sitecore
│   ├── PluginA
│   │   └── config
│   │       └── config.xml
│   └── PluginB
│       └── config
│           └── config.xml
└── sitecoreruntime
    └── <env>
        └── config
            ├── config1.xml
            └── config2.xml

Accessing application and plugin configuration in code

Application and plugin configuration is loaded from disk, patched and then loaded into the ISitecoreEnvironment object, which you can inject into any class.

This topic has further information about:

You can set special environment variables to override file-based configuration. Sitecore environment variables are also added to both the IHostingEnvironment.Configuration and the ISitecoreConfiguration objects, updating any values set previously. When you use environment variables, you can control the configuration of your application without making any changes to the actual assets.

An environment variable must begin with SITECORE_ to be loaded. The prefix is removed when the value is applied to configuration. If the configuration path has multiple paths,  separate each part with a double underscore or a colon, for example:

Environment variable

Read from configuration as

SITECORE_Environment

Environment

SITECORE_Commands__DefaultCommand__Default

Commands:DefaultCommand:Default

SITECORE_MyCustom:Key

MyCustom:Key

Command-line configuration

When you start an application, you can specify arguments and options for specific commands. You can also provide configuration arguments to override configuration by passing values after --.

Specify each configuration value as --<key><value> where the <key> is a colon-separated configuration path, such as  Commands:DefaultCommand:Default.

Values you pass this way will always be the final configuration value because they are the last values added to the collection. Command-line configuration is added to both the IHostingEnvironment.Configuration and the ISitecoreConfiguration objects.

Configuration load order

The following diagram shows the order in which Sitecore evaluates a configuration in the different layers of the application:

loadorder.png

Configuration files have support for patching values in the configuration of a Sitecore Host application or plugin. The patching mechanism within Sitecore Host is designed to mimic the patching logic you use in Sitecore in general, offering the same functionality.

All patching methods from normal Sitecore are fully supported including:

  • patch:before – inserts the element before the specified element.

  • patch:after – inserts the element after the specified element.

  • patch:attribute – defines or replaces the specified attribute of the element. You can achieve the same effect using the setnamespace.

  • patch:delete – removes the specified element.

  • patch:instead – replaces the specified element.

The following is an example of configuration patching:

<Settings>
  <Sitecore xmlns:patch="http://www.sitecore.net/xmlconfig/">
     <sites>
      <site patch:before="*[@name='website']" name="mysite" />
      <site patch:after="*[@name='website']" name="mysite2" />
      <site patch:delete="*[@name='website']" name="mysite2" />
      <site patch:instead="*[@name='website']" name="mysite2" />
      <patch:attribute name="value">
       MyNewValue
      </patch:attribute>
    </sites>
  </Sitecore>
</Settings>

All configuration files are merged into a single configuration source and accessible via the ISitecoreHostingEnvironment.Configuration or ISitecoreConfiguration objects. The following example shows the result of merging two files:

File1.xml


<Settings>
  <Sitecore>
    <Diagnostics>
      <Debug>true</Debug>
      <MyValue>First</MyValue>
    </Diagnostics>
  </Sitecore>
</Settings>


File2.xml


<Settings>
  <Sitecore>
    <Diagnostics>
      <Root>Alt</Root>
      <MyValue>Second</MyValue>
    </Diagnostics>
  </Sitecore>
</Settings>


Merged configuration


<Settings>
  <Sitecore>
    <Diagnostics>
      <Debug>true</Debug>
      <Root>Alt</Root>
      <MyValue>Second</MyValue>
    </Diagnostics>
  </Sitecore>
</Settings>

Use the host configuration (sitecorehost files) to add or change the services available by default for a host application.

Service configuration properties

When you add an entry for a service, you can add the following properties:

Name

Description

Required

Example value

Default value

Type

The namespace of the type to be registered.

True

MyClass, My.Namespace

No default.

As

The type you want to register the service as. This is the type that is used when you access the object from the container.

False

IInterface, My.Namespace

If you do not provide a value , As will have the same value as Type.

Lifetime

The lifetime of the service. Must be a valid ServiceLifetime enum value.

False

Transient

Singleton

Options

Optional values that you can pass to the class. See the BindOptions property for further details.

False

See example below.

Null

BindOptions

Controls how the Options are passed to the created service. Can be Constructor or Property:

  • Constructor - the options are passed to the constructor as an instance of IConfigurationSection. The type must have a public constructor which receives IConfigurationSection.

  • Property - the options are bound directly to the instance properties after construction.

False

Property

Constructor

The following is an example of a service configuration:

<MyType>
  <Type>My.Custom.Class, MyCustom</Type>
  <As>My.Custom.IInterface, MyCustom</As>
  <Lifetime>Transient</Lifetime>
  <Options>
    <SomeProperty>Value</SomeProperty>
  </Options>
  <BindOptions>Property</BindOptions>
</MyType>

Add services

You add services by using the configuration path Host:Services:Add. Add each service under a unique path. This enables patching and updating the service in configuration. The following is an example of adding services using the configuration path:

<Sitecore>
    <Host>
        <Services>
            <Add>
                <MyType>
                    <Type>ConsoleHost.MyType, HostConfiguration</Type>
                    <As>ConsoleHost.IMyType, HostConfiguration</As>
                    <Lifetime>Transient</Lifetime>
                </MyType>
            </Add>            
        </Services>
    </Host>
</Sitecore> 

Replace services

You replace services by using the configuration path Host:Services:Replace, as the following example shows:

<Sitecore>
    <Host>
        <Services>
            <Replace>
                <DefaultAssemblyResolverFactory>
                    <Type>ConsoleHost.MyAssemblyResolverFactory, HostConfiguration</Type>
                    <As>Sitecore.Framework.Runtime.Assembly.IAssemblyResolverFactory, Sitecore.Framework.Runtime.Abstractions</As>
                </DefaultAssemblyResolverFactory>
            </Replace>          
        </Services>
    </Host>
</Sitecore> 

When you look at a Sitecore Host application, you can find that there is configuration in many different locations, due to it being provided by different plugins. For example:

SitecoreHostApplication (Root)
├── sitecore
│   ├── PluginA
│   │   └── config
│   │       └── config.xml
│   └── PluginB
│       └── config
│           └── config.xml
└── sitecoreruntime
    └── <env>
        └── sitecore
            └── RuntimePluginA
               └── config
                   └── config.xml

Never edit these configuration files directly and think of them as being read-only. Create your own configuration file in the config folder in the root of the application instead. This allows you to provide overrides for any values that you need, and you can track your configuration in your own files.

Example

In this example, you have a plugin (SQL.Plugin) inside the main application:

SitecoreHostApplication (Root)
├── sitecore
│   ├── SQL.Plugin
│   │   └── config
│   │       └── config.xml

By default, the ConnectionString element is blank:

<Sitecore>
    <SQL.Plugin>
        <ConnectionString></ConnectionString>
        <Retries>10</Retries>
        <BackOffPeriod>1</BackOffPeriod>
        <BatchSize>500</BatchSize>
    </SQL.Plugin>
</Sitecore>

You might want to provide your own connection string or use different connections for development and production. To do this:

  1. Create a config folder in the root of the application (if one does not already exist).

  2. Create environment specific subfolders for development and production:

    SitecoreHostApplication (Root)
       ├── config
       │   └── production
       │         └── production-config.xml
       │   └── development
       │         └── development-config.xml
       ├── sitecore
       │   ├── SQL.Plugin
       │   │   └── config
       │   │       └── config.xml
  3. In each of these subfolders, create a new XML config file to contain the elements you need to override and update. For example, in the production-config.xml folder,  you can provide the connection string and set a larger batch size:

    <Sitecore>
        <SQL.Plugin>
            <ConnectionString><!-- ProductionDBConnection --></ConnectionString>
            <BatchSize>1000</BatchSize>
        </SQL.Plugin>
    </Sitecore>

    In the development-config.xml folder, supply the connection string:

    <Sitecore>
        <SQL.Plugin>
            <ConnectionString><!-- DevelopmentDBConnection --></ConnectionString>
        </SQL.Plugin>
    </Sitecore>

You do not need to provide a full copy of the original configuration, only the elements that you need to override.