次の方法で共有

WCF クライアントの概要

  • [アーティクル]

このセクションでは、クライアント アプリケーションの処理、Windows Communication Foundation (WCF) クライアントの構成方法、作成方法、使用方法、およびクライアント アプリケーションをセキュリティで保護する方法について説明します。

WCF クライアント オブジェクトの使用

クライアント アプリケーションは、WCF クライアントを使用して別のアプリケーションと通信するマネージ アプリケーションです。WCF サービスのクライアント アプリケーションを作成するには、次の手順に従います。

  1. サービス エンドポイントのサービス コントラクト、バインディング、およびアドレス情報を取得します。

  2. その情報を使用して WCF クライアントを作成します。

  3. 操作を呼び出します。

  4. WCF クライアント オブジェクトを閉じます。

この後の各セクションでは、これらの手順について詳しく説明します。また、次の内容についても簡単に説明します。

  • エラー処理

  • クライアントの構成とセキュリティ保護

  • 双方向サービスのコールバック オブジェクトの作成

  • サービスの非同期呼び出し

  • クライアント チャネルを使用したサービスの呼び出し

サービス コントラクト、バインディング、およびアドレスを取得する

WCF では、サービスとクライアントは、マネージ属性、マネージ インターフェイス、およびマネージ メソッドを使用してコントラクトをモデル化します。クライアント アプリケーションからサービスに接続するには、そのサービス コントラクトの型情報を取得する必要があります。通常これを行うには、ServiceModel メタデータ ユーティリティ ツール (Svcutil.exe) を使用します。このツールは、サービスからメタデータをダウンロードし、それを選択した言語のマネージ ソース コード ファイルに変換して、WCF クライアント オブジェクトの構成に使用できるクライアント アプリケーション構成ファイルを作成します。たとえば、MyCalculatorService を呼び出す WCF クライアント オブジェクトを作成するときに、そのサービスのメタデータが http://computerName/MyCalculatorService/Service.svc?wsdl で公開されていることがわかっている場合に、Svcutil.exe を使用してマネージ コードにサービス コントラクトが含まれている ClientCode.vb ファイルを取得するコード例を次に示します。

svcutil /language:vb /out:ClientCode.vb /config:app.config http://computerName/MyCalculatorService/Service.svc?wsdl

このコントラクト コードをクライアント アプリケーションまたは別のアセンブリにコンパイルし、クライアント アプリケーションでそれを使用して WCF クライアント オブジェクトを作成できます。構成ファイルを使用してサービスに正しく接続するクライアント オブジェクトを構成できます。

このプロセスの例については、「方法 : Windows Communication Foundation クライアントを作成する」を参照してください。コントラクトの詳細については、「コントラクト」を参照してください。

WCF クライアント オブジェクトを作成する

WCF クライアントとは、WCF サービスをクライアントがリモート サービスとの通信に使用できる形式で表すローカル オブジェクトです。WCF クライアント型はターゲットのサービス コントラクトを実装します。したがって、このクライアント型を作成し構成すれば、クライアント オブジェクトを直接使用してサービス操作を呼び出すことができます。WCF ランタイムは、メソッド呼び出しをメッセージに変換してサービスに送信し、応答をリッスンして、その値を WCF クライアント オブジェクトに戻り値または out や ref パラメーターとして返します。

また、サービスとの通信やサービスの使用に WCF クライアント チャネル オブジェクトも使用できます。詳細については、「クライアント アーキテクチャ」を参照してください。

新しい WCF オブジェクトの作成

サービスアプリケーションから次の簡単なサービス コントラクトが生成されていることを前提に、ClientBase クラスの使用方法を説明します。

ms735103.note(ja-jp,VS.100).gif注 :
Visual Studio を使用して WCF クライアントを作成する場合、サービス参照をプロジェクトに追加すると、オブジェクトはオブジェクト ブラウザーに自動的に読み込まれます。 

[System.ServiceModel.ServiceContractAttribute(
  Namespace = "http://microsoft.wcf.documentation"
)]
public interface ISampleService
{
    [System.ServiceModel.OperationContractAttribute(
      Action = "http://microsoft.wcf.documentation/ISampleService/SampleMethod",
      ReplyAction = "http://microsoft.wcf.documentation/ISampleService/SampleMethodResponse"
    )]
    [System.ServiceModel.FaultContractAttribute(
      typeof(microsoft.wcf.documentation.SampleFault),
      Action = "http://microsoft.wcf.documentation/ISampleService/SampleMethodSampleFaultFault"
    )]
    string SampleMethod(string msg);
}

Visual Studio を使用しない場合は、生成されたコントラクト コードを調べて ClientBase を拡張する型とサービス コントラクト インターフェイスの ISampleService を見つけます。この場合、この型は次のようなコードになります。

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]
public partial class SampleServiceClient : System.ServiceModel.ClientBase<ISampleService>, ISampleService
{

    public SampleServiceClient()
    {
    }

    public SampleServiceClient(string endpointConfigurationName)
        :
            base(endpointConfigurationName)
    {
    }

    public SampleServiceClient(string endpointConfigurationName, string remoteAddress)
        :
            base(endpointConfigurationName, remoteAddress)
    {
    }

    public SampleServiceClient(string endpointConfigurationName, System.ServiceModel.EndpointAddress remoteAddress)
        :
            base(endpointConfigurationName, remoteAddress)
    {
    }

    public SampleServiceClient(System.ServiceModel.Channels.Binding binding, System.ServiceModel.EndpointAddress remoteAddress)
        :
            base(binding, remoteAddress)
    {
    }
    public string SampleMethod(string msg)
    {
        return base.Channel.SampleMethod(msg);
    }
}

このクラスを、コンストラクターの 1 つを使用してローカル オブジェクトとして作成し、構成して、型 ISampleService のサービスへの接続に使用できます。

まず WCF クライアント オブジェクトを作成し、それを 1 つの try/catch ブロック内で使用して閉じることをお勧めします。特定のエラー モードで例外をマスクする場合があるので、using ステートメント (Visual Basic では Using) を使用しないでください。詳細については、次のトピックを参照してください。この後の各セクションおよび「Using ステートメントに関する問題の回避」を参照してください。

コントラクト、バインディング、およびアドレス

WCF クライアント オブジェクトを作成するには、クライアント オブジェクトを構成する必要があります。具体的には、使用するサービスの "エンドポイント" を含める必要があります。エンドポイントは、サービス コントラクト、バインディング、およびアドレスの組み合わせです (エンドポイント詳細情報、「エンドポイント : アドレス、バインディング、およびコントラクト」を参照してください)。通常この情報は、クライアント アプリケーションの構成ファイルの <endpoint> 要素内にあります。この構成ファイルは、たとえば、Svcutil.exe ツールで生成するとクライアント オブジェクト作成時に自動的に読み込まれます。両方の WCF クライアント型には、この情報をプログラムで指定できるオーバーロードもあります。

たとえば、上記の例で使用した ISampleService 用に生成された構成ファイルには、次のエンドポイント情報が含まれます。

<configuration>
    <system.serviceModel>
        <bindings>
            <wsHttpBinding>
                <binding name="WSHttpBinding_ISampleService" closeTimeout="00:01:00"
                    openTimeout="00:01:00" receiveTimeout="00:01:00" sendTimeout="00:01:00"
                    bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard"
                    maxBufferPoolSize="524288" maxReceivedMessageSize="65536"
                    messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true"
                    allowCookies="false">
                    <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384"
                        maxBytesPerRead="4096" maxNameTableCharCount="16384" />
                    <reliableSession ordered="true" inactivityTimeout="00:10:00"
                        enabled="false" />
                    <security mode="Message">
                        <transport clientCredentialType="None" proxyCredentialType="None"
                            realm="" />
                        <message clientCredentialType="Windows" negotiateServiceCredential="true"
                            algorithmSuite="Default" establishSecurityContext="true" />
                    </security>
                </binding>
            </wsHttpBinding>
        </bindings>
        <client>
            <endpoint address="https://localhost:8080/SampleService" binding="wsHttpBinding"
                bindingConfiguration="WSHttpBinding_ISampleService" contract="ISampleService"
                name="WSHttpBinding_ISampleService">
            </endpoint>
        </client>
    </system.serviceModel>
</configuration>

この構成ファイルの <client> 要素には、ターゲット エンドポイントが指定されます。複数のターゲット エンドポイントを使用する方法詳細情報、System.ServiceModel.ClientBase.#ctor(System.String) コンストラクターまたは System.ServiceModel.ChannelFactory.#ctor(System.String) コンストラクターを参照してください。

操作の呼び出し

クライアント オブジェクトを作成し構成したら、try/catch ブロックを作成し、ローカルのオブジェクトの場合と同じ方法で操作を呼び出して、WCF クライアント オブジェクトを閉じます。クライアント アプリケーションが最初の操作を呼び出すときに、WCF は、基になるチャネルを自動的に開きます。基になるチャネルはオブジェクトが再利用されるときに閉じられます (また、他の操作を呼び出す前後にチャネルを明示的に開いたり閉じたりすることもできます)。

たとえば、次のようなサービス コントラクトを使用する場合があります。

namespace Microsoft.ServiceModel.Samples
{
    using System;
    using System.ServiceModel;

    [ServiceContract(Namespace = "http://Microsoft.ServiceModel.Samples")]
    public interface ICalculator
   {
        [OperationContract]
        double Add(double n1, double n2);
        [OperationContract]
        double Subtract(double n1, double n2);
        [OperationContract]
        double Multiply(double n1, double n2);
        [OperationContract]
        double Divide(double n1, double n2);
    }
}

Namespace Microsoft.ServiceModel.Samples

    Imports System
    Imports System.ServiceModel

    <ServiceContract(Namespace:= _
    "http://Microsoft.ServiceModel.Samples")> _ 
   Public Interface ICalculator
        <OperationContract> _ 
        Function Add(n1 As Double, n2 As Double) As Double
        <OperationContract> _ 
        Function Subtract(n1 As Double, n2 As Double) As Double
        <OperationContract> _ 
        Function Multiply(n1 As Double, n2 As Double) As Double
        <OperationContract> _ 
     Function Divide(n1 As Double, n2 As Double) As Double
End Interface

次のコード例で示すように、WCF クライアント オブジェクトを作成し、そのメソッドを呼び出すことで操作を呼び出すことができます。WCF クライアント オブジェクトのオープン、呼び出し、クローズは、1 つの try/catch ブロック内で行われます。詳細については、次のトピックを参照してください。、「クライアントを使用したサービスへのアクセス」および「Using ステートメントに関する問題の回避」を参照してください。

CalculatorClient wcfClient = new CalculatorClient();
try
{
    Console.WriteLine(wcfClient.Add(4, 6));
    wcfClient.Close();
}
catch (TimeoutException timeout)
{
    // Handle the timeout exception.
    wcfClient.Abort();
}
catch (CommunicationException commException)
{
    // Handle the communication exception.
    wcfClient.Abort();
}

エラー処理

基になるクライアント チャネルを開いたとき (明示的に開いた場合、または操作を呼び出すことによって自動的に開いた場合)、クライアントまたはチャネル オブジェクトを使用して操作を呼び出したとき、基になるクライアント チャネルを閉じたときに、クライアント アプリケーションで例外が発生する可能性があります。少なくともアプリケーションでは、操作から返される SOAP エラーの結果としてスローされる System.ServiceModel.FaultException オブジェクトに加え、可能性のある System.TimeoutException 例外と System.ServiceModel.CommunicationException 例外を処理することをお勧めします。操作コントラクトで指定されている SOAP エラーは、System.ServiceModel.FaultException としてクライアント アプリケーションに送信されます。ここで、型パラメーターは SOAP エラーの詳細な型です。クライアント アプリケーションでエラー状況を処理する方法詳細情報、「エラーの送受信」を参照してください。クライアントでのエラー処理方法を示す詳細な例については、「予期される例外」を参照してください。

クライアントの構成とセキュリティ保護

クライアントを構成するには、まず、そのクライアントまたはチャネル オブジェクトに必要なターゲット エンドポイント情報を読み込みます。通常は構成ファイルから読み込みますが、クライアント コンストラクターとプロパティを使用してプログラムで読み込むこともできます。ただし、特定のクライアントの動作を有効にし、多くのセキュリティ シナリオに対応するには、追加の構成手順が必要です。

たとえば、サービス コントラクトのセキュリティ要件はサービス コントラクト インターフェイスに宣言します。Svcutil.exe で構成ファイルを作成した場合、通常そのファイルにはサービスのセキュリティ要件に対応できるバインディングが含まれています。ただし、クライアント資格情報の構成など、さらに多くのセキュリティ構成が必要な場合もあります。WCF クライアントのセキュリティ構成の詳細については、「クライアントのセキュリティ保護」を参照してください。

また、カスタム ランタイム動作など、クライアント アプリケーションでいくつかのカスタム変更を有効にすることもできます。カスタム クライアント動作の構成方法詳細情報、「クライアントの動作の構成」を参照してください。

双方向サービスのコールバック オブジェクトの作成

双方向サービスには、コントラクトの要件に従って呼び出すサービスのコールバック オブジェクトを提供するために、クライアント アプリケーションが実装する必要のあるコールバック コントラクトを指定します。コールバック オブジェクトは完全なサービスではありません (たとえば、コールバック オブジェクトを使用してチャネルを初期化できません) が、実装と構成という目的においては、一種のサービスとして考えることができます。

双方向サービスのクライアントでは、以下の処理を行う必要があります。

  • コールバック コントラクト クラスを実装します。

  • コールバック コントラクト実装クラスのインスタンスを作成し、それを使用して、WCF クライアント コンストラクターに渡す System.ServiceModel.InstanceContext オブジェクトを作成します。

  • 操作を呼び出し、操作のコールバックを処理します。

WCF の双方向クライアント オブジェクトは、対応する非双方向クライアント オブジェクトと同じように機能します。ただし、双方向クライアント オブジェクトは、コールバック サービスの構成など、コールバックのサポートに必要な機能を公開します。

たとえば、コールバック クラスの System.ServiceModel.CallbackBehaviorAttribute 属性のプロパティを使用して、コールバック オブジェクトの実行時の動作のさまざまな局面を制御できます。また、別の例として、System.ServiceModel.Description.CallbackDebugBehavior クラスを使用して、例外情報をコールバック オブジェクトを呼び出したサービスに返すこともできます。詳細については、次のトピックを参照してください。、「双方向サービス」を参照してください。サンプル全体については、「双方向」を参照してください。

インターネット インフォメーション サービス (IIS) 5.1 を実行する Windows XP コンピューターの場合、双方向クライアントでは System.ServiceModel.WSDualHttpBinding クラスを使用してクライアントのベース アドレスを指定する必要があります。そうしない場合は例外がスローされます。次のコード例は、コードでこれを指定する方法を示します。

Dim dualBinding As New WSDualHttpBinding()
Dim endptadr As New EndpointAddress("https://localhost:12000/DuplexTestUsingCode/Server")
dualBinding.ClientBaseAddress = New Uri("https://localhost:8000/DuplexTestUsingCode/Client/")

WSDualHttpBinding dualBinding = new WSDualHttpBinding();
EndpointAddress endptadr = new EndpointAddress("https://localhost:12000/DuplexTestUsingCode/Server");
dualBinding.ClientBaseAddress = new Uri("https://localhost:8000/DuplexTestUsingCode/Client/");

次のコードは、構成ファイルでこれを指定する方法を示します。

'      <client>
'        <endpoint 
'          name ="ServerEndpoint" 
'          address="https://localhost:12000/DuplexUsingConfig/Server"
'          bindingConfiguration="WSDualHttpBinding_IDuplex" 
'          binding="wsDualHttpBinding"
'          contract="IDuplex" 
'      />
'      </client>
'      <bindings>
'        <wsDualHttpBinding>
'          <binding 
'            name="WSDualHttpBinding_IDuplex"  
'            clientBaseAddress="https://localhost:8000/myClient/" 
'          />
'        </wsDualHttpBinding>
'      </bindings>

<client>
  <endpoint 
    name ="ServerEndpoint" 
    address="https://localhost:12000/DuplexUsingConfig/Server"
    bindingConfiguration="WSDualHttpBinding_IDuplex" 
    binding="wsDualHttpBinding"
    contract="IDuplex" 
/>
</client>
<bindings>
  <wsDualHttpBinding>
    <binding 
      name="WSDualHttpBinding_IDuplex"  
      clientBaseAddress="https://localhost:8000/myClient/" 
    />
  </wsDualHttpBinding>
</bindings>

サービスの非同期呼び出し

操作の呼び出し方法は、クライアント開発者に完全に依存します。これは、操作を構成するメッセージは、マネージ コードで表現するときに同期メソッドまたは非同期メソッドのどちらかにマップできるためです。したがって、操作を非同期に呼び出すクライアントを作成する場合、Svcutil.exe の /async オプションを使用して非同期クライアント コードを生成できます。詳細については、次のトピックを参照してください。、「方法 : WCF サービス操作を非同期に呼び出す」を参照してください。

WCF クライアント チャネルを使用したサービスの呼び出し

WCF クライアント型は、System.ServiceModel.IClientChannel インターフェイスから派生して基になるチャネル システムを公開する ClientBase を拡張します。ターゲットのサービス コントラクトと System.ServiceModel.ChannelFactory クラスを使用して、サービスを呼び出すことができます。詳細については、「クライアント アーキテクチャ」を参照してください。

参照

リファレンス

System.ServiceModel.ClientBase
System.ServiceModel.ChannelFactory