使用舊版 WindowsAzure.ServiceBus .NET Framework 程式庫搭配 AMQP 1.0

  • 發行項

注意

本文適用於想要改用相同套件內的 AMQP 的現有 WindowsAzure.ServiceBus 套件使用者。 雖然此套件會繼續獲得重大錯誤修正，直到 2026 年 9 月 30 日，但仍強烈建議升級至新的 Azure.Messaging.ServiceBus 套件，該套件自 2020 年 11 月起提供，且預設支援 AMQP。

在 2026 年 9 月 30 日，我們將淘汰不符合 Azure SDK 準則的 Azure 服務匯流排 SDK 程式庫 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus。 我們也將結束 SBMP 通訊協定的支援，因此您將無法在 2026 年 9 月 30 日之後再使用此通訊協定。 請在該日期之前移轉至最新的 Azure SDK 程式庫，該程式庫提供重要的安全性更新和改進的功能。

雖然較舊的程式庫仍可在 2026 年 9 月 30 日之後使用，但這些程式庫將無法繼續收到 Microsoft 的官方支援和更新。 如需詳細資訊，請參閱支援淘汰公告。

根據預設，WindowsAzure.ServiceBus 套件會使用名為服務匯流排傳訊通訊協定 (SBMP) 的專用 SOAP 型通訊協定與服務匯流排服務通訊。 在 2.1 版中已新增 AMQP 1.0 的支援，建議您使用該版本，而不是預設通訊協定。

若要使用 AMQP 1.0 (而非預設的通訊協定)，必須明確設定服務匯流排連接字串，或透過 TransportType 選項在用戶端建構函式中設定。 除了這項變更之外，在使用 AMQP 1.0 時，應用程式程式碼會維持不變。

有幾項 API 功能在使用 AMQP 時不受支援。 不支援的功能皆列在行為差異一節中。 在使用 AMQP 時，某些進階組態設定亦有不同的意義。

設定連接字串以使用 AMQP 1.0

透過 ;TransportType=Amqp 附加連接字串，以指示用戶端使用 AMQP 1.0 連線至服務匯流排。 例如，

Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=Amqp

其中 namespace 和 SAS key 是當您建立服務匯流排命名空間時，取自 Azure 入口網站。 如需詳細資訊，請參閱使用 Azure 入口網站建立服務匯流排命名空間。

透過 WebSocket 的 AMQP

若要透過 WebSockets 使用 AMQP，請將連接字串中的 TransportType 設定為 AmqpWebSockets。 例如： Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=AmqpWebSockets 。

訊息序列化

使用預設通訊協定時，.NET 用戶端程式庫的預設序列化行為是使用 DataContractSerializer 類型來序列化用戶端程式庫與服務匯流排服務之間傳輸的 BrokeredMessage 執行個體。 使用 AMQP 傳輸模式時，用戶端程式庫會使用 AMQP 類型系統，將代理訊息序列化為 AMQP 訊息。 此序列化作業讓可能在不同平台上執行的接收應用程式 (例如使用 JMS API 來存取服務匯流排的 Java 應用程式) 能夠接收和解譯此訊息。

當您建構 BrokeredMessage 執行個體時，您可以提供 .NET 物件做為建構函式的參數，進而做為訊息的本文。 如果是可以對應至 AMQP 基本類型的物件，本文會序列化為 AMQP 資料類型。 如果物件不能直接對應至 AMQP 基本類型 (也就是，應用程式所定義的自訂類型)，則會使用 DataContractSerializer 序列化物件，並且在 AMQP 資料訊息中傳送序列化的位元組。

若要促進與非 .NET 用戶端的互通性，在訊息本文中僅使用可直接序列化為 AMQP 類型的 .NET 類型。 下表詳細說明這些類型及對應的 AMQP 類型系統。

.NET 主體物件類型 對應的 AMQP 類型 AMQP 主體區段類型
bool boolean AMQP 值
byte ubyte AMQP 值
ushort ushort AMQP 值
uint uint AMQP 值
ulong ulong AMQP 值
sbyte byte AMQP 值
short short AMQP 值
int int AMQP 值
long long AMQP 值
FLOAT float AMQP 值
double double AMQP 值
decimal decimal128 AMQP 值
char char AMQP 值
Datetime timestamp AMQP 值
GUID uuid AMQP 值
byte[] BINARY AMQP 值
string string AMQP 值
System.Collections.IList 清單 AMQP 值︰集合中包含的項目只能是在此表格中定義的項目。
System.Array 陣列 AMQP 值︰集合中包含的項目只能是在此表格中定義的項目。
System.Collections.IDictionary map AMQP 值︰集合中包含的項目只能是在此表格中定義的項目。注意︰僅支援 String 索引鍵。
URI 描述的 string (請參閱下表) AMQP 值
DateTimeOffset 描述的 long (請參閱下表) AMQP 值
TimeSpan 描述的 long (請參閱下表) AMQP 值
串流 binary AMQP 資料 (可能有多個)。 Data 區段包含從 Stream 物件讀取的原始位元組。
其他物件 binary AMQP 資料 (可能有多個)。 包含使用 DataContractSerializer 或應用程式所提供序列化程式之物件的序列化二進位資料。
.NET 型別 對應的 AMQP 描述類型 備註
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

行為的差異

相較於預設通訊協定，使用 AMQP 時，WindowsAzure.ServiceBus API 的行為會有些許差異：

  • OperationTimeout 屬性會被忽略。
  • MessageReceiver.Receive(TimeSpan.Zero) 會實作為 MessageReceiver.Receive(TimeSpan.FromSeconds(10))。
  • 只有最初收到訊息的訊息接收者能夠以鎖定權杖完成訊息。

控制 AMQP 通訊協定設定

.NET API 會公開數個可控制 AMQP 通訊協定行為的設定：

下一步

準備好進行深入了解嗎？ 請造訪下列連結：