Agent parameters story -- Eugene Petrenko

There are parameters and references in TeamCity. You may use %PARAM_NAME% syntax mostly in all editable build configuration fields to refer to the value of parameter PARAM_NAME. This gives you much power in customizing and reusing.

In this post I'll cover build agent side of parameters infrastructure api.
On build agent side there are 3 add parameters methods named like:
- add*ConfigParameter
- add*EnvironmentVariable
- add*SystemProperty

And there are 2 methods to get those parameters back:
- get*BuildParameters().getSystemProperties
- get*BuildParmaeters().getEnvironmentVariables
- get*ConfigParameters()

On build agent we have 3 parameters scopes.

The ground scope is BuildAgentConfiguration. In that interface/scope you find all those methods for read/write agent-wide parameters. Those parameters will be visible in any builds. TeamCity server uses those parameters to check build configuration to build agent compatibility.

The second scope is AgentRunningBuild scope. Parameters from the scope are collected for a running build. AgentRunningBuild scope inherits all parameters defined in BuildAgentConfiguration and adds there parameters defined in Build Configuration on server side or web UI. On that scope read/write methods are called with 'Shared' word instead of '*'.

Third and the last scope is BuildRunnerContext. Parameters on the scope are visible for a build step (build runner call). BuildRunnerContext scope inherits all parameters defined in AgentRunningBuild scope. This scope does not allow to add new configuration parameters but it provides getRunnerParameters method for access to runner parameters of a build runner.

On every scope TeamCity does a parameters resolution to replace references with parameters values. For parameters resolution it takes unresolved parameters from all scopes and perform resolution. Resolution results are cached and done lazily on every parameters read.

Changed parameters on lower scope will be seen on any upper scope, e.g. if I add a parameter to BuildAgentConfiguration scope it will be visible on AgentRunningBuild or BuildRunnerContext scopes event while build is running.