Enviar e receber eventos dos Hubs de Eventos do Azure – .NET (Azure.Messaging.EventHubs)

Artigo
07/27/2022
10 minutos para o fim da leitura

Este início rápido mostra como enviar e receber eventos de um hub de eventos usando a biblioteca Azure.Messaging.EventHubs do .NET.

Pré-requisitos

Se você estiver conhecendo agora os Hubs de Eventos do Azure, confira Visão geral dos Hubs de Eventos antes de prosseguir com este início rápido.

Para concluir este início rápido, você precisará dos seguintes pré-requisitos:

Assinatura do Microsoft Azure. Para usar os serviços do Azure, incluindo os Hubs de Eventos do Azure, você precisa ter uma assinatura. Caso não tenha uma conta existente do Azure, inscreva-se em uma avaliação gratuita ou use os benefícios do assinante do MSDN quando criar uma conta.
Microsoft Visual Studio 2019. A biblioteca de clientes dos Hubs de Eventos do Azure usa novos recursos que foram introduzidos no C# 8.0. Você ainda pode usar a biblioteca com versões anteriores da linguagem C#, mas a nova sintaxe não estará disponível. Para usar a sintaxe completa, recomenda-se compilar com o SDK do .NET Core 3.0 ou superior e a versão de linguagem definida como latest. Se você estiver usando o Visual Studio, as versões anteriores ao Visual Studio 2019 não serão compatíveis com as ferramentas necessárias para compilar projetos C# 8.0. O Visual Studio 2019, incluindo a edição Community gratuita, pode ser baixado aqui.
Criar um namespace de Hubs de Eventos e um hub de eventos. A primeira etapa é usar o portal do Azure para criar um namespace do tipo Hubs de eventos e obter as credenciais de gerenciamento das quais que seu aplicativo precisa para se comunicar com o hub de eventos. Para criar um namespace e um hub de eventos, siga o procedimento nesse artigo. Em seguida, obtenha a cadeia de conexão para o namespace dos Hubs de Eventos seguindo as instruções do artigo: Obter a cadeia de conexão. Você usa a cadeia de conexão posteriormente no início rápido.

Enviar eventos

Esta seção mostra como criar um aplicativo de console .NET Core para enviar eventos a um hub de eventos.

Criar um aplicativo de console

Inicie o Visual Studio 2019.
Selecione Criar um novo projeto.
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.
Insira EventHubsSender como o nome do projeto, EventHubsQuickStart como o nome da solução e, em seguida, selecione OK para criar o projeto.

Adicione o pacote NuGet de Hubs de Eventos

Selecione Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes no menu.
Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.EventHubs:
```
Install-Package Azure.Messaging.EventHubs
```

Escrever código para enviar mensagens ao hub de eventos

Adicione as seguintes instruções using ao início do arquivo Program.cs:

using System;
using System.Text;
using System.Threading.Tasks;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;

Adicione constantes à classe Program da cadeia de conexão dos Hubs de Eventos e o nome do hub de eventos.

    // connection string to the Event Hubs namespace
    private const string connectionString = "<EVENT HUBS NAMESPACE - CONNECTION STRING>";

    // name of the event hub
    private const string eventHubName = "<EVENT HUB NAME>";

    // number of events to be sent to the event hub
    private const int numOfEvents = 3;

Observação

Substitua os valores de espaço reservado pela cadeia de conexão para o namespace e o nome do hub de eventos. Verifique se a cadeia de conexão é a cadeia de conexão no nível do namespace.

Adicione a seguinte propriedade estática à classe Program. Confira os comentários sobre código.

    // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
    // of the application, which is best practice when events are being published or read regularly.
    static EventHubProducerClient producerClient;

Substitua o método Main pelo método async Main a seguir. Confira os comentários sobre código para obter detalhes. Aqui estão as etapas importantes do código.

Cria um objeto EventHubProducerClient usando a cadeia de conexão primária para o namespace e o nome do hub de eventos.
Invoca o método CreateBatchAsync no objeto EventHubProducerClient para criar um objetoEventDataBatch.
Adicione eventos ao lote usando o método EventDataBatch.TryAdd .
Envia o lote de mensagens para o hub de eventos usando o método EventHubProducerClient.SendAsync .

    static async Task Main()
    {
        // Create a producer client that you can use to send events to an event hub
        producerClient = new EventHubProducerClient(connectionString, eventHubName);

        // Create a batch of events 
        using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();

        for (int i = 1; i <= numOfEvents; i++)
        {
            if (! eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
            {
                // if it is too large for the batch
                throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
            }
        }

        try
        {
            // Use the producer client to send the batch of events to the event hub
            await producerClient.SendAsync(eventBatch);
            Console.WriteLine($"A batch of {numOfEvents} events has been published.");
        }
        finally
        {
            await producerClient.DisposeAsync();
        }
    }

Compile o projeto e verifique se não há erros.
Execute o programa e aguarde a mensagem de confirmação.
```
A batch of 3 events has been published.
```
No portal do Azure, você poderá verificar se o hub de eventos recebeu os eventos. Alterne para a exibição Mensagens na seção Métricas. Atualize a página para atualizar o gráfico. Poderá levar alguns segundos para que ela mostre que as mensagens foram recebidas.

Observação

Para obter o código-fonte completo com os comentários mais informativos, confira este arquivo no GitHub

Receber eventos

Esta seção mostra como escrever um aplicativo de console .NET Core que recebe eventos de um hub de eventos usando um processador de eventos. O processador de eventos simplifica o recebimento de eventos dos hubs de eventos gerenciando pontos de verificação persistentes e recebimentos paralelos desses hubs de eventos. Um processador de eventos é associado a um hub de eventos e a um grupo de consumidores específicos. Ele recebe eventos de várias partições no hub de eventos, transmitindo-os para um delegado do manipulador para processamento usando o código fornecido por você.

Aviso

Se você executar esse código no Azure Stack Hub, haverá erros de runtime, a menos que você direcione uma versão específica da API de Armazenamento. Isso ocorre porque o SDK dos Hubs de Eventos usa a última API de Armazenamento do Azure disponível no Azure que talvez não esteja disponível na sua plataforma Azure Stack Hub. O Azure Stack Hub pode dar suporte a uma versão diferente do SDK do Armazenamento de Blobs do que aquelas normalmente disponíveis no Azure. Se estiver usando o Armazenamento de Blobs do Azure como um repositório de pontos de verificação, verifique a versão da API do Armazenamento do Azure com suporte para o build do Azure Stack Hub e tenha como destino essa versão no código.

Por exemplo, se a execução estiver sendo feita no Azure Stack Hub versão 2005, a versão mais alta disponível para o serviço de Armazenamento será a versão 2019-02-02. Por padrão, a biblioteca de clientes do SDK dos Hubs de Eventos usa a versão mais alta disponível no Azure (2019-07-07 no momento do lançamento do SDK). Nesse caso, além de seguir as etapas desta seção, você também precisará adicionar o código para ter como destino a versão de API 2019-02-02 do serviço de Armazenamento. Para obter um exemplo de como ter como destino uma versão de API específica do Armazenamento, confira esta amostra no GitHub.

Criar um Armazenamento do Azure e um contêiner de blob

Neste início rápido, você usará o Armazenamento do Azure como o repositório de pontos de verificação. Siga estas etapas para criar uma conta de Armazenamento do Azure.

Crie uma conta de Armazenamento do Azure
Crie um contêiner de blob
Obtenha a cadeia de conexão para a conta de armazenamento

Anote a cadeia de conexão e o nome do contêiner. Você os usará no código de recebimento.

Criar um projeto para o receptor

Na janela do Gerenciador de Soluções, clique com o botão direito do mouse na solução EventHubQuickStart, aponte para Adicionar e selecione Novo Projeto.
Selecione Aplicativo de console e Próximo.
Insira EventHubsReceiver como o Nome do projeto e selecione Criar.
Na janela Gerenciador de Soluções, clique com o botão direito do mouse em EventHubsReceiver e selecione Definir como um Projeto de Inicialização.

Adicione o pacote NuGet de Hubs de Eventos

Selecione Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes no menu.
Na janela Console do Gerenciador de Pacotes, confirme se EventHubsReceiver está selecionado para o Projeto padrão. Caso não esteja, use a lista suspensa para selecionar EventHubsReceiver.
Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.EventHubs:
```
Install-Package Azure.Messaging.EventHubs
```
Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.EventHubs.Processor:
```
Install-Package Azure.Messaging.EventHubs.Processor
```

Atualizar o método Main

Adicione as instruções using a seguir na parte superior do arquivo Program.cs.

using System;
using System.Text;
using System.Threading.Tasks;
using Azure.Storage.Blobs;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Consumer;
using Azure.Messaging.EventHubs.Processor;

Adicione constantes à classe Program da cadeia de conexão dos Hubs de Eventos e o nome do hub de eventos. Substitua os espaços reservados nos colchetes pelos valores adequados obtidos na criação do hub de eventos. Substitua os espaços reservados entre colchetes pelos valores adequados obtidos na criação do hub de eventos e da conta de armazenamento (chaves de acesso/cadeia de conexão primária). Verifique se {Event Hubs namespace connection string} é a cadeia de conexão de nível de namespace e não a cadeia de hub de eventos.
```
    private const string ehubNamespaceConnectionString = "<EVENT HUBS NAMESPACE - CONNECTION STRING>";
    private const string eventHubName = "<EVENT HUB NAME>";
    private const string blobStorageConnectionString = "<AZURE STORAGE CONNECTION STRING>";
    private const string blobContainerName = "<BLOB CONTAINER NAME>";
```

Adicione as propriedades estáticas a seguir à classe Program.

    static BlobContainerClient storageClient;

    // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
    // of the application, which is best practice when events are being published or read regularly.        
    static EventProcessorClient processor;

Substitua o método Main pelo método async Main a seguir. Confira os comentários sobre código para obter detalhes. Aqui estão as etapas importantes do código.

Cria um objeto EventProcessorClient usando a cadeia de conexão primária para o namespace e o hub de eventos. Você precisa criar o objeto BlobContainerClient para o contêiner no armazenamento do Azure criado anteriormente.
Especifica manipuladores para os eventos ProcessEventAsync e ProcessErrorAsync do objeto EventProcessorClient.
Inicia o processamento de eventos invocando oStartProcessingAsync no objeto EventProcessorClient.
Quando o usuário pressionar uma tecla para encerrar o processamento, ele invocará o método StopProcessingAsync no objeto EventProcessorClien.

    static async Task Main()
    {
        // Read from the default consumer group: $Default
        string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

        // Create a blob container client that the event processor will use 
        storageClient = new BlobContainerClient(blobStorageConnectionString, blobContainerName);

        // Create an event processor client to process events in the event hub
        processor = new EventProcessorClient(storageClient, consumerGroup, ehubNamespaceConnectionString, eventHubName);

        // Register handlers for processing events and handling errors
        processor.ProcessEventAsync += ProcessEventHandler;
        processor.ProcessErrorAsync += ProcessErrorHandler;

        // Start the processing
        await processor.StartProcessingAsync();

        // Wait for 30 seconds for the events to be processed
        await Task.Delay(TimeSpan.FromSeconds(30));

        // Stop the processing
        await processor.StopProcessingAsync();
    }

Agora, adicione os métodos de manipulador de erro e eventos à classe.

    static async Task ProcessEventHandler(ProcessEventArgs eventArgs)
    {
        // Write the body of the event to the console window
        Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));

        // Update checkpoint in the blob storage so that the app receives only new events the next time it's run
        await eventArgs.UpdateCheckpointAsync(eventArgs.CancellationToken);
    }

    static Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
    {
        // Write details about the error to the console window
        Console.WriteLine($"\tPartition '{ eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
        Console.WriteLine(eventArgs.Exception.Message);
        return Task.CompletedTask;
    }

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

Observação

Para obter o código-fonte completo com os comentários mais informativos, confira este arquivo no GitHub.
Execute o aplicativo receptor.
Você deverá ver uma mensagem informando que os eventos foram recebidos.
```
Received event: Event 1
Received event: Event 2
Received event: Event 3    
```
Esses eventos são os três eventos que você enviou para o hub de eventos anteriormente executando o programa de remetente.
No portal do Azure, você pode verificar se há três mensagens de saída. Essas são as mensagens que os Hubs de Eventos enviam para o aplicativo receptor. Atualize a página para atualizar o gráfico. Poderá levar alguns segundos para que ela mostre que as mensagens foram recebidas.

Próximas etapas

Este início rápido apresenta instruções passo a passo para implementar um cenário simples de enviar um lote de eventos para um hub de eventos e recebê-los. Para obter mais exemplos sobre outros e cenários avançados, confira os exemplos a seguir no GitHub.