Tokenisation

Abstraction of Application Settings

In this example, the ASP.NET solution creates a Web Deploy package. A common approach for this is to create a build for each environment with the settings transformed into environment specific .config files.

In the CDAF approach, a single, tokenised, configuration file, i.e. Web.Release.config is produced. The principle of a single way of working encourages the abstraction of application settings from the internal representation.

Note: The Release build is used in this example, to avoid breaking the development experience which typically uses the Debug configuration. IF the developers use both Debug & Release configurations, create a separate configuration because the tokenised Release will not run in Visual Studio.

For generic settings, a simple direct mapping is recommended

  <appSettings>
    <add key="displayName" value="%displayName%" />
    <add key="backendURL" value="%backendURL%" />
  </appSettings>

For a connection string, cannot use a token name beginning with d, i.e. %dbname% will fail as %d is interpreted as a special character.

Note the different token marker for sensitive data.

  <connectionStrings>
    <add name="entities"
      connectionString="Server=%sqlDBHost%;Database=%sqlDBName%;user id=%sqlDBUser%;password=@sqlDBPassword@;"
      xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
  </connectionStrings>

The construction of web deploy settings for the deploy path is not intuitive and is no longer (after 2010) accessible via the Visual Studio user interface. Edit the .csproj file directly for the Release property group.

note that the % character itself has to be encoded, i.e. %25

  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <OutputPath>bin\</OutputPath>
    <DefineConstants>TRACE</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
    <DeployIisAppPath>%25webAppSite%25/%25webAppName%25</DeployIisAppPath>
  </PropertyGroup>

Now that the ASP.NET specific files have been prepared, now the Continuous Integration (CI) process can be applied which will Build & Package the solution.

Continuous Integration (CI)

Build & Package Once

The primary driver file for CDAF is the CDAF.solution file. The directory containing this file is the SOLUTIONROOT. The mandatory properties are solutionName and artifactPrefix.

solutionName=MyAspApp
artifactPrefix=0.1

Build Process

The CDAF Execution Engine is used to reduce the cognitive load, allowing the engineer to focus on the primary objective, and not have to cater for logging, exception and error handling. The build.tsk file is placed in the project sub-directory.

build.tsk

The EXITIF operation allows the skipping of the build prcess if the built-in variable $ACTION has been set to clean. The MSTOOL operation loads the path to MSBuild.exe into environment variable $env:MS_BUILD. The REPLAC operation detokenises static content file to inject the product version, which includes the built in $BUILDNUMBER. Then the compile of the code and generation of Web Deploy (/T:Package) artefacts is performed:

REMOVE bin
REMOVE obj

Write-Host "If Action is clean only, then exit`n"
EXITIF $ACTION -eq "clean"

Write-Host "Combine to create symantic (http://semver.org/) version`n"
ASSIGN $productVersion+='.'
ASSIGN $productVersion+=$BUILDNUMBER

MSTOOL

Write-Host "PROJECT         : $($PROJECT)"
Write-Host "`$productVersion : $productVersion`n"

Write-Host "[$PROJECT] Apply product version as static content`n"
REPLAC Views\Shared\_Layout.cshtml %productVersion% $productVersion

Write-Host "[$PROJECT] Build Project ($PROJECT) with specific parameters for web deploy.`n"
& "$env:MS_BUILD" $PROJECT.csproj /T:Package /P:Configuration=Release /p:buildNumber=$productVersion

The resulting build is a directory files, which need to be included in your storeFor definition for packaging

storeFor

Define the artefacts that are needed to perform repeatable deployments.

SelfService\obj\Release\Package\SelfService.deploy.cmd -Flat
SelfService\obj\Release\Package\SelfService.deploy-readme.txt -Flat
SelfService\obj\Release\Package\SelfService.SetParameters.xml -Flat
SelfService\obj\Release\Package\SelfService.SourceManifest.xml -Flat
SelfService\obj\Release\Package\SelfService.zip -Flat

Database\scripts -Recurse

The CDAF CI process will build the application, with tokenised settings and package this into a self-extracting release.ps1 file. This release package can be executed for all target environments.

Continuous Delivery (CD)

Deploy Many

The tokenised configuration files need to be detokenised at deploy time. The settings are likely to include both sensitive and non-sensitive values. A core principle of CDAF for sensitive values is based on the 12-Factor approach of using environment variables, while source control is the recommended approach for non-sensitive values.

Why Source Control for Settings?

The Continuous Delivery Automation Framework (CDAF) has been engineered for enterprise scale implementations. Large scale organisations typically have a higher focus on gating and auditing, and to provide a change of configuration audit trail, along with a single way-of-working, the configuration changes are applied using the same principles as other deliveries, e.g application development.

How are Application Settings Defined?

From the CI process, the release package containers a dokenised SetParameters.xml So now configuration management can be applied at deploy time. To provide a separation of concerns, where a user only wants to compare or change settings for environments, they do not have to understand the ASP.NET specific XML file formats, instead, they only need to review the configuration management tables.

properties.cm

CDAF does not have an opinionated view of configuration management files, but by convention, the key configuration settings are placed in properties.cm in the SOLUTIONROOT. The field names in the configuration management file must match the tokens.

context  target  webAppSite           webAppName  sqlDBHost  sqlDBName  sqlDBUser  sqlDBPassword
local    TEST    "Default Web Site"   test        nonprod    test       testuser   $env:TEST_DB_PASS
local    TEST    "Default Web Site"   uat         nonprod    uat        uatuser    $env:UAT_DB_PASS
local    PROD    "Default Web Site"   prod        prodsql    prod       produser   $env:PROD_DB_PASS

Deploy Many

During (Local)[/10-cdaf/10-getting-started/60-local-tasks] or (Remote)[/10-cdaf/10-getting-started/70-remote-tasks] deployment. The deployment task can now detokenise all properties for the application deployment. The CDAF Execution Engine is used to perform the deploy time detokenisation. CDAF environment variables are used to manipulate behaviour.

Write-Host "Detokenise the non-sensitive settings for this environment"
DETOKN MyAspApp.SetParameters.xml

Write-Host "Detokenise the sensitive settings, resolving, but not revealing, settings containing variable names"
$env:CDAF_OVERRIDE_TOKEN = '@'
DETOKN MyAspApp.SetParameters.xml $TARGET resolve

Write-Host "Use Web Deploy to deploy the Aware application"
.\MyAspApp.deploy.cmd /Y /M:localhost

The overview of how to construct and test this locally see the CDAF basics.