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

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

• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento
• SDK de .NET actual para su 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 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.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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.

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

az login

az login

Connect-AzAccount

using Azure.Identity;

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

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

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

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(connectionString, queueName);

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:

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