TeamCity On-Premises 2024.03 Help

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

初始参数值

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

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

  • Parameters 标签位于 Run Custom Build 对话框中。

    Run Custom Build （运行自定义构建）对话框

  • 在 Build Configuration Settings | Parameters 页面上输入的自定义值。

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

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

  • 在构建代理的 配置文件中指定的值（即 <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%!')" } } } })

检查参数值

在 TeamCity 用户界面

要检查代理参数的当前值，请导航至 Agents | Parameters report 并输入您需要检查的属性的值。

检查关于代理的具体信息

您也可以点击任何构建代理以打开代理详细信息页面，并切换到 Agent Parameters 标签以查看此特定代理报告的所有参数。

检查代理上的所有参数

要查看在特定构建过程中参数具有哪些值，打开此构建的 结果页面 ，并切换到 参数 标签。

构建参数报告

这个页面有两个标签页：

  • 参数 — 列出所有配置参数、系统属性和环境变量的值。 您可以勾选相关的复选框，只查看在此次构建过程中改变了数值的参数。

  • 统计值 — 列出所有构建报告的 统计值（例如，构建成功率或检出远程仓库所需的时间）。 点击 查看图表 按钮（查看图表 ）可以让您检查这些值在构建运行过程中的趋势。

使用 REST API

要通过 REST API 检查特定构建的初始参数值和实际参数值，请向 /app/rest/builds/{buildLocator} 端点发送 GET 请求，并根据 Build schema 指定所需的负载字段。

  • /app/rest/builds/{buildLocator}?fields=originalProperties(*) — 返回构建配置中的用户定义参数及其默认值。

  • /app/rest/builds/{buildLocator}?fields=startProperties(*) — 返回代理报告的所有参数及其在构建开始时的值。

  • /app/rest/builds/{buildLocator}?fields=resultingProperties(*) — 返回代理报告的所有参数及其在构建完成时的值。

您也可以检查特定参数的初始值和最终值。 为了实现这个，指定目标参数的名称。

例如，如果您为在构建过程中更改参数值 节中展示的样例项目运行一个自定义构建，发送以下查询以检查 day.of.week 参数的值。

curl -L \ https:<SERVER_URL>/app/rest/builds/<BUILD_LOCATOR>?fields=\ originalProperties($locator(name:(value:(day.of.week),matchType:matches)),property),\ startProperties($locator(name:(value:(day.of.week),matchType:matches)),property),\ resultingProperties($locator(name:(value:(day.of.week),matchType:matches)),property)

如果此构建在星期三运行，并且您通过 Run Custom Build （运行自定义构建）对话框将星期日作为 day.of.week 参数值传递，那么响应负载将包含以下值：

  • originalProperties 返回周一（存储在构建配置中的默认值）。

  • startProperties 返回星期日（这是来自 Run custom build 对话框的值，优先级高于构建配置中的默认值）。

  • resultingProperties 返回星期三（这是在构建期间计算出的值，并通过服务消息写入）。

最后修改日期： 16日 7月 2024年
使用构建参数 创建并设置自定义参数