Hubs de Eventos do Azure biblioteca de clientes para .NET – versão 5.9.3

  • Artigo

Hubs de Eventos do Azure é um serviço de publicação-assinatura altamente escalonável que pode ingerir milhões de eventos por segundo e transmiti-los para vários consumidores. Isso permite processar e analisar as grandes quantidades de dados produzidos por seus dispositivos e aplicativos conectados. Depois que os Hubs de Eventos coletarem os dados, você poderá recuperá-los, transformá-los e armazená-los usando qualquer provedor de análise em tempo real ou com adaptadores de armazenamento/lote. Se você quiser saber mais sobre Hubs de Eventos do Azure, talvez queira examinar: O que são os Hubs de Eventos.

A biblioteca de clientes dos Hubs de Eventos do Azure permite publicar e consumir eventos dos Hubs de Eventos do Azure e pode ser usada para:

  • Emitir telemetria sobre seu aplicativo para fins de diagnóstico e business intelligence.

  • Publicar fatos sobre o estado do seu aplicativo, que as partes interessadas podem observar e usar como gatilho para tomar medidas.

  • Observar operações interessantes e interações que ocorrem na sua empresa ou em outro ecossistema, permitindo que sistemas flexíveis interajam sem a necessidade de vinculá-los.

  • Receber eventos de um ou mais editores, transformá-los para atender melhor às necessidades do ecossistema e publicar os eventos transformados em um novo fluxo para que os consumidores observem.

Código-fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do produto | Guia de | migraçãoGuia de solução de problemas

Introdução

Pré-requisitos

  • Assinatura do Azure: Para usar os serviços do Azure, incluindo Hubs de Eventos do Azure, você precisará de uma assinatura. Se você não tiver uma conta existente do Azure, poderá se inscrever para uma avaliação gratuita ou usar os benefícios da assinatura do Visual Studio ao criar uma conta.

  • Namespace dos Hubs de Eventos com um Hub de Eventos: Para interagir com Hubs de Eventos do Azure, você também precisará ter um namespace e o Hub de Eventos disponíveis. Se você não estiver familiarizado com a criação de recursos do Azure, convém seguir o guia passo a passo para criar um Hub de Eventos usando o portal do Azure. Lá, você também pode encontrar instruções detalhadas para usar os modelos da CLI do Azure, Azure PowerShell ou ARM (Azure Resource Manager) para criar um Hub de Eventos.

  • C# 8.0: A biblioteca de clientes Hubs de Eventos do Azure usa novos recursos que foram introduzidos no C# 8.0. Para aproveitar a sintaxe do C# 8.0, é recomendável compilar usando o SDK do .NET Core 3.0 ou superior com uma versão de idioma do latest.

    Os usuários do Visual Studio que desejam aproveitar ao máximo a sintaxe do C# 8.0 precisarão usar o Visual Studio 2019 ou posterior. O Visual Studio 2019, incluindo a edição Community gratuita, pode ser baixado aqui. Os usuários do Visual Studio 2017 podem aproveitar a sintaxe do C# 8 usando o pacote NuGet Microsoft.Net.Compilers e definindo a versão do idioma, embora a experiência de edição possa não ser ideal.

    Você ainda pode usar a biblioteca com versões anteriores da linguagem C#, mas precisará gerenciar membros descartáveis assíncronos e enumeráveis e assíncronos manualmente, em vez de se beneficiar da nova sintaxe. Você ainda pode direcionar qualquer versão de estrutura compatível com o SDK do .NET Core, incluindo versões anteriores do .NET Core ou do .NET Framework. Para obter mais informações, consulte: como especificar estruturas de destino.
    Observação importante: Para criar ou executar os exemplos e os exemplos sem modificação, o uso do C# 11.0 é necessário. Você ainda poderá executar os exemplos se decidir ajustá-los para outras versões de idioma. Um exemplo de fazer isso está disponível no exemplo: Versões anteriores do idioma.

Para criar rapidamente um conjunto básico de recursos dos Hubs de Eventos no Azure e receber uma cadeia de conexão para eles, você pode implantar nosso modelo de exemplo clicando em:

Implantar no Azure

Instalar o pacote

Instale a biblioteca de clientes do Hubs de Eventos do Azure para .NET com o NuGet:

dotnet add package Azure.Messaging.EventHubs

Autenticar o cliente

Para que a biblioteca de clientes dos Hubs de Eventos interaja com um Hub de Eventos, ele precisará entender como se conectar e autorizar com ele. O meio mais fácil para fazer isso é usar uma cadeia de conexão, que é criada automaticamente ao criar um namespace dos Hubs de Eventos. Se você não estiver familiarizado com o uso de cadeias de conexão com Hubs de Eventos, convém seguir o guia passo a passo para obter uma cadeia de conexão dos Hubs de Eventos.

