Inicio rápido: envío y recepción de eventos en Azure Event Hubs mediante .NET

  • Artículo

En este inicio rápido, obtendrá información sobre cómo enviar eventos a un centro de eventos y luego recibirlos mediante la biblioteca de .NET Azure.Messaging.EventHubs.

Nota

Las guías de inicio rápido le ayudarán a aumentar rápidamente el servicio. Si ya está familiarizado con el servicio, es posible que desee ver ejemplos de .NET para Event Hubs en nuestro repositorio de SDK de .NET en GitHub: ejemplos de Event Hubs en GitHub, ejemplos de procesador de eventos en GitHub.

Requisitos previos

Si es la primera vez que usa Azure Event Hubs, consulte la información general de Event Hubs antes de comenzar con este inicio rápido.

Para completar este tutorial de inicio rápido, debe cumplir los siguientes requisitos previos:

  • Una suscripción a Microsoft Azure. Para usar los servicios de Azure, entre los que se incluye Azure Event Hubs, se necesita una suscripción. Si no se dispone de una cuenta de Azure, es posible registrarse para obtener una evaluación gratuita, o bien usar las ventajas que disfrutan los suscriptores MSDN al crear una cuenta.
  • Microsoft Visual Studio 2022. La biblioteca cliente de Azure Event Hubs utiliza las nuevas características que se introdujeron en C# 8.0. Aún puede seguir usando la biblioteca con versiones anteriores de lenguaje C#, pero la nueva sintaxis no está disponible. Para usar la sintaxis completa, se recomienda realizar la compilación con el SDK de .NET Core 3.0 o superior y la versión de lenguaje establecida en latest. Si usa Visual Studio, las versiones anteriores a Visual Studio 2022 no son compatibles con las herramientas necesarias para compilar proyectos de C# 8.0. Visual Studio 2022, incluida la edición gratuita Community, se puede descargar aquí.
  • Creación de un espacio de nombres de Event Hubs y un centro de eventos. El primer paso es usar Azure Portal para crear un espacio de nombres de Event Hubs y un centro de eventos en el espacio de nombres. Después, obtenga las credenciales de administración que la aplicación necesita para comunicarse con el centro de eventos. Para crear un espacio de nombres y un centro de eventos, consulte Inicio rápido: creación de un centro de eventos mediante Azure Portal.

Autenticación de la aplicación en Azure

En este inicio rápido se muestran dos maneras de conectarse a Azure Event Hubs:

  • Sin contraseña (autenticación de Microsoft Entra)
  • Cadena de conexión

La primera opción muestra cómo usar la entidad de seguridad de Azure Active Directory y el control de acceso basado en roles (RBAC) para conectarse a un espacio de nombres de Event Hubs. No es necesario preocuparse por tener cadenas de conexión codificadas de forma rígida en el código, en un archivo de configuración o en un almacenamiento seguro, como Azure Key Vault.

La segunda opción muestra cómo usar una cadena de conexión para conectarse a un espacio de nombres de Event Hubs. Si no está familiarizado con Azure, puede que le resulte más fácil la opción de la cadena de conexión. Se recomienda usar la opción sin contraseña en aplicaciones reales y entornos de producción. Para más información, consulte Autenticación y autorización. También puede obtener más información sobre la autenticación sin contraseña en la página de información general.

Asignación de roles al usuario de Microsoft Entra

Al desarrollar localmente, asegúrese de que la cuenta de usuario que se conecta a Azure Event Hubs tenga los permisos correctos. Necesitará el rol propietario de datos Azure Event Hubs para enviar y recibir mensajes. Para asignarse este rol, necesitará el rol Administrador de accesos de usuarios, u otro que incluya la acción Microsoft.Authorization/roleAssignments/write. Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Puede obtener más información sobre los ámbitos disponibles para las asignaciones de roles en la página de información general del ámbito.

En el ejemplo siguiente se asigna el rol Azure Event Hubs Data Owner a la cuenta de usuario, que proporciona un acceso completo a los recursos de Azure Event Hubs. En un escenario real, siga el Principio de privilegios mínimos para conceder a los usuarios solo los permisos mínimos necesarios para un entorno de producción más seguro.

Roles integrados de Azure para Azure Event Hubs

En el caso de Azure Event Hubs, la administración de los espacios de nombres y de todos los recursos relacionados mediante Azure Portal y la API de administración de recursos de Azure, ya se ha protegido mediante el modelo de Azure RBAC. Azure proporciona los siguientes roles integrados de Azure para autorizar el acceso a un espacio de nombres de Event Hubs:

Si desea crear un rol personalizado, consulte Derechos necesarios para las operaciones de Event Hubs.

Importante

En la mayoría de los casos, la asignación de roles tardará un minuto o dos en propagarse en Azure. En ocasiones excepcionales, puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. En Azure Portal, localice el espacio de nombres de Event Hubs mediante la barra de búsqueda principal o el panel de navegación de la izquierda.

  2. En la página de información general, seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.

    Una captura de pantalla que muestra cómo asignar un rol.

  5. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Azure Event Hubs Data Owner y seleccione el resultado coincidente. Después, haga clic en Siguiente.

  6. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  7. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  8. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

Inicio de Visual Studio e inicio de sesión en Azure

Puede autorizar el acceso al espacio de nombres de Service Bus siguiendo estos pasos:

  1. Inicie Visual Studio. Si aparece la ventana Introducción, seleccione el vínculo Continuar sin código en el panel derecho.

  2. Seleccione el botón Iniciar sesión en la parte superior derecha de Visual Studio.

    Captura de pantalla que muestra el botón para iniciar sesión en Azure mediante Visual Studio.

  3. Inicie sesión con la cuenta de Microsoft Entra a la que asignó un rol anteriormente.

    Captura de pantalla que muestra la selección de la cuenta.

Envío de eventos al centro de eventos

En esta sección se muestra cómo crear una aplicación de consola de .NET Core para enviar eventos al centro de eventos que ha creado.

Creación de una aplicación de consola

  1. Si ya tiene Visual Studio 2022 abierto, seleccione Archivo en el menú, seleccione Nuevo y, después, Proyecto. De lo contrario, inicie Visual Studio 2022 y seleccione Crear un nuevo proyecto si ve una ventana emergente.

  2. En el cuadro de diálogo Crear un nuevo proyecto, siga estos pasos: Si no ve este cuadro de diálogo, seleccione Archivo en el menú, seleccione Nuevo y, después, seleccione Proyecto.

    1. Seleccione C# como lenguaje de programación.

    2. Seleccione Consola como tipo de aplicación.

    3. Seleccione Aplicación de consola en la lista de resultados.

    4. Después, seleccione Siguiente.

      Imagen que muestra el cuadro de diálogo Nuevo proyecto

  3. Escriba EventHubsSender como nombre del proyecto, EventHubsQuickStart como nombre de la solución y, después, seleccione Siguiente.

    Imagen que muestra la página donde se escriben los nombres de la solución y del proyecto

  4. En la página Información adicional, seleccione Crear.

Agregar los paquetes de NuGet al proyecto

  1. Seleccione Herramientas>Administrador de paquetes NuGet>Consola del Administrador de paquetes en el menú.

  2. Ejecute los siguientes comandos para instalar los paquetes de NuGet Azure.Messaging.EventHubs y Azure.Identity. Presione ENTRAR para ejecutar el segundo comando.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Identity

Escritura de código para enviar eventos al centro de eventos

  1. Reemplace el código existente en el archivo Program.cs por el código de ejemplo siguiente. A continuación, reemplace los valores de marcador de posición <EVENT_HUB_NAMESPACE> y <HUB_NAME> en los parámetros EventHubProducerClient por los nombres del espacio de nombres de Event Hubs y del centro de eventos. Por ejemplo, "spehubns0309.servicebus.windows.net" y "spehub".

    Estos son los pasos importantes del código:

    1. Crea un objeto EventHubProducerClient mediante el espacio de nombres y el nombre del centro de eventos.
    2. Invoca el método CreateBatchAsync en el objeto EventHubProducerClient para crear un objeto EventDataBatch.
    3. Agregue eventos al lote mediante el método EventDataBatch.TryAdd.
    4. Envía el lote de mensajes al centro de eventos mediante el método EventHubProducerClient.SendAsync.
    using Azure.Identity;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;
using System.Text;

// number of events to be sent to the event hub
int numOfEvents = 3;

// The Event Hubs client types are safe to cache and use as a singleton for the lifetime
// of the application, which is best practice when events are being published or read regularly.
// TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values
EventHubProducerClient producerClient = new EventHubProducerClient(
    "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
    "<HUB_NAME>",
    new DefaultAzureCredential());

// Create a batch of events 
using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();

