Sponsor: Do you build complex software systems? See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling. Get started for free.
Over the years I’ve learned various aspects of messaging either through using various products, reading other blogs, or unfortunately in a lot of cases, discovering them myself. One of those aspects is message properties.
Specifically, (meta) data that you might want to include in your messages to solve some common problems.
My plan is to dive deeper with implementation examples for each topic listed in this post. Hopefully, this post can serve as a reference point to your adventures in messaging or possibly gain some insight that provides a solution for a pain point you may (already) be experiencing.
I was inspired to write this post after seeing this tweet:
Type/Name
The naming of messages is incredibly important for a variety of reasons. When talking about events, it’s important to name them in the past tense because it conveys that they are statements of fact.
Most often the name of an event is used to determine how to deserialize into a specific type. Where I’ve personally run into problems, in .NET specifically, is using the CLR type name as the event name to determine how to deserialize. The issue with this is you’re very likely to change the name of your CLR type.
Prefer to having a static name for an event and not using the CLR type name at runtime to create the event name.
More info on naming can be found in my post Message Naming Guidelines
Message Version
Most often when needing to version a message is to simply create a new type/name. With events, I think this approach works fairly well when you discover a better way to describe the event and along with it the data to expose.
When a new event isn’t required, but rather a slight change in data is to specify the version in the message. Consuming clients can use the message name along with the version to determine how to process the body of the message.
More on versioning can be found in my Event Versioning Guidelines
Message ID
A unique identifier of a message. This can be used for concurrency. Message Handlers can keep track of which messages IDs they have processed and determine if they should act upon receiving a message.
This is important because message handlers should be reentrant and messages can be delivered more than once.
More on this can be found on my Message-IDs for handling Concurrency post.
Correlation ID
A unique identifier that allows you to reference the flow of events (event chain) or a transaction. Also, often called a Trace ID. Assigning a correlation ID as soon as possible and any message handler that receives a message with a correlation ID then uses that same ID for any messages it outputs.
This is very useful for logging and error handling in asynchronous and distributed environments.
Contract Owner
Who owns the message contract can be important. Depending on how messages are distributed, there may be many messages from various owners. Knowing who owns a message contract is helpful for troubleshooting as well as how to handle that message.
An OrderPlaced event seems like it could be unique across all services, however, in a distribution domain, is that a Sales OrderPlaced from the Sales service or a Purch OrderPlaced from the purchasing service?
Having the owner of the message provides the ability to distinguish how to handle the message when the name alone doesn’t provide enough distinction.
UTC Timestamp
This seems obvious but it gives more context to when the message was created. A useful is keeping track of latency between a message being created to how long it’s taking a given service to process it.
Sender
Who originated the message. Not the service, but rather the user. This could be an access token that is then used to determine if the sender has the correct permissions or is authorized to perform the given request.
Resource/Entity Version
The version of the resource/entity that you are performing an action on. Similar to the message ID this can be used for concurrency. A wonderful example of this is Azure Cosmos DB which uses an ETag as the resource version which is then used with an If-None-Match header for optimistic concurrency. If you’re using Cosmos DB check out my post on Optimistic Concurrency in Azure Cosmos DB
Message Properties
I’ll be going in-depth in each of the above topics with code examples for the actual implementation of how you would use these message properties. Stay tuned.
If you’d like to add to the list, let me know in the comments or on Twitter.