Guía de programación de .NET para Azure Event Hubs (paquete heredado Microsoft.Azure.EventHubs)

En este artículo se describen algunos escenarios comunes para escribir código mediante Azure Event Hubs. En él se presupone un conocimiento previo de Event Hubs. Para obtener una visión general conceptual de Event Hubs, consulte la Información general de Azure Event Hubs.

Advertencia

Esta guía se refiere al paquete Microsoft.Azure.EventHubs anterior. Se recomienda migrar el código a fin de usar el paquete Azure.Messaging.EventHubs más reciente.

Publicadores de eventos

Los eventos se envían a un centro de eventos mediante HTTP POST o una conexión AMQP 1.0. La elección de cuál usar y cuándo depende del escenario específico abordado. Las conexiones AMQP 1.0 se miden como conexiones asincrónicas en Service Bus y son más apropiadas en los escenarios con volúmenes mayores de mensajes frecuentes y requisitos de latencia menores, ya que proporcionan un canal de mensajería persistente.

Si se usan las API administradas de .NET, las construcciones principales para publicar datos en Event Hubs son las clases EventHubClient y EventData. EventHubClient proporciona el canal de comunicación AMQP a través del que se envían eventos al centro de eventos. La clase EventData representa un evento y se usa para publicar mensajes en un centro de eventos. Esta clase incluye el cuerpo, algunos metadatos (Properties) e información de encabezado (SystemProperties) sobre el evento. Otras propiedades se agregan al objeto EventData cuando este atraviesa un centro de eventos.

Introducción

Las clases .NET que admiten Event Hubs se proporcionan en el paquete NuGet Microsoft.Azure.EventHubs. Puede instalarlas mediante el Explorador de soluciones de Visual Studio o la Consola del Administrador de paquetes de Visual Studio. Para ello, emita el siguiente comando en la ventana Consola del administrador de paquetes :

Install-Package Microsoft.Azure.EventHubs

Creación de un centro de eventos

Puede usar Azure Portal, Azure PowerShell o la CLI de Azure para crear centros de eventos. Para más información, consulte Creación de un espacio de nombres de Event Hubs y un centro de eventos con Azure Portal.

Creación de un cliente de Event Hubs

La clase principal para interactuar con Event Hubs es Microsoft.Azure.EventHubs.EventHubClient. Puede crear una instancia de esta clase con el método CreateFromConnectionString, tal como se muestra en el ejemplo siguiente:

private const string EventHubConnectionString = "Event Hubs namespace connection string";
private const string EventHubName = "event hub name";

var connectionStringBuilder = new EventHubsConnectionStringBuilder(EventHubConnectionString)
{
    EntityPath = EventHubName

};
eventHubClient = EventHubClient.CreateFromConnectionString(connectionStringBuilder.ToString());

Envío eventos a un centro de eventos

Para enviar eventos a un centro de eventos, cree una instancia EventHubClient y envíela de forma asincrónica mediante el método SendAsync. Este método toma un único parámetro de instancia EventData y lo envía de forma asincrónica a un centro de eventos.

Serialización de eventos

La clase EventData tiene dos constructores sobrecargados que aceptan diversos parámetros, bytes o una matriz de bytes, que representan la carga de datos de eventos. Cuando se usa JSON con EventData, puede usar Encoding.UTF8.GetBytes() para recuperar la matriz de bytes de una cadena codificada con JSON. Por ejemplo:

for (var i = 0; i < numMessagesToSend; i++)
{
    var message = $"Message {i}";
    Console.WriteLine($"Sending message: {message}");
    await eventHubClient.SendAsync(new EventData(Encoding.UTF8.GetBytes(message)));
}

Clave de partición

Nota

Si no está familiarizado con las particiones, consulte este artículo.

Al enviar datos de eventos, puede especificar un valor con hash para generar una asignación de partición. La partición se especifica mediante la propiedad PartitionSender.PartitionID. Sin embargo, la decisión de usar particiones implica la elección entre disponibilidad y coherencia. Para más información, consulte Disponibilidad y coherencia.

Operaciones de envío de eventos por lotes

El envío de eventos por lotes puede ayudar a aumentar el rendimiento. Puede usar la API CreateBatch para crear un lote al que más tarde se pueden agregar objetos de datos para una llamada SendAsync.

Un único lote no debe superar el límite de 1 MB de un evento. Además, cada mensaje del lote usa la misma identidad del publicador. Es responsabilidad del remitente asegurarse de que el lote no supera el tamaño máximo del evento. Si lo hace, se genera un error de envío de cliente. Puede utilizar el método auxiliar EventHubClient.CreateBatch para asegurarse de que el lote no supera los 1 MB. Obtiene una salida vacía EventDataBatch de la API CreateBatch y, después, use TryAdd para agregar eventos para construir el lote.

Enviar de forma asincrónica y enviar a escala

Los eventos se envían a un centro de eventos de forma asincrónica. Al enviar de forma asincrónica aumenta la velocidad a la que un cliente es capaz de enviar eventos. SendAsync devuelve un objeto Task. Puede usar la clase RetryPolicy en el cliente para controlar opciones de reintento del cliente.

Consumidores de eventos

La clase EventProcessorHost procesa los datos de Event Hubs. Debe usar esta implementación para generar los lectores de eventos en la plataforma .NET. EventProcessorHost proporciona un entorno de tiempo de ejecución seguro, seguro para subprocesos y de varios procesos para las implementaciones de procesadores de eventos que también ofrecen administración de concesión de puntos de comprobación y particiones.

Para usar la clase EventProcessorHost, puede implementar IEventProcessor. Esta interfaz contiene cuatro métodos:

Para iniciar el procesamiento de eventos, cree una instancia de EventProcessorHost, proporcionando los parámetros adecuados para el centro de eventos. Por ejemplo:

var eventProcessorHost = new EventProcessorHost(
        EventHubName,
        PartitionReceiver.DefaultConsumerGroupName,
        EventHubConnectionString,
        StorageConnectionString,
        StorageContainerName);

Después, llame a RegisterEventProcessorAsync para registrar su implementación de IEventProcessor en el entorno de tiempo de ejecución.

await eventProcessorHost.RegisterEventProcessorAsync<SimpleEventProcessor>();

En este momento, el host intenta adquirir una concesión en cada partición del centro de eventos mediante un algoritmo "expansivo". Estas concesiones duran un período de tiempo determinado y después deben renovarse. A medida que nuevos nodos, instancias de trabajo en este caso, pasan a estar en línea, colocan reservas de concesión y, con el tiempo, la carga cambia entre los nodos a medida que cada una trata de adquirir más concesiones.

Host del procesador de eventos

Con el tiempo, se establece un equilibrio. Esta capacidad dinámica permite la aplicación del escalado automático basado en CPU a los consumidores para escalar vertical y horizontalmente. Debido a que Event Hubs no tiene un concepto directo de recuentos de mensajes, el uso medio de la CPU suele ser el mejor mecanismo para medir el back-end o la escala del consumidor. Si los publicadores empiezan a publicar más eventos de los que los consumidores pueden procesar, el aumento de la CPU en los consumidores puede usarse para producir una escala automática en el recuento de instancias de trabajador.

La clase EventProcessorHost también implementa un mecanismo de puntos de comprobación basado en el almacenamiento de Azure. Este mecanismo almacena el desplazamiento en función de la partición, para que cada consumidor pueda determinar cuál fue el último punto de comprobación del cliente anterior. A medida que las particiones pasan de un nodo a otro a través de concesiones, este es el mecanismo de sincronización que facilita el desplazamiento de cargas.

Revocación de publicador

Además de las características avanzadas del entorno en tiempo de ejecución del host del procesador de eventos, el servicio Event Hubs permite la revocación del editor con el fin de impedir a editores específicos el envío de eventos a un centro de eventos. Estas características son útiles si se ha visto comprometido el token de un publicador o si una actualización de software está provocando que se comporten incorrectamente. En estas situaciones, es posible bloquear que la identidad del editor, que forma parte de su token de SAS, publique eventos.

Nota

Actualmente, solo la API REST es compatible con esta característica (revocación del editor).

Pasos siguientes

Para obtener más información acerca de los escenarios de Event Hubs, visite estos vínculos: