Applying XDT-Based Configuration Transforms in Sitecore Docker Container Based Setup

👋Introduction

Sitecore is a powerful enterprise-level content management system (CMS) widely used for building robust websites, intranets, and digital experiences. When working with Sitecore (in a Docker container-based setup) or any tech stack product, you sometimes need to use attributes or settings in the form of configuration files that are specific and crucial to your application.

XML Document Transform (XDT) provides an elegant solution for modifying configuration files without altering the base files directly. This article will walk you through the process of implementing XDT-based configuration transforms in a Sitecore Docker container setup.

🤯Understanding XDT Transforms

What are XDT Transforms?

The XML-Document-Transform (XDT) transforms are a way to change base configuration files written in XML during deployment or runtime. These changes follow predefined rules (XPath expressions with the xdt prefix) and can be used to:

• Override settings: Change specific values (e.g., connection strings, API endpoints) based on the environment (development, staging, production).

• Add or remove elements: Insert new elements or remove existing ones from configuration files.

• Modify attributes: Adjust attribute values without modifying the original file.

👷‍♂️Applying XDT Transforms in Sitecore Docker

1. Identify Target Configuration Files

Start by identifying the configuration files you want to transform. Common files include:

• Web.config: The main configuration file for Sitecore.

• ConnectionStrings.config: Contains database connection strings.

• App_Config/Include/*.config: Additional configuration files.

If you are working on a Sitecore-based implementation, you are likely familiar with the Sitecore Helix principles. These principles help you create a modular architecture with controlled dependencies and an easy-to-maintain codebase.

In this case, you can manage and update configuration files based on your requirements. Some are global configuration files, while others are Sitecore role-based configuration files.

2. Examples of XDT transform files in Sitecore Docker Container

If you visit the GitHub repository Sitecore Docker Example, you will find various global and role-level XDT transform files that you can use as references:

Global Transform File

Go to the custom-images/src/DockerExamples.Website folder to find the Web.config.xdt file.

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.webServer>
    <httpProtocol>
      <customHeaders>
        <add name="Docker-Examples" xdt:Locator="Match(name)" value="Solution transform" xdt:Transform="InsertIfMissing" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

In this sample XDT transform file, we are adding the custom header.

Sitecore Role based Transform File

Let's say in your Sitecore implementation, you keep getting an error at your Content Management (CM) Role: "The request queue limit of the session is exceeded."

The "Request Queue Limit" error happens when too many requests are sent to the server, and it can't process them all at the same time.

To fix this issue, you can increase the value of the aspnet:RequestQueueLimitPerSession key in the web.config file. You need to deploy this file to the CM Role using the transformation. Add the following web.config.cm.xdt file at docker/build/cm/transforms.

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <appSettings>
        <add key="aspnet:RequestQueueLimitPerSession" value="2147483647" xdt:Transform="SetAttributes" xdt:Locator="Match(key)"/>
    </appSettings>    
</configuration>

If you visit the DockerFile in the custom-images folder, you will see that all transformation files are copied to the c:\artifacts\transforms folder using the following commands at the end:

# Copy transforms, retaining directory structure
RUN Invoke-Expression 'robocopy C:\build\src C:\out\transforms /s /ndl /njh /njs *.xdt'

# Copy final build artifacts
COPY --from=builder C:\out\transforms .\transforms\

Depending on your DockerFile instructions, the files will be copied.:

To apply both Global and Sitecore Role-based transformation files to Sitecore CM Runtime images, you need to copy and transform the files. You can check the complete CM Role DockerFile here. Here are some important commands:

# Copy Global transforms
COPY --from=solution \artifacts\transforms\ \transforms\solution\

# Copy role transforms
COPY .\transforms\ \transforms\role\

# Perform solution transforms
RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath C:\transforms\solution\DockerExamples.Website

# Perform role transforms
RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath C:\transforms\role

In the above commands, we copy the Global (Solution) transform files into the transforms\solution\ folder. We also copy the CM Role Web.config.xdt file from the current folder docker/build/cm/transforms to the transforms\role\ folder. Then, we use the commands in the Invoke-XdtTransform.ps1 file to append, add, or update the existing web.config file.

You can find more information about web.config transformation in Sitecore Containers here.

3. Verify Transforms

Online Tool

You can verify your transformation file before deployment using the online tool Web.config Transformation Tester ⬇️

Sitecore Container Service File System

You can access the specific Sitecore Container Service folder structure to check if the Web.config.xdt file was copied correctly. You can also verify the web.config file to see if the changes were applied:

PowerShell

You can use a PowerShell command in the Sitecore Container Service to check if the Web.config.xdt file transforms successfully.:

PS C:\inetpub\wwwroot> powershell C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\web.config -XdtPath C:\transforms\role\web.config.cm.xdt

⚡Consideration

When working with XDT Transformation, you should pay attention to the names of the XDT files and the folder structure where you are copying them. During the transformation (running the Invoke-XdtTransform.ps1), you need to provide the correct file paths to -Path and -XdtPath parameters.

I am mentioning this because when I tried to transform some key values in the web.config using the command below, it did not work for me.

# Perform role transforms
RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath C:\transforms\role

In this case, I provided the full path of the XDT file (web.config.cm.xdt) to apply the necessary changes to the web.config, ensuring the updates were reflected in the Sitecore runtime images.

# Perform role transforms
RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\web.config -XdtPath C:\transforms\role\web.config.cm.xdt

💡Conclusion

XDT transforms are a useful tool for managing Sitecore configuration files in a Sitecore Docker Container setup. By knowing the setup and following best practices, you can make your deployment process smoother and keep configurations the same across different environments.

Remember to test thoroughly and document your transformations. Happy Sitecore Docker development! 🚀

I hope you find this guide useful! If you have any more questions or need extra help, feel free to ask. 😊🌟

🙏Credit/References

🏓Pingback