Condividi tramite

Convalidare l'uso di uno schema Avro durante lo streaming di eventi usando gli SDK .NET di Hub eventi (AMQP)

  • Articolo

In questa guida di avvio rapido si apprenderà come inviare e ricevere eventi da un hub eventi con la convalida dello schema utilizzando la libreria .NET Azure.Messaging.EventHubs.

Nota

Il Registro schemi di Azure è una funzionalità di Hub eventi, che fornisce un repository centrale per gli schemi per le applicazioni basate su eventi e incentrate sulla messaggistica. Offre la flessibilità necessaria per consentire alle applicazioni producer e consumer di scambiare dati senza dover gestire e condividere lo schema. Fornisce inoltre un framework di governance semplice per gli schemi riutilizzabili e definisce la relazione tra gli schemi tramite un costrutto di raggruppamento (gruppi di schemi). Per altre informazioni, vedere Registro schemi di Azure in Hub eventi.

Prerequisiti

Se non si ha familiarità con Hub eventi di Azure, vedere Panoramica di Hub eventi prima di procedere con questa guida di avvio rapido.

Per completare questa guida introduttiva è necessario soddisfare i prerequisiti seguenti:

  • Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
  • Microsoft Visual Studio 2022. La libreria client di Hub eventi di Azure usa le nuove funzionalità introdotte in C# 8.0. È comunque possibile usare la libreria con le versioni precedenti del linguaggio C#, ma la nuova sintassi non sarà disponibile. Per utilizzare la sintassi completa, è consigliabile eseguire la compilazione con .NET Core SDK 3.0 o versione successiva e la versione della lingua impostata su latest. Se si usa Visual Studio, le versioni precedenti a Visual Studio 2019 non sono compatibili con gli strumenti necessari per la compilazione di progetti in C# 8.0. Visual Studio 2019, inclusa l'edizione Community gratuita, può essere scaricato qui.

Creare un hub eventi

Seguire le istruzioni della guida di avvio rapido: Creare uno spazio dei nomi di Hub eventi e un hub eventi per creare uno spazio dei nomi di Hub eventi e un hub eventi. Seguire quindi le istruzioni riportate in Ottenere la stringa di connessione per ottenere una stringa di connessione in relazione allo spazio dei nomi di Hub eventi.

Prendere nota delle impostazioni seguenti usate nella guida di avvio rapido corrente:

  • stringa di connessione per lo spazio dei nomi di Hub eventi
  • Nome dell'hub eventi

Creare uno schema

Seguire le istruzioni riportate in Creare schemi utilizzando il Registro schemi per creare un gruppo di schemi e uno schema.

  1. Creare un gruppo di schemi denominato contoso-sg utilizzando il portale del Registro schemi. Usare Avro come tipo di serializzazione e Nessuna per la modalità di compatibilità.

  2. In tale gruppo di schemi creare un nuovo schema Avro con il nome dello schema: Microsoft.Azure.Data.SchemaRegistry.example.Order utilizzando il contenuto dello schema seguente.

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

Aggiungere un utente al ruolo lettore del Registro schemi

Aggiungere l'account utente al ruolo Lettore del Registro schemi a livello di spazio dei nomi. È inoltre possibile usare il ruolo Collaboratore del Registro schemi, ma non è necessario per questa guida introduttiva.

  1. Nella pagina Spazio dei nomi di Hub eventi, selezionare Controllo di accesso (IAM) nel menu a sinistra.
  2. Nella pagina Controllo di accesso (IAM), selezionare + Aggiungi ->Aggiungi assegnazione di ruolo nel menu.
  3. Nella pagina Tipo di assegnazione, selezionare Avanti.
  4. Nella pagina Ruoli, selezionare Lettore del Registro schemi (anteprima) e quindi selezionare Avanti nella parte inferiore della pagina.
  5. Usare il collegamento + Seleziona membri per aggiungere l'account utente al ruolo e quindi selezionare Avanti.
  6. Nella pagina Rivedi + assegna, selezionare Rivedi + assegna.

Generare eventi in hub eventi con la convalida dello schema

