Enviar eventos para e receber eventos do Azure Event Hubs - .NET (Azure.Messaging.EventHubs)

Artigo
07/27/2022
10 minutos para ler

Este quickstart mostra como enviar eventos e receber eventos de um centro de eventos usando a biblioteca Azure.Messaging.EventHubs .NET.

Pré-requisitos

Se você é novo em Azure Event Hubs, consulte o Event Hubs antes de fazer este quickstart.

Para completar este arranque rápido, precisa dos seguintes pré-requisitos:

Subscrição do Microsoft Azure. Para utilizar os serviços Azure, incluindo o Azure Event Hubs, precisa de uma subscrição. Se não tiver uma conta Azure existente, pode inscrever-se para um teste gratuito ou utilizar os benefícios do seu assinante MSDN quando criar uma conta.
Microsoft Visual Studio 2019. A biblioteca de clientes Azure Event Hubs faz uso de novas funcionalidades que foram introduzidas em C# 8.0. Ainda pode utilizar a biblioteca com versões linguísticas C# anteriores, mas a nova sintaxe não estará disponível. Para utilizar a sintaxe completa, recomendamos que compile com a versão .NET Core SDK 3.0 ou superior e a versão linguística definida para latest. Se estiver a utilizar o Visual Studio, as versões antes do Visual Studio 2019 não são compatíveis com as ferramentas necessárias para construir projetos C# 8.0. O Visual Studio 2019, incluindo a edição comunitária gratuita, pode ser descarregado aqui.
Crie um espaço de nomes de Event Hubs e um centro de eventos. O primeiro passo consiste em utilizar o portal do Azure para criar um espaço de nomes do tipo Hubs de Eventos e obter as credenciais de gestão de que a sua aplicação precisa para comunicar com o hub de eventos. Para criar um espaço de nome e um centro de eventos, siga o procedimento neste artigo. Em seguida, obtenha a cadeia de ligação para o espaço de nomes Do Event Hubs seguindo as instruções do artigo: Obtenha a cadeia de ligação. Utilize a cadeia de ligação mais tarde neste arranque rápido.

Enviar eventos

Esta secção mostra-lhe como criar uma aplicação de consola .NET Core para enviar eventos para um centro de eventos.

Criar uma aplicação de consola

Inicie o Visual Studio 2019.
Selecione Criar um novo projeto.
Na nova caixa de diálogo do projeto , faça os seguintes passos: Se não vir esta caixa de diálogo, selecione Ficheiro no menu, selecione Novo e, em seguida, selecione Project.
1. Selecione C# para a linguagem de programação.
2. Selecione Consola para o tipo de aplicação.
3. Selecione a aplicação da consola na lista de resultados.
4. Então, selecione Next.
Insira o EventHubsSender para o nome do projeto, EventHubsQuickStart para o nome da solução e, em seguida, selecione OK para criar o projeto.

Adicionar o pacote NuGet dos Hubs de Eventos

Selecione ferramentas>NuGet Package Manager>Package Manager Consola do menu.
Executar o seguinte comando para instalar o pacote Azure.Messaging.EventHubs NuGet:
```
Install-Package Azure.Messaging.EventHubs
```

Escreva código para enviar eventos para o centro de eventos

Adicione as seguintes using declarações ao topo do ficheiro .cs Programa :

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

Adicione constantes à Program classe para a cadeia de ligação Event Hubs e o nome do centro do evento.

    // 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;

Nota

Substitua os valores do espaço reservado pelo fio de ligação ao seu espaço de nome e o nome do centro de eventos. Certifique-se de que a cadeia de ligação é a cadeia de ligação ao nível do espaço de nome.

Adicione a seguinte propriedade estática à Program classe. Consulte os comentários de 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 Main método pelo seguinte async Main método. Consulte os comentários de código para mais detalhes. Aqui estão os passos importantes do código.

Cria um objeto EventHubProducerClient usando a cadeia de ligação primária para o espaço de nome e o nome do centro do evento.
Invoca o método CreateBatchAsync no objeto EventHubProducerClient para criar um objeto EventDataBatch .
Adicione eventos ao lote utilizando o método EventDataBatch.TryAdd .
Envia o lote de mensagens para o centro de eventos utilizando 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();
        }
    }

Construa o projeto e garanta que não há erros.
Executar o programa e aguardar a mensagem de confirmação.
```
A batch of 3 events has been published.
```
No portal Azure, pode verificar se o centro de eventos recebeu os eventos. Ver mensagens na secção Métricas . Refresque a página para atualizar o gráfico. Pode levar alguns segundos para mostrar que as mensagens foram recebidas.

Nota

Para obter o código fonte completo com comentários mais informativos, consulte este ficheiro no GitHub

Receber eventos

Esta secção mostra como escrever uma aplicação de consola .NET Core que recebe eventos de um centro de eventos usando um processador de eventos. O processador do evento simplifica a receção de eventos a partir de centros de eventos, gerindo pontos de verificação persistentes e receções paralelas desses centros de eventos. Um processador de eventos está associado a um hub de evento específico e a um grupo de consumidores. Recebe eventos de múltiplas divisórias no centro do evento, passando-as a um delegado de manipulador para processamento usando o código que fornece.

