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

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:

  • Microsoft Azure subscrição. Para utilizar os serviços Azure, incluindo os 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, recomenda-se 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 Visual Studio, as versões antes Visual Studio 2019 não são compatíveis com as ferramentas necessárias para construir projetos C# 8.0. Visual Studio 2019, incluindo a edição comunitária gratuita, podem ser descarregados aqui.
  • Crie um espaço de nomes de Centros de Eventos 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: Obter 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

  1. Inicie o Visual Studio 2019.

  2. Selecione Criar um novo projeto.

  3. Na 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. Em seguida, selecione Seguinte.

      Imagem mostrando a caixa de diálogo de Nova Project

  4. Insira o EventHubsSender para o nome do projeto, EventHubsQuickStart para o nome da solução e, em seguida, selecione OK para criar o projeto.

    Imagem mostrando a página onde você inseriu solução e nomes de projeto

Adicionar o pacote NuGet dos Hubs de Eventos

  1. Selecione Ferramentas > NuGet Gestor de Pacotes > consola Gestor de Pacotes consola do menu.

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

  1. Adicione as using seguintes 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;
    
  2. 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 com o 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 nome.

  3. 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;    
    
  4. Substitua o Main método pelo seguinte async Main método. Consulte os comentários de código para mais detalhes.

        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();
            }
        }
    
  5. Construa o projeto e garanta que não há erros.

  6. Executar o programa e aguardar a mensagem de confirmação.

    A batch of 3 events has been published.
    
  7. 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.

    Imagem da página do portal Azure para verificar se o centro de eventos recebeu os eventos

    Nota

    Para obter o código fonte completo com mais comentários 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 Armazenamento específica. Isto porque o Event Hubs SDK utiliza o mais recente Azure Armazenamento API disponível em 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 Armazenamento Blob SDK do que os normalmente disponíveis no Azure. Se estiver a utilizar o Azure Blob Armazenamento como uma loja de ponto de verificação, verifique a versão API suportada Armazenamento para a sua construção do 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 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 a versão API de serviço Armazenamento 2019-02-02. Para um exemplo sobre como direcionar uma versão API Armazenamento específica, consulte esta amostra no GitHub.

Crie um Armazenamento Azure e um recipiente de bolhas

Neste arranque rápido, você usa Azure Armazenamento como a loja de pontos de verificação. Siga estes passos para criar uma conta Armazenamento Azure.

  1. Criar uma conta de Armazenamento do Azure

  2. Criar um contentor de blobs

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

  1. Na janela Solution Explorer, clique com o botão direito na solução EventHubQuickStart, aponte para Adicionar, e selecione New Project.
  2. Selecione a aplicação Consola e selecione Seguinte.
  3. Insira o EventHubsReceiver para obter o nome Project e selecione Create.
  4. Na janela Solution Explorer, clique à direita no EventHubsReceiver e selecione set as a Startup Project.

Adicionar o pacote NuGet dos Hubs de Eventos

  1. Selecione Ferramentas > NuGet Gestor de Pacotes > consola Gestor de Pacotes consola do menu.

  2. Na janela Gestor de Pacotes consola, confirme que o EventHubsReceiver está selecionado para o projeto Predefinido. Caso contrário, utilize a lista de drop-down para selecionar EventHubsReceiver.

  3. Executar o seguinte comando para instalar o pacote Azure.Messaging.EventHubs NuGet:

    Install-Package Azure.Messaging.EventHubs
    
  4. Executar o seguinte comando para instalar o pacote Azure.Messaging.EventHubs.Processor NuGet:

    Install-Package Azure.Messaging.EventHubs.Processor
    

Atualizar o método principal

  1. Adicione as using seguintes 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;
    
  2. 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>";
    
  3. 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;    
    
  4. Substitua o Main método pelo seguinte async Main método. Consulte os comentários de código para mais detalhes.

        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();
        }
    
  5. 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;
        }    
    
  6. 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.

  7. Executar a aplicação do recetor.

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

Passos seguintes

Vê as amostras no GitHub.