Support for immutable messages

I’d like to suggest that NServiceBus supports immutable messages. I’ve been asking around a bit, and it looks like something that may be enabled by certain community packages, but right now I’m working with a customer who’s new to NServiceBus, and while they like it a lot, I don’t think it’s a good idea to lead them off the beaten path yet.

Besides, this is a feature or capability that would, I believe, be generally beneficial, although I by no means suggest that this is made mandatory.

Let me explain first what I’d like to have, and afterwards, why it’s a good idea.


Currently, messages are defined as dumb DTOs like this:

public class ReserveTable : ICommand, IMessage
    public Guid Id { get; set; }
    public DateTime Time { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public int Quantity { get; set; }

(Please accept my apologies if the code doesn’t compile; I’m writing this without IDE assistance.)

It’s easy to define message types like that, but writing code that consumes such a type is bothersome because of non-existing invariants.

Such a design causes several problems. I’ll outline some later in this post.

Feature description

I’d like to be able to instead define messages as immutable records, like this:

public class ReserveTable : ICommand, IMessage
    public ReserveTable(Guid id, DateTime time, string name, string email, int quantity)
        // Initialise all properties with constructor arguments here...

    public Guid Id { get; }
    public DateTime Time { get; }
    public string Name { get; }
    public string Email { get; }
    public int Quantity { get; }

    public override Equals // ...
    public override GetHashCode // ...

Yes, that’s clearly more work when defining the message types, but it makes consuming messages, including unit testing, much simpler. It’s a trade-off I’d make every time, if enabled.

Problems with mutable messages

A mutable message is conceptually wrong. This is particularly clear for events. With mutable messages (the current design) a message handler could easily change one or more properties on the message it handles. That’s odd when the message represents an event that has already happened.

Additionally, messages carry no invariants. Properties can be null, even when conceptually required. This leads to much defensive coding that could otherwise be avoided.

Problems related to unit testing

A common pattern when unit testing is the Test Data Builder design pattern. This enables you to write tests that only explicitly state those things that are important for a test case.

Imagine writing a unit test for a mutable ReserveTable command. In this test case, Name and Email aren’t important. They could be anything, because they don’t impact the behaviour of the program.

Test Data Builders

One can use the Test Data Builder pattern to address such a concern:

    var message = new ReserveTableBuilder()
        .WithDate(/* ... */)
    // The rest of the test goes here...

While elegant, this requires you to define a test-specific ReserveTableBuilder class. Not only that, but if you need it in more than one unit test project (which is likely, as message types are what glues message-based applications together), you’ll either have to duplicate those builder classes, or put them in a shared ‘unit test util’ library.

Equality comparison

Another unit testing problem is that you’d often need to compare an expected message to an actual message. This is possible (particularly with using custom comparers, like this:

public class ReserveTableComparer : IEqualityComparer<ReserveTable>
    public bool Equals(ReserveTable x, ReserveTable y)
        return Equals(x.Id, y.Id)
            && Equals(x.Time, y.Time)
            && Equals(x.Name, y.Name)
            && Equals(x.Email, y.Email)
            && Equals(x.Quantity, y.Quantity);

    public int GetHashCode(CustomerDeleted obj) // ...

Again, you’ll have to add such a comparer to your unit test code base, and again may have to deal with duplcation.

It’d be nice if one could just override Equals for the message itself, but unfortunately, structural equality is a really bad idea for mutable objects.

How immutable messages are better

Immutable messages address all of those concerns. First of all, messages, particularly events, ought to be conceptually immutable.

Also, you don’t need to add and maintain separate test-specific Test Data Builder classes. Just add WithXyz methods to the immutable record type itself:

public class ReserveTable : ICommand, IMessage
    public ReserveTable(Guid id, DateTime time, string name, string email, int quantity) // ...

    // ...
    public int Quantity { get; }

    public ReserveTable WithQuantity(int newQuantity)
        return new ReserveTable(Id, Time, Name, Email, newQuantity);

    // ...

All you have to do in your test code is to define good default test values. All the benefits you get from the Test Data Builder pattern now comes with the type itself (and they’re also available for the production code).

Additionally, immutable records can safely have structural equality, so one can safely override Equals on those classes. No customer comparers are required, making testing even easier.


Immutable message types offers plenty of advantages:

  • Conceptually correct for messaging
  • Better invariants
  • No need for Test Data Builders
  • No need for custom equality comparers

The main disadvantages, as I see them, are:

  • More typing is required to define the message types
  • Serialisation and deserialisation may require more custom coding, since this isn’t a common idiom on .NET

I’m personally not concerned about having to do a bit more up-front typing. This sort of design ultimately requires less typing, and the overall code becomes easier to read and maintain.

Or, if one is much concerned about typing, one can use a DSL to define immutable message types:

type ReserveTable = { Id : Guid; Time : DateTime; Name : string; Email : string; Quantity : int }

This type declaration generates IL code that corresponds to the immutable classes I’ve described above.

The serialisation issue is an internal NServiceBus issue, so doesn’t concern me as a user :grinning: I do, however, understand if this represents a real barrier.

@ploeh That already works, just use a serializer that supports this like Newtonsoft Json.

public class MyMessage : IMessage
    public MyMessage(int value)
        Value = value;

    public int Value { get; private set; }

    public override string ToString()
        return Value.ToString(CultureInfo.InvariantCulture);

This serializer package is fully supported by Particular Software although Newtonsoft Json isn’t maintained by us.

Likely other serializers support deserialization to private properties too but we do not maintain a list.


Oh, that’s good to hear :grinning:

I had the (wrong) impression that this wasn’t supported, but now I see how it works. Obviously, Particular Software can’t support JSON.NET itself; I think that was where I got it wrong.

I’ll see if I can try it out tomorrow when I’m visiting my client.

Thank you


Here are a couple of samples on how to achieve immutable messages:



As Ramon said, what you’re after is possible if you’re using Json Serialization.
I agree 100%, messages are contracts and immutable and should be represented as such in your code as well.

Indu Alagarsamy
Particular Software

Thanks, everyone. The preliminary experiments we did Friday convinced us to move further in this direction. No problems encountered yet :grinning:

Just one thing to very cognizant of here - the types are merely a specification for a message, they are not the message itself. The message is what’s on the wire, an agreement of a contract. If you want to have a formal definition of a message, that’s a schema.

I tend to avoid any sort of behavior on my message types, to avoid confusion about what those types represent. They’re a blueprint, a helper for serialization purposes. The message is not a type, it’s a manifestation of a schema.

If C# ever gets record types, it would be a good fit, but until it does, I’ve found trying to twist C# and other frameworks into immutable types isn’t really worth the effort for the gain.

Instead, I tell our clients to treat the message types no different than you would for View Models or API models in an ASP.NET Core application. Dumb DTOs.

Jimmy, thank you for replying. To be clear, treating message types as DTOs is exactly what I’m after here. I consider immutable records to have less behaviour than mutable objects.

Where we seem to disagree is whether it’s worth pursuing immutable records in C#. I think that it is, for the reasons outlined above.