BuildMaster Documentation

Configuration File Text Templates

Configuration files are intended to represent application configuration files that are deployed side-by-side with a release package. Common examples include the web.config file in .NET or a .properties file in Java.

Configuration File Text Templates are treated as text template assets and are independent from other files in a deployment artifact because their contents may be orthogonal to the application itself or contain environment-specific data such as database connection strings, third-party service URLs, versioning information, etc.

Simple Configuration Files

As a replacement for Configuration File Asset Templates in BuildMaster v5.8, Text Templating in combination with Configuration Variables can be used as a mechanism to deploy configuration files. Traditional configuration file assets may rely on specific key/value pairs that duplicate the functionality of existing configuration variables, but do not allow conditionals or loops.


Using the following values for the text template, deployment plan and configuration variables:

Text Template

A text template named WebConfig in the application with the contents:

<?xml version="1.0"?> <configuration> <appSettings> <add key="Accounts.Value" value="$EnvironmentName"/> <% if $DebugMode { %> <add key="Accounts.BuildNumber" value="$PackageNumber"/> <% } %> </appSettings> <system.web> <compilation <% if $DebugMode { %> debug="true" <% } else { %> debug="false" <% } %> targetFramework="4.5.2"/> <customErrors mode="Off"/> <pages controlRenderingCompatibilityVersion="4.0"/> </system.web> <system.webServer> <modules runAllManagedModulesForAllRequests="true"/> </system.webServer> </configuration>
Configuration Variables

The following variables are examples such that all deployments to pipeline stages associated with integration use $DebugMode=true:

Scope Name Value
System $DebugMode false
Environment (Integration) $DebugMode true
Pipeline Stage (Integration) $TargetDirectory D:\Web\TestWebApp-Int
Example OtterScript Deployment Plan
for server us.web.01.test-shared { Deploy-Artifact $ApplicationName.Web ( To: $TargetDirectory ); Apply-Template WebConfig ( OutputFile: $PathCombine($TargetDirectory, web.config) ); }
Example Result

Assuming the targeted pipeline stage of the "TestWebApp" application is associated with the Integration environment, the resulting output file will be deployed to D:\Web\TestWebApp-Int\web.config:

<?xml version="1.0"?> <configuration> <appSettings> <add key="Accounts.Value" value="Integration"/> <add key="Accounts.BuildNumber" value="1000"/> </appSettings> <system.web> <compilation debug="true" targetFramework="4.5.2"/> <customErrors mode="Off"/> <pages controlRenderingCompatibilityVersion="4.0"/> </system.web> <system.webServer> <modules runAllManagedModulesForAllRequests="true"/> </system.webServer> </configuration>

Additional Uses

Since text templates are transformed using a simplified OtterScript syntax, all configuration variables, runtime variables, variable functions (i.e. $ReleaseNumber), if/else conditionals, and loop syntax are supported.

Differences Between Configuration File Strategies

While using text templates is a powerful yet simple replacement for Configuration File Assets, there are some important differences:

  • Configuration file assets will compare file contents before deployment and will not deploy the file if the contents have not changed
  • Configuration file assets maintain version history and allow arbitrary comparison between instances and versions
  • Configuration file assets allow "manual deployment" outside the scope of a deployment
  • In contrast to configuration file assets, text templates allow the use of if/else conditionals, loops blocks, and access to all variable functions (i.e. $ArtifactPath(...))
  • Text templates only support OtterScript-style variable syntax (i.e. the legacy %-syntax and $-syntax are not supported)