Compartilhar via


Início Rápido: enviar e receber eventos do Hubs de Eventos do Azure usando o .NET

Neste início rápido, você aprende a enviar os eventos de um hub de eventos e, em seguida, receber esses eventos do hub de eventos usando a biblioteca .NET Azure.Messaging.EventHubs.

Observação

Os inícios rápido são para você acelerar rapidamente o serviço. Se você já estiver familiarizado com o serviço, talvez queira ver exemplos do .NET de Hubs de Eventos em nosso repositório do SDK do .NET no GitHub: Exemplos de Hubs de Eventos no GitHub, Exemplos de processadores de eventos no GitHub.

Pré-requisitos

Se você é novo no Hubs de Eventos do Azure, confira a visão geral do Hubs de Eventos antes de passar por 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 2022. 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 as versões anteriores do idioma C#, mas a nova sintaxe não está 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ê está usando o Visual Studio, saiba que as versões anteriores ao Visual Studio 2022 não são compatíveis com as ferramentas necessárias para compilar projetos C# 8.0. O Visual Studio 2022, 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 no Hubs de Eventos e um hub de eventos no namespace. Em seguida, obtenha as credenciais de gerenciamento que seu aplicativo precisa para se comunicar com o hub de eventos. Para criar um namespace e um hub de eventos, confira Início Rápido: criar um hub de eventos usando o portal do Azure.

Autenticar o aplicativo no Azure

Este início rápido mostra duas maneiras de se conectar ao Hubs de Eventos do Azure:

  • Sem senha (autenticação do Microsoft Entra)
  • Cadeia de conexão

A primeira opção mostra como usar sua entidade de segurança no Azure Active Directory e no controle de acesso baseado em função (RBAC) para se conectar a um namespace do Hubs de Eventos. Você não precisa se preocupar em ter cadeias de conexão embutidas no código, em um arquivo de configuração ou em um armazenamento seguro, como o Azure Key Vault.

A segunda opção mostra como usar uma cadeia de conexão para se conectar a um namespace do Hubs de Eventos. Se você é novo no Azure, talvez ache a opção de cadeia de conexão mais fácil de ser seguida. É recomendável usar a opção sem senha em aplicativos do mundo real e ambientes de produção. Para obter mais informações, confira Autenticação e autorização. Você também pode ler mais sobre a autenticação sem senha na página de visão geral.

Atribuir funções ao usuário do Microsoft Entra

No caso de desenvolvimento local, verifique se a conta de usuário que se conecta aos Hubs de Eventos do Azure tem as permissões corretas. Você precisará da função Proprietário de Dados dos Hubs de Eventos do Azure para enviar e receber mensagens. Para atribuir essa função a si mesmo, você precisará da função Administrador de acesso do usuário ou de outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. É possível atribuir funções RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Saiba mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.

O exemplo a seguir atribui a função Azure Event Hubs Data Owner à sua conta de usuário, que fornece acesso completo aos recursos dos Hubs de Eventos do Azure. Em um cenário real, siga o Princípio do Privilégio Mínimo para dar aos usuários apenas as permissões mínimas necessárias para um ambiente de produção mais seguro.

Funções interna do Azure par Hubs de Eventos do Azure

Para os Hubs de Eventos do Azure, o gerenciamento de namespaces e de todos os recursos relacionados por meio do portal do Azure e da API de gerenciamento de recursos do Azure já está protegido pelo modelo Azure RBAC. O Azure fornece as funções internas do Azure abaixo para autorizar o acesso a um namespace dos Hubs de Eventos:

Se você quiser criar uma função personalizada, confira Direitos exigidos para operações dos Hubs de Eventos.

Importante

Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure. Em casos raros, poderá levar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

  1. No portal do Azure, localize o namespace dos Hubs de Eventos usando a barra de pesquisa principal ou a navegação à esquerda.

  2. Na página de visão geral, selecione Controle de acesso (IAM) no menu à esquerda.

  3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

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

    Captura de tela mostrando como atribuir uma função.

  5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Neste exemplo, pesquise Azure Event Hubs Data Owner e selecione o resultado correspondente. Em seguida, escolha Avançar.

  6. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

  7. No diálogo, pesquise seu nome de usuário do Microsoft Entra (geralmente seu endereço de email user@domain) e escolha Selecionar na parte inferior do diálogo.

  8. Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.

Iniciar o Visual Studio e entrar no Azure

Você pode autorizar o acesso ao namespace do barramento de serviço usando as seguintes etapas:

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

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

    Captura de tela mostrando o botão para entrar no Azure usando o Visual Studio.

  3. Entre usando a conta do Microsoft Entra à qual você atribuiu uma função anteriormente.

    Captura de tela mostrando a seleção da conta.

Enviar eventos para o hub de eventos

Esta seção mostra como criar um aplicativo de console .NET Core para enviar eventos para o hub de eventos que você criou.

