Tutorial: Uso de las colas de Azure Queue Storage en .NET

Artículo
08/09/2024

Azure Queue Storage implementa colas que se encuentran en la nube para permitir la comunicación entre los componentes de una aplicación distribuida. Cada cola incluye una lista de los mensajes que un componente emisor puede agregar y un componente receptor puede procesar. Con una cola, la aplicación se puede escalar inmediatamente para satisfacer la demanda. En este artículo se muestran los pasos básicos para trabajar con una cola de Azure Queue Storage.

En este tutorial, aprenderá a:

Creación de una cuenta de Azure Storage
Creación de la aplicación
Agregar las bibliotecas cliente de Azure
Agregar compatibilidad con el código asincrónico
Creación de una cola
Insertar mensajes en una cola
Retirar mensajes de la cola
Eliminar una cola vacía
Buscar argumentos de línea de comandos
Compilación y ejecución de la aplicación

Requisitos previos

Obtenga una copia gratuita del editor de Visual Studio Code multiplataforma.
Descargue e instale la versión 3.1 o posterior del SDK de .NET Core.
Si no tiene una suscripción actual a Azure, cree una cuenta gratuita antes de empezar.

Creación de una cuenta de Azure Storage

En primer lugar, cree una cuenta de Azure Storage.

Para obtener una guía detallada sobre la creación de una cuenta de Storage, consulte Creación de una cuenta de Storage. Este es un paso independiente que debe realizar después de crear una cuenta de Azure gratuita en los requisitos previos.
Asegúrese de que a la cuenta de usuario se le ha asignado el rol de colaborador de datos de cola de almacenamiento, con ámbito a la cuenta de almacenamiento, al grupo de recursos primario o a la suscripción. Consulte Autenticación en Azure AD.

Creación de la aplicación

Cree una aplicación de .NET Core llamada QueueApp. Por motivos de sencillez, esta aplicación enviará y recibirá mensajes a través de la cola.

En una ventana de consola (como cmd, PowerShell o CLI de Azure), use el comando dotnet new para crear una aplicación de consola con el nombre QueueApp. Este comando crea un sencillo proyecto "hola mundo" en C# con un solo archivo de origen llamado Program.cs.
```
dotnet new console -n QueueApp
```

Cambie a la carpeta QueueApp recién creada y compile la aplicación para comprobar que todo sea correcto.

cd QueueApp

dotnet build

Debería ver resultados similares a lo siguiente:

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>_

Adición de las bibliotecas cliente de Azure

Agregue las bibliotecas cliente de Azure Storage al proyecto mediante el comando dotnet add package.

Ejecute el siguiente comando desde la carpeta de proyecto en la ventana de la consola.
```
dotnet add package Azure.Storage.Queues
```

Adición de instrucciones using

En la línea de comandos del directorio del proyecto, escriba code . para abrir Visual Studio Code en el directorio actual. Mantenga la ventana de la línea de comandos abierta. Habrá más comandos que se ejecutarán más tarde. Si se le pide que agregue los recursos de C# necesarios para compilar y depurar, haga clic en el botón Sí.
Abra el archivo de origen Program.cs y agregue los siguientes espacios de nombres justo después de la instrucción using System;. Esta aplicación utiliza tipos de estos espacios de nombres para conectarse a Azure Storage y trabajar con colas.
```
using System.Threading.Tasks;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
```
Guarde el archivo Program.cs.

Agregar compatibilidad con el código asincrónico

Como la aplicación usa recursos en la nube, el código se ejecuta de forma asincrónica.

Actualice el método Main para que se ejecute de forma asincrónica. Reemplace void por un valor devuelto async Task.
```
static async Task Main(string[] args)
```
Guarde el archivo Program.cs.

Creación de una cola

Antes hacer alguna llamada a las API de Azure, tiene que asegurarse de que está autenticado con la misma cuenta de Microsoft Entra a la que asignó el rol. Una vez que se autentique, puede crear y autorizar un objeto QueueClient mediante DefaultAzureCredential para acceder a los datos de la cola en la cuenta de almacenamiento. DefaultAzureCredential descubre y usa automáticamente la cuenta con la que ha iniciado sesión. Para obtener información sobre cómo iniciar sesión y, a continuación, crear un objeto QueueClient, consulte Autorización del acceso y creación de un objeto de cliente.

Inserción de mensajes en la cola

Cree un nuevo método para enviar un mensaje a la cola.

Agregue el método InsertMessageAsync a la clase Program.

A este método se le pasa una referencia de cola. Se crea una cola, en caso de que no exista, mediante una llamada a CreateIfNotExistsAsync. Luego, agrega newMessage a la cola mediante una llamada a 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: de forma predeterminada, el tiempo de vida máximo de un mensaje se establece en siete días. Puede especificar cualquier número positivo para el período de vida de un mensaje. El siguiente fragmento de código agrega un mensaje que nunca expira.

Para agregar un mensaje que no expire, use Timespan.FromSeconds(-1) en la llamada a SendMessageAsync.
```
await theQueue.SendMessageAsync(newMessage, default, TimeSpan.FromSeconds(-1), default);
```
Guarde el archivo.

Un mensaje de cola debe tener un formato compatible con una solicitud XML con codificación UTF-8. Un mensaje puede tener un tamaño de hasta 64 KB. Si un mensaje contiene datos binarios, se recomienda codificarlo en Base64.

Retirar mensajes de la cola

Cree un método para recuperar un mensaje de la cola. Una vez que el mensaje se recibe correctamente, es importante eliminarlo de la cola para que no se procese más de una vez.

Agregue un nuevo método llamado RetrieveNextMessageAsync a la clase Program.

Este método recibe un mensaje de la cola mediante la realización de una llamada a ReceiveMessagesAsync, y usando1 en el primer parámetro para recuperar solo el siguiente mensaje de la cola. Una vez recibido el mensaje, elimínelo de la cola mediante una llamada a DeleteMessageAsync.

Cuando se envía un mensaje a la cola con una versión del SDK anterior a la v12, se codifica automáticamente en Base64. A partir de la versión 12, se ha quitado esta funcionalidad. Cuando se recupera un mensaje mediante el SDK de la v12, no se descodifica automáticamente en Base64. Debe descodificar explícitamente en Base64 el contenido usted mismo.
```
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 el archivo.

Eliminar una cola vacía

Al final de un proyecto es un procedimiento recomendado identificar si aún necesita los recursos que creó. Los recursos que se dejan en ejecución pueden costarle mucho dinero. Si la cola existe pero está vacía, pregunte al usuario si desea eliminarla.

Expanda el método RetrieveNextMessageAsync para incluir un aviso para eliminar la cola vacía.

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 el archivo.

Buscar argumentos de línea de comandos

Si no se pasa ningún argumento de línea de comandos a la aplicación, se supone que hay un mensaje para agregar a la cola. Una los argumentos para crear una cadena. Agregue esta cadena a la cola de mensajes mediante una llamada al método InsertMessageAsync que se agregó anteriormente.

Si no hay ningún argumento de línea de comandos, intente una operación de recuperación. Llame al método RetrieveNextMessageAsync para recuperar el siguiente mensaje de la cola.

Por último, espere la entrada del usuario antes de salir mediante una llamada a Console.ReadLine.

Expanda el método Main para que busque argumentos de línea de comandos y espere la entrada del usuario. En el fragmento de código siguiente, asegúrese de reemplazar el marcador de posición {storageAccountName} por el nombre de la cuenta de almacenamiento.

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 el archivo.

Código completo

Aquí está la lista de códigos completa de este proyecto.

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.";
            }
        }
    }
}

Compilación y ejecución de la aplicación

En la línea de comandos del directorio del proyecto, ejecute el siguiente comando dotnet para compilar el proyecto.
```
dotnet build
```
Después de que el proyecto se compile correctamente, ejecute el siguiente comando para agregar el primer mensaje a la cola.
```
dotnet run First queue message
```
Debería ver este resultado:
```
C:\Tutorials\QueueApp>dotnet run First queue message
The queue was created.
Sent: First queue message
Press Enter..._
```
Ejecute la aplicación sin argumentos de línea de comandos para recibir y quitar el primer mensaje de la cola.
```
dotnet run
```

Continúe ejecutando la aplicación hasta que se eliminen todos los mensajes. Si la ejecuta más de una vez, recibirá un mensaje de que la cola está vacía y un aviso para que elimine la cola.

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>_

Pasos siguientes

En este tutorial, ha aprendido a:

Creación de una cola
Adición y eliminación de mensajes de una cola
Eliminación de una cola de Azure Queue Storage

Para más información, consulte los inicios rápidos sobre Azure Queue Storage.

Inicio rápido de colas para el portal

Para obtener ejemplos de código relacionados con los SDK de .NET versión 11.x en desuso, consulte Ejemplos de código con la versión 11.x de .NET.

Compartir a través de