Início Rápido: Enviar e receber mensagens de um tópico de namespace da Grade de Eventos do Azure (.NET)

Neste guia de início rápido, você realizará as seguintes ações:

1. Crie um namespace da Grade de Eventos usando o portal do Azure.
2. Crie um tópico de namespace da Grade de Eventos usando o portal do Azure.
3. Crie uma assinatura de evento usando o portal do Azure.
4. Escreva um aplicativo de console do .NET para enviar um conjunto de mensagens para o tópico.
5. Escreva um aplicativo de console do .NET para receber essas mensagens do tópico.

Observação

Esse início rápido fornece instruções passo a passo para implementar um cenário simples de enviar um lote de mensagens para um Tópico de Namespace da Grade de Eventos e, em seguida, recebê-las. Para ter uma visão geral da biblioteca de clientes do .NET, confira Biblioteca cliente da Grade de Eventos do Azure para .NET. Para obter mais amostras, confira Amostras da Grade de Eventos do .NET no GitHub.

Pré-requisitos

Se estiver apenas começando a usar o serviço, confira a Visão geral da Grade de Eventos antes de usar esse guia de início rápido.

• Assinatura do Azure. Para usar os serviços do Azure, incluindo a Grade de Eventos do Azure, você precisa ter uma assinatura. Caso tenha uma conta do Azure, poderá se inscrever em uma avaliação gratuita.
• Visual Studio 2022. O aplicativo de exemplo usa novos recursos que foram introduzidos no C# 10. Para usar a sintaxe mais recente, recomendamos instalar o .NET 6.0 ou superior e configurar a versão da linguagem como latest. Se você estiver usando o Visual Studio, as versões anteriores ao Visual Studio 2022 não serão compatíveis com as ferramentas necessárias para compilar projetos do C# 10.

Criar um namespace no Portal do Azure

Um namespace na Grade de Eventos do Azure é um contêiner lógico para um ou mais tópicos, clientes, grupos de clientes, espaços de tópicos e associações de permissão. Ele fornece um namespace exclusivo, permitindo que você tenha vários recursos na mesma região do Azure. Com um namespace da Grade de Eventos do Azure, você já pode agrupar recursos relacionados e gerenciá-los como uma só unidade na sua assinatura do Azure.

Siga as próximas seções para criar, exibir e gerenciar um namespace da Grade de Eventos do Azure.

Para criar um namespace:

1. Entre no portal do Azure.

2. Na caixa de pesquisa, insira Namespaces da Grade de Eventos e selecione Namespaces da Grade de Eventos nos resultados.

   

3. Na página Namespaces da Grade de Eventos, selecione + Criar na barra de ferramentas.

   

4. Na página Básico, siga essas etapas.

   1. Selecione a Assinatura do Azure na qual você quer criar o namespace.

   2. Escolha um grupo de recursos existente ou crie um grupo de recursos.

   3. Insira um nome para o namespace.

   4. Selecione a região ou a localização onde você deseja criar o namespace.

   5. Selecione Revisar + criar na parte inferior da página.

      

5. Na página Revisar + criar, revise as configurações e selecione Criar.

6. Na página Implantação bem sucedida, selecione Ir para o recurso para navegar até a página do seu namespace.

Criar um tópico de namespace

1. Se não está na página Namespace da Grade de Eventos, siga as etapas em criar, exibir e gerenciar namespaces para visualizar o namespace que você quer usar para criar o tópico.

2. Na página Namespace da Grade de Eventos, selecione a opção Tópicos na seção Eventos no menu do lado esquerdo.

3. Na página Tópicos, selecione o botão + Tópico na barra de comandos.

   

4. Na página Criar Tópico, digite o nome do tópico que você quer criar e selecione Criar.

   

Criar uma assinatura de evento

1. No portal do Azure, se você está na página Tópicos do seu namespace da Grade de Eventos, selecione o tópico na lista de tópicos disponíveis. Caso esteja na página Tópicos, siga as instruções descritas em criar, exibir e gerenciar tópicos de um namespace para identificar o tópico que deseja usar para criar a assinatura do evento.

2. Na página do Tópico do Namespace da Grade de Eventos, escolha a opção Assinaturas na seção Entidades no menu lateral esquerdo.

3. Na página Assinaturas, clique no botão "+ Assinatura" na barra de comandos.

   

4. Na guia Informações básicas, digite o nome do tópico que deseja criar e, em seguida, selecione Avançar: Filtros na parte inferior da página.

   

5. Na guia Filtros, adicione os nomes dos tipos de eventos que deseja filtrar na assinatura e adicione filtros de atributo de contexto que deseja usar na assinatura. Em seguida, selecione Avançar: recursos adicionais na parte inferior da página.

   

6. Na guia Recursos adicionais, você pode definir a retenção de eventos,o número máximo de entregas, a duração do bloqueio e as configurações de mensagens não entregues.

   

7. Selecione Criar para criar a assinatura de evento.

Autenticar o aplicativo no Azure

Esse início rápido irá lhe mostrar duas maneiras de se conectar à Grade de Eventos do Azure: cadeia de conexão.

Esse documento mostra a você como usar uma cadeia de conexão para se conectar a um namespace da Grade de Eventos. Se você é novo no Azure, talvez ache a opção de cadeia de conexão mais fácil de ser seguida.

A criação de um novo namespace da Grade de Eventos gera automaticamente uma chave primária e uma chave secundária iniciais, ambas concedendo controle total sobre todos os aspectos ou tópicos do namespace.

Um cliente pode usar a cadeia de conexão para se conectar ao namespace da Grade de Eventos. Para copiar as chaves de acesso para o seu namespace, siga essas etapas:

1. Na página Namespace da Grade de Eventos, selecione Tópicos.
2. Selecione o tópico que você precisa acessar.
3. Na página Chaves de acesso, selecione o botão copiar ao lado da Chave 1 ou Chave 2 para copiar as chaves de acesso para a sua área de transferência para uso posterior. Cole esse valor no Bloco de notas ou em outro local temporário.

Iniciar o Visual Studio

Você pode autorizar o acesso ao namespace da Grade de Eventos usando as seguintes etapas:

Inicie o Visual Studio. Se você vir a janela Introdução, selecione o link Continuar sem código no painel direito.

Enviar mensagens para o tópico

Essa seção mostra a você como criar um aplicativo de console do .NET para enviar mensagens para um tópico da Grade de Eventos.

Criar um aplicativo de console

1. No Visual Studio, selecione o menu Arquivo ->Novo ->Projeto.

2. 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.

      

3. Insira EventSender como o nome do projeto, EventGridQuickStart como o nome da solução e selecione Avançar.

   

4. Na página Informações adicionais, selecione Criar para criar a solução e o projeto.

Adicionar os pacotes do NuGet ao projeto

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

2. Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.EventGrid:

   Install-Package Azure.Messaging.EventGrid -version 4.22.0-beta.1
   

Adicionar o código para enviar o evento para o tópico do namespace

