构建参数的作用域、优先级和生命周期

TeamCity 参数可以从下列一个或多个来源获取其值。

• 从选定为 强制设置模板 的模板中获取的值。 这些值不能被用户禁用或覆盖。

• 参数 选项卡位于 运行自定义构建 对话框中。

  

• 在 生成配置设置 | 参数 页面中输入的自定义值。

• 在 项目设置 | 参数 页面中输入的自定义值。 在项目中定义的参数由其所有子项目和构建配置继承。 如有需要，您可以在单独的构建配置中覆盖它们。

• 在常规 构建配置模板中指定的值。

• 在构建代理的 配置文件中指定的值（即 <AGENT_HOME>/conf/buildAgent.properties 文件）。 例如，以下示例演示了如何实现一个自定义构建代理排名系统，您可以在 代理需求中使用：

  

  // _Root project config
  object Project : Project({
      description = "Contains all other projects"
      params {
        param("agent.tier", "")
      }
  })

  # An agent's "buildAgent.properties" files
  
  ######################################
  #   Default Build Properties         #
  ######################################
  # ...
  agent.tier=Platinum
  # ...

• 代理在连接到 TeamCity 服务器时报告的值。 这些值被传递给描述代理环境的参数。 例如， DotNetCoreSDK7.0_Path 参数用于存储此特定代理上 .NET 7 SDK 的路径。

• 预定义构建参数的值。 这些参数可以在特定构建的服务器端范围内收集其值（例如， build.number 参数），或者在构建开始之前的代理端收集其值 (例如， teamcity.agent.work.dir.freeSpaceMb 参数)。

上述列表还按优先级从高到低排列了参数值来源。 也就是说，如果同一个参数从不同的源获取不同的值，将会应用此列表中最顶端源的值。 例如，如果 my.parameter 在代理配置文件和 TeamCity UI 的构建配置设置页面中定义，那么配置设置页面的值将优先。

TeamCity 参数可以在构建通过其阶段时改变其值。 这可能会自动发生，取决于参数报告的值的性质，或者是由于在构建期间执行的操作而产生的响应。

例如，报告可用代理磁盘空间的 teamcity.agent.work.dir.freeSpaceMb 参数会随着构建签出新的源文件以及生成新的工件和日志而改变其值。

如果您需要在构建步骤内手动更改 TeamCity 参数，请发送以下 服务消息：

echo "##teamcity[setParameter name='myParam1' value='TeamCity Agent %\teamcity.agent.name%']"

在以下配置中，一个 C# 脚本检查当前的周几并将其写入 day.of.week 参数。 随后的 Python 运行器将使用更新后的参数值。

object MyBuildConf : BuildType({
    params {
        param("day.of.week", "Monday")
    }
    steps {
        csharpScript {
            name = "Check the current day"
            content = """
            if ("%\day.of.week%" != DateTime.Today.DayOfWeek.ToString()) {
              string today = DateTime.Today.DayOfWeek.ToString();
              string TCServiceMessage = "##teamcity[setParameter name='day.of.week' value='" + today + "']";
              Console.WriteLine(TCServiceMessage);
            }
        """.trimIndent()
        }
        python {
            name = "Welcome message"
            command = script {
                content = "print('Hello %\teamcity.build.triggeredBy.username%, today is %\day.of.week%!')"
            }
        }
    }
})

warning

请注意，使用 setParameter 服务消息只会在当前构建或构建链的范围内覆盖参数值。 要 永久地 覆盖参数值，请从您的构建步骤中发送 REST API 请求，如下所示：

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script

object UpdateBuildVersion : BuildType({
name = "Update Build Version"

    steps {
        script {
            id = "simpleRunner"
            scriptContent = """
                version=%\build.version%
                ((version=version+1))

                curl --location --request PUT 'http://<server_URL>/app/rest/projects/<project_name>/parameters/build.version' \
                --header 'Accept: */*' \
                --header 'Content-Type: text/plain' \
                --header 'Authorization: Bearer your_token' \
                --data ${'$'}version
            """.trimIndent()
        }
    }
})