使用 AMQP 1.0 通过 .NET 使用服务总线Use Service Bus from .NET with AMQP 1.0

AMQP 1.0 支持在服务总线包 2.1 版或更高版本中提供。AMQP 1.0 support is available in the Service Bus package version 2.1 or later. 为确保使用最新版本,可以从 NuGet下载服务总线安装包。You can ensure you have the latest version by downloading the Service Bus bits from NuGet.

将 .NET 应用程序配置为使用 AMQP 1.0Configure .NET applications to use AMQP 1.0

默认情况下,Service Bus .NET 客户端库使用基于 SOAP 的专用协议与 Service Bus 服务通信。By default, the Service Bus .NET client library communicates with the Service Bus service using a dedicated SOAP-based protocol. 若要使用 AMQP 1.0 而非默认协议,需要对服务总线连接字符串进行显式配置,如下一部分所述。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. 除了此更改之外,在使用 AMQP 1.0 时应用程序代码基本保持不变。Other than this change, application code remains unchanged when using AMQP 1.0.

在当前版本中,有一些在使用 AMQP 时不受支持的 API 功能。In the current release, there are a few API features that are not supported when using AMQP. 这些不受支持的功能在行为差异部分列出。These unsupported features are listed in the section Behavioral differences. 在使用 AMQP 时,一些高级配置设置还具有不同的含义。Some of the advanced configuration settings also have a different meaning when using AMQP.

使用 App.config 进行配置Configuration using App.config

应用程序使用 App.config 配置文件存储设置是一个很好的做法。It is a good practice for applications to use the App.config configuration file to store settings. 对于服务总线应用程序,可以使用 App.config 存储服务总线连接字符串。For Service Bus applications, you can use App.config to store the Service Bus connection string. 示例 App.config 文件如下所示: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.chinacloudapi.cn/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=Amqp" />
    </appSettings>
</configuration>

Microsoft.ServiceBus.ConnectionString 设置的值是用于配置服务总线连接的服务总线连接字符串。The value of the Microsoft.ServiceBus.ConnectionString setting is the Service Bus connection string that is used to configure the connection to Service Bus. 其格式如下所示:The format is as follows:

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

其中 namespaceSAS key 是在创建服务总线命名空间时从 Azure 门户获取的。Where namespace and SAS key are obtained from the Azure portal when you create a Service Bus namespace. 有关详细信息,请参阅使用 Azure 门户创建服务总线命名空间For more information, see Create a Service Bus namespace using the Azure portal.

使用 AMQP 时,在连接字符串后面追加 ;TransportType=AmqpWhen using AMQP, append the connection string with ;TransportType=Amqp. 此表示法使客户端库使用 AMQP 1.0 连接到服务总线。This notation instructs the client library to make its connection to Service Bus using AMQP 1.0.

消息序列化Message serialization

使用默认协议时,.NET 客户端库的默认序列化行为是使用 DataContractSerializer 类型序列化 BrokeredMessage 实例,以便在客户端库和服务总线服务之间进行传输。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. 使用 AMQP 传输模式时,客户端库使用 AMQP 类型系统将 中转消息 序列化为 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. 此序列化使得消息能够由可能在不同平台上运行的接收应用程序接收和解释,例如,使用 JMS API 来访问服务总线的 Java 应用程序。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.

构造 BrokeredMessage 实例时,可以提供 .NET 对象作为构造函数的参数以充当消息的正文。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. 对于可映射到 AMQP 基元类型的对象,正文序列化为 AMQP 数据类型。For objects that can be mapped to AMQP primitive types, the body is serialized into AMQP data types. 如果该对象不能直接映射到 AMQP 基元类型(即,应用程序定义的自定义类型),则使用 DataContractSerializer序列化对象,并且已序列化的字节会在 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.

为了便于使用非 .NET 客户端进行互操作,仅在消息的正文中使用可直接序列化为 AMQP 类型的 .NET 类型。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. 下表详细介绍了这些类型以及到 AMQP 类型系统的相应映射。The following table details those types and the corresponding mapping to the AMQP type system.

.NET 正文对象类型.NET Body Object Type 映射的 AMQP 类型Mapped AMQP Type AMQP 正文部分类型AMQP Body Section Type
boolbool 布尔值boolean AMQP 值AMQP Value
bytebyte ubyteubyte AMQP 值AMQP Value
ushortushort ushortushort AMQP 值AMQP Value
uintuint uintuint AMQP 值AMQP Value
ulongulong ulongulong AMQP 值AMQP Value
sbytesbyte stringbyte AMQP 值AMQP Value
shortshort shortshort AMQP 值AMQP Value
intint intint AMQP 值AMQP Value
longlong longlong AMQP 值AMQP Value
floatfloat floatfloat AMQP 值AMQP Value
Doubledouble Doubledouble AMQP 值AMQP Value
decimaldecimal decimal128decimal128 AMQP 值AMQP Value
charchar charchar AMQP 值AMQP Value
DateTimeDateTime timestamptimestamp AMQP 值AMQP Value
GuidGuid uuiduuid AMQP 值AMQP Value
byte[]byte[] binarybinary AMQP 值AMQP Value
stringstring stringstring AMQP 值AMQP Value
System.Collections.IListSystem.Collections.IList listlist AMQP 值:集合中包含的项只能是此表中定义的类型。AMQP Value: items contained in the collection can only be those that are defined in this table.
System.ArraySystem.Array 数组array AMQP 值:集合中包含的项只能是此表中定义的类型。AMQP Value: items contained in the collection can only be those that are defined in this table.
System.Collections.IDictionarySystem.Collections.IDictionary mapmap AMQP 值:集合中包含的项只能是此表中所定义的类型。注意:仅支持字符串键。AMQP Value: items contained in the collection can only be those that are defined in this table.Note: only String keys are supported.
UriUri 描述型 string(请参阅下表)Described string(see the following table) AMQP 值AMQP Value
DateTimeOffsetDateTimeOffset 描述型 long(请参阅下表)Described long(see the following table) AMQP 值AMQP Value
TimeSpanTimeSpan 描述型 long(请参阅下文)Described long(see the following) AMQP 值AMQP Value
StreamStream binarybinary AMQP 数据(可能有多个)。AMQP Data (may be multiple). 数据部分包含从流对象读取的原始字节。The Data sections contain the raw bytes read from the Stream object.
其他对象Other Object binarybinary AMQP 数据(可能有多个)。AMQP Data (may be multiple). 包含使用 DataContractSerializer 或应用程序提供的序列化程序的对象的已序列化二进制值。Contains the serialized binary of the object that uses the DataContractSerializer or a serializer supplied by the application.
.NET 类型.NET Type 映射的 AMQP 描述类型Mapped AMQP Described Type 注释Notes
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

行为差异Behavioral differences

与默认协议相比,使用 AMQP 时在服务总线 .NET API 的行为方面也有一些细微的差异:There are some small differences in the behavior of the Service Bus .NET API when using AMQP, compared to the default protocol:

  • 将忽略 OperationTimeout 属性。The OperationTimeout property is ignored.
  • MessageReceiver.Receive(TimeSpan.Zero) 是以 MessageReceiver.Receive(TimeSpan.FromSeconds(10)) 的形式实现的。MessageReceiver.Receive(TimeSpan.Zero) is implemented as MessageReceiver.Receive(TimeSpan.FromSeconds(10)).
  • 通过锁定令牌完成消息只能由最初收到消息的消息接收方完成。Completing messages by lock tokens can only be done by the message receivers that initially received the messages.

控制 AMQP 协议设置Control AMQP protocol settings

.NET API 公开了几项设置以控制 AMQP 协议的行为:The .NET APIs expose several settings to control the behavior of the AMQP protocol:

后续步骤Next steps

准备好了解详细信息?Ready to learn more? 请访问以下链接:Visit the following links: