配置构建参数

自定义基于模板的配置

例如，以下构建配置包含两个步骤和布尔 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")
    }
})

传递值到 Recipes

设定步骤执行条件

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 要求

Agent requirements允许您指定 parameter-operator-value 条件。只有满足这些条件的代理才被允许构建此构建配置。

在 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")
    }
})

startsWith("teamcity.agent.jvm.os.name", "Mac")

contains("DotNetWorkloads_7.0", "android")

exists("container.engine")

将值传递给简单脚本运行器

您可以在为命令行、 C# 脚本和 Python 运行器编写脚本时插入对参数的引用，如 ％\参数名称％。

CLI 运行器

Python 运行器

C# 脚本运行器

下面的脚本将签出目录路径（配置参数）和 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 中，使用 $(<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"] 语法代替。

See also

Administrator's Guide

配置构建参数﻿

常见信息﻿

主要使用场景﻿

自定义基于模板的配置﻿

传递值到 Recipes﻿

设定步骤执行条件﻿

指定 Agent 要求﻿

将值传递给简单脚本运行器﻿

note

在步骤之间共享值﻿

将值传递给构建器的配置文件﻿

warning

note

在链式构建之间共享值﻿

See also

Administrator's Guide

配置构建参数

常见信息

主要使用场景