Dead Letter Queue Forwarding

This page refers to the legacy Azure Service Bus transport that uses the WindowsAzure.ServiceBus NuGet package. This package is currently on extended support until May 2022, after which it will be out of support according to the support policy. All users should migrate to the Azure Service Bus transport transport.

When Azure Service Bus detects that an endpoint cannot process messages, or when it has been configured not to discard expired or filtered messages, then it will move those messages to a dead letter queue associated with the entity that originally contained those messages.

From a management perspective, this is less than ideal when operations staff has to monitor a multitude of entities for dead lettered or discarded messages.

A preferred approach is to consolidate all those messages into a single centralized queue by enabling forwarding on the dead letter queue of each entity, except for the destination entity itself.

The Azure Service Bus transport supports this capability. It allows to configure forwarding for dead letter queues when it creates entities on behalf of the application.


To set up dead letter queue forwarding, use the ForwardDeadLetteredMessagesTo(string) method on both the Queues and Subscriptions extension points.

When dead letter forwarding is enabled, it will be enabled for all dead letter queues associated with the queues created by the transport. The API allows making exceptions by using an overload on the configuration API. It is advised to set up forwarding for all entities except for the error queue, audit queue and centralized dead letter queue.

var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var queues = transport.Queues();
        condition: queueName =>
            return queueName != "error" &&
                   queueName != "audit" &&
                   queueName != "centralizeddlq";
        forwardDeadLetteredMessagesTo: "centralizeddlq");
var subscriptions = transport.Subscriptions();
The centralized dead-letter queue is not created when the EnableInstaller call is invoked and therefore should be created up-front.

Last modified