Inicio rápido: Biblioteca cliente de Azure Queue Storage v12 para .NET

Artículo
09/29/2021
9 minutos para leer

Empiece a usar la versión 12 de la biblioteca cliente de Azure Queue Storage para .NET. Azure Queue Storage es un servicio para almacenar gran cantidad de mensajes para su posterior recuperación y procesamiento. Siga estos pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.

Use la biblioteca cliente de Azure Queue Storage v12 para .NET para realizar las siguientes operaciones:

Creación de una cola
Adición de mensajes a una cola
Lectura de los mensajes de una cola
Eliminación de un mensaje de una cola
mensajes de una cola
Eliminación de mensajes de una cola
Eliminación de una cola

Recursos adicionales:

Requisitos previos

Una suscripción a Azure: cree una cuenta gratuita
Una cuenta de Azure Storage: cree una cuenta de almacenamiento
El SDK de NET Core actual del sistema operativo. Asegúrese de obtener el SDK y no el entorno de ejecución.

Instalación

En esta sección se explica cómo preparar un proyecto para que funcione con la biblioteca cliente de Azure Queue Storage v12 para .NET.

Creación del proyecto

Cree una aplicación de .NET Core llamada QueuesQuickstartV12.

En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use el comando dotnet new para crear una nueva aplicación de consola con el nombre QueuesQuickstartV12. Este comando crea un sencillo proyecto "hola mundo" en C# con un solo archivo de origen llamado Program.cs.
```
dotnet new console -n QueuesQuickstartV12
```
Cambie al directorio QueuesQuickstartV12 recién creado.
```
cd QueuesQuickstartV12
```

Instalar el paquete

En el directorio de aplicaciones, instale el paquete de la biblioteca cliente de Azure Queue Storage para .NET mediante el comando dotnet add package.

dotnet add package Azure.Storage.Queues

Instalación del marco de la aplicación

Desde el directorio del proyecto:

Abra el archivo Program.cs en un editor.
Quite la instrucción Console.WriteLine("Hello, World");.
Agregue directivas using.
Actualice la declaración del método Main para admitir código asincrónico.

Este es el código:

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

namespace QueuesQuickstartV12
{
    class Program
    {
        static async Task Main(string[] args)
        {
        }
    }
}

Copia de las credenciales desde Azure Portal

Cuando la aplicación de ejemplo realiza una solicitud a Azure Storage, debe estar autorizada. Para autorizar una solicitud, agregue a la aplicación las credenciales de la cuenta de almacenamiento en forma de cadena de conexión. Para ver las credenciales de la cuenta de almacenamiento, siga estos pasos:

Inicie sesión en Azure Portal.
Busque su cuenta de almacenamiento.
En el panel del menú de la cuenta de almacenamiento, en Seguridad y redes, seleccione Claves de acceso. Aquí puede ver las claves de acceso de la cuenta, así como la cadena de conexión completa de cada clave.
En el panel Claves acceso, seleccione Mostrar claves.
En la sección key1, busque el valor de Cadena de conexión. Seleccione el icono Copiar al portapapeles para copiar la cadena de conexión. En la siguiente sección, agregará el valor de la cadena de conexión a una variable de entorno.

Configuración de la cadena de conexión de almacenamiento.

Una vez que haya copiado la cadena de conexión, escríbala en una variable de entorno nueva en la máquina local que ejecuta la aplicación. Para establecer la variable de entorno, abra una ventana de consola y siga las instrucciones de su sistema operativo. Reemplace <yourconnectionstring> por la cadena de conexión real.

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Después de agregar la variable de entorno en Windows, debe iniciar una nueva instancia de la ventana de comandos.

Linux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Reiniciar programas

Después de agregar la variable de entorno, reinicie todos los programas en ejecución que necesiten leer esta variable. Por ejemplo, reinicie el entorno de desarrollo o el editor antes de continuar.

Modelo de objetos

Azure Queue Storage es un servicio para almacenar grandes cantidades de mensajes, Un mensaje de la cola puede llegar a tener hasta 64 KB. Una cola puede contener millones de mensajes, hasta el límite de capacidad total de una cuenta de almacenamiento. Las colas se utilizan normalmente para crear un trabajo pendiente del trabajo que se va a procesar de forma asincrónica. Queue Storage ofrece tres tipos de recursos:

La cuenta de almacenamiento
Cola en la cuenta de almacenamiento
Mensajes dentro de la cola

En el siguiente diagrama se muestra la relación entre estos recursos.

Diagrama de la arquitectura de Queue Storage

Use las siguientes clases de .NET para interactuar con estos recursos:

QueueServiceClient: La clase QueueServiceClient permite administrar todas las colas de la cuenta de almacenamiento.
QueueClient: La clase QueueClient permite administrar y manipular una cola individual y sus mensajes.
QueueMessage: La clase QueueMessage representa los objetos individuales que se devuelven al llamar a ReceiveMessages en una cola.

Ejemplos de código

Estos fragmentos de código de ejemplo muestran cómo realizar las siguientes acciones con la biblioteca cliente de Azure Queue Storage para .NET:

Obtención de la cadena de conexión
Creación de una cola
Adición de mensajes a una cola
Leer los mensajes de una cola
Eliminación de un mensaje de una cola
Recepción de mensajes de una cola
Eliminación de mensajes de una cola
Eliminación de una cola

Obtención de la cadena de conexión

El siguiente código recupera la cadena de conexión de la cuenta de almacenamiento. La cadena de conexión se almacena en la variable de entorno creada en la sección Configuración de la cadena de conexión de almacenamiento.

Agregue este código dentro del método Main:

Console.WriteLine("Azure Queue Storage client library v12 - .NET quickstart sample\n");

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable called
// AZURE_STORAGE_CONNECTION_STRING on the machine running the application.
// If the environment variable is created after the application is launched
// in a console or with Visual Studio, the shell or application needs to be
// closed and reloaded to take the environment variable into account.
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

Creación de una cola

Decida un nombre para la nueva cola. El siguiente código anexa un valor de GUID al nombre de la cola para asegurarse de que sea único.

Importante

Los nombres de la cola solo puede incluir letras minúsculas, números y guiones y debe empezar por una letra o un número. Antes y después de cada guion debe ir un carácter que no sea otro guión. El nombre debe tener entre 3 y 63 caracteres. Para más información, consulte Asignación de nombres a colas y metadatos.

Cree una instancia de la clase QueueClient. Luego, llame al método CreateAsync para crear la cola en la cuenta de almacenamiento.

Agregue este código al final del método Main:

// Create a unique name for the queue
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();

Console.WriteLine($"Creating queue: {queueName}");

// Instantiate a QueueClient which will be
// used to create and manipulate the queue
QueueClient queueClient = new QueueClient(connectionString, queueName);

// Create the queue
await queueClient.CreateAsync();

Adición de mensajes a una cola

El siguiente fragmento de código agrega de forma asincrónica mensajes a la cola mediante una llamada al método SendMessageAsync. También guarda una clase SendReceipt devuelta desde una llamada a SendMessageAsync. La confirmación se utiliza para actualizar el mensaje más adelante en el programa.

Agregue este código al final del método Main:

