Variables, Objects & Expressions

Expressions and Starting Keys

Throughout Continua CI you will come across input fields which accept expressions in their value. Expressions are built up at design time then evaluated at run time. An Expression can reference either a Continua CI variable or a Continua CI object.

Continua CI differentiates between variables and objects by starting and ending an Expression with the "%" character for variables and a "$" character for objects. These two keys are known as starting keys.

For example, a variable expression would look something like "%Configuration.MyOwnVariable%" and an object expression would look something like "$Build.BuildNumber$".To determine if an input field accepts expressions as values, press either the "%" or "$" key while targeting the input field and wait for the auto-complete drop down to appear.

Objects

The auto-complete drop down for a Continua CI object contains a list of selectable objects and values. If an item in the drop down has a  icon next to it, it's an object. Objects have children which are also objects and values. For example, in figure 1, "Build" has the object icon which means it's an object. When selecting the Build option you will see a new list of items that belong to the build (see figure 2).

Values are denoted by the  icon. Value types have no children and are the last selectable item in the drop down. In figure 2, BuildNumber is an example of a value.

Note: It's possible for object types with children to be used as value types since they can have a default value. This is explained below in the Default Values section.

Figure 1. An example of the drop down created by pressing the object starting key, "$".

Figure 2. An example of the "Build" object's children.

Variables

Variables can be used throughout Continua CI and can be created at all levels of Continua CI. They are used to pass dynamic values into the build process. When a build is ready to run, it pulls the value from one of the following variables:

• Environment variables. These are pulled in from the system automatically and cannot be changed. These environment variables are system wide and include common windows values such as PATH and COMPUTERNAME.
• Application variables. These are the highest variables that the user can define. Any variable defined in the application namespace can be used anywhere in Continua CI.
• Project variables. These variables can be accessed by any configuration or build that belong to that project.
• Configuration variables. These are only accessible from within the configuration and its builds.
• Build variables. These are the lowest level of variables and will override any of the variables listed above.

Figure 3. Variable Namespaces

The auto-complete drop down for a Continua CI variable is similar to the Continua CI objects dropdown (see figure 4). Value types are also denoted by the  icon and are named after the name of the variable. When working with variables, variable namespaces are used instead of objects and these are represented with the folder icon . Namespaces are capable of having children which are the variables in that particular namespace.

Figure 4. An example of the drop down created by pressing the variable starting key, "%".

Working with Variables

Given you have the following:

A project variable called %MyVariable% with a value of 1.

A configuration variable also called %MyVariable% with a value of 2.

These are the results you would get if you referred to these variables:

referring to %MyVariable% would return 2 (as there is no build variable called %MyVariable%, the build pulls the value from the configuration, not the project, as the configuration is further down the hierarchy).

%Configuration.MyVariable% would return 2 (retrieves the configuration variable as it has been specifically called).

%Project.MyVariable% would return 1 (retrieves the project variable as it has been specifically called).

If you ever change the value of a non-build variable during the build process, you are actually creating a new variable in the build namespace. This variable will have the same name and as you are now dealing with a build variable, you will need to refer to it without a namespace prefix for the remainder of the build.

For example, given the %MyVariable% values above:

If you assign the value 3 to %MyVariable%, you will create a new variable called %MyVariable% in the build namespace.

These are the new results you would get referring to %MyVariable%:

%MyVariable% would return 3 (This returns the value of the build variable)

%Configuration.MyVariable% would return 2 (This value never changed)

%Project.MyVariable% would return 1 (This value never changed)

Defining Variables

The method used to declare variables differs depending on the variable level.

• Environment variables are pulled in from the system automatically and cannot be changed.
• Application variables can be created and set on the variables page in the administration section.
• Project variables can be created and set under the variables tab in the project wizard.
• Configuration variables are set in the configuration wizard under the variables tab.
• Build variables can be defined in three separate ways:
  
  • When a build is triggered. These variable definitions can be defined on the trigger in the configuration wizard.
  • When a build is started manually it will prompt the user for a variable value.
  • Variables can be created as a build action in the stages and actions section.

Variable Types

There are three different types of variables in Continua CI:

• Text variables can take standard string and text inputs
• Numeric variables can take any numeric value.
• Expression variables. These can contain references to other variables and objects in Continua CI.

Drop Down Usage and Auto Complete Shortcut keys

Navigating the drop down is possible by using the [Up], [Down], [Home] and [End] keys. [Up] and [Down] will highlight the previous or next item in the list, respectively. [Home] highlights the first item in the list and [End] highlights the last.  The drop down will display a maximum of 10 items but you can get to the other items by using the [Up]/[Down] keys. [Home] and [End] only applies to the viewable items in the drop down.

To select an item you can use either [Enter] (or left mouse click), [Space] or [Tab]. When using [Enter] on a value type item, the cursor will be placed after the closing character of the expression since value types have no children you can get values from. If the type is an object then [Enter] will place the cursor at the end of the selected object's text and before the closing character of the expression. To get the next list of options in the drop down for that object type, press the period key. Alternatively, you can use [Space] to select an item. If the item selected is a value then the expression will be completed and a space added at the end of the closing character. If the item selected is an object, [Space] will complete the expression and put the cursor immediately after the closing character.

As you type in the middle of the expression, the drop down list will filter its results based on the text entered. While the cursor is in the middle of an expression you can also use the key combination of [CTRL]-[.] or [CTRL]-[Space] to display the drop down with available options. The auto-complete behavior will come into effect and take into account what has already been entered into the expression to formulate the selectable items in the drop down.  

Object Default Values

Some objects are overloaded to behave like both objects and values. The most common time an object will be used as a variable is when an expression is used to get a repositories' source directory. For example, if I want to refer to a build's version I would use the expression "$Build.Version$". However, when typing that into an input field, you will note that "Version" is an object that has children objects ("Default" and "DotNet"). If you select the "DotNet" item you will then get a drop down of items which are all value types ("Major", "Minor", "Build", "Revision"). If you wanted to get only the major version value of your version string then you would use the expression "$Build.Version.DotNet.Major$". Build Version is only one example where you may want to use the default value and not any of its children.

Here's a list of other object types that have default values: