配置构建参数

参数是可以在整个 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-Runners

一个 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%"""
        }
    }
})

指定 Agent 要求

代理要求允许您指定 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 运行器编写脚本时插入对参数的引用，如 ％\参数名称％。

下面的脚本将签出目录路径（配置参数）和 TeamCity 服务器版本（环境变量）打印到构建日志中。

echo "Checkout directory: %teamcity.build.checkoutDir%"
echo "Server version: '$TEAMCITY_VERSION'"

以下脚本使用对构建分支的引用来获取应该复制到目标目录的文件。

set -e -x

FILE=%teamcity.build.branch%/fileToCopy.xml
if test -f "$FILE"; then
    cp "$FILE" folderA/folderB
fi

此示例脚本发送 REST API 请求，以从服务器（其 URL 存储为 serverURL 配置参数）下载 "libraries.tar.gz" 归档文件，添加构建号到其名称，并将其保存到签出目录。例如，构建 #54 的存档名称将是 "libraries_54.tar.gz"。

curl -o libraries_%build.number%.tar.gz %serverUrlBase%libraries.tar.gz

以下脚本将签出目录路径（配置参数）和 TeamCity 服务器版本（环境变量）打印到构建日志中。

print(f'Current checkout directory is: %teamcity.build.checkoutDir%')
print(f'TeamCity version is: %env.TEAMCITY_VERSION%')
# or
print(f"TeamCity version is: {os.environ['TEAMCITY_VERSION']}")

以下脚本获取签出目录路径，并在其后追加一个附加路径：

string fullPath = Path.Combine("%teamcity.build.checkoutDir%", "myFolder/bin");
Console.WriteLine(fullPath);

要获取环境变量的值，请使用 Environment.GetEnvironmentVariable 方法：

Console.WriteLine("Predefined variable value = " + System.Environment.GetEnvironmentVariable("TEAMCITY_VERSION"));
Console.WriteLine("Custom variable value = " + System.Environment.GetEnvironmentVariable("My.Custom.Env.Variable"));

您也可以在运行器的 脚本参数 字段中以 ％\参数名称％ 格式添加参数引用。这些参数将可以从全局 实参 数组中获取。

请查看此博客文章，其中提供了在 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 参数。这种技术允许您将所需的值传递给构建过程。

在 .NET 中，使用 $(<parameter_name>) 语法传递参数值。

以下示例 .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"] 语法代替。

TeamCity 参数允许您在构建链的配置之间交换值。参阅此文档文章以获取更多信息：在构建链中使用参数。

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