1. Substitua o conteúdo de Program.cs pelo seguinte código. As etapas importantes estão destacadas, com informações adicionais nos comentários de código.

   Importante

   Substitua os valores do espaço reservado (<ENDPOINT> , <TOPIC-NAME>, <TOPIC-ACCESS-KEY>, <TOPIC-SUBSCRIPTION-NAME>) no trecho de código com o ponto de extremidade, nome, chave e nome da assinatura do seu tópico.

   using Azure.Messaging;
   using Azure;
   using Azure.Messaging.EventGrid.Namespaces;    
   
   // TODO: Replace the <ENDPOINT> , <TOPIC-KEY> and <TOPIC-NAME> placeholder
   
   var topicEndpoint = "<TOPIC-ENDPOINT>"; // Should be in the form: https://namespace01.eastus-1.eventgrid.azure.net. 
   var topicKey = "<TOPIC-ACCESS-KEY>";
   var topicName = "<TOPIC-NAME>";
   var subscription = "<TOPIC-SUBSCRIPTION-NAME>";
   
   // Construct the client using an Endpoint for a namespace as well as the access key
   var client = new EventGridClient(new Uri(topicEndpoint), new AzureKeyCredential(topicKey));
   
   // Publish a single CloudEvent using a custom TestModel for the event data.
   var @ev = new CloudEvent("employee_source", "type", new TestModel { Name = "Bob", Age = 18 });
   await client.PublishCloudEventAsync(topicName, ev);
   
   // Publish a batch of CloudEvents.
   
   await client.PublishCloudEventsAsync(
   topicName,
   new[] {
       new CloudEvent("employee_source", "type", new TestModel { Name = "Tom", Age = 55 }),
       new CloudEvent("employee_source", "type", new TestModel { Name = "Alice", Age = 25 })});
   
   Console.WriteLine("Three events have been published to the topic. Press any key to end the application.");
   Console.ReadKey();
   
   public class TestModel
   {
       public string Name { get; set; }
       public int Age { get; set; }
   }    
   
   

2. Compile o projeto e verifique se não há erros.

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

   Three events have been published to the topic. Press any key to end the application.
   

   Importante

   Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure. Em casos raros, poderá levar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

4. No portal do Azure, siga estas etapas:

   1. Navegue até o namespace da sua Grade de Eventos.

   2. Na página Visão Geral, você verá o número de eventos enviados para o namespace no gráfico.

      

Efetuar pull de mensagens do tópico

Nessa seção, você criará um aplicativo de console do .NET que recebe mensagens do tópico.

Criar um projeto para receber os CloudEvents publicados

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

Adicionar os pacotes do NuGet ao projeto

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

2. Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.EventGrid. Escolha EventReceiver como o Projeto padrão, caso ainda não esteja definido.

   Install-Package Azure.Messaging.EventGrid -version 4.22.0-beta.1
   

   

Adicionar o código para receber eventos do tópico

Nessa seção, você adicionará o código para recuperar mensagens da fila.

1. Dentro da classe Program, adicione o seguinte código:

   Importante

   Substitua os valores do espaço reservado (<ENDPOINT> , <TOPIC-NAME>, <TOPIC-ACCESS-KEY>, <TOPIC-SUBSCRIPTION-NAME>) no trecho de código com o ponto de extremidade, nome, chave e nome da assinatura do seu tópico.

   using Azure;
   using Azure.Messaging;
   using Azure.Messaging.EventGrid.Namespaces;
   
   var topicEndpoint = "<TOPIC-ENDPOINT>"; // Should be in the form: https://namespace01.eastus-1.eventgrid.azure.net. 
   var topicKey = "<TOPIC-ACCESS-KEY>";
   var topicName = "<TOPIC-NAME>";
   var subscription = "<TOPIC-SUBSCRIPTION-NAME>";
   
   // Construct the client using an Endpoint for a namespace as well as the access key
   var client = new EventGridClient(new Uri(topicEndpoint), new AzureKeyCredential(topicKey));
   
   // Receive the published CloudEvents
   ReceiveResult result = await client.ReceiveCloudEventsAsync(topicName, subscription, 3);
   
   Console.WriteLine("Received Response");
   Console.WriteLine("-----------------");
   
   

2. Acrescente os seguintes métodos ao final da classe Program.

   // handle received messages. Define these variables on the top.
   
   var toRelease = new List<string>();
   var toAcknowledge = new List<string>();
   var toReject = new List<string>();
   
   // Iterate through the results and collect the lock tokens for events we want to release/acknowledge/result
   
   foreach (ReceiveDetails detail in result.Value)
   {
       CloudEvent @event = detail.Event;
       BrokerProperties brokerProperties = detail.BrokerProperties;
       Console.WriteLine(@event.Data.ToString());
   
       // The lock token is used to acknowledge, reject or release the event
       Console.WriteLine(brokerProperties.LockToken);
       Console.WriteLine();
   
       // If the event is from the "employee_source" and the name is "Bob", we are not able to acknowledge it yet, so we release it
       if (@event.Source == "employee_source" && @event.Data.ToObjectFromJson<TestModel>().Name == "Bob")
       {
           toRelease.Add(brokerProperties.LockToken);
       }
       // acknowledge other employee_source events
       else if (@event.Source == "employee_source")
       {
           toAcknowledge.Add(brokerProperties.LockToken);
       }
       // reject all other events
       else
       {
           toReject.Add(brokerProperties.LockToken);
       }
   }
   
   // Release/acknowledge/reject the events
   
   if (toRelease.Count > 0)
   {
       ReleaseResult releaseResult = await client.ReleaseCloudEventsAsync(topicName, subscription, new ReleaseOptions(toRelease));
   
       // Inspect the Release result
       Console.WriteLine($"Failed count for Release: {releaseResult.FailedLockTokens.Count}");
       foreach (FailedLockToken failedLockToken in releaseResult.FailedLockTokens)
       {
           Console.WriteLine($"Lock Token: {failedLockToken.LockToken}");
           Console.WriteLine($"Error Code: {failedLockToken.Error}");
           Console.WriteLine($"Error Description: {failedLockToken.ToString}");
       }
   
       Console.WriteLine($"Success count for Release: {releaseResult.SucceededLockTokens.Count}");
       foreach (string lockToken in releaseResult.SucceededLockTokens)
       {
           Console.WriteLine($"Lock Token: {lockToken}");
       }
       Console.WriteLine();
   }
   
   if (toAcknowledge.Count > 0)
   {
       AcknowledgeResult acknowledgeResult = await client.AcknowledgeCloudEventsAsync(topicName, subscription, new AcknowledgeOptions(toAcknowledge));
   
       // Inspect the Acknowledge result
       Console.WriteLine($"Failed count for Acknowledge: {acknowledgeResult.FailedLockTokens.Count}");
       foreach (FailedLockToken failedLockToken in acknowledgeResult.FailedLockTokens)
       {
           Console.WriteLine($"Lock Token: {failedLockToken.LockToken}");
           Console.WriteLine($"Error Code: {failedLockToken.Error}");
           Console.WriteLine($"Error Description: {failedLockToken.ToString}");
       }
   
       Console.WriteLine($"Success count for Acknowledge: {acknowledgeResult.SucceededLockTokens.Count}");
       foreach (string lockToken in acknowledgeResult.SucceededLockTokens)
       {
           Console.WriteLine($"Lock Token: {lockToken}");
       }
       Console.WriteLine();
   }
   
   if (toReject.Count > 0)
   {
       RejectResult rejectResult = await client.RejectCloudEventsAsync(topicName, subscription, new RejectOptions(toReject));
   
       // Inspect the Reject result
       Console.WriteLine($"Failed count for Reject: {rejectResult.FailedLockTokens.Count}");
       foreach (FailedLockToken failedLockToken in rejectResult.FailedLockTokens)
       {
           Console.WriteLine($"Lock Token: {failedLockToken.LockToken}");
           Console.WriteLine($"Error Code: {failedLockToken.Error}");
           Console.WriteLine($"Error Description: {failedLockToken.ToString}");
       }
   
       Console.WriteLine($"Success count for Reject: {rejectResult.SucceededLockTokens.Count}");
       foreach (string lockToken in rejectResult.SucceededLockTokens)
       {
           Console.WriteLine($"Lock Token: {lockToken}");
       }
       Console.WriteLine();
   }
   
   public class TestModel
   {
       public string Name { get; set; }
       public int Age { get; set; }
   }    
   

Limpar os recursos

Navegue até o namespace da sua Grade de Eventos no portal do Azure e selecione Excluir no portal do Azure para excluir o namespace da Grade de Eventos e o tópico incluído.

Tópicos relacionados

Confira API de referência do .NET.