Início Rápido: enviar e receber mensagens em filas do Barramento de Serviço do Azure (.NET)

Neste guia de início rápido, você vai realizar as seguintes etapas:

1. Crie um namespace do Barramento de Serviço usando o portal do Azure.

2. Crie uma fila do Barramento de Serviço usando o portal do Azure.

3. Escreva um aplicativo de console .NET para enviar um conjunto de mensagens à fila.

4. Escreva um aplicativo de console .NET para receber essas mensagens da fila.

   Observação

   Este início rápido apresenta instruções passo a passo para implementar um cenário simples de enviar um lote de mensagens para uma fila Barramento de Serviço e recebê-las. Para ter uma visão geral da biblioteca de clientes do .NET, confira Biblioteca cliente do Barramento de Serviço do Azure para .NET. Para obter mais exemplos, confira Amostras .NET do Barramento de Serviço no GitHub.

Pré-requisitos

Se não conhecer muito bem o serviço, confira a Visão geral do Barramento de Serviço antes de começar com este guia de início rápido.

• Assinatura do Azure. Para usar os serviços do Azure, incluindo o Barramento de Serviço do Azure, você precisa ter uma assinatura. Caso tenha uma conta do Azure, poderá se inscrever em uma avaliação gratuita.
• Visual Studio 2022. O aplicativo de exemplo usa novos recursos que foram introduzidos no C# 10. Ainda pode utilizar a biblioteca de clientes do Barramento de Serviço com versões anteriores da linguagem C#, mas a sintaxe pode variar. Para usar a sintaxe mais recente, recomendamos instalar o .NET 6.0 ou superior e configurar a versão da linguagem como latest. Se você estiver usando o Visual Studio, as versões anteriores ao Visual Studio 2022 não serão compatíveis com as ferramentas necessárias para compilar projetos do C# 10.

Criar um namespace no Portal do Azure

Para começar a usar as entidades de mensagens do Barramento de Serviço no Azure, primeiro é necessário criar um namespace com um nome exclusivo no Azure. Um namespace fornece um contêiner de escopo para recursos do Barramento de Serviço (filas, tópicos, etc.) dentro de seu aplicativo.

Para criar um namespace:

1. Entre no portal do Azure.

2. Navegue até Página Todos os serviços.

3. Na barra de navegação à esquerda, selecione Integração na lista de categorias. Passe o mouse sobre Barramento de Serviço e, em seguida, selecione o botão + no bloco do Barramento de Serviço.

   

4. Na marca Informações Básicas da página Criar namespace, siga estas etapas:

   1. Em Assinatura, escolha uma assinatura do Azure na qual criar o namespace.

   2. Em Grupo de recursos, escolha um grupo de recursos existente no qual o namespace residirá ou então crie um novo.

   3. Insira um nome para o namespace. O nome do namespace deve estar de acordo com as convenções de nomenclatura abaixo:

      • O nome deve ser exclusivo em todo o Azure. O sistema imediatamente verifica para ver se o nome está disponível.
      • O nome deve ter no mínimo seis e no máximo 50 caracteres.
      • O campo pode conter apenas letras, números e hifens "-".
      • O nome precisa começar com uma letra e terminar com uma letra ou um número.
      • O nome não termina com “-sb“ nem “-mgmt“.

   4. Em Localização, escolha a região na qual o namespace deve ser hospedado.

   5. Selecione o Tipo de preço (Básico, Standard ou Premium) do namespace. Para esse início rápido, selecione Padrão.

      Importante

      Se você quiser usar tópicos e assinaturas, escolha Standard ou Premium. Não há suporte para os tópicos/assinaturas no tipo de preço básico.

      Se você selecionou o tipo de preço Premium, especifique o número de unidades do sistema de mensagens. A camada Premium fornece isolamento de recursos no nível de CPU e memória, de modo que cada carga de trabalho seja executada isoladamente. Esse contêiner de recursos é chamado de unidade do sistema de mensagens. Um namespace premium tem pelo menos uma unidade do sistema de mensagens. Você pode selecionar 1, 2, 4, 8 ou 16 unidades do sistema de mensagens para cada namespace Premium do Barramento de Serviço. Para saber mais, confira Sistema de Mensagens Premium do Barramento de Serviço.

   6. Selecione Revisar + criar na parte inferior da página.

      

   7. Na páginaRevisar + criar,revise as configurações e selecioneCriar.

5. Depois que a implantação do recurso for bem-sucedida, selecione Ir para o recurso na página de implantação.

   

6. Você verá a home page do namespace do barramento de serviço.

   

Criar uma fila no portal do Azure

1. Na página Namespace de Barramento de Serviço, selecione Filas no menu de navegação à esquerda.

2. Na página Filas, selecione + Fila na barra de ferramentas.

3. Insira um nome para a fila e deixe os outros valores com os padrões.

4. Agora, selecione Criar.

   

Autenticar o aplicativo no Azure

Este início rápido mostra duas maneiras de se conectar ao Barramento de Serviço do Azure: sem senha e cadeia de conexão.

A primeira opção mostra como usar sua entidade de segurança no Microsoft Entra ID e o RBAC (controle de acesso baseado em função) para se conectar a um namespace do Barramento de Serviço. Você não precisa se preocupar em ter uma cadeia de conexão embutida no código, em um arquivo de configuração ou em um armazenamento seguro, como o Azure Key Vault.

A segunda opção mostra como usar uma cadeia de conexão para se conectar a um namespace do Barramento de Serviço. Se você for novo no Azure, poderá achar a opção de cadeia de conexão mais fácil de ser seguida. É recomendável usar a opção sem senha em aplicativos do mundo real e ambientes de produção. Para obter mais informações, confira Autenticação e autorização. Você também pode ler mais sobre a autenticação sem senha na página de visão geral.

Iniciar o Visual Studio e entrar no Azure

Você pode autorizar o acesso ao namespace do barramento de serviço usando as seguintes etapas:

1. Inicie o Visual Studio. Se você vir a janela Introdução, selecione o link Continuar sem código no painel direito.

2. Selecione o botão Entrar no canto superior direito do Visual Studio.

   

3. Entre usando a conta do Microsoft Entra à qual você atribuiu uma função anteriormente.

   

Enviar mensagens para a fila

Esta seção mostra como criar um aplicativo de console .NET para enviar mensagens para uma fila do Barramento de Serviço.

Criar um aplicativo de console

1. No Visual Studio, selecione o menu Arquivo ->Novo ->Projeto.

2. Na caixa de diálogo Criar um projeto, execute as seguintes etapas: Se essa caixa de diálogo não for exibida, selecione Arquivo no menu, Novo e, em seguida, Projeto.

   1. Selecione C# como a linguagem de programação.

   2. Selecione Console como o tipo do aplicativo.

   3. Selecione Aplicativo de Console na lista de resultados.

   4. Em seguida, selecione Avançar.

      

3. Insira QueueSender no nome do projeto, ServiceBusQueueQuickStart no nome da solução e selecione Próximo.

   

4. Na página Informações adicionais, selecione Criar para criar a solução e o projeto.

Adicionar os pacotes do NuGet ao projeto

Adicionar o código para enviar mensagens à fila

