TeamCity Service Messages Library for .NET

Eugene Petrenko

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

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.

Subscribe to TeamCity Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!