TeamCity 2019.1帮助

Kotlin DSL

除了以XML格式在版本控制存储设置外,TeamCity还允许将设置存储在DSL(基于Kotlin语言 )中。

使用版本控制存储的DSL,您可以以编程方式定义设置。由于Kotlin是静态类型的,因此您会在IDE中自动获得自动补全功能,这使发现可用的API选项变得更加简单。

查看有关在TeamCity中使用Kotlin DSL的博客文章系列

在此页:

Kotlin DSL入门

Kotlin教程可帮助您快速学习大多数Kotlin功能。

要开始使用Kotlin DSL,请在服务器上创建一个空的沙箱项目,然后执行以下步骤:

  1. 为您的项目启用版本设置

  2. 选择Kotlin作为格式。确保已启用“ 生成可移植DSL脚本”选项。

  3. 点击Apply ,TeamCity会将设置提交到您的存储库。

项目设置结构

提交到存储库后,您将获得.teamcity包含以下文件的设置目录:

  • settings.kts –包含所有项目配置的主文件

  • pom.xml –仅当在IDE中打开项目以获得自动完成功能以及编译代码和编写单元测试功能时才需要

在IntelliJ IDEA中打开项目

要在IntelliJ IDEA中打开Kotlin DSL项目,请打开.teamcity/pom.xml文件作为项目。所有必要的依赖关系将立即自动解决。如果所有的依赖关系都已解决,则不会出现红色错误。 settings.kts 。如果您已经有IntelliJ IDEA项目,并想向其中添加Kotlin DSL模块,请按照相关说明进行操作

编辑Kotlin DSL

如果您创建了一个空项目,那么当您打开它时,您将在IDE中看到它settings.kts

导入jetbrains.buildServer.configs.kotlin.v2018_1。* / *一些注释文本* /版本=“ 2018.1”项目{}

project { }代表您将在DSL中定义其设置的当前项目。这是在上一步中启用版本设置的同一项目。可以通过特殊的方式访问此项目ID和名称DslContext对象,但不能通过DSL更改。

您可以通过调用以下内容在此项目中创建不同的实体vcsRoot()buildType()template() , 要么subProject()方法。

例如,要添加带有命令行脚本的构建配置,请执行以下操作:

导入jetbrains.buildServer.configs.kotlin.v2018_1。* import jetbrains.buildServer.configs.kotlin.v2018_1.buildSteps.script版本=“ 2018.1”项目{buildType {id(“ HelloWorld”)name =“ Hello world”步骤{脚本{scriptContent =“ echo'Hello world!'“}}}}

这里, id将用作TeamCity中“ 构建配置ID”字段的值。如果id未指定,则name参数将用作构建配置ID。

之后,您可以将此更改提交到存储库– TeamCity将检测并应用它。如果脚本执行过程中没有错误,则应该在项目中看到名为“ Hello world”的构建配置。

补丁

即使项目设置存储在Kotlin DSL中,TeamCity仍可以通过Web界面编辑项目。对于通过Web界面在项目中进行的每个更改,TeamCity都会以Kotlin格式生成一个补丁,该补丁将在项目补丁目录下带有不同TeamCity实体的子目录的位置进行检入。例如,如果您更改构建配置,TeamCity将提交.teamcity/patches/buildTypes/.kt脚本进行必要的更改到存储库。

例如,以下修补程序将构建文件清理器(Swabra)的构建功能添加到具有ID的构建配置中SampleProject_Build

changeBuildType(RelativeId(“ SampleProject_Build”)){//此部分查找必须进行更改的构建配置功能{add {//这是应复制到settings.kts文件交换的相应位置的部分{filesCleanup = Swabra。FilesCleanup。禁用}}}}

暗示您将更改从补丁文件移至您的settings.kts并删除补丁文件。补丁生成允许从编辑设置通过Web UI平滑过渡到Kotlin DSL。

共享Kotlin DSL脚本

除了简单之外,便携式DSL脚本的优点之一是该脚本可以由多个项目或多个服务器使用(因此名称:可移植)。

如果您有一个存储库.teamcity包含可移植格式的设置,您可以基于这些设置轻松创建另一个项目。可以使用“从URL创建项目”功能。

将TeamCity指向您的存储库,它将检测到.teamcity目录并提供从那里导入设置的信息:

从URL创建项目时导入Kotlin设置

根据上下文,DSL脚本可以生成略有不同的设置,例如:

var deployTarget = if(DslContext.projectId == AbsoluteId(“ Trunk”)){“登台”} else {“生产”}

进阶主题

ID更改后还原构建历史记录

为了在基于便携式DSL的项目中标识构建配置,TeamCity使用分配给DSL中此构建配置的ID 。我们建议保持此ID不变,以便将DSL源中所做的更改一致地应用于TeamCity中的相应构建配置。
但是,如果您需要在DSL中修改构建配置ID,请注意,对于TeamCity而言,看起来好像已删除了具有先前ID的配置,并创建了具有新ID的新配置。在这种情况下,您仍然可以还原已删除配置的构建历史记录。

如果基于DSL的项目使用版本设置 ,则TeamCity将检测源DSL中的任何更改,并将所有更改的设置重新应用到受影响的TeamCity实体。当您在VCS源代码中修改构建配置的ID时,TeamCity从Web UI删除“旧”配置,但将其构建历史记录保留在数据库中5天,然后对其进行清理。TeamCity提供了一种将此历史记录附加到任何现有的基于DSL的构建配置的方法。

要在更改构建配置ID后恢复构建历史,请转到TeamCity中新创建的配置的“ 构建配置设置” ,打开“ 操作”菜单,然后单击“ 附加构建历史” 。您将被重定向到临时的“ 附加构建历史记录”选项卡。在列表中选择最近删除的构建配置,然后单击“ 附加”

附加构建历史

TeamCity将还原所选配置的构建历史记录,并将其附加到新配置的构建历史记录中。

不可携式DSL

2018.1之前的版本对Kotlin DSL设置使用了不同的格式。通过关闭“ 版本设置”页面上的 生成便携式DSL脚本”复选框,仍可以启用此格式。

当TeamCity生成非便携式DSL时, .teamcity目录如下:

  • pom.xml
  • /settings.kts
  • /Project.kt
  • /buildTypes/.kt
  • /vcsRoots/.kt

哪里是启用版本控制的项目的ID。生成构建配置和VCS根目录的Kotlin DSL文件位于相应的子目录下。

settings.kts

在非便携式格式中,每个项目都具有以下内容settings.kts文件:

包MyProject导入jetbrains.buildServer.configs.kotlin.v2018_1。* / * ...* /版本=“ 2018.1”项目(MyProjectId。项目)

这是生成项目设置的入口。基本上,它表示生成项目设置的Project实例。

项目.kt

Project.kt文件外观如下:

软件包MyPackage导入jetbrains.buildServer.configs.kotlin.v2018_1。*导入jetbrains.buildServer.configs.kotlin.v2018_1。项目对象Project:Project({uuid =“ 05acd964-b90f-4493-aa09-c2229f8c76c0” id(“ MyProjectId”)parentId(“ MyParent”)name =“我的项目” ...})

哪里:

  • id是项目的绝对ID,如果您导航到该项目,则将在浏览器地址栏中看到相同的ID

  • parentId是附加有该项目的父项目的绝对ID

  • uuid是一些独特的字符序列。
    uuid是将项目,构建配置或VCS根与其数据相关联的唯一标识符。如果uuid被更改,则数据丢失。还原数据的唯一方法是还原uuid还原为原始值。另一方面, id可以自由更改实体的uuid保持不变。这是非便携式DSL格式与便携式格式的主要区别。可移植格式不需要指定uuid ,但是如果发生这种情况,那么构建配置会丢失其历史记录(例如,在更改构建配置外部ID时),您可以使用“ 操作”菜单中的“ 附加构建历史记录”选项将历史记录重新附加到构建配置中。查看详细信息

如果是不可移植的DSL,则修补程序存储在以下位置的项目修补程序目录下: .teamcity

  • pom.xml
  • /settings.kts
  • /Project.kt
  • /patches/.kt

使用补丁程序与在便携式DSL中相同:您需要将实际设置从补丁程序移至脚本并删除补丁程序。

调试Maven“生成”任务

pom.xml为Kotlin项目提供的文件具有generate任务,可用于从Kotlin DSL文件本地生成TeamCity XML文件。该任务支持调试。如果使用的是IntelliJ IDEA,则可以轻松开始调试Maven任务:

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

  2. 找到任务节点: Plugins | teamcity-configs | teamcity-configs:generate ,上下文菜单中的调试选项可用:

在IDEA中调试任务

使用外部库的能力

您可以在Kotlin DSL代码中使用外部库,该库允许在基于Kotlin DSL的不同项目之间共享代码。

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

在UI中查看DSL

在用户界面中查看构建配置设置时,可以单击侧栏中的“ 查看DSL ”:将显示当前配置的DSL表示,并突出显示正在查看的设置(例如,构建步骤,触发器,依赖项) 。要返回,请点击UI中的编辑

常见问题和常见问题

为什么便携式DSL要求所有ID都使用相同的前缀?

模板,构建配置和VCS根在服务器上所有TeamCity项目中均具有唯一的ID 。这些ID通常如下所示: _

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

但是,将便携式DSL称为便携式的原因之一是因为相同settings.kts即使在同一台服务器上,脚本也可以用于为两个不同项目生成设置。
为了在克服ID唯一性的同时实现这一目标,TeamCity使用便携式DSL脚本中的相对ID进行操作。这些相对ID中没有父项目ID前缀。因此,当TeamCity生成可移植的Kotlin DSL脚本时,它必须从所有生成的实体的ID中删除父项目ID前缀。

但是,如果不是所有的项目实体在其ID中都具有此前缀,则此方法将无效。在这种情况下,可能会显示以下错误:

构建配置ID“ ”应具有与其父项目ID相对应的前缀:“

要解决此问题,请更改受影响实体的ID。如果有很多这样的ID,请使用“ 批量编辑ID”项目操作一次更改所有ID

如何将.teamcity作为新模块添加到项目中?

问题 :如何添加.teamcity设置目录作为IntelliJ IDEA中现有项目的新模块?

解决方案 :在IntelliJ IDEA中的现有项目中:

  • 转到文件|项目结构 ,或按Ctrl + Shift + Alt + S。

  • 在“ 项目设置”部分下选择“ 模块

  • 单击加号,选择导入模块,然后选择包含项目设置的文件夹。单击确定,然后按照向导进行操作。

  • 点击应用 。新模块将添加到您的项目结构中。

设置VCS根目录的新URL(非便携式格式)

问题 :我更改了在Kotlin中存储设置的VCS根目录的URL,现在TeamCity在新位置的存储库中找不到任何设置。

解决方案

  • 在版本控制中修复Kotlin DSL中的URL,然后推送修复。

  • 禁用版本设置以启用UI。

  • 在用户界面的VCS根目录中修复URL。

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

  • 选择导入设置。

如何在Kotlin DSL中读取文件

问题 :我想根据驻留在VCS内部VCS中某些文件中的数据生成一个TeamCity构建配置.teamcity目录。

解决方案 :TeamCity通过以下方式执行DSL .teamcity作为当前目录,因此可以使用相对于.teamcity目录,例如, File("data/setup.xml") 。以外的文件.teamcity Kotlin DSL无法访问该目录。

Kotlin DSL API文档尚未初始化

问题

  • app/dsl-documentation/index.html我们的Teamcity服务器上显示“ Kotlin DSL API文档尚未初始化”

  • OutOfMemoryError在TeamCity启动期间org.jetbrains.dokka在堆栈中

解决方案 :设置内部属性teamcity.kotlinConfigsDsl.docsGenerationXmx=768m

密码相关问题

在TeamCity 2017.1之前

问题 :我不希望将密码提交到VCS,即使是以加扰的形式。

解决方案 :您可以将密码移到其设置未提交到VCS的父项目中。

问题 :生成设置后,我想更改密码。

解决方案 :必须在具有设置的Maven项目中使用以下命令手动对密码进行加密:

mvn -Dtext = org.jetbrains.teamcity:teamcity-configs-maven-plugin:scramble

从TeamCity 2017.1开始

解决方案 :使用令牌代替密码。请参阅相关章节


也可以看看:

管理员指南在版本控制中存储项目设置
TeamCity博客以代码配置,第1部分:Kotlin DSL入门