Configuration
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:
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.
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 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 theset
namespace. -
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>
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 |
---|---|---|---|---|
|
The namespace of the type to be registered. |
Yes |
|
No default. |
|
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 |
|
If you do not provide a value , |
|
The lifetime of the service. Must be a valid ServiceLifetime enum value. |
Yes |
|
|
|
Optional values that you can pass to the class. See the |
No |
See example below. |
|
|
Controls how the
|
Yes |
|
|
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>
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:
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:
-
Create a
config
folder in the root of the application (if one does not already exist). -
Create environment specific subfolders for
development
andproduction
:RequestResponseSitecoreHostApplication (Root) ├── config │ └── production │ └── production-config.xml │ └── development │ └── development-config.xml ├── sitecore │ ├── SQL.Plugin │ │ └── config │ │ └── config.xml
-
In each of these subfolders, create a new XML
config
file to contain the elements you need to override and update. For example, in theproduction-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.