配置构建参数
参数是可以在整个 TeamCity 中引用的 name=value
对。 在 TeamCity 中有三种主要的参数类型:
配置参数—— 其主要目标是在构建配置中共享设置的参数。 您也可以使用这些参数定制从模板创建或使用 Meta-Runner(元运行器)的配置。 TeamCity 不会将此类参数传递给构建过程(也就是说,这些参数对构建脚本引擎来说是无法访问的)。
环境变量 — 开始于
env.
前缀的参数。 这些参数类似于系统的默认 env 变量,被传递给构建运行程序的过程。
系统属性—— 以
system.
前缀开始的参数。 TeamCity 可以将此类参数传递给 某些运行器 的配置文件,作为特定于构建工具的变量。
参数允许您在 TeamCity UI 和构建脚本中避免使用纯值。 反而,您可以使用 %\参数名称%
语法通过其名称引用参数。 另外,参数可以在其值中引用其他参数(例如, system.tomcat.libs=%env.CATALINA_HOME%/lib/*.jar
)。
将数值存储在参数中可以让您:
快速重用经常使用的值;
创建可复用的 模板 和 Meta-Runner (元运行器),其参数值在目标配置中被覆盖;
为您的构建配置增加灵活性:可以在 TeamCity UI 中,通过在构建过程中发送的 服务消息,或在 Run Custom Build 对话框中,快速更改参数值;
隐藏敏感信息,这些信息不应对常规 TeamCity 开发者可见;
通过使用更短的参数引用代替冗长的明文值等,提高您的配置的可读性。
请参看以下文章,其中列出了一些您可以在参数中存储值的简单用例:使用构建参数。
配置参数允许您创建一个带有参数的基础构建配置,将其提取到模板中,并在基于此模板的配置中覆盖这些参数。 使用这种技术,您可以快速复制构建配置,这些配置会根据您当前的任务略有不同。
例如,以下构建配置包含两个步骤和布尔 skip.optional.step
参数。 步骤#2 的执行与否取决于此参数值。
import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script
object SourceConfig : BuildType({
name = "SourceConfig"
params {
param("skip.optional.step", "false")
}
steps {
script {
name = "Mandatory Step"
scriptContent = """echo "Mandatory step #1 is running...""""
}
script {
name = "Optional Step"
scriptContent = """echo "Optional step #2 is running...""""
conditions {
equals("skip.optional.step", "false")
}
}
}})
如果您从此配置中提取一个模版,您可以创建同一配置的多个副本。 在那些不需要运行可选步骤#2的副本中,覆盖 skip.optional.step
参数并将其设置为 true
。
import jetbrains.buildServer.configs.kotlin.*
object ConfigFromTemplate : BuildType({
templates(SourceConfigTemplate)
name = "Build Config Based on Template"
params {
param("skip.optional.step", "true")
}
})
请参阅以下部分,以了解更多有关步骤执行条件的信息:设定步骤执行条件。
一个 Meta-Runner 可以让您从构建配置中提取构建步骤、需求和参数,并创建自定义构建运行程序。
请参考此篇文章,文章中以一个基于 Ant 的 Meta-Runner (元运行器)为例,该运行器利用自定义 system.artifact.paths
参数通过相应的 服务消息发布工件: 准备构建配置。
您可以定义 步骤执行条件 来指定是否应运行单个步骤。 您可以使用 自定义 和 预定义 的配置参数和环境变量来创建这些条件。
要在 TeamCity UI 中设置步骤执行条件,请转到步骤设置并点击 Add condition | Other condition...(添加条件 | 其他条件...)

例如,您可以根据构建代理的操作系统运行不同的 shell 脚本。
import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.powerShell
import jetbrains.buildServer.configs.kotlin.buildSteps.script
object StepExecutionConditions : BuildType({
params {
param("win.destination.path", "C:/Sources")
param("unix.destination.path", "/Users/Admin/Sources")
}
steps {
// PowerShell script runs only on Windows agents
powerShell {
name = "Copy File (Windows)"
conditions {
startsWith("teamcity.agent.jvm.os.name", "Windows")
}
scriptMode = script {
content = """Copy-Item "%system.teamcity.build.workingDir%/result.xml" -Destination %win.destination.path%"""
}
}
// Command Line runner for non-Windows agents
script {
name = "Copy File (Unix)"
executionMode = BuildStep.ExecutionMode.RUN_ON_FAILURE
conditions {
doesNotContain("teamcity.agent.jvm.os.name", "Windows")
}
scriptContent = """cp "%system.teamcity.build.workingDir%/result.xml" %unix.destination.path%"""
}
}
})
代理要求 允许您指定 parameter-operator-value
条件。 只有满足这些条件的代理才被允许构建此构建配置。
您可以只使用代理在构建开始之前可以报告其值的参数来定义代理要求。 这些参数是:
所有代理可用的预定义配置参数(例如,
teamcity.agent.name
)。由代理报告的环境变量(例如,
env.DOTNET_SDK_VERSION
)。在代理的 buildAgent.properties 文件中存在的自定义配置参数(例如,在 TeamCity UI 中创建一个
custom.agent.parameter
并在代理的属性文件中添加custom.agent.parameter=MyValue
行)。
TeamCity 会根据配置的构建步骤自动添加代理要求。 例如,如果构建步骤需要在 Linux 容器内执行,TeamCity 将添加要求,指定代理必须在 Linux 机器上运行 Docker 或 Podman。
要在 TeamCity UI 中定义自定义代理需求,请导航到 Administration | <Build Configuration> | Agent Requirements 标签页。

在 Kotlin DSL 中,使用您的构建配置中的 要求
块来定义一个需求。
import jetbrains.buildServer.configs.kotlin.*
object BuildConfig : BuildType({
name = "Build Config"
steps {
// Build steps
}
requirements {
// Requirements in the following format:
// Operator("ParameterName", "ParameterValue")
}
})
例如,以下条件只允许 Mac 代理为父构建配置运行构建。
startsWith("teamcity.agent.jvm.os.name", "Mac")
以下示例条件仅允许在已为 .NET 7 SDK 安装了 "Android" 工作负载的机器上运行构建:
contains("DotNetWorkloads_7.0", "android")
以下条件要求运行构建的代理必须拥有 Docker 或 Podman:
exists("container.engine")
您可以在为 命令行、 C# 脚本 和 Python 运行器编写脚本时插入对参数的引用,如 %\参数名称%
。
note
请注意,这些运行器仅在脚本直接编写在 TeamCity UI 的运行设置页面中时才解析参数值。 如果您在外部脚本文件中包含参数引用,TeamCity 将不会用参数值替换这些引用。
CLI 运行器 Python 运行器 C# 脚本运行器 下面的脚本将 签出目录 路径(配置参数)和 TeamCity 服务器版本(环境变量)打印到构建日志中。
以下脚本使用对构建分支的引用来获取应该复制到目标目录的文件。
此示例脚本发送 REST API 请求,以从服务器(其 URL 存储为
以下脚本将 签出目录 路径(配置参数)和 TeamCity 服务器版本(环境变量)打印到构建日志中。
以下脚本获取签出目录路径,并在其后追加一个附加路径:
要获取环境变量的值,请使用 Environment.GetEnvironmentVariable 方法:
您也可以在运行器的 脚本参数 字段中以 请查看此博客文章,其中提供了在 C# 脚本和 .NET 运行器中使用参数的示例:如何用 C# 脚本在 TeamCity 中自动化 CI / CD 任务。 |
---|
您可以使用参数将简单数据从一个步骤 / 脚本传递到另一个步骤 / 脚本。 为了做到这一点,从一个计算新参数值的脚本中发送 setParameter
服务消息。
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%!')"
}
}
}
})
.NET,Maven,Gradle,Ant 和 NAnt 运行器允许您在构建配置文件中引用 TeamCity 参数。 这种技术允许您将所需的值传递给构建过程。
warning
在此场景中使用的参数应以
env.
或system.
前缀开头,但在引用时不应包含这些前缀。 例如,在 Maven 配置文件中使用${build.number}
来引用预定义的system.build.number
参数。
在 .NET 中,使用 $(<parameter_name>)
语法传递参数值。
note
MSBuild 不支持带有点(.)的名称,因此您需要在构建脚本中使用参数时用下划线("_")替换点。
nuget push
和nuget delete
命令不支持参数。
以下示例 .csproj
文件定义了两个自定义的 MSBuild 目标:
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<OutputZipFile>project.zip</OutputZipFile>
<OutputUnzipDir>unzipped</OutputUnzipDir>
</PropertyGroup>
<Target Name="Zip">
<ItemGroup>
<FilesToZip Include="project.proj*" />
</ItemGroup>
<Exec Command="dir" />
<Microsoft.Build.Tasks.Message Text="##teamcity[progressMessage 'Archiving files to $(OutputZipFile) file...']"/>
<Exec Command="PowerShell -command Compress-Archive @(FilesToZip, ',') $(OutputZipFile) -Force" />
</Target>
<Target Name="Unzip">
<Microsoft.Build.Tasks.Message Text="##teamcity[progressMessage 'Unzipping files to $(OutputUnzipDir) folder...']"/>
<Exec Command="PowerShell -command Expand-Archive $(OutputZipFile) -DestinationPath $(OutputUnzipDir) -Force" />
</Target>
</Project>
要在 Maven 和 Ant 中引用参数值,请使用 ${parameterName}
语法。
<!--pom.xml file-->
<configuration>
<tasks>
<property environment="env"/>
<echo message="TEMP = ${env.TEMP}"/>
<echo message="TMP = ${env.TMP}"/>
<echo message="java.io.tmpdir = ${java.io.tmpdir}"/>
<echo message="build.number = ${build.number}"/>
</tasks>
</configuration>
要在 Maven 和 Ant 中引用参数值,请使用 ${parameterName}
语法。
<target name="buildmain">
<ant dir="${teamcity.build.checkoutDir}" antfile="${teamcity.build.checkoutDir}/build-test.xml" target="masterbuild_main"/>
</target>
对于 Gradle 运行器,TeamCity 系统属性可以被访问作为原生 Gradle 属性(那些在 gradle.properties
文件中定义的)。 如果属性名称允许用作 Groovy 标识符(没有包含点),请使用以下语法:
println "Custom user property value is ${customUserProperty}"
否则,如果属性的名称中有点(例如, build.vcs.number.1
),请使用 project.ext["build.vcs.number.1"]
语法代替。
感谢您的反馈!