服务消息

服务消息格式

服务消息支持两种格式：

• 单属性消息：

  ##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 中显示为 foo 的测试。 请参考下面的转义值表格。

向构建日志报告消息

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

where:

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

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

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

报告构建状态

使用 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']

将文件写入构建日志

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

• 类型 — 始终等于 '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就会监视给定的文件。 当运行器停止时，文件将一直流到结束并关闭。

发送自定义 Slack 消息

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

TeamCity 通过 Slack 连接 来发送 Slack 消息。 如果您还没有创建 Slack 连接，请转到 Administration | Project Settings | Connections 并创建一个。

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

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

   

   如果您需要包含指向外部资源的链接，请在 允许的主机名 字段中输入它们的主机名。 使用逗号（,）作为分隔符输入多个值，使用星号（*）作为任意字符串的通配符（例如，*.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 连接，并选择 通知限制 不为零的那一个。

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

发送自定义电子邮件消息

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

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

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

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

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

   

   如果您需要包含指向外部资源的链接，请在 允许的主机名 字段中输入它们的主机名。 使用逗号（,）作为分隔符输入多个值，使用星号（*）作为任意字符串的通配符（例如，*.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. 运行构建以确保所有电子邮件都被送达。

通过服务消息取消构建

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

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

添加和删除构建标签

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

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

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

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

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

通过 TeamCity 服务消息报告库结果

几个来自 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 报告测试进度。