CruiseControl.NET : Dynamic Parameters
This page last changed on Jan 27, 2010 by csut017.

Dynamic Parameters

Starting with CruiseControl.NET 1.5.0, it is possible to define dynamic parameters for a project. These parameters are values that are set at build time, as opposed to being hard-coded within the configuration file.

Defining Parameters

Parameters are defined at the project-level. Each parameter must be defined here - if you try to use a parameter that is not defined you will get a runtime error!

The following parameters are defined:

System Parameters

As well as custom parameters, a number of parameters are defined by the system. These are the same as the Integration Properties. To use one of these parameters, prefix it with a $, e.g. $CCNetBuildCondition.

Label Description Example Version
CCNetBuildCondition The condition used to trigger the build, indicating if the build was triggered by new modifications or if it was forced. Legal values are: "IfModificationExists" or "ForceBuild" ForceBuild  
CCNetIntegrationStatus The status of the current integration. Could be Success, Failure, Exception or Unknown Success  
CCNetLabel The label used to identify the CCNet build. This label is generated by the CCNet labeller. 1.0.2.120  
CCNetLastIntegrationStatus The status of the previous integration. Could be Success, Failure, Exception or Unknown Success  
CCNetProject The name of the CCNet project that is being integrated. MyProject  
CCNetBuildDate The date of the build (in yyyy-MM-dd format) 2005-08-10  
CCNetBuildTime The time of the start of the build (in HH:mm:ss format) 08:45:12  
CCNetArtifactDirectory The project artifact directory (as an absolute path) c:\program files\CruiseControl.NET\Server\MyProject\Artifacts  
CCNetWorkingDirectory The project working directory (as an absolute path) c:\program files\CruiseControl.NET\Server\MyProject\WorkingDirectory  
CCNetRequestSource The source of the integration request; this will generally be the name of the trigger that raised the request. IntervalTrigger 1.1.0
CCNetFailureUsers The list of users who have contributed modifications to a sequence of builds that has failed. John, Smith
  
CCNetListenerFile Viewing build progress with Nant and MSBuild c:\Project\Artifact\listener.xml 1.4.0
CCNetProjectUrl The URL where the project is located http://myhost/ccnet/server/  
CCNetNumericLabel Contains the label as an integer if conversion is possible, otherwise zero. 1  
CCNetModifyingUsers
The list of users who have contributed to the current build only
Smith  
CCNetUser The user who forced the build. If security is off, or the build is not forced, then this will not be set. John Doe 1.5.0

Using Parameters

Parameters can be used for tasks/publishers, source control blocks and labellers.

Using parameters can be done in one of two ways: configuration definition or implied replacement.

Not all items allow the use of dynamic parameters. To be able to use the parameters a task must expose a dynamicValues element.

With CruiseControl.NET 1.5 dynamic values are constants. These are initialised at the start of a build and cannot be changed for that build. They provide a mechanism for getting values from an external source, not a mechanism for storing values internally.

Configuration Definition

In this approach the parameter usage is defined within the configuration file. This is generally the more complex approach, but it provides better control over how the parameters are applied.

To us this approach a dynamicValues element must be added to the task/publisher:

<dynamicValues>
  <directValue>
    <property>buildArgs</property>
    <parameter>BuildArgs</parameter>
    <default>-t:Dev</default>
  </directValue>
</dynamicValues>

The following dynamic values are defined:

Implied Replacement

In this approach the parameters are defined inline in the properties. When the configuration is loaded, CruiseControl.NET reads these parameters and converts them into dynamicValues (as above).

An inline definition is contained with a $[...] block and can consist of one or more parts seperated by pipe characters. The first part is the parameter name, the second part is the default value and the third part is the format (only used when a replacementValue is generated).

If an integration property is being used, this will need to have both the $ sign for the implied replacement, plus for the integration property, e.g. $[$CCNetUser].

Some examples are:

  • <buildArgs>$[BuildArgs]</buildArgs> - use the BuildArgs parameter as a direct replacement, if omitted then the value will be empty.
  • <buildArgs>$[BuildArgs|-t:Dev]</buildArgs> - use the BuildArgs parameter as a direct replacement, if omitted then the value will be "-t:Dev".
  • <buildArgs>-t:$[BuildType|Dev] -ll:$[LogLevel|50|00]</buildArgs> - a replacementValue will be generated using the two parameters - the second parameter will use the "00" format.
  • <buildArgs>-t:$[$CCNetBuildCondition] -ll:$[LogLevel|50|00]</buildArgs> - a replacementValue will be generated that uses the system parameter of CCNetBuildCondition and a custom parameter called LogLevel.

Examples

Here are some examples of how to use dynamic values and parameters in a project. For each example, the following basic project template is used:

<project name="Test Project">
  <description>A demonstration project to show the features of the dynamic build parameters.</description>
  <sourcecontrol type="svn">
    <trunkUrl>svn://svn.mycompany.com/firstproject/trunk</trunkUrl>
    <workingDirectory>C:\SourceControl\FirstProject\</workingDirectory>
  </sourcecontrol>
  <triggers>
    <intervalTrigger />
  </triggers>
  <tasks>
    <nant>
      <buildFile>App.build</buildFile>
      <targetList>
        <target>Dev</target>
      </targetList>
      <buildArgs>-D:reason=testing</buildArgs>
    </nant>
    <gendarme>
      <assemblies>
        <assemblyMatch expr="*.dll"/>
      </assemblies>
      <limit>100</limit>
    </gendarme>
  </tasks>
  <publishers>
    <rss />
    <xmllogger />
  </publishers>
</project>

Defining a Build Target

In this example, a single select parameter is being used to set the build target. The user can choose from one of the predefined values:

<project name="Test Project">
  <description>A demonstration project to show the features of the dynamic build parameters.</description>
  <sourcecontrol type="svn">
    <trunkUrl>svn://svn.mycompany.com/firstproject/trunk</trunkUrl>
    <workingDirectory>C:\SourceControl\FirstProject\</workingDirectory>
  </sourcecontrol>
  <triggers>
    <intervalTrigger />
  </triggers>
  <tasks>
    <nant>
      <buildFile>App.build</buildFile>
      <targetList>
        <target>$[buildType|DEV]</target>
      </targetList>
      <buildArgs>-D:reason=testing</buildArgs>
    </nant>
    <gendarme>
      <assemblies>
        <assemblyMatch expr="*.dll"/>
      </assemblies>
      <limit>100</limit>
    </gendarme>
  </tasks>
  <publishers>
    <rss />
    <xmllogger />
  </publishers>
  <parameters>
    <selectParameter name="buildType">
      <allowedValues>
        <value name="Development">DEV</value>
        <value name="Test">TEST</value>
        <value name="Production">PROD</value>
      </allowedValues>
    </selectParameter>
  </parameters>
</project>

Setting a Numeric Limit

In this example, a numeric parameter is used to limit the number of errors that is reported by then Gendarme task:

<project name="Test Project">
  <description>A demonstration project to show the features of the dynamic build parameters.</description>
  <sourcecontrol type="svn">
    <trunkUrl>svn://svn.mycompany.com/firstproject/trunk</trunkUrl>
    <workingDirectory>C:\SourceControl\FirstProject\</workingDirectory>
  </sourcecontrol>
  <triggers>
    <intervalTrigger />
  </triggers>
  <tasks>
    <nant>
      <buildFile>App.build</buildFile>
      <targetList>
        <target>Dev</target>
      </targetList>
      <buildArgs>-D:reason=testing</buildArgs>
    </nant>
    <gendarme>
      <assemblies>
        <assemblyMatch expr="*.dll"/>
      </assemblies>
      <limit>$[GendarmeLimit|100]</limit>
    </gendarme>
  </tasks>
  <publishers>
    <rss />
    <xmllogger />
  </publishers>
  <parameters>
    <numericParameter name="GendarmeLimit">
      <description>The limit of Gendarme errors.</description>
      <minimum>50</minimum>
      <maximum>500</maximum>
      <default>100</default>
    </numericParameter>  
  </parameters>
</project>

Configuring the Build Task

In this example, all the values of the build task can be configured - this includes a combination of both direct and replacement dynamic values:

<cruisecontrol>
  <project name="Test Project">
    <description>A demonstration project to show the features of the dynamic build parameters.</description>
    <sourcecontrol type="svn">
      <trunkUrl>svn://svn.mycompany.com/firstproject/trunk</trunkUrl>
      <workingDirectory>C:\SourceControl\FirstProject\</workingDirectory>
    </sourcecontrol>
    <triggers>
      <intervalTrigger />
    </triggers>
    <tasks>
      <nant>
        <buildFile>$[BuildScript|App].build</buildFile>
        <targetList>
          <target>$[BuildType|DEV]</target>
        </targetList>
        <buildArgs>-D:reason=$[Reason] -D:start=$[StartDate]</buildArgs>
      </nant>
      <gendarme>
        <assemblies>
          <assemblyMatch expr="*.dll"/>
        </assemblies>
        <limit>100</limit>
      </gendarme>
    </tasks>
    <publishers>
      <rss />
      <xmllogger />
    </publishers>
    <parameters>
      <booleanParameter name="BuildScript">
        <true name="App">Yes</true>
        <false name="FullBuild">No</false>
        <display>Production Build</display>
        <description>Do you want to generate a production build?</description>
        <default>App</default>
      </booleanParameter>
      <selectParameter name="BuildType">
        <description>The type of build to perform.</description>
        <allowedValues>
          <value>Dev</value>
          <value>Test</value>
          <value>Prod</value>
        </allowedValues>
        <default>Dev</default>
      </selectParameter>
      <textParameter name="Reason">
        <description>Reason for the build being forced.</description>
        <minimum>10</minimum>
        <maximum>255</maximum>
        <required>true</required>
      </textParameter>
      <dateParameter name="StartDate">
        <default>Today</default>
        <minimum>1-Jan-2000</minimum>
        <maximum>31-Dec-2100</maximum>
      </dateParameter>
    </parameters>
  </project>
</cruisecontrol>

An alternate way of defining the last example is to explicitly define the dynamic parameters in the task:

<project name="Test Project">
  <description>A demonstration project to show the features of the dynamic build parameters.</description>
  <sourcecontrol type="svn">
    <trunkUrl>svn://svn.mycompany.com/firstproject/trunk</trunkUrl>
    <workingDirectory>C:\SourceControl\FirstProject\</workingDirectory>
  </sourcecontrol>
  <triggers>
    <intervalTrigger />
  </triggers>
  <tasks>
    <nant>
      <buildFile>App.build</buildFile>
      <targetList>
        <target>DEV</target>
      </targetList>
      <buildArgs>-D:reason= -D:start=</buildArgs>
      <dynamicValues>
        <replacementValue>
          <format>{0}.build</format>
          <parameters>
            <namedValue>
              <name>BuildScript</name>
              <value>App</value>
            </namedValue>
          </parameters>
          <property>buildFile</property>
        </replacementValue>
        <directValue>
          <default>DEV</default>
          <parameter>BuildType</parameter>
          <property>targetList/target</property>
        </directValue>
        <replacementValue>
          <format>-D:reason={0} -D:start={1}</format>
          <parameters>
            <namedValue>
              <name>Reason</name>
              <value />
            </namedValue>
            <namedValue>
              <name>StartDate</name>
              <value />
            </namedValue>
          </parameters>
          <property>buildArgs</property>
        </replacementValue>
      </dynamicValues>
    </nant>
    <gendarme>
      <assemblies>
        <assemblyMatch expr="*.dll"/>
      </assemblies>
      <limit>100</limit>
    </gendarme>
  </tasks>
  <publishers>
    <rss />
    <xmllogger />
  </publishers>
  <parameters>
    <booleanParameter name="BuildScript">
      <true name="App">Yes</true>
      <false name="FullBuild">No</false>
      <display>Production Build</display>
      <description>Do you want to generate a production build?</description>
      <default>App</default>
    </booleanParameter>
    <selectParameter name="BuildType">
      <description>The type of build to perform.</description>
      <allowedValues>
        <value>Dev</value>
        <value>Test</value>
        <value>Prod</value>
      </allowedValues>
      <default>Dev</default>
    </selectParameter>
    <textParameter name="Reason">
      <description>Reason for the build being forced.</description>
      <minimum>10</minimum>
      <maximum>255</maximum>
      <required>true</required>
    </textParameter>
    <dateParameter name="StartDate">
      <default>Today</default>
      <minimum>1-Jan-2000</minimum>
      <maximum>31-Dec-2100</maximum>
    </dateParameter>
  </parameters>
</project>

In a Source Control Block

Parameters can be used within a source control block in the same way as in a task. Just remember, parameters are static within a build, they do not change after the build has been started.

<project name="Test Project">
  <description>A demonstration project to show the features of the dynamic build parameters.</description>
  <sourcecontrol xsi:type="svn">
    <trunkUrl>svn://svn.mycompany.com/firstproject/$[branch|trunk]</trunkUrl>
    <workingDirectory>C:\SourceControl\FirstProject\</workingDirectory>
    <username>$[$CCNetUser|system]</username>
  </sourcecontrol>
  <tasks>
    <nant>
      <buildFile>App.build</buildFile>
      <targetList>
        <target>Dev</target>
      </targetList>
      <buildArgs>-D:reason=testing</buildArgs>
    </nant>
  </tasks>
  <publishers>
    <rss />
    <xmllogger />
  </publishers>
  <parameters>
    <selectParameter name="branch">
      <allowedValues>
        <value name="trunk">trunk</value>
        <value name="prototype">branches/prototype</value>
        <value name="previous">branches/previous</value>
      </allowedValues>
      <default>trunk</default>
    </selectParameter>
  </parameters>
</project>
Document generated by Confluence on Jan 23, 2011 08:52