Mulai cepat: Pustaka klien Azure Queue Storage untuk .NET

  • Artikel

Mulai menggunakan pustaka klien Azure Queue Storage untuk .NET. Azure Queue Storage adalah layanan untuk menyimpan pesan dalam jumlah besar untuk nantinya diambil dan diproses. Ikuti langkah-langkah berikut untuk menginstal paket dan mencoba contoh kode untuk tugas dasar.

Dokumentasi referensi API | Kode sumber pustaka | Paket (NuGet) | Sampel

Gunakan pustaka klien Azure Queue Storage untuk .NET untuk:

  • Membuat antrean
  • Tambahkan pesan ke antrean
  • Intip pesan dalam antrean
  • Perbarui pesan dalam antrean
  • Dapatkan panjang antrean
  • Terima pesan dari antrean
  • Hapus pesan dari antrean
  • Menghapus antrean

Prasyarat

Menyiapkan

Bagian ini memandu Anda menyiapkan proyek untuk bekerja dengan pustaka klien Azure Queue Storage untuk .NET.

Membuat proyek

Buat aplikasi .NET bernama QueuesQuickstart.

  1. Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan perintah dotnet new untuk membuat aplikasi konsol baru dengan nama QueuesQuickstart. Perintah ini membuat proyek C# "halo dunia" sederhana dengan satu file sumber bernama Program.cs.

    dotnet new console -n QueuesQuickstart

  2. Beralih ke direktori QueuesQuickstart yang baru dibuat.

    cd QueuesQuickstart

Menginstal paket

Saat masih dalam direktori aplikasi, instal pustaka klien Azure Queue Storage untuk paket .NET dengan menggunakan perintah dotnet add package.

dotnet add package Azure.Storage.Queues

Paket pustaka klien Azure Identity juga diperlukan untuk koneksi tanpa kata sandi ke layanan Azure.

dotnet add package Azure.Identity

Menyiapkan kerangka kerja aplikasi

  1. Buka proyek di editor pilihan Anda
  2. Buka file Program.cs
  3. Perbarui kode yang ada agar sesuai dengan yang berikut ini:
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

Mengautentikasi Azure

Permintaan aplikasi ke sebagian besar layanan Azure harus diotorisasi. Menggunakan kelas yang DefaultAzureCredential disediakan oleh pustaka klien Azure Identity adalah pendekatan yang direkomendasikan untuk menerapkan koneksi tanpa kata sandi ke layanan Azure dalam kode Anda.

Anda juga dapat mengotorisasi permintaan ke layanan Azure menggunakan kata sandi, string koneksi, atau kredensial lainnya secara langsung. Namun, pendekatan ini harus digunakan dengan hati-hati. Pengembang harus rajin untuk tidak pernah mengekspos rahasia ini di lokasi yang tidak aman. Siapa pun yang mendapatkan akses ke kata sandi atau kunci rahasia dapat mengautentikasi. DefaultAzureCredential menawarkan keuntungan pengelolaan dan keamanan yang ditingkatkan melalui kunci akun untuk memungkinkan autentikasi tanpa kata sandi. Kedua opsi diperlihatkan dalam contoh berikut.

DefaultAzureCredential adalah kelas yang disediakan oleh pustaka klien Azure Identity untuk .NET. Untuk mempelajari selengkapnya tentang DefaultAzureCredential, lihat gambaran umum DefaultAzureCredential. DefaultAzureCredential mendukung beberapa metode autentikasi dan menentukan metode autentikasi yang harus digunakan saat runtime bahasa umum. Pendekatan ini memungkinkan aplikasi Anda menggunakan metode autentikasi yang berbeda di lingkungan yang berbeda (lokal vs. produksi) tanpa menerapkan kode spesifik per lingkungan.

Misalnya, aplikasi Anda dapat mengautentikasi menggunakan kredensial masuk Visual Studio Saat mengembangkan secara lokal, lalu menggunakan identitas terkelola setelah disebarkan ke Azure. Tidak diperlukan perubahan kode untuk transisi ini.

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang mengakses data antrean memiliki izin yang benar. Anda memerlukan Kontributor Data Antrean Penyimpanan untuk membaca dan menulis data antrean. Untuk menetapkan sendiri peran ini, Anda harus diberi peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write . Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Anda dapat mempelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan.

Dalam skenario ini, Anda akan menetapkan izin ke akun pengguna, yang tercakup ke akun penyimpanan, untuk mengikuti Prinsip Hak Istimewa Paling Rendah. Praktik ini hanya memberi pengguna izin minimum yang diperlukan dan menciptakan lingkungan produksi yang lebih aman.

Contoh berikut akan menetapkan peran Kontributor Data Antrean Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data antrean di akun penyimpanan Anda.

Penting

Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure, tetapi dalam kasus yang jarang terjadi mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

  1. Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Di halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

A screenshot showing how to assign a role.

  1. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Kontributor Data Antrean Penyimpanan dan pilih hasil yang cocok lalu pilih Berikutnya.

  2. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  3. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  4. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Model objek

Azure Queue Storage adalah layanan untuk menyimpan pesan dalam jumlah besar. Pesan antrean dapat berukuran hingga 64 KB. Antrean dapat berisi jutaan pesan, hingga mencapai batas kapasitas total dari akun penyimpanan. Antrean umumnya digunakan untuk membuat backlog pekerjaan untuk diproses secara asinkron. Queue Storage menawarkan tiga jenis sumber daya:

  • Akun penyimpanan: Semua akses ke Azure Storage dilakukan melalui akun penyimpanan. Untuk informasi selengkapnya tentang akun penyimpanan, lihat Gambaran umum akun penyimpanan
  • Antrean: Antrean berisi sekumpulan pesan. Semua pesan harus dalam antrean. Perhatikan bahwa nama antrean harus ditulis dengan huruf kecil semua. Untuk mendapatkan informasi tentang penamaan antrean, lihat Penamaan Antrean dan Metadata.
  • Pesan: Pesan, dalam format apa pun, dapat mencapai ukuran 64 KB. Pesan dapat tetap dalam antrean selama maksimal 7 hari. Untuk versi 29-07-2017 atau yang lebih baru, waktu untuk aktif maksimum dapat berupa angka positif apa pun, atau -1 yang menunjukkan bahwa pesan belum kedaluwarsa. Jika parameter ini dihilangkan, time-to-live default adalah tujuh hari.

Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.

Diagram of Queue storage architecture

Gunakan kelas .NET berikut untuk berinteraksi dengan sumber daya ini:

  • QueueServiceClient: QueueServiceClient memungkinkan Anda mengelola semua antrean di akun penyimpanan Anda.
  • QueueClient: Kelas QueueClient memungkinkan Anda mengelola dan memanipulasi antrean individual dan pesannya.
  • QueueMessage: Kelas QueueMessage mewakili objek individual yang dikembalikan saat memanggil ReceiveMessages dalam antrean.

Contoh kode

Contoh cuplikan kode ini menunjukkan cara melakukan tindakan berikut dengan pustaka klien Azure Queue Storage untuk .NET:

Mengotorisasi akses dan membuat objek klien

Untuk pengembangan lokal, pastikan Anda diautentikasi dengan akun Microsoft Entra yang sama dengan yang Anda tetapkan perannya. Anda dapat mengautentikasi melalui alat pengembangan populer, seperti Azure CLI atau Azure PowerShell. Alat pengembangan yang dapat Anda autentikasi bervariasi di seluruh bahasa.

Masuk ke Azure melalui Azure CLI menggunakan perintah berikut:

az login

Setelah diautentikasi, Anda dapat membuat dan mengotorisasi QueueClient objek menggunakan DefaultAzureCredential untuk mengakses data antrean di akun penyimpanan. DefaultAzureCredential secara otomatis menemukan dan menggunakan akun yang Anda gunakan untuk masuk di langkah sebelumnya.

Untuk mengotorisasi menggunakan DefaultAzureCredential, pastikan Anda telah menambahkan paket Azure.Identity , seperti yang dijelaskan dalam Menginstal paket. Selain itu, pastikan untuk menambahkan direktif penggunaan untuk Azure.Identity namespace dalam file Program.cs :

using Azure.Identity;

Selanjutnya, tentukan nama untuk antrean dan buat instans QueueClient kelas, menggunakan DefaultAzureCredential untuk otorisasi. Kami menggunakan objek klien ini untuk membuat dan berinteraksi dengan sumber daya antrean di akun penyimpanan.

Penting

Nama antrean hanya boleh berisi huruf kecil, angka, dan tanda hubung, dan harus dimulai dengan huruf atau angka. Setiap tanda hubung harus diawali dan diikuti dengan karakter non-tanda hubung. Panjang nama harus antara 3 hingga 63 karakter. Untuk informasi selengkapnya, lihat Penamaan antrean dan metadata.

Tambahkan kode berikut ke akhir file Program.cs . Pastikan untuk mengganti <storage-account-name> nilai tempat penampung:

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

Catatan

Pesan yang QueueClient dikirim menggunakan kelas harus dalam format yang dapat disertakan dalam permintaan XML dengan pengodean UTF-8. Anda dapat secara opsional mengatur opsi MessageEncoding ke Base64 untuk menangani pesan yang tidak sesuai.

Membuat antrean

QueueClient Dengan menggunakan objek , panggil CreateAsync metode untuk membuat antrean di akun penyimpanan Anda.

Tambahkan kode ini ke akhir metode Program.cs :

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

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

Tambahkan pesan ke antrean

Cuplikan kode berikut menambahkan pesan ke antrean dengan memanggil metode SendMessageAsync secara asinkron. Kode tersebut juga menyimpan SendReceipt yang dikembalikan dari panggilan SendMessageAsync. Hasilnya nanti digunakan untuk memperbarui isi pesan dalam program.

Tambahkan kode ini ke akhir 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");

Intip pesan dalam antrean

Lihat sekilas pesan dalam antrean dengan memanggil metode PeekMessagesAsync. Metode ini mengambil satu atau beberapa pesan dari depan antrean tanpa mengubah visibilitas pesan.

Tambahkan kode ini ke akhir 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}");
}

Perbarui pesan dalam antrean

Perbarui konten pesan dengan memanggil metode UpdateMessageAsync. Metode ini dapat mengubah visibilitas batas waktu dan isi pesan. Isi pesan harus merupakan string berkode UTF-8 yang berukuran hingga 64 KB. Bersama dengan isi baru untuk pesan, berikan nilai dari SendReceipt yang disimpan sebelumnya dalam kode itu. Nilai SendReceipt mengenali pesan mana yang akan diperbarui.

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

Dapatkan panjang antrean

Anda bisa mendapat estimasi jumlah pesan dalam antrean. Metode GetProperties ini memberi properti antrean termasuk jumlah pesan. Properti ApproximateMessagesCount berisi perkiraan jumlah pesan dalam antrean. Jumlah ini tidak lebih rendah dari jumlah pesan aktual dalam antrean, tetapi bisa lebih tinggi.

Tambahkan kode ini ke akhir 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}");

Terima pesan dari antrean

Unduh pesan yang ditambahkan sebelumnya dengan memanggil metode ReceiveMessagesAsync.

Tambahkan kode ini ke akhir file Program.cs :

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

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

Anda dapat secara opsional menentukan nilai untuk maxMessages, yang merupakan jumlah pesan yang akan diambil dari antrean. Defaultnya adalah 1 pesan dan maksimum adalah 32 pesan. Anda juga dapat menentukan nilai untuk visibilityTimeout, yang menyembunyikan pesan dari operasi lain untuk periode batas waktu. Defaultnya adalah 30 detik.

Hapus pesan dari antrean

Hapus pesan dari antrean setelah diproses. Dalam kasus ini, pemrosesan hanya menampilkan pesan di konsol.

Aplikasi berhenti sejenak untuk input pengguna dengan memanggil Console.ReadLine sebelum memproses dan menghapus pesan. Pastikan di portal Microsoft Azure Anda bahwa sumber daya dibuat dengan benar, sebelum dihapus. Setiap pesan yang tidak dihapus secara eksplisit akhirnya menjadi terlihat dalam antrean lagi untuk kesempatan lain untuk memprosesnya.

Tambahkan kode ini ke akhir 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);
}

Menghapus antrean

Kode berikut membersihkan sumber daya yang dibuat aplikasi dengan menghapus antrean menggunakan metode DeleteAsync.

Tambahkan kode ini ke akhir 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");

Menjalankan kode

Aplikasi ini membuat dan menambahkan tiga pesan ke antrean Azure. Kode mencantumkan pesan dalam antrean, lalu mengambil dan menghapusnya, sebelum akhirnya menghapus antrean.

Di jendela konsol, navigasikan ke direktori aplikasi, lalu buat dan jalankan aplikasi.

dotnet build

dotnet run

Output aplikasi mirip dengan contoh berikut:

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

Saat aplikasi berhenti sejenak sebelum menerima pesan, periksa akun penyimpanan Anda di portal Microsoft Azure. Pastikan pesan berada dalam antrean.

Tekan tombol Enter untuk menerima dan menghapus pesan. Ketika diminta, tekan tombol Enter lagi untuk menghapus antrean dan menyelesaikan demo.

Langkah berikutnya

Dalam mulai cepat ini, Anda belajar cara membuat antrean dan menambahkan pesan ke dalamnya menggunakan kode .NET asinkron. Kemudian Anda belajar mengintip, mengambil, dan menghapus pesan. Terakhir, Anda belajar cara menghapus antrean pesan.

Untuk tutorial, sampel, mulai cepat, dan dokumentasi lainnya, kunjungi:

Azure untuk pengembang .NET dan .NET Core