.Net Framework による SOAP 形式のサポート

[アーティクル]
09/17/2008

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 これは、既定の設定です。	サポートされています。
Encoded: SOAP 1.1 Section 5 エンコーディング規則	SoapDocumentMethod または SoapDocumentService Use=Encoded	SoapRpcMethod または SoapRpcService

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

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

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

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

SoapDocumentMethod または SoapDocumentService

Use=Literal

これは、既定の設定です。

サポートされています。

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

SoapDocumentMethod または SoapDocumentService

Use=Encoded

SoapRpcMethod または SoapRpcService

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

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

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

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

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

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

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

Web サービスメソッドのパラメータまたは戻り値の書式を制御する Use については、ASP.NET Web サービスの既定の設定は SOAP Encoded ではなく Literal です。

ただし、この設定は、SOAP Body 要素の第 1 (および第 2) レベルのコンテンツの書式に関するスタイルの設定によって決まります。Web サービスメソッドまたは対応するプロキシクラスメソッドで SoapRpcMethod 属性が使用されている場合、自動的に SOAP エンコーディングが使用されます。.NET Framework では、RPC と Literal の組み合わせをサポートします。SoapRpcService 属性が Web サービスクラスに適用されていて、指定された Web サービスメソッドに適用される SoapDocumentMethod 属性によって上書きされない場合も同じです。一方、SoapDocumentMethod 属性および SoapDocumentService 属性には 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 メッセージをカスタマイズする」を参照してください。

次の方法で共有

.Net Framework による SOAP 形式のサポート

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

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

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

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

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

関連項目

タスク

参照

概念

その他の技術情報

その他のリソース