升级 DSL
TeamCity 的 XML 设置格式通常在主要版本中发生变化。 在服务器更新后的首次启动期间,TeamCity 会将 TeamCity 数据目录中的 XML 设置文件转换为新格式。 当设置存储在 Kotlin DSL 中时,可能需要修改 Kotlin 代码以保持其功能性。 我们还建议将 Kotlin 代码更新至最新的 config version。
这些建议将在服务器管理用户界面的相应页面上,以服务器健康报告的形式展示。
TeamCity 设置格式更改
就 DSL 而言,有以下几种类型的 TeamCity 设置更改。
可以自动执行的更改
这种类型的设置更改不需要更改 Kotlin DSL,因为服务器会在每次从 DSL 重新生成设置时自动应用这些更改。
不过,建议您将 DSL 更新到更新的 configs 版本,以减少性能损失,并使 Kotlin 脚本更接近于您在用户界面看到的设置。
TeamCity 设置中的很多更改都归入此类。 例如,一些实现构建步骤的插件可能会重命名其参数。
来自前一个 TeamCity 版本的 DSL 生成了带有旧名称的参数,但 TeamCity 可以在 DSL 执行后自动将旧参数名称替换为新的名称。
无法自动执行的更改
某些 TeamCity 设置的更改需要外部信息,无法自动完成。 例如,在 TeamCity 10.0 中,云集成的设置被保存在一个专用文件中,该文件未提交给 VCS。 在 TeamCity 2017.1 中,这些设置已移至项目级别。 TeamCity 不能在没有外部数据的情况下自动进行此类设置转换,因此需要手动更新 DSL 代码。
DSL 代码中的版本
配置版本
这是在 settings.kts
中指定的版本,它看起来像这样:
TeamCity 使用此版本来在 DSL 执行后执行转换,以使结果的 XML 配置文件与将要应用它们的当前 TeamCity 版本保持同步。 例如,您的 DSL 脚本可以由 TeamCity 2017.2 生成,并将版本设置为 2017.2
。 当您将服务器升级到版本 2022.04
,TeamCity 将执行您的 DSL 并应用额外的转换以修改设置,以便符合最新版本所期望的格式。
Kotlin DSL API 版本
TeamCity 在 2022.04
之前生成的 DSL 代码在包名中编码了 DSL API 版本,例如: jetbrains.buildServer.configs.kotlin.v2019_2
。 那里的 v2019_2
部分对应于引入此 DSL API 时的 TeamCity 版本。
当 DSL API 出现重大不兼容更改时,将引入新的 DSL API 版本。 然而,在 TeamCity 2019.2 之后,没有出现任何不兼容的变更。 因此,几个版本之后的 TeamCity 仍然使用相同的 v2019_2
包名来为新生成的 DSL 代码命名。 由于从 TeamCity 2022.04
开始,缺少不兼容的更改,DSL API 版本被视为多余的,建议执行 切换到没有此版本的包。
升级后启用版本设置
如果您的版本设置存储在 Kotlin 格式中,升级 TeamCity 服务器到较新的版本会使用转换器,自动更新您的 DSL 代码,使其保持功能性。
然而,对于将这些设置存储在 XML 格式中的项目,TeamCity 可能会关闭版本设置功能。 如果服务器升级导致设置 XML 文件发生变化,就会出现这种行为,旨在防止在升级到 TeamCity 服务器的非生产版本时进行不必要的配置更新。
如果您的新版 TeamCity 稳定且您希望继续进行 XML 文件的更新,请点击相应的健康报告操作。 TeamCity 将会将更新后的 XML 配置文件提交给 VCS。 此提交还将包括在版本设置被禁用时通过 TeamCity UI 进行的所有项目配置更新。
Kotlin DSL 升级程序
通常,在服务器升级之后,Kotlin DSL 脚本并不需要任何立即的更改,并应在新版本的 TeamCity 中产生相同的结果。 然而,建议更新 Kotlin DSL 脚本,以使用最新的 configs version。
如果仓库中的 Kotlin DSL 脚本已经更改,而且这些更改不能丢失,那么建议进行手动升级。
手动 DSL 脚本升级:更改配置版本
settings.kts
包含一个所谓的configs version:
这个版本应该更改为 TeamCity 服务器的当前版本。 例如,如果 TeamCity 服务器已升级到 2024.03
,那么应在 settings.kts
中指定 2024.03
。
但在此之前,您应该先查看由您的 TeamCity 服务器在应用 DSL 脚本中最近的更改后产生的健康报告。 这些健康报告描述了在您可以安全更改 configs version 之前,您的 DSL 应该做出哪些更改。
如果您看到类似于以下的信息:
然后,无需对您的 DSL 进行其他更改,您可以将配置的 版本
更改为 2024.03
。 否则,您将收到以下信息:
您应该审阅这些建议,并将它们应用于您的 DSL 脚本。 configs version 只能在应用了所有这些建议后才能更改。
将 DSL 从 2022.05.x 更新至 2023.11.x
附带的 Kotlin 版本已经更新至 1.8.22。
出于安全原因,现有的 AWS 连接现在只能被拥有这些连接的 TeamCity 项目所使用。 子项目无法访问其父项目的连接。 若要允许子项目使用其父项目的 AWS 连接,需要在该连接的设置区块中添加
allowInSubProjects = true
参数。
将 DSL 从 2022.10.x 更新至 2023.05.x
附带的 Kotlin 版本已更新至 1.7.10。
将 DSL 从 2022.04.x 更新为 2022.10.x
针对定向 Bitbucket Server / Data Center 存储库的构建配置的 Pull Requests 构建功能 不再跟踪官方不支持的拉取请求分支(而改为观察源分支)。 要手动切换到以前的(已弃用)行为,请在您的 Pull Requests 功能中添加
usePullRequestBranches = true
参数。 请参阅此 TeamCity Kotlin DSL 文档文章以获取更多信息:PullRequests。
将 DSL 从 2021.2.x 更新到 2022.04.x
附带的 Kotlin 版本已更新至 1.6.21。
引入了包名中没有版本的新 DSL API 工件。 请参阅以下内容,了解如何切换到这些 DSL API 工件。
从 DSL API 包名称中删除版本
从 TeamCity 2022.04 开始,建议您在 DSL 代码中删除导入的版本部分,以使 DSL 代码看起来更简洁,并在 IntelliJ IDEA 中改进代码补全建议。
例如,以下的导入:
可以更改为:
要从导入的包名称中删除 DSL API 版本,应执行以下操作:
更新 pom.xml 文件的
<dependencies/>
部分artifactId
configs-dsl-kotlin
需要更改为configs-dsl-kotlin-latest
并且configs-dsl-kotlin-plugins
应更改为configs-dsl-kotlin-plugins-latest
在最后,
<dependencies/>
部分应该看起来像:
确保 TeamCity 服务器正在运行并处于运行状态。
具有 id
configs-dsl-kotlin-plugins-latest
的工件是由 TeamCity 服务器提供的。 这是同一个 TeamCity 服务器,它在 pom.xml 的<repositories/>
部分中被指定了 idteamcity-server
。 Maven 应该能够下载工件configs-dsl-kotlin-plugins-latest
,因此,这个服务器应该处于启动并运行的状态。在所有的 Kotlin 文件中更改导入。
在所有的 Kotlin 文件中,包名的版本部分应该被移除,例如:
import jetbrains.buildServer.configs.kotlin.v2019_2.*
应替换为:
import jetbrains.buildServer.configs.kotlin.*
编译 DSL 并生成设置。
在对 pom.xml 和 Kotlin 文件进行更改后,建议运行
mvn teamcity-configs:generate
任务,以确保项目仍能编译。 如果没有错误,那么这些更改可以被检入版本设置的存储库中。
将 DSL 从 2021.1.x 更新至 2021.2.x
这次发布没有推出新的 DSL API 包,因此v2019_2仍然是最新的版本。
捆绑的 Kotlin 版本已更新至 1.5.31。
现在支持为大量项目和构建配置设定使用 Typed DSL。 查看完整的改进列表 这里。
将 DSL 从 2020.2.x 更新到 2021.1.x
这次发布没有推出新的 DSL API 包,因此v2019_2仍然是最新的版本。
捆绑的 Kotlin 版本已更新至 1.4.32。
在 Git VCS 根中的
useMirrors
参数已被弃用并被支持以下值的checkoutPolicy
参数取代:AUTO
、USE_MIRRORS
、NO_MIRRORS
、SHALLOW_CLONE
。
项目 DSL 代码中的 Git VCS 根应相应进行更新。 例如,useMirrors=false
应该被替换为checkoutPolicy=NO_MIRRORS
,而useMirrors=true
应该用checkoutPolicy=USE_MIRRORS
替换。 如果在 Git VCS 根目录中未指定useMirrors
,那么应添加checkoutPolicy=USE_MIRRORS
。
关于这些检出策略,您可以在 这里 了解更多。Python 构建步骤中
installToolPackage
字段的默认值已被更改。 自2021.1以来,installToolPackage
默认为true
。 为了保留 Python 构建步骤的当前行为,将installToolPackage = false
添加到构建步骤的设置中。
将 DSL 从 2020.1.x 更新到 2020.2.x
这次发布没有推出新的 DSL API 包,因此v2019_2仍然是最新的版本。
捆绑的 Kotlin 版本已更新至 1.4.21。
将 DSL 从 2019.2.x 更新到 2020.1.x
这次发布没有推出新的 DSL API 包,因此v2019_2仍然是最新的版本。
捆绑的 Kotlin 版本已更新至 1.3.70。
将 DSL 从 2019.1.x 更新至 2019.2.x
捆绑的 Kotlin 版本已更新至 1.3.60。
这个版本引入了新的 DSL API 包:v2019_2。 这个软件包更新了清理规则的 API,并提供了获取 Kotlin DSL 脚本内的 DSL 上下文参数值的功能。
在 DSL 脚本中更新项目报告标签定义
应更改 ReportTab 项目特性的参数:
如果
revisionRuleName
参数的值被设定为lastFinished
、lastSuccessful
或lastPinned
,那么应该移除revisionRuleRevision
参数。如果参数
revisionRuleName
具有buildNumber
值,那么参数revisionRuleRevision
应重命名为revisionRuleBuildNumber
。revisionRuleRevision
参数应重命名为revisionRuleBuildTag
,如果参数revisionRuleName
的值为buildTag
,则应从参数的值中删除后缀.tcbuildtag
。
DslContext.baseDir
自 TeamCity 2019.2 以后,使用 DslContext.baseDir
属性来从 DSL 脚本访问 .teamcity
目录下的文件。 例如:
这是必要的,因为 TeamCity 2019.2 不再保证 DSL 脚本的当前工作目录是 .teamcity
目录。
将 DSL 从 2018.2.x 更新到 2019.1.x
这个版本推出了新的 DSL API 版本,v2019_1,但其包名仍然是 jetbrains.buildServer.configs.kotlin.v2018_2
,因为在 2018.2.x 和 2019.1.x 版本之间,DSL 并没有发生重大变化。
更新 Maven 构建步骤
生成 Maven 构建步骤的 DSL 应进行更新。 如果 Maven 构建步骤没有设置 useOwnLocalRepo
参数为 true
,则应添加以下 localRepoScope
参数:
如果 useOwnLocalRepo
被设置为 true
,那么它应被替换为:
在 MSBuild 和 VS.Solution 构建步骤中添加版本
如果 MSBuild 或 VS.Solution 构建步骤将参数 toolsVersion
设置为 MSBuildStep.MSBuildToolsVersion.V15_0
,应增加额外的 version = MSBuildStep.MSBuildVersion.V15_0
参数:
构建配置参数 buildDefaultBranch 已被弃用
构建配置版本控制设置参数 buildDefaultBranch
已被弃用:应使用 branchFilter
替代。
例如,如果 buildDefaultBranch
被设定为 false
,则应指定以下分支过滤器:
将 DSL 从 2018.1.x 更新到 2018.2.x
这个版本引入了新的 DSL API 版本,v2018_2,它的包为 jetbrains.buildServer.configs.kotlin.v2018_2
。
将 DSL 从 2017.2.x 更新到 2018.1.x
这个版本引入了新的 DSL API 版本,v2018_1,其包是 jetbrains.buildServer.configs.kotlin.v2018_1。 以前的 API 版本仍可使用,如果您不想使用便携式 DSL 脚本,您可以继续使用它们。
更新 Docker 参数
如果您在 TeamCity 2017.2 中使用 Kotlin DSL 进行 Docker 插件的配置,您可能需要对您的 Kotlin 配置脚本进行一些更改,以使您的代码与 TeamCity 2018.1 兼容。
改动的本质:
构建步骤 dockerBuild 现已转换为 dockerCommand
DockerBuild 的参数现在是 commandType 选择器的子参数
请注意下面的区别:
Docker Build 2 Docker 命令迁移
Docker push 命令支持
在 Commit Status Publisher 中向 Gerrit 发布器设置添加标签属性
自 TeamCity 2018.1起,Commit Status Publisher 构建功能的 Gerrit 发布者设置允许自定义反映构建状态的 Gerrit 标签,即您现在可以使用 Verified 以外的内容。
要手动修改 Kotlin DSL 设置,必须按照以下方式添加 label = "Verified" 语句:
将 DSL 从 2017.1.x 更新至 2017.2.x
DSL 版本
这个版本引入了新的 DSL API 版本, v2017_2
。 旧版 API 可以正常运行,如果您不需要新 API 提供的功能,您可以继续使用。
如果您使用了 2017.2 EAPs 并通过用户界面测试更改了 DSL 设置,那么在升级之前,您需要应用所有由 TeamCity 创建的用户界面补丁,因为一些 API 已经以不兼容的方式进行了更改。
由 TeamCity 生成的设置的当前包名为 jetbrains.buildServer.configs.kotlin.v2017_2
。
使用新的 API,您可以从一系列新特性中受益,包括 Kotlin DSL 项目的可编辑管理 UI 和 DSL 文档。 为了在您现有的项目中使用它们,您的 .kt
文件应切换为来自 v2017_2 版本
的包。
为了编译这个项目,您还需要更新您的 pom.xml。 最简单的方法是在您的项目中调用 以 Kotlin 格式下载设置 操作,并从生成的 zip 存档中复制
pom.xml
。 或者您可以自己更新 pom.xml,具体操作如下:将
teamcity.dsl.version
更改为:<teamcity.dsl.version>2017.2</teamcity.dsl.version>
将 kotlin 版本更改为:
<kotlin.version>1.1.4-3</kotlin.version>
并添加对 kotlin-runtime 和 kotlin-reflect 的依赖:
一旦您将项目切换到新的 API 并提交更改,TeamCity 将会检测并应用这些更改,之后将启用网页 UI 编辑。
要在具有现有 pom.xml
的仓库中使用新的 DSL API,必须将 maven 依赖版本更新为 2017.2
。
更新 Docker 参数
如果您在 TeamCity 2017.1 中使用 Kotlin DSL 进行 Docker 插件配置,您可能需要在您的 kotlin 配置脚本中进行一些更改,以使您的代码与 TeamCity 2017.2 兼容。 基本上,TeamCity 提供了一个 Kotlin 配置脚本的转换器,用以自动执行这些更改,但如果由于某种原因无法工作,那么需要手动进行以下更改:
将构建运行程序步骤的名称从 Docker Build 更改为 DockerBuild
将构建运行程序步骤的名称从 Docker Compose 更改为 DockerCompose
将
docker-compose.file
构建参数重命名为dockerCompose.file
从 TeamCity 2017.2 开始,Docker 插件为 Docker 支持 构建功能,容器包装器,Docker 和 Docker Compose 运行器拥有自己的类型 DSL。
Docker Compose 和 Docker Build
Docker 构建功能
命令行运行器配合 Container Wrapper 使用
更新默认项目模板
自2017.2 EAP3以来,TeamCity开始支持项目中的默认模板。 这个设置在 EAP3 和 EAP4 的 "DefaultTemplate" 类型的项目功能中存储,但从 2017.2 RC 版开始,项目配置模式已更新,以适应默认的模板。要手动转换使用默认模版的 DSL 项目配置,您将需要删除对应的项目特性,并如下替换为 defaultTemplate 属性指定:
2017.2 EAP3/4 DSL 项目配置,已配置默认模板:
使用默认模板配置的 2017.2 DSL 项目配置:
更新 .NET CLI 参数
自 2017.2 版本起,TeamCity 开始捆绑 .NET CLI 插件(现在被重新引入为 .NET 运行器)。 如果您在 TeamCity 2017.1.x 中使用 Kotlin DSL 为插件参数,您需要按照以下方式更改命令。 在 TeamCity 2017.1.x 中:
自 TeamCity 2017.2 起,您可以明确指定带参数的构建步骤:
常见参数
2017.1 | 2017.2 | 注释 |
---|---|---|
dotnet-command | dotnet<Command> | 现在,命令名称反映了构建步骤名称,例如 |
dotnet-args | 实参 | |
dotnet-verbosity | 日志记录 |
dotnet build
2017.1 | 2017.2 | 注释 |
---|---|---|
dotnet-paths | 项目 | |
dotnet-build-config | 配置 | |
dotnet-build-framework | 框架 | |
dotnet-build-output | outputDir | |
dotnet-build-runtime | 运行时 | |
dotnet-build-no-deps | - | 应当作为 |
dotnet-build-not-incremental | - | 应当作为 |
dotnet clean
2017.1 | 2017.2 |
---|---|
dotnet-paths | 项目 |
dotnet-clean-config | 配置 |
dotnet-clean-framework | 框架 |
dotnet-clean-output | outputDir |
dotnet-clean-runtime | 运行时 |
dotnet msbuild
2017.1 | 2017.2 |
---|---|
dotnet-paths | 项目 |
dotnet-msbuild-config | 配置 |
dotnet-msbuild-platform | 平台 |
dotnet-msbuild-targets | 目标 |
dotnet-msbuild-runtime | 运行时 |
dotnet nuget delete
2017.1 | 2017.2 |
---|---|
dotnet-nuget-delete-id | packageId |
dotnet-nuget-push-source / dotnet-nuget-delete-source | packageSource |
secure:dotnet-nuget-delete-api-key | apiKey |
dotnet nuget push
2017.1 | 2017.2 | 注释 |
---|---|---|
dotnet-paths | 软件包 | |
dotnet-nuget-push-source | packageSource | |
dotnet-nuget-push-no-symbols | noSymbols | |
secure:dotnet-nuget-push-api-key | outputDir | |
dotnet-build-runtime | apiKey | |
dotnet-nuget-push-no-buffer | - | 应当作为 |
dotnet pack
2017.1 | 2017.2 | 注释 |
---|---|---|
dotnet-paths | 项目 | |
dotnet-pack-config | 配置 | |
dotnet-pack-runtime | 运行时 | |
dotnet-pack-no-build | skipBuild | |
dotnet-pack-output | outputDir | |
dotnet-pack-version-suffix | versionSuffix | |
dotnet-pack-serviceable | - | 应当作为 |
dotnet publish
2017.1 | 2017.2 |
---|---|
dotnet-paths | 项目 |
dotnet-publish-config | 配置 |
dotnet-publish-framework | 框架 |
dotnet-publish-output | outputDir |
dotnet-publish-runtime | 运行时 |
dotnet-publish-version-suffix | versionSuffix |
dotnet restore
2017.1 | 2017.2 | 注释 |
---|---|---|
dotnet-paths | 项目 | |
dotnet-restore-config | configFile | |
dotnet-restore-runtime | 运行时 | |
dotnet-restore-packages | packagesDir | |
dotnet-restore-source | packageSources | |
dotnet-restore-ignore-failed | - | 应当作为 |
dotnet-restore-no-cache | - | 应当作为 |
dotnet-restore-parallel | - | 应当作为 |
dotnet-restore-root-project | - | 应当作为 |
dotnet run
2017.1 | 2017.2 |
---|---|
dotnet-paths | 项目 |
dotnet-run-config | 配置 |
dotnet-run-framework | 框架 |
dotnet-run-runtime | 运行时 |
dotnet test
2017.1 | 2017.2 |
---|---|
dotnet-paths | 项目 |
dotnet-test-config | 配置 |
dotnet-test-framework | 框架 |
dotnet-test-no-build | skipBuild |
dotnet-test-output | outputDir |
dotnet-test-settings-file | settingsFile |
dotnet-test-runtime | 运行时 |
dotnet-test-test-case-filter | 筛选 |
dotnet vstest
2017.1 | 2017.2 | 注释 |
---|---|---|
dotnet-paths | 程序集 | |
dotnet-vstest-config-file | settingsFile | |
dotnet-vstest-framework | 框架 | |
dotnet-vstest-platform | 平台 | |
dotnet-vstest-filter-type | 筛选 | 要按名称筛选测试,使用 |
dotnet-vstest-is-isolation | - | 应当作为 |
将 DSL 从 10.0.x 更新到 2017.1.x
TeamCity 2017.1 没有引入新的 Kotlin DSL API,而是使用了与 TeamCity 10.0.x 相同的包( jetbrains.buildServer.configs.kotlin.v10
)。 新增了几个属性到现有的 API ;为了获取脚本开发的最新 API,更新 teamcity.dsl.version
里的 pom.xml
到 EAP 版本的 2017.1-SNAPSHOT
,以及发布版本的 2017.1
。
需要手动更新 Kotlin DSL 脚本的更改
在启用版本设置之前,应在那些在 TeamCity 升级时被禁用的项目中执行这些更改,其信息为:“由于在 TeamCity 升级过程中修改了设置文件,因此该项目的版本设置已被禁用”。
转换云配置文件
仅在您为根项目设置使用 Kotlin DSL 并且有云配置文件时才相关。
在 2017.1 中,云配置文件从服务器级别移动到了根项目级别。 由于它们未在 Kotlin DSL 中定义,所以如果您启用了版本设置,现有的云配置文件将会从服务器上删除。 因此,在服务器上继续使用 Kotlin DSL 为根项目时,请确保将云配置文件的定义添加到 Kotlin DSL 的根项目设置中。
要使用云配置文件信息更新您的设置,请执行以下操作:
在 Root 项目中运行 'Download settings in Kotlin format' 操作,并将生成的 DSL 保存为压缩文件。
将类型为
CloudIntegration
和CloudProfile
的项目特性从.teamcity/_Root/Project.kt
文件复制到您设置中的根项目配置。将您的更改提交到 VCS。
在 Root 项目的 Versioned Settings 标签页上启用版本设置。
实体中的名称
由于修复了 issue TW-48609,如果您的设置中包含无名实体,TeamCity 将报告相应的 VCS 设置错误。 您需要手动为此类实体设置一个名称参数以解决错误。
将 Kotlin DSL 配置版本从 10.0 更新到 2017.1
这一部分的更改应应用于在将 scripts config version 从 10.0 更改为 2017.1 时的 Kotlin 脚本上。
更新 DotCover 参数
DotCover 使用的参数已经更改,如果您使用它们,请确保 dotNetCoverage.tool
具有 dotcover
值。 如果缺少 dotNetCoverage.dotCover.home.path
参数,请将其设置为 %teamcity.tool.JetBrains.dotCover.CommandLineTools.bundled%
。 结果应该如此:
如果您使用自定义路径(例如, /custom/path
)使用 DotCover,那么结果应该如下所示:
更新 Maven 构建步骤参数
如果您使用的是无原始参数的类型化 maven DSL,那么这个变化应该不会影响您,因为类型化 DSL 会生成最新的设置。
如果您通过 param("name", "value")
方法指定 maven 构建运行程序设置,则需要更新参数。 更新设置的最简单方式是切换到类型化 DSL:您可以生成 Kotlin 格式的设置,以查看 Maven 的类型化 DSL 是什么样子。
如果您想继续使用 param("name", "value")
方法,请按照以下步骤操作:
将
mavenSelection
参数重命名为maven.path
,将其旧值更改为新值:
需要更改的旧值 | 新值 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
移除
maven.home
参数。
更新 PowerShell 构建步骤参数
TeamCity 2017.1 增加了对跨平台 PowerShell 的支持。 以前,PowerShell 构建仅使用桌面版,并且仅在 Windows 上运行。
为确保现有的构建仅限于 PowerShell 的桌面版,您应在现有的 PowerShell 步骤中设置以下属性:
或者如果您使用原始参数: