Guida introduttiva: Libreria client Archiviazione coda di Azure per .NET

  • Articolo

Introduzione alla libreria client di Archiviazione coda di Azure per .NET. Archiviazione code di Azure è un servizio che consente di archiviare un numero elevato di messaggi per recuperali ed elaborarli successivamente. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

Documentazione di riferimento dell'API | Codice sorgente della libreria | Pacchetto (NuGet) | Esempi

Usare la libreria client Archiviazione coda di Azure per .NET per:

  • Crea una coda
  • Aggiungere messaggi a una coda
  • Visualizzare in anteprima i messaggi in una coda
  • Aggiornare un messaggio in una coda
  • Recuperare la lunghezza della coda
  • Ricevere messaggi da una coda
  • Eliminare messaggi da una coda
  • Eliminare una coda

Prerequisiti

Configurazione

Questa sezione illustra come preparare un progetto per l'uso con la libreria client della coda di Azure Archiviazione per .NET.

Creare il progetto

Creare un'applicazione .NET denominata QueuesQuickstart.

  1. In una finestra di una console, ad esempio cmd, PowerShell o Bash, usare il comando dotnet new per creare una nuova app console con il nome QueuesQuickstart. Questo comando crea un semplice progetto C# "hello world" con un singolo file di origine denominato Program.cs.

    dotnet new console -n QueuesQuickstart

  2. Passare alla directory appena creata QueuesQuickstart .

    cd QueuesQuickstart

Installare i pacchetti

Sempre nella directory dell'applicazione, installare il pacchetto della libreria client di Archiviazione code di Azure per .NET usando il comando dotnet add package.

dotnet add package Azure.Storage.Queues

Il pacchetto della libreria client di Identità di Azure è necessario anche per le connessioni senza password ai servizi di Azure.

dotnet add package Azure.Identity

Configurare il framework dell'app

  1. Aprire il progetto nell'editor preferito
  2. Aprire il file Program.cs
  3. Aggiornare il codice esistente in modo che corrisponda al seguente:
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

Autenticazione con Azure

Le richieste dell'applicazione per la maggior parte dei servizi di Azure devono essere autorizzate. L'uso della DefaultAzureCredential classe fornita dalla libreria client di Identità di Azure è l'approccio consigliato per implementare connessioni senza password ai servizi di Azure nel codice.

È anche possibile autorizzare le richieste ai servizi di Azure usando password, stringa di connessione o altre credenziali direttamente. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai questi segreti in una posizione non sicura. Chiunque possa accedere alla password o alla chiave privata è in grado di eseguire l'autenticazione. DefaultAzureCredential offre vantaggi di gestione e sicurezza migliorati rispetto alla chiave dell'account per consentire l'autenticazione senza password. Entrambe le opzioni sono illustrate nell'esempio seguente.

DefaultAzureCredential è una classe fornita dalla libreria client di Identità di Azure per .NET. Per altre informazioni su DefaultAzureCredential, vedere la panoramica di DefaultAzureCredential. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e di produzione) senza implementare codice specifico dell'ambiente.

Ad esempio, l'app può eseguire l'autenticazione usando le credenziali di accesso di Visual Studio durante lo sviluppo in locale e quindi usare un'identità gestita dopo la distribuzione in Azure. Per questa transizione non sono necessarie modifiche al codice.

Quando si sviluppa in locale, assicurarsi che l'account utente che accede ai dati della coda disponga delle autorizzazioni corrette. È necessario Archiviazione Collaboratore ai dati della coda per leggere e scrivere dati della coda. Per assegnare a se stessi questo ruolo, è necessario assegnare il ruolo Accesso utente Amministrazione istrator o un altro ruolo che include l'azione Microsoft.Authorization/roleAssignments/write. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Per altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere la pagina di panoramica dell'ambito.

In questo scenario si assegneranno le autorizzazioni all'account utente, con ambito all'account di archiviazione, per seguire il principio dei privilegi minimi. Questa procedura offre agli utenti solo le autorizzazioni minime necessarie e crea ambienti di produzione più sicuri.

L'esempio seguente assegnerà il ruolo collaboratore ai dati della coda Archiviazione all'account utente, che fornisce sia l'accesso in lettura che in scrittura ai dati della coda nell'account di archiviazione.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà almeno due minuti, ma in rari casi può richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

  1. Nella portale di Azure individuare l'account di archiviazione usando la barra di ricerca principale o lo spostamento a sinistra.

  2. Nella pagina di panoramica dell'account di archiviazione selezionare Controllo di accesso (IAM) dal menu a sinistra.

  3. Nella pagina Controllo di accesso (IAM) selezionare la scheda Assegnazioni di ruolo.

  4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

A screenshot showing how to assign a role.

  1. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Archiviazione Collaboratore dati coda e selezionare il risultato corrispondente e quindi scegliere Avanti.

  2. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

  3. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain ) e quindi scegliere Seleziona nella parte inferiore della finestra di dialogo.

  4. Selezionare Rivedi e assegna per passare alla pagina finale e quindi rivedi e assegna per completare il processo.

Modello a oggetti

Archiviazione code di Azure è un servizio per l'archiviazione di un numero elevato di messaggi. Un messaggio in coda avere dimensioni fino a 64 KB. Una coda può contenere milioni di messaggi, fino al limite di capacità totale dell'account di archiviazione. Le code vengono in genere usate per creare un backlog di lavoro da elaborare in modo asincrono. Archiviazione code offre tre tipi di risorse:

  • Account di archiviazione:l'accesso ad Archiviazione di Azure viene eseguito esclusivamente tramite un account di archiviazione. Per altre informazioni sugli account di archiviazione, vedere panoramica dell'account di Archiviazione
  • Coda: una coda contiene un set di messaggi. Tutti i messaggi devono essere in una coda. Si noti che il nome della coda deve essere tutto minuscolo. Per altre informazioni, vedere Denominazione di code e metadati.
  • Messaggio: un messaggio, in qualsiasi formato, con dimensioni massime di 64 KB. Un messaggio può rimanere nella coda per un massimo di 7 giorni. Per la versione 2017-07-29 o successiva, la durata massima può essere qualsiasi numero positivo o -1 che indica che il messaggio non scade. Se questo parametro viene omesso, il valore TTL predefinito è sette giorni.

Il diagramma seguente mostra la relazione tra queste risorse.

Diagram of Queue storage architecture

Per interagire con queste risorse, usare le classi .NET seguenti:

  • QueueServiceClientQueueServiceClient: consente di gestire tutte le code nell'account di archiviazione.
  • QueueClient: la QueueClient classe consente di gestire e modificare una singola coda e i relativi messaggi.
  • QueueMessage: la QueueMessage classe rappresenta i singoli oggetti restituiti durante la chiamata ReceiveMessages a una coda.

Esempi di codice

Questi frammenti di codice di esempio mostrano come eseguire le azioni seguenti con la libreria client di Archiviazione code di Azure per .NET:

Autorizzare l'accesso e creare un oggetto client

Per lo sviluppo locale, assicurarsi di essere autenticati con lo stesso account Microsoft Entra a cui è stato assegnato il ruolo. È possibile eseguire l'autenticazione tramite strumenti di sviluppo diffusi, ad esempio l'interfaccia della riga di comando di Azure o Azure PowerShell. Gli strumenti di sviluppo con cui è possibile eseguire l'autenticazione variano a seconda dei linguaggi.

Accedere ad Azure tramite l'interfaccia della riga di comando di Azure usando il comando seguente:

az login

Dopo l'autenticazione, è possibile creare e autorizzare un QueueClient oggetto usando DefaultAzureCredential per accedere ai dati della coda nell'account di archiviazione. DefaultAzureCredential individua e usa automaticamente l'account con cui è stato eseguito l'accesso nel passaggio precedente.

Per autorizzare l'uso di DefaultAzureCredential, assicurarsi di aver aggiunto il pacchetto Azure.Identity , come descritto in Installare i pacchetti. Assicurarsi inoltre di aggiungere una direttiva using per lo Azure.Identity spazio dei nomi nel file Program.cs :

using Azure.Identity;

Scegliere quindi un nome per la coda e creare un'istanza della QueueClient classe usando DefaultAzureCredential per l'autorizzazione. Questo oggetto client viene usato per creare e interagire con la risorsa della coda nell'account di archiviazione.

Importante

I nomi di coda possono contenere solo lettere minuscole, numeri e segni meno e devono iniziare con una lettera o un numero. Ogni trattino deve essere preceduto e seguito da un carattere diverso da un trattino. Il nome deve inoltre avere una lunghezza compresa fra 3 e 63 caratteri. Per altre informazioni, vedere Denominazione di code e metadati.

Aggiungere il codice seguente alla fine del file Program.cs . Assicurarsi di sostituire il <storage-account-name> valore segnaposto:

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

