Partilhar via

Guia de início rápido: enviar e receber mensagens de um tópico de namespace da Grade de Eventos do Azure (.NET)

  • Artigo

Neste início rápido, você executa as seguintes etapas:

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

Nota

Este 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 de Grade de Eventos e, em seguida, recebê-las. Para obter uma visão geral da biblioteca de cliente .NET, consulte Biblioteca de cliente da Grade de Eventos do Azure para .NET. Para obter mais exemplos, consulte Exemplos de Grade de Eventos .NET no GitHub.

Pré-requisitos

Se você for novo no serviço, consulte Visão geral da grade de eventos antes de fazer este início rápido.

  • Subscrição do Azure. Para usar os serviços do Azure, incluindo a Grade de Eventos do Azure, você precisa de uma assinatura. Se não tiver uma conta existente do Azure, pode inscrever-se para uma avaliação gratuita.
  • Visual Studio 2022. O aplicativo de exemplo faz uso de novos recursos que foram introduzidos no C# 10. Para usar a sintaxe mais recente, recomendamos que você instale o .NET 6.0 ou superior e defina a versão de idioma como latest. Se você estiver usando o Visual Studio, as versões anteriores ao Visual Studio 2022 não são compatíveis com as ferramentas necessárias para criar projetos C# 10.

Criar um espaço de nomes 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ê pode agrupar agora recursos relacionados e gerenciá-los como uma única unidade em 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 espaço de nomes:

  1. Inicie sessão no portal do Azure.

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

    Captura de ecrã a mostrar Espaços de Nomes da Grelha de Eventos nos resultados da pesquisa.

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

    Captura de ecrã a mostrar a página Espaços de Nomes da Grelha de Eventos com o botão Criar na barra de ferramentas selecionado.

  4. Na página Noções básicas, siga estas etapas.

    1. Selecione a assinatura do Azure na qual você deseja criar o namespace.

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

    3. Insira um nome para o namespace.

    4. Selecione a região ou o local onde deseja criar o namespace.

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

      Captura de tela mostrando a guia Noções básicas da página Criar namespace.

  5. No separador Rever + criar, reveja as suas definições e selecione Criar.

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

Criar um tópico de namespace

  1. Se você não estiver na página Namespace da Grade de Eventos, siga as etapas de criação, exibição e gerenciamento de namespaces para exibir o namespace que deseja 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 à esquerda.

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

    Captura de tela mostrando a criação do tópico do namespace Event Grid.

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

    Captura de tela mostrando noções básicas de criação de tópicos do namespace Event Grid.

Criar uma subscrição de evento

  1. Se você estiver na página Tópicos do namespace Grade de Eventos no portal do Azure, selecione seu tópico na lista de tópicos. Se você estiver na página Tópicos, siga as instruções de criar, exibir e gerenciar tópicos de namespace para identificar o tópico que deseja usar para criar a assinatura do evento.

  2. Na página Event Gird Namespace Topic, selecione a opção Assinaturas na seção Entidades no menu à esquerda.

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

    Captura de ecrã a mostrar a criação da subscrição de eventos da Grelha de Eventos.

  4. No separador Noções básicas, escreva o nome do tópico que pretende criar e, em seguida, selecione Seguinte: Filtros na parte inferior da página.

    Captura de ecrã a mostrar a subscrição de eventos da Grelha de Eventos que cria noções básicas.

  5. Na guia Filtros, adicione os nomes dos tipos de evento 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.

    Captura de ecrã a mostrar a subscrição de eventos da Grelha de Eventos criar filtros.

  6. Na guia Recursos adicionais, você pode especificar a retenção de eventos, a contagem máxima de entrega, a duração do bloqueio e as configurações de letras mortas.

    Captura de ecrã a mostrar a subscrição de eventos da Grelha de Eventos para criar funcionalidades adicionais.

  7. Selecione Criar para criar a assinatura do evento.

Autenticar o aplicativo no Azure

