Partilhar via

Exceções de mensagens do Barramento de Serviço (preteridas)

  • Artigo

Este artigo lista as exceções do .NET geradas pelas APIs do .NET Framework.

Em 30 de setembro de 2026, desativaremos as bibliotecas do SDK do Barramento de Serviço do Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, que não estão em conformidade com as diretrizes do SDK do Azure. Também encerraremos o suporte ao protocolo SBMP, para que você não possa mais usar esse protocolo após 30 de setembro de 2026. Migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e recursos aprimorados, antes dessa data.

Embora as bibliotecas mais antigas ainda possam ser usadas após 30 de setembro de 2026, elas não receberão mais suporte e atualizações oficiais da Microsoft. Para obter mais informações, consulte o anúncio de aposentadoria de suporte.

Categorias de exceção

As APIs de mensagens geram exceções que podem se enquadrar nas seguintes categorias, juntamente com a ação associada que você pode tomar para tentar corrigi-las. O significado e as causas de uma exceção podem variar dependendo do tipo de entidade de mensagens:

  1. Erro de codificação do usuário (System.ArgumentException, System.InvalidOperationException, System.OperationCanceledException, System.Runtime.Serialization.SerializationException). Ação geral: tente corrigir o código antes de prosseguir.
  2. Erro de instalação/configuração (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException, System.UnauthorizedAccessException. Ação geral: revise sua configuração e altere, se necessário.
  3. Exceções transitórias (Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException). Ação geral: repetir a operação ou notificar os usuários. A RetryPolicy classe no SDK do cliente pode ser configurada para lidar com novas tentativas automaticamente. Para obter mais informações, consulte Diretrizes de novas tentativas.
  4. Outras exceções (System.Transactions.TransactionException, System.TimeoutException, Microsoft.ServiceBus.Messaging.MessageLockLostException, Microsoft.ServiceBus.Messaging.SessionLockLostException). Ação geral: específica para o tipo de exceção; Consulte a tabela na secção seguinte:

Importante

  • O Barramento de Serviço do Azure não tenta novamente uma operação em caso de exceção quando a operação está em um escopo de transação.
  • Para obter orientações de repetição específicas do Barramento de Serviço do Azure, consulte Diretrizes de repetição para o Service Bus.

Tipos de exceção

A tabela a seguir lista os tipos de exceção de mensagens e suas causas, além de anotar as ações sugeridas que você pode tomar.

Tipo de exceção Descrição/Causa/Exemplos Ação sugerida Nota sobre a repetição automática/imediata
TimeoutException O servidor não respondeu à operação solicitada dentro do tempo especificado, que é controlado por OperationTimeout. O servidor pode ter concluído a operação solicitada. Isso pode acontecer devido a atrasos na rede ou em outras infraestruturas. Verifique a consistência do estado do sistema e tente novamente, se necessário. Consulte Exceções de tempo limite. Repetir pode ajudar em alguns casos; Adicione lógica de repetição ao código.
InvalidOperationException A operação de usuário solicitada não é permitida dentro do servidor ou serviço. Consulte a mensagem de exceção para obter detalhes. Por exemplo, Complete() gera essa exceção se a mensagem foi recebida no modo ReceiveAndDelete . Verifique o código e a documentação. Verifique se a operação solicitada é válida. Repetir não ajuda.
OperationCanceledException É feita uma tentativa de invocar uma operação em um objeto que já foi fechado, abortado ou descartado. Em casos raros, a transação ambiental já está descartada. Verifique o código e certifique-se de que ele não invoque operações em um objeto descartado. Repetir não ajuda.
UnauthorizedAccessException O objeto TokenProvider não pôde adquirir um token, o token é inválido ou o token não contém as declarações necessárias para fazer a operação. Verifique se o provedor de token foi criado com os valores corretos. Verifique a configuração do Serviço de Controle de Acesso. Repetir pode ajudar em alguns casos; Adicione lógica de repetição ao código.
ArgumentException
ArgumentNullException
ArgumentOutOfRangeException		 Um ou mais argumentos fornecidos ao método são inválidos.
O URI fornecido para NamespaceManager ou Create contém segmentos de caminho.
O esquema de URI fornecido para NamespaceManager ou Create é inválido.
O valor da propriedade é maior que 32 KB.		 Verifique o código de chamada e certifique-se de que os argumentos estão corretos. Repetir não ajuda.
MessagingEntityNotFoundException A entidade associada à operação não existe ou foi excluída. Certifique-se de que a entidade existe. Repetir não ajuda.
MessageNotFoundException Tente receber uma mensagem com um número de sequência específico. Esta mensagem não foi encontrada. Certifique-se de que a mensagem ainda não foi recebida. Verifique a fila de deadletter para ver se a mensagem foi deadlettered. Repetir não ajuda.
MensagemComunicaçãoExceção O cliente não consegue estabelecer uma conexão com o Service Bus. Verifique se o nome do host fornecido está correto e se o host está acessível.

Se o código for executado em um ambiente com firewall/proxy, verifique se o tráfego para o domínio/endereço IP e as portas do Service Bus não está bloqueado.

 Repetir pode ajudar se houver problemas intermitentes de conectividade.
ServerBusyException O serviço não é capaz de processar a solicitação no momento. O cliente pode esperar por um período de tempo e, em seguida, tentar novamente a operação. O cliente pode tentar novamente após um determinado intervalo. Se uma nova tentativa resultar em uma exceção diferente, verifique o comportamento de repetição dessa exceção.
MessagingException Exceção de mensagens genéricas que pode ser lançada nos seguintes casos:

É feita uma tentativa de criar um QueueClient usando um nome ou caminho que pertence a um tipo de entidade diferente (por exemplo, um tópico).

É feita uma tentativa para enviar uma mensagem maior que 256 KB.

O servidor ou serviço encontrou um erro durante o processamento da solicitação. Consulte a mensagem de exceção para obter detalhes. Geralmente é uma exceção transitória.

O pedido foi encerrado porque a entidade está sendo limitada. Código de erro: 50001, 50002, 50008.

Verifique o código e certifique-se de que apenas objetos serializáveis sejam usados para o corpo da mensagem (ou use um serializador personalizado).

Verifique na documentação os tipos de valor suportados das propriedades e use apenas os tipos suportados.

Verifique a propriedade IsTransient . Se for verdade, você pode tentar novamente a operação.

Se a exceção for devido à limitação, aguarde alguns segundos e tente novamente a operação. O comportamento de repetição é indefinido e pode não ajudar em outros cenários.
MessagingEntityAlreadyExistsException Tente criar uma entidade com um nome que já seja usado por outra entidade nesse namespace de serviço. Exclua a entidade existente ou escolha um nome diferente para a entidade a ser criada. Repetir não ajuda.
QuotaExceededException A entidade de mensagens atingiu seu tamanho máximo permitido ou o número máximo de conexões com um namespace foi excedido. Crie espaço na entidade recebendo mensagens da entidade ou de suas subfilas. Consulte QuotaExceededException. Repetir pode ajudar se as mensagens tiverem sido removidas entretanto.
RuleActionException O Barramento de Serviço retorna essa exceção se você tentar criar uma ação de regra inválida. O Barramento de Serviço anexa essa exceção a uma mensagem com letra morta se ocorrer um erro durante o processamento da ação de regra para essa mensagem. Verifique se a ação da regra está correta. Repetir não ajuda.
FilterException O Barramento de Serviço retorna essa exceção se você tentar criar um filtro inválido. O Service Bus anexa essa exceção a uma mensagem com letras mortas se ocorrer um erro durante o processamento do filtro para essa mensagem. Verifique se o filtro está correto. Repetir não ajuda.
SessionCannotBeLockedException Tente aceitar uma sessão com um ID de sessão específico, mas a sessão está atualmente bloqueada por outro cliente. Certifique-se de que a sessão é desbloqueada por outros clientes. Repetir pode ajudar se a sessão tiver sido liberada nesse ínterim.
TransactionSizeExceededException Muitas operações fazem parte da transação. Reduza o número de operações que fazem parte dessa transação. Repetir não ajuda.
MessagingEntityDisabledException Solicitação de uma operação de tempo de execução em uma entidade desabilitada. Ative a entidade. Repetir pode ajudar se a entidade tiver sido ativada nesse ínterim.
NoMatchingSubscriptionException O Barramento de Serviço retornará essa exceção se você enviar uma mensagem para um tópico que tenha a pré-filtragem habilitada e nenhum dos filtros corresponder. Certifique-se de que pelo menos um filtro corresponde. Repetir não ajuda.
MessageSizeExceededException Uma carga útil de mensagem excede o limite de 256 KB. O limite de 256 KB é o tamanho total da mensagem, que pode incluir propriedades do sistema e qualquer sobrecarga do .NET. Reduza o tamanho da carga útil da mensagem e, em seguida, tente novamente a operação. Repetir não ajuda.
TransactionException A transação ambiente (Transaction.Current) é inválida. Pode ter sido concluída ou abortada. A exceção interna pode fornecer informações adicionais. Repetir não ajuda.
TransactionInDoubtException Uma operação é tentada em uma transação que está em dúvida, ou uma tentativa é feita para confirmar a transação e a transação fica em dúvida. Seu aplicativo deve lidar com essa exceção (como um caso especial), pois a transação pode já ter sido confirmada. -

QuotaExceededException

QuotaExceededException indica que foi excedida uma quota de uma entidade específica.

Nota

Para cotas do Barramento de Serviço, consulte Cotas.

Filas e tópicos

Para filas e tópicos, geralmente é o tamanho da fila. A propriedade error message contém mais detalhes, como no exemplo a seguir:

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

A mensagem afirma que o tópico excedeu seu limite de tamanho, neste caso 1 GB (o limite de tamanho padrão).

Espaços de Nomes

Para namespaces, QuotaExceededException pode indicar que um aplicativo excedeu o número máximo de conexões com um namespace. Por exemplo:

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

Causas comuns

Há duas causas comuns para esse erro: a fila de mensagens mortas e os recetores de mensagens que não funcionam.

  1. Fila de mensagens mortas Um leitor não está conseguindo concluir as mensagens e as mensagens são retornadas para a fila/tópico quando o bloqueio expira. Isso pode acontecer se o leitor encontrar uma exceção que o impeça de chamar BrokeredMessage.Complete. Depois que uma mensagem é lida 10 vezes, ela é movida para a fila de mensagens mortas por padrão. Esse comportamento é controlado pela propriedade QueueDescription.MaxDeliveryCount e tem um valor padrão de 10. À medida que as mensagens se acumulam na fila de letras mortas, elas ocupam espaço.

    Para resolver o problema, leia e conclua as mensagens da fila de mensagens mortas, como faria em qualquer outra fila. Você pode usar o método FormatDeadLetterPath para ajudar a formatar o caminho da fila de mensagens mortas.

  2. O recetor parou. Um destinatário parou de receber mensagens de uma fila ou assinatura. A maneira de identificar isso é examinar a propriedade QueueDescription.MessageCountDetails , que mostra o detalhamento completo das mensagens. Se a propriedade ActiveMessageCount estiver alta ou crescendo, as mensagens não estão sendo lidas tão rápido quanto estão sendo escritas.

TimeoutException

Uma TimeoutException indica que uma operação iniciada pelo utilizador está a demorar mais do que o tempo limite da operação.

Você deve verificar o valor da propriedade ServicePointManager.DefaultConnectionLimit , pois atingir esse limite também pode causar uma TimeoutException.

Espera-se que os tempos limite ocorram durante ou entre as operações de manutenção, como as atualizações de serviço do Service Bus (ou) atualizações do SO nos recursos que executam o serviço. Durante as atualizações de SO, as entidades são movidas e os nós são atualizados ou reiniciados, o que pode causar tempos limite. Para obter detalhes sobre o contrato de nível de serviço (SLA) para o serviço Azure Service Bus, veja SLA para o Service Bus.

Filas e tópicos

Para filas e tópicos, o tempo limite é especificado na propriedade MessagingFactorySettings.OperationTimeout , como parte da cadeia de conexão, ou por meio de ServiceBusConnectionStringBuilder. A mensagem de erro em si pode variar, mas sempre contém o valor de tempo limite especificado para a operação atual.

MessageLockLostException

Causa

O MessageLockLostException é lançado quando uma mensagem é recebida usando o modo de recebimento PeekLock e o bloqueio mantido pelo cliente expira no lado do serviço.

O bloqueio de uma mensagem pode expirar devido a vários motivos:

  • O temporizador de bloqueio expirou antes de ser renovado pelo aplicativo cliente.
  • O aplicativo cliente adquiriu o bloqueio, salvou-o em um armazenamento persistente e, em seguida, reiniciado. Uma vez reiniciado, o aplicativo cliente olhou para as mensagens de bordo e tentou concluí-las.

Você também pode receber essa exceção nos seguintes cenários:

  • Atualização do Serviço
  • Atualização do SO
  • Alterar propriedades na entidade (fila, tópico, assinatura) enquanto mantém o bloqueio.

Resolução

Quando um aplicativo cliente recebe MessageLockLostException, ele não pode mais processar a mensagem. O aplicativo cliente pode, opcionalmente, considerar registrar a exceção para análise, mas o cliente deve descartar a mensagem.

Como o bloqueio da mensagem expirou, ela voltaria para a Fila (ou Assinatura) e poderia ser processada pelo próximo aplicativo cliente que as chamadas recebessem.

Se o MaxDeliveryCount tiver excedido, a mensagem pode ser movida para o DeadLetterQueue.

SessionLockLostException

Causa

O SessionLockLostException é lançado quando uma sessão é aceita e o bloqueio mantido pelo cliente expira no lado do serviço.

O bloqueio de uma sessão pode expirar devido a vários motivos:

  • O temporizador de bloqueio expirou antes de ser renovado pelo aplicativo cliente.
  • O aplicativo cliente adquiriu o bloqueio, salvou-o em um armazenamento persistente e, em seguida, reiniciado. Depois de reiniciado, o aplicativo cliente olhou para as sessões de bordo e tentou processar as mensagens nessas sessões.

Você também pode receber essa exceção nos seguintes cenários:

  • Atualização do Serviço
  • Atualização do SO
  • Alterar propriedades na entidade (fila, tópico, assinatura) enquanto mantém o bloqueio.

Resolução

Quando um aplicativo cliente recebe SessionLockLostException, ele não pode mais processar as mensagens na sessão. O aplicativo cliente pode considerar registrar a exceção para análise, mas o cliente deve descartar a mensagem.

Como o bloqueio na sessão expirou, ele voltaria para a Fila (ou Assinatura) e pode ser bloqueado pelo próximo aplicativo cliente que aceita a sessão. Como o bloqueio de sessão é mantido por um único aplicativo cliente a qualquer momento, o processamento em ordem é garantido.

SocketException

Causa

Um SocketException é lançado nos seguintes casos:

  • Quando uma tentativa de conexão falha porque o host não respondeu corretamente após um tempo especificado (código de erro TCP 10060).
  • Uma conexão estabelecida falhou porque o host conectado não respondeu.
  • Ocorreu um erro ao processar a mensagem ou o tempo limite é excedido pelo anfitrião remoto.
  • Problema subjacente de recursos de rede.

Resolução

Os erros SocketException indicam que a VM que hospeda os aplicativos não consegue converter o nome <mynamespace>.servicebus.windows.net para o endereço IP correspondente.

Verifique se o comando a seguir consegue mapear para um endereço IP.

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

O que deve fornecer uma saída como:

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

Se o nome acima não resolver para um IP e o alias de namespace, verifique com o administrador da rede para investigar mais. A resolução de nomes é feita através de um servidor DNS, normalmente um recurso na rede do cliente. Se a resolução de DNS for feita pelo DNS do Azure, entre em contato com o suporte do Azure.

Se a resolução de nomes funcionar conforme o esperado, verifique se as conexões com o Barramento de Serviço do Azure são permitidas aqui.

MessagingException

Causa

MessagingException é uma exceção genérica que pode ser lançada por vários motivos. Algumas das razões são:

  • É feita uma tentativa de criar um QueueClient em um tópico ou uma assinatura.
  • O tamanho da mensagem enviada é maior do que o limite para uma determinada camada. Leia mais sobre as cotas e limites do Service Bus.
  • A solicitação de plano de dados específico (enviar, receber, concluir, abandonar) foi encerrada devido à limitação.
  • Problemas transitórios causados devido a atualizações e reinicializações do serviço.

Nota

A lista de exceções acima referida não é exaustiva.

Resolução

As etapas de resolução dependem do que causou o lançamento de MessagingException .

  • Para problemas transitórios (onde isTransient está definido como true) ou para problemas de limitação, tentar novamente a operação pode resolvê-lo. A política de repetição padrão no SDK pode ser usada para isso.
  • Para outras questões, os detalhes na exceção indicam que as etapas de problema e resolução podem ser deduzidas do mesmo.

StorageQuotaExceededException

Causa

O StorageQuotaExceededException é gerado quando o tamanho total das entidades em um namespace premium excede o limite de 1 TB por unidade de mensagens.

Resolução

  • Aumentar o número de unidades de mensagens atribuídas ao namespace premium
  • Se você já estiver usando unidades de mensagens máximas permitidas para um namespace, crie um namespace separado.

Próximos passos

Para obter a referência completa da API .NET do Service Bus, consulte a referência da API do Azure .NET. Para obter dicas de solução de problemas, consulte o Guia de solução de problemas.