Use a rule-based configuration

Current version: 9.1

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:

  1. Make sure the rule is defined in the web.config file. It can be a predefined rule or a custom rule.

  2. Create a patch file with the configuration settings you want to implement.

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

    Note

    If 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/">
  4. 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 to 6, if localenv includes the value QA:

    RequestResponse
    <setting name="Search.ClassicSearch.MaxResults" localenv:require="QA">
    <patch:attribute name="value">6</patch:attribute>
    </setting>
  5. 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 if localenv includes the value QA:

    RequestResponse
    <sitecore localenv:require="QA">
    
    </sitecore>
Note

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.

Rule test

Result

localenv:require="QA"

The setting is applied if localenv contains QA.

localenv:require="!QA"

The setting is applied if localenv does not contain QA.

localenv:require="QA or Test"

The setting is applied if localenv contains either QA or Test or both.

localenv:require="QA and Test"

The setting is applied if localenv contains both QA and Test.

localenv:require="QA and !Test"

The setting is applied if localenv contains QA but not Test. For example, it is applied if localenv is QA,Production, but not if it is QA,Test.

localenv:require="(QA or Production) and !Test"

The setting is applied if localenv contains QA or Production but not Test. For example, it is applied if localenv is QA,Development, but not if it is QA,Test.

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 value QA and role contains either the value ContentManagement or the value ContentDelivery. 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:

RequestResponse
<sitecore localenv:require="QA and !Test" role:require="Standalone or ContentDelivery">
Note

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.

Do you have some feedback for us?

If you have suggestions for improving this article,