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

  • Artículo

Introducción a 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.

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (NuGet) | Ejemplos

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

  • 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
  • la longitud de la cola
  • mensajes de una cola
  • Eliminación de mensajes de una cola
  • Eliminación de una cola

Requisitos previos

Instalación

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

Creación del proyecto

Creación de una aplicación .NET denominada QueuesQuickstart.

  1. 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 QueuesQuickstart. Este comando crea un sencillo proyecto de C#, "hola mundo", con un solo archivo de origen denominado Program.cs.

    dotnet new console -n QueuesQuickstart

  2. Cambie al directorio QueuesQuickstart recién creado.

    cd QueuesQuickstart

Instalación de los paquetes

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

El paquete de biblioteca cliente de identidad de Azure también es necesario para las conexiones sin contraseña a los servicios de Azure.

dotnet add package Azure.Identity

Instalación del marco de la aplicación

  1. Abra el proyecto en el editor que prefiera.
  2. Abra el archivo Program.cs.
  3. Actualice el código existente para que coincida con el siguiente:
using Azure;
using Azure.Identity;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using System;
using System.Threading.Tasks;

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

// Quickstart code goes here

Autentíquese en Azure

Deben autorizarse las solicitudes de aplicación a la mayor parte de servicios de Azure. El uso de la clase DefaultAzureCredential que proporciona la biblioteca cliente de Azure Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código.

También puede autorizar directamente las solicitudes a los servicios de Azure mediante contraseñas, cadenas de conexión u otras credenciales. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser meticulosos y no exponer nunca estos secretos en una ubicación que no sea segura. Cualquier persona que obtenga acceso a la contraseña o a la clave secreta puede autenticarse. DefaultAzureCredential ofrece ventajas de seguridad y administración mejoradas con respecto la clave de cuenta para permitir la autenticación sin contraseña. Ambas opciones se muestran en el ejemplo siguiente.

DefaultAzureCredential es una clase proporcionada por la biblioteca cliente de Azure Identity para .NET. Para más información sobre DefaultAzureCredential, consulte la información general sobre DefaultAzureCredential. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.

Por ejemplo, la aplicación puede autenticarse con las credenciales de inicio de sesión de Visual Studio cuando se trabaja en un desarrollo localmente y, después, usar una identidad administrada tras haberse implementado en Azure. No se necesitan cambios de código para esta transición.

Al desarrollar localmente, asegúrese de que la cuenta de usuario que accede a los datos de la cola tenga los permisos correctos. Necesitará el Colaborador de datos de cola de almacenamiento para leer y escribir datos de la cola. Para asignarse este rol a sí mismo, necesitará que se le asigne el rol Administrador de acceso de usuario u otro rol que incluya la acción Microsoft.Authorization/roleAssignments/write. Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Puede obtener más información sobre los ámbitos disponibles para las asignaciones de roles en la página de información general del ámbito.

En este escenario, asignará permisos a la cuenta de usuario, cuyo ámbito es la cuenta de almacenamiento, a fin de seguir el principio de privilegios mínimos. Esta práctica solo proporciona a los usuarios los permisos mínimos necesarios y crea entornos de producción más seguros.

En el ejemplo siguiente se asignará el rol Colaborador de datos de cola de almacenamiento a la cuenta de usuario, que proporciona acceso de lectura y escritura a los datos de la cola de la cuenta de almacenamiento.

Importante

En la mayoría de los casos, la asignación de roles tardará un minuto o dos en propagarse en Azure, pero en casos excepcionales puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. En Azure Portal, busque la cuenta de almacenamiento mediante la barra de búsqueda principal o el panel de navegación de la izquierda.

  2. En la página de información general de la cuenta de almacenamiento, seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.

A screenshot showing how to assign a role.

  1. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Colaborador de datos de cola de almacenamiento y seleccione el resultado coincidente y, a continuación, elija Siguiente.

  2. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  3. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  4. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

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:

  • Cuenta de almacenamiento:todo el acceso a Azure Storage se realiza a través de una cuenta de almacenamiento. Para más información sobre las cuentas de almacenamiento, consulte Introducción a las cuentas de Storage
  • Cola: una cola contiene un conjunto de mensajes. Todos los mensajes deben encontrarse en una cola. Tenga en cuenta que el nombre de la cola debe ir en minúsculas. Para más información, consulte Asignar nombres a colas y metadatos.
  • Mensaje: un mensaje, en cualquier formato, de hasta 64 KB. Un mensaje puede permanecer en la cola durante un máximo de 7 días. A partir de la versión del 2017-07-29, inclusive, el tiempo de vida máximo puede ser cualquier número positivo o -1, lo que indica que el mensaje no expira. Si se omite este parámetro, el tiempo de vida predeterminado es siete días.

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

Diagram of Queue storage architecture

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:

Autorización del acceso y creación de un objeto de cliente

En el caso del desarrollo local, asegúrese de realizar la autenticación con la misma cuenta de Microsoft Entra a la que ha asignado el rol. Puede autenticarse a través de herramientas de desarrollo populares, como la CLI de Azure o Azure PowerShell. Las herramientas de desarrollo con las que puede autenticarse varían en todos los idiomas.

Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:

az login

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 detecta y usa automáticamente la cuenta con la que ha iniciado sesión en el paso anterior.

Para autorizar mediante DefaultAzureCredential, asegúrese de que ha agregado el paquete Azure.Identity, como se describe en Instalación de los paquetes. Además, asegúrese de agregar una directiva using para el espacio de nombres Azure.Identity en el archivo Program.cs:

using Azure.Identity;

A continuación, decida un nombre para la cola y cree una instancia de la clase QueueClient mediante DefaultAzureCredential para la autorización. Usaremos este objeto de cliente para crear e interactuar con el recurso de cola en la cuenta de almacenamiento.

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.

Agregue el código siguiente al final del archivo Program.cs. Asegúrese de reemplazar el valor del marcador de posición <storage-account-name>:

// Create a unique name for the queue
// TODO: Replace the <storage-account-name> placeholder 
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();
string storageAccountName = "<storage-account-name>";

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(
    new Uri($"https://{storageAccountName}.queue.core.windows.net/{queueName}"),
    new DefaultAzureCredential());

Nota:

Los mensajes enviados mediante la clase QueueClient deben tener un formato que se pueda incluir en una solicitud XML con codificación UTF-8. Opcionalmente, puede establecer la opción MessageEncoding como Base64 para controlar los mensajes no compatibles.

Creación de una cola

Con el objeto QueueClient, llame al método CreateAsync para crear la cola en la cuenta de almacenamiento.

Agregue este código al final del método Program.cs:

Console.WriteLine($"Creating queue: {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 archivo Program.cs:

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 archivo Program.cs:

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");

la longitud de la cola

Puede obtener una estimación del número de mensajes existentes en una cola. El método GetProperties devuelve propiedades de cola, incluido el recuento de mensajes. La propiedad ApproximateMessagesCount obtiene el número aproximado de mensajes en la cola. Este número no es menor que el número real de mensajes de la cola, pero podría ser mayor.

Agregue este código al final del archivo Program.cs:

QueueProperties properties = queueClient.GetProperties();

// Retrieve the cached approximate message count
int cachedMessagesCount = properties.ApproximateMessagesCount;

// Display number of messages
Console.WriteLine($"Number of messages in queue: {cachedMessagesCount}");

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 archivo Program.cs:

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

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

Puede especificar opcionalmente un valor para maxMessages, que es el número de mensajes que se van a recuperar de la cola. El valor predeterminado es 1 mensaje y el máximo es 32 mensajes. También puede especificar un valor para visibilityTimeout, que oculta los mensajes de otras operaciones durante el período de tiempo de espera. El valor predeterminado es 30 segundos.

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 archivo Program.cs:

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 archivo Program.cs:

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