Este início rápido mostra maneiras de se conectar à Grade de Eventos do Azure: cadeia de conexão.

Este documento mostra como usar uma cadeia de conexão para se conectar a um namespace de Grade de Eventos. Se você for novo no Azure, poderá achar a opção de cadeia de conexão mais fácil de seguir.

A criação de um novo namespace de Grade de Eventos gera automaticamente uma chave primária e secundária inicial que concedem controle total sobre todos os aspetos do namespace ou tópicos.

Um cliente pode usar a cadeia de conexão para se conectar ao namespace Grade de Eventos. Para copiar as chaves de acesso para o tópico do namespace, siga estas 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 Teclas de acesso, selecione o botão de cópia ao lado de Tecla 1 ou Tecla 2, para copiar as teclas de acesso para a área de transferência para uso posterior. Cole este valor no Bloco de Notas ou noutra localização temporária.

Iniciar o Visual Studio

Você pode autorizar o acesso ao namespace Event Grid 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

Esta seção mostra como criar um aplicativo de console .NET para enviar mensagens para um tópico de grade de eventos.

Criar uma aplicação de consola

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

  2. Na caixa de diálogo Criar um novo projeto, execute as seguintes etapas: 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 Console para o tipo do aplicativo.

    3. Selecione Aplicativo de console na lista de resultados.

    4. Em seguida, selecione Seguinte.

      Captura de tela mostrando a caixa de diálogo Criar um novo projeto com C# e Console selecionados.

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

    Captura de tela mostrando os nomes da solução e do projeto na caixa de diálogo Configurar seu novo projeto.

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

Adicionar os pacotes NuGet ao projeto

  1. Selecione Ferramentas>NuGet Package Manager Package Manager>Console 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 código para enviar evento ao tópico namespace

  1. Substitua o conteúdo do pelo código a Program.cs seguir. As etapas importantes são delineadas, com informações adicionais nos comentários do código.

    Importante

    Atualize os valores de espaço reservado (<ENDPOINT> , <TOPIC-NAME>, <TOPIC-ACCESS-KEY>, <TOPIC-SUBSCRIPTION-NAME>) no trecho de código com seu ponto de extremidade de tópico, nome do tópico, chave do tópico, nome da assinatura do 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. Crie o projeto e certifique-se de que 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 que a atribuição de função se propague no Azure. Em casos raros, pode demorar até oito minutos. Se você receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos e tente novamente.

  4. No portal do Azure, siga estas etapas:

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

    2. Na página Visão geral, você vê o número de eventos postados no namespace no gráfico.

      Captura de ecrã a mostrar a página Espaço de Nomes da Grelha de Eventos no portal do Azure.

Extrair mensagens do tópico

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

Criar um projeto para receber os CloudEvents publicados

  1. Na janela 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 selecione Avançar.
  3. Digite EventReceiver para o nome do projeto e selecione Criar.
  4. Na janela 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 NuGet ao projeto

  1. Selecione Ferramentas>NuGet Package Manager Package Manager>Console no menu.

  2. Execute o seguinte comando para instalar o pacote NuGet Azure.Messaging.EventGrid. Selecione EventReceiver para o projeto Default se ainda não estiver definido.

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

    Captura de tela mostrando o projeto EventReceiver selecionado no Console do Gerenciador de Pacotes.

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

Nesta seção, você adiciona código para recuperar mensagens da fila.

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

    Importante

    Atualize os valores de espaço reservado (<ENDPOINT> , <TOPIC-NAME>, <TOPIC-ACCESS-KEY>, <TOPIC-SUBSCRIPTION-NAME>) no trecho de código com seu ponto de extremidade de tópico, nome do tópico, chave do tópico, nome da assinatura do 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. Anexe os seguintes métodos ao final da Program classe.

    // 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; }
}

Clean up resources (Limpar recursos)

Navegue até o namespace da 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 nele.

Consulte Referência da API do .NET.