.NET Framework での SOAP 形式のサポート

[アーティクル]
02/24/2011

このトピックの対象は、レガシテクノロジに特定されています。XML Web サービスと XML Web サービスクライアントは以下を使用して作成してください。 Windows Communication Foundation.

ASP.NET の Web サービスを作成する開発者は、WSDL ドキュメントを手動で作成する代わりに、個々の Web サービスメソッドまたは Web サービスクラス全体に属性を適用することで SOAP 形式を指定できます。属性を指定しない場合は、既定の SOAP 形式が使用されます。

既存の WSDL ドキュメントに基づいて Web サービスを開発する場合は、/server オプションを指定して Wsdl.exe ツールを実行すると、適切な属性値が自動的に設定された抽象 Web サービスクラスが生成されます。

/server オプションを指定しない場合は、関連する SOAP 形式の属性に適切な値が設定され、入力 WSDL ドキュメントに記述された Web サービスと通信するクライアントプロキシクラスが生成されます。クライアントプロキシクラスでは、サーバーで指定できる属性のほとんどが使用されます。通常、開発者が手動でこれらのクライアントプロキシクラスの属性を追加または編集する必要はありません。クライアントは Wsdl.exe によって、WSDL ドキュメントで指定されたサービスコントラクトに準拠するように生成されるためです。

次の表に、ASP.NET と .NET Framework を使用して作成された Web サービスとクライアントでサポートされる形式の選択肢と、特定の組み合わせを実現する属性を示します。Service サフィックスが付いた属性は、Web サービスを実装するクラス (クライアントプロキシクラスではなく) に適用し、クラス内の Web サービスメソッドの既定の書式スタイルを設定できます。Method サフィックスが付いた属性は、Web サービスメソッド、または Web サービスメソッドを呼び出すクライアントプロキシクラスのメソッドに適用できます。それぞれの組み合わせの詳細については、後で説明します。

パラメーターの書式 (使用方法)	ドキュメントベースの SOAP メッセージの SOAP 本文書式 (Style)	RPC ベースの SOAP メッセージ (SOAP 1.1 Section 7 準拠) の SOAP 本文書式 (Style)
Literal: 各パラメーターの XSD スキーマに準拠	SoapDocumentMethod またはSoapDocumentService Use=Literal これが既定値です。	SoapRpcMethod またはSoapRpcService Use=Literal
Encoded: SOAP 1.1 Section 5 エンコーディング規則	SoapDocumentMethod またはSoapDocumentService Use=Encoded	SoapRpcMethod またはSoapRpcService Use=Encoded これが既定値です。

パラメーターの書式 (使用方法)

ドキュメントベースの SOAP メッセージの SOAP 本文書式 (Style)

RPC ベースの SOAP メッセージ (SOAP 1.1 Section 7 準拠) の SOAP 本文書式 (Style)

Literal: 各パラメーターの XSD スキーマに準拠

SoapDocumentMethod またはSoapDocumentService

Use=Literal

これが既定値です。

SoapRpcMethod またはSoapRpcService

Use=Literal

Encoded: SOAP 1.1 Section 5 エンコーディング規則

SoapDocumentMethod またはSoapDocumentService

Use=Encoded

SoapRpcMethod またはSoapRpcService

Use=Encoded

これが既定値です。

注 :
実際の属性名には、Attribute サフィックスが使用されます。ソースコードでは、この表に示すように名前を短縮できます。

SOAP 本文全体の書式全体の制御

Web サービスランタイムエンジンが RPC 規約を適用するか XML ドキュメントに従うかを制御する Style については、ASP.NET Web サービスの既定の設定は、RPC ではなく Document です。

ドキュメントスタイルを明示的に指定するには、Web サービスメソッドまたはクライアントプロキシメソッドに SoapDocumentMethodAttribute 属性を適用するか、Web サービスクラスに SoapDocumentServiceAttribute 属性を適用します。RPC スタイルを明示的に指定するには、Web サービスメソッドまたはクライアントプロキシメソッドに SoapRpcMethodAttribute 属性を適用するか、Web サービスクラスに SoapRpcServiceAttribute 属性を適用します。サービスについては、メソッドレベルの属性によってクラスレベルの属性が上書きされます。

このトピックの後半で説明するように、これらの属性には、パラメーターと戻り値の書式を決定する役割があります。また、実行時に "ラッパー" 要素を自動生成して、パラメーターまたは戻り値を含めるかどうかを決定する役割もあります。詳細については、次のトピックを参照してください。「方法 : Web サービスメソッドのパラメーターを別の要素で囲むかどうかを制御する」を参照してください。

これらの属性の適用方法詳細情報「方法 : Web サービスメソッドで SOAP 本文全体の書式を制御する」を参照してください。

パラメーターと戻り値の書式の制御

Web サービスメソッドのパラメーターまたは戻り値の書式を制御する Use については、ドキュメントスタイルの ASP.NET Web サービスの既定の設定は Literal です。RPC スタイルの ASP.NET Web サービスの既定の設定は Encoded です。Use 値を変更するには、対応する SoapDocumentMethodAttribute 属性、SoapDocumentServiceAttribute 属性、SoapRpcMethodAttribute 属性、または SoapRpcServiceAttribute 属性の Use プロパティを SoapBindingUse.Literal または SoapBindingUse.Encoded に設定します。

Use プロパティの設定方法詳細情報「方法 : Web サービスメソッド向けにパラメーターと戻り値の形式を制御する」を参照してください。

パラメーターを XML 要素で囲むかどうかの制御

Web サービスメソッドのパラメーターまたは戻り値は、SOAP メッセージの Body 要素にある親 XML 要素に自動的にカプセル化されます。開発者が親要素を指定する必要はありません。これまでに説明したように、これは RPC 書式スタイルで実行されます。ただし、Document 書式スタイルでも任意で実行できます。親 XML 要素 (ラッパー) が WSDL ドキュメントで指定されるのではなく、実行時に Web サービスのインフラストラクチャによって追加の要素が暗黙で挿入されます。

この規約はラップと呼ばれ、SoapDocumentMethod.ParameterStyle プロパティまたは SoapDocumentService.ParameterStyle プロパティの値を SoapParameterStyle.Wrapped に設定することで指定できます。Wrapped も既定値です。

SoapParameterStyle 列挙型には、サービスクラスレベルの既定のパラメータースタイルを指定する値 Default があります。さらに、ラップを無効にして、WSDL によりメッセージ部分として指定された XML 要素をメソッドのパラメーターと戻り値に変換する値 Bare があります。Bare パラメータースタイルを使用すると、各パラメーターまたは戻り値は、指定されたメッセージ部分と一致します。

Wrapped と Bare のどちらについても、ラップの選択は WSDL ドキュメントでは指定されません。使用されるバインディングスタイルは Document です。選択には、XML とコード間 (WSDL で定義された XML と、メソッドのパラメーターおよび戻り値) のバインディングが含まれます。

ParameterStyle プロパティを SoapParameterStyle.Bare に設定すると、開発者は、複数の部分 (SOAP Body 要素の子要素となる複数の XML 要素) を持つメッセージを指定できます。技術的には、ドキュメントのルートは 1 つである必要があるため、複数の要素が 1 つの XML ドキュメントを構成することはありません。このため、Web サービスコミュニティでは、Document スタイルのサービスを持つ単一のメッセージ部分を使用することをお勧めします。各 Web サービスメソッドでは、対象とするシグネチャではなく、XML ドキュメントへのオブジェクトの割り当てが単一パラメーターで XML ドキュメントへの別オブジェクトの割り当てが戻り値であるシグネチャを使用する必要があります。開発者は、実際のパラメーターまたは戻り値を抽出またはパッケージ化するコードを記述する必要があります。

このため、開発者は通常、ParameterStyle プロパティを SoapParameterStyle.Wrapped に設定するだけで十分です。これで、Web サービスインフラストラクチャによって、パラメーターと戻り値が XML ドキュメントに配置されます。

ParameterStyle プロパティの設定方法詳細情報「方法 : Web サービスメソッドのパラメーターを別の要素で囲むかどうかを制御する」を参照してください。

Web サービス全体の既定の SOAP 形式の設定

このトピックで説明したように、SoapDocumentServiceAttribute 属性と SoapRpcServiceAttribute 属性を使用すると、クライアントプロキシクラスではなく Web サービスクラス全体に対して、Style および Use の既定値や、パラメーターとドキュメントの対応付けのスタイルの既定値を設定できます。SoapDocumentMethod 属性と SoapRpcMethod 属性を使用すると、各 Web サービスメソッドでサービスレベルの設定を上書きできます。

SoapDocumentService 属性および SoapRpcService 属性の使用方法詳細情報「方法 : Web サービス全体の既定の SOAP 形式を変更する」を参照してください。

XML シリアル化による SOAP メッセージのカスタマイズ

Style および Use の指定、ラッパー要素を挿入するかどうかの指定に加え、XML シリアル化によって SOAP メッセージ内の XML を直接カスタマイズできます。既定では、.NET Framework の Web サービスインフラストラクチャによって、パブリックフィールドとパブリックプロパティが自動的に XML メッセージにシリアル化されます。

System.Xml.Serialization 名前空間には、XML を操作するためのさまざまな属性が含まれます。次のコード例では、これらの属性の一部を Web サービスメソッドのパラメーターまたは戻り値に直接適用する方法を示します。

[SoapDocumentMethod(
     "https://www.contoso.com/DocumentBareLiteral",
     Use=SoapBindingUse.Literal,
     ParameterStyle=SoapParameterStyle.Bare)]
[return: XmlElement(Namespace="https://www.contoso.com",
                    IsNullable=true)]
public string DocumentBareLiteral(
   [XmlElement(Namespace="https://www.contoso.com",
                     IsNullable=true)] 
   Address1 MyAddress, 
   [XmlElement(Namespace="https://www.contoso.com",
            IsNullable=false)] 
   bool useZipPlus4) {

<SoapDocumentMethod( _
     https://www.contoso.com/DocumentBareLiteral", _
     Use:=SoapBindingUse.Literal, _
     ParameterStyle:= SoapParameterStyle.Bare)> _
Public Function DocumentBareLiteral( _
   ByVal <XmlElement([Namespace]:="https://www.contoso.com", _
                      IsNullable:=true)> _
   MyAddress As Address1, _
   ByVal <XmlElement([Namespace]:="https://www.contoso.com", _
                      IsNullable:=false)> _
   useZipPlus4 As Boolean) _
   As <XmlElement([Namespace]:="https://www.contoso.com", _
                  IsNullable:=true)> _
   String

よく使用される属性を次に示します。それぞれの名前には、Attribute サフィックス (省略可能) は付いていません。

XmlElement: パブリックフィールドまたはパブリックプロパティが XML 要素としてシリアル化されることを指定します。これは、非配列のパブリックフィールドおよびパブリックプロパティをシリアル化するための既定の属性です。XmlElement 属性が配列型属性のパブリックフィールドおよびパブリックプロパティに適用されると、その配列は、特別な親要素を使用せずに、他のメンバーと共にシリアル化されます。
XmlAttribute: パブリックフィールドまたはパブリックプロパティが、包含型を表す要素の XML 属性としてシリアル化されることを指定します。
XmlArray: 配列型のパブリックフィールドが、特別な親要素を使用してシリアル化されることを指定します。これは、配列型のパブリックフィールドおよびパブリックプロパティをシリアル化するための既定の属性です。
XmlArrayItem: XmlArray 属性と組み合わせて使用し、配列要素を制御します。
XmlIgnore: パブリックフィールドまたはパブリックプロパティがシリアル化されないことを指定します。

XmlIgnore を除き、これらの属性を使用して、既定値の他に、非配列メンバーの名前となる要素または属性の名前を指定できます。また、特定の要素の名前空間を指定することもできます。通常、Web サービスでは名前空間は混在しません。名前空間は、WebService や WebServiceBinding などの属性を使用してクラスレベルで指定するだけで十分です。

詳細については、次のトピックを参照してください。「System.Xml.Serialization」を参照してください。

注 :
RPC またはエンコードされた Web サービスの場合は、SOAP エンコーディングが指定された RPC スタイルを使用して、XML シリアル化の使用が制限されます。パラメーターと戻り値は、名前空間の修飾なしで自動的に表示されます。また、SOAP 1.1 Section 5 エンコーディングと Document スタイルまたは RPC スタイルとの組み合わせでは、XML 属性へのデータのバインディングが禁止されます。

RPC またはエンコードされた Web サービスの場合は、SOAP エンコーディングが指定された RPC スタイルを使用して、XML シリアル化の使用が制限されます。パラメーターと戻り値は、名前空間の修飾なしで自動的に表示されます。また、SOAP 1.1 Section 5 エンコーディングと Document スタイルまたは RPC スタイルとの組み合わせでは、XML 属性へのデータのバインディングが禁止されます。

注 :
抽象サービスクラスまたはクライアントプロキシクラスが WSDL ドキュメントから生成される場合は、インラインで配置されるか、インポートされるかに関係なく、WSDL の types 要素で定義される XML スキーマの要素と型に対して、適切な System.Xml.Serialization 属性が自動的に適用されます。

注 :
Web サービスで Null 許容型を使用すると、WSDL には、その型に対する "nillable=true" 設定が含まれます。ただし、Null 許容型が Web メソッドのパラメーターまたは戻り値として直接使用されると、次のような場合は、結果の WSDL に Null 値の許容が反映されません。1) RPC ベースの SOAP メッセージが使用される場合。2) Document ベースの SOAP メッセージが、Bare モードでエンコードパラメーターと共に使用される場合。

Web サービスで Null 許容型を使用すると、WSDL には、その型に対する "nillable=true" 設定が含まれます。ただし、Null 許容型が Web メソッドのパラメーターまたは戻り値として直接使用されると、次のような場合は、結果の WSDL に Null 値の許容が反映されません。1) RPC ベースの SOAP メッセージが使用される場合。2) Document ベースの SOAP メッセージが、Bare モードでエンコードパラメーターと共に使用される場合。

XmlElement 属性の使用方法詳細情報「方法 : XML シリアル化によって SOAP メッセージをカスタマイズする」を参照してください。

参照