Config Transforms and Roles in Sitecore

There are scenarios when we want to change value of some setting(s) based on environment, like DEV/QA/Staging/CM/CD1/CD2 and etc..
For example- we have an API URL which varies based on environment, so how you can have different values for different environments, we can make use of transformations config using Slow Cheetah and set different values across environments.

You can read more about Slow Cheetah transformations here- https://marketplace.visualstudio.com/items?itemName=vscps.SlowCheetah-XMLTransforms

It’s super useful when you want to :

  1. Have different AppSettings for debug and release when building your app.
  2. Use different connection strings based on your build configuration when building your app.
  3. Transform any XML file with a clean and simple syntax.

Setup and Installation:

You just need to install and setup “SlowCheetah” nuget package and Visual studio SlowCheetah extension and you are good to go.

Once Slow Cheetah is installed- In your ‘App_Config’ folder, right click on the file(this includes ConnectionString, app settings or any other config you have) you want to perform a transform on and select ‘Add Transform‘. This will add variations for each configuration build we have setup in our project like (UAT CD1,UAT CD2, PROD CD1, PROD CD2, STAGE CD1,STAGE CD2 etc):

For web projects the files are transformed when you publish or package your application.

Some of the commands which you can use to transform the configs are as follows:

To Insert:

If you want to add/Insert some setting into specific environment(s) like CM/CD, you can use the below syntax on specific configuration build transformation config file.

<add name="MySetting" value="Setting Value" xdt:Transform="Insert"/>

If you want to remove specific setting from environment(s) like CM/CD, you can use the below syntax on specific configuration build transformation config file.

To Remove:

<setting name="MySetting" value="Setting Value" xdt:Transform="Remove" xdt:Locator="Match(name)"/>

If you want to replace some value for specific setting from environment(s) like CM/CD, you can use the below syntax on specific configuration build transformation config file.

To Replace:

<setting name="MySetting" value="New Value" xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>

How to transform in Sitecore 9?

From Sitecore 9 we have an option to configure different values for different servers and environments via Rules Based Configuration. so no more config transforms to change the values, we simply need to update the config roles by one of the role available:

Following roles are available:

  • ContentDelivery
  • ContentManagement
  • Processing
  • Reporting
  • Standalone

Below are the supported roles for Sitecore 9.3 which is present in web.config file and we need to define/set role:define attribute to the correct server role.

 <!-- SUPPORTED SERVER ROLES     
         Specify the roles that you want this server to perform. A server can perform one or more roles. Enter the roles in a comma separated list. The supported roles are:

         ContentDelivery
         ContentManagement
         ContentDelivery, Indexing
         ContentManagement, Indexing
         Processing
         Reporting
         Standalone
          
    Default value: Standalone
    -->
    <add key="role:define" value="Standalone" />

For example- if we want to deploy specific setting only in ContentManagement or Standalone role we can specify it like this:

<setting name="CookieExpiryValue" value="1" role:require="Standalone or ContentManagement"/>

So things are made easy in terms of configs changes across environment and also regarding server configurations.

Note: If you are upgrading from Sitecore 8 to 9 you have to make a note of this and if you have any transformation configs present- it would be better to use Sitecore roles instead of transformation configs.

Sitecore Custom rules:

In addition to default server roles mentioned above, if you want to control some values across environments like Dev, INT, Staging CM or UAT CM we can create custom roles and use these custom roles along with server roles to define the changes.

How to define a custom rule:

In the web.config file, in the <appSettings> section, add a line specifying the rule.

<appSettings>

..
..
<add key="localenv:define" value="Dev">
..
..

</appsettings>

In the above section we have created a custom rule called “Dev“- so if we want to execute/deploy config which is based on Standalone Server role and Dev custom rule we need to define below:

<setting name="MySetting" value="TestValue" localenv:require="Dev">

We can also specify multiple rules to configure like below:

<appSettings>

..
..
<add key="localenv:define" value="Dev, INT, Staging CM, UAT CM, PROD CM">
..
..

</appsettings>

Recently we upgraded from 8.2 to 9.3 for and we changed the transformation part to Sitecore roles to control and deploy configs across environment and the change was easy and neat.

In addition to this we also have an option to test how the configurations looks like on different server role.

You can access the page from content management server and get to see the configs for different server role- http://yourhost/sitecore/admin/ShowConfigLayers.aspx

Hope this helps.

Happy learning 🙂

https://doc.sitecore.com/developers/93/platform-administration-and-architecture/en/rule-based-configuration.html

https://doc.sitecore.com/developers/93/platform-administration-and-architecture/en/add-a-custom-rule-to-your-configuration.html

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s