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 クライアント オブジェクトを作成できます。 構成ファイルを使用してサービスに正しく接続するクライアント オブジェクトを構成できます。

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

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

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

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

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

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

Note

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<TChannel> を拡張する型とサービス コントラクト インターフェイスの 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) は使用しないでください。 詳細については、次のセクションと、Close と Abort を使用した WCF クライアント リソースの解放に関するページを参照してください。

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

WCF クライアント オブジェクトを作成するには、事前にそのクライアント オブジェクトを構成しておく必要があります。 具体的には、使用するサービスの "エンドポイント" を含める必要があります。 エンドポイントは、サービス コントラクト、バインディング、およびアドレスの組み合わせです (エンドポイントの詳細については、「エンドポイント: アドレス、バインディング、およびコントラクト」を参照してください)。この情報は通常、クライアント アプリケーション構成ファイル (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="http://localhost:8080/SampleService" binding="wsHttpBinding"
                bindingConfiguration="WSHttpBinding_ISampleService" contract="ISampleService"
                name="WSHttpBinding_ISampleService">
            </endpoint>
        </client>
    </system.serviceModel>
</configuration>

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

操作の呼び出し

クライアント オブジェクトを作成と構成が完了したら、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 ブロック内で行われます。 詳細については、「WCF クライアントを使用したサービスへのアクセス」および Close と Abort を使用した WCF クライアント リソースの解放に関するページを参照してください。

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.TimeoutException オブジェクトに加え、可能性のある System.ServiceModel.CommunicationException 例外と System.ServiceModel.FaultException 例外を処理することをお勧めします。 操作コントラクトで指定されている SOAP エラーは、System.ServiceModel.FaultException<TDetail> としてクライアント アプリケーションに送信されます。ここで、型パラメーターは SOAP エラーの詳細な型です。 クライアントアプリケーションでのエラー条件の処理の詳細については、「エラーの送受信」を参照してください。 クライアントでのエラーの処理方法を示す詳細な例については、「予期される例外」を参照してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

関連項目