Hubs de Eventos do Azure biblioteca de clientes do Processador de Eventos para .NET – versão 5.9.3
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/envio em 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 do Processador de Eventos é um complemento à biblioteca de clientes do Hubs de Eventos do Azure, fornecendo um cliente autônomo para consumir eventos de maneira robusta, durável e escalonável adequada para a maioria dos cenários de produção. Uma implementação opinativa criada usando blobs de Armazenamento do Azure, o Processador de Eventos é recomendado para:
Ler e processar eventos em todas as partições de um Hub de Eventos em escala com resiliência a falhas transitórias e problemas intermitentes de rede.
Processando eventos de forma cooperativa, em que vários processadores distribuem e compartilham dinamicamente a responsabilidade no contexto de um grupo de consumidores, gerenciando normalmente a carga à medida que os processadores são adicionados e removidos do grupo.
Gerenciando pontos de verificação e estado para processamento de maneira durável usando blobs de Armazenamento do Azure como o armazenamento de dados subjacente.
Código-fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do produto | Guia 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 seus benefícios de 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 um 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.
Conta de Armazenamento do Azure com armazenamento de blobs: Para persistir pontos de verificação e controlar a propriedade no Armazenamento do Azure, você precisará ter uma conta de Armazenamento do Azure com blobs disponíveis. A conta de Armazenamento do Azure usada para o processador deve ter a exclusão reversível e o controle de versão de blob desabilitado. Se você não estiver familiarizado com contas de Armazenamento do Azure, convém seguir o guia passo a passo para criar uma conta de armazenamento 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 contas de armazenamento.
Contêiner de blob do Armazenamento do Azure: Os dados de ponto de verificação e propriedade no Armazenamento do Azure serão gravados em blobs em um contêiner específico. O
EventProcessorClientrequer um contêiner existente e não criará implicitamente um para ajudar a proteger contra configuração incorreta acidental. É recomendável que você use um contêiner exclusivo para cada combinação de Hub de Eventos e grupo de consumidores. Se você não estiver familiarizado com contêineres do Armazenamento do Azure, convém consultar a documentação sobre como gerenciar contêineres. Lá, você pode encontrar instruções detalhadas para usar o .NET, a CLI do Azure ou Azure PowerShell para criar um contêiner.C# 8.0: A biblioteca de clientes do 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 linguagem 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 da linguagem, 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.
Para criar rapidamente os recursos necessários no Azure e receber cadeias de conexão para eles, você pode implantar nosso modelo de exemplo clicando em:
Instalar o pacote
Instale a biblioteca de clientes do Processador de Eventos do Hubs de Eventos do Azure para .NET usando o NuGet:
dotnet add package Azure.Messaging.EventHubs.Processor
Autenticar o cliente
Obter uma cadeia de conexão dos Hubs de Eventos
Para que a biblioteca de clientes dos Hubs de Eventos interaja com um Hub de Eventos, ela 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.
Obter uma cadeia de conexão do Armazenamento do Azure
Para que o cliente do processador de eventos use blobs de Armazenamento do Azure para ponto de verificação, ele precisará entender como se conectar a uma conta de armazenamento e autorizar com ela. O método mais simples de fazer isso é usar uma cadeia de conexão, que é gerada no momento em que a conta de armazenamento é criada. Se você não estiver familiarizado com a autorização de cadeia de conexão da conta de armazenamento no Azure, convém seguir o guia passo a passo para configurar cadeias de conexão do Armazenamento do Azure.
Depois de ter as cadeias de conexão, consulte Criando um cliente do processador de eventos para obter um exemplo de como usá-las para criar o processador.
Principais conceitos
Um processador de eventos é um constructo destinado a gerenciar as responsabilidades associadas à conexão a um determinado Hub de Eventos e ao processamento de eventos de cada uma de suas partições, no contexto de um grupo de consumidores específico. O ato de processar eventos lidos da partição e lidar com erros que ocorrem é delegado pelo processador de eventos ao código que você fornece, permitindo que sua lógica se concentre em fornecer valor comercial enquanto o processador lida com as tarefas associadas à leitura de eventos, gerenciamento das partições e permitir que o estado seja persistido na forma de pontos de verificação.
O ponto de verificação é um processo pelo qual os leitores marcam e persistem sua posição para eventos que foram processados para uma partição. O ponto de verificação é responsabilidade do consumidor e ocorre em uma partição, normalmente no contexto de um grupo de consumidores específico. Para o
EventProcessorClient, isso significa que, para uma combinação de grupo de consumidores e partição, o processador deve acompanhar sua posição atual no fluxo de eventos. Se você quiser obter mais informações, consulte o ponto de verificação na documentação do produto hubs de eventos.Quando um processador de eventos se conecta, ele começará a ler eventos no ponto de verificação que foi persistido anteriormente pelo último processador dessa partição nesse grupo de consumidores, se houver. À medida que um processador de eventos lê e atua em eventos na partição, ele deve criar periodicamente pontos de verificação para marcar os eventos como "concluídos" por aplicativos downstream e fornecer resiliência caso um processador de eventos ou o ambiente que o hospeda falhe. Se for necessário, é possível reprocessar eventos que foram marcados anteriormente como "concluídos" especificando um deslocamento anterior por meio desse processo de ponto de verificação.
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 uma discussão mais profunda, consulte: Recursos dos Hubs de Eventos.
Tempo de vida do cliente
O EventProcessorClient é seguro para armazenar em cache e usar como um singleton durante o tempo de vida do aplicativo, o que é uma prática recomendada quando os eventos estão sendo 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 StopProcessingAsync ou StopProcessing no processador é 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 | clienteManipuladores | Tratamento de falhas | Diagnostics | Simulação (processador) | Simulação (tipos de cliente)
Exemplos
Criando um cliente do Processador de Eventos
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. O contêiner usado para configurar o EventProcessorClient deve existir.
Como o EventProcessorClient não tem como saber a intenção de especificar um contêiner que não existe, ele não criará implicitamente o contêiner. Isso atua como uma proteção contra um contêiner configurado incorretamente, fazendo com que um processador não autorizado não consiga compartilhar 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 manipuladores de eventos e erros
Para usar o , os EventProcessorClientmanipuladores para processamento de eventos e erros devem ser fornecidos. Esses manipuladores são considerados independentes e os desenvolvedores são responsáveis por garantir que as exceções no código do manipulador sejam contabilizados.
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 executará seu processamento em segundo plano depois de ter sido iniciado explicitamente e continuará fazendo isso até que tenha sido explicitamente interrompido. Embora isso permita que o código do aplicativo execute outras tarefas, ele também coloca a responsabilidade de garantir que o processo não seja encerrado durante o processamento se não houver outras tarefas sendo 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;
}
Usando uma entidade de segurança do Active Directory com o cliente do Processador de Eventos
A biblioteca de identidade do Azure fornece suporte à autenticação do Azure Active Directory que pode ser usada para as bibliotecas de clientes do Azure, incluindo Hubs de Eventos e Armazenamento do Azure.
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 usar uma entidade de segurança do Active Directory com contêineres de blob do Armazenamento do Azure, a URL totalmente qualificada para o contêiner deve ser fornecida ao criar o cliente de armazenamento. Detalhes sobre os formatos de URI válidos para acessar o Armazenamento de Blobs podem ser encontrados em Nomenclatura e Referência de Contêineres, 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 usar o Azure Active Directory com Hubs de Eventos, sua entidade de segurança deve receber uma função que permita a leitura dos Hubs de Eventos, como a Azure Event Hubs Data Receiver 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.
Ao usar o Azure Active Directory com o Armazenamento do Azure, sua entidade de segurança deve receber uma função que permita acesso de leitura, gravação e exclusão a blobs, como a Storage Blob Data Contributor função. Para obter mais informações sobre como usar a Autorização do Active Directory com o Armazenamento do Azure, consulte a documentação associada e o exemplo de autorização do Armazenamento do Azure.
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.
Tratamento de exceções
Exceções de cliente do Processador de Eventos
O cliente processador de eventos faz todas as tentativas de serem resilientes diante de exceções e tomará as ações necessárias para continuar o processamento, a menos que seja impossível fazê-lo. Nenhuma ação dos desenvolvedores é necessária para que isso ocorra; ele faz parte nativamente do comportamento do processador.
Para permitir aos desenvolvedores a oportunidade de inspecionar e reagir a exceções que ocorrem dentro das operações de cliente do Processador de Eventos, eles são exibidos por meio do ProcessError evento . Os argumentos para esse evento oferecem detalhes sobre a exceção e o contexto no qual ela foi observada. Os desenvolvedores podem executar operações normais no cliente processador de eventos de dentro desse manipulador de eventos, como parar e/ou reiniciá-lo em resposta a erros, mas pode não influenciar o comportamento de exceção do processador.
Para obter um exemplo básico de implementação do manipulador de erros, consulte o exemplo: Manipuladores de processador de eventos.
Exceções em manipuladores de eventos
Como o cliente do Processador de Eventos não tem o contexto apropriado para entender a gravidade das exceções dentro dos manipuladores de eventos que os desenvolvedores fornecem, ele não pode assumir quais ações seriam uma resposta razoável para eles. Como resultado, os desenvolvedores são considerados responsáveis por exceções que ocorrem dentro dos manipuladores de eventos que fornecem usando try/catch blocos e outros constructos de linguagem padrão.
O cliente processador de eventos não tentará detectar exceções no código do desenvolvedor nem exibi-las explicitamente. O comportamento resultante dependerá do ambiente de hospedagem do processador e do contexto no qual o manipulador de eventos foi chamado. Como isso pode variar entre diferentes cenários, é altamente recomendável que os desenvolvedores codifiquem seus manipuladores de eventos defensivamente e sejam responsáveis por possíveis exceções.
Log e diagnóstico
A biblioteca de clientes do Processador 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 do cliente do Processador de Eventos estão disponíveis para qualquer EventListener , optando pela origem chamada "Azure-Messaging-EventHubs-Processor-EventProcessorClient" ou optando por todas as fontes que têm a característica "AzureEventSource". Para facilitar a captura de logs das bibliotecas de cliente do Azure, a Azure.Core biblioteca usada pelos Hubs de Eventos oferece um AzureEventSourceListener. Mais informações podem ser encontradas em Capturando logs dos Hubs de Eventos usando o AzureEventSourceListener.
A biblioteca do Processador de Eventos também é instrumentada para rastreamento distribuído usando o Application Insights ou o OpenTelemetry. Mais informações podem ser encontradas no exemplo diagnóstico do Azure.Core.
Próximas etapas
Além dos cenários discutidos, a biblioteca do processador Hubs de Eventos do Azure oferece suporte para cenários adicionais para ajudar a aproveitar o conjunto completo de recursos do EventProcessorClient. Para ajudar a explorar alguns desses cenários, a biblioteca de clientes do Processador de Hubs de Eventos oferece um projeto de exemplos para servir como uma ilustração para cenários comuns. Consulte 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.
