Vue d’ensemble des files d’attente de lettres mortes Service BusOverview of Service Bus dead-letter queues

Les files d’attente Azure Service Bus et les abonnements aux rubriques fournissent une sous-file d’attente secondaire, appelée file d’attente de lettres mortes.Azure Service Bus queues and topic subscriptions provide a secondary sub-queue, called a dead-letter queue (DLQ). La file d’attente de lettres mortes n’a pas besoin d’être explicitement créée et ne peut pas être supprimée ou gérée indépendamment de l’entité principale.The dead-letter queue does not need to be explicitly created and cannot be deleted or otherwise managed independent of the main entity.

Cet article décrit les files d’attente de lettres mortes dans Service Bus.This article describes dead-letter queues in Service Bus. Une grande partie de la discussion est illustrée par l’exemple de files d’attente de lettres mortes qui se trouve sur GitHub.Much of the discussion is illustrated by the Dead-Letter queues sample on GitHub.

La file d’attente de lettres mortesThe dead-letter queue

L’objectif de la file d’attente de lettres mortes est de conserver les messages qui ne peuvent pas être remis aux destinataires ou les messages qui n’ont pas pu être traités.The purpose of the dead-letter queue is to hold messages that cannot be delivered to any receiver, or messages that could not be processed. Les messages peuvent alors être supprimés de la file d’attente de lettres mortes et inspectés.Messages can then be removed from the DLQ and inspected. Une application peut, à l’aide d’un opérateur, corriger les problèmes et renvoyer le message, consigner le fait qu’une erreur s’est produite et prendre des mesures correctives.An application might, with help of an operator, correct issues and resubmit the message, log the fact that there was an error, and take corrective action.

Du point de vue de l’API et du protocole, la file d’attente de lettres mortes est essentiellement similaire à une autre file d’attente, sauf que les messages peuvent être envoyés uniquement par le biais de l’opération de lettres mortes de l’entité parente.From an API and protocol perspective, the DLQ is mostly similar to any other queue, except that messages can only be submitted via the dead-letter operation of the parent entity. En outre, la durée de vie n’est pas observée, et vous ne pouvez pas supprimer un message d’une file d’attente de lettres mortes.In addition, time-to-live is not observed, and you can't dead-letter a message from a DLQ. La file d’attente de lettres mortes prend entièrement en charge la remise de verrou d’affichage et les opérations transactionnelles.The dead-letter queue fully supports peek-lock delivery and transactional operations.

Notez qu’il n’y a aucun nettoyage automatique de la file d’attente de lettres mortes.Note that there is no automatic cleanup of the DLQ. Les messages restent dans la file d’attente de lettres mortes jusqu’à ce que vous les récupériez explicitement et que vous appeliez Complete() sur le message de lettres mortes.Messages remain in the DLQ until you explicitly retrieve them from the DLQ and call Complete() on the dead-letter message.

Déplacer des messages vers la file d’attente de lettres mortesMoving messages to the DLQ

Plusieurs activités dans Service Bus entraînent l’envoi des messages dans la file d’attente de lettres mortes à partir du moteur de messagerie lui-même.There are several activities in Service Bus that cause messages to get pushed to the DLQ from within the messaging engine itself. Une application peut également explicitement déplacer des messages dans la file d’attente de lettres mortes.An application can also explicitly move messages to the DLQ.

Comme le message est déplacé par le service broker, deux propriétés sont ajoutées au message quand le service broker appelle sa version interne de la méthode DeadLetter sur le message : DeadLetterReason et DeadLetterErrorDescription.As the message gets moved by the broker, two properties are added to the message as the broker calls its internal version of the DeadLetter method on the message: DeadLetterReason and DeadLetterErrorDescription.

Les applications peuvent définir leurs propres codes pour la propriété DeadLetterReason, mais le système définit les valeurs suivantes.Applications can define their own codes for the DeadLetterReason property, but the system sets the following values.

ConditionCondition DeadLetterReasonDeadLetterReason DeadLetterErrorDescriptionDeadLetterErrorDescription
ToujoursAlways HeaderSizeExceededHeaderSizeExceeded Le quota de taille pour ce flux a été dépassé.The size quota for this stream has been exceeded.
!TopicDescription.!TopicDescription.
EnableFilteringMessagesBeforePublishing et SubscriptionDescription.EnableFilteringMessagesBeforePublishing and SubscriptionDescription.
EnableDeadLetteringOnFilterEvaluationExceptionsEnableDeadLetteringOnFilterEvaluationExceptions
exception.GetType().Nameexception.GetType().Name exception.Messageexception.Message
EnableDeadLetteringOnMessageExpirationEnableDeadLetteringOnMessageExpiration TTLExpiredExceptionTTLExpiredException Le message a expiré et a été placé dans la file d’attente de lettres mortes.The message expired and was dead lettered.
SubscriptionDescription.RequiresSessionSubscriptionDescription.RequiresSession L’ID de session a la valeur null.Session id is null. L’entité activée dans la session n’autorise pas les messages dont l’identificateur de session a la valeur null.Session enabled entity doesn't allow a message whose session identifier is null.
!dead letter queue!dead letter queue MaxTransferHopCountExceededMaxTransferHopCountExceeded NullNull
Mise en file d’attente de lettres mortes explicite par l’applicationApplication explicit dead lettering Spécifié par l’applicationSpecified by application Spécifié par l’applicationSpecified by application

Dépassement de MaxDeliveryCountExceeding MaxDeliveryCount

Les files d’attente et les abonnements ont chacun une propriété QueueDescription.MaxDeliveryCount et SubscriptionDescription.MaxDeliveryCount, respectivement. La valeur par défaut est 10.Queues and subscriptions each have a QueueDescription.MaxDeliveryCount and SubscriptionDescription.MaxDeliveryCount property respectively; the default value is 10. Chaque fois qu’un message a été remis sous un verrou (ReceiveMode.PeekLock), mais qu’il a été explicitement abandonné ou que le verrou a expiré, la propriété BrokeredMessage.DeliveryCount du message est incrémentée.Whenever a message has been delivered under a lock (ReceiveMode.PeekLock), but has been either explicitly abandoned or the lock has expired, the message BrokeredMessage.DeliveryCount is incremented. Quand DeliveryCount dépasse MaxDeliveryCount, le message est déplacé vers la file d’attente de lettres mortes avec le code motif MaxDeliveryCountExceeded.When DeliveryCount exceeds MaxDeliveryCount, the message is moved to the DLQ, specifying the MaxDeliveryCountExceeded reason code.

Ce comportement ne peut pas être désactivé, mais vous pouvez définir MaxDeliveryCount sur un très grand nombre.This behavior cannot be disabled, but you can set MaxDeliveryCount to a very large number.

Dépassement de TimeToLiveExceeding TimeToLive

Quand la propriété QueueDescription.EnableDeadLetteringOnMessageExpiration ou SubscriptionDescription.EnableDeadLetteringOnMessageExpiration est définie sur true (la valeur par défaut est false), tous les messages arrivant à expiration sont déplacés vers la file d’attente de lettres mortes avec le code motif TTLExpiredException.When the QueueDescription.EnableDeadLetteringOnMessageExpiration or SubscriptionDescription.EnableDeadLetteringOnMessageExpiration property is set to true (the default is false), all expiring messages are moved to the DLQ, specifying the TTLExpiredException reason code.

Les messages ayant expiré sont uniquement purgés et transférés vers la file d’attente de lettres mortes quand au moins un destinataire actif effectue une collecte à partir de la file d’attente principale ou l’abonnement. Ce comportement est normal.Note that expired messages are only purged and moved to the DLQ when there is at least one active receiver pulling from the main queue or subscription; that behavior is by design.

Erreurs pendant le traitement des règles d’abonnementErrors while processing subscription rules

Quand la propriété SubscriptionDescription.EnableDeadLetteringOnFilterEvaluationExceptions est activée pour un abonnement, les erreurs qui surviennent pendant l’exécution des règles de filtre SQL d’un abonnement sont capturées dans la file d’attente de lettres mortes avec le message incriminé.When the SubscriptionDescription.EnableDeadLetteringOnFilterEvaluationExceptions property is enabled for a subscription, any errors that occur while a subscription's SQL filter rule executes are captured in the DLQ along with the offending message.

Mise en file d’attente de lettres mortes au niveau de l’applicationApplication-level dead-lettering

En plus des fonctionnalités de file d’attente de lettres mortes fournies par le système, les applications peuvent utiliser la file d’attente de lettres mortes pour refuser explicitement les messages inacceptables.In addition to the system-provided dead-lettering features, applications can use the DLQ to explicitly reject unacceptable messages. Il peut s’agir de messages qui ne peuvent pas être traités correctement en raison d’un problème système, de messages qui contiennent des charges utiles incorrectement formées ou de messages qui n’ont pas pu être authentifiés lors de l’utilisation d’un schéma de sécurité au niveau du message.This can include messages that cannot be properly processed due to any sort of system issue, messages that hold malformed payloads, or messages that fail authentication when some message-level security scheme is used.

Mise en file d’attente de lettres mortes dans des scénarios ForwardTo ou SendViaDead-lettering in ForwardTo or SendVia scenarios

Les messages seront envoyés à la file d’attente de lettres mortes de transfert dans les conditions suivantes :Messages will be sent to the transfer dead-letter queue under the following conditions:

  • Un message passe par plus de 4 files d’attente ou rubriques enchaînées.A message passes through more than 4 queues or topics that are chained together.
  • La file d’attente de destination ou la rubrique est désactivée ou supprimée.The destination queue or topic is disabled or deleted.
  • La file d’attente ou la rubrique de destination dépasse la taille d’entité maximale.The destination queue or topic exceeds the maximum entity size.

Pour récupérer ces messages de lettres mortes, vous pouvez créer un récepteur à l’aide de la méthode utilitaire FormatTransferDeadletterPath.To retrieve these dead-lettered messages, you can create a receiver using the FormatTransferDeadletterPath utility method.

ExemplesExample

L’extrait de code suivant crée un destinataire de message.The following code snippet creates a message receiver. Dans la boucle de réception de la file d’attente principale, le code récupère le message avec Receive(TimeSpan.Zero), qui demande au service broker de retourner immédiatement les messages disponibles ou de ne retourner aucun résultat.In the receive loop for the main queue, the code retrieves the message with Receive(TimeSpan.Zero), which asks the broker to instantly return any message readily available, or to return with no result. Si le code reçoit un message, il l’abandonne immédiatement, ce qui incrémente le DeliveryCount.If the code receives a message, it immediately abandons it, which increments the DeliveryCount. Une fois que le système déplace le message vers la file d’attente de lettres mortes, la file d’attente principale est vide et la boucle se ferme, car ReceiveAsync retourne null.Once the system moves the message to the DLQ, the main queue is empty and the loop exits, as ReceiveAsync returns null.

var receiver = await receiverFactory.CreateMessageReceiverAsync(queueName, ReceiveMode.PeekLock);
while(true)
{
    var msg = await receiver.ReceiveAsync(TimeSpan.Zero);
    if (msg != null)
    {
        Console.WriteLine("Picked up message; DeliveryCount {0}", msg.DeliveryCount);
        await msg.AbandonAsync();
    }
    else
    {
        break;
    }
}

Chemin d’accès à la file d’attente de lettres mortesPath to the dead-letter queue

Vous pouvez accéder à la file d’attente de lettres mortes à l’aide de la syntaxe suivante :You can access the dead-letter queue by using the following syntax:

<queue path>/$deadletterqueue
<topic path>/Subscription/<subscription path>/$deadletterqueue

Si vous utilisez le kit SDK .NET, vous pouvez obtenir le chemin d’accès à la file d’attente de lettres mortes à l’aide de la méthode SubscriptionClient.FormatDeadLetterPath().If you are using the .NET SDK, you can get the path to the dead-letter queue by using the SubscriptionClient.FormatDeadLetterPath() method. Cette méthode prend le nom de nom / d’abonnement de rubrique et suffixes avec /$DeadLetterQueue.This method takes the topic name/subscription name and suffixes with /$DeadLetterQueue.

Étapes suivantesNext steps

Pour plus d’informations sur les files d’attente de lettres mortes Service Bus, consultez les articles suivants :See the following articles for more information about Service Bus queues: