XML Web サービス プロキシの作成
このトピックの対象は、レガシ テクノロジに特定されています。XML Web サービスと XML Web サービス クライアントは以下を使用して作成してください。 Windows Communication Foundation.
Web サービスは定義上、SOAP などの業界標準プロトコルを使用してネットワーク経由で通信できます。つまり、クライアントと Web サービス間では、IN パラメーターおよび OUT パラメーターを XML としてカプセル化する SOAP メッセージを使用して通信します。Web サービス クライアントについては、パラメーターを XML 要素に割り当て、SOAP メッセージをネットワーク経由で送信する処理をプロキシ クラスが行います。
サービスの説明が存在し、そのサービスの説明が Web サービス記述言語 (WSDL: Web Services Description Language) に準拠していれば、プロキシ クラスを生成できます。サービスの説明には、Web サービスと通信する方法が定義されています。サービスの説明があれば、Wsdl.exe ツールを使用してプロキシ クラスを作成できます。その後、Web サービス クライアントがプロキシ クラスのメソッドを呼び出します。プロキシ クラスでは Web サービスとの間でやり取りされる SOAP メッセージが処理され、ネットワーク経由で Web サービスと通信します。プロキシ クラスはインターネット経由で Web サービスと通信するため、プロキシ クラスの Url プロパティが、信頼できる通信先を参照していることを確認することをお勧めします。
既定では、プロキシ クラスは SOAP over HTTP を使用して Web サービスと通信します。ただし、Wsdl.exe では、HTTP-GET プロトコルまたは HTTP-POST プロトコルを使用して Web サービスと通信するプロキシ クラスも生成できます。プロキシ クラスでの HTTP-GET または HTTP-POST の使用を指定するには、次の表に示すように、Wsdl.exe ツールに /protocol スイッチを指定します。
Wsdl.exe ツールを使用した XML Web サービス プロキシ クラスの生成
コマンド プロンプトで Web サービス記述言語ツール (Wsdl.exe) を使用し、少なくとも Web サービスまたはサービスの説明への URL を指定するか、保存されているサービスの説明へのパスを指定してプロキシ クラスを作成します。
Wsdl /language:language /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>
.gif "d2s8y7bs.note(ja-jp,VS.100).gif") 注 : |
|---|
| 一般的に Wsdl.exe に使用される引数の一覧を次に示します。Wsdl.exe の完全な構文については、「Web サービス記述言語ツール (Wsdl.exe)」を参照してください。 |
| パラメーター | 値 |
|---|---|
<url or path> |
サービスの説明 (Web サービス記述言語で Web サービスを説明するファイル) の URL またはパス。 ファイルを指定する場合は、サービスの説明が含まれるファイルを指定します。たとえば、次のような方法があります。 mywebservice.wsdl URL を指定する場合、.asmx ページを参照する URL、またはサービスの説明を返す URL を指定する必要があります。ASP.NET を使用して作成した Web サービスでは、Web サービスの URL に ?WSDL を追加すると、サービスの説明を返すことができます。次に例を示します。 https://www.contoso.com/MyWebService.asmx?WSDL |
/language:language |
プロキシ クラスの生成に使用する言語。有効なオプションは、CS (C#)、VB (Visual Basic .NET)、および JS (JScript .NET) です。既定の言語は C# です。この値は省略できます。 |
/protocol:protocol |
Web サービス メソッドとの通信に使用するプロトコル。有効なオプションは、SOAP、HTTP-GET、および HTTP-POST です。既定のプロトコルは SOAP です。この値は省略できます。 |
/namespace:myNameSpace |
生成するプロキシの名前空間。既定値はグローバル名前空間です。(省略可能) |
/out:filename |
作成するプロキシ クラスを含むファイルの名前。既定の名前は、Web サービスを実装するクラスの名前に基づく名前です。(省略可能) |
/username:username |
認証を要求する Web サーバーへの接続時に使用するユーザー名。この値は省略できます。 |
/password:password |
認証を要求する Web サーバーへの接続時に使用するパスワード。この値は省略できます。 |
/domain:domain |
認証を要求する Web サーバーへの接続時に使用するドメイン。この値は省略できます。 |
生成されるプロキシ クラスの詳細
Wsdl.exe を使用してプロキシ クラスを生成すると、指定した言語でソース ファイルが 1 つ作成されます。このファイルには、Web サービスの各 Web サービス メソッドに対応する同期メソッドおよび非同期メソッドの両方を公開するプロキシ クラスが含まれています。たとえば、Add という名前の Web サービス メソッドが Web サービスに含まれる場合は、プロキシ クラスに、Add Web サービス メソッドを呼び出すための Add、BeginAdd、および EndAdd という名前のメソッドが含まれます。**Add Web サービス メソッドと同期的に通信する場合はプロキシ クラスの Add メソッドを使用し、Web サービス メソッドと非同期的に通信する場合は BeginAdd メソッドおよび EndAdd メソッドを使用します。Web サービス メソッドとの非同期通信詳細情報「XML Web サービスとの非同期通信」を参照してください。
生成されるプロキシ クラスの各メソッドには、各 Web サービス メソッドと通信するために必要なコードが含まれています。Web サービスとプロキシ クラスの通信中にエラーが発生した場合は、例外がスローされます。例外の処理詳細情報「XML Web サービスでの例外の処理およびスロー」を参照してください。
Web サービスのメソッドと、関連するプロキシ クラスのメソッドでは、パラメーターの定義順序が異なることがあります。ほとんどの場合、パラメーターの順序は一致しています。ただし、Web サービスが Document 形式の SOAP メッセージを要求する場合は、パラメーターの順序が一致しません。Web サービス メソッドで、in パラメーターの前に out パラメーターが定義されている場合、プロキシ クラスでは、すべての in パラメーターの後に out パラメーターが配置されます。たとえば、次のコード例の MyWebMethod Web サービス メソッドでは、in パラメーターの inStr の前に out パラメーターの outStr が宣言されています。一方、プロキシ クラスでは、outStr パラメーターの前に inStr パラメーターが宣言されています。
' Declare MyWebMethod in the 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)
// Declare MyWebMethod in the 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> を持つ重複するサービスの説明を無視します。
指定された複数のサービスの説明に対する TargetNamespace が同一であることを示しています。TargetNamespace は、特定の XML ドキュメント (この場合はサービスの説明) に対する一意の識別子であると見なされるため、Wsdl.exe は、これらのサービスの説明が同一であると見なします。その場合、Wsdl.exe はいずれか 1 つのサービスの説明に対するプロキシ クラスを 1 つ作成します。この動作が要件と合わない場合は変更できます。ASP.NET を使用して作成した Web サービスを表すサービスの説明に対しては、一意の Namespace プロパティを指定する WebService 属性を、Web サービスを実装するクラスに適用できます。次に、Namespace プロパティがサービスの説明の TargetNamespace として使用され、Web サービスが一意に特定されます。
警告: 場所 <schema URI> からの TargetNamespace=<schema Namespace> を持つ重複するスキーマを無視します。
指定されたサービスの説明で、複数の XML スキーマに対する TargetNamespace が同一であることを示しています。TargetNamespace は、特定の XML ドキュメント (この場合は XML スキーマ) に対する一意の識別子であると見なされるため、Wsdl.exe は、これらの XML スキーマが同一であると見なします。その場合、Wsdl.exe はいずれか 1 つのスキーマに対してのみクラスを作成します。この動作が要件に合わない場合は、それぞれの XML スキーマに対する TargetNamespace を一意の URI に変更する必要があります。TargetNamespace の変更方法は、特定の XML スキーマのソースによって異なります。
参照
処理手順
方法 : ASP.NET を使用して作成した既存の XML Web サービスを調査する
方法 : ブラウザーから XML Web サービスにアクセスする
概念
XML Web サービス クライアントの作成
Web サービス探索
XML Web サービスとの非同期通信