Hubs de Eventos do Azure biblioteca de cliente do Processador de Eventos 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 as enormes 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/lotes. 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 do Processador de Eventos é um complemento da biblioteca de cliente Hubs de Eventos do Azure, fornecendo um cliente autónomo para consumir eventos de uma forma robusta, durável e dimensionável adequada para a maioria dos cenários de produção. Uma implementação opinada criada com blobs de Armazenamento do Azure, o Processador de Eventos é recomendado para:
Eventos de leitura e processamento em todas as partições de um Hub de Eventos em escala com resiliência a falhas transitórias e problemas de rede intermitentes.
Processar eventos em cooperação, em que vários processadores distribuem e partilham dinamicamente a responsabilidade no contexto de um grupo de consumidores, gerindo corretamente a carga à medida que os processadores são adicionados e removidos do grupo.
Gerir pontos de verificação e estado para processamento de forma durável com os blobs do Armazenamento do Azure como o arquivo de dados subjacente.
Código fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do | produto Guia 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. Aí, também pode encontrar instruções detalhadas para utilizar os modelos da CLI do Azure, do Azure PowerShell ou do Azure Resource Manager (ARM) para criar um Hub de Eventos.
Conta de Armazenamento do Azure com armazenamento de blobs: Para manter os pontos de verificação e governar a propriedade no Armazenamento do Azure, terá de ter uma conta de Armazenamento do Azure com blobs disponíveis. Se não estiver familiarizado com as contas de Armazenamento do Azure, poderá querer seguir o guia passo a passo para criar uma conta de armazenamento com o portal do Azure. Aí, também pode encontrar instruções detalhadas para utilizar os modelos da CLI do Azure, do Azure PowerShell ou do Azure Resource Manager (ARM) para criar contas de armazenamento.
Contentor de blobs do Armazenamento do Azure: Os dados de propriedade e ponto de verificação no Armazenamento do Azure serão escritos em blobs num contentor específico. O
EventProcessorClientrequer um contentor existente e não irá criar implicitamente um para ajudar a proteger-se contra a configuração incorreta acidental. Se não estiver familiarizado com os contentores do Armazenamento do Azure, poderá querer consultar a documentação sobre a gestão de contentores. Aí, pode encontrar instruções detalhadas para utilizar o .NET, a CLI do Azure ou Azure PowerShell para criar um contentor.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 idioma 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 Comunidade 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 definir a versão de idioma, embora a experiência de edição possa não ser a ideal.
Ainda pode utilizar a biblioteca com versões de idioma C# anteriores, mas terá de gerir os membros descartáveis assíncronos e enumerados manualmente em vez de beneficiar da nova sintaxe. Pode ainda 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 do C# 11.0. Ainda pode executar os exemplos se decidir alterá-los para outras versões de idioma.
Para criar rapidamente os recursos necessários no Azure e receber cadeias de ligação para os mesmos, pode implementar o nosso modelo de exemplo ao clicar em:
Instalar o pacote
Instale a biblioteca de cliente do Processador de Eventos Hubs de Eventos do Azure para .NET com o NuGet:
dotnet add package Azure.Messaging.EventHubs.Processor
Autenticar o cliente
Obter uma cadeia de ligação dos Hubs de Eventos
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. O meio mais fácil para tal é 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á querer seguir o guia passo a passo para obter uma cadeia de ligação dos Hubs de Eventos.
Obter uma cadeia de ligação do Armazenamento do Azure
Para que o cliente do processador de eventos utilize os blobs de Armazenamento do Azure para o ponto de verificação, terá de compreender como ligar a uma conta de armazenamento e autorizar com a mesma. O método mais simples de o fazer é utilizar uma cadeia de ligação, que é gerada no momento em que a conta de armazenamento é criada. Se não estiver familiarizado com a autorização da cadeia de ligação da conta de armazenamento no Azure, poderá querer seguir o guia passo a passo para configurar cadeias de ligação do Armazenamento do Azure.
Conceitos-chave
Um processador de eventos é uma construção destinada a gerir as responsabilidades associadas à ligação a um determinado Hub de Eventos e ao processamento de eventos de cada uma das suas partições, no contexto de um grupo de consumidores específico. O ato de processamento de eventos lidos a partir da partição e processamento de erros que ocorram é delegado pelo processador de eventos ao código que fornecer, permitindo que a sua lógica se concentre na entrega de valor empresarial enquanto o processador processa as tarefas associadas a eventos de leitura, gere as partições e permite que o estado seja mantido sob a forma de pontos de verificação.
O ponto de verificação é um processo pelo qual os leitores marcam e persistem a sua posição para eventos que foram processados para uma partição. O ponto de verificação é da responsabilidade do consumidor e ocorre numa partição por partição, normalmente no contexto de um grupo de consumidores específico. Para o
EventProcessorClient, isto significa que, para um grupo de consumidores e combinação de partições, o processador tem de controlar a sua posição atual no fluxo de eventos. Se quiser obter mais informações, veja ponto de verificação na documentação do produto dos Hubs de Eventos.Quando um processador de eventos se liga, começará a ler eventos no ponto de verificação que foi anteriormente mantido pelo último processador dessa partição nesse grupo de consumidores, se existir. À medida que um processador de eventos lê e atua em eventos na partição, deve criar periodicamente pontos de verificação para marcar os eventos como "concluídos" por aplicações a jusante e para fornecer resiliência caso um processador de eventos ou o ambiente que o aloja falhe. Se for necessário, é possível reprocessar eventos que foram marcados anteriormente como "concluídos" ao especificar um desvio anterior através deste processo de ponto de verificação.
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 em fluxo 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 várias aplicações de consumo tenham uma vista separada do fluxo de eventos e leiam o fluxo de forma independente ao seu próprio ritmo e 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 partição 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 uma discussão mais aprofundada, consulte: Funcionalidades dos Hubs de Eventos.
Duração do cliente
É EventProcessorClient seguro colocar em cache e utilizar como singleton durante a duração da aplicação, o que é a melhor prática quando os eventos estão a ser 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. As chamadas StopProcessingAsync ou StopProcessing o processador são necessários 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 partilhadas entre threads nem utilizadas em simultâneo com métodos de cliente.
Conceitos adicionais
Opções de | cliente Processadores de eventos | Lidar com falhas | Diagnósticos | Zombaria (processador) | Zombaria (tipos de cliente)
Exemplos
Criar um cliente do Processador de Eventos
Uma vez que o EventProcessorClient tem uma dependência dos blobs do 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. O contentor utilizado para configurar o EventProcessorClient tem de existir.
EventProcessorClient Uma vez que não tem forma de saber a intenção de especificar um contentor que não existe, não irá criar implicitamente o contentor. Isto funciona como um proteção contra um contentor mal configurado, o que faz com que um processador não autorizado não consiga partilhar a propriedade e interferir com outros processadores no grupo de consumidores.
// The container specified when creating the BlobContainerClient must exist; it will
// not be implicitly created.
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 >>";
var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);
Configurar os processadores de eventos e erros
Para utilizar o EventProcessorClient, os processadores para processamento de eventos e erros têm de ser fornecidos. Estes processadores são considerados autónomos e os programadores são responsáveis por garantir que as exceções no código do processador são contabilizadas.
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 >>";
async Task processEventHandler(ProcessEventArgs eventArgs)
{
try
{
// Perform the application-specific processing for an event. This method
// is intended for illustration and is not defined in this snippet.
await DoSomethingWithTheEvent(eventArgs.Partition, eventArgs.Data);
}
catch
{
// Handle the exception from handler code
}
}
async Task processErrorHandler(ProcessErrorEventArgs eventArgs)
{
try
{
// Perform the application-specific processing for an error. This method
// is intended for illustration and is not defined in this snippet.
await DoSomethingWithTheError(eventArgs.Exception);
}
catch
{
// Handle the exception from handler code
}
}
var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);
processor.ProcessEventAsync += processEventHandler;
processor.ProcessErrorAsync += processErrorHandler;
Iniciar e parar o processamento
O EventProcessorClient irá efetuar o processamento em segundo plano depois de ter sido explicitamente iniciado e continuar a fazê-lo até que tenha sido explicitamente interrompido. Embora isto permita que o código da aplicação efetue outras tarefas, também atribui a responsabilidade de garantir que o processo não termina durante o processamento se não existirem outras tarefas a serem executadas.
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;
}
Utilizar um principal do Active Directory com o cliente do Processador de Eventos
A biblioteca de Identidade 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 e o Armazenamento do Azure.
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 utilizar um principal do Active Directory com contentores de blobs de Armazenamento do Azure, o URL completamente qualificado para o contentor tem de ser fornecido ao criar o cliente de armazenamento. Os detalhes sobre os formatos URI válidos para aceder ao armazenamento de Blobs podem ser encontrados em Nomenclatura e Referência de Contentores, Blobs e Metadados.
var credential = new DefaultAzureCredential();
var blobStorageUrl ="<< FULLY-QUALIFIED CONTAINER URL (like https://myaccount.blob.core.windows.net/mycontainer) >>";
var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var consumerGroup = "<< NAME OF THE EVENT HUB CONSUMER GROUP >>";
var storageClient = new BlobContainerClient(new Uri(blobStorageUrl), credential);
var processor = new EventProcessorClient
(
storageClient,
consumerGroup,
fullyQualifiedNamespace,
eventHubName,
credential
);
Ao utilizar o Azure Active Directory com Hubs de Eventos, tem de lhe ser atribuída uma função principal que permita a leitura a partir dos Hubs de Eventos, como a função Azure Event Hubs Data Receiver . 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.
Ao utilizar o Azure Active Directory com o Armazenamento do Azure, tem de lhe ser atribuída uma função que permita o acesso de leitura, escrita e eliminação a blobs, como a função Storage Blob Data Contributor . Para obter mais informações sobre como utilizar a Autorização do Active Directory com o Armazenamento do Azure, veja a documentação associada e o exemplo de autorização do Armazenamento do Azure.
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.
Processamento de exceções
Exceções do cliente do Processador de Eventos
O cliente do Processador de Eventos faz todas as tentativas de ser resiliente face a exceções e tomará as ações necessárias para continuar o processamento, a menos que seja impossível fazê-lo. Não é necessária qualquer ação por parte dos programadores para que isto ocorra; faz parte nativa do comportamento do processador.
Para permitir aos programadores a oportunidade de inspecionar e reagir a exceções que ocorrem nas operações de cliente do Processador de Eventos, estes são apresentados através do ProcessError evento. Os argumentos para este evento oferecem detalhes sobre a exceção e o contexto em que foi observado. Os programadores podem realizar operações normais no cliente do Processador de Eventos a partir deste processador de eventos, como parar e/ou reiniciá-lo em resposta a erros, mas podem não influenciar o comportamento de exceção do processador.
Para obter um exemplo básico de implementação do processador de erros, veja o exemplo: Processadores de Processadores de Eventos.
Exceções nos processadores de eventos
Uma vez que o cliente do Processador de Eventos não tem o contexto adequado para compreender a gravidade das exceções nos processadores de eventos que os programadores fornecem, não pode assumir que ações seriam uma resposta razoável às mesmas. Como resultado, os programadores são considerados responsáveis por exceções que ocorrem nos processadores de eventos que fornecem através try/catch de blocos e outras construções de linguagem padrão.
O cliente do Processador de Eventos não tentará detetar exceções no código do programador nem aparecer explicitamente. O comportamento resultante dependerá do ambiente de alojamento do processador e do contexto no qual o processador de eventos foi chamado. Uma vez que isto pode variar entre diferentes cenários, recomenda-se vivamente que os programadores codizem os respetivos processadores de eventos defensivamente e considerem possíveis exceções.
Registo e diagnóstico
A biblioteca de cliente do Processador 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 do cliente do Processador de Eventos estão disponíveis para qualquer EventListener um ao optar pela origem com o nome "Azure-Messaging-EventHubs-Processor-EventProcessorClient" 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 do Processador 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 abordados, a biblioteca de Processador Hubs de Eventos do Azure oferece suporte para cenários adicionais para ajudar a tirar partido do conjunto completo de funcionalidades do EventProcessorClient. Para ajudar a explorar alguns destes cenários, a biblioteca de cliente processador 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