for (int i = 1; i <= numOfEvents; i++)
{
    if (!eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
    {
        // if it is too large for the batch
        throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
    }
}

try
{
    // Use the producer client to send the batch of events to the event hub
    await producerClient.SendAsync(eventBatch);
    Console.WriteLine($"A batch of {numOfEvents} events has been published.");
    Console.ReadLine();
}
finally
{
    await producerClient.DisposeAsync();
}

  1. Compile el proyecto y asegúrese de que no hay errores.

  2. Ejecute el programa y espere el mensaje de confirmación.

    A batch of 3 events has been published.

    Importante

    Si usa la autenticación sin contraseña (control de acceso basado en roles de Azure Active Directory), seleccione Herramientasy, a continuación, seleccione Opciones. En la ventana Opciones, expanda Autenticación de servicio de Azure y seleccione Selección de cuenta. Confirme que usa la cuenta que se agregó al rol Propietario de datos de Azure Event Hubs en el espacio de nombres de Event Hubs.

  3. En la página Espacio de nombres de Event Hubs de Azure Portal, verá tres mensajes entrantes en el gráfico Mensajes. Actualice la página para actualizar el gráfico, si es necesario. Pueden pasar unos segundos hasta que aparezca que los mensajes se han recibido.

    Imagen de la página de Azure Portal para comprobar que el centro de eventos recibió los eventos.

    Nota

    Para ver el código fuente completo con comentarios muy útiles, consulte este archivo en GitHub.

Recepción de eventos desde el centro de eventos

En esta sección se muestra cómo escribir una aplicación de consola de .NET Core que reciba eventos de un centro de eventos mediante un procesador de eventos. El procesador de eventos simplifica la recepción de eventos desde el centro de eventos.

Creación de una cuenta de Azure Storage y un contenedor de blobs

En este inicio rápido, se usa Azure Storage como almacén de puntos de control. Siga estos pasos para crear una cuenta de Azure Storage.

  1. Creación de una cuenta de Azure Storage
  2. Creación de un contenedor de blobs
  3. Autentíquese en el contenedor de blobs mediante la autenticación de Microsoft Entra ID (sin contraseña) o una cadena de conexión al espacio de nombres.

Siga estas recomendaciones al usar Azure Blob Storage como almacén de puntos de control:

  • Use un contenedor independiente para cada grupo de consumidores. Puede usar la misma cuenta de almacenamiento, pero usar un contenedor por cada grupo.
  • No use el contenedor ni la cuenta de almacenamiento para otras actividades.
  • La cuenta de almacenamiento debe estar en la misma región en la que se encuentra la aplicación implementada. Si la aplicación es local, intente elegir la región más cercana posible.

En la página Cuenta de almacenamiento de Azure Portal, en la sección Blob service, asegúrese de que la siguiente configuración está deshabilitada.

  • Espacio de nombres jerárquico
  • Eliminación temporal de blobs
  • Control de versiones

Al desarrollar localmente, asegúrese de que la cuenta de usuario que accede a los datos de blob tenga los permisos correctos. Necesitará el Colaborador de datos de blobs de almacenamiento para leer y escribir datos de blob. Para asignarse este rol a sí mismo, necesitará que se le asigne el rol Administrador de acceso de usuario u otro rol que incluya la acción Microsoft.Authorization/roleAssignments/write. Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Puede obtener más información sobre los ámbitos disponibles para las asignaciones de roles en la página de información general del ámbito.

En este escenario, asignará permisos a la cuenta de usuario, cuyo ámbito es la cuenta de almacenamiento, a fin de seguir el principio de privilegios mínimos. Esta práctica solo proporciona a los usuarios los permisos mínimos necesarios y crea entornos de producción más seguros.

En el ejemplo siguiente se asignará el rol Colaborador de datos de blobs de almacenamiento a la cuenta de usuario, que proporciona acceso de lectura y escritura a los datos de blobs de la cuenta de almacenamiento.

Importante

En la mayoría de los casos, la asignación de roles tardará un minuto o dos en propagarse en Azure, pero en casos excepcionales puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. En Azure Portal, busque la cuenta de almacenamiento mediante la barra de búsqueda principal o el panel de navegación de la izquierda.

  2. En la página de información general de la cuenta de almacenamiento, seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.

    Una captura de pantalla que muestra cómo asignar un rol de cuenta de almacenamiento.

  5. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Colaborador de datos de blobs de almacenamiento y seleccione el resultado coincidente y, a continuación, elija Siguiente.

  6. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  7. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  8. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

Creación de un proyecto para el destinatario

  1. En la ventana del Explorador de soluciones, haga clic con el botón derecho en la solución EventHubQuickStart, haga clic en Agregar y seleccione Nuevo proyecto.
  2. Seleccione Aplicación de consola y elija Siguiente.
  3. Escriba EventHubsReceiver en Nombre de proyecto y seleccione Crear.
  4. En la ventana del Explorador de soluciones, haga clic con el botón derecho en EventHubsReceiver y seleccione Set as a Startup Project (Establecer como proyecto de inicio).

Agregar los paquetes de NuGet al proyecto

  1. Seleccione Herramientas>Administrador de paquetes NuGet>Consola del Administrador de paquetes en el menú.

  2. En la ventana de la Consola del Administrador de paquetes, confirme que EventHubsReceiver está seleccionado como Proyecto predeterminado. Si no es así, use la lista desplegable para seleccionarlo.

  3. Ejecute el siguiente comando para instalar los paquetes de NuGet Azure.Messaging.EventHubs y Azure.Identity. Presione ENTRAR para ejecutar el último comando.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Messaging.EventHubs.Processor
Install-Package Azure.Identity

Actualización del código

Reemplace el contenido de Program.cs por el código siguiente:

  1. Reemplace el código existente en el archivo Program.cs por el código de ejemplo siguiente. Después, reemplace los valores de marcador de posición <STORAGE_ACCOUNT_NAME> y <BLOB_CONTAINER_NAME> para la URI BlobContainerClient. Reemplace también los valores de marcador de posición <EVENT_HUB_NAMESPACE> y <HUB_NAME> por EventProcessorClient.

    Estos son los pasos importantes del código:

    1. Crea un objeto EventProcessorClient mediante el espacio de nombres de Event Hubs y el nombre del centro de eventos. Debe compilar el objeto BlobContainerClient para el contenedor en el almacenamiento de Azure que creó anteriormente.
    2. Especifica controladores para los eventos ProcessEventAsync y ProcessErrorAsync del objeto EventProcessorClient.
    3. Inicia el procesamiento de eventos invocando StartProcessingAsync en el objeto EventProcessorClient.
    4. Detiene el procesamiento de eventos a los 30 segundos y para ello invoca StopProcessingAsync en el objeto EventProcessorClient.
    using Azure.Identity;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Consumer;
using Azure.Messaging.EventHubs.Processor;
using Azure.Storage.Blobs;
using System.Text;

// Create a blob container client that the event processor will use
// TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTATINAER_NAME> with actual names
BlobContainerClient storageClient = new BlobContainerClient(
    new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/<BLOB_CONTAINER_NAME>"),
    new DefaultAzureCredential());

// Create an event processor client to process events in the event hub
// TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values
var processor = new EventProcessorClient(
    storageClient,
    EventHubConsumerClient.DefaultConsumerGroupName,
    "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
    "<HUB_NAME>",
    new DefaultAzureCredential());

// Register handlers for processing events and handling errors
processor.ProcessEventAsync += ProcessEventHandler;
processor.ProcessErrorAsync += ProcessErrorHandler;

// Start the processing
await processor.StartProcessingAsync();

// Wait for 30 seconds for the events to be processed
await Task.Delay(TimeSpan.FromSeconds(30));

// Stop the processing
await processor.StopProcessingAsync();

Task ProcessEventHandler(ProcessEventArgs eventArgs)
{
    // Write the body of the event to the console window
    Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
    Console.ReadLine();
    return Task.CompletedTask;
}

Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
{
    // Write details about the error to the console window
    Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
    Console.WriteLine(eventArgs.Exception.Message);
    Console.ReadLine();
    return Task.CompletedTask;
}

  1. Compile el proyecto y asegúrese de que no hay errores.

    Nota

    Para ver el código fuente completo con comentarios muy útiles, consulte este archivo en GitHub.

  2. Ejecute la aplicación del destinatario.

  3. Debería ver un mensaje que indica que se han recibido los eventos. Presione ENTRAR después de ver un mensaje de evento recibido.

    Received event: Event 1
Received event: Event 2
Received event: Event 3

    Estos eventos son los tres que envió al centro de eventos anteriormente mediante la ejecución del programa del emisor.

  4. En Azure Portal, puede comprobar que hay tres mensajes salientes, que Event Hubs envió a la aplicación receptora. Actualice la página para actualizar el gráfico. Pueden pasar unos segundos hasta que aparezca que los mensajes se han recibido.

    Imagen de la página de Azure Portal para comprobar que el centro de eventos envió los eventos a la aplicación destinataria.

Validación de esquemas para aplicaciones basadas en el SDK de Event Hubs

Puede usar Azure Schema Registry para realizar la validación del esquema al transmitir datos con las aplicaciones basadas en el SDK de Event Hubs. El registro de esquemas de Azure de Event Hubs proporciona un repositorio centralizado para administrar esquemas y puede conectar sin problemas las aplicaciones nuevas o existentes con el registro de esquemas.

Para más información, consulte Validación de esquemas con el SDK de Event Hubs.

Ejemplos y referencia

En este inicio rápido se proporcionan instrucciones paso a paso para implementar un escenario de envío de un lote de eventos a un centro de eventos y la posterior recepción de estos. Para más ejemplos, seleccione los vínculos siguientes.

Para obtener una referencia completa de la biblioteca de .NET, consulte nuestra documentación de SDK.

Limpieza de recursos

Elimine el grupo de recursos que tiene el espacio de nombres de Event Hubs o elimine solo el espacio de nombres si desea mantener el grupo de recursos.

Contenido relacionado

Consulte el siguiente tutorial:

Tutorial: Visualización de anomalías de datos de eventos en tiempo real enviados a Azure Event Hubs