Validar a utilização de um esquema Avro ao transmitir eventos com SDKs .NET (AMQP) dos Hubs de Eventos

Neste início rápido, irá aprender a enviar eventos para e receber eventos de um hub de eventos com validação de esquema com a biblioteca .NET do Azure.Messaging.EventHubs .

Nota

O Azure Schema Registry é uma funcionalidade dos Hubs de Eventos, que fornece um repositório central para esquemas para aplicações centradas em eventos e mensagens. Fornece a flexibilidade para que as suas aplicações de produtor e consumidor troquem dados sem terem de gerir e partilhar o esquema. Também fornece uma arquitetura de governação simples para esquemas reutilizáveis e define a relação entre esquemas através de uma construção de agrupamento (grupos de esquemas). Para obter mais informações, veja Registo de Esquemas do Azure nos Hubs de Eventos.

Pré-requisitos

Se não estiver familiarizado com Hubs de Eventos do Azure, consulte Descrição geral dos Hubs de Eventos antes de efetuar este início rápido.

Para concluir este início rápido, precisa dos seguintes pré-requisitos:

• Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
• Microsoft Visual Studio 2022. A biblioteca de cliente Hubs de Eventos do Azure utiliza as novas funcionalidades que foram introduzidas no C# 8.0. Ainda pode utilizar a biblioteca com versões de idioma C# anteriores, mas a nova sintaxe não está disponível. Para utilizar a sintaxe completa, recomendamos que compile com o SDK .NET Core 3.0 ou superior e a versão de idioma definida como latest. Se estiver a utilizar o Visual Studio, as versões anteriores ao Visual Studio 2019 não são compatíveis com as ferramentas necessárias para criar projetos C# 8.0. O Visual Studio 2019, incluindo a edição Comunidade gratuita, pode ser transferido aqui.

Criar um hub de eventos

Siga as instruções do início rápido: crie um espaço de nomes dos Hubs de Eventos e um hub de eventos para criar um espaço de nomes dos Hubs de Eventos e um hub de eventos. Em seguida, siga as instruções de Obter a cadeia de ligação para obter uma cadeia de ligação para o espaço de nomes dos Hubs de Eventos.

Tenha em atenção as seguintes definições que irá utilizar no início rápido atual:

• Cadeia de ligação para o espaço de nomes dos Hubs de Eventos
• Nome do hub de eventos

Criar um esquema

Siga as instruções de Criar esquemas com o Registo de Esquemas para criar um grupo de esquemas e um esquema.

1. Crie um grupo de esquema com o nome contoso-sg com o portal do Registo de Esquemas. Utilize o Avro como o tipo de serialização e Nenhum para o modo de compatibilidade.

2. Nesse grupo de esquemas, crie um novo esquema Avro com o nome do esquema: Microsoft.Azure.Data.SchemaRegistry.example.Order com o seguinte conteúdo 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"
       }
     ]
   } 
   

Adicionar utilizador à função de Leitor de Registo de Esquemas

Adicione a sua conta de utilizador à função Leitor de Registo de Esquemas ao nível do espaço de nomes. Também pode utilizar a função Contribuidor do Registo de Esquema , mas isso não é necessário para este início rápido.

1. Na página Espaço de Nomes dos Hubs de Eventos , selecione Controlo de acesso (IAM) no menu esquerdo.
2. Na página Controlo de acesso (IAM), selecione + Adicionar ->Adicionar atribuição de função no menu.
3. Na página Tipo de atribuição , selecione Seguinte.
4. Na página Funções , selecione Leitor de Registo de Esquemas (Pré-visualização) e, em seguida, selecione Seguinte na parte inferior da página.
5. Utilize a ligação + Selecionar membros para adicionar a sua conta de utilizador à função e, em seguida, selecione Seguinte.
6. Na página Rever + atribuir , selecione Rever + atribuir.

Produzir eventos para hubs de eventos com validação de esquema