1. Substitua o conteúdo de Program.cs pelo seguinte código. As etapas importantes são descritas na seção a seguir, com informações adicionais nos comentários de código.

   • Sem senha
   • Cadeia de conexão

   • Cria um objeto ServiceBusClient usando o objeto DefaultAzureCredential. DefaultAzureCredential descobre e usa automaticamente as credenciais de sua entrada do Visual Studio para autenticar no Barramento de Serviço do Azure.
   • Invoca o método CreateSender no objeto ServiceBusClient a fim de criar um objeto ServiceBusSender para a fila específica do Barramento de Serviço.
   • Cria um objeto do ServiceBusMessageBatch usando o método ServiceBusSender.CreateMessageBatchAsync.
   • Adiciona mensagens ao lote usando o método ServiceBusMessageBatch.TryAddMessage.
   • Envia o lote de mensagens à fila do Barramento de Serviço usando o método ServiceBusSender.SendMessagesAsync.

   Importante

   Atualize os valores do espaço reservado (<NAMESPACE-NAME> e <QUEUE-NAME>) no snippet de código com os nomes do namespace e da fila do Barramento de Serviço.

   using Azure.Messaging.ServiceBus;
   using Azure.Identity;
   
   // name of your Service Bus queue
   // the client that owns the connection and can be used to create senders and receivers
   ServiceBusClient client;
   
   // the sender used to publish messages to the queue
   ServiceBusSender sender;
   
   // number of messages to be sent to the queue
   const int numOfMessages = 3;
   
   // The Service Bus client types are safe to cache and use as a singleton for the lifetime
   // of the application, which is best practice when messages are being published or read
   // regularly.
   //
   // Set the transport type to AmqpWebSockets so that the ServiceBusClient uses the port 443. 
   // If you use the default AmqpTcp, ensure that ports 5671 and 5672 are open.
   var clientOptions = new ServiceBusClientOptions
   { 
       TransportType = ServiceBusTransportType.AmqpWebSockets
   };
   //TODO: Replace the "<NAMESPACE-NAME>" and "<QUEUE-NAME>" placeholders.
   client = new ServiceBusClient(
       "<NAMESPACE-NAME>.servicebus.windows.net",
       new DefaultAzureCredential(),
       clientOptions);
   sender = client.CreateSender("<QUEUE-NAME>");
   
   // create a batch 
   using ServiceBusMessageBatch messageBatch = await sender.CreateMessageBatchAsync();
   
   for (int i = 1; i <= numOfMessages; i++)
   {
       // try adding a message to the batch
       if (!messageBatch.TryAddMessage(new ServiceBusMessage($"Message {i}")))
       {
           // if it is too large for the batch
           throw new Exception($"The message {i} is too large to fit in the batch.");
       }
   }
   
   try
   {
       // Use the producer client to send the batch of messages to the Service Bus queue
       await sender.SendMessagesAsync(messageBatch);
       Console.WriteLine($"A batch of {numOfMessages} messages has been published to the queue.");
   }
   finally
   {
       // Calling DisposeAsync on client types is required to ensure that network
       // resources and other unmanaged objects are properly cleaned up.
       await sender.DisposeAsync();
       await client.DisposeAsync();
   }
   
   Console.WriteLine("Press any key to end the application");
   Console.ReadKey();
   

2. Compile o projeto e verifique se não há erros.

3. Execute o programa e aguarde a mensagem de confirmação.

   A batch of 3 messages has been published to the queue
   

   Importante

   Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure. Em casos raros, pode demorar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

4. No portal do Azure, siga estas etapas:

   1. Acesse o namespace do Barramento de Serviço.

   2. Na página Visão geral, selecione a fila no painel inferior central.

      

   3. Observe os valores da seção Essentials.

      

   Observe os seguintes valores:

   • O valor de contagem de mensagens Ativas da fila agora é 3. Toda vez que você executa esse aplicativo de envio sem recuperar as mensagens, esse valor aumenta em 3.
   • O tamanho atual da fila aumenta cada vez que o aplicativo adiciona uma mensagem à fila.
   • No gráfico Mensagens da seção inferior Métricas, você pode ver que há três mensagens de entrada na fila.

Receber mensagens da fila

Nesta seção, você criará um aplicativo de console do .NET que recebe mensagens da fila.

Criar um projeto para o receptor

1. Na janela do Gerenciador de Soluções, clique com o botão direito do mouse na solução ServiceBusQueueQuickStart, aponte para Adicionar e selecione Novo projeto.
2. Selecione Aplicativo de console e Próximo.
3. Insira QueueReceiver como o Nome do projeto e selecione Criar.
4. Na janela Gerenciador de Soluções, clique com o botão direito do mouse em QueueReceiver e selecione Definir como um projeto de inicialização.

Adicionar os pacotes do NuGet ao projeto

Adicionar o código para receber mensagens da fila

Nessa seção, você adicionará o código para recuperar mensagens da fila.

1. Dentro da classe Program, adicione o seguinte código:

   • Sem senha
   • Cadeia de conexão

   using System.Threading.Tasks;
   using Azure.Identity;
   using Azure.Messaging.ServiceBus;
   
   // the client that owns the connection and can be used to create senders and receivers
   ServiceBusClient client;
   
   // the processor that reads and processes messages from the queue
   ServiceBusProcessor processor;
   

2. Acrescente os seguintes métodos ao final da classe Program.

   // handle received messages
   async Task MessageHandler(ProcessMessageEventArgs args)
   {
       string body = args.Message.Body.ToString();
       Console.WriteLine($"Received: {body}");
   
       // complete the message. message is deleted from the queue. 
       await args.CompleteMessageAsync(args.Message);
   }
   
   // handle any errors when receiving messages
   Task ErrorHandler(ProcessErrorEventArgs args)
   {
       Console.WriteLine(args.Exception.ToString());
       return Task.CompletedTask;
   }
   

3. Acrescente o seguinte código ao final da classe Program. As etapas importantes são descritas na seção a seguir, com informações adicionais nos comentários de código.

   • Sem senha
   • Cadeia de conexão

   • Cria um objeto ServiceBusClient usando o objeto DefaultAzureCredential. DefaultAzureCredential descobre e usa automaticamente as credenciais de sua entrada do Visual Studio para se autenticar no Barramento de Serviço do Azure.
   • Invoca o método CreateProcessor no objeto ServiceBusClient a fim de criar um objeto ServiceBusProcessor para a fila do Barramento de Serviço especificado.
   • Especifica os manipuladores dos eventos ProcessMessageAsync e ProcessErrorAsync do objeto ServiceBusProcessor.
   • Inicia o processamento de mensagens invocando o método StartProcessingAsync no objeto ServiceBusProcessor.
   • Quando o usuário pressionar uma tecla para encerrar o processamento, ele invocará o método StopProcessingAsync no objeto ServiceBusProcessor.

   Importante

   Atualize os valores do espaço reservado (<NAMESPACE-NAME> e <QUEUE-NAME>) no snippet de código com os nomes do namespace e da fila do Barramento de Serviço.

   // The Service Bus client types are safe to cache and use as a singleton for the lifetime
   // of the application, which is best practice when messages are being published or read
   // regularly.
   //
   // Set the transport type to AmqpWebSockets so that the ServiceBusClient uses port 443. 
   // If you use the default AmqpTcp, make sure that ports 5671 and 5672 are open.
   
   // TODO: Replace the <NAMESPACE-NAME> placeholder
   var clientOptions = new ServiceBusClientOptions()
   {
       TransportType = ServiceBusTransportType.AmqpWebSockets
   };
   client = new ServiceBusClient(
       "<NAMESPACE-NAME>.servicebus.windows.net",
       new DefaultAzureCredential(),
       clientOptions);
   
   // create a processor that we can use to process the messages
   // TODO: Replace the <QUEUE-NAME> placeholder
   processor = client.CreateProcessor("<QUEUE-NAME>", new ServiceBusProcessorOptions());
   
   try
   {
       // add handler to process messages
       processor.ProcessMessageAsync += MessageHandler;
   
       // add handler to process any errors
       processor.ProcessErrorAsync += ErrorHandler;
   
       // start processing 
       await processor.StartProcessingAsync();
   
       Console.WriteLine("Wait for a minute and then press any key to end the processing");
       Console.ReadKey();
   
       // stop processing 
       Console.WriteLine("\nStopping the receiver...");
       await processor.StopProcessingAsync();
       Console.WriteLine("Stopped receiving messages");
   }
   finally
   {
       // Calling DisposeAsync on client types is required to ensure that network
       // resources and other unmanaged objects are properly cleaned up.
       await processor.DisposeAsync();
       await client.DisposeAsync();
   }
   