Creare un'applicazione console per il producer di eventi

  1. Avviare Visual Studio 2019.
  2. Selezionare Crea un nuovo progetto.
  3. Nella finestra di dialogo Crea un nuovo progetto seguire questa procedura: se non viene visualizzata questa finestra di dialogo, selezionare File dal menu, selezionare Nuovoe quindi selezionare Progetto.

    1. Selezionare C# come linguaggio di programmazione.

    2. Selezionare Console come tipo di applicazione.

    3. Selezionare Applicazione console nell'elenco dei risultati.

    4. Quindi seleziona Avanti.

      Image showing the New Project dialog box.

  4. Immettere OrderProducer come nome del progetto, SRQuickStart per il nome della soluzione e quindi selezionare OK per creare il progetto.

Aggiungere il pacchetto NuGet di Hub eventi

  1. Scegliere Strumenti>Gestione pacchetti NuGet>Console di Gestione pacchetti dal menu.

  2. Eseguire i comandi seguenti per installare Azure.Messaging.EventHubs e altri pacchetti NuGet. Premere INVIO per eseguire l'ultimo comando.

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

  3. Autenticare le applicazioni producer per connettersi ad Azure tramite Visual Studio, come illustrato qui.

  4. Accedere ad Azure utilizzando l'account utente membro del ruolo Schema Registry Reader a livello dello spazio dei nomi. Per informazioni sui ruoli del Registro schemi, vedere Registro schemi di Azure in Hub eventi.

Generazione di codice con lo schema Avro

  1. Utilizzare lo stesso contenuto usato per creare lo schema per creare un file denominato Order.avsc. Salvare il file nella cartella del progetto o della soluzione.
  2. È quindi possibile usare questo file di schema per generare codice per .NET. È possibile usare qualsiasi strumento di generazione di codice esterno, ad esempio avrogen per la generazione di codice. Ad esempio, è possibile eseguire avrogen -s .\Order.avsc . per generare codice.
  3. Dopo aver generato il codice, verrà visualizzato il file denominato Order.cs nella cartella \Microsoft\Azure\Data\SchemaRegistry\example. Per lo schema Avro precedente, genera i tipi C# nello spazio dei nomi Microsoft.Azure.Data.SchemaRegistry.example.
  4. Aggiungere il file Order.cs al progetto OrderProducer.

Scrivere codice per serializzare e inviare eventi all'hub eventi

  1. Aggiungere il codice seguente al file Program.cs. Per i dettagli, vedere i commenti nel codice. I passaggi di alto livello nel codice sono:

    1. Creare un client producer che è possibile utilizzare per inviare eventi a un hub eventi.
    2. Creare un client del Registro schemi che è possibile usare per serializzare e convalidare i dati in un oggetto Order.
    3. Creare un nuovo oggetto Order usando il tipo Order generato.
    4. Utilizzare il client del Registro schemi per serializzare l'oggetto Order in EventData.
    5. Creare un batch di eventi.
    6. Aggiungere i dati dell'evento al batch di eventi.
    7. Utilizzare il client producer per inviare il batch di eventi all'hub eventi.
    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. Sostituire i valori segnaposto seguenti con i valori reali.

    • EVENTHUBSNAMESPACECONNECTIONSTRING - stringa di connessione per lo spazio dei nomi di Hub eventi
    • EVENTHUBNAME - nome dell'hub eventi
    • EVENTHUBSNAMESPACENAME - nome dello spazio dei nomi di Hub eventi
    • SCHEMAGROUPNAME - nome del gruppo di schemi
    // 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. Compilare il progetto e assicurarsi che non siano presenti errori.

  4. Eseguire il programma e attendere il messaggio di conferma.

    A batch of 1 order has been published.

  5. Nel portale di Azure è possibile verificare che l'hub eventi abbia ricevuto gli eventi. Passare alla visualizzazione Messaggi nella sezione Metriche. Aggiornare la pagina per aggiornare il grafico. La conferma che i messaggi sono stati ricevuti potrebbe comparire dopo alcuni secondi.

    Image of the Azure portal page to verify that the event hub received the events.

