Usar a biblioteca herdada do WindowsAzure.ServiceBus .NET Framework com o AMQP 1.0
Observação
Este artigo é destinado a usuários existentes do pacote WindowsAzure.ServiceBus que desejam alternar para o uso do AMQP dentro do mesmo pacote. Embora esse pacote continue recebendo correções de bug críticas até 30 de setembro de 2026, incentivamos fortemente a atualizar para o novo pacote Azure.Messaging.ServiceBus, que está disponível a partir de novembro de 2020 e que dá suporte ao AMQP por padrão.
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. 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, confira o anúncio de desativação do suporte.
Por padrão, o pacote WindowsAzure.ServiceBus se comunica com o serviço Barramento de Serviço usando um protocolo dedicado baseado em SOAP chamado Protocolo de Mensagens do Barramento de Serviço (SBMP). Na versão 2.1, foi adicionado suporte para AMQP 1.0, que recomendamos em vez do protocolo padrão.
Para usar o AMQP 1.0 em vez do protocolo padrão, é necessário uma configuração explícita na cadeia de conexão do Barramento de Serviço ou nos construtores do cliente por meio da opção TransportType. Além dessa alteração, o código do aplicativo permanece inalterado ao usar o AMQP 1.0.
Existem alguns outros recursos da API que não têm suporte com o uso do AMQP. Esses recursos sem suporte são listados na seção Diferenças de comportamento. Algumas das definições de configuração avançadas também apresentam um significado diferente com o uso do AMQP.
Configurar a cadeia de conexão para usar o AMQP 1.0
Adeque sua cadeia de conexão com ;TransportType=Amqp para instruir o cliente a fazer sua conexão com o Barramento de Serviço usando o AMQP 1.0.
Por exemplo,
Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=Amqp
Onde namespace e SAS key são obtidos a partir de Portal do Azure quando você cria um namespace do Barramento de Serviço. Para saber mais, veja Como criar um namespace do Barramento de Serviço usando o Portal do Azure.
AMQP sobre WebSockets
Para usar o AMQP em WebSockets, defina TransportType na cadeia de conexão como AmqpWebSockets. Por exemplo: Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=AmqpWebSockets.
Serialização de mensagem
Ao usar o protocolo padrão, o comportamento de serialização padrão da biblioteca de cliente .NET é usar o tipo DataContractSerializer para serializar uma instância BrokeredMessage para transporte entre a biblioteca de cliente e o serviço de Barramento de Serviço. Ao usar o modo de transporte do AMQP, a biblioteca de cliente usa o sistema do tipo AMQP para a serialização da mensagem agenciada em uma mensagem do AMQP. Essa serialização permite que a mensagem seja recebida e interpretada por um aplicativo receptor que está potencialmente em execução em uma plataforma diferente, por exemplo, um aplicativo Java que usa a API JMS para acessar o Barramento de Serviço.
Quando você constrói uma instância BrokeredMessage, você pode fornecer um objeto .NET como um parâmetro para o construtor para servir como o corpo da mensagem. Para objetos que podem ser mapeados para tipos primitivos do AMQP, o corpo é serializado em tipos de dados do AMQP. Se o objeto não pode ser mapeado diretamente para um tipo primitivo do AMQP; ou seja, um tipo personalizado definido pelo aplicativo, então, o objeto é serializado usando o DataContractSerializer, e os bytes serializados são enviados em uma mensagem de dados AMQP.
Para facilitar a interoperabilidade com clientes não .NET, use somente tipos .NET que podem ser serializados diretamente em tipos do AMQP para o corpo da mensagem. A tabela a seguir detalha os tipos e o mapeamento correspondente ao sistema de tipos do AMQP.
| Tipo de objeto de corpo .NET | Tipo do AMQP mapeado | Tipo de seção de corpo do AMQP |
|---|---|---|
| bool | booleano | Valor do AMQP |
| byte | ubyte | Valor do AMQP |
| ushort | ushort | Valor do AMQP |
| uint | uint | Valor do AMQP |
| ulong | ulong | Valor do AMQP |
| sbyte | byte | Valor do AMQP |
| short | short | Valor do AMQP |
| INT | INT | Valor do AMQP |
| long | long | Valor do AMQP |
| FLOAT | FLOAT | Valor do AMQP |
| double | double | Valor do AMQP |
| decimal | decimal128 | Valor do AMQP |
| char | char | Valor do AMQP |
| Datetime | timestamp | Valor do AMQP |
| Guid | uuid | Valor do AMQP |
| byte[] | binary | Valor do AMQP |
| string | string | Valor do AMQP |
| System.Collections.IList | list | Valor AMQP: os itens contidos na coleção só podem ser aqueles definidos nesta tabela. |
| System.Array | array | Valor AMQP: os itens contidos na coleção só podem ser aqueles definidos nesta tabela. |
| System.Collections.IDictionary | mapa | Valor AMQP: os itens contidos na coleção só podem ser aqueles definidos nesta tabela. Observação: apenas as chaves de cadeia de caracteres são suportadas. |
| Uri | Cadeia de caracteres descrita (consulte a tabela a seguir) | Valor do AMQP |
| DateTimeOffset | Longo descrito (consulte a tabela a seguir) | Valor do AMQP |
| TimeSpan | Longo descrito (consulte a seguir) | Valor do AMQP |
| STREAM | binary | Dados do AMQP (podem ser múltiplos). As seções de Dados contêm os bytes brutos lidos do objeto Stream. |
| Outro Objeto | binary | Dados do AMQP (podem ser múltiplos). Contém o binário serializado do objeto que usa o DataContractSerializer ou um serializador fornecido pelo aplicativo. |
| Tipo .NET | Tipo descrito do AMQP mapeado | Observações |
|---|---|---|
| Uri | <type name=”uri” class=restricted source=”string”> <descriptor name=”com.microsoft:uri” /></type> |
URI.AbsoluteUri |
| DateTimeOffset | <type name=”datetime-offset” class=restricted source=”long”> <descriptor name=”com.microsoft:datetime-offset” /></type> |
DateTimeOffset.UtcTicks |
| TimeSpan | <type name=”timespan” class=restricted source=”long”> <descriptor name=”com.microsoft:timespan” /></type> |
TimeSpan.Ticks |
Diferenças de comportamento
Há algumas pequenas diferenças no comportamento da API WindowsAzure.ServiceBus ao usar AMQP, em comparação com o protocolo padrão:
- A propriedade OperationTimeout será ignorada.
MessageReceiver.Receive(TimeSpan.Zero)é implementado comoMessageReceiver.Receive(TimeSpan.FromSeconds(10)).- Só é possível concluir mensagens com tokens de bloqueio pelos destinatários de mensagem que inicialmente receberam as mensagens.
Controlar configurações de protocolo do AMQP
As APIs .NET expõem diversas configurações que controlam o comportamento do protocolo AMQP:
- MessageReceiver.PrefetchCount: controla o crédito inicial aplicado a um link. O padrão é 0.
- MessagingFactorySettings.AmqpTransportSettings.MaxFrameSize: controla o tamanho máximo do quadro do AMQP oferecido durante a negociação em tempo de conexão aberta. O padrão é de 65.536 bytes.
- MessagingFactorySettings.AmqpTransportSettings.BatchFlushInterval: caso as transferências possam ser em lote, esse valor determina o atraso máximo para envio de disposições. Herdado pelos remetentes/destinatários por padrão. O remetente/destinatário individual pode substituir o padrão, que é 20 milissegundos.
- MessagingFactorySettings.AmqpTransportSettings.UseSslStreamSecurity : controla se as conexões do AMQP são estabelecidas por uma conexão TLS. O padrão é true.
Próximas etapas
Está pronto(a) para saber mais? Visite os links a seguir: