Compartilhar via

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

  • Artigo

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.

    Captura de tela mostrando namespaces da Grade de Eventos nos resultados da pesquisa.

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

    Captura de tela mostrando a página Namespaces da Grade de Eventos com o botão Criar na barra de ferramentas selecionada.

  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.

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

  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 você 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ê 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 Agente de eventos no menu à esquerda.

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

    Captura de tela que mostra a criação de tópicos de namespace da Grade de Eventos.

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

    Captura de tela que mostra as informações básicas da criação de tópicos de namespace da Grade de Eventos.

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.

    Captura de tela mostrando a página de tópicos da Grade de Eventos com um tópico selecionado.

  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.

    Captura de tela que mostra a criação da assinatura de evento da Grade de Eventos.

  4. Na guia Básico, siga estas etapas:

    1. Insira um nome para a assinatura que você deseja criar

    2. Confirme se o esquema de entrega está definido como Eventos de Nuvem v1.0.

    3. Confirme se o modo de entrega está definido como Fila (modo de pull).

    4. Selecione Próximo: Filtros na parte inferior da página.

      Captura de tela que mostra as informações básicas da criação da assinatura de evento da Grade de Eventos.

  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.

    Captura de tela que mostra os filtros de criação da assinatura de evento da Grade de Eventos.

  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.

    Captura de tela que mostra os recursos adicionais de criação da assinatura de evento da Grade de Eventos.

  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. Esta seção mostra como usar uma cadeia de conexão para se conectar a um namespace da Grade de Eventos. Se você ainda estiver conhecendo o Azure, a opção de cadeia de conexão é mais fácil de seguir. 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.

    Captura de tela que mostra a chave de acesso de um tópico da Grade de Eventos.

Iniciar o Visual Studio

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.

      Captura de tela mostrando a caixa de diálogo

  3. Insira EventSender como o nome do projeto, EventGridQuickStart como 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

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

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

    Atualize os valores do espaço reservado (<NAMESPACE-ENDPOINT>, <TOPIC-NAME>, <TOPIC-ACCESS-KEY>, <TOPIC-SUBSCRIPTION-NAME>) no snippet de código com o ponto de extremidade do namespace, o nome e a chave do tópico.

    using Azure.Messaging;
using Azure;
using Azure.Messaging.EventGrid.Namespaces;


// TODO: Replace the following placeholders with appropriate values

// Endpoint of the namespace that you can find on the Overview page for your Event Grid namespace. Prefix it with https://.
// Should be in the form: https://namespace01.eastus-1.eventgrid.azure.net. 
var namespaceEndpoint = "<NAMESPACE-ENDPOINT>";

// Name of the topic in the namespace
var topicName = "<TOPIC-NAME>";

// Access key for the topic
var topicKey = "<TOPIC-ACCESS-KEY>";

// Construct the client using an Endpoint for a namespace as well as the access key
var client = new EventGridSenderClient(new Uri(namespaceEndpoint), topicName, 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.SendAsync(ev);

// Publish a batch of CloudEvents.

await client.SendAsync(
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.

      Captura de tela mostrando a página do Namespace da Grade de Eventos no portal do Azure.

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

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

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

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

    using Azure;
using Azure.Messaging;
using Azure.Messaging.EventGrid.Namespaces;

// TODO: Replace the following placeholders with appropriate values

// Endpoint of the namespace that you can find on the Overview page for your Event Grid namespace
// Example: https://namespace01.eastus-1.eventgrid.azure.net. 
var namespaceEndpoint = "<NAMESPACE-ENDPOINT>"; // Should be in the form: https://namespace01.eastus-1.eventgrid.azure.net. 

// Name of the topic in the namespace
var topicName = "<TOPIC-NAME>";

// Access key for the topic
var topicKey = "<TOPIC-ACCESS-KEY>";

// Name of the subscription to the topic
var subscriptionName = "<TOPIC-SUBSCRIPTION-NAME>";

// Maximum number of events you want to receive
const short MaxEventCount = 3;

// Construct the client using an Endpoint for a namespace as well as the access key
var client = new EventGridReceiverClient(new Uri(namespaceEndpoint), topicName, subscriptionName, new AzureKeyCredential(topicKey));

// Receive the published CloudEvents. 
ReceiveResult result = await client.ReceiveAsync(MaxEventCount);

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.Details)
{
    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.ReleaseAsync(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.AcknowledgeAsync(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.RejectAsync(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; }
}

  3. Na janela Gerenciador de Soluções, clique com o botão direito do mouse no projeto EventReceiver e selecione Definir como um projeto de Inicialização.

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

  5. Execute o aplicativo EventReceiver e confirme que você vê três eventos na janela de saída.

    Captura de tela mostrando a saída do aplicativo Receiver.

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.

Confira API de referência do .NET.