Getting Started

Basic MSMQ Dead Letter Queue Monitoring With Custom Checks

Component: MSMQ Transport
NuGet Package: NServiceBus.Transport.Msmq (2.x)
Target Version: NServiceBus 8.x

When using MSMQ (as with any queuing technology), the delivery of a message may fail. This can occur for a number of reasons, such as including network failure, a deleted queue, a full queue, authentication failure, or a failure to deliver on time. In these cases, the message will be moved to the MSMQ Dead Letter Queue (DLQ).

Since these messages can contain valuable business data, it is important to monitor the dead letter queue. Also, if the dead letter queue fills up, it can cause MSMQ to run out of resources and the system as a whole to fail.

This sample shows how to use a Custom Check to monitor the dead letter queue. The custom check runs once every minute. If there are no messages in the dead letter queue then the custom check reports success. Otherwise, the custom check reports failure and includes the number of messages in the DLQ.

This is what the CustomCheck will look like in ServicePulse.

CustomCheck reported in ServicePulse


  • Ensure that MSMQ has been installed.
  • Ensure that ServiceControl and ServicePulse have been installed.

Code walk-through

Configure the custom checks plugin with the location of the ServiceControl input queue.


Check dead letter queue length

class CheckDeadLetterQueue :
    PerformanceCounter dlqPerformanceCounter;

    public CheckDeadLetterQueue() :
        base("Dead Letter Queue", "Transport", TimeSpan.FromMinutes(1))
        dlqPerformanceCounter = new PerformanceCounter(
            categoryName: "MSMQ Queue",
            counterName: "Messages in Queue",
            instanceName: "Computer Queues",
            readOnly: true);

    public override Task<CheckResult> PerformCheck(CancellationToken cancellationToken)
        var currentValue = dlqPerformanceCounter.NextValue();

        if (currentValue <= 0)
            return CheckResult.Pass;
        return CheckResult.Failed($"{currentValue} messages in the Dead Letter Queue on {Environment.MachineName}");

Related Articles

  • Custom Checks
    Define a custom set of conditions that are checked on the endpoint.
  • MSMQ Dead Letter Queues
    Controlling MSMQ Dead Letter Queue behavior.
  • MSMQ Transport
    MSMQ is a solid durable communications technology but does not dynamically detect network interfaces.