Używanie starszej biblioteki platformy .NET Framework windowsAzure.ServiceBus z programem AMQP 1.0

  • Artykuł

Uwaga

Ten artykuł dotyczy istniejących użytkowników pakietu WindowsAzure.ServiceBus, którzy chcą przełączyć się na korzystanie z protokołu AMQP w ramach tego samego pakietu. Chociaż ten pakiet będzie nadal otrzymywać krytyczne poprawki błędów do 30 września 2026 r., zdecydowanie zachęcamy do uaktualnienia do nowego pakietu Azure.Messaging.ServiceBus , który jest dostępny domyślnie od listopada 2020 r. i który domyślnie obsługuje protokół AMQP.

30 września 2026 r. wycofamy biblioteki zestawu SDK usługi Azure Service Bus WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus i com.microsoft.azure.servicebus, które nie są zgodne z wytycznymi dotyczącymi zestawu Azure SDK. Zakończymy również obsługę protokołu SBMP, więc nie będzie można już używać tego protokołu po 30 września 2026 r. Przeprowadź migrację do najnowszych bibliotek zestawu Azure SDK, które oferują krytyczne aktualizacje zabezpieczeń i ulepszone możliwości przed tą datą.

Mimo że starsze biblioteki mogą być nadal używane poza 30 września 2026 r., nie będą już otrzymywać oficjalnej pomocy technicznej i aktualizacji od firmy Microsoft. Aby uzyskać więcej informacji, zobacz ogłoszenie o wycofaniu pomocy technicznej.

Domyślnie pakiet WindowsAzure.ServiceBus komunikuje się z usługą Service Bus przy użyciu dedykowanego protokołu opartego na protokole SOAP o nazwie Service Bus Messaging Protocol (SBMP). W wersji 2.1 dodano obsługę protokołu AMQP 1.0, którego zalecamy użyć, a nie domyślnego protokołu.

Aby użyć protokołu AMQP 1.0 zamiast domyślnego protokołu, wymagana jest jawna konfiguracja w usłudze Service Bus parametry połączenia lub w konstruktorach klienta za pośrednictwem opcji TransportType. Poza tą zmianą kod aplikacji pozostaje niezmieniony podczas korzystania z protokołu AMQP 1.0.

Istnieje kilka funkcji interfejsu API, które nie są obsługiwane w przypadku korzystania z protokołu AMQP. Te nieobsługiwane funkcje są wymienione w sekcji Różnice behawioralne. Niektóre zaawansowane ustawienia konfiguracji mają również inne znaczenie w przypadku korzystania z protokołu AMQP.

Konfigurowanie parametry połączenia do używania protokołu AMQP 1.0

Dołącz parametry połączenia, ;TransportType=Amqp aby poinstruować klienta, aby nawiązał połączenie z usługą Service Bus przy użyciu protokołu AMQP 1.0. Przykład:

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

Gdzie namespace i SAS key są uzyskiwane z witryny Azure Portal podczas tworzenia przestrzeni nazw usługi Service Bus. Aby uzyskać więcej informacji, zobacz Tworzenie przestrzeni nazw usługi Service Bus przy użyciu witryny Azure Portal.

AMQP za pośrednictwem obiektów WebSocket

Aby użyć protokołu AMQP za pośrednictwem obiektów WebSocket, ustaw TransportType w parametry połączenia wartość AmqpWebSockets. Na przykład: Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=AmqpWebSockets.

Serializacja komunikatów

W przypadku korzystania z protokołu domyślnego domyślne zachowanie serializacji biblioteki klienta platformy .NET polega na użyciu typu DataContractSerializer w celu serializacji wystąpienia BrokeredMessage na potrzeby transportu między biblioteką klienta a usługą Service Bus. W przypadku korzystania z trybu transportu AMQP biblioteka klienta używa systemu typów AMQP do serializacji komunikatu obsługiwanego przez brokera do komunikatu AMQP. Ta serializacja umożliwia odbieranie i interpretowanie komunikatu przez aplikację odbierającą, która potencjalnie działa na innej platformie, na przykład aplikacja Java korzystająca z interfejsu API JMS w celu uzyskania dostępu do usługi Service Bus.

Podczas konstruowania wystąpienia BrokeredMessage można podać obiekt .NET jako parametr konstruktora, który będzie służył jako treść komunikatu. W przypadku obiektów, które można mapować na typy pierwotne AMQP, treść jest serializowana w typach danych protokołu AMQP. Jeśli nie można bezpośrednio zamapować obiektu na typ pierwotny AMQP; oznacza to, że typ niestandardowy zdefiniowany przez aplikację, a następnie obiekt jest serializowany przy użyciu modułu DataContractSerializer, a serializowane bajty są wysyłane w komunikacie danych protokołu AMQP.

Aby ułatwić współdziałanie z klientami non-.NET, użyj tylko typów platformy .NET, które mogą być serializowane bezpośrednio w typach protokołu AMQP dla treści komunikatu. Poniższa tabela zawiera szczegółowe informacje o tych typach i odpowiadających im mapowaniu na system typów protokołu AMQP.

Typ obiektu treści platformy .NET Mapowany typ protokołu AMQP Typ sekcji Treści protokołu AMQP
bool boolean Wartość protokołu AMQP
byte ubyte Wartość protokołu AMQP
ushort ushort Wartość protokołu AMQP
uint uint Wartość protokołu AMQP
ulong ulong Wartość protokołu AMQP
sbyte byte Wartość protokołu AMQP
short short Wartość protokołu AMQP
int int Wartość protokołu AMQP
długi długi Wartość protokołu AMQP
liczba zmiennoprzecinkowa liczba zmiennoprzecinkowa Wartość protokołu AMQP
double double Wartość protokołu AMQP
decimal liczba dziesiętna128 Wartość protokołu AMQP
char char Wartość protokołu AMQP
Data/godzina sygnatura czasowa Wartość protokołu AMQP
Identyfikator GUID uuid Wartość protokołu AMQP
byte[] dane binarne Wartość protokołu AMQP
string string Wartość protokołu AMQP
System.collections.ilist lista Wartość protokołu AMQP: elementy zawarte w kolekcji mogą być tylko tymi, które są zdefiniowane w tej tabeli.
System.array tablica Wartość protokołu AMQP: elementy zawarte w kolekcji mogą być tylko tymi, które są zdefiniowane w tej tabeli.
System.collections.idictionary map Wartość protokołu AMQP: elementy zawarte w kolekcji mogą być tylko tymi, które są zdefiniowane w tej tabeli. Uwaga: obsługiwane są tylko klucze ciągu.
Identyfikator URI Opisany ciąg (zobacz poniższą tabelę) Wartość protokołu AMQP
DateTimeOffset Opis długi (zobacz poniższą tabelę) Wartość protokołu AMQP
przedział_czasu Opis długi (zobacz następujące) Wartość protokołu AMQP
Stream dane binarne Dane protokołu AMQP (mogą być wielokrotne). Sekcje Dane zawierają nieprzetworzone bajty odczytane z obiektu stream.
Inny obiekt dane binarne Dane protokołu AMQP (mogą być wielokrotne). Zawiera serializowany plik binarny obiektu, który używa klasy DataContractSerializer lub serializatora dostarczonego przez aplikację.
Typ platformy .NET Zamapowany typ protokołu AMQP Uwagi
Identyfikator 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
przedział_czasu <type name=”timespan” class=restricted source=”long”> <descriptor name=”com.microsoft:timespan” /></type> TimeSpan.Ticks

Różnice behawioralne

Istnieją pewne niewielkie różnice w zachowaniu interfejsu API WindowsAzure.ServiceBus podczas korzystania z protokołu AMQP w porównaniu z protokołem domyślnym:

  • Właściwość OperationTimeout jest ignorowana.
  • MessageReceiver.Receive(TimeSpan.Zero) jest implementowany jako MessageReceiver.Receive(TimeSpan.FromSeconds(10)).
  • Kończenie komunikatów przez tokeny blokady może być wykonywane tylko przez odbiorniki komunikatów, które początkowo odebrały komunikaty.

Kontrolowanie ustawień protokołu AMQP

Interfejsy API platformy .NET udostępniają kilka ustawień w celu kontrolowania zachowania protokołu AMQP:

Następne kroki

Chcesz dowiedzieć się więcej? Odwiedź następujące linki: