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

Artigo
04/28/2023

O Armazenamento de Filas do Azure implementa filas baseadas na cloud para ativar a comunicação entre componentes de uma aplicação distribuída. Cada fila mantém uma lista de mensagens que podem ser adicionadas por um componente do remetente e processadas por um componente recetor. Com uma fila, a sua aplicação pode ser dimensionada imediatamente para satisfazer a procura. Este artigo mostra os passos básicos para trabalhar com uma fila de Armazenamento de Filas do Azure.

Neste tutorial, ficará a saber como:

Criar uma conta de Armazenamento do Azure
Criar a aplicação
Adicionar as bibliotecas de cliente do Azure
Adicionar suporte para código assíncrono
Criar uma fila
Inserir mensagens numa fila
Desativar mensagens
Eliminar uma fila vazia
Procurar argumentos da linha de comandos
Compilar e executar a aplicação

Pré-requisitos

Obtenha a sua cópia gratuita do editor do Visual Studio Code entre plataformas.
Transfira e instale a versão 3.1 ou posterior do SDK .NET Core .
Se não tiver uma subscrição atual do Azure, crie uma conta gratuita antes de começar.

Criar uma conta de Armazenamento do Azure

Primeiro, crie uma conta de Armazenamento do Azure. Para obter um guia passo a passo para criar uma conta de armazenamento, veja Criar uma conta de armazenamento. Este é um passo separado que efetua após criar uma conta gratuita do Azure nos pré-requisitos.

Criar a aplicação

Crie uma aplicação .NET Core com o nome QueueApp. Para simplificar, esta aplicação irá enviar e receber mensagens através da fila.

Numa janela da consola (como cmd, PowerShell ou CLI do Azure), utilize o dotnet new comando para criar uma nova aplicação de consola com o nome QueueApp. Este comando cria um projeto C# "hello world" simples com um único ficheiro de origem com o nome Program.cs.
```
dotnet new console -n QueueApp
```

Mude para pasta QueueApp acabada de criar e compile a aplicação, para confirmar que está tudo bem.

cd QueueApp

dotnet build

Deverá ver resultados semelhantes ao seguinte resultado:

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 cliente do Azure

Adicione as bibliotecas de cliente do Armazenamento do Azure ao projeto com o dotnet add package comando .

Execute o seguinte comando a partir da pasta do projeto na janela da consola.
```
dotnet add package Azure.Storage.Queues
```

Adicionar instruções de utilização

Na linha de comandos no diretório do projeto, escreva code . para abrir o Visual Studio Code no diretório atual. Mantenha a janela da linha de comandos aberta. Haverá mais comandos para executar mais tarde. Se lhe for pedido para adicionar recursos C# necessários para criar e depurar, clique no botão Sim .
Abra o ficheiro de origem Program.cs e adicione os seguintes espaços de nomes logo a seguir à using System; instrução. Esta aplicação utiliza tipos destes espaços de nomes para ligar ao Armazenamento do Azure e trabalhar com filas.
```
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
```
Guarde o ficheiro Program.cs.

Adicionar suporte para código assíncrono

Uma vez que a aplicação utiliza recursos da cloud, o código é executado de forma assíncrona.

Atualize o Main método para ser executado de forma assíncrona. Substitua por void um async Task valor devolvido.
```
static async Task Main(string[] args)
```
Guarde o ficheiro Program.cs.

Criar uma fila

Antes de efetuar chamadas para as APIs do Azure, tem de obter as suas credenciais a partir do portal do Azure.

Copiar as credenciais do Portal do Azure

Quando a aplicação de exemplo faz um pedido ao Armazenamento do Azure, este tem de ser autorizado. Para autorizar um pedido, adicione as credenciais da conta de armazenamento à aplicação como uma cadeia de ligação. Para ver as credenciais da conta de armazenamento, siga estes passos:

Inicie sessão no portal do Azure.
Localize a sua conta de armazenamento.
No painel de menus da conta de armazenamento, em Segurança + rede, selecione Chaves de acesso. Aqui, pode ver as chaves de acesso da conta e a cadeia de ligação completa para cada chave.
No painel Chaves de acesso , selecione Mostrar chaves.
Na secção key1 , localize o valor cadeia de ligação . Selecione o ícone Copiar para a área de transferência para copiar a cadeia de ligação. Irá adicionar o valor da cadeia de ligação a uma variável de ambiente na secção seguinte.

Configurar a cadeia de ligação de armazenamento

Depois de copiar a cadeia de ligação, escreva-a numa nova variável de ambiente no computador local que executa a aplicação. Para definir a variável de ambiente, abra uma janela da consola e siga as instruções relevantes para o seu sistema operativo. Substitua pela <yourconnectionstring> cadeia de ligação real.

