Configuration

Current version: 10.2

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 works like this:

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

The sitecorehost.xml file has the default host configuration for your application. If there is an environment-specific configuration file (for example sitecorehost.production.xml), Sitecore uses this configuration to patch the configuration that is already loaded. If you have configured a shared environment is configured in the sitecoreruntime/_shared folder, it can also have a sitecorecorehost.xml file. If it does, Sitecore uses this configuration to patch the configuration that is already loaded.

If a specific environment (for example production) is configured under the sitecoreruntime folder, it can also have a sitecorecorehost.xml file. If it does, Sitecore uses this configuration to patch the configuration that is already loaded.

All configuration files are optional. When the host application starts, it loads the sitecorehost configuration files and populates an instance of ISitecoreHostingEnvironment with the values it finds To access the full configuration discovered from the sitecorehost*.xml files, use the Configuration property of the hosting object.

Plugin configuration

You can configiure plugins by adding xml files to a config folder. The host can also provide a config folder, where the host can override configuration values from a plugin.

If you configure a shared environment in the sitecoreruntime_shared folder, it can also have a config folder that you use to override configuration values.

If you configure a specific environment (for example production) under the sitecoreruntime folder, it can also have 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 check the config folder for a folder with a name matches the name of the current environment.  If found, it loads the *.xml files in this folder in name order.This is then repeated for the host config folder, if it exists.

Finally, the sitecoreruntime folder is also checked, if a config folder exists here, the process is repeated again for that folder. All config folders are optional.

You can access the configuration provided by plugins by using the ISitecoreConfiguration object, which can be injected into any class.

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

Accessing 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:

Override configuration values at runtime

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:

Configuration layers

Configuration patching

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:

RequestResponse
<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:

RequestResponse
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>

Register services through Sitecore Host configuration

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.

Yes

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.

No

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.

Yes

Transient

Singleton

Options

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

No

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.

Yes

Property

Constructor

The following is an example of a service configuration:

RequestResponse
<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:

RequestResponse
<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:

RequestResponse
<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> 

Best practices

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:

RequestResponse
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:

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

By default, the ConnectionString element is blank:

RequestResponse
<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:

    RequestResponse
    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:

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

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

    RequestResponse
    <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.

Do you have some feedback for us?

If you have suggestions for improving this article,