Tutorial: Trabalhar com filas de armazenamento de filas do Azure no .NET

Artigo
08/08/2024

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

Neste tutorial, irá aprender a:

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 em uma fila
Retirar mensagens da fila
Excluir uma fila vazia
Verificar se há argumentos de linha de comando
Compilar e executar a aplicação

Pré-requisitos

Obtenha sua cópia gratuita do editor de código multiplataforma do Visual Studio.
Baixe e instale o SDK do .NET Core versão 3.1 ou posterior.
Se você não tiver uma assinatura 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, consulte Criar uma conta de armazenamento. Esta é uma etapa separada que você executa depois de criar uma conta gratuita do Azure nos pré-requisitos.
Verifique se a sua conta de usuário recebeu a função de 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 a aplicação

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

Em uma janela de console (como cmd, PowerShell ou CLI do Azure), use o dotnet new comando para criar um novo aplicativo de console com o nome QueueApp. Este comando cria um projeto C# simples "hello world" com um único arquivo de origem chamado 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

Você deve 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 cliente do Azure

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

Execute o seguinte comando 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 mais tarde. Se você for solicitado a adicionar ativos C# necessários para criar e depurar, clique no botão Sim .
Abra o Program.cs arquivo de origem e adicione os namespaces a seguir logo após a using System; instrução. Este aplicativo usa tipos desses namespaces para se conectar 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

Como o aplicativo usa recursos de nuvem, o código é executado de forma assíncrona.

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

Criar uma fila

Antes de fazer chamadas para APIs do Azure, você deve certificar-se de que está autenticado com a mesma conta do Microsoft Entra à qual atribuiu a função. Depois de autenticado, você pode criar e autorizar um QueueClient objeto usando DefaultAzureCredential para acessar dados de fila na conta de armazenamento. DefaultAzureCredential Descobre e utiliza automaticamente a conta em que iniciou sessão. Para saber como entrar e, em seguida, criar um QueueClient objeto, consulte Autorizar acesso e criar um objeto cliente.

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 é passado uma referência de fila. Uma nova fila é criada, se ainda não existir, chamando CreateIfNotExistsAsync. 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, o tempo máximo de vida útil de uma mensagem é definido como sete dias. Você pode especificar qualquer número positivo para o tempo de vida útil da mensagem. O trecho de código a seguir adiciona uma mensagem que nunca expira.

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

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

Retirar mensagens da fila

Crie um novo método para recuperar uma mensagem da fila. Depois que a mensagem for recebida com sucesso, é importante excluí-la da fila para que não seja processada mais de uma vez.

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

Este método recebe uma mensagem da fila chamando ReceiveMessagesAsync, passando 1 o primeiro parâmetro para recuperar apenas a próxima mensagem na fila. Depois que a mensagem for recebida, exclua-a da fila chamando DeleteMessageAsync.

Quando uma mensagem é enviada para a fila com uma versão do SDK anterior à v12, ela é automaticamente codificada em Base64. A partir da v12, essa funcionalidade foi removida. Quando você recupera uma mensagem usando o SDK v12, ela não é automaticamente decodificada em Base64. Você deve explicitamente Base64-decodificar o 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;
}
```
Guarde o ficheiro.

Excluir uma fila vazia

É uma prática recomendada no final de um projeto identificar se você ainda precisa dos recursos criados. Os recursos que deixar em execução podem custar dinheiro. Se a fila existir, mas estiver vazia, pergunte ao usuário se ele gostaria de excluí-la.

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

Guarde o ficheiro.

Verificar se há argumentos de linha de comando

Se houver argumentos de linha de comando passados para o aplicativo, suponha que eles sejam 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 InsertMessageAsync método que adicionamos anteriormente.

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

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

Expanda o método para verificar se há argumentos de linha de comando e aguarde a Main entrada do usuário. No trecho 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();
}

Guarde o ficheiro.

Código completo

Aqui está 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 a aplicação

A partir da linha de comando no diretório do projeto, execute o seguinte comando dotnet para criar 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

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 você executá-lo mais uma vez, 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óximos passos

Neste tutorial, ficou a saber como:

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

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

Início rápido de filas para o portal

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

Partilhar via