Szybki start: biblioteka klienta usługi Azure Queue Storage dla platformy .NET

Wprowadzenie do biblioteki klienta usługi Azure Queue Storage dla platformy .NET. Azure Queue Storage to usługa do przechowywania dużej liczby komunikatów na potrzeby późniejszego pobierania i przetwarzania. Wykonaj następujące kroki, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

Dokumentacja interfejsu API — przykłady | pakietu kodu | źródłowego biblioteki (NuGet) |

Użyj biblioteki klienta usługi Azure Queue Storage dla platformy .NET, aby:

• Utwórz kolejkę
• Dodawanie komunikatów do kolejki
• Podgląd komunikatów w kolejce
• Aktualizowanie komunikatu w kolejce
• Pobieranie długości kolejki
• Odbieranie komunikatów z kolejki
• Usuwanie komunikatów z kolejki
• Usuwanie kolejki

Wymagania wstępne

• Subskrypcja platformy Azure — utwórz jedną bezpłatnie
• Konto usługi Azure Storage — tworzenie konta magazynu
• Bieżący zestaw .NET SDK dla systemu operacyjnego. Pamiętaj, aby pobrać zestaw SDK, a nie środowisko uruchomieniowe.

Konfigurowanie

Ta sekcja przeprowadzi Cię przez proces przygotowywania projektu do pracy z biblioteką klienta usługi Azure Queue Storage dla platformy .NET.

Tworzenie projektu

Utwórz aplikację .NET o nazwie QueuesQuickstart.

1. W oknie konsoli (takim jak cmd, PowerShell lub Bash) użyj dotnet new polecenia , aby utworzyć nową aplikację konsolową o nazwie QueuesQuickstart. To polecenie tworzy prosty projekt języka C# "hello world" z pojedynczym plikiem źródłowym o nazwie Program.cs.

   dotnet new console -n QueuesQuickstart
   

2. Przejdź do nowo utworzonego QueuesQuickstart katalogu.

   cd QueuesQuickstart
   

Instalowanie pakietów

Nadal w katalogu aplikacji zainstaluj bibliotekę klienta usługi Azure Queue Storage dla pakietu .NET przy użyciu dotnet add package polecenia .

dotnet add package Azure.Storage.Queues

Pakiet biblioteki klienta tożsamości platformy Azure jest również wymagany w przypadku połączeń bez hasła z usługami platformy Azure.

dotnet add package Azure.Identity

Konfigurowanie struktury aplikacji

1. Otwórz projekt w wybranym edytorze
2. Otwórz plik Program.cs
3. Zaktualizuj istniejący kod, aby był zgodny z następującymi elementami:

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

Uwierzytelnianie na platformie Azure

Żądania aplikacji do większości usług platformy Azure muszą być autoryzowane. DefaultAzureCredential Użycie klasy udostępnionej przez bibliotekę klienta tożsamości platformy Azure jest zalecanym podejściem do implementowania połączeń bez hasła z usługami platformy Azure w kodzie.

Możesz również autoryzować żądania do usług platformy Azure przy użyciu haseł, parametry połączenia lub innych poświadczeń bezpośrednio. Należy jednak zachować ostrożność przy użyciu tego podejścia. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać tych wpisów tajnych w niezabezpieczonej lokalizacji. Każdy, kto uzyskuje dostęp do hasła lub klucza tajnego, może się uwierzytelnić. DefaultAzureCredential oferuje ulepszone korzyści związane z zarządzaniem i zabezpieczeniami za pośrednictwem klucza konta, aby umożliwić uwierzytelnianie bez hasła. Obie opcje przedstawiono w poniższym przykładzie.

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

Model obiektów

Azure Queue Storage to usługa służąca do przechowywania dużej liczby komunikatów. Komunikat kolejki może mieć rozmiar do 64 KB. Kolejka może zawierać miliony komunikatów do całkowitego limitu pojemności konta magazynu. Kolejki są często używane do tworzenia listy prac w celu asynchronicznego przetwarzania. Usługa Queue Storage oferuje trzy typy zasobów:

• Konto magazynu: cały dostęp do usługi Azure Storage odbywa się za pośrednictwem konta magazynu. Aby uzyskać więcej informacji na temat kont magazynu, zobacz Omówienie konta magazynu
• Kolejka: kolejka zawiera zestaw komunikatów. Wszystkie komunikaty muszą być w kolejce. Pamiętaj, że nazwa kolejki może zawierać tylko małe litery. Informacje dotyczące nazewnictwa kolejek można znaleźć w temacie Naming Queues and Metadata (Nazewnictwo kolejek i metadanych).
• Komunikat: komunikat w dowolnym formacie, o maksymalnym rozmiarze 64 KB. Komunikat może pozostać w kolejce przez maksymalnie 7 dni. W przypadku wersji 2017-07-29 lub nowszej maksymalny czas wygaśnięcia może być dowolną liczbą dodatnią lub -1 wskazującą, że komunikat nie wygasa. Jeśli ten parametr zostanie pominięty, domyślny czas wygaśnięcia wynosi siedem dni.

Na poniższym diagramie przedstawiono relacje między tymi zasobami.

Użyj następujących klas platformy .NET, aby wchodzić w interakcje z tymi zasobami:

• QueueServiceClient: umożliwia QueueServiceClient zarządzanie wszystkimi kolejkami na koncie magazynu.
• QueueClient: Klasa QueueClient umożliwia zarządzanie pojedynczą kolejką i jej komunikatami oraz manipulowanie nimi.
• QueueMessageQueueMessage: Klasa reprezentuje poszczególne obiekty zwracane podczas wywoływania ReceiveMessages w kolejce.

Przykłady kodu

Te przykładowe fragmenty kodu pokazują, jak wykonać następujące akcje za pomocą biblioteki klienta usługi Azure Queue Storage dla platformy .NET:

• Autoryzowanie dostępu i tworzenie obiektu klienta
• Tworzenie kolejki
• Dodawanie komunikatów do kolejki
• Podgląd komunikatów w kolejce
• Aktualizowanie komunikatu w kolejce
• Pobieranie długości kolejki
• Odbieranie komunikatów z kolejki
• Usuwanie komunikatów z kolejki
• Usuwanie kolejki

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

Utwórz kolejkę

Za pomocą obiektu wywołaj QueueClient metodę CreateAsync , aby utworzyć kolejkę na koncie magazynu.

Dodaj ten kod na końcu metody Program.cs :

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

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

Dodawanie komunikatów do kolejki

Poniższy fragment kodu asynchronicznie dodaje komunikaty do kolejki, wywołując metodę SendMessageAsync . Zapisuje również zwrócony element SendReceipt z wywołania SendMessageAsync . Potwierdzenie jest używane do aktualizacji wiadomości w dalszej części programu.

Dodaj ten kod na końcu pliku 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");

Podgląd komunikatów w kolejce

Przyjrzyj się komunikatom w kolejce, wywołując metodę PeekMessagesAsync . Ta metoda pobiera jeden lub więcej komunikatów z przodu kolejki, ale nie zmienia widoczności komunikatu.

Dodaj ten kod na końcu pliku 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}");
}

Aktualizowanie komunikatu w kolejce

Zaktualizuj zawartość komunikatu, wywołując metodę UpdateMessageAsync . Ta metoda może zmienić limit czasu widoczności i zawartości komunikatu. Zawartość komunikatu musi być ciągiem zakodowanym w formacie UTF-8 o rozmiarze do 64 KB. Wraz z nową zawartością komunikatu przekaż wartości z zapisanego SendReceipt wcześniej kodu. Wartości SendReceipt identyfikują komunikat do zaktualizowania.

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

Pobieranie długości kolejki

Możesz uzyskać szacunkową liczbę komunikatów w kolejce. Metoda GetProperties zwraca właściwości kolejki, w tym liczbę komunikatów. Właściwość ApproximateMessagesCount zawiera przybliżoną liczbę komunikatów w kolejce. Ta liczba nie jest niższa niż rzeczywista liczba komunikatów w kolejce, ale może być wyższa.

Dodaj ten kod na końcu pliku 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}");

Odbieranie komunikatów z kolejki

Pobierz wcześniej dodane komunikaty, wywołując metodę ReceiveMessagesAsync .

Dodaj ten kod na końcu pliku Program.cs :

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

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

Opcjonalnie można określić wartość parametru maxMessages, czyli liczbę komunikatów do pobrania z kolejki. Wartość domyślna to 1 komunikat, a maksymalna to 32 komunikaty. Można również określić wartość parametru visibilityTimeout, która ukrywa komunikaty przed innymi operacjami w okresie przekroczenia limitu czasu. Wartość domyślna to 30 sekund.

Usuwanie komunikatów z kolejki

Usuń komunikaty z kolejki po ich przetworzeniu. W takim przypadku przetwarzanie po prostu wyświetla komunikat w konsoli programu .

Aplikacja wstrzymuje dane wejściowe użytkownika przez wywołanie Console.ReadLine metody , zanim przetworzy i usunie komunikaty. Sprawdź w witrynie Azure Portal , czy zasoby zostały utworzone poprawnie, zanim zostaną usunięte. Wszystkie komunikaty, które nie zostały jawnie usunięte, staną się widoczne w kolejce ponownie, aby można było je przetworzyć.

Dodaj ten kod na końcu pliku 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);
}

Usuwanie kolejki

Poniższy kod czyści zasoby utworzone przez aplikację przez usunięcie kolejki przy użyciu DeleteAsync metody .

Dodaj ten kod na końcu pliku 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");

Uruchamianie kodu

Ta aplikacja tworzy i dodaje trzy komunikaty do kolejki platformy Azure. Kod wyświetla listę komunikatów w kolejce, a następnie pobiera je i usuwa przed usunięciem kolejki.

W oknie konsoli przejdź do katalogu aplikacji, a następnie skompiluj i uruchom aplikację.

dotnet build

dotnet run

Dane wyjściowe aplikacji są podobne do następującego przykładu:

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

Gdy aplikacja wstrzymuje się przed odebraniem komunikatów, sprawdź konto magazynu w witrynie Azure Portal. Sprawdź, czy komunikaty znajdują się w kolejce.

Naciśnij klawisz , Enter aby odbierać i usuwać komunikaty. Po wyświetleniu monitu Enter naciśnij ponownie klawisz, aby usunąć kolejkę i zakończyć pokaz.

Następne kroki

W tym przewodniku Szybki start przedstawiono sposób tworzenia kolejki i dodawania do niej komunikatów przy użyciu asynchronicznego kodu platformy .NET. Następnie przedstawiono wgląd, pobieranie i usuwanie komunikatów. Na koniec przedstawiono sposób usuwania kolejki komunikatów.

Aby zapoznać się z samouczkami, przykładami, przewodnikami Szybki start i inną dokumentacją, odwiedź stronę:

• Aby uzyskać powiązane przykłady kodu korzystające z przestarzałych zestawów SDK platformy .NET w wersji 11.x, zobacz Przykłady kodu korzystające z platformy .NET w wersji 11.x.
• Aby dowiedzieć się więcej, zobacz biblioteki usługi Azure Storage dla platformy .NET.
• Aby uzyskać więcej przykładowych aplikacji usługi Azure Queue Storage, zobacz Bibliotekę klienta usługi Azure Queue Storage dla przykładów platformy .NET.
• Aby dowiedzieć się więcej na temat platformy .NET Core, zobacz Get started with .NET in 10 minutes (Rozpoczynanie pracy z platformą .NET w 10 minut).