Criar aplicação de consola para o produtor de eventos

1. Inicie o Visual Studio 2019.
2. Selecione Criar um novo projeto.
3. Na caixa de diálogo Criar um novo projeto , siga os seguintes passos: se não vir esta caixa de diálogo, selecione Ficheiro no menu, selecione Novo e, em seguida, selecione Projeto.

   1. Selecione C# para a linguagem de programação.

   2. Selecione Consola para o tipo de aplicação.

   3. Selecione Aplicação de Consola na lista de resultados.

   4. Em seguida, selecione Seguinte.

      

4. Introduza OrderProducer para o nome do projeto, SRQuickStart para o nome da solução e, em seguida, selecione OK para criar o projeto.

Adicionar o pacote NuGet dos Hubs de Eventos

1. Selecione Ferramentas>NuGet Gestor de>Pacotes Consola do Gestor de Pacotes no menu.

2. Execute os seguintes comandos para instalar o Azure.Messaging.EventHubs e outros pacotes NuGet. Prima ENTER para executar o último comando.

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

3. Autenticar aplicações de produtor para ligar ao Azure através do Visual Studio, conforme mostrado aqui.

4. Inicie sessão no Azure com a conta de utilizador que é membro da função Schema Registry Reader ao nível do espaço de nomes. Para obter informações sobre as funções de registo de esquemas, veja Registo de Esquemas do Azure nos Hubs de Eventos.

Geração de código com o esquema Avro

1. Utilize o mesmo conteúdo que utilizou para criar o esquema para criar um ficheiro com o nome Order.avsc. Guarde o ficheiro na pasta projeto ou solução.
2. Em seguida, pode utilizar este ficheiro de esquema para gerar código para .NET. Pode utilizar qualquer ferramenta de geração de código externo, como o avrogen para a geração de código. Por exemplo, pode executar avrogen -s .\Order.avsc . para gerar código.
3. Assim que gerar código, verá o ficheiro com o \Microsoft\Azure\Data\SchemaRegistry\example nome Order.cs na pasta. Para o esquema Avro acima, gera os tipos C# no Microsoft.Azure.Data.SchemaRegistry.example espaço de nomes.
4. Adicione o Order.cs ficheiro ao OrderProducer projeto.

Escrever código para serializar e enviar eventos para o hub de eventos

1. Adicione o seguinte código ao ficheiro Program.cs. Veja os comentários de código para obter detalhes. Os passos de alto nível no código são:

   1. Crie um cliente de produtor que pode utilizar para enviar eventos para um hub de eventos.
   2. Crie um cliente de registo de esquema que pode utilizar para serializar e validar dados num Order objeto.
   3. Crie um novo Order objeto com o tipo gerado Order .
   4. Utilize o cliente do registo de esquemas para serializar o Order objeto para EventData.
   5. Crie um lote de eventos.
   6. Adicione os dados do evento ao lote de eventos.
   7. Utilize o cliente de produtor para enviar o lote de eventos para o hub 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. Substitua os seguintes valores de marcador de posição pelos valores reais.

   • EVENTHUBSNAMESPACECONNECTIONSTRING - cadeia de ligação para o espaço de nomes dos Hubs de Eventos
   • EVENTHUBNAME - nome do hub de eventos
   • EVENTHUBSNAMESPACENAME - nome do espaço de nomes dos Hubs de Eventos
   • SCHEMAGROUPNAME - nome do 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. Crie o projeto e certifique-se de que não existem erros.

4. Execute o programa e aguarde pela mensagem de confirmação.

   A batch of 1 order has been published.
   

5. No portal do Azure, pode verificar se o hub de eventos recebeu os eventos. Mude para a vista Mensagens na secção Métricas . Atualize a página para atualizar o gráfico. Pode demorar alguns segundos para que mostre que as mensagens foram recebidas.

   

Consumir eventos de hubs de eventos com validação de esquema

Esta secção mostra como escrever uma aplicação de consola .NET Core que recebe eventos de um hub de eventos e utilizar o registo de esquemas para anular a serialização de dados de eventos.

Pré-requisitos adicionais

• Crie a conta de armazenamento para utilizar o processador de eventos.

Criar aplicação de consumidor

1. Na janela Explorador de Soluções, clique com o botão direito do rato na solução SRQuickStart, aponte para Adicionar e selecione Novo Projeto.
2. Selecione Aplicação de consola e selecione Seguinte.
3. Introduza OrderConsumer para o Nome do projeto e selecione Criar.
4. Na janela Explorador de Soluções, clique com o botão direito do rato em OrderConsumer e selecione Definir como um Projeto de Arranque.

Adicionar o pacote NuGet dos Hubs de Eventos

1. Selecione Ferramentas>NuGet Gestor de>Pacotes Consola do Gestor de Pacotes no menu.

2. Na janela Consola do Gestor de Pacotes , confirme que OrderConsumer está selecionado para o projeto Predefinido. Caso contrário, utilize a lista pendente para selecionar OrderConsumer.

3. Execute o seguinte comando para instalar os pacotes NuGet necessários. Prima ENTER para executar o ú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 as aplicações de produtor para ligar ao Azure através do Visual Studio, conforme mostrado aqui.

5. Inicie sessão no Azure com a conta de utilizador que é membro da função Schema Registry Reader ao nível do espaço de nomes. Para obter informações sobre as funções de registo de esquemas, veja Registo de Esquemas do Azure nos Hubs de Eventos.

6. Adicione o Order.cs ficheiro que gerou como parte da criação da aplicação de produtor ao projeto OrderConsumer .

7. Clique com o botão direito do rato em OrderConsumer project (Projeto OrderConsumer ) e selecione Set as Startup project (Definir como projeto de Arranque).

Escrever código para receber eventos e anular a serialização com o Registo de Esquemas

1. Adicione o seguinte código ao ficheiro Program.cs. Veja os comentários de código para obter detalhes. Os passos de alto nível no código são:

   1. Crie um cliente de consumidor que pode utilizar para enviar eventos para um hub de eventos.
   2. Crie um cliente de contentor de blobs para o contentor de blobs no armazenamento de blobs do Azure.
   3. Crie um cliente de processador de eventos e registe processadores de eventos e erros.
   4. No processador de eventos, crie um cliente de registo de esquema que pode utilizar para anular a serialização de dados de eventos num Order objeto.
   5. Anular a serialização dos dados do evento num Order objeto com o serializador.
   6. Imprima as informações sobre a encomenda recebida.

   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. Substitua os seguintes valores de marcador de posição pelos valores reais.

   • EVENTHUBSNAMESPACE-CONNECTIONSTRING - cadeia de ligação para o espaço de nomes dos Hubs de Eventos
   • EVENTHUBNAME - nome do hub de eventos
   • EVENTHUBSNAMESPACENAME - nome do espaço de nomes dos Hubs de Eventos
   • SCHEMAGROUPNAME - nome do grupo de esquemas
   • AZURESTORAGECONNECTIONSTRING - cadeia de ligação para a conta de armazenamento do Azure
   • BLOBCONTAINERNAME - Nome do contentor 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. Crie o projeto e certifique-se de que não existem erros.

4. Execute a aplicação recetora.

5. Deverá ver uma mensagem a indicar que os eventos foram recebidos.

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

   Estes eventos são os três eventos que enviou anteriormente para o hub de eventos ao executar o programa do remetente.

Amostras

Veja o artigo Leia-me no nosso repositório do GitHub.

Limpar os recursos

Elimine o espaço de nomes dos Hubs de Eventos ou elimine o grupo de recursos que contém o espaço de nomes.

Passos seguintes

Veja a biblioteca de cliente do Registo de Esquemas do Azure para .NET