Compartir a través de

Inicio rápido: Validación del uso de un esquema de Avro al transmitir eventos mediante SDK de .NET de Event Hubs (AMQP)

En este inicio rápido, aprenderá a enviar y recibir eventos desde un centro de eventos con validación de esquema mediante la biblioteca .NET Azure.Messaging.EventHubs .

Azure Schema Registry es una característica de Event Hubs. El registro proporciona un repositorio central para esquemas para aplicaciones basadas en eventos y centradas en mensajería. Ofrece la flexibilidad para que las aplicaciones de productor y consumidor intercambien datos sin tener que administrar y compartir el esquema. También proporciona un marco de gobierno sencillo para los esquemas reutilizables y define la relación entre los esquemas a través de una construcción de agrupación (grupos de esquemas). Para más información, consulte Registro de esquema de Azure en Event Hubs.

Prerrequisitos

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

Para completar este inicio rápido, necesita los siguientes requisitos previos:

  • Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

  • Microsoft Visual Studio 2022.

    La biblioteca cliente de Azure Event Hubs usa 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 compilar con el SDK de .NET Core 3.0 o superior y configurar la versión del lenguaje a latest.

    Si usa Visual Studio, las versiones anteriores a Visual Studio 2019 no son compatibles con las herramientas necesarias para compilar proyectos de C# 8.0. Para descargar Visual Studio 2019 o Visual Studio 2022, incluida la edición gratuita Community, consulte Visual Studio.

Creación de un centro de eventos

Para crear un espacio de nombres de Event Hubs y un centro de eventos, siga las instrucciones de Creación de un espacio de nombres de Event Hubs y un centro de eventos.

Para obtener una cadena de conexión al espacio de nombres de Event Hubs, siga las instrucciones de Obtención de la cadena de conexión.

Anote la siguiente configuración para usarla en el inicio rápido actual:

  • Cadena de conexión del espacio de nombres de Event Hubs
  • Nombre del centro de eventos

Creación de un esquema

Para crear un grupo de esquemas y un esquema, siga las instrucciones de Creación de esquemas mediante el Registro de esquemas.

  1. Cree un grupo de esquemas denominado contoso-sg mediante el portal de Schema Registry. Use Avro como tipo de serialización y None para el modo de compatibilidad.

  2. En ese grupo de esquemas, cree un nuevo esquema de Avro con el nombre del esquema: Microsoft.Azure.Data.SchemaRegistry.example.Order. Use el siguiente contenido de esquema.

    {
  "namespace": "Microsoft.Azure.Data.SchemaRegistry.example",
  "type": "record",
  "name": "Order",
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "amount",
      "type": "double"
    },
    {
      "name": "description",
      "type": "string"
    }
  ]
}

Agregar usuario al rol Lector de Schema Registry

Agregue la cuenta de usuario al rol Lector del registro de esquema en el nivel de espacio de nombres. También puede usar el rol Colaborador del registro de esquema, pero no es necesario para este inicio rápido.

  1. En la página Espacio de nombres de Event Hubs , en el menú izquierdo, seleccione Control de acceso (IAM) .
  2. En la página Control de acceso (IAM), seleccione + Agregar asignación> deroles.
  3. En la página Roles , seleccione Lector del Registro de esquemas y, a continuación, seleccione Siguiente.
  4. Use el vínculo + Seleccionar miembros para agregar la cuenta de usuario al rol y, a continuación, seleccione Siguiente.
  5. En la página Revisar + asignar, seleccione Revisar + asignar.

Generar eventos en Event Hubs con validación de esquema

Creación de una aplicación de consola para el productor de eventos

  1. Inicie Visual Studio.

  2. Seleccione Crear un nuevo proyecto.

  3. 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, 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.

      Captura de pantalla que muestra el cuadro de diálogo Nuevo proyecto de Visual Studio.

  4. Escriba OrderProducer como nombre del proyecto, SRQuickStart como nombre de la solución y, a continuación, seleccione Aceptar para crear el proyecto.

Agregar el paquete NuGet de Event Hubs

  1. Seleccione Herramientas>NuGet Package Manager> de paquetes de NuGet).

  2. Ejecute los siguientes comandos para instalar Azure.Messaging.EventHubs y otros paquetes NuGet. Presione ENTRAR para ejecutar el último comando.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Identity
Install-Package Microsoft.Azure.Data.SchemaRegistry.ApacheAvro
Install-Package Azure.ResourceManager.Compute

  3. Autentique las aplicaciones de productor para conectarse a Azure mediante Visual Studio. Para más información, consulte Biblioteca cliente de Azure Identity para .NET.

  4. Inicie sesión en Azure con la cuenta de usuario que sea miembro del rol de Schema Registry Reader en el nivel de espacio de nombres. Para más información sobre los roles del Registro de esquema, consulte Control de acceso basado en roles de Azure.

Generación de código mediante el esquema avro

  1. Use el mismo contenido que usó para crear el esquema para crear un archivo denominado Order.avsc. Guarde el archivo en el proyecto o la carpeta de la solución.
  2. Use este archivo de esquema para generar código para .NET. Puede usar cualquier herramienta de generación de código externo, como avrogen para la generación de código. Por ejemplo, ejecute avrogen -s .\Order.avsc . para generar código.
  3. Después de generar código, verá el archivo denominado Order.cs en la \Microsoft\Azure\Data\SchemaRegistry\example carpeta . Para el esquema Avro aquí, genera los tipos de C# en el espacio de nombres Microsoft.Azure.Data.SchemaRegistry.example.
  4. Agregue el Order.cs archivo al OrderProducer proyecto.

Escribir código para serializar y enviar eventos al centro de eventos

  1. Agregue el siguiente código al archivo Program.cs. Consulte los comentarios de código para obtener más información. Los pasos generales del código son:

    1. Cree un cliente de productor que pueda usar para enviar eventos a un centro de eventos.
    2. Cree un cliente del Registro de esquema que pueda usar para serializar y validar datos en un Order objeto .
    3. Cree un nuevo objeto Order usando el tipo generado Order.
    4. Utilice el cliente del registro de esquemas para serializar el objeto Order en EventData.
    5. Cree un lote de eventos.
    6. Agregue los datos del evento al lote de eventos.
    7. Use el cliente productor para enviar el lote de eventos al centro de eventos.
    using Azure.Data.SchemaRegistry;
using Azure.Identity;
using Microsoft.Azure.Data.SchemaRegistry.ApacheAvro;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;

using Microsoft.Azure.Data.SchemaRegistry.example;

// connection string to the Event Hubs namespace
const string connectionString = "EVENTHUBSNAMESPACECONNECTIONSTRING";

// name of the event hub
const string eventHubName = "EVENTHUBNAME";

// Schema Registry endpoint 
const string schemaRegistryEndpoint = "EVENTHUBSNAMESPACENAME.servicebus.windows.net";

// name of the consumer group   
const string schemaGroup = "SCHEMAGROUPNAME";

// 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.
EventHubProducerClient producerClient;

// Create a producer client that you can use to send events to an event hub
producerClient = new EventHubProducerClient(connectionString, eventHubName);

// Create a schema registry client that you can use to serialize and validate data.  
var schemaRegistryClient = new SchemaRegistryClient(schemaRegistryEndpoint, new DefaultAzureCredential());

// Create an Avro object serializer using the Schema Registry client object. 
var serializer = new SchemaRegistryAvroSerializer(schemaRegistryClient, schemaGroup, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

// Create a new order object using the generated type/class 'Order'. 
var sampleOrder = new Order { id = "1234", amount = 45.29, description = "First sample order." };
EventData eventData = (EventData)await serializer.SerializeAsync(sampleOrder, messageType: typeof(EventData));

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

// Add the event data to the event batch. 
eventBatch.TryAdd(eventData);

// Send the batch of events to the event hub. 
await producerClient.SendAsync(eventBatch);
Console.WriteLine("A batch of 1 order has been published.");

  2. Reemplace los siguientes valores de marcador de posición por los valores reales.

    • EVENTHUBSNAMESPACECONNECTIONSTRING: cadena de conexión del espacio de nombres de Event Hubs
    • EVENTHUBNAME : nombre del centro de eventos
    • EVENTHUBSNAMESPACENAME : nombre del espacio de nombres de Event Hubs
    • SCHEMAGROUPNAME : nombre del grupo de esquemas
    // connection string to the Event Hubs namespace
const string connectionString = "EVENTHUBSNAMESPACECONNECTIONSTRING";

// name of the event hub
const string eventHubName = "EVENTHUBNAME";

// Schema Registry endpoint 
const string schemaRegistryEndpoint = "EVENTHUBSNAMESPACENAME.servicebus.windows.net";

// name of the consumer group   
const string schemaGroup = "SCHEMAGROUPNAME";

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

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

    A batch of 1 order has been published.

  5. En Azure Portal, puede comprobar que el centro de eventos recibió los eventos. Cambie a la vista Mensajes en la sección Métricas . Actualice la página para actualizar el gráfico. Puede tardar unos segundos en mostrar que recibió los mensajes.

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

Consumo de eventos de Event Hubs con validación de esquema

En esta sección se muestra cómo escribir una aplicación de consola de .NET Core que recibe eventos de un centro de eventos y usar el registro de esquemas para deserializar los datos de eventos.

Requisitos previos adicionales

  • Cree la cuenta de almacenamiento para usar el procesador de eventos.

Creación de una aplicación de consumidor

  1. En la ventana Explorador de soluciones, haga clic con el botón derecho en la solución SRQuickStart , seleccione Agregar y seleccione Nuevo proyecto.
  2. Seleccione Aplicación de consola y elija Siguiente.
  3. Escriba OrderConsumer como Nombre del proyecto y seleccione Crear.
  4. En la ventana Explorador de soluciones, haga clic con el botón derecho en OrderConsumer y seleccione Establecer como proyecto de inicio.

Agregar el paquete NuGet de Event Hubs

  1. Seleccione Herramientas>NuGet Package Manager> de paquetes de NuGet).

  2. En la ventana Consola del Administrador de paquetes, confirme que OrderConsumer está seleccionado para el proyecto Predeterminado. Si no es así, use la lista desplegable para seleccionar OrderConsumer.

  3. Ejecute el siguiente comando para instalar los paquetes NuGet necesarios. Presione ENTRAR para ejecutar el último comando.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Messaging.EventHubs.Processor
Install-Package Azure.Identity
Install-Package Microsoft.Azure.Data.SchemaRegistry.ApacheAvro
Install-Package Azure.ResourceManager.Compute

  4. Autentique las aplicaciones de productor para conectarse a Azure mediante Visual Studio, como se muestra en la biblioteca cliente de Identidad de Azure para .NET.

  5. Inicie sesión en Azure con la cuenta de usuario que sea miembro del rol Schema Registry Reader a nivel de espacio de nombres. Para más información sobre los roles del Registro de esquema, consulte Control de acceso basado en roles de Azure.

  6. Agregue el archivo Order.cs que generó como parte de la creación de la aplicación del productor al proyecto OrderConsumer.

  7. Haga clic con el botón derecho en OrderConsumer proyecto y seleccione Establecer como proyecto de inicio.

Escribir código para recibir eventos y deserializarlos mediante el Registro de esquemas

  1. Agregue el siguiente código al archivo Program.cs. Consulte los comentarios de código para obtener más información. Los pasos generales del código son:

    1. Cree un cliente de consumidor que pueda usar para enviar eventos a un centro de eventos.
    2. Cree un cliente de contenedor de blobs para el contenedor de blobs en el almacenamiento de blobs de Azure.
    3. Cree un cliente de procesador de eventos y registre controladores de eventos y errores.
    4. En el controlador de eventos, cree un cliente del Registro de esquema que puede usar para deserializar los datos de eventos en un objeto Order.
    5. Deserialice los datos del evento en un Order objeto mediante el serializador.
    6. Imprima la información sobre el pedido recibido.
    using Azure.Data.SchemaRegistry;
using Azure.Identity;
using Microsoft.Azure.Data.SchemaRegistry.ApacheAvro;
using Azure.Storage.Blobs;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Consumer;
using Azure.Messaging.EventHubs.Processor;

using Microsoft.Azure.Data.SchemaRegistry.example;


// connection string to the Event Hubs namespace
const string connectionString = "EVENTHUBSNAMESPACECONNECTIONSTRING";

// name of the event hub
const string eventHubName = "EVENTHUBNAME";

// Schema Registry endpoint 
const string schemaRegistryEndpoint = "EVENTHUBSNAMESPACENAME.servicebus.windows.net";

// name of the consumer group   
const string schemaGroup = "SCHEMAGROUPNAME";

// connection string for the Azure Storage account
const string blobStorageConnectionString = "AZURESTORAGECONNECTIONSTRING";

// name of the blob container that will be used as a checkpoint store
const string blobContainerName = "BLOBCONTAINERNAME";

// Create a blob container client that the event processor will use 
BlobContainerClient storageClient = new BlobContainerClient(blobStorageConnectionString, blobContainerName);

// Create an event processor client to process events in the event hub
EventProcessorClient processor = new EventProcessorClient(storageClient, EventHubConsumerClient.DefaultConsumerGroupName, connectionString, eventHubName);

// 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();

static async Task ProcessEventHandler(ProcessEventArgs eventArgs)
{
    // Create a schema registry client that you can use to serialize and validate data.  
    var schemaRegistryClient = new SchemaRegistryClient(schemaRegistryEndpoint, new DefaultAzureCredential());

    // Create an Avro object serializer using the Schema Registry client object. 
    var serializer = new SchemaRegistryAvroSerializer(schemaRegistryClient, schemaGroup, new SchemaRegistryAvroSerializerOptions { AutoRegisterSchemas = true });

    // Deserialized data in the received event using the schema 
    Order sampleOrder = (Order)await serializer.DeserializeAsync(eventArgs.Data, typeof(Order));

    // Print the received event
    Console.WriteLine($"Received order with ID: {sampleOrder.id}, amount: {sampleOrder.amount}, description: {sampleOrder.description}");

       await eventArgs.UpdateCheckpointAsync(eventArgs.CancellationToken);
    }

    static 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);
    return Task.CompletedTask;
}

  2. Reemplace los siguientes valores de marcador de posición por los valores reales.

    • EVENTHUBSNAMESPACE-CONNECTIONSTRING: cadena de conexión del espacio de nombres de Event Hubs
    • EVENTHUBNAME : nombre del centro de eventos
    • EVENTHUBSNAMESPACENAME : nombre del espacio de nombres de Event Hubs
    • SCHEMAGROUPNAME : nombre del grupo de esquemas
    • AZURESTORAGECONNECTIONSTRING : cadena de conexión para la cuenta de Almacenamiento de Azure
    • BLOBCONTAINERNAME: nombre del contenedor de blobs
    // connection string to the Event Hubs namespace
const string connectionString = "EVENTHUBSNAMESPACE-CONNECTIONSTRING";

// name of the event hub
const string eventHubName = "EVENTHUBNAME";

// Schema Registry endpoint 
const string schemaRegistryEndpoint = "EVENTHUBSNAMESPACENAME.servicebus.windows.net";

// name of the consumer group   
const string schemaGroup = "SCHEMAGROUPNAME";

// Azure storage connection string
const string blobStorageConnectionString = "AZURESTORAGECONNECTIONSTRING";

// Azure blob container name
const string blobContainerName = "BLOBCONTAINERNAME";

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

  4. Ejecute la aplicación del destinatario.

  5. Debería ver un mensaje que indica que el centro de eventos recibió los eventos.

    Received order with ID: 1234, amount: 45.29, description: First sample order.

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

Muestras

Consulte La biblioteca cliente de Apache Avro del Registro de esquemas de Azure para .NET.

Limpieza de recursos

Elimine el espacio de nombres de Event Hubs o elimine el grupo de recursos que contiene el espacio de nombres.

Paso siguiente

Biblioteca cliente de Azure Schema Registry para .NET