Console.WriteLine("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.SendMessageAsync("First message");
await queueClient.SendMessageAsync("Second message");

// Save the receipt so we can update this message later
SendReceipt receipt = await queueClient.SendMessageAsync("Third message");

Lectura de los mensajes de una cola

Lea los mensajes de la cola, para lo que debe llamar al método PeekMessagesAsync. Este método recupera uno o varios mensajes de la parte delantera de la cola, pero no modifica la visibilidad del mensaje.

Agregue este código al final del método Main:

Console.WriteLine("\nPeek at the messages in the queue...");

// Peek at messages in the queue
PeekedMessage[] peekedMessages = await queueClient.PeekMessagesAsync(maxMessages: 10);

foreach (PeekedMessage peekedMessage in peekedMessages)
{
    // Display the message
    Console.WriteLine($"Message: {peekedMessage.MessageText}");
}

Eliminación de un mensaje de una cola

Actualice el contenido de un mensaje mediante una llamada al método UpdateMessageAsync. Este método puede cambiar tanto el contenido como el tiempo de espera de visibilidad de un mensaje. El contenido del mensaje debe ser una cadena con codificación UTF-8 de hasta 64 KB de tamaño. Junto con el nuevo contenido del mensaje, pase los valores de SendReceipt que se guardó anteriormente en el código. Los valores SendReceipt identifican el mensaje que se va a actualizar.

Console.WriteLine("\nUpdating the third message in the queue...");

// Update a message using the saved receipt from sending the message
await queueClient.UpdateMessageAsync(receipt.MessageId, receipt.PopReceipt, "Third message has been updated");

mensajes de una cola

Descargue los mensajes que ha agregado anteriormente, para lo que debe llamar al método ReceiveMessagesAsync.

Agregue este código al final del método Main:

Console.WriteLine("\nReceiving messages from the queue...");

// Get messages from the queue
QueueMessage[] messages = await queueClient.ReceiveMessagesAsync(maxMessages: 10);

Eliminación de mensajes de una cola

Elimine los mensajes de la cola una vez procesados. En este caso, el procesamiento solo muestra el mensaje en la consola.

La aplicación se detiene para la entrada del usuario mediante una llamada a Console.ReadLine antes de procesar y eliminar los mensajes. Compruebe en Azure Portal que los recursos se crearon correctamente, antes de que se eliminen. Los mensajes que no se eliminen explícitamente volverán a estar visibles en la cola para que se procesen.

Agregue este código al final del método Main:

Console.WriteLine("\nPress Enter key to 'process' messages and delete them from the queue...");
Console.ReadLine();

// Process and delete messages from the queue
foreach (QueueMessage message in messages)
{
    // "Process" the message
    Console.WriteLine($"Message: {message.MessageText}");

    // Let the service know we're finished with
    // the message and it can be safely deleted.
    await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt);
}

Eliminación de una cola

El siguiente código limpia los recursos que creó la aplicación; para ello, elimina la cola mediante el método DeleteAsync.

Agregue este código al final del método Main:

Console.WriteLine("\nPress Enter key to delete the queue...");
Console.ReadLine();

// Clean up
Console.WriteLine($"Deleting queue: {queueClient.Name}");
await queueClient.DeleteAsync();

Console.WriteLine("Done");

Ejecución del código

Esta aplicación crea y agrega tres mensajes a una cola de Azure. El código muestra los mensajes en la cola y, a continuación, los recupera y los elimina antes de eliminar la cola.

En la ventana de la consola, vaya al directorio de la aplicación y, después, compile y ejecute la aplicación.

dotnet build

dotnet run

La salida de la aplicación es similar a la del ejemplo siguiente:

Azure Queue Storage client library v12 - .NET quickstart sample

Creating queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2
Done

Cuando la aplicación se detiene antes de recibir mensajes, compruebe la cuenta de almacenamiento en Azure Portal. Compruebe que los mensajes están en la cola.

Presione la tecla Enter para recibir y eliminar los mensajes. Cuando se le solicite, presione de nuevo la tecla Enter para eliminar la cola y finalizar la demostración.

Pasos siguientes

En este inicio rápido, ha aprendido a crear una cola y a agregarle mensajes mediante código .NET asincrónico. Después aprendió a ver, recuperar y eliminar mensajes. Por último, ha aprendido a eliminar una cola de mensajes.

Para ver tutoriales, ejemplos, artículos de inicio rápido y otra documentación, visite:

Azure para desarrolladores de .NET y .NET Core

Para más información, consulte Bibliotecas de Azure Storage para .NET.
Para ver más aplicaciones de ejemplo de Azure Queue Storage, consulte los ejemplos de la biblioteca de Azure Queue Storage para .NET.
Para más información sobre .NET Core, consulte Get started with .NET in 10 minutes (Introducción a .NET en 10 minutos).

Inicio rápido: Biblioteca cliente de Azure Queue Storage v12 para .NET

Valore su experiencia

Requisitos previos

Instalación

Creación del proyecto

Instalar el paquete

Instalación del marco de la aplicación

Copia de las credenciales desde Azure Portal

Configuración de la cadena de conexión de almacenamiento.

Windows

Linux

macOS

Reiniciar programas

Modelo de objetos

Ejemplos de código

Obtención de la cadena de conexión

Creación de una cola

Adición de mensajes a una cola

Lectura de los mensajes de una cola

Eliminación de un mensaje de una cola

mensajes de una cola

Eliminación de mensajes de una cola

Eliminación de una cola

Ejecución del código

Pasos siguientes