4. A classe concluída Program deve corresponder ao seguinte código:

   • Sem senha
   • Cadeia de conexão

   using System.Threading.Tasks;
   using Azure.Messaging.ServiceBus;
   using Azure.Identity;
   
   // the client that owns the connection and can be used to create senders and receivers
   ServiceBusClient client;
   
   // the processor that reads and processes messages from the queue
   ServiceBusProcessor processor;
   
   // The Service Bus client types are safe to cache and use as a singleton for the lifetime
   // of the application, which is best practice when messages are being published or read
   // regularly.
   //
   // Set the transport type to AmqpWebSockets so that the ServiceBusClient uses port 443.
   // If you use the default AmqpTcp, make sure that ports 5671 and 5672 are open.
   
   // TODO: Replace the <NAMESPACE-NAME> and <QUEUE-NAME> placeholders
   var clientOptions = new ServiceBusClientOptions() 
   {
       TransportType = ServiceBusTransportType.AmqpWebSockets
   };
   client = new ServiceBusClient("<NAMESPACE-NAME>.servicebus.windows.net", 
       new DefaultAzureCredential(), clientOptions);
   
   // create a processor that we can use to process the messages
   // TODO: Replace the <QUEUE-NAME> placeholder
   processor = client.CreateProcessor("<QUEUE-NAME>", new ServiceBusProcessorOptions());
   
   try
   {
       // add handler to process messages
       processor.ProcessMessageAsync += MessageHandler;
   
       // add handler to process any errors
       processor.ProcessErrorAsync += ErrorHandler;
   
       // start processing 
       await processor.StartProcessingAsync();
   
       Console.WriteLine("Wait for a minute and then press any key to end the processing");
       Console.ReadKey();
   
       // stop processing 
       Console.WriteLine("\nStopping the receiver...");
       await processor.StopProcessingAsync();
       Console.WriteLine("Stopped receiving messages");
   }
   finally
   {
       // Calling DisposeAsync on client types is required to ensure that network
       // resources and other unmanaged objects are properly cleaned up.
       await processor.DisposeAsync();
       await client.DisposeAsync();
   }
   
   // handle received messages
   async Task MessageHandler(ProcessMessageEventArgs args)
   {
       string body = args.Message.Body.ToString();
       Console.WriteLine($"Received: {body}");
   
       // complete the message. message is deleted from the queue. 
       await args.CompleteMessageAsync(args.Message);
   }
   
   // handle any errors when receiving messages
   Task ErrorHandler(ProcessErrorEventArgs args)
   {
       Console.WriteLine(args.Exception.ToString());
       return Task.CompletedTask;
   }
   

5. Compile o projeto e verifique se não há erros.

6. Execute o aplicativo receptor. Você verá as mensagens recebidas. Pressione qualquer tecla para interromper o recebimento e o aplicativo.

   Wait for a minute and then press any key to end the processing
   Received: Message 1
   Received: Message 2
   Received: Message 3
   
   Stopping the receiver...
   Stopped receiving messages
   

7. Verifique o portal novamente. Aguarde alguns minutos e atualize a página, se não vir 0 para as mensagens Ativas.

   • Os valores da contagem de mensagens Ativas e do Tamanho atual agora estão com 0.

   • No gráfico Mensagens, na seção inferior Métricas, você verá que há três mensagens de entrada e três mensagens de saída para a fila.

     

Limpar os recursos

Navegue até o namespace do Barramento de Serviço no portal do Azure e selecione Excluir no portal do Azure para excluir o namespace e a fila.

Confira também

Confira os seguintes exemplos e a documentação:

• Biblioteca de clientes do Barramento de Serviço do Azure para .NET – Leiame
• Exemplos no GitHub
• Referência da API REST
• Abstrair preocupações de infraestrutura com estruturas de nível superior, como NServiceBus

Próximas etapas