Criar um aplicativo de console

  1. Se você já tiver o Visual Studio 2022 aberto, selecione Arquivo no menu, selecione Novo e então selecione Projeto. Caso contrário, inicie o Visual Studio 2022 e selecione Criar um novo projeto se você vir uma janela pop-up.

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

      Imagem mostrando a caixa de diálogo Novo Projeto

  3. Insira EventHubsSender no nome do projeto, EventHubsQuickStart no nome da solução e selecione Avançar.

    Imagem mostrando a página na qual você insere os nomes da solução e do projeto

  4. Na página Informações adicionais, selecione Criar.

Adicionar os pacotes do NuGet ao projeto

  1. Selecione Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes no menu.

  2. Execute os comandos a seguir para instalar os pacotes NuGet do Azure.Messaging.EventHubs e do Azure.Identity. Pressione ENTER para executar o segundo comando.

    Install-Package Azure.Messaging.EventHubs
    Install-Package Azure.Identity
    

Escrever código para enviar mensagens ao hub de eventos

  1. Substitua o código existente no arquivo Program.cs pelo seguinte código de exemplo. Em seguida, substitua os valores de espaço reservado <EVENT_HUB_NAMESPACE> e <HUB_NAME> para os parâmetros EventHubProducerClient pelos nomes do seu namespace do Hubs de Eventos e do hub de eventos. Por exemplo: "spehubns0309.servicebus.windows.net" e "spehub".

    Veja estas etapas importantes do código:

    1. Cria um objeto EventHubProducerClient usando o namespace e o nome do hub de eventos.
    2. Invoca o método CreateBatchAsync no objeto EventHubProducerClient para criar um objetoEventDataBatch.
    3. Adicione eventos ao lote usando o método EventDataBatch.TryAdd .
    4. Envia o lote de mensagens para o hub de eventos usando o método EventHubProducerClient.SendAsync .
    using Azure.Identity;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Producer;
    using System.Text;
    
    // number of events to be sent to the event hub
    int numOfEvents = 3;
    
    // 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.
    // TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values
    EventHubProducerClient producerClient = new EventHubProducerClient(
        "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
        "<HUB_NAME>",
        new DefaultAzureCredential());
    
    // 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.");
        Console.ReadLine();
    }
    finally
    {
        await producerClient.DisposeAsync();
    }
    
  1. Compile o projeto e verifique se não há erros.

  2. Execute o programa e aguarde a mensagem de confirmação.

    A batch of 3 events has been published.
    

    Importante

    Se você estiver usando a autenticação sem senha (Controle de Acesso Baseado em Função do Azure Active Directory), selecione Ferramentas e, em seguida, selecione Opções. Na janela Opções, expanda Autenticação de Serviço do Azure e selecione Seleção de Conta. Confirme se você está usando a conta que foi adicionada à função Proprietário de dados dos Hubs de Eventos do Azure no namespace dos Hubs de Eventos.

  3. Na página Namespace do Hubs de Eventos no portal do Azure, você vê três mensagens de entrada no gráfico Mensagens. Atualize a página para atualizar o gráfico, se necessário. Pode levar alguns segundos para que ela mostre que as mensagens foram recebidas.

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

    Observação

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

Receber eventos do hub de 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.

Criar uma conta de armazenamento e um contêiner de blobs do Azure

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.

  1. Crie uma conta de Armazenamento do Azure
  2. Crie um contêiner de blob
  3. Autentique-se no contêiner blob usando a autenticação do Microsoft Entra ID (sem senha) ou uma cadeia de conexão com o namespace.

Siga estas recomendações ao usar Armazenamento de Blobs do Azure como um repositório de ponto de verificação:

  • Use um contêiner separado para cada grupo de consumidores. Você pode usar a mesma conta de armazenamento, mas usar um contêiner por cada grupo.
  • Não use o contêiner para mais nada e não use a conta de armazenamento para mais nada.
  • A conta de armazenamento deve estar na mesma região em que o aplicativo implantado está localizado. Se o aplicativo for local, tente escolher a região mais próxima possível.

Na página Conta de armazenamento do portal do Azure, na seção serviço Blob, verifique se as seguintes configurações estão desabilitadas.

  • Namespace hierárquico
  • Exclusão temporária de blobs
  • Controle de versão

Ao desenvolver localmente, verifique se a conta de usuário que está acessando os dados de blob tem as permissões corretas. Você precisará do Colaborador de Dados do Blob de Armazenamento para ler e gravar os dados de blob. Para atribuir essa função a si mesmo, você precisará receber a atribuição da função Administrador de Acesso do Usuário ou de outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. É possível atribuir funções RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Você pode saber mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.

Nesse cenário, você atribuirá permissões à sua conta de usuário, no escopo da conta de armazenamento, para seguir o Princípio do Privilégio Mínimo. Essa prática fornece aos usuários apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo a seguir atribuirá a função de Colaborador de Dados do Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob na sua conta de armazenamento.

Importante

Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure, mas em casos raros pode levar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

  1. No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.

  2. Na página de visão geral da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.

  3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

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

    Uma captura de tela mostrando como atribuir uma função de conta de armazenamento.

  5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, pesquise o Colaborador de Dados do Blob de Armazenamento e selecione o resultado correspondente e, em seguida, escolha Avançar.

  6. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

  7. No diálogo, pesquise seu nome de usuário do Microsoft Entra (geralmente seu endereço de email user@domain) e escolha Selecionar na parte inferior do diálogo.

  8. Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.

Criar um projeto para o receptor

  1. 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.
  2. Selecione Aplicativo de console e Próximo.
  3. Insira EventHubsReceiver como o Nome do projeto e selecione Criar.
  4. 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.

Adicionar os pacotes do NuGet ao projeto

  1. Selecione Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes no menu.

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

  3. Execute o comando a seguir para instalar os pacotes NuGet Azure.Messaging.EventHubs e Azure.Identity. Pressione ENTER para executar o último comando.

    Install-Package Azure.Messaging.EventHubs
    Install-Package Azure.Messaging.EventHubs.Processor
    Install-Package Azure.Identity
    

Atualizar o código

Substitua o conteúdo do Program.cs pelo seguinte código:

  1. Substitua o código existente no arquivo Program.cs pelo seguinte código de exemplo. Em seguida, substitua os valores do espaço reservado <STORAGE_ACCOUNT_NAME> e <BLOB_CONTAINER_NAME> pelo URI BlobContainerClient. Substitua os valores de espaço reservado <EVENT_HUB_NAMESPACE> e <HUB_NAME> do EventProcessorClient também.

    Veja estas etapas importantes do código:

    1. Cria um objeto EventProcessorClient usando o namespace do Hubs de Eventos e o nome do hub de eventos. Você precisa criar o objeto BlobContainerClient para o contêiner no armazenamento do Azure criado anteriormente.
    2. Especifica manipuladores para os eventos ProcessEventAsync e ProcessErrorAsync do objeto EventProcessorClient.
    3. Inicia o processamento de eventos invocando oStartProcessingAsync no objeto EventProcessorClient.
    4. Interrompe o processamento de eventos após 30 segundos invocando StopProcessingAsync no objeto EventProcessorClient.
    using Azure.Identity;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Consumer;
    using Azure.Messaging.EventHubs.Processor;
    using Azure.Storage.Blobs;
    using System.Text;
    
    // Create a blob container client that the event processor will use
    // TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTATINAER_NAME> with actual names
    BlobContainerClient storageClient = new BlobContainerClient(
        new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/<BLOB_CONTAINER_NAME>"),
        new DefaultAzureCredential());
    
    // Create an event processor client to process events in the event hub
    // TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values
    var processor = new EventProcessorClient(
        storageClient,
        EventHubConsumerClient.DefaultConsumerGroupName,
        "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
        "<HUB_NAME>",
        new DefaultAzureCredential());
    
    // 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();
    
    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()));
        Console.ReadLine();
        return Task.CompletedTask;
    }
    
    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);
        Console.ReadLine();
        return Task.CompletedTask;
    }
    
  1. 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.

  2. Execute o aplicativo receptor.

  3. Você deverá ver uma mensagem informando que os eventos foram recebidos. Pressione ENTER depois de ver uma mensagem de evento recebida.

    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.

  4. No portal do Azure, você pode verificar se há três mensagens de saída, que o Hubs de Eventos enviou para o aplicativo de recebimento. Atualize a página para atualizar o gráfico. Pode levar alguns segundos para que ela mostre que as mensagens foram recebidas.

    Imagem da página do portal do Azure para verificar se o hub de eventos enviou os eventos ao aplicativo de destino

Validação do esquema para aplicativos baseados no SDK do Hubs de Eventos

Você pode utilizar o Registro de Esquema do Azure para realizar a validação do esquema ao transmitir dados com seus aplicativos baseados no SDK do Hubs de Eventos. O Registro de Esquemas dos Hubs de Eventos do Azure fornece um repositório centralizado para o gerenciamento de esquemas e você pode conectar perfeitamente seus aplicativos novos ou existentes ao Registro de Esquemas.

Para obter mais informações, confira Validar esquemas com o SDK do Hubs de Eventos.

Amostras e referências

Este início rápido fornece instruções passo a passo para implementar um cenário de envio de um lote de eventos para um hub de eventos e, em seguida, recebê-los. Para ver mais exemplos, selecione os links a seguir.

Para obter uma referência completa da biblioteca .NET, confira nossa documentação do SDK.

Limpar os recursos

Exclua o grupo de recursos que tem o namespace dos Hubs de Eventos ou exclua apenas o namespace se quiser manter o grupo de recursos.

Confira o seguinte tutorial: