Início Rápido: Enviar e receber mensagens de uma fila de Azure Service Bus (.NET)
Neste início rápido, irá seguir os seguintes passos:
- Criar um espaço de nomes do Service Bus com o Portal do Azure.
- Criar uma fila do Service Bus com o portal do Azure.
- Escreva uma aplicação de consola .NET para enviar um conjunto de mensagens para a fila.
- Escreva uma aplicação de consola .NET para receber essas mensagens da fila.
Nota
Este guia de introdução fornece instruções passo a passo para implementar um cenário simples de enviar um lote de mensagens para uma fila do Service Bus e, em seguida, recebê-las. Para obter uma descrição geral da biblioteca de cliente .NET, veja Azure Service Bus biblioteca de cliente para .NET. Para obter mais exemplos, veja Exemplos .NET do Service Bus no GitHub.
Pré-requisitos
Se não estiver familiarizado com o serviço, veja Descrição geral do Service Bus antes de efetuar este início rápido.
- Subscrição do Azure. Para utilizar os serviços do Azure, incluindo Azure Service Bus, precisa de uma subscrição. Se não tiver uma conta do Azure existente, pode inscrever-se numa avaliação gratuita.
- Visual Studio 2022. A aplicação de exemplo utiliza novas funcionalidades que foram introduzidas no C# 10. Ainda pode utilizar a biblioteca de cliente do Service Bus com versões de idioma C# anteriores, mas a sintaxe pode variar. Para utilizar a sintaxe mais recente, recomendamos que instale o .NET 6.0 ou superior e defina a versão do idioma como
latest
. Se estiver a utilizar o Visual Studio, as versões anteriores ao Visual Studio 2022 não são compatíveis com as ferramentas necessárias para criar projetos C# 10.
Criar um espaço de nomes no portal do Azure
Para começar a utilizar as entidades de mensagens do Service Bus no Azure, tem de, primeiro, criar um espaço de nomes que seja exclusivo em todo o Azure. Um espaço de nomes fornece um contentor de âmbito para os recursos do Service Bus na sua aplicação.
Para criar um espaço de nomes:
Inicie sessão no portal do Azure
No painel de navegação esquerdo do portal, selecione Todos os serviços, selecione Integração na lista de categorias, paire o rato sobre o Service Bus e, em seguida, selecione Criar no mosaico Service Bus.
Na etiqueta Noções básicas da página Criar espaço de nomes , siga estes passos:
Em Subscrição, selecione uma subscrição do Azure na qual pretende criar o espaço de nomes.
Para Grupo de recursos, escolha um grupo de recursos existente no qual o espaço de nomes irá viver ou crie um novo.
Introduza um nome para o espaço de nomes. O nome do espaço de nomes deve cumprir as seguintes convenções de nomenclatura:
- O nome tem de ser exclusivo em todo o Azure. O sistema verifica imediatamente a disponibilidade do nome.
- O comprimento do nome é, pelo menos, 6 e, no máximo, 50 carateres.
- O nome só pode conter letras, números, hífenes "-".
- O nome tem de começar com uma letra e terminar com uma letra ou número.
- O nome não termina com "-sb" ou "-mgmt".
Em Localização, selecione a região na qual o espaço de nomes deve ser alojado.
Para Escalão de preço, selecione o escalão de preço (Básico, Standard ou Premium) para o espaço de nomes. Para este início rápido, selecione Standard.
Importante
Se quiser utilizar tópicos e subscrições, escolha Standard ou Premium. Os tópicos/subscrições não são suportados no escalão de preço Básico.
Se tiver selecionado o escalão de preço Premium , especifique o número de unidades de mensagens. O escalão premium fornece isolamento de recursos ao nível da CPU e da memória para que cada carga de trabalho seja executada isoladamente. Este contentor de recursos é designado por unidade de mensagens. Um espaço de nomes premium tem, pelo menos, uma unidade de mensagens. Pode selecionar 1, 2, 4, 8 ou 16 unidades de mensagens para cada espaço de nomes Premium do Service Bus. Para obter mais informações, veja Mensagens Premium do Service Bus.
Selecione Rever + criar na parte inferior da página.
Na página Rever + criar , reveja as definições e selecione Criar.
Assim que a implementação do recurso for bem-sucedida, selecione Ir para recurso na página de implementação.
Verá a home page do espaço de nomes do service bus.
Criar uma fila no portal do Azure
Na página Espaço de Nomes do Service Bus , selecione Filas no menu de navegação esquerdo.
Na página Filas , selecione + Fila na barra de ferramentas.
Introduza um nome para a fila e deixe os outros valores com as respetivas predefinições.
Agora, selecione Criar.
Autenticar a aplicação no Azure
Este guia de introdução mostra-lhe duas formas de ligar a Azure Service Bus: sem palavra-passe e cadeia de ligação. A primeira opção mostra-lhe como utilizar o principal de segurança no Azure Active Directory e o controlo de acesso baseado em funções (RBAC) para ligar a um espaço de nomes do Service Bus. Não precisa de se preocupar em ter uma cadeia de ligação hard-coded no seu código ou num ficheiro de configuração ou num armazenamento seguro, como o Azure Key Vault. A segunda opção mostra como utilizar uma cadeia de ligação para ligar a um espaço de nomes do Service Bus. Se não estiver familiarizado com o Azure, poderá achar mais fácil seguir a opção de cadeia de ligação. Recomendamos que utilize a opção sem palavra-passe em aplicações e ambientes de produção do mundo real. Para obter mais informações, veja Autenticação e autorização. Também pode ler mais sobre a autenticação sem palavra-passe na página de descrição geral.
Atribuir funções ao utilizador Azure AD
Ao desenvolver localmente, certifique-se de que a conta de utilizador que se liga ao Azure Service Bus tem as permissões corretas. Precisará da função de Proprietário de Dados Azure Service Bus para enviar e receber mensagens. Para atribuir esta função a si próprio, precisará da função Administrador de Acesso de Utilizador ou de outra função que inclua a ação Microsoft.Authorization/roleAssignments/write
. Pode atribuir funções RBAC do Azure a um utilizador com o portal do Azure, a CLI do Azure ou Azure PowerShell. Saiba mais sobre os âmbitos disponíveis para atribuições de funções na página de descrição geral do âmbito .
O exemplo seguinte atribui a Azure Service Bus Data Owner
função à sua conta de utilizador, que fornece acesso total aos recursos Azure Service Bus. Num cenário real, siga o Princípio do Privilégio Mínimo para conceder aos utilizadores apenas as permissões mínimas necessárias para um ambiente de produção mais seguro.
Funções incorporadas do Azure para Azure Service Bus
Por Azure Service Bus, a gestão de espaços de nomes e todos os recursos relacionados através do portal do Azure e da API de gestão de recursos do Azure já está protegida com o modelo RBAC do Azure. O Azure fornece as funções incorporadas do Azure abaixo para autorizar o acesso a um espaço de nomes do Service Bus:
- Azure Service Bus Proprietário de Dados: permite o acesso a dados ao espaço de nomes do Service Bus e às respetivas entidades (filas, tópicos, subscrições e filtros). Um membro desta função pode enviar e receber mensagens de filas ou tópicos/subscrições.
- Azure Service Bus Remetente de Dados: utilize esta função para conceder acesso de envio ao espaço de nomes do Service Bus e às respetivas entidades.
- Azure Service Bus Recetor de Dados: utilize esta função para conceder acesso de receção ao espaço de nomes do Service Bus e às respetivas entidades.
Se quiser criar uma função personalizada, veja Direitos necessários para operações do Service Bus.
Adicionar Azure AD utilizador à função proprietário do Azure Service Bus
Adicione o Azure AD nome de utilizador à função proprietário de dados do Azure Service Bus ao nível do espaço de nomes do Service Bus. Permitirá que uma aplicação em execução no contexto da sua conta de utilizador envie mensagens para uma fila ou tópico e receba mensagens de uma fila ou subscrição de um tópico.
Importante
Na maioria dos casos, a propagação da atribuição de funções no Azure demorará um minuto ou dois. Em casos raros, pode demorar até oito minutos. Se receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos e tente novamente.
Se não tiver a página Espaço de Nomes do Service Bus aberta no portal do Azure, localize o espaço de nomes do Service Bus com a barra de pesquisa principal ou a navegação à esquerda.
Na página de descrição geral, selecione Controlo de acesso (IAM) no menu esquerdo.
Na página Controlo de acesso (IAM), selecione o separador Atribuições de funções .
Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu pendente resultante.
Utilize a caixa de pesquisa para filtrar os resultados para a função pretendida. Neste exemplo, procure
Azure Service Bus Data Owner
e selecione o resultado correspondente. Em seguida, selecione Seguinte.Em Atribuir acesso a, selecione Utilizador, grupo ou principal de serviço e, em seguida, selecione + Selecionar membros.
Na caixa de diálogo, procure o seu Azure AD nome de utilizador (normalmente o seu endereço de e-mail user@domain) e, em seguida, selecione Selecionar na parte inferior da caixa de diálogo.
Selecione Rever + atribuir para ir para a página final e, em seguida, Rever + atribuir novamente para concluir o processo.
Iniciar o Visual Studio e iniciar sessão no Azure
Pode autorizar o acesso ao espaço de nomes do service bus com os seguintes passos:
Inicie o Visual Studio. Se vir a janela Introdução , selecione a ligação Continuar sem código no painel direito.
Selecione o botão Iniciar sessão no canto superior direito do Visual Studio.
Inicie sessão com a conta Azure AD à qual atribuiu uma função anteriormente.
Enviar mensagens para a fila
Esta secção mostra-lhe como criar uma aplicação de consola .NET para enviar mensagens para uma fila do Service Bus.
Nota
Este guia de introdução fornece instruções passo a passo para implementar um cenário simples de enviar um lote de mensagens para uma fila do Service Bus e, em seguida, recebê-las. Para obter mais exemplos sobre outros cenários avançados, veja Exemplos .NET do Service Bus no GitHub.
Criar uma aplicação de consola
No Visual Studio, selecione Ficheiro ->Novo ->menu Projeto.
Na caixa de diálogo Criar um novo projeto , siga os seguintes passos: se não vir esta caixa de diálogo, selecione Ficheiro no menu, selecione Novo e, em seguida, selecione Projeto.
Selecione C# para a linguagem de programação.
Selecione Consola para o tipo de aplicação.
Selecione Aplicação de Consola na lista de resultados.
Em seguida, selecione Seguinte.
Introduza QueueSender para o nome do projeto, ServiceBusQueueQuickStart para o nome da solução e, em seguida, selecione Seguinte.
Na página Informações adicionais , selecione Criar para criar a solução e o projeto.
Adicionar os pacotes NuGet ao projeto
Selecione Ferramentas>Consola do Gestor dePacotes NuGet Gestor> de Pacotes no menu.
Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.ServiceBus .
Install-Package Azure.Messaging.ServiceBus
Execute o seguinte comando para instalar o pacote NuGet Azure.Identity .
Install-Package Azure.Identity
Adicionar código para enviar mensagens para a fila
Substitua o conteúdo de
Program.cs
pelo seguinte código. Os passos importantes são descritos abaixo, com informações adicionais nos comentários de código.- Cria um objeto ServiceBusClient com o
DefaultAzureCredential
objeto .DefaultAzureCredential
irá detetar e utilizar automaticamente as credenciais do seu início de sessão do Visual Studio para se autenticar no Azure Service Bus. - Invoca o método CreateSender no objeto ServiceBusClient para criar um objeto ServiceBusSender para a fila específica do Service Bus.
- Cria um objeto ServiceBusMessageBatch com o método ServiceBusSender.CreateMessageBatchAsync .
- Adicione mensagens ao lote com ServiceBusMessageBatch.TryAddMessage.
- Envia o lote de mensagens para a fila do Service Bus com o método ServiceBusSender.SendMessagesAsync .
Importante
Atualize os valores dos marcadores de posição (
<NAMESPACE-CONNECTION-STRING>
e<QUEUE-NAME>
) no fragmento de código com os nomes do espaço de nomes e da fila do Service Bus.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();
- Cria um objeto ServiceBusClient com o
Crie o projeto e certifique-se de que não existem erros.
Execute o programa e aguarde pela mensagem de confirmação.
A batch of 3 messages has been published to the queue
Importante
Na maioria dos casos, a propagação da atribuição de funções no Azure demorará um minuto ou dois. Em casos raros, pode demorar até oito minutos. Se receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos e tente novamente.
Na portal do Azure, siga estes passos:
Navegue para o espaço de nomes do Service Bus.
Na página Descrição geral , selecione a fila no painel do meio inferior.
Repare nos valores na secção Essentials .
Repare nos seguintes valores:
- O valor de contagem de mensagens Ativas para a fila é agora 3. Sempre que executar esta aplicação de remetente sem obter as mensagens, este valor aumenta 3.
- O tamanho atual da fila é incrementado sempre que a aplicação adiciona mensagens à fila.
- No gráfico Mensagens na secção Métricas inferior, pode ver que existem três mensagens a receber para a fila.
Receber mensagens da fila
Nesta secção, irá criar uma aplicação de consola .NET que recebe mensagens da fila.
Nota
Este início rápido fornece instruções passo a passo para implementar um cenário de envio de um lote de mensagens para uma fila do Service Bus e, em seguida, recebê-las. Para obter mais exemplos sobre outros cenários avançados, veja Exemplos .NET do Service Bus no GitHub.
Criar um projeto para o recetor
- Na janela Explorador de Soluções, clique com o botão direito do rato na solução ServiceBusQueueQuickStart, aponte para Adicionar e selecione Novo Projeto.
- Selecione Aplicação de consola e selecione Seguinte.
- Introduza QueueReceiver para o Nome do projeto e selecione Criar.
- Na janela Explorador de Soluções, clique com o botão direito do rato em QueueReceiver e selecione Definir como um Projeto de Arranque.
Adicionar os pacotes NuGet ao projeto
Selecione Ferramentas>NuGet Gestor de>Pacotes Consola do Gestor de Pacotes no menu.
Selecione QueueReceiver para Projeto predefinido.
Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.ServiceBus .
Install-Package Azure.Messaging.ServiceBus
Execute o seguinte comando para instalar o pacote NuGet Azure.Identity .
Install-Package Azure.Identity
Adicionar o código para receber mensagens da fila
Nesta secção, irá adicionar código para obter mensagens da fila.
Program
Na classe, adicione o seguinte código: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;
Acrescente os seguintes métodos ao final da
Program
classe.// 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; }
Acrescente o seguinte código ao final da
Program
classe. Os passos importantes são descritos abaixo, com informações adicionais nos comentários de código.- Cria um objeto ServiceBusClient com o
DefaultAzureCredential
objeto.DefaultAzureCredential
irá detetar e utilizar automaticamente as credenciais do seu início de sessão do Visual Studio para se autenticar no Azure Service Bus. - Invoca o método CreateProcessor no
ServiceBusClient
objeto para criar um objeto ServiceBusProcessor para a fila do Service Bus especificada. - Especifica processadores para os eventos ProcessMessageAsync e ProcessErrorAsync do objeto ServiceBusProcessor .
- Inicia o processamento de mensagens ao invocar o StartProcessingAsync no
ServiceBusProcessor
objeto. - Quando o utilizador prime uma chave para terminar o processamento, invoca StopProcessingAsync no
ServiceBusProcessor
objeto.
Importante
Atualize os valores dos marcadores de posição (
<NAMESPACE-NAME>
e<QUEUE-NAME>
) no fragmento de código com os nomes do espaço de nomes e da fila do Service Bus.// 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(); }
- Cria um objeto ServiceBusClient com o
A classe concluída
Program
deve corresponder ao seguinte código: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; }
Crie o projeto e certifique-se de que não existem erros.
Execute a aplicação recetora. Deverá ver as mensagens recebidas. Prima qualquer tecla para parar o recetor e a aplicação.
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
Verifique o portal novamente. Aguarde alguns minutos e atualize a página se não vir
0
mensagens ativas .
Limpar os recursos
Navegue para o espaço de nomes do Service Bus no portal do Azure e selecione Eliminar no portal do Azure para eliminar o espaço de nomes e a fila no mesmo.
Ver também
Veja a seguinte documentação e exemplos:
- Azure Service Bus biblioteca de cliente para .NET – Readme
- Exemplos no GitHub
- Referência de .NET API
- Abstrair as preocupações da infraestrutura com arquiteturas de nível mais elevado, como o NServiceBus