Tutorial: Trabalhar com filas do Armazenamento de Filas do Azure no .NET

Artigo
08/13/2024

O Armazenamento de Filas do Azure implementa filas baseadas em nuvem para permitir comunicação entre os componentes de um aplicativo distribuído. Cada fila mantém uma lista de mensagens que podem ser adicionadas por um componente emissor e processadas por um componente receptor. Com uma fila, o aplicativo pode ser dimensionado imediatamente para atender à demanda. Este artigo mostra as etapas básicas para trabalhar com uma fila do Armazenamento de Filas do Azure.

Neste tutorial, você aprenderá como:

Criar uma conta de Armazenamento do Azure
Criar o aplicativo
Adicionar as bibliotecas de clientes do Azure
Adicionar suporte para código assíncrono
Criar uma fila
Inserir mensagens em uma fila
Remover mensagens da fila
Excluir uma fila vazia
Verificar argumentos de linha de comando
Compilar e executar o aplicativo

Pré-requisitos

Obtenha a cópia gratuita do editor Visual Studio Code multiplataforma.
Baixe e instale o SDK do .NET Core versão 3.1 ou posterior.
Caso não tenha uma assinatura atual do Azure, crie uma conta gratuita antes de começar.

Criar uma conta do Armazenamento do Azure

Primeiro, crie uma conta do Armazenamento do Microsoft Azure.

Para obter um guia passo a passo sobre como criar uma conta de armazenamento, confira Criar uma conta de armazenamento. Essa é uma etapa separada que você executa depois de criar uma conta gratuita do Azure nos pré-requisitos.
Verifique se sua conta de usuário recebeu a função Colaborador de Dados da Fila de Armazenamento, com escopo para a conta de armazenamento, grupo de recursos pai ou assinatura. Consulte Autenticar no Azure.

Criar o aplicativo

Crie um aplicativo .NET Core nomeado QueueApp. Para simplificar, esse aplicativo enviará e receberá mensagens através da fila.

Em uma janela do console (como cmd, PowerShell ou CLI do Azure), use o comando dotnet new para criar um aplicativo do console com o nome QueueApp. Esse comando cria um projeto simples em C# do tipo "Olá, Mundo" com um arquivo de origem único chamado Program.cs.
```
dotnet new console -n QueueApp
```

Alterne para a pasta QueueApp recém-criada e crie o aplicativo para verificar se está tudo bem.

cd QueueApp

dotnet build

Você verá resultados semelhantes à seguinte saída:

C:\Tutorials>dotnet new console -n QueueApp
The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on QueueApp\QueueApp.csproj...
  Restore completed in 155.63 ms for C:\Tutorials\QueueApp\QueueApp.csproj.

Restore succeeded.

C:\Tutorials>cd QueueApp

C:\Tutorials\QueueApp>dotnet build
Microsoft (R) Build Engine version 16.0.450+ga8dc7f1d34 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 40.87 ms for C:\Tutorials\QueueApp\QueueApp.csproj.
  QueueApp -> C:\Tutorials\QueueApp\bin\Debug\netcoreapp3.1\QueueApp.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:02.40

C:\Tutorials\QueueApp>_

Adicionar as bibliotecas de clientes do Azure

Adicione as bibliotecas de clientes do Armazenamento do Azure ao projeto usando o comando dotnet add package.

Execute o comando a seguir na pasta do projeto na janela do console.
```
dotnet add package Azure.Storage.Queues
```

Adicionar instruções using

Na linha de comando no diretório do projeto, digite code . para abrir o Visual Studio Code no diretório atual. Mantenha a janela da linha de comando aberta. Haverá mais comandos para executar posteriormente. Se você receber uma solicitação para adicionar ativos C# necessários para build e depuração, clique no botão Sim.
Abra o arquivo de origem Program.cs e adicione os namespaces a seguir, logo após a instrução using System;. Esse aplicativo usa tipos desses namespaces para conectar-se ao Armazenamento do Azure e trabalhar com filas.
```
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
```
Salve o arquivo Program.cs.

Adicionar suporte para código assíncrono

Como o aplicativo usa recursos de nuvem, o código executa assincronamente.

Atualize o método Main para ser executado de maneira assíncrona. Substitua void por um valor retornado da async Task.
```
static async Task Main(string[] args)
```
Salve o arquivo Program.cs.

Criar uma fila

Antes de fazer chamadas para APIs do Azure, você deve verificar se está autenticado com a mesma conta do Microsoft Entra à qual atribuiu a função. Depois de autenticado, você pode criar e autorizar um objeto QueueClient usando DefaultAzureCredential para acessar dados da fila na conta de armazenamento. DefaultAzureCredential descobre e usa automaticamente a conta com que você usou na etapa anterior. Para saber como entrar e criar um objeto QueueClient, consulte Autorizar o acesso e criar um objeto cliente.

Inserir mensagens na fila

Criar um novo método para enviar uma mensagem na fila.

Adicione o método InsertMessageAsync a seguir à sua classe Program.

Esse método é passado por uma referência de fila. Ao chamar CreateIfNotExistsAsync, uma fila será criada, se ela ainda não existir. Em seguida, ele adiciona o newMessage à fila chamando SendMessageAsync.
```
static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
{
    if (null != await theQueue.CreateIfNotExistsAsync())
    {
        Console.WriteLine("The queue was created.");
    }

    await theQueue.SendMessageAsync(newMessage);
}
```
Opcional: Por padrão, a vida útil máxima de uma mensagem é definida como sete dias. Você pode especificar qualquer número positivo para a vida útil da mensagem. O snippet de código a seguir adiciona uma mensagem que nunca expira.

Para adicionar uma mensagem que não expira, use Timespan.FromSeconds(-1) na chamada para SendMessageAsync.
```
await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);
```
Salve o arquivo.

Uma mensagem da fila deve estar em um formato compatível com uma solicitação XML usando a codificação UTF-8. Uma mensagem pode ter tamanho de até 64 KB. Se uma mensagem contém dados binários, codifique a mensagem como Base64.

Remover mensagens da fila

Criar um método para recuperar uma mensagem da fila. Quando a mensagem for recebida com êxito, será importante excluí-la da fila para que a mensagem não seja processada mais de uma vez.

Adicione um novo método chamado RetrieveNextMessageAsync à sua classe Program.

Esse método recebe uma mensagem da fila ao chamar ReceiveMessagesAsync, passando 1 no primeiro parâmetro para recuperar apenas a próxima mensagem na fila. Após receber a mensagem, exclua-a da fila, chamando DeleteMessageAsync.

Quando uma mensagem é enviada para a fila com uma versão do SDK anterior à v12, ela é codificada automaticamente em Base64. Da v12 em diante, essa funcionalidade foi removida. Quando você recupera uma mensagem usando o SDK v12, ela não é automaticamente decodificada em Base64. Você precisa realizar explicitamente a decodificação em Base64 do conteúdo por conta própria.
```
static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
{
    if (await theQueue.ExistsAsync())
    {
        QueueProperties properties = await theQueue.GetPropertiesAsync();

        if (properties.ApproximateMessagesCount > 0)
        {
            QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
            string theMessage = retrievedMessage[0].Body.ToString();
            await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
            return theMessage;
        }

        return null;
    }

    return null;
}
```
Salve o arquivo.

Excluir uma fila vazia

É uma melhor prática no final de um projeto identificar se os recursos criados ainda serão necessários. Recursos deixados em execução podem custar dinheiro. Se a fila existir, mas estiver vazia, pergunte ao usuário se ele deseja excluí-la.

Expanda o método RetrieveNextMessageAsync para incluir uma solicitação e excluir a fila vazia.

static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
{
    if (await theQueue.ExistsAsync())
    {
        QueueProperties properties = await theQueue.GetPropertiesAsync();

        if (properties.ApproximateMessagesCount > 0)
        {
            QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
            string theMessage = retrievedMessage[0].Body.ToString();
            await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
            return theMessage;
        }
        else
        {
            Console.Write("The queue is empty. Attempt to delete it? (Y/N) ");
            string response = Console.ReadLine();

            if (response.ToUpper() == "Y")
            {
                await theQueue.DeleteIfExistsAsync();
                return "The queue was deleted.";
            }
            else
            {
                return "The queue was not deleted.";
            }
        }
    }
    else
    {
        return "The queue does not exist. Add a message to the command line to create the queue and store the message.";
    }
}

Salve o arquivo.

Verificar argumentos de linha de comando

Se houver argumentos de linha de comando inseridos no aplicativo, considere que esses argumentos são uma mensagem a ser adicionada à fila. Junte os argumentos para criar uma cadeia de caracteres. Adicione essa cadeia de caracteres à fila de mensagens, chamando o método InsertMessageAsync adicionado anteriormente.

Se não houver argumentos de linha de comando, tente realizar uma operação de recuperação. Chame o método RetrieveNextMessageAsync para recuperar a próxima mensagem na fila.

Por fim, aguarde a entrada do usuário antes de sair, chamando Console.ReadLine.

Expanda o método Main para verificar os argumentos de linha de comandos e aguarde a entrada do usuário. No snippet de código abaixo, substitua o espaço reservado {storageAccountName} pelo nome da sua conta de armazenamento.

static async Task Main(string[] args)
{
   QueueClient queue = new QueueClient(
      new Uri($"https://{storageAccountName}.queue.core.windows.net/mystoragequeue"),
      new DefaultAzureCredential());

   if (args.Length > 0)
   {
      string value = String.Join(" ", args);
      await InsertMessageAsync(queue, value);
      Console.WriteLine($"Sent: {value}");
   }
   else
   {
      string value = await RetrieveNextMessageAsync(queue);
      Console.WriteLine($"Received: {value}");
   }

   Console.Write("Press Enter...");
   Console.ReadLine();
}

Salve o arquivo.

Código completo

Aqui é apresentada a lista completa de códigos para este projeto.

using System;
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using Azure.Identity;

namespace QueueApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            QueueClient queue = new QueueClient(
               new Uri($"https://{storageAccountName}.queue.core.windows.net/mystoragequeue"),
               new DefaultAzureCredential());

            if (args.Length > 0)
            {
                string value = String.Join(" ", args);
                await InsertMessageAsync(queue, value);
                Console.WriteLine($"Sent: {value}");
            }
            else
            {
                string value = await RetrieveNextMessageAsync(queue);
                Console.WriteLine($"Received: {value}");
            }

            Console.Write("Press Enter...");
            Console.ReadLine();
        }

        static async Task InsertMessageAsync(QueueClient theQueue, string newMessage)
        {
            if (null != await theQueue.CreateIfNotExistsAsync())
            {
                Console.WriteLine("The queue was created.");
            }

            await theQueue.SendMessageAsync(newMessage);
        }

        static async Task<string> RetrieveNextMessageAsync(QueueClient theQueue)
        {
            if (await theQueue.ExistsAsync())
            {
                QueueProperties properties = await theQueue.GetPropertiesAsync();

                if (properties.ApproximateMessagesCount > 0)
                {
                    QueueMessage[] retrievedMessage = await theQueue.ReceiveMessagesAsync(1);
                    string theMessage = retrievedMessage[0].Body.ToString();
                    await theQueue.DeleteMessageAsync(retrievedMessage[0].MessageId, retrievedMessage[0].PopReceipt);
                    return theMessage;
                }
                else
                {
                    Console.Write("The queue is empty. Attempt to delete it? (Y/N) ");
                    string response = Console.ReadLine();

                    if (response.ToUpper() == "Y")
                    {
                        await theQueue.DeleteIfExistsAsync();
                        return "The queue was deleted.";
                    }
                    else
                    {
                        return "The queue was not deleted.";
                    }
                }
            }
            else
            {
                return "The queue does not exist. Add a message to the command line to create the queue and store the message.";
            }
        }
    }
}

Compilar e executar o aplicativo

A partir da linha de comando no diretório do projeto, execute o seguinte comando dotnet para compilar o projeto.
```
dotnet build
```

Depois que o projeto for compilado com êxito, execute o seguinte comando para adicionar a primeira mensagem à fila.

dotnet run First queue message

Você deverá ver este resultado:

C:\Tutorials\QueueApp>dotnet run First queue message
The queue was created.
Sent: First queue message
Press Enter..._

Execute o aplicativo sem argumentos de linha de comando para receber e remover a primeira mensagem na fila.
```
dotnet run
```

Continue a executar o aplicativo até que todas as mensagens sejam removidas. Se executá-lo mais uma vez, você receberá uma mensagem informando que a fila está vazia e uma solicitação para excluir a fila.

C:\Tutorials\QueueApp>dotnet run First queue message
The queue was created.
Sent: First queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run Second queue message
Sent: Second queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run Third queue message
Sent: Third queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
Received: First queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
Received: Second queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
Received: Third queue message
Press Enter...

C:\Tutorials\QueueApp>dotnet run
The queue is empty. Attempt to delete it? (Y/N) Y
Received: The queue was deleted.
Press Enter...

C:\Tutorials\QueueApp>_

Próximas etapas

Neste tutorial, você aprendeu a:

Criar uma fila
Adicionar e remover mensagens de uma fila
Excluir uma fila do Armazenamento de Filas do Azure

Para obter mais informações, confira os guias de início rápido do Armazenamento de Filas do Azure.

Início rápido de Filas para o portal

Para obter exemplos de código relacionados usando SDKs preteridos do .NET versão 11.x, confira os Exemplos de código usando o .NET versão 11.x.

Compartilhar via