Hubs de Eventos do Azure biblioteca de cliente para .NET – versão 5.8.1
Hubs de Eventos do Azure é um serviço de publicação-subscrição altamente dimensionável que pode ingerir milhões de eventos por segundo e transmiti-los em fluxo para vários consumidores. Isto permite-lhe processar e analisar grandes quantidades de dados produzidos pelos seus dispositivos e aplicações ligados. Assim que os Hubs de Eventos recolherem os dados, pode recuperá-los, transformá-los e armazená-los utilizando qualquer fornecedor de análise em tempo real ou com adaptadores de armazenamento/batching. Se quiser saber mais sobre Hubs de Eventos do Azure, poderá querer rever: O que são os Hubs de Eventos.
A biblioteca de cliente dos Hubs de Eventos do Azure permite a publicação e o consumo de eventos dos Hubs de Eventos do Azure e pode ser utilizada para:
Emitir telemetria sobre a aplicação para fins de diagnóstico e business intelligence.
Publicar factos sobre o estado da aplicação que as partes interessadas podem observar e utilizar como acionador para tomar medidas.
Observar operações e interações interessantes que ocorrem na sua empresa ou noutro ecossistema, o que permite aos sistemas acoplados interagir sem terem de estar associados.
Receber eventos de um ou mais publicadores, transformá-los para satisfazer melhor as necessidades do seu ecossistema e, em seguida, publicar os eventos transformados num novo fluxo para os consumidores observarem.
Código fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do | produto Guia | de migraçãoGuia de resolução de problemas
Introdução
Pré-requisitos
Subscrição do Azure: Para utilizar os serviços do Azure, incluindo Hubs de Eventos do Azure, precisará de uma subscrição. Se não tiver uma conta do Azure existente, poderá inscrever-se numa avaliação gratuita ou utilizar os benefícios da Subscrição do Visual Studio quando criar uma conta.
Espaço de nomes dos Hubs de Eventos com um Hub de Eventos: Para interagir com Hubs de Eventos do Azure, também terá de ter um espaço de nomes e o Hub de Eventos disponíveis. Se não estiver familiarizado com a criação de recursos do Azure, poderá querer seguir o guia passo a passo para criar um Hub de Eventos com o portal do Azure. Aqui, também pode encontrar instruções detalhadas para utilizar a CLI do Azure, Azure PowerShell ou modelos do Azure Resource Manager (ARM) para criar um Hub de Eventos.
C# 8.0: A biblioteca de cliente Hubs de Eventos do Azure utiliza as novas funcionalidades que foram introduzidas no C# 8.0. Para tirar partido da sintaxe C# 8.0, recomenda-se que compile com o SDK .NET Core 3.0 ou superior com uma versão de linguagem do
latest.Os utilizadores do Visual Studio que pretendam tirar o máximo partido da sintaxe C# 8.0 terão de utilizar o Visual Studio 2019 ou posterior. O Visual Studio 2019, incluindo a edição Community gratuita, pode ser transferido aqui. Os utilizadores do Visual Studio 2017 podem tirar partido da sintaxe C# 8 ao utilizar o pacote NuGet Microsoft.Net.Compilers e ao definir a versão do idioma, embora a experiência de edição possa não ser a ideal.
Ainda pode utilizar a biblioteca com versões de linguagem C# anteriores, mas terá de gerir manualmente membros descartáveis assíncronos e enumerados assíncronos em vez de beneficiar da nova sintaxe. Ainda pode visar qualquer versão de arquitetura suportada pelo seu SDK .NET Core, incluindo versões anteriores do .NET Core ou do .NET Framework. Para obter mais informações, veja: como especificar arquiteturas de destino.
Nota Importante: Para criar ou executar os exemplos e os exemplos sem modificação, é necessária a utilização de C# 11.0. Ainda pode executar os exemplos se decidir alterá-los para outras versões de idioma. Está disponível um exemplo de como fazê-lo no exemplo: Versões de Idioma Anteriores.
Para criar rapidamente um conjunto básico de recursos dos Hubs de Eventos no Azure e para receber uma cadeia de ligação para os mesmos, pode implementar o nosso modelo de exemplo ao clicar em:
Instalar o pacote
Instale a biblioteca de cliente Hubs de Eventos do Azure para .NET com NuGet:
dotnet add package Azure.Messaging.EventHubs
Autenticar o cliente
Para que a biblioteca de cliente dos Hubs de Eventos interaja com um Hub de Eventos, terá de compreender como ligar e autorizar com o mesmo. A forma mais fácil de o fazer é utilizar uma cadeia de ligação, que é criada automaticamente ao criar um espaço de nomes dos Hubs de Eventos. Se não estiver familiarizado com a utilização de cadeias de ligação com os Hubs de Eventos, poderá seguir o guia passo a passo para obter uma cadeia de ligação dos Hubs de Eventos.
Conceitos-chave
Um cliente do Hub de Eventos é a interface principal para programadores que interagem com a biblioteca de cliente dos Hubs de Eventos. Existem vários clientes do Hub de Eventos diferentes, cada um dedicado a uma utilização específica dos Hubs de Eventos, como publicar ou consumir eventos.
Um produtor do Hub de Eventos é um tipo de cliente que serve como uma origem de dados telemétricos, informações de diagnóstico, registos de utilização ou outros dados de registo, como parte de uma solução de dispositivo incorporado, uma aplicação de dispositivo móvel, um título de jogo em execução numa consola ou outro dispositivo, alguma solução empresarial baseada em cliente ou servidor ou um site.
Um consumidor do Hub de Eventos é um tipo de cliente que lê informações do Hub de Eventos e permite o processamento das mesmas. O processamento pode envolver agregação, computação e filtragem complexas. O processamento também pode envolver a distribuição ou o armazenamento das informações de forma não processada ou transformada. Os consumidores do Hub de Eventos são, muitas vezes, peças de infraestrutura de plataforma robustas e de grande escala com capacidades de análise incorporadas, como o Azure Stream Analytics, o Apache Spark ou o Apache Storm.
Uma partição é uma sequência ordenada de eventos que é realizada num Hub de Eventos. As partições são um meio de organização de dados associada ao paralelismo exigido pelos consumidores de eventos. Hubs de Eventos do Azure fornece a transmissão de mensagens através 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 chegam novos eventos, eles são adicionados ao final desta 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 vista de um Hub de Eventos inteiro. Os grupos de consumidores permitem que cada uma tenha uma vista separada do fluxo de eventos e leia o fluxo de forma independente ao seu próprio ritmo e a partir da sua própria posição. Pode haver, no máximo, 5 leitores simultâneos numa partição por grupo de consumidores; no entanto, recomenda-se que exista apenas um consumidor ativo para uma determinada criação de partições e emparelhamento de grupos de consumidores. Cada leitor ativo recebe todos os eventos da sua partição; Se existirem vários leitores na mesma partição, receberão eventos duplicados.
Para obter mais conceitos e debates mais aprofundados, veja: Funcionalidades dos Hubs de Eventos.
Duração do cliente
Cada um dos tipos de cliente dos Hubs de Eventos é seguro para colocar em cache e utilizar como singleton durante a duração da aplicação, que é a melhor prática quando os eventos são publicados ou lidos regularmente. Os clientes são responsáveis pela gestão eficiente da utilização de rede, CPU e memória, trabalhando para manter a utilização baixa durante períodos de inatividade. CloseAsync É necessário chamar ou DisposeAsync num cliente para garantir que os recursos de rede e outros objetos não geridos são devidamente limpos.
Segurança de threads
Garantimos que todos os métodos de instância de cliente são seguros para threads e independentes uns dos outros (orientação). Isto garante que a recomendação de reutilização de instâncias de cliente é sempre segura, mesmo entre threads.
Os tipos de modelo de dados, como EventData e EventDataBatch não são seguros para threads. Não devem ser partilhados entre threads nem utilizados em simultâneo com métodos de cliente.
Conceitos adicionais
Opções de | cliente Lidar com falhas | Diagnósticos | A gozar
Exemplos
Inspecionar um Hub de Eventos
Muitas operações do Hub de Eventos ocorrem no âmbito de uma partição específica. Uma vez que as partições pertencem ao Hub de Eventos, os respetivos nomes são atribuídos no momento da criação. Para compreender que partições estão disponíveis, consulte o Hub de Eventos com um dos clientes do Hub de Eventos. Para ilustração, o EventHubProducerClient é demonstrado nestes exemplos, mas o conceito e a forma são comuns entre clientes.
var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
string[] partitionIds = await producer.GetPartitionIdsAsync();
}
Publicar eventos num Hub de Eventos
Para publicar eventos, terá de criar um EventHubProducerClient. Os produtores publicam eventos em lotes e podem pedir uma partição específica ou permitir que o serviço dos Hubs de Eventos decida em que eventos de partição devem ser publicados. É recomendado utilizar o encaminhamento automático quando a publicação de eventos tem de estar altamente disponível ou quando os dados de eventos devem ser distribuídos uniformemente entre as partições. O nosso exemplo irá tirar partido do encaminhamento automático.
var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
using EventDataBatch eventBatch = await producer.CreateBatchAsync();
eventBatch.TryAdd(new EventData(new BinaryData("First")));
eventBatch.TryAdd(new EventData(new BinaryData("Second")));
await producer.SendAsync(eventBatch);
}
Ler eventos a partir de um Hub de Eventos
Para ler eventos a partir de um Hub de Eventos, terá de criar um EventHubConsumerClient para um determinado grupo de consumidores. Quando um Hub de Eventos é criado, fornece um grupo de consumidores predefinido que pode ser utilizado para começar a explorar os Hubs de Eventos. No nosso exemplo, vamos concentrar-nos na leitura de todos os eventos que foram publicados no Hub de Eventos com um iterador.
Nota: É importante ter em atenção que esta abordagem ao consumo se destina a melhorar a experiência de exploração da biblioteca de cliente e prototipagem dos Hubs de Eventos. Recomenda-se que não seja utilizado em cenários de produção. Para utilização de produção, recomendamos a utilização do Cliente do Processador de Eventos, uma vez que proporciona uma experiência mais robusta e eficaz.
var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;
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 de uma partição do Hub de Eventos
Para ler eventos para uma partição do Hub de Eventos, terá de criar um EventHubConsumerClient para um determinado grupo de consumidores. Quando um Hub de Eventos é criado, fornece um grupo de consumidores predefinido que pode ser utilizado para começar a explorar os Hubs de Eventos. Para ler a partir de uma partição específica, o consumidor também terá de especificar onde no fluxo de eventos para começar a receber eventos; no nosso exemplo, vamos concentrar-nos 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;
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 com um cliente do Processador de Eventos
Para a maioria dos cenários de produção, recomenda-se que o Cliente do Processador de Eventos seja utilizado para ler e processar eventos. O processador destina-se a proporcionar uma experiência robusta para processar eventos em todas as partições de um Hub de Eventos de forma eficaz e tolerante a falhas, ao mesmo tempo que fornece um meio para manter o seu estado. Os clientes do Processador de Eventos também são capazes de trabalhar em cooperação no contexto de um grupo de consumidores para um determinado Hub de Eventos, onde irão gerir automaticamente a distribuição e o equilíbrio de trabalho à medida que as instâncias ficam disponíveis ou indisponíveis para o grupo.
Uma vez que o EventProcessorClient tem uma dependência dos blobs de Armazenamento do Azure para persistência do respetivo estado, terá de fornecer um BlobContainerClient para o processador, que foi configurado para a conta de armazenamento e contentor que deve ser utilizado.
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;
}
Pode encontrar mais detalhes no README do Cliente do Processador de Eventos e nos exemplos que o acompanham.
Utilizar um principal do Active Directory com os clientes do Hub de Eventos
A biblioteca de Identidades do Azure fornece suporte de autenticação do Azure Active Directory que pode ser utilizado para as bibliotecas de cliente do Azure, incluindo os Hubs de Eventos.
Para utilizar um principal do Active Directory, é especificada uma das credenciais disponíveis da Azure.Identity biblioteca ao criar o cliente dos Hubs de Eventos. Além disso, o espaço de nomes dos Hubs de Eventos completamente qualificado e o nome do Hub de Eventos pretendido são fornecidos em vez da cadeia de ligação dos Hubs de Eventos. Para ilustração, o EventHubProducerClient é demonstrado nestes exemplos, mas o conceito e a forma são comuns entre clientes.
var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();
await using (var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential))
{
using EventDataBatch eventBatch = await producer.CreateBatchAsync();
eventBatch.TryAdd(new EventData(new BinaryData("First")));
eventBatch.TryAdd(new EventData(new BinaryData("Second")));
await producer.SendAsync(eventBatch);
}
Ao utilizar o Azure Active Directory, tem de ser atribuída uma função ao principal que permita o acesso aos Hubs de Eventos, como a função Azure Event Hubs Data Owner . Para obter mais informações sobre como utilizar a autorização do Azure Active Directory com os Hubs de Eventos, veja a documentação associada.
Resolução de problemas
Para obter informações detalhadas sobre a resolução de problemas, veja o Guia de Resolução de Problemas dos Hubs de Eventos.
Registo e diagnóstico
A biblioteca de cliente dos Hubs de Eventos está totalmente instrumentada para informações de registo em vários níveis de detalhe através do .NET EventSource para emitir informações. O registo é efetuado para cada operação e segue o padrão de marcação do ponto de partida da operação, a sua conclusão e quaisquer exceções encontradas. As informações adicionais que podem oferecer informações também são registadas no contexto da operação associada.
Os registos de cliente dos Hubs de Eventos estão disponíveis para qualquer EventListener um ao optar pela origem com o nome "Azure-Messaging-EventHubs" ou optar por todas as origens com o traço "AzureEventSource". Para facilitar a captura de registos das bibliotecas de cliente do Azure, a Azure.Core biblioteca utilizada pelos Hubs de Eventos oferece um AzureEventSourceListener. Pode encontrar mais informações em Capturar registos dos Hubs de Eventos com o AzureEventSourceListener.
A biblioteca de cliente dos Hubs de Eventos também é instrumentada para rastreio distribuído com o Application Insights ou o OpenTelemetry. Pode encontrar mais informações no exemplo de Diagnóstico Azure.Core.
Passos seguintes
Para além dos cenários introdutórios discutidos, a biblioteca de cliente Hubs de Eventos do Azure oferece suporte para cenários adicionais para ajudar a tirar partido do conjunto completo de funcionalidades do serviço Hubs de Eventos do Azure. Para ajudar a explorar alguns destes cenários, a biblioteca de cliente dos Hubs de Eventos oferece um projeto de exemplos para servir de ilustração para cenários comuns. Veja os exemplos README para obter detalhes.
Contribuir
Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.
Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.
Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.
Consulte o nosso guia de contribuição para obter mais informações.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários