TeamCity On-Premises 2024.03 Help

预定义构建参数列表

TeamCity 提供了数十个预定义的构建参数,可在构建配置或构建脚本的设置中使用。

除了 预定义的配置参数 ,所有这些参数都被 传递给一个构建过程。 请注意,根据您的构建类型(例如,参见 构建属性 部分,了解在 Gradle 构建中访问 TeamCity 系统属性的信息),访问这些参数所需要的技术可能会有所不同。

预定义的服务器构建参数

这些参数是在特定构建的范围内在服务器端生成的 - 例如,构建号。

服务器构建参数通常以系统属性和相应的环境变量的形式可用。

system.teamcity.version   |   env.TEAMCITY_VERSION

TeamCity 服务器的版本。 这个属性可以用来判断构建是否在 TeamCity 中运行。

system.teamcity.projectName   |   env.TEAMCITY_PROJECT_NAME

当前构建所属的项目名称。

system.teamcity.buildConfName   |   env.TEAMCITY_BUILDCONF_NAME

当前构建所属的构建配置的名称。

system.teamcity.buildType.id

TeamCity 使用 唯一 ID 来引用当前构建所属的构建配置。

system.teamcity.configuration.properties.file

包含所有按字母顺序排列的构建参数的文件的全名(包括路径)。 当构建过程开始时,会编写此文件,并使用 Java 属性文件格式 (例如,特殊字符将以反斜杠转义)。 另请参阅:build.properties.file

system.build.is.personal   |   env.BUILD_IS_PERSONAL

返回 true 用于 个人构建。 对于常规构建,未定义(不存在)。

system.build.number   |   env.BUILD_NUMBER

由TeamCity分配给生成的生成号。 参数采用特殊的 构建编号格式

env.BUILD_URL

当前构建的链接。

system.teamcity.build.id

TeamCity 用于引用构建的内部唯一 ID。

system.teamcity.auth.userId

生成的用户名,可用于下载其他构建配置的工件。 仅在构建期间有效。 参见此部分获取更多信息:构建级别的身份验证

系统团队城市认证密码

生成的密码,可用于下载其他构建配置的工件。 仅在构建期间有效。 参见此部分获取更多信息:构建级别的身份验证

system.build.vcs.number.<VCS_root_ID>   |   env.BUILD_VCS_NUMBER_<VCS_root_ID>

包含在指定根的生成中的最新VCS修订。 有关 VCS 根 ID 的更多信息,请参阅以下文章:配置 VCS 根.

如果构建配置只有一个 VCS 根,您可以使用 build.vcs.number 参数而不使用根 ID 标识符。

该值是 VCS 特有的。 例如,SVN的修订号和CVS的时间戳。

预定义的 Agent 构建参数

这些 系统属性 对于每一个构建都是唯一的(例如,一个包含变更列表的文件的路径)。 他们的值是在构建开始之前在代理端计算的,然后传递给构建。

system.teamcity.build.checkoutDir

用于构建的签出目录

system.teamcity.build.workingDir

开始构建的 工作目录。 这是 TeamCity 构建运行程序预计启动进程的路径。 这是一个针对运行器的特定属性,因此它在每个步骤中都有一个不同的值。

system.teamcity.build.tempDir

由 TeamCity 生成的构建临时目录的完整路径。 构建后会清理目录。

system.teamcity.build.changedFiles.file

包含构建中更改文件信息的文件的完整路径。 您可以使用此属性在您的自定义测试运行器中支持风险测试重新排序

此文件不适用于历史构建,并且如果此特定构建没有任何更改。

system.teamcity.build.properties.file   |   env.TEAMCITY_BUILD_PROPERTIES_FILE

包含所有构建系统属性的文件(包括路径)的全名,但不包括其 system. 后缀。 当构建过程开始时,将会写入此文件,并使用 Java Properties 文件格式 (例如,特殊字符将通过反斜杠进行转义)。

预定义的 Agent 环境参数

这些特定于代理的参数在每个构建代理上定义,并根据其环境变化。 除了标准参数(例如,由运行在代理上的 JVM 提供的 teamcity.agent.jvm.os.nameteamcity.agent.jvm.os.arch ),代理可以根据其安装的软件进行参数设置。 TeamCity 会自动检测像 .NET Framework、Mono 或 Visual Studio 这样的软件,并添加相应的 系统属性环境变量

如果代理机器上安装了额外的软件,系统管理员可以修改 <Agent Home>/conf/buildAgent.properties 文件来覆盖相应参数的值。

代理环境参数可以用来设置构建配置选项,定义 代理需求,和 在构建脚本内部

要查看给定构建代理的所有现有参数及其当前值,请打开代理详细信息页面并切换到 参数 标签。 请查看此链接以获取更多信息:检查参数值

teamcity.agent.name

代理的名称,如在 buildAgent.properties 代理配置文件 中所指定。 您可以使用代理名称来指定 代理要求,并限制目标配置可以使用的代理数量。

teamcity.agent.work.dir

代理工作目录 的路径。

teamcity.agent.work.dir.freeSpaceMb

代理工作目录 中可用的空闲空间。

teamcity.agent.home.dir

代理主目录 的路径

teamcity.agent.tools.dir

代理上的 Tools 目录的路径。

teamcity.agent.jvm.os.version

操作系统的版本。 报告对应 JVM 属性的值。

teamcity.agent.jvm.user.country

用户所在的国家。 报告对应 JVM 属性的值。

teamcity.agent.jvm.user.home

用户的主目录。 报告对应 JVM 属性的值。

teamcity.agent.jvm.user.timezone

用户的时区。 报告对应 JVM 属性的值。

teamcity.agent.jvm.user.name

用户的帐户名称。 报告对应 JVM 属性的值。

teamcity.agent.jvm.user.language

用户的主要操作系统语言。 报告对应 JVM 属性的值。

teamcity.agent.jvm.user.variant

用于表示用户区域设置的变化的任意值。 报告对应 JVM 属性的值。

teamcity.agent.jvm.file.encoding

默认字符集的名称,默认为 UTF-8。 报告对应 JVM 属性的值。

teamcity.agent.jvm.file.separator

文件分隔符。 报告对应 JVM 属性的值。

teamcity.agent.jvm.path.separator

路径分隔符。 报告对应 JVM 属性的值。

teamcity.agent.jvm.specification

Java 运行时环境(JRE)规范版本。 返回 java.specification.version JVM 属性 的值。

teamcity.agent.jvm.version

Java 虚拟机(JVM)实现版本。 报告对应 JVM 属性的值。

teamcity.agent.jvm.java.home

Java 安装目录。 有关更多信息,请参阅以下部分:Java 相关环境变量

teamcity.agent.os.arch.bits

代理的操作系统位数。

DotNetCLI

.NET CLI 版本。

DotNetCLI_Path

.NET CLI可执行文件的路径。

DotNetFramework <版本>[_x86 | _X64]

仅当相应版本的 .NET Framework 运行时已安装,才会定义。

DotNetFramework<version>[_x86|_x64]_Path

此参数的值被设置为相应框架运行时版本的路径。

请注意,此参数仅为每个主要版本的最新安装版本定义。 例如,如果您安装了 3.5 、 4.5 和 4.8 的版本,此参数将仅为 3.5 和 4.8 定义。 版本/参数 4.5 将被省略,因为存在 .NET Framework 4 的较新版本。 要明确定义此类版本,请考虑改用 DotNetFrameworkTargetingPack<version>_Path 参数。

DotNetFrameworkSDK<version>[_x86|_x64]

定义是否已安装对应版本的 .NET Framework SDK 。

DotNetFrameworkSDK<version>[_x86|_x64]_Path

对应框架 SDK 版本的路径。

DotNetFrameworkTargetingPack<version>_Path

对应的参考程序集(又名目标包)位置的路径。

DotNetCoreSDKx.x_Path

.NET SDK 版本。

DotNetWorkloads_<版本>

列出代理机器上安装的所有 .NET 工作负载

末尾的 <version> 是已安装的 .NET SDK 的版本。 例如,如果安装了版本 7.0.300,代理将报告 `DotNetWorkloads_7.0.300` 参数。

除了这些完整的 SDK 版本,代理还会报告带有缩短的 major.minor 后缀的工作负载参数。 例如,如果代理机器已安装了 7.0.100、7.0.200 和 7.0.300 的 .NET SDK,那么将报告引用最高版本 7.0.300 的 DotNetWorkloads_7.0 参数。

参数值是由逗号分隔的工作负载名称字符串,根据 <dotnet_dir>/metadata/workloads/<sdk_version>/InstalledWorkloads目录中的文件夹。 例如,"android,maui-ios,wasm-tools"。

WindowsSDK<version>

只有在安装了相应的 Windows SDK 版本后才会定义。

WindowsSDK<version>_Path

对应版本的 Windows SDK 的路径。

VS<Version>

定义是否已安装对应的 Visual Studio 版本

VS<Version>_Path

指向 Visual Studio 安装文件夹的路径(包含 devenv.exe 的目录)。

teamcity.dotnet.nunitlauncher<版本>

包含独立 NUnit 测试启动器的目录路径, NUnitLauncher.exe。 版本号是指测试将在其下运行的 .NET Framework 的版本。 版本等同于 .NET Framework 的版本。

teamcity.dotnet.nunitlauncher.msbuild.task

包含 MSBuild 任务 dll 的目录的路径,为 MSBuild 和 Visual Studio (sln) 提供 NUnit 任务。

teamcity.dotnet.msbuild.extensions2.0

包含 MSBuild 2.0 监听器和任务组件的目录的路径。

teamcity.dotnet.msbuild.extensions4.0

包含 MSBuild 4.0 监听器和任务程序集的目录路径。

teamcity.agent.ownPort

TeamCity 服务器用于连接到代理的 代理端口

teamcity.agent.protocol

代理和服务器之间用于数据传输的 协议

teamcity.agent.cpuBenchmark

该代理的 CPU 基准测试 结果。

teamcity.agent.hardware.cpuCount

代理机器 CPU 上的核心 / 线程数量。

teamcity.agent.hostname

构建代理主机的名称。

与 Java 相关的环境变量

当构建代理启动时,它会检测已安装的 JDK 和 JRE,然后按照下述方式定义与 Java 相关的环境变量。 如果一个已启动的代理已经设置了与 Java 相关的环境变量,那么它们将不会被重新定义。

这些变量可以像通常的 环境变量 一样在构建脚本中使用。

在 Agent 上检测 Java

代理程序会搜索并启动所有 Java 安装,以验证它们是否有效。 它根据输出确定 Java 版本和位数。

以下位置将被搜索(其中一些位置对所有操作系统通用,一些是特定操作系统专有的):

  • 如果已定义,代理上的自定义目录。 参见 如何定义自定义目录

  • 代理工具目录, <Agent Home Directory>/tools ,已检查是否包含 JRE 或 JDK。 默认情况下, /tools 的子目录不会被扫描。 要搜索子目录,请在 buildAgent.properties 文件中定义 teamcity.agent.java.search.path=%agent.tools.NAME%/INNER_PATH
    对于 Unix 和 macOS,记住在文件上 设置可执行位,以便 TeamCity 能够启动发现的 Java。

  • 在由 JAVA_HOMEJDK_HOMEJRE_HOME 环境变量指定的路径中,如果已定义。

  • 特定操作系统的位置:

    • 系统将搜索 Windows 注册表,以查找使用 Java 安装程序安装的 Java。

    • C:\Program FilesC:\Program Files (x86) 目录会被搜索,寻找 JavaJavaSoft 子目录。

    • C:\Java

    • /usr/local/java

    • /usr/local

    • /usr/java

    • /usr/lib/jvm

    • /usr

    • /System/Library/Frameworks/JavaVM.framework/Versions/<Java Version>/Home

    • /Library/Java/JavaVirtualMachines/Versions/<Java 版本>/Home

    • /Library/Java/JavaVirtualMachines/<Java 版本>/Contents/Home

  • 在由 PATH 环境变量指定的路径中,如果已定义。

定义用于搜索 Java 的自定义目录

您可以在代理上定义一个自定义目录来搜索 Java 安装。 为了实现这个,将 teamcity.agent.java.search.path 属性添加到 buildAgent.properties 文件中。

您可以定义一个目录列表:分隔符类型取决于操作系统。

定义 Java 相关环境变量

对于每个 Java 版本,都定义了以下变量: JDK_<major>_<minor>[_x64]。 例如, env.JDK_1_6 (Java 6)或 env.JDK_14_0_x64 (Java 14 64 位)。

当找到 JDK 时, JDK 变量将被定义。 在 Java 11 之前,当找到 JRE 但没有找到 JDK 时, JRE 变量就被定义了。
_x64 变量只指向 64 位的 Java。 没有 _x64 后缀的变量可能指向 32 位或 64 位安装程序,但优先选择 32 位程序。
如果发现有多个安装程序拥有相同的主版本和位数,但次版本/更新不同,则选择最新的一个。

另外,定义了以下变量:

  • JAVA_HOME — 用于最新的 JDK 安装(但更推荐 32 位的)。

  • JDK_HOME — 与 JAVA_HOME 相同。

  • JRE_HOME — 适用于最新的 JRE 或 JDK 安装(但优先选择 32 位版本),即使发现了 JDK 也需要定义。

JRE_HOMEJDK_HOME 变量可能指向不同的安装。 例如,如果已安装 JRE 1.7 和 JDK 1.6,但没有安装 JDK 1.7 —— JRE_HOME 将指向 JRE 1.7,而 JDK_HOME 将指向 JDK 1.6。

所有变量都指向 Java Home 目录,而不是二进制文件。 例如,如果您想要执行 javac 版本 1.6,您可以使用以下路径:

%env.JDK_1_6%/bin/javac
%JDK_1_6%\bin\javac
$JDK_1_6/bin/javac

预定义的配置参数

配置参数可以被其他参数引用(只有在 参数 页面中定义后才能使用),但它们不会传递给构建。

要查看这些服务器参数的完整列表,请打开任何构建的 参数标签页,或下载内部 teamcity/properties/build.start.properties.gz 工件。

依赖性参数

请参阅以下文章,以了解更多关于依赖参数的信息:在构建链中使用参数

VCS 参数

这些是附加到构建配置的 VCS 根的设置。

VCS 参数具有以下格式:

vcsroot.<VCS_root_ID>.<VCS_root_parameter_name>
  • <VCS_root_ID> — 这是 VCS 根 ID

  • <VCS_root_parameter_name> — 这是 VCS 根参数的名称。 这个参数是特定于 VCS 的。 参见如何获取 可用参数列表

如果构建配置中只有一个 VCS 根,那么可以省掉 <VCS_root_ID>. 部分。

被 VCS 标记为 secure 的参数(例如,密码)对 引用 不可用。

构建分支参数

当 TeamCity 在配置了 分支规格 的构建配置中启动构建时,它会给每个构建添加一个分支标签,或逻辑名称。 这个逻辑名称也可以作为配置参数使用:

teamcity.build.branch

为了区分在默认分支和非默认分支上启动的构建,有一个额外的布尔配置参数可以区分这些情况:

teamcity.build.branch.is_default=true|false

对于 Git 和 Mercurial,TeamCity 会在构建开始时提供附带已知 VCS 分支名称的额外参数。 请注意,根据分支配置的规范,这些可能与逻辑分支名称有所不同。 这个 VCS 分支可以通过以下名称的配置参数获得:

teamcity.build.vcs.branch.<VCS_root_ID>

在此, <VCS_root_ID>VCS 根 ID

其他参数

teamcity.build.triggeredBy

返回构建触发方式的人性化描述。

teamcity.build.triggeredBy.username

如果构建是由用户触发的,系统将报告这个用户的用户名。 当构建不是由用户触发时,将不会报告此属性。

最后修改日期: 16日 7月 2024年