Windows
Linux e macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Depois de adicionar a variável de ambiente no Windows, tem de iniciar uma nova instância da janela de comandos.

Reiniciar programas

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

Adicionar a cadeia de ligação à aplicação

Adicione a cadeia de ligação à aplicação para que possa aceder à conta de armazenamento.

Regresse ao Visual Studio Code.
Main No método, substitua o Console.WriteLine("Hello, World"); código pela seguinte linha que obtém a cadeia de ligação da variável de ambiente.
```
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");
```
Adicione o seguinte código para Main criar um objeto de fila, que é posteriormente transmitido para os métodos de envio e receção.
```
QueueClient queue = new QueueClient(connectionString, "mystoragequeue");
```
Guarde o ficheiro.

Inserir mensagens na fila

Crie um novo método para enviar uma mensagem para a fila.

Adicione o seguinte InsertMessageAsync método à sua Program classe.

Este método é transmitido como uma referência de fila. É criada uma nova fila, se ainda não existir, ao chamar CreateIfNotExistsAsync. Em seguida, adiciona a newMessage fila ao chamar 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 predefinição, o tempo máximo para uma mensagem está definido como sete dias. Pode especificar qualquer número positivo para a mensagem time-to-live. O fragmento de código seguinte adiciona uma mensagem que nunca expira.

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

Uma mensagem de fila tem de estar num formato compatível com um pedido XML com a codificação UTF-8. Uma mensagem pode ter até 64 KB de tamanho. Se uma mensagem contiver dados binários, codifigue a mensagem com base64 .

Desativar mensagens

Crie um novo método para obter uma mensagem da fila. Assim que a mensagem for recebida com êxito, é importante eliminá-la da fila para que não seja processada mais do que uma vez.

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

Este método recebe uma mensagem da fila ao chamar , transmitindo ReceiveMessagesAsync1 o primeiro parâmetro para obter apenas a mensagem seguinte na fila. Depois de a mensagem ser recebida, elimine-a da fila ao chamar DeleteMessageAsync.

Quando uma mensagem é enviada para a fila com uma versão do SDK anterior à v12, é automaticamente codificada em Base64. A partir da v12, essa funcionalidade foi removida. Quando obtém uma mensagem com o SDK v12, esta não é automaticamente descodificada por Base64. Tem de descodificar explicitamente o conteúdo por base64.
```
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;
}
```
Guarde o ficheiro.

Eliminar uma fila vazia

É uma melhor prática no final de um projeto identificar se ainda precisa dos recursos que criou. Os recursos que deixar em execução podem custar-lhe dinheiro. Se a fila existir, mas estiver vazia, pergunte ao utilizador se pretende eliminá-la.

Expanda o RetrieveNextMessageAsync método para incluir um pedido para eliminar 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.";
    }
}

Guarde o ficheiro.

Procurar argumentos da linha de comandos

Se existirem argumentos de linha de comandos transmitidos para a aplicação, suponha que é uma mensagem a ser adicionada à fila. Junte os argumentos para criar uma cadeia. Adicione esta cadeia à fila de mensagens ao chamar o InsertMessageAsync método que adicionámos anteriormente.

Se não existirem argumentos de linha de comandos, tente obter uma operação. Chame o RetrieveNextMessageAsync método para obter a mensagem seguinte na fila.

Por fim, aguarde pela entrada do utilizador antes de sair ao chamar Console.ReadLine.

Expanda o Main método para verificar a existência de argumentos da linha de comandos e aguarde pela entrada do utilizador.

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();
}

Guarde o ficheiro.

Código completo

Eis a listagem de código completa 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 a aplicação

Na linha de comandos no diretório do projeto, execute o seguinte comando dotnet para criar o projeto.
```
dotnet build
```

Depois de o projeto ser criado com êxito, execute o seguinte comando para adicionar a primeira mensagem à fila.

dotnet run First queue message

Deverá ver este resultado:

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

Execute a aplicação sem argumentos de linha de comandos para receber e remover a primeira mensagem na fila.
```
dotnet run
```

Continue a executar a aplicação até que todas as mensagens sejam removidas. Se a executar mais uma vez, receberá uma mensagem a indicar que a fila está vazia e um pedido para eliminar 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>_

Passos seguintes

Neste tutorial, ficou a saber como:

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

Consulte os inícios rápidos do Armazenamento de Filas do Azure para obter mais informações.

Início rápido das filas para o portal

Para exemplos de código relacionados com SDKs .NET preteridos versão 11.x, veja Exemplos de código com a versão 11.x do .NET.