Guia de solução de problemas do Barramento de Serviço do Microsoft Azure

  • Artigo

Este artigo fornece dicas de solução de problemas e recomendações para alguns problemas que você vê quando usa o Barramento de Serviço do Azure.

Problemas de conectividade

Atingir tempo limite durante a conexão com o serviço

Dependendo da rede e do ambiente de host, um problema de conectividade pode se apresentar aos aplicativos como um TimeoutException, OperationCanceledExceptionou um ServiceBusException com Reason de ServiceTimeout e, geralmente, ocorre quando o cliente não consegue encontrar um caminho de rede para o serviço.

Para solucionar problemas:

  • Verifique se a cadeia de conexão ou o nome de domínio totalmente qualificado que você especificou ao criar o cliente está correto. Para obter informações sobre como adquirir uma cadeia de conexão, consulte Obter uma cadeia de conexão do Barramento de Serviço.
  • Verifique as permissões de firewall e porta em seu ambiente de hospedagem. Verifique se as portas 5671 e 5672 do AMQP (Advanced Message Queuing Protocol) estão abertas e se o ponto de extremidade é permitido por meio do firewall.
  • Tente usar a opção de transporte do Socket Web, que se conecta usando a porta 443. Para obter detalhes, consulte Configurar o transporte.
  • Veja se a rede está bloqueando endereços IP específicos. Para obter detalhes, consulte Quais endereços IP preciso permitir?
  • Se aplicável, verifique a configuração do proxy. Para obter detalhes, consulte: Configurar o transporte
  • Para obter mais informações sobre como solucionar problemas de conectividade de rede, consulte: [Problemas de conectividade, certificado ou tempo limite][#connectivity-certificate-or-timeout-issues].

Falhas de handshake do protocolo SSL

Esse erro pode ocorrer quando um proxy de interceptação é usado. Para verificar, é recomendável testar o aplicativo no ambiente de host com o proxy desabilitado.

Erros de esgotamento do soquete

Os aplicativos devem preferir tratar os tipos de Barramento de Serviço como singletons, criando e usando uma única instância durante o tempo de vida do aplicativo. Cada novo ServiceBusClient criou resultados em uma nova conexão AMQP, que usa um soquete. O tipo ServiceBusClient gerencia a conexão para todos os tipos criados a partir dessa instância. Cada ServiceBusReceiver, ServiceBusSessionReceiver, ServiceBusSender e ServiceBusProcessor gerenciam seu próprio link AMQP para a entidade do Barramento de Serviço associada. Quando você usa ServiceBusSessionProcessor, vários links AMQP são estabelecidos dependendo do número de sessões que estão sendo processadas simultaneamente.

Os clientes estão seguros para armazenar em cache quando ociosos; eles garantem um gerenciamento eficiente de rede, CPU e uso de memória, minimizando o impacto desses recursos durante períodos de inatividade. Também é importante que CloseAsync ou DisposeAsync seja chamado quando um cliente não for mais necessário para garantir a limpeza correta dos recursos de rede.

A adição de componentes à cadeia de conexão não funciona

A geração atual da biblioteca de clientes do Barramento de Serviço dá suporte a cadeias de conexão somente no formulário publicado pelo portal do Azure. As cadeias de conexão fornecem apenas informações básicas de localização e chave compartilhada. A configuração do comportamento dos clientes é feita por meio de suas opções.

As gerações anteriores dos clientes do Barramento de Serviço permitiram que algum comportamento fosse configurado adicionando componentes de chave/valor a uma cadeia de conexão. Esses componentes não são mais reconhecidos e não têm efeito sobre o comportamento do cliente.

"TransportType=AmqpWebSockets" alternativo

Para configurar os Soquetes Web como o tipo de transporte, consulte Configurar o transporte.

"Authentication=Managed Identity" alternativo

Para autenticar com a Identidade Gerenciada, consulte: Identidade e credenciais de acesso compartilhado. Para obter mais informações sobre a biblioteca Azure.Identity, consulte Autenticação e SDK do Azure.

Logon e diagnósticos

A biblioteca de clientes do Barramento de Serviço é totalmente instrumentada para registrar informações em log em vários níveis de detalhes usando EventSource do .NET para emitir informações. O registro em log é executado para cada operação e segue o padrão de marcação do ponto de partida da operação, sua conclusão e quaisquer exceções encontradas. Informações adicionais que podem oferecer insights também são registradas no contexto da operação associada.

Habilitar o registro em log

Os logs de cliente do Barramento de Serviço estão disponíveis para qualquer EventListener optando pelas fontes começando com Azure-Messaging-ServiceBus ou por todas as fontes que têm a característica AzureEventSource. Para facilitar a captura de logs das bibliotecas de clientes do Azure, a biblioteca Azure.Core usada pelo Barramento de Serviço oferece um AzureEventSourceListener.

Para obter mais informações, confira Registrar em log com o SDK do Azure para .NET.

Rastreamento distribuído

A biblioteca de clientes do Barramento de Serviço dá suporte ao rastreamento distribuído por meio da integração com o SDK do Application Insights. Também tem suporte experimental para a especificação OpenTelemetry por meio do tipo ActivitySource do .NET introduzido no .NET 5. Para habilitar o suporte a ActivitySource para uso com o OpenTelemetry, consulte Suporte ao ActivitySource.

Para usar o suporte ao DiagnosticActivity de GA, você pode se integrar ao SDK do Application Insights. Mais detalhes podem ser encontrados no ApplicationInsights com o Azure Monitor.

A biblioteca cria os seguintes intervalos:

Message
ServiceBusSender.Send
ServiceBusSender.Schedule
ServiceBusSender.Cancel
ServiceBusReceiver.Receive
ServiceBusReceiver.ReceiveDeferred
ServiceBusReceiver.Peek
ServiceBusReceiver.Abandon
ServiceBusReceiver.Complete
ServiceBusReceiver.DeadLetter
ServiceBusReceiver.Defer
ServiceBusReceiver.RenewMessageLock
ServiceBusSessionReceiver.RenewSessionLock
ServiceBusSessionReceiver.GetSessionState
ServiceBusSessionReceiver.SetSessionState
ServiceBusProcessor.ProcessMessage
ServiceBusSessionProcessor.ProcessSessionMessage
ServiceBusRuleManager.CreateRule
ServiceBusRuleManager.DeleteRule
ServiceBusRuleManager.GetRules

A maioria dos intervalos são autoexplicativos, iniciados e interrompidos durante a operação que leva seu nome. O intervalo que une os outros é Message. O modo de rastreamento da mensagem é feito por meio do Diagnostic-Id definido na propriedade ServiceBusMessage.ApplicationProperties pela biblioteca durante operações de envio e agendamento. No Application Insights, os intervalos de Message são exibidos como vinculação aos vários outros intervalos que foram usados para interagir com a mensagem, por exemplo, os intervalos de ServiceBusReceiver.Receive, ServiceBusSender.Send e ServiceBusReceiver.Complete seriam todos vinculados do intervalo de Message. Aqui está um exemplo de como isso acontece no Application Insights:

Image showing a sample distributed trace.

Na captura de tela acima, você vê a transação de ponta a ponta que pode ser exibida no Application Insights no portal. Nesse cenário, o aplicativo está enviando mensagens e usando o ServiceBusSessionProcessor para processá-las. A atividade Message está vinculada a ServiceBusSender.Send, ServiceBusReceiver.Receive, ServiceBusSessionProcessor.ProcessSessionMessage e ServiceBusReceiver.Complete.

Observação

Para obter mais informações, confira Rastreamento distribuído e correlação por meio de mensagens do Barramento de Serviço.

Solucionar problemas de remetentes

Não é possível enviar um lote com várias chaves de partição

Quando um aplicativo envia um lote para uma entidade habilitada para partição, todas as mensagens incluídas em uma única operação de envio devem ter a mesma PartitionKey. Se a entidade estiver habilitada para sessão, o mesmo requisito será válido para a propriedade SessionId. Para enviar mensagens com valores PartitionKey ou SessionId diferentes, agrupe as mensagens em instâncias ServiceBusMessageBatch separadas ou inclua-as em chamadas separadas para a sobrecarga de SendMessagesAsync que usa um conjunto de instâncias de ServiceBusMessage.

O lote falha ao enviar

Um lote de mensagens é ServiceBusMessageBatch contendo duas ou mais mensagens ou uma chamada para SendMessagesAsync em que duas ou mais mensagens são passadas. O serviço não permite que um lote de mensagens exceda 1 MB. Esse comportamento é verdadeiro se o recurso de Suporte a mensagens grandes Premium está habilitado. Se você pretende enviar uma mensagem maior que 1 MB, ela deve ser enviada individualmente em vez de agrupada com outras mensagens. Infelizmente, o tipo ServiceBusMessageBatch não dá suporte no momento à validação de que um lote não contém mensagens maiores que 1 MB, pois o tamanho é limitado pelo serviço e pode ser alterado. Portanto, se você pretende usar o recurso de suporte a mensagens grandes Premium, precisa garantir o envio de mensagens com mais de 1 MB individualmente.

Solucionar problemas de receptor

O número de mensagens retornadas não corresponde ao número solicitado no recebimento em lote

Ao tentar fazer uma operação de recebimento em lotes, ou seja, passar um valor maxMessages de dois ou mais para o método ReceiveMessagesAsync, você não terá a garantia de receber o número de mensagens solicitadas, mesmo que a fila ou assinatura tenha tantas mensagens disponíveis no momento e mesmo que todo o maxWaitTime configurado ainda não tenha decorrido. Para maximizar a taxa de transferência e evitar a expiração do bloqueio, assim que a primeira mensagem chegar pela rede, o receptor aguardará mais 20 milissegundos por mensagens adicionais antes de expedir as mensagens para processamento. O maxWaitTime controla quanto tempo o receptor aguardará para receber a primeira mensagem – as mensagens subsequentes serão aguardadas por 20 milissegundos. Portanto, seu aplicativo não deve assumir que todas as mensagens disponíveis serão recebidas em uma chamada.

O bloqueio de mensagem ou sessão é perdido antes do tempo de expiração do bloqueio

O serviço de Barramento de Serviço usa o protocolo AMQP, que conta com estado. Devido à natureza do protocolo, se o link que conecta o cliente e o serviço for desanexado depois que uma mensagem for recebida, mas antes de ela ser estabelecida, ela não poderá ser estabelecida ao reconectar o link. Os links podem ser desanexados devido a uma falha de rede transitória de curto prazo, uma interrupção de rede ou devido ao tempo limite ocioso de 10 minutos imposto pelo serviço. A reconexão do link ocorre automaticamente como parte de qualquer operação que exija o link, ou seja, o estabelecimento ou recebimento de mensagens. Nessa situação, você recebe um ServiceBusException com Reason de MessageLockLost ou SessionLockLost mesmo que o tempo de expiração do bloqueio ainda não tenha passado.

Como procurar mensagens agendadas ou adiadas

Mensagens agendadas e adiadas são incluídas ao espiar mensagens. Elas podem ser identificadas pela propriedade ServiceBusReceivedMessage.State. Depois de ter o SequenceNumber de uma mensagem adiada, você pode recebê-la com um bloqueio por meio do método ReceiveDeferredMessagesAsync.

Ao trabalhar com tópicos, você não pode espiar mensagens agendadas na assinatura, pois as mensagens permanecem no tópico até a hora de enfileiramento agendada. Como solução alternativa, você pode construir um ServiceBusReceiver passando o nome do tópico para espiar essas mensagens. Nenhuma outra operação com o receptor funciona ao usar um nome de tópico.

Como procurar mensagens de sessão em todas as sessões

Você pode usar um serviceBusReceiver regular para espiar todas as sessões. Para espiar uma sessão específica, você poderá usar o ServiceBusSessionReceiver, mas precisará obter um bloqueio de sessão.

NotSupportedException gerado ao acessar o corpo da mensagem

Esse problema ocorre com mais frequência em cenários de interoperabilidade ao receber uma mensagem enviada de uma biblioteca diferente que usa um formato de corpo de mensagem AMQP diferente. Se você estiver interagindo com esses tipos de mensagens, consulte a Amostra do corpo da mensagem AMQP para saber como acessar o corpo da mensagem.

Solucionar problemas do processador

A renovação do bloqueio automático não está funcionando

A renovação do bloqueio automático depende do tempo do sistema para determinar quando renovar um bloqueio para uma mensagem ou sessão. Caso a hora do sistema não seja precisa, por exemplo, seu relógio está lento, então a renovação do bloqueio pode não acontecer antes que o bloqueio seja perdido. Verifique se o tempo do sistema é preciso se a renovação do bloqueio automático não estiver funcionando.

O processador parece travar ou ter problemas de latência ao usar alta simultaneidade

Esse comportamento geralmente é causado pela falta de thread, especialmente ao usar o processador de sessão e usar um valor muito alto para MaxConcurrentSessions, em relação ao número de núcleos no computador. Inicialmente, verifique se você não está fazendo sync-over-async em nenhum dos manipuladores de eventos. Sync-over-async é uma maneira fácil de causar deadlocks e falta de threads. Mesmo que você não esteja fazendo sync-over-async, qualquer código de sincronização pura em seus manipuladores pode contribuir para a falta de threads. Se você determinou que esse não é o problema, por exemplo, porque tem código assíncrono puro, pode tentar aumentar o [TryTimeout][TryTimeout]. Isso alivia a pressão sobre o pool de threads, reduzindo o número de alternâncias de contexto e tempos limite que ocorrem, especialmente ao usar o processador de sessão. O valor padrão para [TryTimeout][TryTimeout] é de 60 segundos, mas pode ser definido até 1 hora. É recomendável testar com o TryTimeout definido como 5 minutos como ponto de partida e iterar a partir daí. Se nenhuma dessas sugestões funcionar, você simplesmente precisará escalar horizontalmente para vários hosts, reduzindo a simultaneidade no aplicativo, mas executando o aplicativo em vários hosts para alcançar a simultaneidade geral desejada.

Leitura adicional:

O processador de sessão leva muito tempo para alternar sessões

Isso pode ser configurado usando o [SessionIdleTimeout][SessionIdleTimeout], que informa ao processador quanto tempo esperar para receber uma mensagem de uma sessão, antes de desistir e mover para outra. Isso será útil se você tiver muitas sessões preenchidas esparsamente, em que cada sessão tenha apenas algumas mensagens. Se você espera que cada sessão tenha muitas mensagens, definir isso com um valor muito baixo pode ser contraproducente, pois resultará no fechamento desnecessário da sessão.

O processador é interrompido imediatamente

Isso geralmente é observado em cenários de demonstração ou teste. StartProcessingAsync retorna imediatamente após o processador ser iniciado. Chamar esse método não bloqueará e manterá seu aplicativo ativo enquanto o processador estiver em execução, portanto, você precisará de algum outro mecanismo para fazer isso. Para demonstrações ou testes, basta adicionar uma chamada Console.ReadKey() depois de iniciar o processador. Em cenários de produção, você provavelmente desejará usar algum tipo de integração de estrutura, como [BackgroundService][BackgroundService], para fornecer ganchos convenientes de ciclo de vida do aplicativo que podem ser usados para iniciar e descartar o processador.

Solucionar problemas de transações

Para obter informações gerais sobre transações no Barramento de Serviço, consulte [Visão geral do processamento de transações do Barramento de Serviço][Transações].

Operações com suporte

Nem todas as operações são aceitas durante o uso de transações. Para ver a lista de transações compatíveis, consulte [Operações dentro de um escopo de transação][TransactionOperations].

Tempo limite

Uma transação atinge o tempo limite após um [período de tempo][TransactionTimeout], portanto, é importante que o processamento que ocorre dentro de um escopo de transação cumpra esse tempo limite.

As operações em uma transação não são repetidas

Isso ocorre por design. Considere o cenário a seguir – você está tentando concluir uma mensagem dentro de uma transação, mas há algum erro transitório que ocorre, por exemplo, ServiceBusException com um Reason de ServiceCommunicationProblem. Suponha que a solicitação realmente faça isso no serviço. Se o cliente tentar novamente, o serviço verá duas solicitações completas. A primeira solicitação completa não será finalizada até que a transação seja confirmada. A segunda não pode nem ser avaliada antes da conclusão da primeira. A transação no cliente está aguardando a conclusão completa. Isso cria um deadlock em que o serviço está aguardando o cliente concluir a transação, mas o cliente está aguardando o serviço reconhecer a segunda operação completa. A transação acabará após 2 minutos, mas essa é uma experiência ruim do usuário. Por esse motivo, não tentamos novamente as operações dentro de uma transação.

Transações entre entidades não estão funcionando

Para executar transações que envolvam várias entidades, você precisará definir a propriedade ServiceBusClientOptions.EnableCrossEntityTransactions como true. Para obter detalhes, consulte a amostra de [Transações entre entidades][CrossEntityTransactions].

Cotas

Informações sobre cotas do Barramento de Serviço podem ser encontradas [aqui][ServiceBusQuotas].

Problemas de conectividade, certificado ou tempo limite

As etapas a seguir podem ajudá-lo a solucionar problemas de conectividade/certificado/tempo limite para todos os serviços em *.servicebus.windows.net.

  • Acesse o wgethttps://<yournamespace>.servicebus.windows.net/. Ele ajuda a verificar se você tem problemas de filtragem de IP ou de rede virtual ou de cadeia de certificados, que são mais comuns ao usar o SDK do Java.

    Um exemplo de mensagem de ação bem-sucedida:

    <feed xmlns="http://www.w3.org/2005/Atom"><title type="text">Publicly Listed Services</title><subtitle type="text">This is the list of publicly-listed services currently available.</subtitle><id>uuid:27fcd1e2-3a99-44b1-8f1e-3e92b52f0171;id=30</id><updated>2019-12-27T13:11:47Z</updated><generator>Service Bus 1.1</generator></feed>

    Um exemplo de mensagem de erro de falha:

    <Error>
    <Code>400</Code>
    <Detail>
        Bad Request. To know more visit https://aka.ms/sbResourceMgrExceptions. . TrackingId:b786d4d1-cbaf-47a8-a3d1-be689cda2a98_G22, SystemTracker:NoSystemTracker, Timestamp:2019-12-27T13:12:40
    </Detail>
</Error>

  • Execute o comando a seguir para verificar se alguma porta está bloqueada no firewall. As portas usadas são 443 (HTTPS), 5671 e 5672 (AMQP) e 9354 (Net Messaging/SBMP). Dependendo da biblioteca que você usa, outras portas também são usadas. Aqui está o exemplo de comando que verifica se a porta 5671 está bloqueada. C

    tnc <yournamespacename>.servicebus.windows.net -port 5671

    No Linux:

    telnet <yournamespacename>.servicebus.windows.net 5671

  • Quando houver problemas de conectividade intermitente, execute o seguinte comando para verificar se há algum pacote descartado. Este comando tenta estabelecer 25 conexões TCP diferentes a cada 1 segundo com o serviço. Em seguida, você pode verificar quantos deles tiveram êxito/falharam e também ver a latência da conexão TCP. Você pode baixar a ferramenta pspingpsping.

    .\psping.exe -n 25 -i 1 -q <yournamespace>.servicebus.windows.net:5671 -nobanner

    Você pode usar comandos equivalentes se estiver usando outras ferramentas, como tnc, ping e assim sucessivamente.

  • Obtenha um rastreamento de rede se as etapas anteriores não ajudarem e analise-o usando ferramentas como o Wireshark. Entre em contato com o Suporte da Microsoft, se necessário.

  • Para localizar os endereços IP certos para adicionar à lista de permitidos para suas conexões, confira Quais endereços IP preciso adicionar à lista de permitidos.

Em 30 de setembro de 2026, desativaremos o suporte do protocolo SBMP para o Barramento de Serviço do Azure, portanto, não será mais possível usar esse protocolo após essa data. Migre para as bibliotecas mais recentes do SDK do Barramento de Serviço do Azure usando o protocolo AMQP, que oferece atualizações de segurança críticas e funcionalidades aprimoradas, antes dessa data.

Para obter mais informações, confira o anúncio de desativação do suporte.

Problemas que podem ocorrer com atualizações/reinicializações de serviço

Sintomas

  • As solicitações podem ficar momentaneamente limitadas.
  • Pode haver uma queda nas mensagens/solicitações de entrada.
  • O arquivo de log pode conter mensagens de erro.
  • Os aplicativos podem ser desconectados do serviço por alguns segundos.

Causa

As atualizações e reinicializações do serviço de back-end podem causar esses problemas nos seus aplicativos.

Resolução

Se o código do aplicativo utilizar o SDK, a política de repetição já estará interna e ativa. O aplicativo se reconecta sem impacto significativo sobre o aplicativo/fluxo de trabalho.

Acesso não autorizado: as declarações de envio são necessárias

Sintomas

Você pode ver esse erro ao tentar acessar um tópico do Barramento de Serviço do Visual Studio em um computador local usando uma identidade gerenciada atribuída pelo usuário com permissões de envio.

Service Bus Error: Unauthorized access. 'Send' claim\(s\) are required to perform this operation.

Causa

A identidade não tem permissões para acessar o tópico do Barramento de Serviço.

Resolução

Para resolver esse erro, instale a biblioteca Microsoft.Azure.Services.AppAuthentication. Para saber mais, confira Autenticação de desenvolvimento local.

Para saber como atribuir permissões a funções, confira Autenticar uma identidade gerenciada com o Microsoft Entra ID para acessar os recursos do Barramento de Serviço do Azure.

Exceção do Barramento de Serviço: falha no token put

Sintomas

Você vê a seguinte mensagem de erro:

Microsoft.Azure.ServiceBus.ServiceBusException: Put token failed. status-code: 403, status-description: The maximum number of '1000' tokens per connection has been reached.

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, portanto, ele não poderá mais ser usado após 30 de setembro de 2026. Antes dessa data, migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e funcionalidades aprimoradas.

Embora as bibliotecas mais antigas ainda poderão 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, confira o anúncio de desativação do suporte.

Causa

O número de tokens de autenticação para links simultâneos em uma conexão com um namespace do Barramento de Serviço excedeu o limite: 1000.

Resolução

Siga uma das etapas a seguir:

  • Reduzir o número de links simultâneos em uma conexão ou usar uma nova conexão
  • Usar SDKs do Barramento de Serviço do Azure, o que garante que você não entre nessa situação (recomendado)

Os bloqueios de recursos não funcionam ao usar o SDK do plano de dados

Sintomas

Você configurou um bloqueio de exclusão em um namespace do Barramento de Serviço, mas pode excluir recursos no namespace (filas, tópicos etc.) usando o Service Bus Explorer.

Causa

O bloqueio de recursos é preservado no Azure Resource Manager (painel de controle) e não impede que a chamada do SDK do plano de dados exclua o recurso diretamente a partir do namespace. O Service Bus Explorer usa o SDK do plano de dados, portanto, a exclusão é realizada.

Resolução

Recomendamos que você use a API baseada no Azure Resource Manager por meio de portal do Azure, PowerShell, CLI ou modelo do Resource Manager para excluir entidades, de modo que o bloqueio de recursos impeça que os recursos sejam excluídos acidentalmente.

A entidade não está mais disponível

Sintomas

Você vê um erro informando que a entidade não está mais disponível.

Causa

O recurso pode ter sido excluído. Siga estas etapas para identificar por que a entidade foi excluída.

  • Verifique o log de atividades para ver se há uma solicitação de exclusão do Azure Resource Manager.
  • Verifique o log operacional para ver se houve uma chamada direta à API para exclusão. Para saber como coletar um log operacional, consulte Coleta e roteamento. Para obter o esquema e um exemplo de um log de operações, consulte Logs de operação
  • Verifique o log de operações para ver se houve uma exclusão relacionada à autodeleteonidle.

Próximas etapas

Veja os artigos a seguir:

  • Exceções do Azure Resource Manager. Lista as exceções geradas na interação com o Barramento de Serviço do Azure usando modelos do Azure Resource Manager ou chamadas diretas.
  • Exceções de mensagens. Fornece uma lista de exceções geradas pelo .NET Framework para o Barramento de Serviço do Azure.