AMQP 1.0 で .NET から Service Bus を使用するUse Service Bus from .NET with AMQP 1.0

AMQP 1.0 は、Service Bus パッケージ バージョン 2.1 以降でサポートされています。AMQP 1.0 support is available in the Service Bus package version 2.1 or later. NuGet から Service Bus ビットをダウンロードすることによって確実に最新バージョンを入手できます。You can ensure you have the latest version by downloading the Service Bus bits from NuGet.

AMQP 1.0 を使用するように .NET アプリケーションを構成するConfigure .NET applications to use AMQP 1.0

既定では、Service Bus .NET クライアント ライブラリは AMQP プロトコルを使ってサービス バス サービスと通信します。By default, the Service Bus .NET client library communicates with the Service Bus service using AMQP protocol. 次のセクションで示すように、トランスポートの種類として AMQP を明示的に指定することもできます。You can also explicitly specify AMQP as the transport type as shown in the following section.

現在のリリースでは、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. Service Bus アプリケーションでは、App.config を使って Service Bus の接続文字列を保存できます。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.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=Amqp" />
    </appSettings>
</configuration>

Microsoft.ServiceBus.ConnectionString 設定の値は、Service Bus への接続を構成するために使用される Service Bus 接続文字列です。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.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[SAS key];TransportType=Amqp

namespaceSAS key は、Service Bus 名前空間を作成するときに、Azure portal から取得します。Where namespace and SAS key are obtained from the Azure portal when you create a Service Bus namespace. 詳細については、「Azure portal を使用して Service Bus 名前空間を作成する」を参照してください。For more information, see Create a Service Bus namespace using the Azure portal.

AMQP を使用する場合は、接続文字列に ;TransportType=Amqp を付加します。When using AMQP, append the connection string with ;TransportType=Amqp. この表記により、クライアント ライブラリに対して、AMQP 1.0 を使用して Service Bus に接続するように通知します。This notation instructs the client library to make its connection to Service Bus using AMQP 1.0.

メッセージのシリアル化Message serialization

既定のプロトコルを使用する場合、.NET クライアント ライブラリの既定のシリアル化の動作として、クライアント ライブラリと Service Bus サービスの間のトランスポートのために 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 を使用して Service Bus にアクセスする 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
[bool]bool booleanboolean AMQP 値AMQP Value
bytebyte ubyteubyte AMQP 値AMQP Value
ushortushort ushortushort AMQP 値AMQP Value
uintuint uintuint AMQP 値AMQP Value
ulongulong ulongulong AMQP 値AMQP Value
sbytesbyte bytebyte 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 arrayarray 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 値: コレクションに含まれるアイテムとして指定できるのは、この表で定義されている項目のみです。注: 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 記述子付き 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
ストリームStream binarybinary AMQP データ (複数の場合あり)。AMQP Data (may be multiple). データ セクションには、Stream オブジェクトから読み取られた未加工のバイトが格納されます。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 NotesNotes
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

Service Bus .NET API の動作は、AMQP を使用する場合と既定のプロトコルを使用する場合では以下のようないくつかの細かい違いがあります。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: