服务消息

服务消息支持两种格式：

• 单属性消息：

  ##teamcity[<messageName> 'value']

• 多属性信息：

  ##teamcity[<messageName> name1='value1' name2='value2']

  多属性消息可以更正式地描述为：

  ##teamcity[messageNameWSPpropertyNameOWSP=OWSP'value'WSPpropertyName_IDOWSP=OWSP'value'...OWSP]

where:

• messageName 是消息的名称，例如 flowStarted 或 setParameter。

• propertyName 是消息属性的名称。 必须是有效的 Java ID。

• 值 是属性的值。 必须是一个 escaped value。

• WSP 是必需的空格：空格或制表符（\t）。

• OWSP 是一个可选的空格。

• ... 是任何数量的 WSPpropertyNameOWSP=OWSP'value' 块。

对于转义值，TeamCity 使用竖线 | 作为转义字符。 为了让 TeamCity 服务器正确解释某些特殊字符，它们必须以竖线开始。 例如，以下信息：

##teamcity[testStarted name='foo|'s test']

将在 TeamCity 中显示为 foo 的测试。 请参考下面的转义值表格。

您可以按照以下方式向构建日志报告消息：

##teamcity[message text='<message text>' errorDetails='<error details>' status='<status value>']

where:

• 状态 可以取以下值： 正常 （默认）， 警告， 失败， 错误。

• errorDetails 仅在 状态 为 错误 时使用，在其他情况下会被忽略。
  如果此消息的状态为 错误 ，并且在构建配置的 构建失败条件 页面上勾选了“ 如果构建运行器记录了错误消息则失败构建 ”框，则此消息会导致构建失败。 例如：

  ##teamcity[message text='Exception text' errorDetails='stack trace' status='ERROR']

tip

如果您希望控制何时构建失败，可以配置 失败条件 ，或者发送包含 构建问题的特殊消息。

##teamcity[blockOpened name='<blockName>' description='<this is the description of blockName>']

##teamcity[blockClosed name='<blockName>']

##teamcity[compilationStarted compiler='<compiler_name>']
...
##teamcity[message text='compiler output']
##teamcity[message text='compiler output']
##teamcity[message text='compiler error' status='ERROR']
...
##teamcity[compilationFinished compiler='<compiler name>']

消息 FlowId

任何消息都支持可选属性 flowId ，该属性允许您将消息分组到不同的类别（流）中。 例如，由于每条消息都是按照发送顺序处理的，因此以下示例将生成一个块层次结构，其中两个输出消息都归最新块所有：

##teamcity[blockOpened name='block 1']
##teamcity[blockOpened name='block 2']
##teamcity[message text='Message 1']
##teamcity[message text='Message 2']

添加 flowId 属性可以让您将消息分成两个并行的流程。

##teamcity[blockOpened name='block 1' flowId='1']
##teamcity[blockOpened name='block 2' flowId='2']
##teamcity[message text='Message 1' flowId='1']
##teamcity[message text='Message 2' flowId='2']

在大多数情况下， flowId 是启动消息流程所需的唯一属性。 在 嵌套测试报告 中，您可能希望在现有的流中作为子流启动，而不是在根流中启动。 要做到这一点，请添加 flowStarted 参数并将父流 ID 指定为 父项 参数。 未指定父级的流将在当前步骤的根流内开始。

要结束一个子流，请使用 flowFinished 参数。 结束一个父流程会自动关闭所有的子流程，但我们建议明确声明流程的顺序：

##teamcity[flowStarted flowId='MainFlow' ...]
##teamcity[flowStarted flowId='SubFlow1' parent='MainFlow' ...]
##teamcity[flowFinished flowId='SubFlow1' ...]
##teamcity[flowStarted flowId='SubFlow2' parent='MainFlow' ...]
##teamcity[flowFinished flowId='SubFlow2' ...]
##teamcity[flowFinished flowId='MainFlow' ...]

请注意， flowStarted 和 flowFinished 消息仅在出现在 testStarted 和 testFinished 消息之间时有效。

##teamcity[<messageName> timestamp='timestamp' ...]

##teamcity[<messageName> timestamp='2008-09-03T14:02:34.487+0400' ...]
##teamcity[<messageName> timestamp='2008-09-03T14:02:34.487' ...]

var date = DateTimeOffset.Now;
var timestamp = $"{date:yyyy-MM-dd'T'HH:mm:ss.fff}{date.Offset.Ticks:+;-;}{date.Offset:hhmm}";

##teamcity[<messageName> timestamp='2008-09-03T14:02:34.487+0400' ...]

##teamcity[testSuiteStarted name='suiteName']
<individual test messages go here>
##teamcity[testSuiteFinished name='suiteName']

##teamcity[testStarted name='testName' captureStandardOutput='<true/false>']
<here go all the test service messages with the same name>
##teamcity[testFinished name='testName' duration='<test_duration_in_milliseconds>']

##teamcity[testIgnored name='testName' message='ignore comment']

##teamcity[testStarted name='className.testName']
##teamcity[testStdOut name='className.testName' out='text']
##teamcity[testStdErr name='className.testName' out='error text']
##teamcity[testFinished name='className.testName' duration='50']

##teamcity[testStarted name='MyTest.test1']
##teamcity[testFailed name='MyTest.test1' message='failure message' details='message and stack trace']
##teamcity[testFinished name='MyTest.test1']

##teamcity[testStarted name='MyTest.test2']
##teamcity[testFailed type='comparisonFailure' name='MyTest.test2' message='failure message' details='message and stack trace' expected='expected value' actual='actual value']
##teamcity[testFinished name='MyTest.test2']

##teamcity[testSuiteStarted name='suiteName']
##teamcity[testSuiteStarted name='nestedSuiteName']
##teamcity[testStarted name='package_or_namespace.ClassName.TestName']
##teamcity[testFailed name='package_or_namespace.ClassName.TestName' message='The number must be 20000' details='junit.framework.AssertionFailedError: expected:<20000> but was:<10000>|n|r    at junit.framework.Assert.fail(Assert.java:47)|n|r    at junit.framework.Assert.failNotEquals(Assert.java:280)|n|r...']
##teamcity[testFinished name='package_or_namespace.ClassName.TestName']
##teamcity[testSuiteFinished name='nestedSuiteName']
##teamcity[testSuiteFinished name='suiteName']

##teamcity[testRetrySupport enabled=’true’]

Integration Tests: Backend: org.jetbrains.teamcity.LoginPageController.testBadPassword("incorrect password", false)

// in the example above,
// suite name = "Integration Tests: Backend"
// package = org.jetbrains.teamcity
// class name = LoginPageController
// test method = testBadPassword
// test parameters = ("incorrect password", false)

##teamcity[inspectionType id='<id>' name='<name>' description='<description>' category='<category>']

<html>
    <body>
    Reports unnecessary local variables, which add nothing to the comprehensibility of a method. Variables caught include local variables which are immediately returned, local variables that are immediately assigned to another variable and then not used, and local variables which always have the same value as another
    local variable or parameter.
    <!-- tooltip end -->
        <p>
        Use the first checkbox below to have this inspection ignore variables which are immediately returned or thrown. Some coding styles suggest using such variables for clarity and ease of debugging.
        </p>
        <p>
        Use the second checkbox below to have this inspection ignore variables which are annotated.
        </p>
    </body>
</html>

##teamcity[inspection typeId='<inspection type identity>' message='<instance description>' file='<file path>' line='<line>' additional attribute='<additional attribute>']

##teamcity[inspectionType id='UnnecessaryLocalVariable' name='Redundant local variable' description='<html><body>Reports unnecessary local variables...</body>
</html>' category='Data flow issues']
##teamcity[inspection typeId='UnnecessaryLocalVariable' message='Local variable <code>i</code> is redundant' file='src/Test.java' line='19' SEVERITY='WARNING']

##teamcity[publishArtifacts '<path>']

##teamcity[progressMessage '<message>']

##teamcity[progressStart '<message>']
...some build activity...
##teamcity[progressFinish '<message>']

##teamcity[buildProblem description='<description>' identity='<identity>']

报告构建状态

使用 buildStatus 设置 构建状态文本。

##teamcity[buildStatus text='NuGet packages were successfully published.']

与设计用于反映构建状态中当前正在进行的操作的 进度消息 不同， buildStatus 消息设定了构建完成后持久存在的最终构建状态。

您可以添加单独的步骤，并使用不同的 步骤执行条件来区分"绿色"构建和失败的构建，并为它们每一个设置不同的自定义状态。

steps {
    // ...
    script {
        id = "set-custom-green-text"
        scriptContent = """echo "##teamcity[buildStatus text='NuGet packages were successfully published.']""""
    }

    script {
        id = "set-custom-red-text"
        executionMode = BuildStep.ExecutionMode.RUN_ONLY_ON_FAILURE
        scriptContent = """echo "##teamcity[buildStatus text='Build failed! NuGet packages were not updated.']""""
    }
}

默认状态文本可以通过 {build.status.text} 占位符进行引用。

##teamcity[buildStatus text='The default status of this build is: {build.status.text}']

状态参数

状态 参数是 buildStatus 服务消息的可选项，允许您覆盖构建的显示：将失败的构建描述为成功，甚至（并不推荐）将成功的构建描述为失败。

• 要将构建的状态从失败更改为成功，请添加 status='SUCCESS' 参数。

  ##teamcity[buildStatus status='SUCCESS' text='{build.status.text}, the build is marked as successful']

  

• 如果您希望一个 "green" 构建显示为失败，您可以发送以下消息：

  ##teamcity[buildStatus status='FAILURE' text='The build status was manually switched to {build.status.text}']

  然而，由于这只改变了构建状态，而没有为任何正在调查这个“失败”的构建的人提供任何可行的见解，我们建议您发送 buildProblem 消息作为替代。 这条信息允许您真正地使构建失败（并提供与此问题相关的具体细节），而不仅仅是更改最终状态。 因此，项目维护者将能够使用 TeamCity 提供的各种工具来解决问题：调查，静音等等。

  ##teamcity[buildProblem description='The artifact size has decreased dramatically' identity='2281488']

##teamcity[buildNumber '<new build number>']

##teamcity[buildNumber '1.2.3_{build.number}-ent']

##teamcity[setParameter name='ddd' value='fff']

##teamcity[buildStatisticValue key='<valueTypeKey>' value='<value>']

##teamcity[enableServiceMessages]
##teamcity[disableServiceMessages]

##teamcity[importData type='typeID' path='<path to the xml file>']

发送以下服务消息以开始跟踪文件的内容，并将其新行写入构建日志。

##teamcity[importData type='streamToBuildLog' filePath='path-to-file' wrapFileContentInBlock='false' charset='UTF-8']

• 类型 — 始终等于 'streamToBuildLog'。

• filePath — 指向特定文件的路径。 这个路径可以是绝对的（filePath='%teamcity.build.checkoutDir%/temp.txt' ）或相对的（filePath='./myFolder/temp.txt'）。 相对路径是根据运行构建的代理的当前工作目录（由 teamcity.agent.work.dir 参数 返回的目录）来解析的。 如果指定的文件不存在或无法打开，TeamCity 将周期性地尝试访问此文件（只要发送此服务消息的 runner 仍在运行）。

• wrapFileContentInBlock （可选）—— 指定此消息的输出是否应放置在可折叠的 "Streaming file..." 块中。 默认值为 "true"。

  

• 字符集 （可选）- 是 Java 支持的编码的规范名称或别名。 如果参数不存在或无法解析编码，将使用 UTF-8。

只要父运行器处于活动状态，TeamCity就会监视给定的文件。 当运行器停止时，文件将一直流到结束并关闭。

您可以使用 TeamCity 服务消息来发送 Slack 直接消息并在 Slack 频道中发布更新。

TeamCity 通过 Slack 连接 来发送 Slack 消息。 如果您尚未有 Slack 连接，请转到 项目设置 | 连接 并创建一个。

1. 打开 Slack 连接的设置，并将 通知限制 设置为任意正数。 此值指定了构建配置每次运行可以发送的消息的最大数量。

2. 出于安全原因，只允许在消息中添加指向同一 TeamCity 服务器的链接。 带有指向外部网络资源的 URL 的消息会被自动阻止，并在 "teamcity-notifications.log" 文件中写入相应的消息（管理 | 诊断 | 服务器日志）。

   

   如果您需要包含指向外部资源的链接，请在 允许的主机名 字段中输入它们的主机名。 使用逗号（,）作为分隔符输入多个值，使用星号（*）作为任意字符串的通配符（例如，*.test.co.uk）。

3. 一旦配置了 Slack 连接，您可以按照以下格式在构建脚本中添加服务消息：

   ##teamcity[notification notifier='slack' message='Line 1 |rLine2 |rLine3' sendTo='build_farm_alerts' connectionId='PROJECT_EXT_2']

   • notifier（通知程序） — 始终等于 "slack"。

   • 消息 — 显示的信息。 支持 Markdown 语法（除了用于换行的 "\n"，请使用 "|n" 或 "|r" 作为替代）。

     

   • sendTo — 指定谁应接收此消息。 接受单个 Slack 频道名称、频道 ID（以 "C" 开头，例如 "C052UHDRZU7"）或用户 ID（以 "U" 开头，例如 "U02K2UVKJP7"）作为值。 如果您需要向多个收件人发送相同的信息，请创建带有不同 sendTo 值的多个服务消息。

   • connectionID — 这是一个可选参数，允许您选择 TeamCity 应该用来发送此消息的特定 Slack 连接。 接受连接 ID 作为值。 如果未指定此参数，TeamCity 将检索当前项目可用的所有 Slack 连接，并选择其 通知限制 不为零的连接。

     tip

     快速获取目标 Slack 连接 的 ID：

     1. 打开 项目设置并导航到 连接设置选项卡。

     2. 从概览表中复制一个连接 ID。

        

4. 运行构建以确保所有 Slack 消息都已发送。

您可以使用 TeamCity 服务消息从构建脚本内部发送电子邮件。

1. 导航到 管理 | 邮件通知器 并设置常见的 通知器 设置：发件人的电子邮件、SMTP 登录名和密码、连接安全协议等。 参见此链接以获取示例： 设置 Google 邮箱作为通知服务器。

2. 将 通知限制 设置为任意正数。 此值指定了构建配置每次运行可以发送的消息的最大数量。

3. 在 允许的地址 中输入收件人列表。 向此列表外的收件人发送的消息将被自动阻止。 使用逗号（,）作为分隔符来输入多个地址，以及使用星号（*）作为通配符来替代任何字符串（例如，*@gmail.com）。

4. 出于安全原因，只允许在消息中添加指向同一 TeamCity 服务器的链接。 带有指向外部网络资源的 URL 的消息会被自动阻止，并在 "teamcity-notifications.log" 文件中写入相应的消息（管理 | 诊断 | 服务器日志）。

   

   如果您需要包含指向外部资源的链接，请在 允许的主机名 字段中输入它们的主机名。 使用逗号（,）作为分隔符输入多个值，使用星号（*）作为任意字符串的通配符（例如，*.test.co.uk）。

5. 一旦设置了电子邮件通知程序，您可以按照以下格式向构建脚本中添加服务消息：

   ##teamcity[notification notifier='email' message='Message body' subject='Email subject' address='user1@gmail.com,user2@yourcompany.com']

   • notifier（通知程序） — 总是等于 "email"。

   • 消息 — 这是以纯文本格式显示的消息主体。

   • subject — 这是电子邮件的主题。

   • 地址 — 来自 允许的地址 的电子邮件通知器列表中的一个或多个地址。

6. 运行构建以确保所有电子邮件都被送达。

如果您需要从脚本中取消构建，例如，由于环境原因无法正常进行构建，或者应从子进程中取消构建，您可以使用以下的服务消息：

echo "##teamcity[buildStop comment='canceling comment' readdToQueue='true']"

如有必要，您可以在取消后重新将构建添加到队列中。 默认情况下，TeamCity 将尝试 3 次将构建重新加入队列。

可以通过从前置（上游）配置发送 skipQueuedBuilds 消息来取消下游链构建。 此消息接受您希望跳过的配置的 ID 或标签作为 标记 参数。

##teamcity[skipQueuedBuilds tags='value1,value2,...' comment='Your comment']

有关取消构建链中链接的构建的更多信息，请参阅 部分链执行 文章。

服务消息允许您添加和删除 build tags。

• ##teamcity[addBuildTag 'your-custom-tag'] — 在当前构建中添加新的标签。

• ##teamcity[removeBuildTag 'tag-to-remove'] — 从当前构建中删除一个标签。

两种消息都让您可以传递 配置参数 的值，而非纯文本字符串。 例如， ##teamcity[addBuildTag '%teamcity.agent.jvm.os.name%'] 消息标签会与安装在代理机器上的操作系统的名称一起构建。

一条服务消息可以添加或删除一个标签。 要添加或删除多个标签，发送多个服务消息。

几个来自 JetBrains 和外部资源的特定平台库能够通过 TeamCity 服务消息报告结果。

• Service messages .NET 库 — 用于从 .NET 应用程序生成 （和解析）TeamCity 服务消息的 .NET 库。 请查看一篇 相关博客文章。

• Jasmine 2.0 TeamCity reporter—— 支持从 Jasmine 2.0 报告器发出 TeamCity 服务信息

• Perl TAP Formatter—— 这是一个用于将 TAP 消息转换为 TeamCity 服务消息的 Perl 格式化程序

• PHPUnit 5.0 — 支持 TeamCity 服务消息进行测试。 对于早期的 PHPUnit 版本，可以使用以下外部库： PHPUnit Listener 1， PHPUnit Listener 2—— 这些监听器可以通过 PHPUnit 的 suite.xml 插入，为测试生成 TeamCity 服务消息。

• Python 单元测试报告发送至 TeamCity—— 这是一个自动将单元测试报告发送至 TeamCity 服务器的包，通过服务消息 (当在 TeamCity 下运行并且提供的测试代码已适应使用它)。

• Mocha — 通过服务消息进行即时汇报，供 Mocha JavaScript 测试框架使用。 查看相关的 帖子 ，其中有操作指导。

• Karma—— 是 JavaScript 测试工具中的一个支持，用于利用 TeamCity 服务消息向 TeamCity 报告测试进度。

个人构建 在处理 Perforce 项目 时，可能会在最终的“撤销个人更改”阶段失败。 如果代码源检出目录在此阶段开始之前变得不可用（例如，当它由 引导构建步骤 挂载并在最后一个构建步骤后自动卸载时），通常会发生这种情况。

在这种情况下，您必须比 TeamCity 通常的操作更早撤销个人更改——在构建步骤仍在运行时。 为此，请在最终构建步骤期间发送以下 服务消息：

##teamcity[undoPersonalPatch]