Exceptions de la messagerie Service Bus (.NET)

La bibliothèque de client .NET Service Bus expose des exceptions lorsqu’une opération de service ou un client rencontre une erreur. Si possible, les types d’exceptions .NET standard sont utilisés pour transmettre des informations d’erreur. Pour les scénarios spécifiques à Service Bus, une exception ServiceBusException est levée.

Les clients Service Bus réessayent automatiquement les exceptions considérées comme temporaires, en suivant les options de nouvelle tentative configurées. Lorsqu’une exception est exposée à l’application, toutes les nouvelles tentatives ont été appliquées sans succès, ou l’exception a été considérée comme non temporaire. Vous trouverez plus d’informations sur la configuration des options de nouvelle tentative dans l’exemple de personnalisation d’options de nouvelle tentative.

ServiceBusException

L’exception inclut des informations contextuelles pour vous aider à comprendre le contexte de l’erreur et sa gravité relative.

• EntityPath : identifie l’entité Service Bus à partir de laquelle l’exception s’est produite, si elle est disponible.
• IsTransient : indique si l’exception est considérée comme récupérable. Dans le cas où il a été estimé temporaire, le service Azure Service Bus a déjà été appliqué à la stratégie de nouvelles tentatives appropriée et toutes les nouvelles tentatives ont échoué.
• Message : fournit une description de l’erreur qui s’est produite et du contexte pertinent.
• StackTrace : représente les cadres immédiats de la pile des appels, mettant en surbrillance l’emplacement dans le code où l’erreur s’est produite.
• InnerException : lorsqu’une exception a été le résultat d’une opération de service, il s’agit souvent d’une instance Microsoft.Azure.Amqp.AmqpException décrivant l’erreur, conformément à la spécification OASIS Advanced Message Queuing Protocol (AMQP) 1.0.
• Reason : donne un ensemble de raisons connues de l’échec qui permettent de catégoriser et de clarifier la cause racine. Ces valeurs visent à permettre l’application du filtrage des exceptions et d’autres logiques dans le cas où l’inspection du texte d’un message d’exception ne serait pas idéale. Voici quelques-unes des principales raisons de l’échec :

  • ServiceTimeout : indique que le service Service Bus n’a pas répondu à une requête d’opération dans le laps de temps attendu. Cela peut être dû à un problème de réseau ou de service temporaire. Le service Service Bus peut ou non avoir traité la requête avec succès, le statut n’est pas connu. Dans le contexte de la prochaine session disponible, cette exception indique qu’aucune session non verrouillée n’était disponible dans l’entité. Ces erreurs sont des erreurs temporaires qui ont automatiquement fait l’objet d’une nouvelle tentative.

  • QuotaExceeded: indique généralement qu’il existe trop d’opérations de réception actives pour une seule entité. Pour éviter cette erreur, réduisez le nombre de réceptions simultanées potentielles. Vous pouvez utiliser des réceptions par lots pour tenter de recevoir plusieurs messages par requête de réception. Pour plus d’informations, consultez Quotas de Service Bus.

  • MessageSizeExceeded : indique que la taille du message a dépassé la taille maximale de message. La taille du message inclut le corps du message et toutes les métadonnées associées. La meilleure approche pour résoudre cette erreur consiste à réduire le nombre de messages envoyés dans un lot ou la taille du corps inclus dans le message. Étant donné que les limites de taille sont sujettes à modification, consultez les quotas Service Bus pour plus de détails.

  • MessageLockLost : indique que le verrou sur le message est perdu. Les appelants doivent tenter de recevoir et de traiter le message à nouveau. Cette exception s’applique uniquement aux entités qui n’utilisent aucune sessions. Cette erreur se produit si le traitement dure plus longtemps que la durée du verrou et que le verrou du message n’est pas renouvelé. Cette erreur peut également se produire lorsque le lien est détaché en raison d’un problème de réseau temporaire ou lorsque le lien est inactif pendant 10 minutes.

    Le service Service Bus utilise le protocole AMQP, qui est avec état. En raison de la nature du protocole, si le lien qui connecte le client et le service est détaché une fois qu’un message est reçu, mais avant qu’il ne soit résolu, le message ne peut pas l’être lors de la reconnexion du lien. Les liens peuvent être détachés en raison d’une défaillance réseau temporaire à court terme, d’une panne du réseau ou d’un délai d’inactivité de 10 minutes imposé par le service. La reconnexion du lien se produit automatiquement dans le cadre d’une opération qui nécessite le lien, autrement dit, l’installation ou la réception de messages. En raison de ce comportement, vous pouvez rencontrer une ServiceBusException avec une ReasonMessageLockLost ou SessionLockLost, même si le délai d’expiration du verrou n’est pas encore écoulé.

  • SessionLockLost : indique que le verrou a expiré sur la session. Les appelants doivent réessayer d’accepter la session. Cette exception ne s’applique qu’aux entités activées par session. Cette erreur se produit si le traitement dure plus longtemps que la durée du verrou et que le verrou de session n’est pas renouvelé. Cette erreur peut également se produire lorsque le lien est détaché en raison d’un problème de réseau temporaire ou lorsque le lien est inactif pendant 10 minutes. Le service Service Bus utilise le protocole AMQP, qui est avec état. En raison de la nature du protocole, si le lien qui connecte le client et le service est détaché une fois qu’un message est reçu, mais avant qu’il ne soit résolu, le message ne peut pas l’être lors de la reconnexion du lien. Les liens peuvent être détachés en raison d’une défaillance réseau temporaire à court terme, d’une panne du réseau ou d’un délai d’inactivité de 10 minutes imposé par le service. La reconnexion du lien se produit automatiquement dans le cadre d’une opération qui nécessite le lien, autrement dit, l’installation ou la réception de messages. En raison de ce comportement, vous pouvez rencontrer une ServiceBusException avec une ReasonMessageLockLost ou SessionLockLost, même si le délai d’expiration du verrou n’est pas encore écoulé.

  • MessageNotFound : cette erreur se produit lors de la tentative de réception d’un message différé par numéro de séquence pour un message qui n’existe pas dans l’entité ou qui est actuellement verrouillé.

  • SessionCannotBeLocked : indique que la session demandée ne peut pas être verrouillée, car le verrou est déjà conservé ailleurs. Une fois le verrou expiré, la session peut être acceptée.

  • GeneralError : indique que le service Service Bus a rencontré une erreur lors du traitement de la requête. Les mises à niveau et les redémarrages du service provoquent souvent cette erreur. Ces erreurs sont des erreurs temporaires qui ont automatiquement fait l’objet d’une nouvelle tentative.

  • ServiceCommunicationProblem : indique qu’une erreur s’est produite lors de la communication avec le service. Le problème peut provenir d’un problème de réseau temporaire ou d’un problème de service. Ces erreurs sont des erreurs temporaires qui feront automatiquement l’objet d’une nouvelle tentative.

  • ServiceBusy : indique que le service a limité la requête. Les détails décrivant ce qui peut entraîner la limitation d’une requête et la façon d’éviter d’être limité sont disponibles ici. Les requêtes limitées font l’objet d’une nouvelle tentative, mais la bibliothèque de client applique automatiquement une temporisation de 10 secondes avant d’essayer d’effectuer d’autres requêtes à l’aide du même ServiceBusClient (ou de tous les sous-types créés à partir de ce client). Cela peut entraîner des problèmes si la durée du verrou de votre entité est inférieure à 10 secondes, car les verrous de message ou de session sont susceptibles d’être perdus pour les messages non résolus ou les sessions verrouillées. Étant donné que les requêtes limitées font l’objet d’une nouvelle tentative correcte, les exceptions générées sont enregistrées sous forme d’avertissements plutôt que d’erreurs : l’événement source de l’événement au niveau de l’avertissement spécifique est 43 (RunOperation a rencontré une exception et une nouvelle tentative se produit).

  • MessagingEntityAlreadyExists : indique qu’une entité portant le même nom existe sous le même espace de noms.

  • MessagingEntityDisabled : l’entité de messagerie est désactivée. Réactivez l’entité à l’aide de Portal.

  • MessagingEntityNotFound : Le service Service Bus ne trouve pas de ressource Service Bus.

Gérer ServiceBusException : exemple

Voici un exemple de gestion de ServiceBusException et de filtrage par le Reason.

try
{
    // Receive messages using the receiver client
}
catch (ServiceBusException ex) when
    (ex.Reason == ServiceBusFailureReason.ServiceTimeout)
{
    // Take action based on a service time out
}

Autres exceptions courantes

• ArgumentException : le client lance cette exception dérivée de ArgumentException lorsqu’un paramètre fourni lors de l’interaction avec le client n’est pas valide. Des informations sur le paramètre spécifique et la nature du problème sont disponibles dans le Message.
• InvalidOperationException : se produit lors de la tentative d’exécution d’une opération qui n’est pas valide pour sa configuration actuelle. Cette exception se produit généralement lorsqu’un client n’a pas été configuré pour prendre en charge l’opération. Souvent, elle peut être atténuée en ajustant les options transmises au client.
• NotSupportedException : se produit lorsqu’une opération demandée est valide pour le client, mais pas prise en charge par son état actuel. Vous trouverez des informations sur le scénario dans le Message.
• AggregateException : se produit lorsqu’une opération peut rencontrer plusieurs exceptions et les exposer en tant qu’échec unique. Cette exception est généralement rencontrée lors du démarrage ou de l’arrêt du processeur Service Bus ou du processeur de session Service Bus.

Raison : QuotaExceeded

Une ServiceBusException ayant pour raison QuotaExceeded indique qu’un quota pour une entité spécifique a été dépassé.

Remarque

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 :

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, l’exception QuotaExceeded peut indiquer qu’une application a dépassé le nombre maximal de connexions à un espace de noms. Par exemple :

<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.

• 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 de terminer le message. Une fois un message lu 10 fois, il passe à la file d’attente de lettres mortes par défaut. La propriété MaxDeliveryCount contrôle ce comportement, dont la valeur par défaut est 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.

• Récepteur arrêté. Un récepteur a cessé de recevoir des messages d’une file d’attente ou d’un abonnement. La façon d’identifier le problème consiste à examiner le nombre de messages actifs. Si le nombre de messages actifs est élevé ou augmente, les messages ne sont pas lus aussi rapidement qu’ils sont écrits.

Raison : MessageLockLost

Cause

Une ServiceBusException ayant pour raison MessageLockLost indique qu’un message est reçu à l’aide du mode de réception PeekLock et que le verrou détenu par le client expire du côté du service.

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

• Le minuteur du verrou a expiré avant son renouvellement par l’application cliente.
• 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 la réception.

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

Raison : SessionLockLost

Cause

Une ServiceBusException ayant pour raison MessageLockLost 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.

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.

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 un délai spécifié (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 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.

UnauthorizedAccessException

Une UnauthorizedAccessException indique que les informations d’identification fournies n’autorisent pas l’exécution de l’action demandée. La propriété Message contient des informations sur la défaillance.

Nous vous recommandons de suivre ces étapes de vérification, en fonction du type d’autorisation fourni lors de la construction de ServiceBusClient.

• Vérifier que la chaîne de connexion est correcte
• Vérifier que le jeton SAS a été correctement généré
• Vérifier que les rôles corrects de contrôle d’accès en fonction du rôle (RBAC) ont été accordés

Exceptions de géoréplication

ServerBusyException

Causes

• Pendant la réplication asynchrone (décalage de réplication supérieur à zéro), le client tente d’effectuer une opération sur une entité Service Bus (file d’attente, rubrique) ou effectue une opération de gestion, mais l’opération échoue parce que le décalage de réplication entre la région principale et la région secondaire a dépassé le décalage de réplication maximal autorisé en secondes.
  • Exemple : l’opération subit une limitation, car avec elle, le nouveau décalage de réplication atteindrait 38 323 secondes, ce qui est supérieur au décalage maximal de réplication défini (300 secondes). Le décalage de réplication actuel pour la dernière opération en cours de réplication est de 0 secondes.
• La file d’attente de réplication d’une entité dépasse sa taille maximale en octets. La taille maximale en octets d’une file d’attente de réplication est une limite interne définie par Service Bus.
  • Exemple : la taille de file d’attente de réplication de 73 128 000 a dépassé le seuil de 67 108 864.
• Dans la réplication synchrone, une requête expire en attendant qu’une autre demande soit répliquée.
  • Exemple : volume élevé de requêtes de l’application cliente pour <NAMESPACE>/<ENTITYNAME>. Une réplication vers d’autres régions est en cours.

Résolution

• Le client doit se retirer pour donner du temps au service pour traiter sa charge de travail donnée, avant de réessayer.

Expiration

Cause

• Une exception de délai d’expiration dans la récupération d’urgence géographique signifie que l’opération ne s’est pas terminée avant le délai d’expiration fourni par le client.
  • Dans la réplication synchrone, l’écriture dans la région primaire et la réplication vers les régions secondaires d’une opération se trouvent dans l’étendue du délai d’expiration de l’opération.
  • Dans la réplication asynchrone, l’écriture dans la région primaire d’une opération rentre dans le délai d’expiration de l’opération, mais la réplication d’une opération sur les régions secondaires ne rentre pas dans le délai d’expiration de l’opération.
  • Exemple : l’opération ne s’est pas terminée dans le délai alloué 00:01:00 pour le message objet. (ServiceTimeout).

Résolution

• Le client doit réessayer l’opération.
• Certaines étapes d’une opération expirée peuvent avoir été effectuées. Il est possible qu’une opération expirée ait été écrite dans la région primaire et dans certaines régions secondaires. Si une opération a été écrite dans la région primaire, elle est éventuellement répliquée dans toutes les régions secondaires, quel que soit le délai d’expiration du client.

BadRequest

Cause

• Lors d’un basculement planifié, la région primaire est temporairement définie en lecture seule pour permettre à la région secondaire de rattraper son retard. Si le client tente une opération d’écriture dans la région primaire pendant qu’il est dans cet état temporaire en lecture seule, le client reçoit une exception BadRequest.
  • Exemple : commutateur de rôle de réplication en cours, réplica principal :<entity-name> est ReadOnly.

Résolution

• Le client doit attendre la fin du basculement planifié avant que les opérations d’écriture réussissent.
• Si le basculement planifié prend trop de temps, il est possible de déclencher un basculement forcé à la place.

É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.