Skip Navigation LinksAzure Developers Guide > Azure Service Bus > Brokered Messaging > Brokered Messaging Features & Patterns > Deadlettering > Deadlettering Messages in a Receiving Application

Training Courses

All course material is in English, and courses are delivered in English. Feel free to contact me for further information.

Deadlettering Messages in a Receiving Application

It is also possible for a receiving application to deadletter messages if they are formatted incorrectly or fail to comply with business rules.

The brokered message class contains the following methods for deadlettering messages.


public void DeadLetter()


public void DeadLetter(string deadLetterReason, string deadLetterErrorDescription)



The QueueClient, SubscriptionClient and MessageReceiver classes provide the following messages.


public void DeadLetter(Guid lockToken)


public void DeadLetter

    (Guid lockToken, string deadLetterReason, string deadLetterErrorDescription)



When values are passed for the deadLetterReason and deadLetterErrorDescription parameters they will be added to the message properties collection with the names of DeadLetterReason and DeadLetterErrorDescription respectively. This will help a deadletter processing application to determine the cause of the failure.

Suppose the receiving application can only process order statistics for the UK, United States and Sweden.


List<string> validRegions = new List<string>()


    "UK", "US", "SE"




When a message is received a check could be performed to verify that the order statistics are for a valid region, if this validation check fails the message can be deadlettered by the receiving application. Explicitly deadlettering a message in the receiving application will save the message from being processed reputedly until it is deadlettered by the queue.


OrderStat stat = msg.GetBody<OrderStat>();


if (!validRegions.Contains(stat.Region))


    string errorDescription = string.Format("Region {0} is not known.", stat.Region);


    msg.DeadLetter("Unknown region", errorDescription);





It is also possible for the receiving application to check the DeliveryCount property of a message and decide weather it should be abandoned or deadlettered.


if (msg.DeliveryCount < 3)













Speaking Engagements