Condividi tramite

Usare la libreria legacy WindowsAzure.ServiceBus .NET Framework con AMQP 1.0

  • Articolo

Nota

Questo articolo è destinato agli utenti esistenti del pacchetto WindowsAzure.ServiceBus che cercano di passare all'uso di AMQP all'interno dello stesso pacchetto. Anche se questo pacchetto continuerà a ricevere correzioni di bug critiche fino al 30 settembre 2026, è consigliabile eseguire l'aggiornamento al nuovo pacchetto Azure.Messaging.ServiceBus , disponibile a partire da novembre 2020 e che supporta AMQP per impostazione predefinita.

Il 30 settembre 2026 verranno ritirati le librerie bus di servizio di Azure SDK WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, che non sono conformi alle linee guida di Azure SDK. Il supporto del protocollo SBMP verrà terminato, quindi non sarà più possibile usare questo protocollo dopo il 30 settembre 2026. Eseguire la migrazione alle librerie più recenti di Azure SDK, che offrono aggiornamenti critici della sicurezza e funzionalità migliorate, prima di tale data.

Anche se le librerie precedenti possono ancora essere usate oltre il 30 settembre 2026, non riceveranno più il supporto e gli aggiornamenti ufficiali da Microsoft. Per altre informazioni, vedere l'annuncio di ritiro del supporto.

Per impostazione predefinita, il pacchetto WindowsAzure.ServiceBus comunica con il servizio bus di servizio usando un protocollo basato su SOAP dedicato denominato bus di servizio Protocollo di messaggistica (SBMP). Nella versione 2.1 è stato aggiunto il supporto per AMQP 1.0, che è consigliabile usare anziché il protocollo predefinito.

Per usare AMQP 1.0 invece del protocollo predefinito, è necessaria una configurazione esplicita nel bus di servizio stringa di connessione o nei costruttori client tramite l'opzione TransportType. A parte questa modifica, il codice dell'applicazione rimane invariato quando si usa AMQP 1.0.

Esistono alcune funzionalità api non supportate quando si usa AMQP. Queste funzionalità non supportate sono elencate nella sezione Differenze di comportamento. Anche alcune impostazioni di configurazione avanzate assumono un significato differente quando si utilizza AMQP.

Configurare stringa di connessione per l'uso di AMQP 1.0

Aggiungere il stringa di connessione con ;TransportType=Amqp per indicare al client di stabilire la connessione a bus di servizio usando AMQP 1.0. ad esempio:

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

Dove namespace e SAS key si ottengono dal portale di Azure quando si crea uno spazio dei nomi del bus di servizio. Per altre informazioni, vedere Creare uno spazio dei nomi del bus di servizio usando il portale di Azure.

AMQP su WebSockets

Per usare AMQP su WebSocket, impostare TransportType nel stringa di connessione su AmqpWebSockets. Ad esempio: Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=AmqpWebSockets.

Serializzazione dei messaggi

Quando si usa il protocollo predefinito, il comportamento di serializzazione predefinito della libreria client .NET consiste nell'usare il tipo DataContractSerializer per serializzare un'istanza di BrokeredMessage per il trasporto tra la libreria client e il servizio del bus di servizio. Quando si usa la modalità di trasporto AMQP, la libreria client usa il sistema di tipi AMQP per la serializzazione del messaggio negoziato in un messaggio AMQP. Questa serializzazione consente la ricezione e l'interpretazione dei messaggi da parte di un'applicazione ricevente che è potenzialmente in esecuzione in una piattaforma diversa, ad esempio un'applicazione Java che usa l'API JMS per accedere al bus di servizio.

Quando si crea un'istanza di BrokeredMessage, è possibile specificare al costruttore un oggetto .NET come parametro da usare come corpo del messaggio. Per gli oggetti che possono essere mappati a tipi primitivi AMQP, il corpo viene serializzato in tipi di dati AMQP. Se non è possibile eseguire direttamente il mapping dell'oggetto a un tipo primitivo AMQP, ovvero un tipo personalizzato definito dall'applicazione, l'oggetto viene serializzato tramite DataContractSerializer e i byte serializzati vengono inviati in un messaggio di dati AMQP.

Per semplificare l'interoperabilità con client non .NET, usare solo tipi .NET che possono essere serializzati direttamente in tipi AMQP per il corpo del messaggio. La tabella seguente descrive in modo dettagliato questi tipi e il mapping corrispondente al sistema di tipi AMQP.

Tipo di oggetto del corpo .NET Tipo AMQP mappato Tipo di sezione del corpo AMQP
bool boolean Valore AMQP
byte ubyte Valore AMQP
ushort ushort Valore AMQP
uint uint Valore AMQP
ulong ulong Valore AMQP
sbyte byte Valore AMQP
short short Valore AMQP
int int Valore AMQP
long long Valore AMQP
float float Valore AMQP
double double Valore AMQP
decimal decimal128 Valore AMQP
char char Valore AMQP
Data/Ora timestamp Valore AMQP
GUID uuid Valore AMQP
byte[] binary Valore AMQP
stringa stringa Valore AMQP
System.Collections.IList list Valore AMQP: la raccolta può includere solo gli elementi definiti in questa tabella.
System.Array array Valore AMQP: la raccolta può includere solo gli elementi definiti in questa tabella.
System.Collections.IDictionary mappa Valore AMQP: la raccolta può includere solo gli elementi definiti in questa tabella. Nota: sono supportate solo chiavi di tipo String.
URI Stringa descritta (vedere la tabella seguente) Valore AMQP
DateTimeOffset Elemento Long descritto (vedere la tabella seguente) Valore AMQP
TimeSpan Elemento Long descritto (vedere la tabella seguente) Valore AMQP
Stream binary Dati AMQP (possono essere multipli). Le sezioni Data contengono i byte non elaborati dall'oggetto Stream.
Altro oggetto binary Dati AMQP (possono essere multipli). Contiene i dati binari serializzati dell'oggetto che usa DataContractSerializer o un serializzatore fornito dall'applicazione.
Tipo di .NET Tipo descritto AMQP mappato Note
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

Differenze di comportamento

Esistono alcune piccole differenze nel comportamento dell'API WindowsAzure.ServiceBus quando si usa AMQP rispetto al protocollo predefinito:

  • La proprietà OperationTimeout viene ignorata.
  • MessageReceiver.Receive(TimeSpan.Zero) viene implementato come MessageReceiver.Receive(TimeSpan.FromSeconds(10)).
  • Il completamento di messaggi tramite token di blocco può essere eseguito solo dai destinatari che hanno ricevuto i messaggi all'inizio.

Controllare le impostazioni del protocollo AMQP

Le API .NET espongono diverse impostazioni per controllare il comportamento del protocollo AMQP:

Passaggi successivi

Di seguito sono disponibili altre informazioni. vedere i collegamenti seguenti: