Menggunakan pustaka kerangka kerja .NET WindowsAzure.ServiceBus versi warisan dengan AMQP 1.0
Catatan
Artikel ini ditujukan bagi pengguna lama dari paket WindowsAzure.ServiceBus yang ingin beralih ke AMQP di dalam paket yang sama. Meskipun paket ini akan terus menerima perbaikan bug penting hingga 30 September 2026, kami sangat mendorong untuk meningkatkan ke paket Azure.Messaging.ServiceBus baru sebagai gantinya yang tersedia per November 2020 dan yang mendukung AMQP secara default.
Pada 30 September 2026, kami akan menghentikan pustaka Azure Bus Layanan SDK WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus, dan com.microsoft.azure.servicebus, yang tidak sesuai dengan panduan Azure SDK. Kami juga akan mengakhiri dukungan protokol SBMP, sehingga Anda tidak akan lagi dapat menggunakan protokol ini setelah 30 September 2026. Migrasikan ke pustaka Azure SDK terbaru, yang menawarkan pembaruan keamanan penting dan kemampuan yang ditingkatkan, sebelum tanggal tersebut.
Meskipun pustaka lama masih dapat digunakan melebihi 30 September 2026, pustaka tersebut tidak akan lagi menerima dukungan dan pembaruan resmi dari Microsoft. Untuk informasi selengkapnya, lihat pengumuman penghentian dukungan.
Secara default, paket WindowsAzure.ServiceBus berkomunikasi dengan layanan Azure Service Bus menggunakan protokol khusus berbasis SOAP yang disebut Service Bus Messaging Protocol (SBMP). Pada versi 2.1, AMQP 1.0, yang kami sarankan untuk digunakan daripada protokol default, mulai didukung.
Untuk beralih dari protokol default menjadi AMQP 1.0, diperlukan konfigurasi eksplisit pada string koneksi Service Bus atau di konstruktor klien melalui opsi TransportType. Selain perubahan ini, kode aplikasi tetap tidak berubah saat menggunakan AMQP 1.0.
Ada beberapa fitur API yang tidak didukung saat menggunakan AMQP. Fitur yang tidak didukung ini tercantum di bagian Perbedaan perilaku. Beberapa pengaturan konfigurasi lanjutan juga memiliki arti yang berbeda saat menggunakan AMQP.
Mengonfigurasi string koneksi untuk menggunakan AMQP 1.0
Tambahkan string koneksi Anda dengan ;TransportType=Amqp guna menginstruksikan klien untuk membuat koneksi ke Service Bus menggunakan AMQP 1.0.
Contohnya,
Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=Amqp
Di mana namespace dan SAS key didapatkan dari portal Microsoft Azure saat Anda membuat namespace Bus Layanan. Untuk informasi selengkapnya, lihat Buat namespace Bus Layanan menggunakan portal Azure.
AMQP melalui WebSocket
Untuk menggunakan AMQP melalui WebSockets, atur TransportType dalam string koneksi ke AmqpWebSockets Sebagai contoh: Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=AmqpWebSockets.
Serialisasi pesan
Saat menggunakan protokol default, perilaku serialisasi default dari pustaka klien .NET adalah menggunakan jenis DataContractSerializer untuk membuat serialisasi instans BrokeredMessage sebagai transportasi antara pustaka klien dan layanan Bus Layanan. Saat menggunakan mode transportasi AMQP, pustaka klien meggunakan sistem jenis AMQP untuk serialisasi dari pesan broker menjadi pesan AMQP. Serialisasi ini memungkinkan pesan untuk diterima dan diinterpretasikan oleh aplikasi penerima yang berpotensi berjalan di platform yang berbeda, misalnya, aplikasi Java yang menggunakan API JMS untuk mengakses Bus Layanan.
Saat Anda menyusun instans BrokeredMessage, Anda dapat memberikan objek .NET sebagai parameter ke konstruktor untuk dijadikan isi pesan. Untuk objek yang dapat dipetakan ke jenis primitif AMQP, isi pesannya diserialisasikan ke dalam jenis data AMQP. Jika objek tersebut tidak dapat langsung dipetakan ke dalam jenis primitif AMQP; yaitu, jenis khusus yang ditentukan oleh aplikasi, kemudian objek tersebut diserialisasikan menggunakan DataContractSerializer, dan byte serial dikirim dalam pesan data AMQP.
Untuk memfasilitasi interoperabilitas dengan klien non-.NET, gunakan hanya jenis .NET yang dapat diserialisasikan langsung ke jenis AMQP untuk isi pesan. Tabel berikut akan merincikan jenis-jenis tersebut dan pemetaan yang sesuai dengan sistem jenis AMQP.
| Jenis Objek Isi .NET | Jenis AMQP yang Dipetakan | Jenis Bagian Isi AMQP |
|---|---|---|
| bool | Boolean | Nilai AMQP |
| byte | ubyte | Nilai AMQP |
| ushort | ushort | Nilai AMQP |
| uint | uint | Nilai AMQP |
| ulong | ulong | Nilai AMQP |
| sbyte | byte | Nilai AMQP |
| pendek | pendek | Nilai AMQP |
| int | int | Nilai AMQP |
| long | long | Nilai AMQP |
| float | float | Nilai AMQP |
| ganda | ganda | Nilai AMQP |
| desimal | decimal128 | Nilai AMQP |
| char | char | Nilai AMQP |
| WaktuTanggal | rentang waktu | Nilai AMQP |
| Guid | uuid | Nilai AMQP |
| byte[] | biner | Nilai AMQP |
| string | string | Nilai AMQP |
| System.Collections.IList | list | Nilai AMQP: item yang terdapat dalam koleksi hanya item yang ditentukan dalam tabel ini. |
| System.Array | array | Nilai AMQP: item yang terdapat dalam koleksi hanya item yang ditentukan dalam tabel ini. |
| System.Collections.IDictionary | peta | Nilai AMQP: item yang terdapat dalam koleksi hanya item yang ditentukan dalam tabel ini.Catatan: hanya kunci String yang didukung. |
| Uri | String yang dijelaskan(lihat tabel berikut ini) | Nilai AMQP |
| DateTimeOffset | Panjang yang dijelaskan(lihat tabel berikut) | Nilai AMQP |
| TimeSpan | Panjang yang dijelaskan(lihat tabel berikut) | Nilai AMQP |
| Stream | biner | Data AMQP (mungkin banyak) Bagian Data berisikan byte mentah yang dibaca dari objek Stream. |
| Objek Lainnya | biner | Data AMQP (mungkin banyak) Berisi biner berseri dari objek yang menggunakan DataContractSerializer atau serializer yang disediakan oleh aplikasi. |
| Jenis .NET | Jenis yang Dijelaskan AMQP yang Dipetakan | Catatan |
|---|---|---|
| Uri | <type name=”uri” class=restricted source=”string”> <descriptor name=”com.microsoft:uri” /></type> |
Uri.AbsoluteUri |
| DateTimeOffset | <type name=”datetime-offset” class=restricted source=”long”> <descriptor name=”com.microsoft:datetime-offset” /></type> |
DateTimeOffset.UtcTicks |
| TimeSpan | <type name=”timespan” class=restricted source=”long”> <descriptor name=”com.microsoft:timespan” /></type> |
TimeSpan.Ticks |
Perbedaan perilaku
Ada beberapa perbedaan kecil pada perilaku API WindowsAzure.ServiceBus saat menggunakan AMQP dibandingkan dengan saat menggunakan protokol default:
- Properti OperationTimeout diabaikan.
MessageReceiver.Receive(TimeSpan.Zero)diterapkan sebagaiMessageReceiver.Receive(TimeSpan.FromSeconds(10)).- Menyelesaikan pesan dengan token kunci hanya dapat dilakukan oleh penerima pesan yang pertama kali menerima pesan.
Kontrol pengaturan protokol AMQP
API .NET memperlihatkan beberapa pengaturan untuk mengontrol perilaku protokol AMQP:
- MessageReceiver.PrefetchCount: Mengontrol kredit awal yang diterapkan ke tautan. Defaultnya adalah 0.
- MessagingFactorySettings.AmqpTransportSettings.MaxFrameSize: Mengontrol ukuran bingkai AMQP maksimum yang ditawarkan selama negoisasi pada waktu buka koneksi. Defaultnya adalah 65.536 byte.
- MessagingFactorySettings.AmqpTransportSettings.BatchFlushInterval: Jika transfer dapat dikelompokkan, nilai ini menentukan penundaan maksimum untuk pengiriman disposisi. Diwarisi oleh pengirim/penerima secara default. Pengirim/penerima individu dapat mengganti default, yaitu 20 milidetik.
- MessagingFactorySettings.AmqpTransportSettings.UseSslStreamSecurity: Mengontrol apakah koneksi AMQP dibuat melalui koneksi TLS. Defaultnya adalah true
Langkah berikutnya
Siap mempelajari lebih lanjut? Kunjungi tautan berikut:
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk