Use a rule-based configuration
When you customize the Sitecore configuration using patch files, you can use rule-based logic to specify under which conditions a particular setting is applied.
The rule-based configuration uses rule definitions that are set in the web.config
file. Sitecore comes with two predefined rule definitions: role, which determines which Sitecore role or roles the instance runs, and search, which determines the search provider Sitecore is optimized for. You can also add your own custom rule definitions.
This topic describes how to:
Make configuration settings dependent on a rule
To make configuration settings dependent on a rule:
-
Make sure the rule is defined in the
web.config
file. It can be a predefined rule or a custom rule. -
Create a patch file with the configuration settings you want to implement.
-
Register the namespace for the rule by adding a statement of the form
xmlns:[rulename]="http://www.sitecore.net/xmlconfig/[rulename]/"
to the<configuration>
statement in the patch file.NoteIf you use the predefined rule definitions role and search in a patch file, you must also register the namespaces for them.
For example, the following adds a namespace for a rule definition called
localenv
:RequestResponse<configuration xmlns:patch=http://www.sitecore.net/xmlconfig/ xmlns:localenv="http://www.sitecore.net/xmlconfig/localenv/">
-
To make a single setting dependent on the value of a rule, add a test with the syntax
[rulename]:require=[testvalue]
to the statement that defines the setting.For example, the following sets
Search.ClassicSearch.MaxResults
to6
, iflocalenv
includes the valueQA
:RequestResponse<setting name="Search.ClassicSearch.MaxResults" localenv:require="QA"> <patch:attribute name="value">6</patch:attribute> </setting>
-
To make all settings within the patch file dependent on the value of a rule, add a test with the syntax
[rulename]:require=[testvalue]
to the<sitecore>
statement in the patch file. For example, the following applies all the settings contained within the<sitecore>
statement iflocalenv
includes the valueQA
:RequestResponse<sitecore localenv:require="QA"> … </sitecore>
If localenv
contains more than one value, the statement localenv:require="QA"
is true as long as one of the values is QA
. The statement does not have to match all the values contained in the rule definition.
The test can contain more than one test value, and can use the operators and
, or
and !
(not). The following table shows examples of valid rule tests.
|
|
---|---|
|
The setting is applied if |
|
The setting is applied if |
|
The setting is applied if |
|
The setting is applied if |
|
The setting is applied if |
|
The setting is applied if |
Use two or more rules for the same setting
You can add tests for more than one rule to the same configuration setting.
To use two or more rules for the same setting:
-
Add all the needed tests in the statement for the individual setting or in the
<sitecore>
statement. Sitecore applies the settings if all the tests are passed.In the following example, Sitecore applies the settings if
localenv
contains the valueQA
androle
contains either the valueContentManagement
or the valueContentDelivery
. Both tests must be passed in order for the settings to be applied:RequestResponse<sitecore localenv:require="QA" role:require="ContentManagement or ContentDelivery">
Tests are always concatenated using and. You cannot use or or not when concatenating multiple tests in the same statement. You can still use and, or, and not within each individual test. For example, the following statement is valid:
<sitecore localenv:require="QA and !Test" role:require="Standalone or ContentDelivery">
You can use the Show Config tool to see the resulting configuration as it looks when Sitecore compiles it at runtime. You can also use the Show Config tool to simulate changing the configuration rules or disabling configuration layers without actually changing the configuration.