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.

Usage

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
  {
    [NotNull]
    string Name { get; }
    [CanBeNull]
    string DefaultValue { get; }
    IEnumerable<string> Keys { get; }
    [CanBeNull]
    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(
        "rulez",
        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(
        "rulez",
        new ServiceMessageProperty("Apple", "239"),
        new ServiceMessageProperty("Pie", "42")
  ));
...

Summary

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 NuGet.org. For a full description of the format and usages of Service Messages see the Build Script Integration with TeamCity article.

image description

Discover more