I messaggi inviati tramite la QueueClient classe devono essere in un formato che può essere incluso in una richiesta XML con codifica UTF-8. Facoltativamente, è possibile impostare l'opzione MessageEncoding su Base64 per gestire i messaggi non conformi.

Crea una coda

Usando l'oggetto QueueClient , chiamare il CreateAsync metodo per creare la coda nell'account di archiviazione.

Aggiungere questo codice alla fine del metodo Program.cs :

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

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

Aggiungere messaggi a una coda

Il frammento di codice seguente aggiunge messaggi alla coda in modo asincrono chiamando il metodo SendMessageAsync. Salva anche un SendReceipt restituito da una chiamata a SendMessageAsync. L'elemento restituito viene usato per aggiornare il messaggio in un secondo momento nel programma.

Aggiungere questo codice alla fine del file 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");

Visualizzare in anteprima i messaggi in una coda

Per visualizzare in anteprima i messaggi nella coda, chiamare il metodo PeekMessagesAsync. Questo metodo recupera uno o più messaggi dall'inizio della coda, senza modificare la visibilità del messaggio.

Aggiungere questo codice alla fine del file 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}");
}

Aggiornare un messaggio in una coda

Per aggiornare il contenuto di un messaggio, chiamare il metodo UpdateMessageAsync. Questo metodo può modificare il timeout di visibilità e il contenuto di un messaggio. Il contenuto del messaggio deve essere una stringa con codifica UTF-8 di dimensioni non superiori a 64 KB. Insieme al nuovo contenuto del messaggio, passare i valori del SendReceipt salvati in precedenza nel codice. I valori del SendReceipt identificano il messaggio da aggiornare.

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

Recuperare la lunghezza della coda

È possibile ottenere una stima del numero di messaggi in una coda. Il metodo GetProperties restituisce le proprietà della coda, incluso il numero dei messaggi. La proprietà ApproximateMessagesCount contiene il numero approssimativo di messaggi nella coda. Questo numero non è inferiore al numero effettivo di messaggi nella coda, ma potrebbe essere superiore.

Aggiungere questo codice alla fine del file 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}");

Ricevere messaggi da una coda

Scaricare i messaggi aggiunti precedentemente chiamando il metodo ReceiveMessagesAsync.

Aggiungere questo codice alla fine del file Program.cs :

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

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

Facoltativamente, è possibile specificare un valore per maxMessages, ovvero il numero di messaggi da recuperare dalla coda. Il valore predefinito è 1 messaggio e il massimo è 32 messaggi. È anche possibile specificare un valore per visibilityTimeout, che nasconde i messaggi da altre operazioni per il periodo di timeout. Il valore predefinito è 30 secondi.

Eliminare messaggi da una coda

Eliminare i messaggi dalla coda dopo l'elaborazione. In questo caso, l'elaborazione consiste semplicemente nella visualizzazione del messaggio nella console.

L'app viene sospesa per l'input dell'utente chiamando Console.ReadLine prima dell'elaborazione ed eliminazione dei messaggi. Verificare nel portale di Azure che le risorse siano state create correttamente, prima di eliminarle. Eventuali messaggi non eliminati in modo esplicito diventano nuovamente visibili nella coda per un'altra possibilità di elaborarli.

Aggiungere questo codice alla fine del file 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);
}

Eliminare una coda

Il codice seguente pulisce le risorse create dall'app eliminando la coda tramite il metodo DeleteAsync.

Aggiungere questo codice alla fine del file 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");

Eseguire il codice

Questa app crea e aggiunge tre messaggi a una coda di Azure. Il codice elenca i messaggi nella coda, quindi li recupera e li elimina, prima di eliminare definitivamente la coda.

Nella finestra della console passare alla directory dell'applicazione, quindi compilarla ed eseguirla.

dotnet build

dotnet run

L'output dell'app è simile all'esempio seguente:

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

Quando l'app viene sospesa prima della ricezione dei messaggi, controllare l'account di archiviazione nel portale di Azure. Verificare che i messaggi siano nella coda.

Premere il Enter tasto per ricevere ed eliminare i messaggi. Quando richiesto, premere di nuovo il Enter tasto per eliminare la coda e completare la demo.

Passaggi successivi

In questo argomento di avvio rapido si è appreso come creare una coda e aggiungervi messaggi usando codice .NET asincrono. Si è quindi appreso come visualizzare in anteprima, recuperare ed eliminare i messaggi. Infine, si è appreso come eliminare una coda di messaggi.

Per esercitazioni, esempi, guide di avvio rapido e altra documentazione, vedere:

Azure per sviluppatori .NET e .NET Core