FYI Tips & Tricks

TeamCity Service Messages Library for .NET

TeamCity uses Service Messages to provide an easy API to allow for build scripts integration, i.e. the build providing status reports, artifacts publishing, test reporting, etc. A Service Message has the following format:

##teamcity[hello message=’teamcity’ version=’6.5.x’ comment=’awesome’]

Service Messages introduce a communication protocol for data exchanges  between processes using streams, sockets, HTTP or pipes.

I’ve created a wrapper to allow for easier interaction with TeamCity Service Messages, providing it as a package available on NuGet.


PM> Install-Package TeamCity.ServiceMessages

The library contains two main classes. One for reading and one for writing service messages.

Reading service messages

Reading service messages can be done using a TextReader or string with minimal memory requirements:

  using JetBrains.TeamCity.ServiceMessages.Read;
  var parser = new ServiceMessageParser();
  using(TextReader reader = ... ) {
     foreach(var message in parser.ParseServiceMessages(reader)) {
        /// process IServiceMessage object

Parse method gives us an IEnumerable of IServiceMessage:

  public interface IServiceMessage
    string Name { get; }
    string DefaultValue { get; }
    IEnumerable<string> Keys { get; }
    string GetValue([NotNull] string key);

The Name is the name of service message, i.e. ‘name’ in ##teamcity[name‘aaa’].
The DefaultValue contains simple value, i.e. ‘value’ for ##teamcity[name ‘value‘] or null for service message with attributes, i.e. ##teamcity[name tea=’hot’ ice=’cold’]. To access service message attributes use Keys property and GetValue method.

Writing service messages

To create a service message you may use anonymous type for service message attributes:

using JetBrains.TeamCity.ServiceMessages.Write;
string serializedMessage
  = new ServiceMessageFormatter().FormatMessage(
        new {
          Version = "3.2.2",
          Mode = "zoom"
/// returns:  ##teamcity[rulez Version='3.2.2' Mode='zoom']

The previous is the simplest way for creating service messages, although you may use a strongly typed approach:

using JetBrains.TeamCity.ServiceMessages.Write;
string serializedMessage
  = new ServiceMessageFormatter().FormatMessage(
        new ServiceMessageProperty("Apple", "239"),
        new ServiceMessageProperty("Pie", "42")


The source code for the project is available on GitHub and the build is at TeamCity.CodeBetter.Com and with TeamCity support for NuGet, it automatically publishes the library as NuGet package on For a full description of the format and usages of Service Messages see the Build Script Integration with TeamCity article.

Comments below can no longer be edited.

2 Responses to TeamCity Service Messages Library for .NET

  1. Avatar

    Simone says:

    October 24, 2011

    Hi Eugene, sorry if I’m missing something, but what would I use this for?

  2. Avatar

    Eugene says:

    October 25, 2011

    Thank you for question. It is a good question and I mostly expect it would be asked.

    What this library to, actually is formatting and reading of service messages. Actually, this involves escaping for some symbols as described at On that documentation page you find listing of service messages that TeamCity supports.

    In future, I plan to add some TeamCity specific classes to provide higher level API for build script integration.

    For example, you may consider using this library to report tests or publishes build artifacts.

Discover more