What are they?
Expressions are a mechanism for the auto-completion of values which may not be known until build execution time (for example the current build number). They can also be used to autocomplete variables.
Where can I use them?
Expressions can be utilised in several dialog fields throughout Continua (they are especially useful within stage actions, and build event handlers).
The expansion icon (below) denotes fields that have expression capabilities. Note is some areas, such as configuration variables, you can click on this icon to disable expressions
Expression Expansion
To initiate an expansion, simply type the dollar symbol '$' and the expression auto complete will present (note: not all objects are available in all fields).
Available Expression Objects
Different expression objects are available for each expandable field depending on which stage in the build process the expression will be evaluated at, and whether it will be evaluated on the server or an agent.
Agent-side expression objects
Stage Actions, Workspace Rules, and Expression Variables
Expandable fields on Action dialogs, and the Workspace Rules tab of the Stage Options dialog in the Stages step of the configuration wizard, and the Edit Variable dialog in various areas, support the following root expression objects.
- Workspace
- Build
- Configuration
- Agent
- Stage
- Project
- Source
- Server
- Utils
Server-side expression objects
Triggers and Repositories
Most expandable fields on the Edit Repository dialog and the Edit Trigger dialog, except for the Variables and Artifacts tabs for Build Completed triggers, support the following root expression objects.
- Server
- Utils
Variables and Artifacts for Build Completed Triggers
Expandable fields on the Variables and Artifacts tabs for Build Completed triggers, support the following root expression objects.
- Build Object
- Configuration
- Project
- Source
- Server
- Utils
Version Format
The Version Format field on the Stages step of the configuration wizard, supports the following root expression objects.
- Build
- Source
- Server
- Utils
Variables
Expandable fields on the Edit Variable dialog (for variable types other than Expression) , support the following root expression objects.
- Configuration
- Project
- Server
- Utils
Configuration Conditions, Build Event Handlers and Agent Conditions
Expandable fields when editing Configuration Conditions in the Conditions step of the configuration wizard, in the Edit Build Event Handlers dialog, and in Agent Conditions on the Agent page under Administration, support the following root expression objects.
- Workspace
- Build
- Configuration
- Project
- Source
- Server
- Utils
Agent Requirements
Expandable fields on the Agent Requirements tab of the Stage Options dialog in the Stages step of the configuration wizard, support the following root expression objects.
- Workspace
- Build
- Agent
- Source
- Server
- Utils
Stage Gate, Promote Conditions and Skip Conditions
Expandable fields on the Edit Stage Gate dialog, Promote Conditions and Skip Conditions tabs of the Stage Options dialog in the Stages step of the configuration wizard, support the following root expression objects.
- Stage
- Build
- Server
- Utils
Reports
Expandable fields on the Edit Report dialog, support the following root expression objects.
- Workspace
- Build
- Configuration
- Project
- Server
- Utils
$Workspace
| Name | Description | Type | Usage Examples | |
|---|---|---|---|---|
| N/A | Represents the full path of a build's workspace folder. | String | $Workspace$\testfolder | "D:\ContinuaAgent\Ws\19\" |
$Build
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| BuildNumber | A zero-based auto-incremented integer allocated to this build (the first build will be build 0, the second build 1, etc) | Integer | $Build.BuildNumber$ | 100 |
| Duration | ||||
| FirstSharedResourceLabel | ||||
| HasErroredStages | ||||
| HasFailedStages | ||||
| HasNewChanges | Does this build contain changesets which have not been associated with a previous build? | Boolean | $Build.HasNewChanges$ | true |
| HasSuccessfulStages | ||||
| HasWarnings | ||||
| Id | A unique Integer allocated automatically to this build | String | $Build.Id$ | "10" |
| IsFeatureBranchBuild | Utilised via build triggers. This expression is set to true when a build is triggered on a non-default branch | Boolean | $Build.IsFeatureBranchBuild$ | true |
| LastSharedResourceLabel | ||||
| LinkUrl | Build details URL | String | $Build.LinkUrl$ | "http:\\SERVERNAME\New_Project_1\ci\builds\view\123" |
| Metrics | A reference object to the metrics associated with this build (as defined below). | Metrics | $Build.Metrics$ | N/A |
| SharedResourceLabels | ||||
| SharedResources | ||||
| StartComment | ||||
| StartedBy | The username of the user who initiated the build | String | $Build.StartedBy$ | "peter.toms@finalbuilder.com" |
| Version | A reference object for the build version (as defined below). | Version | $Build.Version$ | N/A |
$Configuration
| Name | Description | Type | Usage Examples | |
|---|---|---|---|---|
| Description | ||||
| InitialisingBuildCount | The number of currently initialising builds | Integer | $Configuration.InitialisingBuilds$ | 1 |
| InitialisingOrQueuedBuildCount | ||||
| LastBuild | ||||
| LastFinishedBuild | ||||
| Name | Name of the configuration (as defined within the Configuration details page) | String | $Configuration.Name$ | "New Configuration 1" |
| PendingPromotionBuildCount | ||||
| QueuedBuildCount | The number of currently queued builds | Integer | $Configuration.QueuedBuilds$ | 1 |
| RunningBuildCount | The number of currently running builds | Integer | $Configuration.RunningBuilds$ | 1 |
$Agent
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Port | The port number used for agent communication | String | $Agent.Port$ | "9000" |
| Hostname | The agents host name | String | $Agent.Hostname$ | "AGENTMACHINE" |
| Now | The current date and time given as local to the agent | DateTime | $Agent.Now$ | "2014 4:51:44 PM" |
| NowUTC | The current date and time given as UTC | DateTime | $Agent.NowUtc$ | "2014 6:52:25 AM" |
| InstallPath | The installation path of the agent | String | $Agent.InstallPath$ | "C:\Program Files\VSoft Technologies\ContinuaCIAgent\" |
| GetUserEnvironmentVariable | Gets the specified Windows user environment variable (relative to the agent machine's service user, and relative to the agent machine) | String | $Agent.GetUserEnvironmentVariable("TEMP")$ | "%USERPROFILE%\AppData\Local\Temp" |
| GetMachineEnvironmentVariable | Gets the specified Windows machine environment variable (relative to the agent machine) | String | $Agent.GetMachineEnvironmentVariable("NUMBER_OF_PROCESSORS")$ | "8" |
| N/A | Within the Agent object is a list of the current agent property collectors | Property Collector | $Agent.NuGet.Default.Path$ | "C:\Program Files\NuGet\NuGet.exe" |
$Project
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Name | The name of the project the current configuration is a part of (as provided on the Project details page) | String | $Project.Name$ | "New Project 1" |
| Description | The description of the project the current configuration is a part of (as provided on the Project details page) | String | $Project.Description$ | "This is a description for new project 1" |
| Slug | A shortened version of the project name which is safe to use within URLs and other whitespace sensitive identifiers. | String | $Project.Slug$ | "New_Project_1" |
$Source
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| N/A | A list of repositories associated with the current configuration | Repository | $Source.Reponame$ | "Mercurial_Test_1" |
$Server
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Hostname | The Continua server hostname | String | $Server.Hostname$ | "SERVERMACHINE" |
| InstallPath | The Continua server install path | String | $Server.InstallPath$ | "C:\Program Files\VSoft Technologies\ContinuaCI\" |
| Now | The current date and time given as local to the server | DateTime | $Server.Now$ | "01/01/2014 5:03:18 PM" |
| NowUtc | The date and time given as UTC | DateTime | $Server.NowUtc$ | "01/01/2014 7:04:01 AM" |
| Url | The web service URL | String | $Server.Url$ | "http:\\SERVERNAME:8080" |
$Utils
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| GetBoolean | ||||
| GetDate | ||||
| GetDateTime | ||||
| GetNumber | ||||
| GetString | ||||
| NewGuid | Create a new randomly generated GUID | Guid | $Utils.NewGuid$ | "da47b2d6-3580-48ed-b27a-f152da2345e6" |
| RandomNumber | Generate a new random integer value If one parameter is provided it designates a random number in the range of greater than or equal to zero and the number provided will be generated If two parameters are provided they designate the range for the generated number. If no parameters are provided a 32-bit integer greater than or equal to zero and less than Int32 max value (2,147,483,647) will be generated. | Integer | $Utils.RandomNumber("1", "10")$ $Utils.RandomNumber("10")$ $Utils.RandomNumber$ | 5 2 1906529119 |
Repository (used by $Source )
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Branch | The full name of the branch associated with the build for the given repository | String | $Source.RepoName.Branch$ | "/branches/a_test_branch" |
| BranchName | The branch name of the branch associated with the build for the given repository | String | $Source.RepoName.BranchName$ | "a_test_branch" |
| BuiltChangeset | A reference object to the changeset information related to the changeset which is being built for the given repository (as defined below) | Changeset | $Source.RepoName.BuildChangeset.TagNames$ | "tag1,tag2,tag3" |
| CommitsSinceLatestTag | The number of commits listed in the changeset history for the current branch of the given repository since the latest tag | Integer | $Source.RepoName.CommitsSinceLatestTag$ | 3 |
| LatestChangeset | A reference object to the changeset information related to the most recent changeset for the given repository (as defined below). | Changeset | $Source.RepoName.LatestChangeset.Comment$ | "a comment from the last commit" |
| LatestTagName | The latest tag name (if one exists) listed in the changeset history for the current branch of the given repository | String | $Source.RepoName.LatestTagName$ | "tag3" |
| LatestTriggeringChangeset | A reference object to the changeset information related to the latest changeset for the given repository which triggerred this build (as defined below) | Changeset | $Source.RepoName.BuildChangeset.BranchName$ | "master" |
| Path | The disk location of the source associated with the build for the given repository | String | $Source.RepoName.Path$ | "C:\ContinuaAgent\Ws\44\Source\" |
| Tag | The tag name (if one exists) associated with the build for the given repository | String | $Source.RepoName.Tag$ | "v3-release" |
| Type | The repository product being used | String | $Source.RepoName.Type$ | "Mercurial" |
| Url | The URL of the repository in question (as defined within the repository preferences) | String | $Source.RepoName.Url$ | "https://github.com/VSoftTechnologies/Delphi-Mocks.git" |
Changeset (used by $Source)
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Id | A unique identifier given to this changeset | String | $Source.RepoName.BuiltChangeset.Id$ | "a4ae66dffe5342e47c3aaf987bced4e9a320559e" |
| Comment | This comment associated with this changeset | String | $Source.RepoName.BuiltChangeset.Comment$ | "This is a test commit" |
| RepositoryUsername | The username of the repository user who committed this changeset | String | $Source.RepoName.BuiltChangeset.RepositoryUsername$ | "Peter Toms" |
| Branch | The full branch path of the latest changeset associated with this repository | String | $Source.RepoName.BuiltChangeset.Branch$ | "/branches/a_test_branch" |
| BranchName | The branch name of the latest changeset associated with this repository | String | $Source.RepoName.BuiltChangeset.BranchName$ | "a_test_branch" |
| Created | The date and time when the changeset was committed or created within the source repository | DateTime | $Source.RepoName.BuiltChangeset.Created$ | "11/09/2014 1:48:36 AM" |
| FileCount | The number of file changes associated with this commit | Integer | $Source.RepoName.BuiltChangeset.FileCount$ | 1 |
| CommitterUserName | The username of the Continua User who committed this changeset (if one exists based on user repository mappings ) | String | $Source.RepoName.BuiltChangeset.CommitterUserName$ | "peter.toms@finalbuilder.com" |
| CommitterFullName | The full name of the Continua user who committed this changeset (if one exists based on user repository mappings) | String | $Source.RepoName.BuiltChangeset.CommitterFullName$ | "Peter Toms" |
| FirstTagName | The name of the first (or earliest) tag associated with this changeset | String | $Source.RepoName.BuiltChangeset.FirstTagName$ | "tag1" |
| LatestTagName | The name of the latest tag associated with this changeset | String | $Source.RepoName.BuiltChangeset.LatestTagName$ | "tag3" |
| TagNames | A comma-delimited list of tags associated with this changeset | String | $Source.RepoName.BuiltChangeset.TagNames$ | "tag1,tag2,tag3" |
| ChangedTagName | The name of the tag which was changed by this changeset | String | $Source.RepoName.LatestTriggeringChangeset.ChangedTagName$ | "tag3" |
Stage (used by $Build)
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Name | The stage name as defined within the workflow editor | String | $Build.Stage.Name | "this is a test stage" |
| Metrics | A reference object to the metrics associated with this build (as defined below). | Metrics | $Build.Stage.Metrics | N/A |
Metrics (used by $Build)
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Compiler.Warning | The total number of compiler warnings for the current build (eg MSBuild or Visual Studio build warnings) | Integer | $Build.Metrics.Compiler.Warning$ | 5 |
| Compiler.Error | The total number of compiler errors for the current build (eg MSBuild or Visual Studio build errors) | Integer | $Build.Metrics.Compiler.Error$ | 5 |
| UnitTests | A reference object for the unit test metric details (as defined below) | UnitTests | $Build.Metrics.UnitTests | N/A |
UnitTests (used by $Build.Metrics)
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| FixtureCount | The total number of test fixtures | Integer | $Build.Metrics.UnitTests.FixtureCount$ | 5 |
| CaseCount | The total number of test cases | Integer | $Build.Metrics.UnitTests.CaseCount$ | 5 |
| Passed | The number of passed tests | Integer | $Build.Metrics.UnitTests.Passed$ | 10 |
| Failed | The number of failed tests | Integer | $Build.Metrics.UnitTests.Failed$ | 5 |
| Error | The number of tests in error | Integer | $Build.Metrics.UnitTests.Error$ | 1 |
| NotRun | The number of tests not run | Integer | $Build.Metrics.UnitTests.NotRun$ | 1 |
| Inconclusive | The number of inconclusive tests | Integer | $Build.Metrics.UnitTests.Inconclusive$ | 1 |
| Ignored | The number of ignored tests | Integer | $Build.Metrics.UnitTests.Ignored$ | 1 |
| Invalid | The number of invalid tests | Integer | $Build.Metrics.UnitTests.Invalid$ | 1 |
| Skipped | The number of skipped tests | Integer | $Build.Metrics.UnitTests.Skipped$ | 1 |
Version (used by $Build.Version)
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Default | A reference object for the default version | Default | $Build.Version.Default | N/A |
| DotNet | A reference object for the .Net version | DotNet | $Build.Version.DotNet | N/A |
Default (used by $Build.Version.Default)
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Major | The version major portion of the version number | Integer | $Build.Version.Default.Major$ | "1" (given "1.2.3.4") |
| Minor | The version minor portion of the version number | Integer | $Build.Version.Default.Minor$ | "2" (given "1.2.3.4") |
| Build | The version build portion of the version number | Integer | $Build.Version.Default.Build$ | "3" (given "1.2.3.4") |
| Revision | The version revision portion of the version number | Integer | $Build.Version.Default.Revision$ | "4" (given "1.2.3.4") |
DotNet (used by $Build.Version.DotNet)
| Name | Description | Type | Usage Example | |
|---|---|---|---|---|
| Major | The version major portion of the version number | Integer | $Build.Version.DotNet.Major$ | "1" (given "1.2.0.1287") |
| Minor | The version minor portion of the version number | Integer | $Build.Version.DotNet.Minor$ | "2" (given "1.2.0.1287") |
| Build | The version build portion of the version number | Integer | $Build.Version.DotNet.Build$ | "0" (given "1.2.0.1287") |
| Revision | The version revision portion of the version number | Integer | $Build.Version.DotNet.Revision$ | "1287" (given "1.2.0.1287") |
String Properties and Functions
| Name and Parameters | Description | Return Type | Usage Example | |
|---|---|---|---|---|
| Append(string value) | Returns a new string with the specified string added to the end | string | $Configuration.Name.Append(" ").Append($Build.Version$)$ | "Build Config 1.2.3" (given "Build Config", and "1.2.3") |
| Contains(string value [, bool ignoreCase]) | Returns a value indicating whether the specified string occurs within the current text. Use ignoreCase parameter is false by default | boolean | ||
| Insert(int startIndex, string value) | Returns a new string in which a specified string is inserted at a specified index position in the current text | string | ||
| Length | Returns the number of characters in the text | integer | ||
| PadLeft(int totalWidth [, char paddingChar]) | Returns a new string that right-aligns the characters in the current text by padding them on the left with a specified character, for a specified total length | string | ||
| PadRight(int totalWidth [, char paddingChar]) | Returns a new string that left-aligns the characters in the current text by padding them on the right with a specified character, for a specified total length | string | ||
| Remove(int startIndex [, int count]) | Returns a new string in which a specified number of characters in the current text beginning at a specified position have been deleted | string | ||
| Replace(string oldValue, string newValue) | Replaces all occurrences of the first specified string in the current string with the second specified string | string | $Configuration.Name.Replace("v.", "version" )$ | "Test Config version 10" (given "Test Config v. 10") |
| Replace(string pattern, string replacement, ignoreCase) | Returns a new string in which all matches of the specified regular expression pattern in the current text are replaced with a specified replacement string | |||
| Split(string separators, [bool trimWhitespace,] [bool removeEmptyEntries]) | Splits a string into substrings separated by any of the characters in separator parameter | string array | ||
| SplitWithQuotes(string separators [, string quotetype] [, bool trimQuotes] [, bool trimWhitespace] [, bool removeEmptyEntries]) | Splits a string into substrings separated by any of the characters in separator parameter. Separators within quotes are ignored. The quoteType parameter can be "single" or "double" and defaults to "double" | string array | ||
| Substring(int startIndex [, int length]) | Returns a substring of the current text starting at a specified character position with an optional specified length | string | ||
| ToBoolean() | Parses text to a boolean, allowing boolean operations and functions | boolean | ||
| ToLower() | Converts a string to lowercase | string | $Source.RepoName.Branch.ToLower$ | "version 1.5" (given "Version 1.5") |
| ToNumber() | Parses text to a number, allowing numeric operations and functions | number | ||
| ToUpper() | Converts a string to uppercase | string | $Project.Name.ToUpper$ | "PROJECT X" (given "Project X") |
| TrimStart([string trimChars]) | Returns a new string with all leading occurrences of white space or a specified set of characters removed | string | ||
| Trim([string trimChars]) | Returns a new string with all leading and trailing occurrences of white space or a specified set of characters removed | string | $Build.Version.Trim$ $Build.Version.Trim(".,")$ | "a b c d" (given " a b c d ") "a.b.c.d" (given ",a.b.c.d.") |
| TrimEnd([string trimChars]) | "Returns a new string with all trailing occurrences of white space or a specified set of characters removed | string | ||
Number Functions
| Name | Description | Parameters | Return Type | Usage Examples | |
|---|---|---|---|---|---|
| Add | Adds the specified number to the current number and returns the result | number | |||
| Ceiling | Returns the smallest integer greater than or equal to the current decimal number | number | |||
| Decrement | Decrements the current number by one | number | |||
| Divide | Divides the current number by the specified number and returns the result | number | |||
| Floor | Returns the largest integer less than or equal to the current decimal number | integer | |||
| Increment | Increments the current number by one | number | |||
| IntegerDivide | Divides the current integer by the specified integer and returns an integer result | integer | |||
| Modulus | Returns the remainder after dividing the current number by the specified number | number | |||
| Multiply | Multiplies the current number by the specified number and returns the result | number | |||
| Round | Rounds the current decimal number to the nearest integer | integer | |||
| Subtract | Subtracts the specified number from the current number and returns the result | number | |||
| ToString | Parses current number to a string, allowing string operations and functions | string | |||
Boolean Functions
| Name | Description | Parameters | Return Type | Usage Examples | |
|---|---|---|---|---|---|
| And | Returns logical AND of current boolean value with specified value | boolean | |||
| Or | Returns logical OR of current boolean value with specified value | boolean | |||
| Not | Negates current boolean value | boolean | |||
| ToString | Parses current boolean to a string, allowing string operations and functions | string | |||
DateTime Properties and Functions
| Name | Description | Parameters | Return Type | Usage Examples | |
|---|---|---|---|---|---|
| Day | string array | ||||
| DayOfWeek | |||||
| DaysAgo | |||||
| Format | Formats a date or time value using standard or custom .Net formatting strings | String | $Server.Now.Format("hh:mm")$ | "23:55" (given the date time "31/12/2000 23:55:333") | |
| Hour | |||||
| HoursAgo | |||||
| Local | |||||
| Millisecond | |||||
| Minute | |||||
| MinutesAgo | |||||
| Month | |||||
| Second | |||||
| SecondsAgo | |||||
| ToLongDateString | |||||
| ToLongTimeString | |||||
| ToShortDateString | |||||
| ToShortTimeString | |||||
| UTC | |||||
| Year | |||||
Date Properties and Functions
| Name | Description | Parameters | Return Type | Usage Examples | |
|---|---|---|---|---|---|
| Day | string array | ||||
| DayOfWeek | |||||
| DaysAgo | |||||
| Format | Formats a date or time value using standard or custom .Net formatting strings | String | $Server.Now.Format("hh:mm")$ | "23:55" (given the date time "31/12/2000 23:55:333") | |
| Month | |||||
| ToLongDateString | |||||
| ToShortDateString | |||||
| Year | |||||
DateTime Properties and Functions
| Name | Description | Parameters | Return Type | Usage Examples | |
|---|---|---|---|---|---|
| Format | Formats a date or time value using standard or custom .Net formatting strings | String | $Server.Now.Format("hh:mm")$ | "23:55" (given the date time "31/12/2000 23:55:333") | |
| Hour | |||||
| HoursAgo | |||||
| Millisecond | |||||
| Minute | |||||
| MinutesAgo | |||||
| Second | |||||
| SecondsAgo | |||||
| ToLongTimeString | |||||
| ToShortTimeString | |||||
| Year | |||||
TimeSpan Properties and Functions
| Name | Description | Parameters | Return Type | Usage Examples | |
|---|---|---|---|---|---|
| Format | Formats a date or time value using standard or custom .Net formatting strings | String | $Server.Now.Format("hh:mm")$ | "23:55" (given the date time "31/12/2000 23:55:333") | |
| FullAbreviatedText | |||||
| Hours | |||||
| LongText | |||||
| Milliseconds | |||||
| Minutes | |||||
| Seconds | |||||
| ShortAbbreviatedText | |||||
| ShortText | |||||
| ShortTextPadding | |||||
| Text | |||||
| TotalHours | |||||
| TotalMilliseconds | |||||
| TotalMinutes | |||||
| TotalSeconds | |||||