| Info |
|---|
For the list of expressions available for version 1.9.1 of Continua CI see Expression Objects. |
What are they?
Expressions are a mechanism for the autocompletion of variables whose values which may not be known until build execution time (for example the current build number). They can also be used to autocomplete build variables (defined within the variables tag of the configuration).
Where can I use them?
Expressions can be utilised in several dialogue dialog fields throughout Continua (they are especially useful within stage actions, and build event handlers).
The expansion icon (below) denotes fields that can provide query expansion capabilities.have expression capabilities. Note is some areas, such as configuration variables, you can click on this icon to disable expressions
Expression Expansion
To initiate a query an expansion, simply type the dollar sign symbol '$' and the query expansion expression auto complete will present. When you see an expansion box (with a green tick), this denotes that this field supports query expressions (note; not all queries present (note: not all objects are available in all fields).
Image Added
...
$Workspace| Example | | The disk location on the server for the build workspace | string| 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 |
|---|
| Id | A unique Integer allocated automatically to this build |
string| String | $Build.Id$ | "10" |
| Version |
The | A reference object for the build version |
. This is derived from the configuration 'Version Format String' field on the configuration details tabversion | $Build.Version.Default.Major$ |
| StartedBy | The username of the user who initiated the build |
string| String | $Build.StartedBy$ | "peter.toms@finalbuilder.com" |
| IsFeatureBranchBuild |
Utilized | Utilised via build triggers |
, this descriptor | . This expression is set to true when a build is triggered on a non-default branch | Boolean | $Build.IsFeatureBranchBuild$ |
BuildNumber | The total number of builds | Numeric| true |
| 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 |
| Metrics | A |
placeholder for metrics related to | reference object to the metrics associated with this build ( |
eg the number of unit tests passed) any new Changesets (which Continua has not yet seen)| changesets which have not been associated with a previous build? | Boolean | $Build.HasNewChanges$ | true |
| LinkUrl | Build details |
Url (eg | URL | String | $Build.LinkUrl$ | "http:\\SERVERNAME\New_Project_1\ci\builds\view\123 |
)string | $Build.LinkUrl$
| Anchor |
|---|
| configuration |
|---|
| configuration |
|---|
|
$Configuration Example Configuration | configuration (as defined |
on Details Pagestring| details page) | String | $Configuration.Name$ | "New Configuration 1" |
| RunningBuilds | The number of currently running builds | Integer | $Configuration.RunningBuilds$ | 1 |
| QueuedBuilds | The number of currently queued builds | Integer | $Configuration.QueuedBuilds$ | 1 |
| InitialisingBuilds | The number of currently initialising builds | Integer | $Configuration.InitialisingBuilds$ | 1 |
$Agent| Name | Description | Type | Usage Example |
|---|
| Port | The |
Port | port number used for agent communication |
string| String | $Agent.Port$ | "9000" |
| Hostname | The |
Agents Hostnamestring | | agents host name | String | $Agent.Hostname$ | "AGENTMACHINE" |
| Now | The current date and time given as local to the agent |
localdatetime| DateTime | $Agent.Now$ | "2014 4:51:44 PM" |
| NowUTC | The |
Date Time datetime| DateTime | $Agent.NowUtc$ | "2014 6:52:25 AM" |
| InstallPath | The installation path of the agent |
(eg C:\ContinuaAgentInstall)stringGetUserEnvironmentVairable| "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) |
stringGetUserEnvironmentVairable| GetUserEnvironmentVariable("TEMP")$ |
GetMachineEnvironmentVairable| "%USERPROFILE%\AppData\Local\Temp" |
| GetMachineEnvironmentVariable | Gets the specified |
Machine Environment Variable | Windows machine environment variable (relative to the agent machine) |
stringGetMachineEnvironmentVairable| GetMachineEnvironmentVariable("NUMBER_OF_PROCESSORS")$ |
List of Property Collectors | What follows | "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 for which this | project the current configuration is a part of (as |
Provided Details stringName.ToLower$| Name$ | "New Project 1" |
| Description | The description of the |
Project for which this | project the current configuration is a part of (as |
Provided Details stringDescription.ToLower$| Description$ | "This is a description for new project 1" |
| Slug | A |
shorterned | shortened version of the project name which is safe to use within |
Url's identifiers. For example "New Project 1" would have a slug of | whitespace sensitive identifiers. | String | $Project.Slug$ | "New_Project_1" |
...
...
$Source| Name | Description | Type | Usage Example |
|---|
List of the repositories associated with configuration | What follows is a given | current configuration | Repository | $Source.Reponame$ | "Mercurial_Test_1" |
$Server| Name | Description | Type | Usage Example |
|---|
| Now | The current date and time given as local to the server |
localNow.Day$| Now$ | "01/01/2014 5:03:18 PM" |
| NowUtc | The date and time given as UTC | DateTime | $Server. |
NowUtc.Month$| NowUtc$ | "01/01/2014 7:04:01 AM" |
| Hostname | The Continua server hostname |
stringHostname.ToLower$| Hostname$ | "SERVERMACHINE" |
| InstallPath | The Continua server install path |
(eg | String | $Server.InstallPath$ | "C:\Program Files\VSoft |
\)string | $Server.InstallPath.ToLower$ | Url | The Server URL (eg http://ContinuaServerName) | string | $Server.Url.ToLower$| Technologies\ContinuaCI\" |
| Url | The web service URL | String | $Server.Url$ | "http:\\SERVERNAME:8080" |
$Utils| Name | Description | Type | Usage Example |
|
|---|
| 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. |
aa.Branch.ToLower$| RepoName.Branch$ | "/branches/a_test_branch" |
| BranchName | The branch name of the branch associated with the build for the given repository |
BranchName | aa.BranchName.ToLower$| 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). |
LatestChangeset | aa| RepoName.LatestChangeset.Comment$ |
| Path | | String | $Source.aa.Path.ToLower$ |
| "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 |
Tag | aa.Tag.ToLower$| RepoName.Tag$ | "v3-release" |
| Type |
| The repository product being used | String | $Source. |
aa.Type$| RepoName.Type$ | "Mercurial" |
| Url |
| The URL of the repository in question (as defined within the repository preferences) | String | $Source. |
aa
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$ |
Repositoryusername | | | "This is a test commit" |
| RepositoryUsername | The username of the repository user who committed this changeset | String |
Repositoryusername$| BuiltChangeset.RepositoryUsername$ | "Peter Toms" |
| Branch |
| | The full branch path of the latest changeset associated with this repository | String |
| $Source.RepoName.BuiltChangeset.Branch$ |
Branchname | | "/branches/a_test_branch" |
| BranchName | The branch name of the latest changeset associated with this repository |
Branchname| BuiltChangeset.BranchName$ |
Created | | Date time| "a_test_branch" |
| Created | The date and time when the changeset was committed or created within the source repository | DateTime | $Source.RepoName.BuiltChangeset.Created |
$| Filecount | | int | $Source.RepoName.Filecount$ |
| $ | "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 |
Committerusername | | String | $Source.RepoName.BuiltChangeset. |
Committerusername$Committerfullname | | TagNames$ | "tag1,tag2,tag3" |
| ChangedTagName | The name of the tag which was changed by this changeset |
| String | $Source.RepoName.LatestTriggeringChangeset. |
Committerfullname$
Stage (used by ...
| Name | Description | Type | Usage Example |
|---|
| Name |
| | | Metrics | | | | 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 |
| | | | Unit Tests | | | |
...
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 |
| | | | Minor | | | |
| Build | | | |
| Revision | | | |
| 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") |
General Functions (used by DateTime and String objects)| Name | Description | 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") |
| ToLower | Converts a string to lowercase | String | $Source.RepoName.Branch.ToLower$ | "version 1.5" (given "Version 1.5") |
| ToUpper | Converts a string to uppercase | String | $Project.Name.ToUpper$ | "PROJECT X" (given "Project X") |
| Trim | Removes all leading and trailing occurrences of whitespace or the characters in the string provided | 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.") |
| Replace | 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") |
...