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

Artigo
04/28/2023

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.

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 as APIs do Azure, você precisa obter suas credenciais do portal do Azure.

Copiar suas credenciais no Portal do Azure

Quando o aplicativo de exemplo faz uma solicitação para o Armazenamento do Azure, ele precisa ser autorizado. Para autenticar uma solicitação, adicione suas credenciais da conta de armazenamento ao aplicativo como uma cadeia de conexão. Para ver as credenciais da conta de armazenamento, siga estas etapas:

Entre no portal do Azure.
Localize sua cadeia de conexão.
No painel do menu da conta de armazenamento, em Segurança + rede, selecione Chaves de acesso. Aqui, você pode ver as chaves de acesso da conta, bem como a cadeia de conexão completa para cada chave.
No painel Chaves de acesso, selecione Mostrar chaves.
Na seção key1, localize o valor Cadeia de conexão. Selecione o ícone Copiar para a área de transferência para copiar a cadeia de conexão. Você adicionará o valor da cadeia de conexão a uma variável de ambiente na próxima seção.

Configurar a cadeia de conexão de armazenamento

Depois de copiar a cadeia de conexão, grave em uma nova variável de ambiente no computador local que executa o aplicativo. Para definir a variável de ambiente, abra uma janela de console e siga as instruções do seu sistema operacional. Substitua <yourconnectionstring> pela cadeia de conexão real.

Windows
Linux e macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Após adicionar a variável de ambiente no Windows, é necessário iniciar uma nova instância da janela de comando.

Reiniciar programas

Depois de adicionar a variável de ambiente, reinicie todos os programas em execução que precisarem ler a variável de ambiente. Por exemplo, reinicie seu ambiente ou editor de desenvolvimento antes de continuar.

Adicionar a cadeia de conexão ao aplicativo

Adicione a cadeia de conexão ao aplicativo para que ele possa acessar a conta de armazenamento.

Reverta para o Visual Studio Code.
No método Main, substitua o código Console.WriteLine("Hello, World"); pela linha a seguir que obtém a cadeia de conexão da variável de ambiente.
```
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");
```
Adicione o código a seguir a Main para criar um objeto queue, que posteriormente será passado para os métodos de envio e recebimento.
```
QueueClient queue = new QueueClient(connectionString, "mystoragequeue");
```
Salve o arquivo.

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.

static async Task Main(string[] args)
{
    string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

    QueueClient queue = new QueueClient(connectionString, "mystoragequeue");

    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;

namespace QueueApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

            QueueClient queue = new QueueClient(connectionString, "mystoragequeue");

            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