Uso del bus di servizio da .NET con AMQP 1.0Using Service Bus from .NET with AMQP 1.0

Download di Service Bus SDKDownloading the Service Bus SDK

Il supporto per AMQP 1.0 è disponibile in Service Bus SDK versione 2.1 o successiva.AMQP 1.0 support is available in the Service Bus SDK version 2.1 or later. Scaricare la versione più recente del bus di servizio da NuGet per essere certi di disporre della versione corretta.You can ensure you have the latest version by downloading the Service Bus bits from NuGet.

Configurazione delle applicazioni .NET per l'uso di AMQP 1.0Configuring .NET applications to use AMQP 1.0

Per impostazione predefinita, la libreria client .NET del bus di servizio comunica con il bus di servizio tramite un protocollo dedicato basato su SOAP.By default, the Service Bus .NET client library communicates with the Service Bus service using a dedicated SOAP-based protocol. Per usare AMQP 1.0 anziché il protocollo predefinito, è necessaria una configurazione esplicita nella stringa di connessione del bus di servizio, come illustrato nella sezione successiva.To use AMQP 1.0 instead of the default protocol requires explicit configuration on the Service Bus connection string, as described in the next section. A parte questa modifica, il codice dell'applicazione rimane invariato quando si usa AMQP 1.0.Other than this change, application code remains unchanged when using AMQP 1.0.

Nella versione corrente alcune funzionalità API non sono supportate se si usa AMQP.In the current release, there are a few API features that are not supported when using AMQP. Queste funzionalità non supportate sono elencate più avanti nella sezione Funzionalità non supportate, restrizioni e differenze di comportamento.These unsupported features are listed later in the section Unsupported features, restrictions, and behavioral differences. Anche alcune impostazioni di configurazione avanzate assumono un significato differente quando si utilizza AMQP.Some of the advanced configuration settings also have a different meaning when using AMQP.

Configurazione mediante App.configConfiguration using App.config

È consigliabile usare il file di configurazione App.config per l'archiviazione delle impostazioni delle applicazioni.It is good practice for applications to use the App.config configuration file to store settings. Per le applicazioni del bus di servizio, è possibile usare App.config per archiviare la stringa di connessione del bus di servizio.For Service Bus applications, you can use App.config to store the Service Bus connection string. Ecco un file App.config di esempio:An example App.config file is as follows:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <appSettings>
        <add key="Microsoft.ServiceBus.ConnectionString"
             value="Endpoint=sb://[namespace].servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=Amqp" />
    </appSettings>
</configuration>

Il valore dell'impostazione Microsoft.ServiceBus.ConnectionString corrisponde alla stringa di connessione del bus di servizio, usata per configurare la connessione con il bus di servizio.The value of the Microsoft.ServiceBus.ConnectionString setting is the Service Bus connection string that is used to configure the connection to Service Bus. Il formato è il seguente:The format is as follows:

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.Where namespace and SAS key are obtained from the Azure portal when you create a Service Bus namespace. Per altre informazioni, vedere Creare uno spazio dei nomi del bus di servizio usando il portale di Azure.For more information, see Create a Service Bus namespace using the Azure portal.

Quando si usa AMQP, aggiungere ;TransportType=Amqp alla fine della stringa di connessione.When using AMQP, append the connection string with ;TransportType=Amqp. Questa notazione indica alla libreria client di effettuare la connessione al bus di servizio tramite AMQP 1.0.This notation instructs the client library to make its connection to Service Bus using AMQP 1.0.

Serializzazione dei messaggiMessage serialization

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.When using the default protocol, the default serialization behavior of the .NET client library is to use the DataContractSerializer type to serialize a BrokeredMessage instance for transport between the client library and the Service Bus service. 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.When using the AMQP transport mode, the client library uses the AMQP type system for serialization of the brokered message into an AMQP message. 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.This serialization enables the message to be received and interpreted by a receiving application that is potentially running on a different platform, for example, a Java application that uses the JMS API to access Service Bus.

Quando si crea un'istanza di BrokeredMessage, è possibile specificare al costruttore un oggetto .NET come parametro da usare come corpo del messaggio.When you construct a BrokeredMessage instance, you can provide a .NET object as a parameter to the constructor to serve as the body of the message. Per gli oggetti che possono essere mappati a tipi primitivi AMQP, il corpo viene serializzato in tipi di dati AMQP.For objects that can be mapped to AMQP primitive types, the body is serialized into AMQP data types. 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.If the object cannot be directly mapped into an AMQP primitive type; that is, a custom type defined by the application, then the object is serialized using the DataContractSerializer, and the serialized bytes are sent in an AMQP data message.

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.To facilitate interoperability with non-.NET clients, use only .NET types that can be serialized directly into AMQP types for the body of the message. La tabella seguente descrive in modo dettagliato questi tipi e il mapping corrispondente al sistema di tipi AMQP.The following table details those types and the corresponding mapping to the AMQP type system.

Tipo di oggetto del corpo .NET.NET Body Object Type Tipo AMQP mappatoMapped AMQP Type Tipo di sezione del corpo AMQPAMQP Body Section Type
boolbool booleanboolean Valore AMQPAMQP Value
bytebyte ubyteubyte Valore AMQPAMQP Value
ushortushort ushortushort Valore AMQPAMQP Value
uintuint uintuint Valore AMQPAMQP Value
ulongulong ulongulong Valore AMQPAMQP Value
sbytesbyte bytebyte Valore AMQPAMQP Value
shortshort shortshort Valore AMQPAMQP Value
intint intint Valore AMQPAMQP Value
longlong longlong Valore AMQPAMQP Value
floatfloat floatfloat Valore AMQPAMQP Value
doubledouble doubledouble Valore AMQPAMQP Value
decimaldecimal decimal128decimal128 Valore AMQPAMQP Value
charchar charchar Valore AMQPAMQP Value
DateTimeDateTime timestamptimestamp Valore AMQPAMQP Value
GuidGuid uuiduuid Valore AMQPAMQP Value
byte[]byte[] binarybinary Valore AMQPAMQP Value
stringstring stringastring Valore AMQPAMQP Value
System.Collections.IListSystem.Collections.IList listlist Valore AMQP: la raccolta può includere solo gli elementi definiti in questa tabella.AMQP Value: items contained in the collection can only be those that are defined in this table.
System.ArraySystem.Array arrayarray Valore AMQP: la raccolta può includere solo gli elementi definiti in questa tabella.AMQP Value: items contained in the collection can only be those that are defined in this table.
System.Collections.IDictionarySystem.Collections.IDictionary mapmap Valore AMQP: la raccolta può includere solo gli elementi definiti in questa tabella. Nota: sono supportate solo chiavi di tipo String.AMQP Value: items contained in the collection can only be those that are defined in this table.Note: only String keys are supported.
UriUri Stringa descritta (vedere la tabella seguente)Described string(see the following table) Valore AMQPAMQP Value
DateTimeOffsetDateTimeOffset Elemento Long descritto (vedere la tabella seguente)Described long(see the following table) Valore AMQPAMQP Value
TimeSpanTimeSpan Elemento Long descritto (vedere la tabella seguente)Described long(see the following) Valore AMQPAMQP Value
FlussoStream binarybinary Dati AMQP (possono essere multipli).AMQP Data (may be multiple). Le sezioni Data contengono i byte non elaborati dall'oggetto Stream.The Data sections contain the raw bytes read from the Stream object.
Altro oggettoOther Object binarybinary Dati AMQP (possono essere multipli).AMQP Data (may be multiple). Contiene i dati binari serializzati dell'oggetto che usa DataContractSerializer o un serializzatore fornito dall'applicazione.Contains the serialized binary of the object that uses the DataContractSerializer or a serializer supplied by the application.
Tipo .NET.NET Type Tipo descritto AMQP mappatoMapped AMQP Described Type NoteNotes
UriUri <type name=”uri” class=restricted source=”string”> <descriptor name=”com.microsoft:uri” /></type> Uri.AbsoluteUriUri.AbsoluteUri
DatetimeoffsetDateTimeOffset <type name=”datetime-offset” class=restricted source=”long”> <descriptor name=”com.microsoft:datetime-offset” /></type> DateTimeOffset.UtcTicksDateTimeOffset.UtcTicks
TimeSpanTimeSpan <type name=”timespan” class=restricted source=”long”> <descriptor name=”com.microsoft:timespan” /></type> TimeSpan.TicksTimeSpan.Ticks

Funzionalità non supportate, restrizioni e differenze di comportamentoUnsupported features, restrictions, and behavioral differences

Le seguenti funzionalità dell'API .NET del bus di servizio non sono al momento supportate con AMQP:The following features of the Service Bus .NET API are not currently supported when using AMQP:

  • TransazioniTransactions
  • Invio tramite destinazione del trasferimentoSend via transfer destination

Esistono anche alcune piccole differenze di comportamento dell'API .NET del bus di servizio durante l'uso di AMQP, rispetto al protocollo predefinito:There are also some small differences in the behavior of the Service Bus .NET API when using AMQP, compared to the default protocol:

  • La proprietà OperationTimeout viene ignorata.The OperationTimeout property is ignored.
  • MessageReceiver.Receive(TimeSpan.Zero) viene implementato come MessageReceiver.Receive(TimeSpan.FromSeconds(10)).MessageReceiver.Receive(TimeSpan.Zero) is implemented as 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.Completing messages by lock tokens can only be done by the message receivers that initially received the messages.

Controllo delle impostazioni del protocollo AMQPControlling AMQP protocol settings

Le API .NET espongono diverse impostazioni per controllare il comportamento del protocollo AMQP:The .NET APIs expose several settings to control the behavior of the AMQP protocol:

Passaggi successiviNext steps

Per altre informazioni,Ready to learn more? vedere i collegamenti seguenti:Visit the following links: