使用配方

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

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

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

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

什么是公共配方？
公开配方是指那些在 JetBrains Marketplace 上共享的配方。 目前，仅有 JetBrains 手工制作的配方可用。 未来的版本将支持 TeamCity 用户社区共享的配方。

公共配方安全吗？
您可以从 JetBrains Marketplace 手动下载配方 .yml 定义文件，以在将此配方添加到您的配置之前进行查看。 未来的版本将提供更直观的方式来检查配方代码。

我想创建一个配方，我该怎么做？
找到一个现有的或创建一个新的构建配置，该配置执行您希望保存为自定义构建步骤的操作，然后使用 TeamCity UI 中的配置 操作 菜单 提取配方。

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

配方可以编辑吗？
是的，您无需每次更改时重新配置源配置并重新提取配方。 可以在 配方 的 项目设置 页面上 编辑 配方。

创建新配方的最直接方法是从使用所需步骤或步骤序列的现有配置中提取它。 例如，下面的 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"
        }
    }
})

从现有配置中提取配方：

1. 在 配置设置 中，调用 操作 菜单并单击 提取配方。

   

2. 在弹出对话框中，输入配方的内部 ID、公开名称和描述。

3. 单击 提取 创建您的新配方。 您的配方应如下所示：

   <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:'" />
               <!--other parameters-->
           </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>

   note

   默认情况下，配方包括源配置中的所有参数。 您可以删除不必要的参数，并编辑参数 spec 属性以调整在配方页面上的外观和行为： 编辑本地配方。

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

要使配方对整个 TeamCity 服务器可用，请将其配置文件移动到 <TeamCity Data Directory>\config\projects\_Root\pluginData\metaRunners 目录中。 有关更多信息，请参阅 从文件上传配方 部分。

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

1. 打开 配置设置 并导航到 构建步骤 设置选项卡。

2. 单击 添加构建步骤 按钮。

3. 从右侧列中选择一个配方，该列显示：

   • 本项目或其父项目拥有的本地配方；

   • 来自 JetBrains Marketplace 的公开配方。

   

4. 以与常规 TeamCity 步骤相同的方式设置所需的配方设置。

您可以通过 TeamCity 团队在 https://plugins.jetbrains.com/teamcity_recipe 上探索公开配方。 我们希望在未来的发布周期中扩展我们的集合，并欢迎您的想法和反馈。

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

1. 打开 项目设置 并导航到 配方 设置选项卡。

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

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

要从文件安装配方，请使用 TeamCity UI 或将此文件放置到所需目录中。

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

1. 打开 项目设置 并导航到 配方 设置选项卡。

2. 单击 本地配方 表中的配方以查看和编辑其配置文件。

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

<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'" />

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

示例 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>