Freigeben über


Verwenden der .NET Framework-Legacybibliothek „WindowsAzure.ServiceBus“ mit AMQP 1.0

Hinweis

Dieser Artikel richtet sich an vorhandene Benutzer des WindowsAzure.ServiceBus-Pakets, die zur Verwendung von AMQP innerhalb desselben Pakets wechseln möchten. Dieses Paket wird zwar weiterhin kritische Fehlerbehebungen bis 30. September 2026 erhalten, es wird jedoch dringend empfohlen, ein Upgrade auf das neue Azure.Messaging.ServiceBus-Paket durchzuführen, das ab November 2020 verfügbar ist und AMQP standardmäßig unterstützt.

Am 30. September 2026 werden die Azure Service Bus SDK-Bibliotheken „WindowsAzure.ServiceBus“, „Microsoft.Azure.ServiceBus“ und „com.microsoft.azure.servicebus“ eingestellt, da sie nicht den Azure SDK-Richtlinien entsprechen. Außerdem wird die Unterstützung des SBMP-Protokolls beendet, sodass Sie dieses Protokoll nach dem 30. September 2026 nicht mehr verwenden können. Migrieren Sie vor diesem Datum zu den neuesten Azure SDK-Bibliotheken, die wichtige Sicherheitsupdates und verbesserte Funktionen bieten.

Obwohl die älteren Bibliotheken noch über den 30. September 2026 hinaus verwendet werden können, erhalten sie keinen offiziellen Support und keine Updates mehr von Microsoft. Weitere Informationen finden Sie in der Ankündigung der Supporteinstellung.

Das WindowsAzure.ServiceBus-Paket kommuniziert standardmäßig mit dem Service Bus-Dienst mithilfe eines dedizierten SOAP-basierten Protokolls namens Service Bus Messaging Protocol (SBMP). In Version 2.1 wurde die Unterstützung für AMQP 1.0 hinzugefügt, das anstelle des Standardprotokolls verwendet werden sollte.

Wenn Sie anstatt des Standardprotokolls AMQP 1.0 verwenden möchten, ist eine explizite Konfiguration der Service Bus-Verbindungszeichenfolge oder der Clientkonstruktoren über die Option TransportType erforderlich. Abgesehen von dieser Änderung bleibt der Anwendungscode bei Verwendung von AMQP 1.0 unverändert.

Einige wenige API-Features werden bei Verwendung von AMQP nicht unterstützt. Diese nicht unterstützten Features finden Sie im Abschnitt Verhaltensunterschiede. Darüber hinaus haben einige der erweiterten Konfigurationseinstellungen eine unterschiedliche Bedeutung, wenn AMQP zum Einsatz kommt.

Konfigurieren einer Verbindungszeichenfolge zur Verwendung von AMQP 1.0

Fügen Sie die Verbindungszeichenfolge mit ;TransportType=Amqp an, um den Client anzuweisen, mithilfe von AMQP 1.0 eine Verbindung mit der Service Bus-Instanz herzustellen. Beispiel:

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

namespace und SAS key werden aus dem Azure-Portal abgerufen, wenn Sie einen Service Bus-Namespace erstellen. Weitere Informationen finden Sie unter Erstellen eines Service Bus-Namespace mithilfe des Azure-Portals.

AMQP über WebSockets

Wenn Sie AMQP über WebSockets verwenden möchten, legen Sie TransportType in der Verbindungszeichenfolge auf AmqpWebSockets fest. Beispiel: Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=AmqpWebSockets.

Nachrichtenserialisierung

Bei Verwendung des Standardprotokolls sieht das Standardserialisierungsverhalten der .NET-Clientbibliothek die Verwendung des DataContractSerializer-Typs zum Serialisieren einer BrokeredMessage-Instanz für die Übertragung zwischen der Clientbibliothek und dem Service Bus-Dienst vor. Bei Verwendung des AMQP-Transportmodus verwendet die Clientbibliothek das AMQP-Typsystem für die Serialisierung der im Broker gespeicherten Nachricht in eine AMQP-Nachricht. Diese Serialisierung ermöglicht, dass die Nachricht von einer empfangenden Anwendung empfangen und interpretiert wird, die möglicherweise auf einer anderen Plattform ausgeführt wird, z. B. einer Java-Anwendung, die die JMS-API für den Zugriff auf Service Bus verwendet.

Wenn Sie eine BrokeredMessage-Instanz erstellen, können Sie ein .NET-Objekt als Parameter für den Konstruktor bereitstellen, der als Text der Nachricht dient. Für Objekte, die primitiven AMQP-Typen zugeordnet werden können, wird der Text in AMQP-Datentypen serialisiert. Wenn das Objekt nicht direkt einem primitiven AMQP-Typ, d.h. einem von der Anwendung definierten benutzerdefinierten Typ, zugeordnet werden kann, wird das Objekt mithilfe von DataContractSerializer serialisiert, und die serialisierten Bytes werden in einer AMQP-Datennachricht gesendet.

Um die Interoperabilität mit Nicht-.NET-Clients zu erleichtern, verwenden Sie nur .NET-Typen, die für den Text der Nachricht direkt in AMQP-Typen serialisiert werden können. Die folgende Tabelle enthält diese Typen und die entsprechende Zuordnung zum AMQP-Typsystem.

.NET Body-Objekttyp Zugeordneter AMQP-Typ AMQP Body-Abschnittstyp
bool boolean AMQP Value
byte ubyte AMQP Value
ushort ushort AMQP Value
uint uint AMQP Value
ulong ulong AMQP Value
sbyte byte AMQP Value
short short AMQP Value
INT INT AMQP Value
long long AMQP Value
float float AMQP Value
double double AMQP Value
Decimal decimal128 AMQP Value
char char AMQP Value
Datetime timestamp AMQP Value
Guid uuid AMQP Value
byte[] BINARY AMQP Value
Zeichenfolge Zeichenfolge AMQP Value
System.Collections.IList list AMQP Value: Diese Auflistung kann nur Elemente enthalten, die in dieser Tabelle definiert sind.
System.Array array AMQP Value: Diese Auflistung kann nur Elemente enthalten, die in dieser Tabelle definiert sind.
System.Collections.IDictionary map AMQP Value: Diese Auflistung kann nur Elemente enthalten, die in dieser Tabelle definiert sind. Hinweis: nur "String"-Schlüssel werden unterstützt.
Uri Beschriebene Zeichenfolge (siehe die folgende Tabelle) AMQP Value
DateTimeOffset Lange Beschreibung (siehe die folgende Tabelle) AMQP Value
TimeSpan Lange Beschreibung (siehe die folgende Tabelle) AMQP Value
STREAM BINARY AMQP Data (können mehrere sein). Die "Data"-Abschnitte enthalten die rohen Bytes, die aus dem "Stream"-Objekt gelesen.
Other Object BINARY AMQP Data (können mehrere sein). Enthält die serialisierten Binärdaten des Objekts, das "DataContractSerializer" oder einen von der Anwendung bereitgestellten Serialisierer verwendet.
.NET-Typ Zugeordneter beschriebener AMQP-Typ Notizen
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

Verhaltensunterschiede

Bei der Verwendung von AMQP gibt es im Vergleich zum Standardprotokoll einige kleine Unterschiede im Verhalten der WindowsAzure.ServiceBus-API:

  • Die OperationTimeout-Eigenschaft wird ignoriert.
  • MessageReceiver.Receive(TimeSpan.Zero) wird als MessageReceiver.Receive(TimeSpan.FromSeconds(10)) implementiert.
  • Das Abschließen von Nachrichten durch Sperrtoken kann nur von den Nachrichtenempfängern durchgeführt werden, die die Nachrichten ursprünglich erhalten haben.

Steuern von AMQP-Protokolleinstellungen

Die .NET-APIs stellen mehrere Einstellungen zum Steuern des Verhaltens des AMQP-Protokolls zur Verfügung:

Nächste Schritte

Möchten Sie mehr erfahren? Nutzen Sie die folgenden Links: