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.

Example

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)