Configuration layers

XM Cloud divides configuration files into layers. Each layer consists of a dedicated folder under the App_config folder. By default, there are four layers:

Sitecore
Modules
Custom
Environment

Each layer influences a specific area of functionality.

The configuration files are divided into layers in order to:

Give you better control over when files are loaded at runtime.
Allow you to disable all configuration files in a layer at once.

Layer definitions

XM Cloud defines the layers and the order in which they load at runtime in the Website/App_Config/layers.config file.

The following table describes the default layers, and where their configurations are stored. All folders are placed under the Website/App_Config folder.

Layer	Config section	Folder	Description
Sitecore	`<layer name="Sitecore" includefolder = "/App_config/Sitecore/">`	Sitecore	Reserved for Sitecore use. Contains configuration files for standard Sitecore components and features. You must not change the order in which configuration files load in this layer, because components are dependent on each other. Changing the default load order can cause components to stop working.
Modules	`<layer name="Modules" includefolder = "/App_config/Modules /">`	Modules	Reserved for Sitecore use. Contains configuration files for official XM Cloud modules. When you install a module, its configuration files are added to its associated folder under the Modules folder. In addition, the `layers.config` file is updated with the module's load order and the path to the module's configuration folder. By default, modules load in the order they were installed.
Custom	`<layer name="Custom" includefolder = "/App_config/Include /">`	Include	Contains the patch files you create in order to modify settings in the default XM Cloud configuration.
Environment	`<layer name="Environment" includefolder = "/App_config/Environment /">`	Environment	Contains the patch files you create to configure XM Cloud for different environments, such as QA, production, or development. For example, in a development environment, you can add patch files that enable additional logging information.

To change XM Cloud settings, you can place patch files in the Custom and Environment layers.

Important

You must not modify or add files in the Sitecore or Modules layers. Changes to files in these layers can affect the stability of the platform and can be lost during an upgrade

The load order of configuration files

By default, XM Cloud loads its configuration files in this order:

Basic system files, such as layers.config, ConnectionStrings.config, and web.config.
Configuration files in the Sitecore layer.
Configuration files in the Modules layer.
Configuration files in the Custom layer.
Configuration files in the Environment layer.

Important

Do not change the order in which the layers load.

Within each layer, by default, XM Cloud goes through all the subfolders in the layer recursively and loads the files in each subfolder in alphabetical order. Files in the root of a folder are merged before files in subfolders within the folder. For example, the file /App_Config/Include/mywebsite9.config loads before the file /App_Config/Include/Myfolder/mywebsite1.config.

If you want more control over the sequence in which your patch files load, you can add a <loadOrder> setting to the layer.

Do you have some feedback for us?

If you have suggestions for improving this article,