Validar usando um esquema Avro ao transmitir eventos usando os SDKs do .NET dos Hubs de Eventos (AMQP)

Neste início rápido, você aprende como enviar e receber eventos de um hub de eventos com validação de esquema usando a biblioteca Azure.Messaging.EventHubs do .NET.

Observação

O Registro de Esquema do Azure é um recurso dos Hubs de Eventos que funciona como um repositório central para esquemas para aplicativos voltados para mensagens e controlados por eventos. É uma ferramenta flexível para aplicativos de consumidor e produtor trocarem dados sem precisar gerenciar e compartilhar o esquema. Ele também conta com uma estrutura de governança simples para esquemas reutilizáveis e define a relação entre os esquemas por meio de um constructo de agrupamento (grupos de esquemas). Para saber mais, confira Registro de Esquema do Azure nos Hubs de Eventos.

Pré-requisitos

Se você estiver conhecendo agora os Hubs de Eventos do Azure, confira Visão geral dos Hubs de Eventos antes de prosseguir com este início rápido.

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

• Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
• Microsoft Visual Studio 2022. A biblioteca de clientes dos Hubs de Eventos do Azure usa novos recursos que foram introduzidos no C# 8.0. Você ainda pode usar a biblioteca com as versões anteriores do idioma C#, mas a nova sintaxe não está disponível. Para usar a sintaxe completa, recomenda-se compilar com o SDK do .NET Core 3.0 ou superior e a versão de linguagem definida como latest. Se você estiver usando o Visual Studio, as versões anteriores ao Visual Studio 2019 não serão compatíveis com as ferramentas necessárias para compilar projetos C# 8.0. O Visual Studio 2019, incluindo a edição Community gratuita, pode ser baixado aqui.

Criar um Hub de Evento

Siga as instruções do início rápido: Criar um namespace dos Hubs de Eventos e um hub de eventos para criar um namespace dos Hubs de Eventos e um hub de eventos. Depois, siga as instruções em Obter a cadeia de conexão para obter uma cadeia de conexão para seu namespace dos Hubs de Eventos.

Anote as seguintes configurações que você usará no início rápido atual:

• Cadeia de conexão para o namespace dos Hubs de Eventos
• Nome do hub de eventos

Criar um esquema

Siga as instruções em Criar esquemas usando o Registro de Esquema para criar um grupo de esquema e um esquema.

1. Crie um grupo de esquema chamado contoso-sg usando o portal do registro de esquema. Use Avro como o tipo de serialização e Nenhum para o modo de compatibilidade.

2. Nesse grupo de esquemas, crie um esquema Avro com o nome do esquema Microsoft.Azure.Data.SchemaRegistry.example.Order usando o conteúdo do esquema a seguir.

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

Adicionar usuário à função de Leitor de Registro de Esquema

Adicione sua conta de usuário à função Leitor de Registro de Esquema no nível do namespace. Você também pode usar a função Colaborador do Registro de Esquema, mas isso não é necessário para este início rápido.

1. Na página Namespace de Hubs de Eventos, selecione Gerenciamento de Identidades e Acesso (IAM) no menu à esquerda.
2. Na página Gerenciamento de Identidades e Acesso (IAM), selecione + Adicionar ->Adicionar atribuição de função no menu.
3. Na página Tipo de atribuição, selecione Avançar.
4. Na página Funções, selecione Leitor de Registro de Esquema (versão prévia), e então selecione Avançar na parte inferior da página.
5. Use o link + Selecionar membros para adicionar sua conta de usuário à função, e depois selecione Avançar.
6. Na página Examinar + atribuir, selecione Examinar + atribuir.

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

Criar um aplicativo de console 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 projeto, execute as seguintes etapas: Se essa caixa de diálogo não for exibida, selecione Arquivo no menu, Novo e, em seguida, Projeto.

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

   2. Selecione Console como o tipo do aplicativo.

   3. Selecione Aplicativo de console na lista de resultados.

   4. Em seguida, selecione Avançar.

      

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

Adicione o pacote NuGet de Hubs de Eventos

1. Selecione Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes no menu.

2. Execute os seguintes comandos para instalar Azure.Messaging.EventHubs e outros pacotes NuGet. Pressione 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. Autentique aplicativos de produtor para se conectar ao Azure por meio de Visual Studio, conforme mostrado aqui.

4. Entre no Azure usando a conta de usuário que é membro da função Schema Registry Reader no nível do namespace. Para obter informações sobre funções de registro de esquema, consulte Registro de Esquema do Azure nos Hubs de Eventos.

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

1. Use o mesmo conteúdo que você usou para criar o esquema para criar um arquivo nomeado Order.avsc. Salve o arquivo na pasta do projeto ou solução.
2. Em seguida, você pode usar esse arquivo de esquema para gerar código para .NET. Para geração de código. você pode usar qualquer ferramenta de externa para esse fim, como avrogen. Por exemplo, você pode executar avrogen -s .\Order.avsc . para gerar código.
3. Uma vez gerado o código, você verá o arquivo nomeado Order.cs na pasta \Microsoft\Azure\Data\SchemaRegistry\example. Para o esquema Avro acima, ele gera os tipos de C# no namespace Microsoft.Azure.Data.SchemaRegistry.example.
4. Adicione o arquivo Order.cs ao projeto OrderProducer.

Escrever código para serializar eventos e enviá-los para o hub de eventos

1. Adicione o seguinte código ao arquivo Program.cs. Confira os comentários sobre código para obter detalhes. As etapas de alto nível do código são:

   1. Criar um cliente produtor que você pode usar para enviar eventos para um hub de eventos.
   2. Criar um cliente de registro de esquema que você pode usar para serializar e validar dados em um objeto Order.
   3. Criar um novo objeto Order usando o tipo Order gerado.
   4. Use o cliente de registro de esquema para serializar o objeto Order para EventData.
   5. Criar um lote de eventos.
   6. Adicionar os dados do evento ao lote de eventos.
   7. Use o cliente 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. Substituir os seguintes valores de espaço reservado por valores reais.

   • EVENTHUBSNAMESPACECONNECTIONSTRING - cadeia de conexão para o namespace dos Hubs de Eventos
   • EVENTHUBNAME - nome do hub de eventos
   • EVENTHUBSNAMESPACENAME - nome do namespace dos Hubs de Eventos
   • SCHEMAGROUPNAME - nome do grupo de esquema

   // 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 o projeto e verifique se não há erros.

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

   A batch of 1 order has been published.
   

5. No portal do Azure, você poderá verificar se o hub de eventos recebeu os eventos. Alterne para a exibição Mensagens na seção Métricas. Atualize a página para atualizar o gráfico. Poderá levar alguns segundos para que ela mostre que as mensagens foram recebidas.

   

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

Esta seção mostra como gravar um aplicativo de console .NET Core que recebe eventos de um hub de eventos e usa o registro de esquema para desserializar os dados de evento.

Pré-requisitos adicionais

• Criar a conta de armazenamento a ser usada no processador de eventos.

Criar um aplicativo de consumidor

1. Na janela do Gerenciador de Soluções, clique com o botão direito do mouse na solução SRQuickStart, aponte para Adicionar e selecione Novo Projeto.
2. Selecione Aplicativo de console e Próximo.
3. Insira OrderConsumer em Nome do projeto e selecione Criar.
4. Na janela Gerenciador de Soluções, clique com o botão direito do mouse em OrderConsumer e selecione Definir como um projeto de inicialização.

Adicione o pacote NuGet de Hubs de Eventos

1. Selecione Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes no menu.

2. Na janela Gerenciador de pacotes de console, confirme se OrderConsumer está selecionado para o Projeto padrão. Caso não esteja, use a lista suspensa para selecionar OrderConsumer.

3. Execute o seguinte comando para instalar os pacotes de NuGet necessários. Pressione 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 aplicativos de produtor para se conectar ao Azure por meio de Visual Studio, conforme mostrado aqui.

5. Entre no Azure usando a conta de usuário que é membro da função Schema Registry Reader no nível do namespace. Para obter informações sobre funções de registro de esquema, consulte Registro de Esquema do Azure nos Hubs de Eventos.

6. Adicionar o arquivo Order.cs gerado como parte da criação do aplicativo produtor ao projeto OrderConsumer.

7. Clique com o botão direito do mouse no projeto OrderConsumer, e selecione Definir como Projeto de Inicialização.

Escrever código para receber eventos e desserializá-los usando o Registro de Esquema

1. Adicione o seguinte código ao arquivo Program.cs. Confira os comentários sobre código para obter detalhes. As etapas de alto nível do código são:

   1. Criar um cliente consumidor que você pode usar para enviar eventos para um hub de eventos.
   2. Criar um cliente de contêiner de blob para o contêiner de blob no armazenamento de blob do Azure.
   3. Criar um cliente processador de eventos e registre os manipuladores de eventos e erros.
   4. No manipulador de eventos, crie um cliente de registro de esquema que você pode usar para desserializar os dados de evento em um objeto Order.
   5. Desserializar os dados do evento em um objeto Order usando o serializador.
   6. Imprimir as informações sobre a ordem 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. Substituir os seguintes valores de espaço reservado por valores reais.

   • EVENTHUBSNAMESPACE-CONNECTIONSTRING - cadeia de conexão para o namespace dos Hubs de Eventos
   • EVENTHUBNAME - nome do hub de eventos
   • EVENTHUBSNAMESPACENAME - nome do namespace dos Hubs de Eventos
   • SCHEMAGROUPNAME - nome do grupo de esquema
   • AZURESTORAGECONNECTIONSTRING - cadeia de conexão para a conta de armazenamento do Azure
   • BLOBCONTAINERNAME - Nome do contêiner de 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. Compile o projeto e verifique se não há erros.

4. Execute o aplicativo receptor.

5. Você deverá ver uma mensagem informando que os eventos foram recebidos.

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

   Esses eventos são os três eventos que você enviou para o hub de eventos anteriormente executando o programa de remetente.

Exemplos

Consulte o artigo Leiame em nosso repositório GitHub.

Limpar os recursos

Excluir o namespace dos Hubs de Eventos ou excluir o grupo de recursos que contém o namespace.

Próximas etapas

Veja Biblioteca de clientes do Registro de Esquema do Azure para .NET