Utilizzare eventi da hub eventi con la convalida dello schema

Questa sezione illustra come scrivere un'applicazione console .NET Core che riceve eventi da un hub eventi e come usare il Registro schemi per deserializzare i dati degli eventi.

Prerequisiti aggiuntivi

  • Creare l'account di archiviazione da usare per il processore di eventi.

Creare un'applicazione consumer

  1. Nella finestra Esplora soluzioni fare clic con il pulsante destro del mouse sulla soluzione EventHubQuickStart, scegliere Aggiunti e selezionare Nuovo progetto.
  2. Selezionare Applicazione console e selezionare Avanti.
  3. Immettere OrderConsumer come Nome progetto e selezionare Crea.
  4. Nella finestra Esplora soluzioni, fare clic con il pulsante destro del mouse su OrderConsumere scegliere Imposta come progetto di avvio.

Aggiungere il pacchetto NuGet di Hub eventi

  1. Scegliere Strumenti>Gestione pacchetti NuGet>Console di Gestione pacchetti dal menu.

  2. Nella finestra Console di gestione pacchetti verificare che OrderConsumer sia selezionato per il progetto predefinito. In caso contrario, utilizzare l'elenco a discesa per selezionare OrderConsumer.

  3. Eseguire il comando seguente per installare i pacchetti NuGet necessari. Premere INVIO per eseguire l'ultimo 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. Autenticare le applicazioni producer per connettersi ad Azure tramite Visual Studio, come illustrato qui.

  5. Accedere ad Azure utilizzando l'account utente membro del ruolo Schema Registry Reader a livello dello spazio dei nomi. Per informazioni sui ruoli del Registro schemi, vedere Registro schemi di Azure in Hub eventi.

  6. Aggiungere il file Order.cs generato durante la creazione dell'app producer al progetto OrderConsumer.

  7. Fare clic con il pulsante destro del mouse sul progetto OrderConsumer e scegliere Imposta come progetto di avvio.

Scrivere codice per ricevere gli eventi e deserializzarli usando il Registro schemi

  1. Aggiungere il codice seguente al file Program.cs. Per i dettagli, vedere i commenti nel codice. I passaggi di alto livello nel codice sono:

    1. Creare un client consumer che è possibile usare per inviare eventi a un hub eventi.
    2. Creare un client contenitore BLOB per il contenitore BLOB nell'archivio BLOB di Azure.
    3. Creare un client del processore di eventi e registrare gestori eventi ed errori.
    4. Nel gestore dell’evento creare un client del Registro schemi che è possibile usare per deserializzare i dati degli eventi in un oggetto Order.
    5. Deserializzare i dati degli eventi in un oggetto Order utilizzando il serializzatore.
    6. Stampare le informazioni sull'ordine ricevuto.
    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 userd 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. Sostituire i valori segnaposto seguenti con i valori reali.

    • EVENTHUBSNAMESPACE-CONNECTIONSTRING - stringa di connessione per lo spazio dei nomi di Hub eventi
    • EVENTHUBNAME - nome dell'hub eventi
    • EVENTHUBSNAMESPACENAME - nome dello spazio dei nomi di Hub eventi
    • SCHEMAGROUPNAME - nome del gruppo di schemi
    • AZURESTORAGECONNECTIONSTRING - stringa di connessione per l'account di archiviazione di Azure
    • BLOBCONTAINERNAME - Nome del contenitore BLOB
    // 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. Compilare il progetto e assicurarsi che non siano presenti errori.

  4. Eseguire l'applicazione ricevente.

  5. Verrà visualizzato un messaggio che informa che gli eventi sono stati ricevuti.

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

    Questi eventi sono i tre eventi inviati in precedenza all'hub eventi eseguendo il programma mittente.

Esempi

Vedere l'articolo Leggimi nel repository GitHub.

Pulire le risorse

Eliminare lo spazio dei nomi di Hub eventi o eliminare il gruppo di risorse che contiene lo spazio dei nomi.

Passaggi successivi

Eseguire il checkout della libreria client del Registro schemi di Azure per .NET