WCF クライアントの概要WCF Client Overview

このセクションでは、クライアント アプリケーションの処理、構成、作成、および Windows Communication Foundation (WCF) クライアントを使用する方法、およびクライアント アプリケーションをセキュリティで保護する方法について説明します。This section describes what client applications do, how to configure, create, and use a Windows Communication Foundation (WCF) client, and how to secure client applications.

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

クライアント アプリケーションでは、別のアプリケーションと通信する WCF クライアントを使用するマネージ アプリケーションです。A client application is a managed application that uses a WCF client to communicate with another application. クライアントを作成するには、WCF サービスのアプリケーションには、次の手順が必要です。To create a client application for a WCF service requires the following steps:

  1. サービス エンドポイントのサービス コントラクト、バインディング、およびアドレス情報を取得します。Obtain the service contract, bindings, and address information for a service endpoint.

  2. その情報を使用して WCF クライアントを作成します。Create a WCF client using that information.

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

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

この後の各セクションでは、これらの手順について詳しく説明します。また、次の内容についても簡単に説明します。The following sections discuss these steps and provide brief introductions to the following issues:

  • エラー処理Handling errors.

  • クライアントの構成とセキュリティ保護Configuring and securing clients.

  • 双方向サービスのコールバック オブジェクトの作成Creating callback objects for duplex services.

  • サービスの非同期呼び出しCalling services asynchronously.

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

サービス コントラクト、バインディング、およびアドレスを取得するObtain the Service Contract, Bindings, and Addresses

WCF では、サービスとクライアントは、マネージ属性、インターフェイス、およびメソッドを使用してコントラクトをモデルします。In WCF, services and clients model contracts using managed attributes, interfaces, and methods. クライアント アプリケーションからサービスに接続するには、そのサービス コントラクトの型情報を取得する必要があります。To connect to a service in a client application, you need to obtain the type information for the service contract. 通常、これを行うを使用して、 ServiceModel メタデータ ユーティリティ ツール (Svcutil.exe)、サービスからメタデータをダウンロード、好みの言語でのマネージ ソース コード ファイルに変換し、クライアントを作成します。WCF クライアント オブジェクトを構成に使用できるアプリケーション構成ファイル。Typically, you do this by using the ServiceModel Metadata Utility Tool (Svcutil.exe), which downloads metadata from the service, converts it to a managed source code file in the language of your choice, and creates a client application configuration file that you can use to configure your WCF client object. 呼び出す、WCF クライアント オブジェクトを作成する場合など、MyCalculatorServiceでそのサービスのメタデータが公開されていることがわかってhttp://computerName/MyCalculatorService/Service.svc?wsdl、次のコード例は、Svcutil.exe を使用して取得する方法を示していますその後、ClientCode.vbファイル。マネージ コードでサービス コントラクトが含まれています。For example, if you are going to create an WCF client object to invoke a MyCalculatorService, and you know that the metadata for that service is published at http://computerName/MyCalculatorService/Service.svc?wsdl, then the following code example shows how to use Svcutil.exe to obtain a ClientCode.vb file that contains the service contract in managed code.

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

クライアント アプリケーションやクライアント アプリケーションは WCF クライアント オブジェクトを作成し、使用できる別のアセンブリに、このコントラクト コードをコンパイルできます。You can either compile this contract code into the client application or into another assembly that the client application can then use to create an WCF client object. 構成ファイルを使用してサービスに正しく接続するクライアント オブジェクトを構成できます。You can use the configuration file to configure the client object to properly connect to the service .

このプロセスの例は、次を参照してください。方法。クライアントを作成するします。For an example of this process, see How to: Create a Client. コントラクトの詳細については、次を参照してください。コントラクトします。For more complete information about contracts, see Contracts.

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

WCF クライアントは、クライアントがリモート サービスとの通信に使用できる形式で WCF サービスを表すローカル オブジェクトです。A WCF client is a local object that represents a WCF service in a form that the client can use to communicate with the remote service. WCF クライアントの種類、対象サービスを実装するコントラクト、サービス操作を呼び出すには、直接クライアント オブジェクトを使用できますし、1 つ作成し、構成したときにします。WCF client types implement the target service contract, so when you create one and configure it, you can then use the client object directly to invoke service operations. WCF ランタイム メソッドの呼び出しをメッセージに変換、サービスに送信、応答をリッスンおよび戻り値として、WCF クライアント オブジェクトにこれらの値を返しますまたはoutまたはrefパラメーター。The WCF run time converts the method calls into messages, sends them to the service, listens for the reply, and returns those values to the WCF client object as return values or out or ref parameters.

接続してサービスを使用して WCF クライアント チャネル オブジェクトを使用することもできます。You can also use WCF client channel objects to connect with and use services. 詳細については、次を参照してください。 WCF クライアント アーキテクチャします。For details, see WCF Client Architecture.

新しい WCF オブジェクトの作成Creating a New WCF Object

サービスアプリケーションから次の簡単なサービス コントラクトが生成されていることを前提に、ClientBase<TChannel> クラスの使用方法を説明します。To illustrate the use of a ClientBase<TChannel> class, assume the following simple service contract has been generated from a service application.

注意

場合は、WCF クライアントを作成する Visual Studio を使用するオブジェクトに読み込まれます自動的にオブジェクト ブラウザーをプロジェクトにサービス参照を追加する場合。If you are using Visual Studio to create your WCF client, objects are loaded automatically into the object browser when you add a service reference to your project.

[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します。If you are not using Visual Studio, examine the generated contract code to find the type that extends ClientBase<TChannel> and the service contract interface ISampleService. この場合、この型は次のようなコードになります。In this case, that type looks like the following code:

[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 のサービスへの接続に使用できます。This class can be created as a local object using one of the constructors, configured, and then used to connect to a service of the type ISampleService.

最初に、WCF クライアント オブジェクトを作成し、それを使用して閉じて、1 つの try/catch ブロック内でお勧めします。It is recommended that you create your WCF client object first, and then use it and close it inside a single try/catch block. 使用しないようにする、usingステートメント (Using Visual Basic で) 特定のエラー モードでの例外をマスクする場合があるためです。You should not use the using statement (Using in Visual Basic) because it may mask exceptions in certain failure modes. 詳細については、次のセクションを参照してください。 だけでなく使用終了、中止 WCF クライアントのリソースを解放するします。For more information, see the following sections as well as Use Close and Abort to release WCF client resources.

コントラクト、バインディング、およびアドレスContracts, Bindings, and Addresses

WCF クライアント オブジェクトを作成するには、クライアント オブジェクトを構成する必要があります。Before you can create a WCF client object, you must configure the client object. 具体的には、サービスがありますエンドポイントを使用します。Specifically, it must have a service endpoint to use. エンドポイントは、サービス コントラクト、バインディング、およびアドレスの組み合わせです An endpoint is the combination of a service contract, a binding, and an address. (エンドポイントの詳細については、次を参照してください。エンドポイント。アドレス、バインディング、およびコントラクト)。通常、この情報にある、 <エンドポイント > Svcutil.exe ツールを生成して、クライアントを作成するときに自動的に読み込まれますなど、クライアントのアプリケーション構成ファイル内の要素オブジェクト。(For more information about endpoints, see Endpoints: Addresses, Bindings, and Contracts.) Typically, this information is located in the <endpoint> element in a client application configuration file, such as the one the Svcutil.exe tool generates, and is loaded automatically when you create your client object. WCF クライアントの両方の種類では、プログラムでこの情報を指定するためのオーバー ロードもあります。Both WCF client types also have overloads that enable you to programmatically specify this information.

たとえば、上記の例で使用した ISampleService 用に生成された構成ファイルには、次のエンドポイント情報が含まれます。For example, a generated configuration file for an ISampleService used in the preceding examples contains the following endpoint information.

<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> 要素には、ターゲット エンドポイントが指定されます。This configuration file specifies a target endpoint in the <client> element. 詳細については、複数のターゲット エンドポイントを使用して、次を参照してください。、ClientBase<TChannel>.ClientBase<TChannel>またはChannelFactory<TChannel>.ChannelFactory<TChannel>コンス トラクター。For more information about using multiple target endpoints, see the ClientBase<TChannel>.ClientBase<TChannel> or the ChannelFactory<TChannel>.ChannelFactory<TChannel> constructors.

操作の呼び出しCalling Operations

1 回クライアント オブジェクトを作成し、構成するには、try/catch ブロックを作成、オブジェクトは、ローカルの場合と同じ方法で操作を呼び出しておよび WCF クライアント オブジェクトを閉じます。Once you have a client object created and configured, create a try/catch block, call operations in the same way that you would if the object were local, and close the WCF client object. クライアント アプリケーションが最初の操作を呼び出すと WCF は、基になるチャネルを自動的に開き、オブジェクトをリサイクルするときに、基になるチャネルが閉じられます。When the client application calls the first operation, WCF automatically opens the underlying channel, and the underlying channel is closed when the object is recycled. (また、他の操作を呼び出す前後にチャネルを明示的に開いたり閉じたりすることもできます)。(Alternatively, you can also explicitly open and close the channel prior to or subsequent to calling other operations.)

たとえば、次のようなサービス コントラクトを使用する場合があります。For example, if you have the following service contract:

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 クライアント オブジェクトを作成する操作を呼び出すことができ、次のコード例として、そのメソッドを呼び出すことを示します。You can call operations by creating a WCF client object and calling its methods, as the following code example demonstrates. 開始タグを呼び出しと WCF クライアント オブジェクトの終了が 1 つの try/catch ブロック内で発生することに注意してください。Note that the opening, calling, and closing of the WCF client object occurs within a single try/catch block. 詳細については、次を参照してください。にアクセスするサービスの WCF クライアントを使用して使用終了、中止 WCF クライアントのリソースを解放するします。For more information, see Accessing Services Using a WCF Client and Use Close and Abort to release WCF client resources.

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();
}

エラー処理Handling Errors

基になるクライアント チャネルを開いたとき (明示的に開いた場合、または操作を呼び出すことによって自動的に開いた場合)、クライアントまたはチャネル オブジェクトを使用して操作を呼び出したとき、基になるクライアント チャネルを閉じたときときに、クライアント アプリケーションで例外が発生する可能性があります。Exceptions can occur in a client application when opening the underlying client channel (whether explicitly or automatically by calling an operation), using the client or channel object to call operations, or when closing the underlying client channel. 少なくともアプリケーションでは、操作から返される SOAP エラーの結果としてスローされる System.TimeoutException オブジェクトに加え、可能性のある System.ServiceModel.CommunicationException 例外と System.ServiceModel.FaultException 例外を処理することをお勧めします。It is recommended at a minimum that applications expect to handle possible System.TimeoutException and System.ServiceModel.CommunicationException exceptions in addition to any System.ServiceModel.FaultException objects thrown as a result of SOAP faults returned by operations. 操作コントラクトで指定されている SOAP エラーは、System.ServiceModel.FaultException<TDetail> としてクライアント アプリケーションに送信されます。ここで、型パラメーターは SOAP エラーの詳細な型です。SOAP faults specified in the operation contract are raised to client applications as a System.ServiceModel.FaultException<TDetail> where the type parameter is the detail type of the SOAP fault. クライアント アプリケーションでエラー状態の処理の詳細については、次を参照してください。 Sending and Receiving Faultsします。For more information about handling error conditions in a client application, see Sending and Receiving Faults. 詳細な例に示すクライアントでのエラーを処理する方法を参照してください。予想例外します。For a complete sample the shows how to handle errors in a client, see Expected Exceptions.

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

クライアントを構成するには、まず、そのクライアントまたはチャネル オブジェクトに必要なターゲット エンドポイント情報を読み込みます。通常は構成ファイルから読み込みますが、クライアント コンストラクターとプロパティを使用してプログラムで読み込むこともできます。Configuring a client starts with the required loading of target endpoint information for the client or channel object, usually from a configuration file, although you can also load this information programmatically using the client constructors and properties. ただし、特定のクライアントの動作を有効にし、多くのセキュリティ シナリオに対応するには、追加の構成手順が必要です。However, additional configuration steps are required to enable certain client behavior and for many security scenarios.

たとえば、サービス コントラクトのセキュリティ要件はサービス コントラクト インターフェイスに宣言します。Svcutil.exe で構成ファイルを作成した場合、通常そのファイルにはサービスのセキュリティ要件に対応できるバインディングが含まれています。For example, security requirements for service contracts are declared in the service contract interface, and if Svcutil.exe created a configuration file, that file usually contains a binding that is capable of supporting the security requirements of the service. ただし、クライアント資格情報の構成など、さらに多くのセキュリティ構成が必要な場合もあります。In some cases, however, more security configuration may be required, such as configuring client credentials. WCF クライアントのセキュリティの構成については、次を参照してください。クライアントのセキュリティで保護するします。For complete information about the configuration of security for WCF clients, see Securing Clients.

また、カスタム ランタイム動作など、クライアント アプリケーションでいくつかのカスタム変更を有効にすることもできます。In addition, some custom modifications can be enabled in client applications, such as custom run-time behaviors. カスタム クライアント動作を構成する方法の詳細については、次を参照してください。クライアントの動作を構成するします。For more information about how to configure a custom client behavior, see Configuring Client Behaviors.

双方向サービスのコールバック オブジェクトの作成Creating Callback Objects for Duplex Services

双方向サービスには、コントラクトの要件に従って呼び出すサービスのコールバック オブジェクトを提供するために、クライアント アプリケーションが実装する必要のあるコールバック コントラクトを指定します。Duplex services specify a callback contract that the client application must implement in order to provide a callback object for the service to call according to the requirements of the contract. コールバック オブジェクトは完全なサービスではありません (たとえば、コールバック オブジェクトを使用してチャネルを初期化できません) が、実装と構成という目的においては、一種のサービスとして考えることができます。Although callback objects are not full services (for example, you cannot initiate a channel with a callback object), for the purposes of implementation and configuration they can be thought of as a kind of service.

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

  • コールバック コントラクト クラスを実装します。Implement a callback contract class.

  • コールバック コントラクト実装クラスのインスタンスを作成し、使用して作成する、 System.ServiceModel.InstanceContext WCF クライアント コンス トラクターに渡すオブジェクト。Create an instance of the callback contract implementation class and use it to create the System.ServiceModel.InstanceContext object that you pass to the WCF client constructor.

  • 操作を呼び出し、操作のコールバックを処理します。Invoke operations and handle operation callbacks.

双方向の WCF クライアント オブジェクトの関数などの対応する双方向コールバック サービスの構成など、コールバックをサポートするために必要な機能を公開する例外を使用します。Duplex WCF client objects function like their nonduplex counterparts, with the exception that they expose the functionality necessary to support callbacks, including the configuration of the callback service.

たとえば、コールバック クラスの System.ServiceModel.CallbackBehaviorAttribute 属性のプロパティを使用して、コールバック オブジェクトの実行時の動作のさまざまな局面を制御できます。For example, you can control various aspects of callback object runtime behavior by using properties of the System.ServiceModel.CallbackBehaviorAttribute attribute on the callback class. また、別の例として、System.ServiceModel.Description.CallbackDebugBehavior クラスを使用して、例外情報をコールバック オブジェクトを呼び出したサービスに返すこともできます。Another example is the use of the System.ServiceModel.Description.CallbackDebugBehavior class to enable the return of exception information to services that call the callback object. 詳細については、次を参照してください。双方向サービスします。For more information, see Duplex Services. 完全なサンプルを参照してください。双方向します。For a complete sample, see Duplex.

インターネット インフォメーション サービス (IIS) 5.1 を実行する Windows XP コンピューターの場合、双方向クライアントでは System.ServiceModel.WSDualHttpBinding クラスを使用してクライアントのベース アドレスを指定する必要があります。そうしない場合は例外がスローされます。On Windows XP computers running Internet Information Services (IIS) 5.1, duplex clients must specify a client base address using the System.ServiceModel.WSDualHttpBinding class or an exception is thrown. 次のコード例は、コードでこれを指定する方法を示します。The following code example shows how to do this in code.

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/")

次のコードは、構成ファイルでこれを指定する方法を示します。The following code shows how to do this in a configuration file

<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>

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

操作の呼び出し方法は、クライアント開発者に完全に依存します。How operations are called is entirely up to the client developer. これは、操作を構成するメッセージは、マネージ コードで表現するときに同期メソッドまたは非同期メソッドのどちらかにマップできるためです。This is because the messages that make up an operation can be mapped to either synchronous or asynchronous methods when expressed in managed code. したがって、操作を非同期に呼び出すクライアントを作成する場合、Svcutil.exe の /async オプションを使用して非同期クライアント コードを生成できます。Therefore, if you want to build a client that calls operations asynchronously, you can use Svcutil.exe to generate asynchronous client code using the /async option. 詳細については、「方法 :サービス操作を非同期的に呼び出すします。For more information, see How to: Call Service Operations Asynchronously.

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

WCF クライアントの型を拡張ClientBase<TChannel>から派生したSystem.ServiceModel.IClientChannel基になるチャネル システムを公開するインターフェイス。WCF client types extend ClientBase<TChannel>, which itself derives from System.ServiceModel.IClientChannel interface to expose the underlying channel system. ターゲットのサービス コントラクトと System.ServiceModel.ChannelFactory<TChannel> クラスを使用して、サービスを呼び出すことができます。You can invoke services by using the target service contract with the System.ServiceModel.ChannelFactory<TChannel> class. 詳細については、次を参照してください。 WCF クライアント アーキテクチャします。For details, see WCF Client Architecture.

関連項目See also