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:

  1. Criar um espaço de nomes do Service Bus com o Portal do Azure.
  2. Criar uma fila do Service Bus com o portal do Azure.
  3. Escreva uma aplicação de consola .NET para enviar um conjunto de mensagens para a fila.
  4. 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:

  1. Inicie sessão no portal do Azure

  2. 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.

    Imagem a mostrar a seleção de Criar um recurso, Integração e, em seguida, Service Bus no menu.

  3. Na etiqueta Noções básicas da página Criar espaço de nomes , siga estes passos:

    1. Em Subscrição, selecione uma subscrição do Azure na qual pretende criar o espaço de nomes.

    2. Para Grupo de recursos, escolha um grupo de recursos existente no qual o espaço de nomes irá viver ou crie um novo.

    3. 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".
    4. Em Localização, selecione a região na qual o espaço de nomes deve ser alojado.

    5. 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.

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

      Imagem a mostrar a página Criar um espaço de nomes

    7. Na página Rever + criar , reveja as definições e selecione Criar.

  4. Assim que a implementação do recurso for bem-sucedida, selecione Ir para recurso na página de implementação.

    Imagem a mostrar a página implementação bem-sucedida com a ligação Ir para recurso.

  5. Verá a home page do espaço de nomes do service bus.

    Imagem a mostrar a home page do espaço de nomes do Service Bus criado.

Criar uma fila no portal do Azure

  1. Na página Espaço de Nomes do Service Bus , selecione Filas no menu de navegação esquerdo.

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

  3. Introduza um nome para a fila e deixe os outros valores com as respetivas predefinições.

  4. Agora, selecione Criar.

    Imagem a mostrar a criação de uma fila no portal

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.

  1. 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.

  2. Na página de descrição geral, selecione Controlo de acesso (IAM) no menu esquerdo.

  3. Na página Controlo de acesso (IAM), selecione o separador Atribuições de funções .

  4. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu pendente resultante.

    Uma captura de ecrã a mostrar como atribuir uma função.

  5. 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.

  6. Em Atribuir acesso a, selecione Utilizador, grupo ou principal de serviço e, em seguida, selecione + Selecionar membros.

  7. 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.

  8. 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:

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

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

    Captura de ecrã a mostrar um botão para iniciar sessão no Azure com o Visual Studio.

  3. Inicie sessão com a conta Azure AD à qual atribuiu uma função anteriormente.

    Captura de ecrã a mostrar a seleção da conta.

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

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

  2. 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.

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

    2. Selecione Consola para o tipo de aplicação.

    3. Selecione Aplicação de Consola na lista de resultados.

    4. Em seguida, selecione Seguinte.

      Imagem a mostrar a caixa de diálogo Criar um novo projeto com C# e Consola selecionadas

  3. Introduza QueueSender para o nome do projeto, ServiceBusQueueQuickStart para o nome da solução e, em seguida, selecione Seguinte.

    Imagem a mostrar os nomes da solução e do projeto na caixa de diálogo Configurar o novo projeto

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

Adicionar os pacotes NuGet ao projeto

  1. Selecione Ferramentas>Consola do Gestor dePacotes NuGet Gestor> de Pacotes no menu.

  2. Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.ServiceBus .

    Install-Package Azure.Messaging.ServiceBus
    
  3. Execute o seguinte comando para instalar o pacote NuGet Azure.Identity .

    Install-Package Azure.Identity
    

Adicionar código para enviar mensagens para a fila

  1. 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.

    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();
    
  2. Crie o projeto e certifique-se de que não existem erros.

  3. 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.

  4. Na portal do Azure, siga estes passos:

    1. Navegue para o espaço de nomes do Service Bus.

    2. Na página Descrição geral , selecione a fila no painel do meio inferior.

      Imagem a mostrar a página Espaço de Nomes do Service Bus na portal do Azure com a fila selecionada.

    3. Repare nos valores na secção Essentials .

      Imagem a mostrar o número de mensagens recebidas e o tamanho da fila.

    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

  1. 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.
  2. Selecione Aplicação de consola e selecione Seguinte.
  3. Introduza QueueReceiver para o Nome do projeto e selecione Criar.
  4. 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

  1. Selecione Ferramentas>NuGet Gestor de>Pacotes Consola do Gestor de Pacotes no menu.

  2. Selecione QueueReceiver para Projeto predefinido.

    Captura de ecrã a mostrar o projeto QueueReceiver selecionado na Consola do Gestor de Pacotes.

  3. Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.ServiceBus .

    Install-Package Azure.Messaging.ServiceBus
    
  4. 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.

  1. 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;
    
  2. 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;
    }
    
  3. 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.

    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();
    }
    
  4. 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;
    }
    
  5. Crie o projeto e certifique-se de que não existem erros.

  6. 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
    
  7. Verifique o portal novamente. Aguarde alguns minutos e atualize a página se não vir 0 mensagens ativas .

    • A contagem de mensagens ativas e os valores de tamanho atual são agora 0.

    • No gráfico Mensagens na secção Métricas inferiores , pode ver que existem três mensagens recebidas e três mensagens a enviar para a fila.

      Captura de ecrã a mostrar as mensagens ativas e o tamanho após a receção.

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:

Passos seguintes