Aviso

Se executar este código no Azure Stack Hub, irá sofrer erros de tempo de execução a menos que tenha como alvo uma versão API de armazenamento específica. Isto porque o Event Hubs SDK utiliza o mais recente API de Armazenamento Azure disponível disponível no Azure Que pode não estar disponível na sua plataforma Azure Stack Hub. O Azure Stack Hub pode suportar uma versão diferente do Storage Blob SDK do que os normalmente disponíveis no Azure. Se estiver a utilizar o Azure Blob Storage como uma loja de ponto de verificação, verifique a versão API suportada para o seu Azure Stack Hub e direcione essa versão no seu código.

Por exemplo, Se estiver a executar a versão Azure Stack Hub 2005, a versão mais alta disponível para o serviço de Armazenamento é a versão 2019-02-02. Por padrão, a biblioteca de clientes Event Hubs SDK utiliza a versão mais alta disponível no Azure (2019-07-07 no momento do lançamento do SDK). Neste caso, além de seguir os passos nesta secção, também terá de adicionar código para direcionar o serviço de armazenamento API versão 2019-02-02. Para um exemplo sobre como direcionar uma versão específica da API de armazenamento, consulte esta amostra no GitHub.

Criar um Azure Storage e um recipiente blob

Neste arranque rápido, utiliza-se o Azure Storage como loja de pontos de verificação. Siga estes passos para criar uma conta de Armazenamento Azure.

Criar uma conta de Armazenamento do Azure
Criar um contentor de blobs
Obtenha o fio de ligação para a conta de armazenamento

Observe o fio de ligação e o nome do recipiente. Vai usá-los no código de receção.

Criar um projeto para o recetor

Na janela Solution Explorer, clique à direita na solução EventHubQuickStart , aponte para Adicionar e selecione Novo Projeto.
Selecione a aplicação Consola e selecione Seguinte.
Insira o EventHubsReceiver para o nome do projeto e selecione Criar.
Na janela Solution Explorer , clique à direita no EventHubsReceiver e selecione set as a Startup Project.

Adicionar o pacote NuGet dos Hubs de Eventos

Selecione ferramentas>NuGet Package Manager>Package Manager Consola do menu.
Na janela da consola do gestor de pacotes , confirme que o EventHubsReceiver está selecionado para o projeto Predefinido. Caso contrário, utilize a lista de drop-down para selecionar EventHubsReceiver.
Executar o seguinte comando para instalar o pacote Azure.Messaging.EventHubs NuGet:
```
Install-Package Azure.Messaging.EventHubs
```
Executar o seguinte comando para instalar o pacote Azure.Messaging.EventHubs.Processor NuGet:
```
Install-Package Azure.Messaging.EventHubs.Processor
```

Atualizar o método principal

Adicione as seguintes using declarações no topo do ficheiro .cs Programa .

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 à Program classe para a cadeia de ligação Event Hubs e o nome do centro do evento. Substitua os espaços reservados nos parênteses pelos valores adequados que obteve ao criar o centro de eventos. Substitua os espaços reservados nos suportes pelos valores adequados que obteve ao criar o centro de eventos e a conta de armazenamento (teclas de acesso - cadeia de ligação primária). Certifique-se de que {Event Hubs namespace connection string} é a cadeia de ligação ao nível do espaço de nomes 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 seguintes propriedades estáticas à Program classe.

    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 Main método pelo seguinte async Main método. Consulte os comentários de código para mais detalhes. Aqui estão os passos importantes do código.

Cria um objeto EventProcessorClient usando a cadeia de ligação primária ao espaço de nome e ao centro de eventos. Você precisa construir o objeto BlobContainerClient para o recipiente no armazenamento Azure que criou anteriormente.
Especifica os manipuladores para os eventos ProcessEventAsync e ProcessErrorAsync do objeto EventProcessorClient .
Inicia o processamento de eventos invocando o StartProcessingAsync no objeto EventProcessorClient .
Quando o utilizador pressiona uma tecla para terminar o processamento, invoca o StopProcessingAsync no objeto EventProcessorClient .

    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 seguintes métodos de manipulação de eventos e erros à 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;
    }

Construa o projeto e garanta que não há erros.

Nota

Para obter o código fonte completo com mais comentários informativos, consulte este ficheiro no GitHub.
Executar a aplicação do recetor.
Devia ver uma mensagem de que os acontecimentos foram recebidos.
```
Received event: Event 1
Received event: Event 2
Received event: Event 3    
```
Estes eventos são os três eventos que enviou para o centro de eventos mais cedo, executando o programa remetente.
No portal Azure, pode verificar se existem 3 mensagens de saída. Estas são as mensagens que os Centros de Eventos enviaram para a aplicação recetora. Refresque a página para atualizar o gráfico. Pode levar alguns segundos para mostrar que as mensagens foram recebidas.

Passos seguintes

Este início rápido fornece instruções passo a passo para implementar um cenário simples de enviar um lote de eventos para um centro de eventos e depois recebê-los. Para mais amostras em outros cenários avançados, confira as seguintes amostras no GitHub.