使用配方

配方是基于一个或多个标准 TeamCity 步骤的自定义构建步骤。如果 TeamCity 的内置步骤缺少所需选项，并且您经常模拟它（例如，使用 CLI 步骤通过云提供商 API 上传构件），您可以将此自定义步骤保存为可重用的配方。

创建配方是开发实现自定义构建步骤的 TeamCity 插件的更简单替代方案。

关键要点

什么是配方？
配方是由以特定方式预设的默认 TeamCity 构建步骤组成的自定义构建步骤。复杂的配方可以包含其他配方作为构建块。

配方的意义是什么？
配方允许您将预先自定义的 TeamCity 构建步骤封装成一个新步骤，可以轻松地跨构建配置共享。

配方和元运行器有什么区别？
在 2025.03 版本中，“meta-runners” 被重命名为“配方”。虽然基于相同的概念，但配方提供了额外的优势，例如 YAML 支持和在 JetBrains Marketplace 上的轻松共享。

我可以继续使用现有的元运行器和 TeamCity Meta-Runner Pack吗？
是的，meta-runners 在新名称下仍然可用，并且不需要手动更新。

什么是公共配方？
公开配方是指那些在 JetBrains Marketplace 上共享的配方。这些包括由 JetBrains 精心制作的配方以及其他 TeamCity 用户分享的配方。

公共配方安全吗？
是的，所有发布在 JetBrains Marketplace 上的配方都经过我们员工的验证。您始终可以在安装之前，在 Marketplace 或直接在 TeamCity UI 中检查源配方代码。

我想创建一个配方，我该怎么做？
找到一个现有的或创建一个新的构建配置，该配置执行您希望保存为自定义构建步骤的操作，然后使用 TeamCity UI 中的配置操作菜单提取配方。这样做可以让您保存一个 XML 配方。要创建一个 YAML 配方，您需要从头编写其定义。检查公共 Marketplace 配方的源代码，并查看配方 YAML 语法文章以了解更多信息。

如何使用配方？
以与使用常规构建步骤相同的方式：将它们添加到配置的“构建步骤”列表中。

配方可以编辑吗？
是的，您无需每次更改时重新配置源配置并重新提取配方。私有配方可以在配方的项目设置页面上编辑。公共配方由外部方创建，无法直接编辑。

从构建配置中提取配方

创建新配方的最直接方法是从使用所需步骤或步骤序列的现有配置中提取它。例如，下面的 Kotlin DSL 示例显示了一个具有两个 CLI 构建步骤的构建配置：一个使用 cURL 下载文件，另一个运行 ls 列出工作目录内容。

import jetbrains.buildServer.configs.kotlin.*

object SourceConfiguration : BuildType({
    name = "Source Configuration"
    
    params {
        param("URL", "")
        param("fileName", "")
    }
    
    steps {
        script {
            id = "simpleRunner"
            scriptContent = "curl -o %URL% %fileName%"
        }
        script {
            id = "simpleRunner_1"
            scriptContent = "ls"
        }
    }
})

  

从现有配置中提取配方：

在配置设置中，调用操作菜单并点击提取配方。
在弹出对话框中，输入配方的内部 ID、公开名称和描述。配方会在添加构建步骤页面上显示这些字符串。
点击提取创建您的新配方。您的配方应如下所示：
<meta-runner name="cURL: File Download"> <description>A two-step recipe that utilizes the "curl -o %URL% %fileName%" command to download a file, and calls "ls" command to print the contents of a working directory afterwards</description> <settings> <parameters> <param name="URL" value="" spec="text description='The URL of a file to be downloaded' display='normal' label='Download URL:'"/> <param name="fileName" value="" spec="text description='Enter the saved file name or leave blank to keep the origin name' label='File name:'" />  </parameters> <build-runners> <runner name="" type="simpleRunner"> <parameters> <param name="script.content" value="curl -o %URL% %fileName%" /> <param name="teamcity.step.mode" value="default" /> <param name="use.custom.script" value="true" /> </parameters> </runner> <runner name="" type="simpleRunner"> <parameters> <param name="script.content" value="ls" /> <param name="teamcity.step.mode" value="default" /> <param name="use.custom.script" value="true" /> </parameters> </runner> </build-runners> <requirements /> </settings> </meta-runner>
默认情况下，配方包括源配置中的所有参数。您可以删除不必要的参数，并编辑参数 spec 属性以调整在配方页面上的外观和行为：编辑私有配方。

配方被保存到 <TeamCity Data Directory>\config\projects\<project_ID>\pluginData\metaRunners 目录中。它们归属于使用其配置作为来源的项目。因此，配方默认仅对其原始项目及其子项目可用。

使用配方

配方是自定义构建步骤，因此以相同的方式添加到构建配置中。

打开配置设置并导航到 构建步骤 设置选项卡。
点击添加构建步骤按钮。
从右侧列中选择一个配方，该列显示：
- 此项目或其父项目拥有的私有配方；
- 来自 JetBrains Marketplace 的公开配方。
以与常规 TeamCity 步骤相同的方式设置所需的配方设置。

您可以在 https://plugins.jetbrains.com/teamcity_recipe 上探索由 TeamCity 开发者和其他 TeamCity 用户创建的公共配方。我们希望在未来的发布周期中扩展我们的集合，并欢迎您的想法和反馈。

如果您未看到任何 Marketplace 配方选项，请验证它们是否已为您的项目启用：

打开项目设置并导航到配方设置选项卡。
将 JetBrains 公共 Marketplace 配方设置切换为“启用”。如果此设置为“禁用”且呈灰色，请编辑强制此行为的父项目的设置或与管理此项目的人联系。

从文件上传配方

如果您有一个配方的 .xml 定义文件，您可以手动将此文件上传到所需的项目。例如，您可能希望将配方从一个项目移动到另一个项目，或从 JetBrains Marketplace 手动下载配方。

要从文件安装配方，请执行以下操作：

打开项目设置并导航到配方设置选项卡。
点击 上传配方 按钮。
选择一个配置文件并输入一个唯一的配方名称。
点击 Save。您上传的配方现在可用于此项目及其子项目的所有配置。

管理现有配方

配方项目设置页面允许您：

为此项目及其所有子项目启用或禁用公共（基于 Marketplace 的）配方；
检查此项目中使用的所有公共和私有配方：查看其使用情况并发现任何问题。

您可以为根项目打开此页面以查看服务器范围的使用报告。配方标签会通知您是否有新版本的配方可用、当前版本或整个配方是否已不再在 Marketplace 上可用，或者 TeamCity 无法联系 JetBrains Marketplace 并检索配方数据。

您可以在 JetBrains Marketplace 上与 TeamCity 社区分享基于 YAML 的配方。有关更多信息，请参阅此文章：上传 TeamCity 配方。

编辑私有配方

从构建配置中提取或从文件上传的配方存储在您的服务器机器上，并可以在 TeamCity UI 中编辑。

打开项目设置并导航到配方设置选项卡。
一个用于查看和编辑其配置文件的私有配方。

例如，从现有配置中提取的配方会复制此配置中的所有参数。您可以删除与配方实际执行的构建步骤无关的参数。

XML 参数规范

XML 配方参数规范具有 spec="type attribute='value' 格式。您可以编辑此规范以修改参数/编辑器的外观和行为设置。

<parameters>
    <param name="internalName" value="" spec="type attribute1='value1' attribute2='value2'/>
</parameters>

   

例如：

# Checkbox parameter
<param name="enabled" value="" spec="checkbox checkedValue='true' uncheckedValue='false' label='Enable debug' description='Tick this setting to run in debug mode'"/>

# Select parameter
<param name="logBehavior" value="" spec="select data_1='All' data_2='Errors only' data_3='Errors and warnings' label='Logging verbosity:' description='Choose whether only critical or all messages should be logged'"/>

# Prompt parameter that cannot have an empty value
<param name="tag" value="default" spec="text description='This value cannot be empty' label='Tag: ' validationMode='not_empty' display='prompt'" />

   

配方自主性

配方被设计为在整个构建配置中重复使用，因此应与配置无关。这意味着您的配方应理想地执行可以独立于其他配置设置运行的操作。

此外，配方与其原始构建步骤具有相同的项目要求。您可以选择跨平台的构建步骤（如命令行或 Kotlin 脚本）作为配方的基础，以使其与尽可能多的构建代理兼容。

示例 1：VCS 根

VCS Roots 不会嵌入到配方配置文件中。因此，如果您创建一个对存储库文件和文件夹执行操作的配方，没有合适 VCS Roots 的配置将会失败。如果您需要这样的配方，请执行以下操作：

转到导入配方的构建配置的设置。
切换到版本控制设置选项卡。
点击附加 VCS 根按钮。
在附加现有 VCS 根中选择与您的原始配置使用相同的根。
点击页面底部的保存并运行您的构建配置。由于现在已经与 VCS 仓库建立了连接，构建步骤可以访问所需的文件，并能够成功完成。

示例 2：构建文件

Gradle、 Maven、 Ant 和其他构建步骤处理诸如 build.xml 或 pom.xml 的构建文件。如果您的自定义配方包含这样的步骤，请确保导入的构建配置能够定位所需文件以避免失败。

允许直接定义构建文件而不仅仅是指定路径的构建步骤特别适合用于配方。例如， Ant 构建步骤。

在容器中启动配方

组成配方的单个构建步骤具有允许 TeamCity 在 Docker/Podman 容器中运行这些步骤的设置。相同的设置也适用于配方本身。

如果您希望所有步骤都在所需的容器中执行，请在配方级别设置所需的镜像。单个步骤的容器设置优先于这些配方设置，并允许您在每个步骤中运行其独特的容器。

Kotlin 示例的配方在 "ubuntu" Linux 容器中运行其步骤：

object Build : BuildType({
    steps {
        step {
            id = "SimpleMetaRunner"
            type = "idSimpleMetaRunner"
            executionMode = BuildStep.ExecutionMode.DEFAULT
            param("plugin.docker.imageId", "ubuntu")
            param("plugin.docker.imagePlatform", "linux")
            param("plugin.docker.pull.enabled", "true")
            param("plugin.docker.run.parameters", "")
        }
    }
})

  

此配方的 XML 标记如下所示。步骤 #1 在 python:3.9.20-bullseye 容器中运行。步骤 #2 没有单独的容器设置，并在上述 Kotlin 代码中定义的 ubuntu 容器中运行。

<meta-runner name="SimpleMetaRunner">
    <description>A Py/CLI sample recipe</description>
    <settings>
        <parameters/>
        <build-runners>
            <runner name="Py" type="python-runner">
                <parameters>
                    <param name="plugin.docker.imageId" value="python:3.9.20-bullseye" />
                    <!-- Python step parameters -->
                </parameters>
            </runner>
            <runner name="" type="simpleRunner">
                <parameters>
                    <!-- CLI step parameters -->
                </parameters>
            </runner>
        </build-runners>
        <requirements />
    </settings>
</meta-runner>

  

最后修改日期： 2025年 9月 3日

使用配方

关键要点

从构建配置中提取配方

使用配方

从文件上传配方

管理现有配方

在 Marketplace 上分享配方

编辑私有配方

XML 参数规范

配方自主性

示例 1：VCS 根

示例 2：构建文件

在容器中启动配方