XML Web サービス プロキシの作成
定義上、XML Web サービスとは、SOAP などの業界標準プロトコルを使用してネットワーク経由で通信できます。つまり、クライアントと XML Web サービスは SOAP メッセージを使用して通信します。SOAP メッセージは、In パラメータと Out パラメータを XML としてカプセル化します。XML Web サービス クライアントの場合、パラメータを XML 要素に割り当て、ネットワーク経由で SOAP メッセージを送信する作業は、プロキシ クラスが処理します。
サービスの説明が存在している限り、さらにその説明が Web サービス記述言語 (WSDL: Web Services Description Language) に準拠している場合には、プロキシ クラスを生成できます。サービスの説明には、XML Web サービスと通信する方法が定義されています。サービスの説明を利用して、Wsdl.exe ツールを用いてプロキシ クラスを作成できます。その後、XML Web サービス クライアントがプロキシ クラスのメソッドを呼び出し、プロキシ クラスは、XML Web サービスとの間で送受信される SOAP メッセージを処理することにより、ネットワーク経由で XML Web サービスと通信します。プロキシ クラスはインターネット経由で XML Web サービスと通信するので、プロキシ クラスの Url プロパティが、信頼されている接続先を参照していることを確認することが重要です。
既定では、プロキシ クラスでは HTTP ではなく SOAP を使用して XML Web サービスと通信します。また、Wsdl.exe を使用して、HTTP-GET プロトコルまたは HTTP-POST プロトコルのいずれかを使用して XML Web サービスと通信するプロキシ クラスを生成することもできます。プロキシ クラスで HTTP-GET または HTTP-POST を使用するように指定するには、次の表に説明されているように、Wsdl.exe ツールに /protocol スイッチを渡します。
XML Web サービス プロキシ クラスを生成するには
コマンド プロンプトから Wsdl.exe を使用して、少なくとも XML Web サービスまたはサービスの説明への URL を指定するか、または保存されているサービスの説明へのパスを指定して、プロキシ クラスを作成します。
Wsdl /language:language /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>メモ 上に示した引数は、Wsdl.exe ツールで一般的に使用される引数です。Wsdl.exe ツールの完全な構文については、「Web サービス記述言語ツール (Wsdl.exe)」を参照してください。
パラメータ 値 <url or path> サービスの説明 (Web サービス記述言語で XML Web サービスを記述するファイル) の URL またはパスを指定します。 ファイルを指定する場合、サービスの説明を含むファイルを指定します。次に例を示します。
mywebservice.wsdl
URL を指定する場合、.asmx ページを参照するか、サービスの説明を返す URL を指定する必要があります。ASP.NET を使用して作成する XML Web サービスの場合、XML Web サービスの URL に ?WSDL を追加することで、サービスの説明を返すことができます。次に例を示します。
https://www.contoso.com/MyWebService.asmx?WSDL
/language:language プロキシ クラスの生成に使用する言語を指定します。有効なオプションは、CS、VB、および JS (それぞれ、C#、Visual Basic .NET、および JScript .NET を示す) です。既定の言語は C# です。この値は省略できます。 /protocol:protocol XML Web サービス メソッドとの通信に使用するプロトコルを指定します。有効なオプションは、SOAP、HTTP-GET、および HTTP-POST です。既定のプロトコルは SOAP です。この値は省略できます。 /namespace:myNameSpace 生成するプロキシの名前空間を指定します。既定値はグローバル名前空間です。この値は省略できます。 /out:filename 作成するプロキシ クラスを含むファイルの名前を指定します。既定値は、XML Web サービスを実装するクラスの名前に基づく名前です。この値は省略できます。 /username:username 認証情報を要求する Web サーバーに接続するときに使用するユーザー名を指定します。この値は省略できます。 /password:password 認証情報を要求する Web サーバーに接続するときに使用するパスワードを指定します。この値は省略できます。 /domain:domain 認証情報を要求する Web サーバーに接続するときに使用するドメインを指定します。この値は省略できます。
生成されるプロキシ クラスの詳細
Wsdl.exe を使用してプロキシ クラスを生成すると、1 つのソース ファイルが指定した言語で生成されます。このファイルには、XML Web サービスの各 XML Web サービス メソッドに対応する同期メソッドおよび非同期メソッドの両方を公開するプロキシ クラスが含まれています。たとえば、XML Web サービスに Add という名前の XML Web サービス メソッドが含まれている場合、そのプロキシ クラスには、Add XML Web サービス メソッドを呼び出すための Add、BeginAdd、EndAdd の各メソッドがあります。Add XML Web サービス メソッドと同期通信する場合にはプロキシ クラスの Add メソッドを使用し、XML Web サービス メソッドと非同期通信する場合には BeginAdd メソッドと EndAdd メソッドを使用します。XML Web サービス メソッドとの非同期通信の詳細については、「XML Web サービスとの非同期通信」を参照してください。
生成されるプロキシ クラスの各メソッドには、XML Web サービス メソッドと通信するための適切なコードが含まれています。XML Web サービスとプロキシ クラス間の通信時にエラーが発生した場合は、例外がスローされます。例外処理の詳細については、「XML Web サービスでの例外の処理およびスロー」を参照してください。
パラメータの順序については、XML Web サービス メソッドで定義されている順序と、プロキシ クラスの関連メソッドで定義されている順序が異なる場合があります。ほとんどの場合、パラメータの順序は一致します。ただし、書式として Document が指定された SOAP メッセージ**を XML Web サービスが要求する場合には、**パラメータの順序が一致しません。XML Web サービス メソッドで In パラメータの前に Out パラメータが定義されている場合、その Out パラメータは、プロキシ クラスではすべての In パラメータの後に配置されます。たとえば、次のコード例では、XML Web サービス メソッド MyWebMethod では、inStr In パラメータの前に outStr Out パラメータが宣言されています。しかし、プロキシ クラスでは、inStr パラメータが outStr パラメータの前に宣言されています。
場合によっては、WSDL.exe によって生成されたプロキシ クラスは、最小公分母的な手法を使って、サービスの説明で指定された型にオブジェクトをキャストします。結果として、そのプロキシ クラスの生成された型が開発者の意図するものと異なることがあります。たとえば、WSDL.exe がサービスの説明で ArrayList 型を検出した場合は、生成するプロキシ クラス内に Object Array が作成されます。オブジェクト型が正しくキャストされるようにするには、生成されたプロキシ クラスが含まれているファイルを開き、不正なオブジェクト型を正しいオブジェクト型に変更します。
' Declare MyWebMethod in the XML Web service.
MyWebMethod(ByRef outStr As String, inStr As String)
' This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(inStr As String, ByRef outStr As String)
[C#]
// Declare MyWebMethod in the XML Web service.
MyWebMethod(out string outStr, string inStr)
// This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(string inStr, out string outStr).
場合によっては、WSDL.exe によって生成されたプロキシ クラスは、最小公分母的な手法を使って、サービスの説明で指定された型にオブジェクトをキャストします。結果として、そのプロキシ クラスの生成された型が開発者の意図するものと異なることがあります。たとえば、WSDL.exe がサービスの説明で ArrayList 型を検出した場合、生成されたプロキシ クラス内に Object 配列が作成されます。オブジェクト型が正しくキャストされるようにするには、生成されたプロキシ クラスが含まれているファイルを開き、不正なオブジェクト型を正しいオブジェクト型に変更します。
Wsdl.exe によってスローされる警告
Wsdl.exe に複数のサービスの説明を指定すると、次のように 2 つのエラー メッセージが発生する場合があります。
警告 : 場所 <schema URI> からの TargetNamespace=<schema namespace> を持つ重複するサービスの説明を無視します。
指定した 2 つ以上のサービスの説明に対する TargetNamespace が同一であることを示しています。TargetNamespace は特定の XML ドキュメント (この場合はサービスの説明) に固有の ID と見なされるため、Wsdl.exe では、2 つのサービスの説明が同一であると見なされます。そのため、Wsdl.exe は、サービスの説明のいずれか 1 つに対するプロキシ クラスを 1 つだけ作成します。この動作が要件と合わない場合には、変更できます。ASP.NET を使用して作成する XML Web サービスを表すサービス説明の場合、一意の Namespace プロパティを指定する WebService 属性を、XML Web サービスを実装するクラスに適用できます。その Namespace プロパティを TargetNamespace としてサービスの説明で使用すると、XML Web サービスを一意に識別できます。Namespace プロパティの設定の詳細については、「WebService 属性の適用」を参照してください。
警告 : 場所 <schema URI> からの TargetNamespace=<schema Namespace> を持つ重複するスキーマを無視します。
指定した 2 つ以上の XML スキーマに対する TargetNamespace が同一であることを示しています。TargetNamespace は特定の XML ドキュメント (この場合は XML スキーマ) に固有の ID と見なされるため、Wsdl.exe では、2 つの XML スキーマが同一であると見なされます。そのため、Wsdl.exe は、XML スキーマのいずれか 1 つに対するクラスを作成します。この動作が要件に合わない場合には、各 XML スキーマの TargetNamespace を一意の URI に変更する必要があります。TargetNamespace の変更方法は、特定の XML スキーマのソースに応じて異なります。
参照
XML Web サービス クライアントの作成 | XML Web サービスの探索 | XML Web サービスのクライアントの作成 | ASP.NET を使用して作成した既存の XML Web サービスの調査 | XML Web サービスとの非同期通信 | ブラウザから XML Web サービスへのアクセス