Compartir a través de

Azure Event Hubs biblioteca cliente para .NET: versión 5.9.3

  • Artículo

Azure Event Hubs es un servicio de publicación y suscripción altamente escalable que puede ingerir millones de eventos por segundo y transmitirlos a varios consumidores. Esto le permite procesar y analizar grandes cantidades de datos generados por los dispositivos y aplicaciones conectados. Una vez que Event Hubs ha recopilado los datos, puede recuperarlos, transformarlos y almacenarlos mediante cualquier proveedor de análisis en tiempo real o con adaptadores de almacenamiento o procesamiento por lotes. Si desea obtener más información sobre Azure Event Hubs, puede que desee revisar: ¿Qué es Event Hubs?

La biblioteca cliente de Azure Event Hubs permite publicar y consumir eventos de Azure Event Hubs y se puede usar para lo siguiente:

  • Emitir telemetría sobre la aplicación con fines de diagnóstico e inteligencia empresarial.

  • Publicar datos sobre el estado de la aplicación que las partes interesadas pueden consultar y usar como desencadenadores para tomar medidas.

  • Observar las operaciones e interacciones interesantes que se están produciendo en el negocio u otro ecosistema, lo que permite que los sistemas de acoplamiento flexible interactúen sin necesidad de enlazarlos.

  • Recibir eventos de uno o varios editores, transformarlos para satisfacer mejor las necesidades del ecosistema y, a continuación, publicar los eventos transformados en un nuevo flujo para que los consumidores los observen.

Código | fuentePaquete (NuGet) | Documentación | de referencia de APIDocumentación | del productoGuía | de migraciónGuía de solución de problemas

Introducción

Requisitos previos

  • Suscripción de Azure: Para usar los servicios de Azure, incluida Azure Event Hubs, necesitará una suscripción. Si no tiene una cuenta de Azure existente, puede registrarse para obtener una evaluación gratuita o usar las ventajas de la suscripción de Visual Studio al crear una cuenta.

  • Espacio de nombres de Event Hubs con un centro de eventos: Para interactuar con Azure Event Hubs, también deberá tener un espacio de nombres y un centro de eventos disponibles. Si no está familiarizado con la creación de recursos de Azure, puede seguir la guía paso a paso para crear un centro de eventos mediante el Azure Portal. Allí también puede encontrar instrucciones detalladas para usar la CLI de Azure, Azure PowerShell o plantillas de Azure Resource Manager (ARM) para crear un centro de eventos.

  • C# 8.0: La biblioteca cliente de Azure Event Hubs usa nuevas características que se introdujeron en C# 8.0. Para aprovechar la sintaxis de C# 8.0, se recomienda compilar con el SDK de .NET Core 3.0 o posterior con una versión de lenguaje de .latest

    Los usuarios de Visual Studio que deseen aprovechar al máximo la sintaxis de C# 8.0 tendrán que usar Visual Studio 2019 o posterior. Visual Studio 2019, incluida la edición gratuita Community, se puede descargar aquí. Los usuarios de Visual Studio 2017 pueden aprovechar la sintaxis de C# 8 haciendo uso del paquete NuGet Microsoft.Net.Compilers y estableciendo la versión del lenguaje, aunque es posible que la experiencia de edición no sea ideal.

    Todavía puede usar la biblioteca con versiones anteriores del lenguaje C#, pero tendrá que administrar miembros asincrónicos enumerables y asincrónicos descartables manualmente en lugar de beneficiarse de la nueva sintaxis. Puede seguir teniendo como destino cualquier versión de marco compatible con el SDK de .NET Core, incluidas las versiones anteriores de .NET Core o .NET Framework. Para obtener más información, vea: cómo especificar marcos de destino.
    Nota importante: Para compilar o ejecutar los ejemplos y los ejemplos sin modificaciones, es necesario usar C# 11.0. Todavía puede ejecutar los ejemplos si decide ajustarlos para otras versiones de lenguaje. Un ejemplo de hacerlo está disponible en el ejemplo: Versiones anteriores del lenguaje.

Para crear rápidamente un conjunto básico de recursos de Event Hubs en Azure y recibir una cadena de conexión para ellos, puede implementar nuestra plantilla de ejemplo haciendo clic en:

Implementación en Azure

Instalar el paquete

Instale la biblioteca cliente de Azure Event Hubs para .NET con NuGet:

dotnet add package Azure.Messaging.EventHubs

Autenticar el cliente

Para que la biblioteca cliente de Event Hubs interactúe con un centro de eventos, deberá comprender cómo conectarse y autorizarla. Los medios más fáciles para hacerlo es usar una cadena de conexión, que se crea automáticamente al crear un espacio de nombres de Event Hubs. Si no está familiarizado con el uso de cadenas de conexión con Event Hubs, puede seguir la guía paso a paso para obtener una cadena de conexión de Event Hubs.

Una vez que tenga una cadena de conexión, se puede crear cualquiera de los tipos de cliente de Event Hubs con ella:

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 obtener ejemplos de autenticación de los clientes de Event Hubs con tipos de credenciales, consulte Uso de una entidad de seguridad de Azure Active Directory (AAD) o el ejemplo identidad y credenciales de acceso compartido .

Para obtener ejemplos de autenticación de los clientes de Event Hubs para una aplicación de ASP.NET Core, consulte Registro con ASP.NET Core inserción de dependencias.

Conceptos clave

  • Un cliente de centros de eventos es la interfaz principal para los desarrolladores que interactúan con la biblioteca cliente de Event Hubs. Hay varios clientes de Event Hubs diferentes, cada uno dedicado a un uso específico de Event Hubs, como la publicación o el consumo de eventos.

  • Un productor de centros de eventos es un tipo de cliente que actúa como origen de datos de telemetría, información de diagnóstico, registros de uso u otros datos de registro, como parte de una solución de dispositivo insertada, una aplicación de dispositivo móvil, un título de juego que se ejecuta en una consola u otro dispositivo, alguna solución empresarial basada en cliente o servidor o un sitio web.

  • Un consumidor de centros de eventos es un tipo de cliente que lee información del centro de eventos y permite su procesamiento. El procesamiento puede implicar agregación, cálculo complejo y filtrado. El procesamiento también puede implicar la distribución o el almacenamiento de la información sin procesar o transformada. Los consumidores de centros de eventos suelen ser componentes sólidos y a gran escala de la infraestructura de la plataforma con funcionalidades de análisis integradas, como Azure Stream Analytics, Apache Spark o Apache Storm.

  • Una partición es una secuencia ordenada de eventos que se mantiene en un centro de eventos. Las particiones son un medio de organización de datos asociado al paralelismo requerido por los consumidores de eventos. Azure Event Hubs proporciona streaming de mensajes a través de un patrón de consumidor con particiones en el que cada consumidor solo lee un subconjunto específico, o partición, de la secuencia de mensajes. A medida que llegan eventos más recientes, se agregan al final de esta secuencia. El número de particiones se especifica en el momento en que se crea un centro de eventos y no se puede modificar.

  • Un grupo de consumidores es una vista de un centro de eventos completo. Los grupos de consumidores habilitan a varias aplicaciones de consumo para que cada una de ellas tenga una vista independiente de la secuencia de eventos, y para que lea la secuencia de manera independiente a su propio ritmo y desde su propia ubicación. Puede haber como máximo cinco lectores simultáneos en una partición por grupo de consumidores; sin embargo, se recomienda que solo haya un consumidor activo para un emparejamiento determinado de partición y grupo de consumidores. Cada lector activo recibe todos los eventos de su partición; si hay varios lectores en la misma partición, recibirán eventos duplicados.

Para obtener más conceptos y una explicación más detallada, consulte: Características de Event Hubs.

Duración del cliente

Cada uno de los tipos de cliente de Event Hubs es seguro almacenar en caché y usar como singleton durante la vigencia de la aplicación, que es el procedimiento recomendado cuando se publican o leen eventos con regularidad. Los clientes son responsables de la administración eficaz de la red, la CPU y el uso de memoria, trabajando para mantener el uso bajo durante períodos de inactividad. CloseAsync Es necesario llamar a o DisposeAsync en un cliente para asegurarse de que los recursos de red y otros objetos no administrados se limpien correctamente.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente sean seguros para subprocesos e independientes entre sí (guía). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Los tipos de modelo de datos, como EventData y EventDataBatch no son seguros para subprocesos. No deben compartirse entre subprocesos ni usarse simultáneamente con métodos de cliente.

Conceptos adicionales

Opciones | de clienteControl de errores | Diagnóstico | Burla

Ejemplos

Inspección de un centro de eventos

Muchas operaciones del centro de eventos tienen lugar dentro del ámbito de una partición específica. Dado que las particiones son propiedad del centro de eventos, sus nombres se asignan en el momento en que se crean. Para saber qué particiones están disponibles, consulte el centro de eventos mediante uno de los clientes del centro de eventos. A modo de ilustración, se muestra EventHubProducerClient en estos ejemplos, pero el concepto y la forma son comunes entre los 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();
}

Publicación de eventos en un centro de eventos

Para publicar eventos, deberá crear un elemento EventHubProducerClient. Los productores publican eventos por lotes y pueden solicitar una partición específica o permitir que el servicio Event Hubs decida en qué eventos de partición se deben publicar. Se recomienda usar el enrutamiento automático cuando la publicación de eventos debe ser de alta disponibilidad o cuando los datos del evento se deben distribuir uniformemente entre las particiones. Nuestro ejemplo utilizará el enrutamiento 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);
}

Lectura de eventos desde un centro de eventos

Para leer eventos de un centro de eventos, deberá crear un EventHubConsumerClient para un grupo de consumidores determinado. Cuando se crea un centro de eventos, proporciona un grupo de consumidores predeterminado que se puede usar para empezar a explorar Event Hubs. En nuestro ejemplo, nos centraremos en leer todos los eventos publicados en el centro de eventos mediante un iterador.

Nota: Es importante tener en cuenta que este enfoque para consumir está pensado para mejorar la experiencia de explorar la biblioteca cliente de Event Hubs y crear prototipos. Se recomienda no utilizarlo en escenarios de producción. Para su uso en producción, se recomienda usar el cliente de procesador de eventos, ya que proporciona una experiencia más sólida y mejorada.

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

Lectura de eventos desde una partición de un centro de eventos

Para leer eventos de una partición del centro de eventos, deberá crear un EventHubConsumerClient para un grupo de consumidores determinado. Cuando se crea un centro de eventos, proporciona un grupo de consumidores predeterminado que se puede usar para empezar a explorar Event Hubs. Para leer desde una partición específica, el consumidor también tendrá que especificar dónde en el flujo de eventos para empezar a recibir eventos; en nuestro ejemplo, nos centraremos en leer todos los eventos publicados para la primera partición del centro 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.
    }
}

Procesamiento de eventos mediante un cliente de procesador de eventos

Para la mayoría de los escenarios de producción, se recomienda usar el cliente del procesador de eventos para leer y procesar eventos. El procesador está pensado para proporcionar una experiencia sólida para procesar eventos en todas las particiones de un centro de eventos de una manera eficaz y tolerante a errores, a la vez que proporciona un medio para conservar su estado. Los clientes del procesador de eventos también pueden trabajar de forma cooperativa en el contexto de un grupo de consumidores para un centro de eventos determinado, donde administrarán automáticamente la distribución y el equilibrio de trabajo a medida que las instancias estén disponibles o no estén disponibles para el grupo.

Dado que EventProcessorClient tiene una dependencia de los blobs de Azure Storage para la persistencia de su estado, deberá proporcionar un BlobContainerClient para el procesador, que se ha configurado para la cuenta de almacenamiento y el contenedor que se deben usar.

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;
}

Puede encontrar más detalles en el ARCHIVO LÉAME del cliente del procesador de eventos y en los ejemplos adjuntos.

Uso de una entidad de seguridad de Active Directory con los clientes del centro de eventos

La biblioteca de identidades de Azure proporciona compatibilidad con la autenticación de Azure Active Directory (AAD), que se puede usar para las bibliotecas cliente de Azure, incluidos Event Hubs.

Para usar una entidad de seguridad de Active Directory, se especifica una de las credenciales disponibles de la Azure.Identity biblioteca al crear el cliente de Event Hubs. Además, el espacio de nombres completo de Event Hubs y el nombre del centro de eventos deseado se proporcionan en lugar de la cadena de conexión de Event Hubs. A modo de ilustración, se muestra EventHubProducerClient en estos ejemplos, pero el concepto y la forma son comunes entre los 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);
}

Al usar Azure Active Directory, la entidad de seguridad debe tener asignado un rol que permita el acceso a Event Hubs, como el Azure Event Hubs Data Owner rol . Para más información sobre el uso de la autorización de Azure Active Directory con Event Hubs, consulte la documentación asociada.

Registro con inserción de dependencias de ASP.NET Core

Para insertar uno de los clientes de Event Hubs como una dependencia en una aplicación de ASP.NET Core, instale la integración de la biblioteca cliente de Azure para ASP.NET Core paquete.

dotnet add package Microsoft.Extensions.Azure

Después de la instalación, registre los tipos de cliente de Event Hubs deseados en el Startup.ConfigureServices método :

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

Para usar el código anterior, agréguelo a la configuración de la aplicación:

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

En el caso de las aplicaciones que prefieren usar una credencial compartida Azure.Identity para sus clientes, el registro tiene un aspecto ligeramente 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 más información, consulte Inserción de dependencias con el SDK de Azure para .NET.

Solución de problemas

Para obtener información detallada sobre la solución de problemas, consulte la Guía de solución de problemas de Event Hubs.

Registro y diagnósticos

La biblioteca cliente de Event Hubs está totalmente instrumentada para registrar información en varios niveles de detalle mediante .NET EventSource para emitir información. El registro se realiza para cada operación y sigue el patrón de marcar el punto inicial de la operación, su finalización y las excepciones encontradas. También se registra información adicional que puede ofrecer información en el contexto de la operación asociada.

Los registros de cliente de Event Hubs están disponibles para cualquier EventListener mediante la participación en el origen denominado "Azure-Messaging-EventHubs" o la participación en todos los orígenes que tienen el rasgo "AzureEventSource". Para facilitar la captura de registros de las bibliotecas cliente de Azure, la Azure.Core biblioteca usada por Event Hubs ofrece un AzureEventSourceListener. Puede encontrar más información en Captura de registros de Event Hubs mediante AzureEventSourceListener.

La biblioteca cliente de Event Hubs también se instrumenta para el seguimiento distribuido mediante Application Insights o OpenTelemetry. Puede encontrar más información en el ejemplo Azure.Core Diagnostics.

Pasos siguientes

Además de los escenarios introductorios descritos, la biblioteca cliente de Azure Event Hubs ofrece compatibilidad con escenarios adicionales para ayudar a aprovechar el conjunto de características completo del servicio Azure Event Hubs. Para ayudar a explorar algunos de estos escenarios, la biblioteca cliente de Event Hubs ofrece un proyecto de ejemplos que sirve como ilustración para escenarios comunes. Consulte los ejemplos Léame para obtener más información.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Consulte nuestra guía de contribución para obtener más información.

Impresiones