Depois que você tiver uma cadeia de conexão, qualquer um dos tipos de cliente dos Hubs de Eventos poderá ser criado com ela:

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends.  This example disposes
// after the immediate scope for simplicity.

await using var producer = new EventHubProducerClient(connectionString, eventHubName);

Para obter exemplos de autenticação dos clientes dos Hubs de Eventos com tipos de credencial, consulte Usando uma entidade de segurança do AAD (Azure Active Directory) ou o exemplo identidade e credenciais de acesso compartilhado .

Para obter exemplos de autenticação dos clientes dos Hubs de Eventos para um aplicativo ASP.NET Core, consulte Registrando-se com ASP.NET Core injeção de dependência.

Principais conceitos

  • Um cliente do Hub de Eventos é a interface principal para desenvolvedores que interagem com a biblioteca de clientes dos Hubs de Eventos. Há vários clientes diferentes do Hub de Eventos, cada um dedicado a um uso específico dos Hubs de Eventos, como publicação ou consumo de eventos.

  • Um produtor do Hub de Eventos é um tipo de cliente que serve como uma fonte de dados de telemetria, informações de diagnóstico, logs de uso ou outros dados de log, como parte de uma solução de dispositivo inserida, um aplicativo de dispositivo móvel, um título de jogo em execução em um console ou outro dispositivo, alguma solução de negócios baseada em cliente ou servidor ou um site da Web.

  • Um consumidor do Hub de Eventos é um tipo de cliente que lê informações do Hub de Eventos e permite o processamento dele. O processamento pode envolver agregação, computação complexa e filtragem. O processamento também pode envolver a distribuição ou o armazenamento das informações de maneira bruta ou transformada. Os consumidores do Hub de Eventos geralmente são partes de infraestrutura de plataforma robustas e de alta escala com recursos de análise integrados, como Azure Stream Analytics, Apache Spark ou Apache Storm.

  • Uma partição é uma sequência ordenada de eventos que é mantida em um Hub de Eventos. As partições são um meio de organização de dados associada ao paralelismo exigido pelos consumidores de eventos. Os Hubs de Eventos do Azure fornecem streaming de mensagens por meio de um padrão de consumidor particionado no qual cada consumidor lê apenas um subconjunto específico, ou partição, do fluxo de mensagens. À medida que novos eventos chegam, eles são adicionados ao final dessa sequência. O número de partições é especificado no momento em que um Hub de Eventos é criado e não pode ser alterado.

  • Um grupo de consumidores é uma exibição de um Hub de Eventos inteiro. Os grupos de consumidores habilitam vários aplicativos de consumo para que cada um tenha um modo de exibição do fluxo de evento separado e para ler o fluxo de forma independente em seu próprio ritmo e com seus próprio deslocamentos. Pode haver no máximo cinco leitores simultâneos em uma partição por grupo de consumidores; no entanto, é recomendável que haja apenas um consumidor ativo para um determinado emparelhamento de partição e grupo de consumidores. Cada leitor ativo recebe todos os eventos de sua partição; se houver vários leitores na mesma partição, eles receberão eventos duplicados.

Para obter mais conceitos e discussões mais profundas, consulte: Recursos dos Hubs de Eventos.

Tempo de vida do cliente

Cada um dos tipos de cliente dos Hubs de Eventos é seguro para armazenar em cache e usar como singleton durante o tempo de vida do aplicativo, o que é uma prática recomendada quando os eventos estão sendo publicados ou lidos regularmente. Os clientes são responsáveis pelo gerenciamento eficiente de rede, CPU e uso de memória, trabalhando para manter o uso baixo durante períodos de inatividade. Chamar ou CloseAsyncDisposeAsync em um cliente é necessário para garantir que os recursos de rede e outros objetos não gerenciados sejam limpos corretamente.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Os tipos de modelo de dados, como EventData e EventDataBatch não são thread-safe. Eles não devem ser compartilhados entre threads nem usados simultaneamente com métodos de cliente.

Conceitos adicionais

Opções | do clienteTratamento de falhas | Diagnostics | Zombando

Exemplos

Inspecione um Hub de Eventos

Muitas operações do Hub de Eventos ocorrem dentro do escopo de uma partição específica. Como as partições pertencem ao Hub de Eventos, seus nomes são atribuídos no momento da criação. Para entender quais partições estão disponíveis, consulte o Hub de Eventos usando um dos clientes do Hub de Eventos. Para ilustração, o EventHubProducerClient é demonstrado nesses exemplos, mas o conceito e a forma são comuns entre os clientes.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends.  This example disposes
// after the immediate scope for simplicity.

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    string[] partitionIds = await producer.GetPartitionIdsAsync();
}

Envio de eventos para um Hub de Eventos

Para publicar eventos, você precisará criar um EventHubProducerClient. Os produtores publicam eventos em lotes e podem solicitar uma partição específica ou permitir que o serviço de Hubs de Eventos decida em quais eventos de partição devem ser publicados. É recomendável usar o roteamento automático quando a publicação de eventos precisa estar altamente disponível ou quando os dados de evento devem ser distribuídos uniformemente entre as partições. Nosso exemplo aproveitará o roteamento automático.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends.  This example disposes
// after the immediate scope for simplicity.

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();

    if ((!eventBatch.TryAdd(new EventData("First"))) ||
        (!eventBatch.TryAdd(new EventData("Second"))))
    {
       throw new ApplicationException("Not all events could be added to the batch!");
    }

    await producer.SendAsync(eventBatch);
}

Ler eventos de um Hub de Eventos

Para ler eventos de um Hub de Eventos, você precisará criar um EventHubConsumerClient para um determinado grupo de consumidores. Quando um Hub de Eventos é criado, ele fornece um grupo de consumidores padrão que pode ser usado para começar a explorar os Hubs de Eventos. Em nosso exemplo, nos concentraremos em ler todos os eventos que foram publicados no Hub de Eventos usando um iterador.

Nota: É importante observar que essa abordagem de consumo destina-se a melhorar a experiência de explorar a biblioteca de clientes e a prototipagem dos Hubs de Eventos. Recomendamos que ele não seja usado em cenários de produção. Para uso em produção, recomendamos usar o Cliente do Processador de Eventos, pois ele fornece uma experiência mais robusta e de desempenho.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends.  This example disposes
// after the immediate scope for simplicity.

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync(cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the Event Hub.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Ler eventos a partir de um Hub de Eventos

Para ler eventos para uma partição do Hub de Eventos, você precisará criar um EventHubConsumerClient para um determinado grupo de consumidores. Quando um Hub de Eventos é criado, ele fornece um grupo de consumidores padrão que pode ser usado para começar a explorar os Hubs de Eventos. Para ler de uma partição específica, o consumidor também precisará especificar onde no fluxo de eventos para começar a receber eventos; em nosso exemplo, nos concentraremos na leitura de todos os eventos publicados para a primeira partição do Hub de Eventos.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends.  This example disposes
// after the immediate scope for simplicity.

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    EventPosition startingPosition = EventPosition.Earliest;
    string partitionId = (await consumer.GetPartitionIdsAsync()).First();

    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsFromPartitionAsync(partitionId, startingPosition, cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the partition.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Processar eventos usando um cliente do Processador de Eventos

Para a maioria dos cenários de produção, é recomendável que o Cliente processador de eventos seja usado para ler e processar eventos. O processador destina-se a fornecer uma experiência robusta para processar eventos em todas as partições de um Hub de Eventos de maneira tolerante a falhas e, ao mesmo tempo, fornecer um meio para manter seu estado. Os clientes do Processador de Eventos também são capazes de trabalhar de forma cooperativa dentro do contexto de um grupo de consumidores para um determinado Hub de Eventos, no qual eles gerenciarão automaticamente a distribuição e o balanceamento do trabalho à medida que as instâncias ficam disponíveis ou não estão disponíveis para o grupo.

Como o EventProcessorClient tem uma dependência nos blobs do Armazenamento do Microsoft Azure para persistência de seu estado, você precisará fornecer um BlobContainerClient para o processador, que foi configurado para a conta de armazenamento e o contêiner que devem ser usados.

var cancellationSource = new CancellationTokenSource();
cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";

var eventHubsConnectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var consumerGroup = "<< NAME OF THE EVENT HUB CONSUMER GROUP >>";

Task processEventHandler(ProcessEventArgs eventArgs) => Task.CompletedTask;
Task processErrorHandler(ProcessErrorEventArgs eventArgs) => Task.CompletedTask;

var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);

processor.ProcessEventAsync += processEventHandler;
processor.ProcessErrorAsync += processErrorHandler;

await processor.StartProcessingAsync();

try
{
    // The processor performs its work in the background; block until cancellation
    // to allow processing to take place.

    await Task.Delay(Timeout.Infinite, cancellationSource.Token);
}
catch (TaskCanceledException)
{
    // This is expected when the delay is canceled.
}

try
{
    await processor.StopProcessingAsync();
}
finally
{
    // To prevent leaks, the handlers should be removed when processing is complete.

    processor.ProcessEventAsync -= processEventHandler;
    processor.ProcessErrorAsync -= processErrorHandler;
}

Mais detalhes podem ser encontrados no README do Cliente do Processador de Eventos e nos exemplos que acompanham.

Usando uma entidade de segurança do Active Directory com os clientes do Hub de Eventos

A biblioteca de Identidade do Azure fornece suporte à autenticação do AAD (Azure Active Directory), que pode ser usada para as bibliotecas de clientes do Azure, incluindo Hubs de Eventos.

Para usar uma entidade de segurança do Active Directory, uma das credenciais disponíveis da Azure.Identity biblioteca é especificada ao criar o cliente dos Hubs de Eventos. Além disso, o namespace dos Hubs de Eventos totalmente qualificado e o nome do Hub de Eventos desejado são fornecidos em vez da cadeia de conexão dos Hubs de Eventos. Para ilustração, o EventHubProducerClient é demonstrado nesses exemplos, mas o conceito e a forma são comuns entre os clientes.

var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();

// It is recommended that you cache the Event Hubs clients for the lifetime of your
// application, closing or disposing when application ends.  This example disposes
// after the immediate scope for simplicity.

await using (var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();

    if ((!eventBatch.TryAdd(new EventData("First"))) ||
        (!eventBatch.TryAdd(new EventData("Second"))))
    {
       throw new ApplicationException("Not all events could be added to the batch!");
    }

    await producer.SendAsync(eventBatch);
}

Ao usar o Azure Active Directory, sua entidade de segurança deve receber uma função que permita o acesso aos Hubs de Eventos, como a Azure Event Hubs Data Owner função . Para obter mais informações sobre como usar a autorização do Azure Active Directory com hubs de eventos, consulte a documentação associada.

Registrando-se com ASP.NET Core injeção de dependência

Para injetar um dos clientes dos Hubs de Eventos como uma dependência em um aplicativo ASP.NET Core, instale a integração da biblioteca de clientes do Azure para ASP.NET Core pacote.

dotnet add package Microsoft.Extensions.Azure

Após a instalação, registre os tipos de cliente dos Hubs de Eventos desejados no Startup.ConfigureServices método :

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        builder.AddEventHubProducerClient(Configuration.GetConnectionString("EventHubs"));
    });
  
    services.AddControllers();
}

Para usar o código anterior, adicione-o à configuração do aplicativo:

{
  "ConnectionStrings": {
    "EventHubs": "<connection_string>"
  }
}

Para aplicativos que preferem usar uma credencial compartilhada Azure.Identity para seus clientes, o registro parece um pouco diferente:

var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        // This will register the EventHubProducerClient using the default credential.
        builder.AddEventHubProducerClientWithNamespace(fullyQualifiedNamespace);

        // By default, DefaultAzureCredential is used, which is likely desired for most
        // scenarios. If you need to restrict to a specific credential instance, you could
        // register that instance as the default credential instead.
        builder.UseCredential(new ManagedIdentityCredential());
    });
  
    services.AddControllers();
}

Para obter mais detalhes, consulte Injeção de dependência com o SDK do Azure para .NET.

Solução de problemas

Para obter informações detalhadas de solução de problemas, consulte o Guia de solução de problemas dos Hubs de Eventos.

Log e diagnóstico

A biblioteca de clientes dos Hubs de Eventos é totalmente instrumentada para registrar informações em log em vários níveis de detalhes usando o .NET EventSource para emitir informações. O registro em log é executado para cada operação e segue o padrão de marcação do ponto de partida da operação, sua conclusão e quaisquer exceções encontradas. Informações adicionais que podem oferecer insights também são registradas no contexto da operação associada.

Os logs de cliente dos Hubs de Eventos estão disponíveis para qualquer EventListener , aceitando a origem chamada "Azure-Messaging-EventHubs" ou optando por todas as fontes que têm a característica "AzureEventSource". Para facilitar a captura de logs das bibliotecas de clientes do Azure, a Azure.Core biblioteca usada pelos Hubs de Eventos oferece um AzureEventSourceListener. Mais informações podem ser encontradas em Capturar logs dos Hubs de Eventos usando o AzureEventSourceListener.

A biblioteca de clientes dos Hubs de Eventos também é instrumentada para rastreamento distribuído usando o Application Insights ou o OpenTelemetry. Mais informações podem ser encontradas no exemplo de Diagnóstico do Azure.Core.

Próximas etapas

Além dos cenários introdutórios discutidos, a biblioteca de clientes Hubs de Eventos do Azure oferece suporte para cenários adicionais para ajudar a aproveitar o conjunto completo de recursos do serviço Hubs de Eventos do Azure. Para ajudar a explorar alguns desses cenários, a biblioteca de clientes dos Hubs de Eventos oferece um projeto de exemplos para servir como ilustração para cenários comuns. Confira os exemplos README para obter detalhes.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Consulte nosso guia de contribuição para obter mais informações.

Impressões