Kotlin DSL

要将 .teamcity 设置目录作为新模块添加到 IntelliJ IDEA 中的现有项目中，请按照以下步骤操作：

1. 转到 文件 | 项目结构 ，或按 Ctrl+Shift+Alt+S。

2. 在 项目设置 部分下选择 模块。

3. 单击加号，选择 导入模块 并选择包含项目设置的目录。 单击 确定 并按照向导操作。

4. 单击 Apply。 新的模块已添加到您的项目结构中。

要在 IntelliJ IDEA 中打开 Kotlin DSL 项目，请将 .teamcity/pom.xml 文件作为项目打开。 所有必要的依赖项将会立即自动解决。

note

如果您使用 macOS，请注意 .teamcity 目录将被隐藏，而 IntelliJ IDEA 默认不会在文件选择器中显示它。 要显示隐藏的文件和目录，请在文件选择器内按 命令 + Shift + .。

如果所有依赖都已解决，那么在 settings.kts 中将不会看到红色的错误。 如果您已经有一个 IntelliJ IDEA 项目，并希望在其中添加一个 Kotlin DSL 模块，请按照 创建新项目 部分中的指示进行操作。

您本地的 TeamCity 服务器的 DSL 文档始终可以在 <TeamCity_server_URL/app/dsl-documentation/index.html 上找到。 您也可以将此文档导入至 IDE。 这样，您编辑 .kts 文件时，就能查看对象描述和示例。

要下载这些源文件，请在 Maven 面板中点击相应的选项...

...或运行 mvn -U dependency:sources 命令。

导入的文档将作为提示显示，这些提示会在指针悬停在关键字上时出现。 要在独立窗口中打开它，请按文档快捷键（默认情况下为 F1），单击 查看 | 工具窗口 | 文档 ，或在提示面板中使用省略号按钮。

当创建一个空项目时，您会在 IDE 中的 settings.kts 中看到：

import jetbrains.buildServer.configs.kotlin.*
/* some comment text */
version = "2025.03"

project {
}

在此， 项目 {} 代表了您将在 DSL 中定义的当前项目（在 DSL 代码中，有时会被引用为 _Self）。 这就是您在上一步中启用了版本设置的同一个项目。 此项目的 ID 和名称可以通过一个特殊的 DslContext 对象进行访问，但不能通过 DSL 代码进行更改。

以下示例展示了如何使用命令行脚本添加构建配置：

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script

version = "2025.03"

project {
  buildType {
    id("HelloWorld")
    name = "Hello world"
    steps {
        script {
            scriptContent = "echo 'Hello world!'"
        }
    }
  }
}

在这里， iD 将被用作 TeamCity 中 构建配置 ID 字段的值。 在上述示例中，必须指定 iD。 如果您省略它，尝试从这个脚本生成设置时会出现验证错误。

还有另一种定义相同构建配置的方法：

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script

version = "2025.03"

project {
  buildType(HelloWorld)
}

object HelloWorld: BuildType({
    name = "Hello world"
    steps {
        script {
            scriptContent = "echo 'Hello world!'"
        }
    }
})

在这种情况下， id() 函数调用是可选的，因为 TeamCity 会根据类名（在我们的案例中是 HelloWorld ）生成 id。

在 settings.kts 文件中进行了必要的更改后，您可以将它们提交到存储库——TeamCity 将会检测并应用它们。 如果脚本执行过程中没有错误，您应该在项目中看到一个名为 "Hello world" 的构建配置。

为Kotlin项目提供的 pom.xml 文件具有 生成 任务，可用于从DSL脚本本地生成TeamCity XML配置文件。 此任务可以从 IDE 开始（请参阅 Maven 工具窗口中的 插件 | teamcity-configs | teamcity-configs:generate 节点），或从命令行开始：

mvn teamcity-configs:generate

任务执行的结果将会被放在 .teamcity/target/generated-configs 目录下。

如果您正在使用 IntelliJ IDEA ，您可以轻松开始调试任何 Maven 任务：

1. 导航到 查看 | 工具窗口 | Maven 项目。 Maven 项目 工具窗口显示。

2. 找到任务节点： 插件 | teamcity-configs | teamcity-configs:generate ，任务的上下文菜单中提供 调试 选项：

以下补丁将 构建文件清理器（Swabra） 构建功能添加到具有 ID SampleProject_Build 的构建配置中：

changeBuildType(RelativeId("SampleProject_Build")) { // this part finds the build configuration where the change has to be done
    features {
        add {
            // this is the part which should be copied to a file which generates settings for SampleProject_Build build configuration
            swabra {
                filesCleanup = Swabra.FilesCleanup.DISABLED
            }
        }
    }
}

暗示您将更改从补丁文件移至相应的 .kt 或 .kts 文件，并删除补丁文件。 补丁生成使您可以继续使用用户界面进行项目设置的编辑，同时利用 Kotlin DSL 脚本的优势。

为了识别基于便携式 DSL 的项目中的构建配置，TeamCity 使用分配给 DSL 中的此构建配置的 ID。 我们建议保持此 ID 的恒定性，以便在 DSL 代码中所做的更改能够始终一致地应用于 TeamCity 中的相应构建配置。

但是，如果您在 DSL 中修改了构建配置 ID，请注意，对于 TeamCity，此修改看起来像是使用单个提交删除了先前 ID 的配置并创建了具有新 ID 的新配置。 在这种情况下，TeamCity 将自动将构建历史附加到具有新 ID 的构建配置中。 这也适用于在一次提交中更改多个构建配置的 ID 的情况：TeamCity 使用将构建历史分配给与已删除配置最相似的配置的逻辑。 此操作的条目将出现在 服务器日志 中。

如果您使用两个提交来修改构建配置 ID——一个用于删除具有先前 ID 的配置，另一个用于添加具有新 ID 的构建配置——新构建配置将不再包含构建历史。 TeamCity 将保留 5 天的构建历史，直到 清理 ，在此期间，仍可以手动还原历史记录。

要在更改构建配置 ID 后手动恢复构建历史，请转到更改了 ID 的构建配置的 构建配置设置 ，打开 操作 菜单，然后单击 附加构建历史。 您将被重定向到 附加构建历史 选项卡。 选择分离的构建历史并单击 附加。

tip

如果您不确定选择哪个构建历史，可以查看此历史中最后一个构建的 构建结果 页面。

要为 上下文参数 定义特定值，请在您的 pom.xml 文件中添加 <contextParameters> 块。

带有上下文参数的 Maven 插件示例：

<plugin>
    <groupId>org.jetbrains.teamcity</groupId>
    <artifactId>teamcity-configs-maven-plugin</artifactId>
    <version>${teamcity.dsl.version}</version>
    <configuration>
        <format>kotlin</format>
        <dstDir>target/generated-configs</dstDir>

        <contextParameters>
            <BuildName>Test</BuildName>
            <Message>Test</Message>
        </contextParameters>

    </configuration>
</plugin>

如果您希望在本地 验证您的 DSL 脚本是否根据 DSL 上下文参数的不同值正确生成设置，那么这将非常有用。

note

TeamCity 服务器并不使用 Maven 从您的 DSL 脚本生成设置，因此，如果您将包含上下文参数的 pom.xml 提交回存储库，服务器上的设置生成将不会受到影响。

TeamCity Kotlin DSL 为配置 构建链 提供了一种管道风格的替代方法。

在 DSL 代码中，构建链是由 顺序的 方法在项目内部逐个列出并声明的链式构建。 要将将并行运行在一个链中的构建进行分组，请使用 并行 方法：在 并行 区块之后的第一个随后构建将依赖于所有前面的并行构建。

以下示例阐述了一个典型的编译和部署应用程序的流程：

project {
  buildType(Compile)
  buildType(Test1)
  buildType(Test2)
  buildType(Package)
  buildType(Deploy)
  buildType(Extra)
  ...

    sequential  {
      buildType(Compile)
      parallel (options = { onDependencyFailure = FailureAction.CANCEL }) { // non-default snapshot dependency options
        dependsOn(Extra) // extra dependency to be defined in all builds in the parallel block
        buildType(Test1)
        buildType(Test2)
      }
      buildType(Package)
      buildType(Deploy)
    }
}

如果您以管道风格定义构建链，请确保在所引用的构建配置中没有定义明确的快照依赖。

在上述示例中，构建链引用了已声明的构建。 或者，您可以在链声明后使用简化语法注册所有列出的构建：

project {

 // build chain definition:
  val buildChain = sequential {
   ...
  }

  // register all build configurations, referenced in the chain, in the current project:
  buildChain.buildTypes().forEach { buildType(it) }
}

明确的快照依赖性可以通过在 并行 和 顺序的 块中的 依赖于() 语句来定义，带有一个可选的 lambda 参数，允许设置依赖性选项。 可以通过任何块的 选项 lambda 参数设定隐式快照依赖项的非默认选项值。

使用 DSL API 版本 v2017_2+ 的设置会在 TeamCity 服务器上的 DSL 执行期间进行验证。 您还可以通过 生成 XML 配置文件 的 生成 任务，在本地进行验证。

验证确保必填属性都已指定，例如像这样的构建步骤：

buildType {
    ...
    steps {
        exec {
        }
    }
    ...
}

将产生一个验证错误，表示未指定强制性的 path 属性。 这类似于您在用户界面中创建新的构建步骤时，TeamCity 执行的检查。

您也可以以适合您的设置的方式扩展验证。 为了做到这一点，您需要重写 验证() 方法。 例如，以下类为 Git VCS 根添加了自定义验证：

open class MyGit() : GitVcsRoot() {
    constructor(init: MyGit.() -> Unit): this() {
        init()
    }

    override fun validate(consumer: ErrorConsumer) {
        super.validate(consumer) //perform basic validation

        url?.let {
            if (it.startsWith("git://") || it.startsWith("http://")) {
                consumer.consumePropertyError("url", "Insecure protocol, please use https or ssh instead")
            }
        }

        authMethod?.let {
            if (it is AuthMethod.CustomPrivateKey || it is AuthMethod.DefaultPrivateKey) {
                consumer.consumePropertyError("authMethod", "Prohibited authentication method, please use 'uploadedKey' instead")
            }
        }
    }
}

您可以在您的 Kotlin DSL 代码中使用外部库，这样可以在不同的基于 Kotlin DSL 的项目之间分享代码。

要在您的 Kotlin DSL 代码中使用外部库，需要在设置仓库的 .teamcity/pom.xml 文件中添加对此库的依赖，并提交此更改，以便 TeamCity 能够检测到它。 然后，在开始生成过程之前，TeamCity 服务器将从 Maven 仓库获取必要的依赖项，用它们编译代码，然后启动设置的生成器。

您可以在私有仓库中建立对外部库的访问。 为此，请在 Maven 设置文件 （mavenSettingsDsl.xml ）中指定所有必需的凭据，并将其上传到 Maven 设置 页面的 Root项目中。

在 2018.1 之前的 TeamCity 版本中，Kotlin DSL 设置使用的是不同的格式。 如果您导入这种过时的非便携式格式的项目，TeamCity 将允许您使用它。 在这种情况下， Generate portable DSL scripts 选项将变为可用。

当 TeamCity 生成一种非便携式的 DSL 时， .teamcity 目录中的项目结构如下：

• pom.xml

• <项目 id>/settings.kts

• <项目 id>/Project.kt

• <项目 id>/buildTypes/<构建配置 id>.kt

• <项目 id>/vcsRoots/<vcs 根 id>.kt

其中 <project id> 是启用版本设置的项目的 ID。 产生构建配置和 VCS 根的 Kotlin DSL 文件放在相应的子目录下。

package MyProject
import jetbrains.buildServer.configs.kotlin.*
/* ... */
version = "2025.03"

project(MyProjectId.Project)

package MyPackage
import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.Project

object Project : Project({
   uuid = "05acd964-b90f-4493-aa09-c2229f8c76c0"
   id("MyProjectId")
   parentId("MyParent")
   name = "My project"
   ...
})

<project id>/patches/projects/<uuid>.kts
<project id>/patches/buildTypes/<uuid>.kts
<project id>/patches/templates/<uuid>.kts
<project id>/patches/vcsRoots/<uuid>.kts

总的来说，TeamCity 将 DSL 参数处理为字符串。 为了将 DSL 值标记为安全，您可以将其分配给 密码 类型的参数：

params {
    password("<parameter_name>", "credentialsJSON:<token>")
}

在这里， <parameter_name> 是一个独特的名称，可以作为使用 DSL（例如，在 文件内容替换器 构建功能中）访问安全值的键； <token> 是对应目标安全值的代币。

示例：

params {
    password("pass-to-bucket", "credentialsJSON:12a3b456-c7de-890f-123g-4hi567890123")
}

tip

为了生成一个安全值的令牌，请按照 此指南 操作。

模板、构建配置以及 VCS 根都在服务器上的所有 TeamCity 项目中都有 唯一的 ID。 这些 ID 通常看起来像这样： <父项目 id>_<实体 id>。

由于这些 ID 必须是唯一的，因此系统中不能存在两个具有相同 ID 的不同实体。

然而，可移植 DSL 被称为可移植的原因之一是因为相同的 settings.kts 脚本甚至可以在同一服务器上为两个不同的项目生成设置。
为了在克服 ID 的唯一性的同时达到这个目标，TeamCity 在可移植 DSL 脚本中使用相对 ID。 这些相对 ID 中并未包含父项目 ID 前缀。 所以，当 TeamCity 生成可移植的 Kotlin DSL 脚本时，它必须从所有生成的实体的 ID 中移除父项目的 ID 前缀。

但是，如果并非所有项目实体的 ID 都包含此前缀，此方法将无法正常工作。 在这种情况下，可能会显示以下错误：

构建配置 id '<some id>' 应该有一个与其父项目 id ： '<parent project id>' 相对应的前缀

为了解决这个问题，更改受影响实体的 ID。 如果有许多这样的 ID，请使用 批量编辑 ID 项目操作一次更改所有 ID。

为了保持您的设置文件整洁，将冗长的代码指令存储在单独的文件中是便利的。 此类辅助脚本可以与设置文件一同放在 .teamcity 目录中。 您可以通过它们的相对路径来引用它们。

例如，这部分的 settings.kts 创建了一个带有功能的对象 readScript ，该功能读取它接收到的文件的内容：

object Util {
    fun readScript(path: String): String {
        val bufferedReader: BufferedReader = File(path).bufferedReader()
        return bufferedReader.use{ it.readText() }.trimIndent()
    }
}

在构建步骤中，我们调用了这个函数，所以它读取了位于 .teamcity 目录下的 scripts\test.sh 文件：

object CommandLineRunnerTest : BuildType({
    name = "Command Line Runner Test"
    steps {
        script {
            name = "Imported from a file"
            scriptContent = Util.readScript("scripts\\test.sh")
        }
    }
})

因此，您的 Command Line 构建步骤将运行一个在 scripts\test.sh 中指定的自定义脚本。

当编写用于脚本运行器（命令行， PowerShell， Python 等）的 Kotlin DSL 时，需注意脚本中使用的特殊字符可能与 Kotlin DSL 语法发生冲突。 这些潜在问题大多数通常属于以下任何一个类别：

• 根据 Kotlin 指南 的要求，没有逃避特殊字符。 例如， echo $(date +"%A") Shell 命令并不与 Kotlin 语法规则冲突，可以直接在 Kotlin DSL 中使用：

  script {
     id = "simpleRunner"
     scriptContent = """
         #...
         echo $(date +"%A")
     """.trimIndent()
  }

  然而，如果不进行转义，直接变量引用将导致"Kotlin DSL 编译错误：无法解析的引用"的构建日志消息。

  script {
     id = "simpleRunner"
     scriptContent = """
         day_of_week=Monday
         echo $day_of_week // Compilation error
         echo ${'$'}day_of_week // No compilation error, returns "Monday"
     """.trimIndent()
  }

• 不转义 % 字符。 TeamCity 可能会将此类未转义的字符串解读为对 构建参数 的引用。 要转义百分号字符，需要重复两次（%%）。

  例如，如果您将双百分号字符（%%regex%% ）替换为单一的（% \regex % ），以下的 Kotlin DSL 将生成一个没有兼容代理的配置：

  script {
      name = "Bash script"
      scriptContent = """
          //...
          set "regex=[0-9]+[.][0-9][0-9](.1)? EAP"
          set "items="
          for /r "$tcInstallDir" %%i in (*) do (
              findstr /r "%\%regex%%" "%%i" >nul 2>nul
              if errorlevel 1 (
                  set "items=1"
              )
          )
          //...
  """
  }

问题 ：我更改了在 Kotlin 中存储设置的 VCS 根的 URL，现在 TeamCity 无法在新位置的仓库中找到任何设置。

解决方案：

• 在版本控制中修复 Kotlin DSL 的 URL，并推送修复。

• 禁用版本设置以启用用户界面。

• 在 UI 中修复 VCS 根目录中的 URL。

• 启用版本设置 ，并再次使用相同的 VCS 根目录和 Kotlin 格式。 TeamCity 将检测到存储库中包含 .teamcity 目录，并询问您是否要导入设置。

• 选择导入设置。

问题 ：我希望根据存储在 VCS 内的 .teamcity 目录中的某个文件中的数据生成 TeamCity 构建配置。

解决方案：
您可以使用 DslContext.baseDir 属性从 DSL 脚本访问 .teamcity 目录的位置，例如：

val dataFile = File(DslContext.baseDir, "data/setup.xml")

自2019.2开始，这已成为首选方法，因为 TeamCity 不再保证 DSL 脚本的当前工作目录与 .teamcity 目录相同。

在 2019.2 之前，可以使用以下代码：

val dataFile = File("data/setup.xml")

要通过 DSL 在项目内重新排序子项目或构建配置，类似于 相应的 UI 选项 ，将它们的列表传递给 subProjectsOrder 或 buildTypesOrder。 例如，

project {
    buildType(BuildA)
    buildType(BuildB)
    buildType(BuildC)
    buildTypesOrder = arrayListOf(BuildC, BuildA, BuildB)
}

object BuildA: buildType ({
...
})

object BuildB: buildType ({
...
})

object BuildC: buildType ({
...
})

根据这些设置，构建配置将按照以下顺序在用户界面中显示：C ，A ，B。

描述服务器上所有项目设置的单个 .kts 文件可能难以维护。 您可能会在两种情况下结束此类文件：

• 该文件由 TeamCity 生成。 当您通过 操作 | 以 Kotlin 格式下载设置... 菜单导出项目设置时，TeamCity 首先会计算您当前拥有的实体（项目、配置、根）的数量。 如果此数字小于20，TeamCity 会写入一个 .kts 文件。 否则，它会为每个项目生成包含单独 .kt 文件的多个文件夹。

• 该文件是手动创建的。 如果您从一个 .kts 文件开始，并不断向其添加新的项目，那么随着时间的推移，这个文件可能会变得过于庞大，难以管理。

在第一种情况下，一旦您的构建服务器超过20个实体，TeamCity 会自动分割其设置。 对于手动创建的 .kts 文件，您可以按照以下方式进行分割：

.teamcity
  └─── pom.xml
  └─── settings.kts   # Stores only the Kotlin DSL version and the "project(_Self.Project)" line
  └─── _Self
         └─── ...
         └─── ...
  └─── ProjectA
         └─── ...
         └─── ...
  └─── ProjectA_Subproject1
         └─── ...
         └─── ...
  └─── ProjectA_Subproject2
         └─── ...
         └─── ...
  └─── ProjectB
         └─── ...
         └─── ...
  └───...
  └───...

每个文件夹（包括 <Root> 项目的 "_Self" 文件夹）都具有以下结构：

ProjectA
  └─── Project.kt   # Stores a list of subprojects, parameters, connections, and other project-level settings
  └─── buildTypes   # A folder with .kt files that define build configurations, their steps, triggers, build features, and more
          └─── ProjectA_MyBuildConfig1.kt
          └─── ProjectA_MyBuildConfig2.kt
  └─── vcsRoots     # A folder with .kt files that define VCS roots (for example, custom GitVcsRoot class descendants)
          └─── ProjectA_MyRoot1.kt
          └─── ProjectA_MyRoot2.kt

您可以下载附在 TW-64768 工单上的 ZIP 压缩包，以查看样本的层次结构，并了解单个 .kt 文件通常储存什么内容。

Kotlin 脚本可以使用如 JUnit 这样的常规测试框架进行测试。 请参阅此博客文章以获取更多信息： 代码化配置，第6部分：测试配置脚本。

问题：

• app / dsl-documentation / index.html 在我们的 Teamcity 服务器上显示 "Kotlin DSL API documentation is not initialized yet" （Kotlin DSL API 文档尚未初始化）

• OutOfMemoryError 在 TeamCity 启动时，堆栈跟踪中出现 org.jetbrains.dokka

解决方案 ：设置 内部属性teamcity.kotlinConfigsDsl.docsGenerationXmx=1500m ，然后重启服务器。

问题 ：同步 Kotlin DSL 设置失败，"编译错误：java.lang.OutOfMemoryError：Java 堆空间" 错误写入 teamcity-versioned-settings.log 文件。

解决方案 ：将 teamcity.versionedSettings.configsGeneratorXmx 内部属性设定为 1g （一千兆字节）或更多，然后重新启动服务器。 默认属性值为 512m。