The Set Variable action can be used to replace, increment or append to the value of Build variables, Server variables and Agent variables. Build variables are specific to the current build and are accessible during the build using the expression %MyVariable%. They inherit the value of the Configuration, Project or Application server variable at the start of the build. Only the initial value of the server variable is accessible by the build. This is referred to as the agent variable can be referenced using expressions prefixed with a namespace, such as %Configuration.VariableName%, %Project.VariableName% and %Application.VariableName%.
Set Variable
Name
A friendly name for this action (will be displayed in the actions workflow area).
Enabled
Determines if this action will be run within the relevant stage.
Variable
This drop down contains a list of Configuration, Project and Application variables accessible to the configuration. See Variables for details on how to create a variable. Note that Expression variables cannot be modified and are therefore not listed.
Operation
You can choose to run one of the following operations on the variable:
- Replace: The variable's value will be overwritten with the new value.
- Append or increment: For Text type variables, the new value will be appended to the old value. For Numeric type variable values the old value will be incremented by the new value. DateTime/Date/Time variables cannot be incremented or appended to. Not you can decrement Numeric type variables by using negative number as the new value.
- Replace using a regular expression: This allows you to overwrite parts of the variable's old value which match a regular expression pattern.
New Value
The new value of the variable used for Replace and "Append or increment" operations.
Note: Any date time variable values should be entered as UTC. Full date time format is: yyyy-MM-dd'T'HH:mm:ss'Z' e.g. 2099-12-31T23:59:59Z
Expand expressions in new value
If this option is ticked, then the New Value will be expanded (if there's any expressions in it) before it is used to replace, append, or increment the variable's value.
Regular Expressions
Available for the "Replace using a regular expression" operation.
Pattern
A regular expression pattern to match against the existing value of the variable.
Ignore case when matching regular expression
When ticked regular expression pattern will match both lower and upper case characters
Replace first regular expression match only
When ticked only the first regular expression pattern match will be replaced
Replace With
This text will used to replace regular expression matches in the variable's value. This may contain back references to captured groups in the regular expression pattern, see Substitutions in Regular Expressions. Note, if the Expand expressions in replacement value option is ticked, these will need to be escaped e.g. $1 => $$1.
Expand expressions in replacement value
If this option is ticked, then the Replace With will be expanded (if there's any expressions in it) before it is used to replace regular expression matches in the variable's value.
Options
Set
This drop down contains a list of variable types that this action can set:
- Build variable: This is the default option and is used to set the value of the build variable only.
Build variables inherit the value of the Configuration, Project or Application server variable at the start of the build. Changes to the build variable, either manually entered into the Queue Options prompt or set by actions such as this one are specific to the build. Build variables are not accessible by other builds.
Note that, after running this action, you can reference the build variable's original value by using %Configuration.MyVariable%. Otherwise, to use the updated value, simply reference the variable by its name %MyVariable%. - Server variable: This option is used to set the value of Configuration, Project and Application variables.
These are the variables that you can edit manually on the server and are referred to as Server variables. The values of these variables determine the initial value of build variables at the start of each build. Server variables are therefore accessible across multiple builds within their defined scope. The variable with the most specific namespace is set. e.g. if the configuration variable is defined, then the configuration variable value is set, otherwise if the project variable is defined, then the project variable value is set, otherwise the application variable value is set.
Note that the updated server variable value cannot be referenced during the build - unless loaded into a build variable. This can be done either with the next option, or using a Load Variable action or Load Build Variable build event handler. - Server variable and overwrite build variable with result: This option allows you to set both the server variable and the build variable.
Synchronise agent variable with updated server variable value
Variable expressions prefixed with a namespace, such as %Configuration.VariableName%, %Project.VariableName% and %Application.VariableName%, contain the value of the server variable at the start of the build. These can be referred to as agent variables.
When this option is ticked, the value of the agent variable is updated with the new value set for the server variable.
Keep write lock on the server variable
A write lock will be acquired when updating the server variable. Tick this option to extend the write lock until the end of the build. This will prevent other builds and users from updating the variable value for the duration of the build.
Release write lock at the end of stage
Tick this option to release the extended write lock at the end of the stage rather than the end of the build.
Lock Timeout
If the server variable is locked by another build, the build will wait until the server variable lock is released and is available for writing. The maximum time it will wait can be set here. By default, it will wait for 24 hours,.
Lock Retry Delay (in seconds)
While the server variable is locked by another build, the current build will, by default, wait 3 seconds before retrying. This delay between retries can be set here. If this the value is set to zero then the default of 3 seconds will be used. Shorter delays may have a performance impact on server. Longer delays will mean that the build takes longer to to respond to the lock being released.
Note that there is no queueing - if more than one build is waiting for a variable lock, then the order in which the lock is acquired depends on which build makes a lock request first after the lock is released. So the order is essentially arbitrary..
Verbose logging
Tick to display more verbose information in the build log