Checklist
Idempotent Message Handler Checklist
25 checks to make every Azure Service Bus handler safe to run twice.
Who it’s for
For teams running event-driven .NET on Azure Service Bus (or any at-least-once broker) who want to catch double-charges, duplicate emails and silent dead-letter queues before production does.
What’s inside
- Delivery assumptions to write down before you code
- Three deduplication strategies and when each one is enough
- The transaction boundary check that closes the 'worked but never acknowledged' gap
- Retry, poison-message and dead-letter settings, with the monitoring that makes them useful
Free preview
The full checklist has 25 checks. Here is the first section.
A. Know your delivery guarantees
It is written down that this queue or subscription is at-least-once, and every handler author knows it.
Duplicates are normal broker behaviour, not an incident. Designs that assume exactly-once fail quietly.
The receive mode is a deliberate choice. PeekLock for anything that matters; ReceiveAndDelete only where losing a message is acceptable.
ReceiveAndDelete removes the message before your code runs, so a crash loses it for good.
Lock duration comfortably exceeds your slowest realistic handler run, or lock renewal is on.
An expired lock redelivers a message you are still processing, which gives you two concurrent runs of the same work.
Every message carries a stable identity set by the producer (MessageId or a business key), never generated on receipt.
Deduplication only works if the redelivered copy has the same identity as the original.
Producers reuse the same MessageId when they retry a send, and you have decided whether to enable broker duplicate detection.
Duplicates also enter at the source when a send times out and is retried.
Questions
- Is it really free?
- Yes. No payment and no sales call. You give me an email address and the PDF is yours.
- What will you do with my email?
- Send you the occasional note about similar resources and new writing. Reply “stop” and I’ll remove you.
- Can I share it with my team?
- Please do. Print it, adapt it, put it in your wiki. A link back to the site is appreciated.