Partage via

Exceptions de la messagerie Service Bus (déconseillé)

  • Article

Cet article répertorie les exceptions .NET générées par les API .NET Framework.

Le 30 septembre 2026, nous retirerons les bibliothèques WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus et com.microsoft.azure.servicebus du kit de développement logiciel (SDK) Azure Service Bus, qui ne sont pas conformes aux directives du kit de développement logiciel (SDK) Azure. Nous mettrons également fin à la prise en charge du protocole SBMP. Vous ne pourrez donc plus utiliser ce protocole après le 30 septembre 2026. Migrez vers les dernières bibliothèques du kit de développement logiciel (SDK) Azure, qui offre des correctifs de sécurité critiques et des fonctionnalités améliorées, avant cette date.

Bien que les anciennes bibliothèques puissent toujours être utilisées au-delà du 30 septembre 2026, elles ne seront plus prises en charge officiellement et mises à jour par Microsoft. Pour plus d’informations, consultez l’annonce concernant l’arrêt de la prise en charge.

Catégories d'exceptions

Les API de messagerie génèrent des exceptions qui peuvent être classées dans les catégories suivantes, ainsi que l'action associée que vous pouvez mener pour essayer de les résoudre. La signification et les causes d’une exception peuvent varier en fonction du type d’entité de messagerie :

  1. Erreur de codage utilisateur (System.ArgumentException, System.InvalidOperationException, System.OperationCanceledException, System.Runtime.Serialization.SerializationException). Action générale : essayez de corriger le code avant de poursuivre.
  2. Erreur d’installation ou de configuration (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException, System.UnauthorizedAccessException. Action générale : révisez la configuration et modifiez-la si besoin.
  3. Exceptions temporaires (Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException). Action générale : relancez l'opération ou avertissez les utilisateurs. La classe RetryPolicy du SDK client peut être configurée pour traiter automatiquement les nouvelles tentatives. Pour plus d’informations, consultez les conseils sur les nouvelles tentatives.
  4. Autres exceptions (System.Transactions.TransactionException, System.TimeoutException, Microsoft.ServiceBus.Messaging.MessageLockLostException, Microsoft.ServiceBus.Messaging.SessionLockLostException). Action générale : propre au type d’exception. Reportez-vous au tableau de la section suivante :

Important

Types d'exceptions

Le tableau suivant répertorie les types d'exceptions de la messagerie, leurs causes et les propositions d'actions que vous pouvez effectuer.

Type d'exception Description/Cause/Exemples Action suggérée Remarques sur la nouvelle tentative automatique/immédiate
TimeoutException Le serveur n’a pas répondu à l’opération demandée dans le délai spécifié, qui est contrôlé par le paramètre OperationTimeout. Le serveur peut avoir terminé l’opération demandée. Cela peut se produire en raison des délais observés sur le réseau ou une autre infrastructure. Vérifiez la cohérence de l'état du système et réessayez si nécessaire. Consultez Exceptions au délai d’expiration. Dans certains cas, l'exécution d'une nouvelle tentative peut aider ; ajouter une logique de nouvelle tentative au code.
InvalidOperationException L’opération utilisateur demandée n’est pas autorisée sur le serveur ou le service. Consultez le message de l'exception pour obtenir plus d'informations. Par exemple, le paramètre Complete() génère cette exception si le message a été reçu en mode ReceiveAndDelete. Vérifiez le code et consultez la documentation. Assurez-vous que l'opération demandée est valide. La nouvelle tentative ne résout pas le problème.
OperationCanceledException Une tentative est effectuée pour appeler une opération sur un objet qui a déjà été fermé, abandonné ou supprimé. Dans de rares cas, la transaction ambiante est déjà supprimée. Vérifiez le code et veillez à ce qu’il n’appelle pas d’opérations sur un objet supprimé. La nouvelle tentative ne résout pas le problème.
UnauthorizedAccessException L’objet TokenProvider n’a pas pu obtenir de jeton, le jeton n’est pas valide ou le jeton ne contient pas les revendications nécessaires pour exécuter l’opération. Assurez-vous que le fournisseur de jetons est créé avec les valeurs correctes. Vérifiez la configuration du service ACS (Access Control Service). Dans certains cas, l'exécution d'une nouvelle tentative peut aider ; ajouter une logique de nouvelle tentative au code.
ArgumentException
ArgumentNullException
ArgumentOutOfRangeException		 Un ou plusieurs des arguments fournis à la méthode ne sont pas valides.
L’URI fourni à NamespaceManager ou Create contient des segments de chemin d’accès.
Le schéma d’URI fourni à NamespaceManager ou Ceate n’est pas valide.
La valeur de la propriété est supérieure à 32 ko.		 Vérifiez le code appelant et assurez-vous que les arguments sont corrects. La nouvelle tentative ne résout pas le problème.
MessagingEntityNotFoundException L’entité associée à l’opération n’existe pas ou a été supprimée. Assurez-vous que l'entité existe. La nouvelle tentative ne résout pas le problème.
MessageNotFoundException Tentative de réception d'un message avec un numéro de séquence spécifique. Ce message est introuvable. Vérifiez que le message n’a pas déjà été reçu. Vérifiez la file d'attente de lettres mortes pour voir si le message a été désactivé. La nouvelle tentative ne résout pas le problème.
MessagingCommunicationException Le client ne peut pas établir de connexion à Service Bus. Assurez-vous que le nom d'hôte fourni est correct et que l'hôte est accessible.

Si votre code s’exécute dans un environnement avec un pare-feu/proxy, assurez-vous que le trafic vers le domaine Service Bus/l’adresse IP et les ports n’est pas bloqué.

 Une nouvelle tentative peut aider en cas de problèmes de connectivité intermittents.
ServerBusyException Le service n’est pas en mesure de traiter la demande pour l’instant. Le client peut attendre pendant une période de temps, puis recommencer l'opération. Le client peut faire une nouvelle tentative après un certain temps. Si une nouvelle tentative provoque une exception différente, vérifiez le comportement de nouvelle tentative de cette exception.
MessagingException Exception de messagerie générique qui peut être levée dans les cas suivants :

une tentative est effectuée pour créer un QueueClient à l’aide d’un nom ou d’un chemin d’accès qui appartient à un autre type d’entité (par exemple, une rubrique).

Une tentative est effectuée pour envoyer un message de taille supérieure à 256 Ko.

Le serveur ou le service a rencontré une erreur lors du traitement de la demande. Consultez le message de l'exception pour obtenir plus d'informations. Il s’agit généralement d’une exception temporaire.

La demande a été arrêtée parce que l’entité est limitée. Code d’erreur : 50001, 50002, 50008.

Vérifiez le code et assurez-vous que seuls les objets sérialisables sont utilisés dans le corps du message (ou utilisez un sérialiseur personnalisé).

Consultez la documentation pour connaître les types de valeurs des propriétés pris en charge et utilisez uniquement les types pris en charge.

Vérifiez la propriété IsTransient . Si sa valeur est true, vous pouvez réessayer d’effectuer l’opération.

Si l’exception est due à une limitation, attendez quelques secondes, puis réessayez l’opération. Le comportement de la nouvelle tentative n’est pas défini et peut ne pas être utile dans d’autres scénarios.
MessagingEntityAlreadyExistsException Tentative de création d'une entité dont le nom est déjà utilisé par une autre entité de l'espace de noms de ce service. Supprimez l'entité existante ou choisissez un autre nom pour l'entité à créer. La nouvelle tentative ne résout pas le problème.
QuotaExceededException L’entité de messagerie a atteint sa taille maximale autorisée, ou le nombre maximal de connexions à un espace de noms a été dépassé. Créez de l’espace dans l’entité en recevant des messages à partir de l’entité ou de ses files d’attente secondaires. Consultez QuotaExceededException. Une nouvelle tentative peut aider si des messages ont été supprimés entre-temps.
RuleActionException Service Bus renvoie cette exception si vous essayez de créer une action de règle non valide. Service Bus associe cette exception à un message désactivé si une erreur se produit lors du traitement de l'action de règle pour ce message. Vérifiez que l'action de règle est correcte. La nouvelle tentative ne résout pas le problème.
FilterException Service Bus renvoie cette exception si vous essayez de créer un filtre non valide. Service Bus associe cette exception à un message désactivé si une erreur se produit lors du traitement du filtre pour ce message. Vérifiez l'exactitude du filtre. La nouvelle tentative ne résout pas le problème.
SessionCannotBeLockedException Tentative d'acceptation d'une session avec un ID de session spécifique, mais la session est actuellement verrouillée par un autre client. Assurez-vous que la session est déverrouillée par les autres clients. Une nouvelle tentative peut aider si la session a été libérée entre-temps.
TransactionSizeExceededException Trop d'opérations font partie de la transaction. Réduisez le nombre d'opérations qui font partie de cette transaction. La nouvelle tentative ne résout pas le problème.
MessagingEntityDisabledException Demande d'une opération d'exécution sur une entité désactivée. Activez l'entité. Une nouvelle tentative peut aider si l'entité a été activée entre-temps.
NoMatchingSubscriptionException Service Bus renvoie cette exception si vous envoyez un message à une rubrique avec le filtre préalable activé et si aucun des filtres ne correspond. Assurez-vous qu'au moins un filtre correspond. La nouvelle tentative ne résout pas le problème.
MessageSizeExceededException Une charge utile de message dépasse la limite de 256 Ko. La limite de 256 Ko correspond à la taille totale du message, qui peut inclure des propriétés système et toute surcharge .NET. Réduisez la taille de la charge utile de message, puis recommencez l'opération. La nouvelle tentative ne résout pas le problème.
TransactionException La transaction ambiante (Transaction.Current) n'est pas valide. Elle a peut-être été terminée ou abandonnée. Une exception en interne peut fournir des informations supplémentaires. La nouvelle tentative ne résout pas le problème.
TransactionInDoubtException Une opération est tentée sur une transaction incertaine, ou une tentative est faite pour valider la transaction et la transaction devient incertaine. Votre application doit gérer cette exception (comme un cas spécial), car la transaction a peut-être déjà été validée. -

QuotaExceededException

QuotaExceededException indique que le quota d’une entité spécifique a été dépassé.

Notes

Pour les quotas Service Bus, consultez Quotas.

Files d’attente et rubriques

Pour les files d’attente et les rubriques, il s’agit souvent de la taille de la file d’attente. La propriété du message d’erreur contient davantage d’informations, comme dans l’exemple suivant :

Microsoft.ServiceBus.Messaging.QuotaExceededException
Message: The maximum entity size has been reached or exceeded for Topic: 'xxx-xxx-xxx'. 
    Size of entity in bytes:1073742326, Max entity size in bytes:
1073741824..TrackingId:xxxxxxxxxxxxxxxxxxxxxxxxxx, TimeStamp:3/15/2013 7:50:18 AM

Ce message indique que la rubrique a dépassé sa limite de taille, dans ce cas 1 Go (limite de taille par défaut).

Espaces de noms

En ce qui concerne les espaces de noms, QuotaExceededException peut indiquer qu’une application a dépassé le nombre maximal de connexions à un espace de noms. Par exemple :

Microsoft.ServiceBus.Messaging.QuotaExceededException: ConnectionsQuotaExceeded for namespace xxx.
<tracking-id-guid>_G12 ---> 
System.ServiceModel.FaultException`1[System.ServiceModel.ExceptionDetail]: 
ConnectionsQuotaExceeded for namespace xxx.

Causes courantes

Il existe deux causes courantes pour cette erreur : la file d’attente de lettres mortes et des récepteurs de messages non fonctionnels.

  1. File d’attente de lettres mortes Un lecteur ne parvient pas à terminer les messages et ceux-ci sont renvoyés à la file d’attente/rubrique après expiration du verrouillage. Cela peut se produire si le lecteur rencontre une exception qui l’empêche d’appeler BrokeredMessage.Complete. Une fois un message lu 10 fois, il passe à la file d'attente de lettres mortes par défaut. Ce comportement est contrôlé par la propriété QueueDescription.MaxDeliveryCount et a une valeur par défaut de 10. Quand les messages s'accumulent dans la file d'attente de lettres mortes, ils prennent de la place.

    Pour résoudre ce problème, lisez et terminez les messages de la file d'attente de lettres mortes, comme vous le feriez pour une autre file d'attente. Vous pouvez utiliser la méthode FormatDeadLetterPath pour aider à mettre en forme le chemin d’accès de la file d’attente de lettres mortes.

  2. Récepteur arrêté. Un récepteur a cessé de recevoir des messages d’une file d’attente ou d’un abonnement. Pour l’identifier, examinez la propriété QueueDescription.MessageCountDetails , qui affiche la répartition complète des messages. Si la valeur de la propriété ActiveMessageCount est élevée ou augmente, les messages ne sont pas lus aussi rapidement qu’ils sont écrits.

TimeoutException

Une TimeoutException indique qu’une opération lancée par l’utilisateur dépasse le délai d’expiration de l’opération.

Vous devez vérifier la valeur de la propriété ServicePointManager.DefaultConnectionLimit car cette limite, si elle est atteinte, peut également entraîner une exception TimeoutException.

Des expirations de délai sont à prévoir pendant ou entre les opérations de maintenance telles que les mises à jour de service Service Bus (ou) les mises à jour de système d’exploitation sur les ressources qui exécutent le service. Pendant les mises à jour du système d’exploitation, les entités sont déplacées et les nœuds sont mis à jour ou redémarrés, ce qui peut entraîner des expirations de délai. Pour plus d’informations sur les contrats de niveau de service (SLA) pour le service Azure Service Bus, consultez Contrat SLA pour Service Bus.

Files d’attente et rubriques

Pour les files d’attente et les rubriques, le délai d’attente est spécifié dans la propriété MessagingFactorySettings.OperationTimeout, au sein de la chaîne de connexion ou par le biais de ServiceBusConnectionStringBuilder. Le message d'erreur peut varier, mais il contient toujours la valeur du délai d'attente spécifiée pour l'opération en cours.

MessageLockLostException

Cause

L’exception MessageLockLostException est levée lors de la réception d’un message en mode de réception PeekLock quand le verrou détenu par le client expire côté service.

Le verrou associé à un message peut expirer pour diverses raisons :

  • Le minuteur du verrou a expiré avant que l’application cliente l’ait renouvelé.
  • L’application cliente a acquis le verrou, l’a enregistré dans un magasin persistant, puis a redémarré. Après redémarrage, l’application cliente a examiné les messages en cours et tenté de les compléter.

Vous pouvez également recevoir cette exception dans les scénarios suivants :

  • Mise à jour du service
  • Mise à jour du système d’exploitation
  • Changement des propriétés de l’entité (file d’attente, rubrique, abonnement) pendant le maintien du verrou.

Résolution

Lorsqu’une application cliente reçoit MessageLockLostException, elle ne peut plus traiter le message. Elle peut éventuellement envisager de journaliser l’exception pour analyse, mais le client doit supprimer le message.

Étant donné que le verrou sur le message a expiré, celui-ci retourne à la file d’attente (ou à l’abonnement) et peut être traité par l’application cliente suivante qui appelle Receive.

En cas de dépassement de la valeur MaxDeliveryCount, le message peut être déplacé vers la file d’attente DeadLetterQueue.

SessionLockLostException

Cause

L’exception SessionLockLostException est levée quand une session est acceptée et que le verrou détenu par le client expire côté service.

Le verrou associé à une session peut expirer pour différentes raisons :

  • Le minuteur du verrou a expiré avant que l’application cliente l’ait renouvelé.
  • L’application cliente a acquis le verrou, l’a enregistré dans un magasin persistant, puis a redémarré. Après redémarrage, l’application cliente a examiné les sessions en cours et tenté de traiter les messages dans celles-ci.

Vous pouvez également recevoir cette exception dans les scénarios suivants :

  • Mise à jour du service
  • Mise à jour du système d’exploitation
  • Changement des propriétés de l’entité (file d’attente, rubrique, abonnement) pendant le maintien du verrou.

Résolution

Lorsqu’une application cliente reçoit SessionLockLostException, elle ne peut plus traiter les messages sur la session. Elle peut envisager de journaliser l’exception pour analyse, mais le client doit supprimer le message.

Étant donné que le verrou sur la session a expiré, celle-ci retourne à la file d’attente (ou à l’abonnement) et peut être verrouillée par l’application cliente suivante qui l’accepte. Étant donné que le verrou de session est détenu par une seule application cliente à un moment donné, le traitement dans l’ordre est garanti.

SocketException

Cause

Une exception SocketException est générée dans les cas suivants :

  • Quand une tentative de connexion échoue parce que l’hôte n’a pas répondu correctement après une heure spécifiée (code d’erreur TCP 10060).
  • Quand une connexion établie a échoué parce que l’hôte connecté n’a pas pu répondre.
  • Quand une erreur s’est produite lors du traitement du message ou que l’hôte distant a dépassé le délai d’expiration.
  • Quand il y a un problème de ressource réseau sous-jacent.

Résolution

Les erreurs SocketException indiquent que la machine virtuelle hébergeant les applications ne peut pas convertir le nom <mynamespace>.servicebus.windows.net en l’adresse IP correspondante.

Vérifiez que la commande qui suit parvient à mapper à une adresse IP.

PS C:\> nslookup <mynamespace>.servicebus.windows.net

Ce qui doit produire une sortie comme :

Name:    <cloudappinstance>.cloudapp.net
Address:  XX.XX.XXX.240
Aliases:  <mynamespace>.servicebus.windows.net

Si le nom ci-dessus n’est pas résolu en adresse IP et en l’alias d’espace de noms, demandez à l’administrateur réseau d’effectuer des recherches plus poussées. La résolution de noms s’effectue au travers d’un serveur DNS qui est généralement une ressource du réseau du client. Si la résolution DNS est effectuée par Azure DNS, contactez le support Azure.

Si la résolution de noms fonctionne comme prévu, vérifiez si les connexions à Azure Service Bus sont autorisées ici.

MessagingException

Cause

MessagingException est une exception générique qui peut être levée pour diverses raisons. Voici quelques-unes de ces raisons :

  • Une tentative est faite de créer une classe QueueClient sur une Rubrique ou un Abonnement.
  • La taille du message envoyé est supérieure à la limite applicable au niveau donné. Apprenez-en davantage sur les quotas et limites Service Bus.
  • La demande de plan de données spécifique (envoi, réception, exécution, abandon) a été arrêtée en raison d’une limitation.
  • Des problèmes temporaires se posent en raison de mises à niveau et redémarrages de service.

Notes

La liste d’exceptions ci-dessus n’est pas exhaustive.

Résolution

Les étapes de résolution dépendent de la cause de la levée de l’exception MessagingException.

  • Pour des problèmes temporaires (où isTransient a la valeur true) ou des problèmes de limitation, une nouvelle tentative d’exécution de l’opération peut les résoudre. La stratégie de nouvelle tentative par défaut du Kit de développement logiciel (SDK) peut être utilisée à cette fin.
  • Pour les autres problèmes, les détails de l’exception indiquent que les étapes du problème et de sa résolution peuvent être déduits de l’exception.

StorageQuotaExceededException

Cause

L’exception StorageQuotaExceededException est levée lorsque la taille totale des entités d’un espace de noms Premium dépasse la limite de 1 To par unité de messagerie.

Résolution

  • Augmenter le nombre d’unités de messagerie affectées à l’espace de noms Premium
  • Si vous utilisez déjà le nombre maximal d’unités de messagerie autorisées pour un espace de noms, créez un autre espace de noms.

Étapes suivantes

Pour obtenir des informations complètes sur l’API .NET Service Bus, consultez les informations de référence sur l’API .NET Azure. Pour des conseils relatifs à la résolution des problèmes, consultez le Guide de résolution des problèmes.