Client Architecture

Applications use Windows Communication Foundation (WCF) client objects to invoke service operations. This topic discusses WCF client objects, WCF client channels, and their relationships to the underlying channel architecture. For a basic overview of WCF client objects, see WCF Client Overview. For more information about the channel layer, see Extending the Channel Layer.

Overview

The service model run time creates WCF clients, which are composed of the following:

• An automatically generated client implementation of a service contract, which turns calls from your application code into outgoing messages, and turns response messages into output parameters and return values that your application can retrieve.

• An implementation of a control interface (System.ServiceModel.IClientChannel) that groups together various interfaces and provides access to control functionality, most notably the ability to close the client session and dispose the channel.

• A client channel that is built based on the configuration settings specified by the used binding.

Applications can create such clients on demand, either through a System.ServiceModel.ChannelFactory or by creating an instance of a ClientBase derived class as it is generated by the ServiceModel Metadata Utility Tool (Svcutil.exe). These ready-built client classes encapsulate and delegate to a client channel implementation that is dynamically constructed by a ChannelFactory. Therefore, the client channel and the channel factory that produces them are the focal point of interest for this discussion.

Client Objects and Client Channels

The base interface of WCF clients is the System.ServiceModel.IClientChannel interface, which exposes core client functionality as well as the basic communication object functionality of System.ServiceModel.ICommunicationObject, the context functionality of System.ServiceModel.IContextChannel, and the extensible behavior of System.ServiceModel.IExtensibleObject.

The IClientChannel interface, however, does not define a service contract itself. Those are declared by the service contract interface (typically generated from service metadata using a tool like the ServiceModel Metadata Utility Tool (Svcutil.exe)). WCF client types extend both IClientChannel and the target service contract interface to enable applications to call operations directly and also have access to client-side run-time functionality. Creating an WCF client provides WCF System.ServiceModel.ChannelFactory objects with the information necessary to create a run time that can connect and interact with the configured service endpoint.

As mentioned earlier, the two WCF client types must be configured before you can use them. The simplest WCF client types are objects that derive from ClientBase (or DuplexClientBase if the service contract is a duplex contract). You can create these types by using a constructor, configured programmatically, or by using a configuration file, and then called directly to invoke service operations. For a basic overview of ClientBase objects, see WCF Client Overview.

The second type is generated at run time from a call to the CreateChannel method. Applications concerned with tight control of the communication specifics typically use this client type, called a client channel object, because it enables more direct interaction than the underlying client run-time and channel system.

Channel Factories

The class that is responsible for creating the underlying run time that supports client invocations is the System.ServiceModel.ChannelFactory class. Both WCF client objects and WCF client channel objects use a ChannelFactory object to create instances; the ClientBase derived client object encapsulates the handling of the channel factory, but for a number of scenarios it is perfectly reasonable to use the channel factory directly. The common scenario for this is if you want to repeatedly create new client channels from an existing factory. If you are using a client object, you can obtain the underlying channel factory from a WCF client object by calling the System.ServiceModel.ClientBase.ChannelFactory property.

The important thing to remember about channel factories is that they create new instances of client channels for the configuration provided to them prior to calling System.ServiceModel.ChannelFactory.CreateChannel. Once you call CreateChannel (or System.ServiceModel.ClientBase.Open, System.ServiceModel.ClientBase.CreateChannel, or any operation on a WCF client object), you cannot modify the channel factory and expect to get channels to different service instances, even if you are merely changing the target endpoint address. If you want to create a client object or client channel with a different configuration, you must create a new channel factory first.

For more information about various issues using WCF client objects and WCF client channels, see Accessing Services Using a Client.

The following two sections describe the creation and use of WCF client channel objects.

Creating a New WCF Client Channel Object

To illustrate the use of a client channel, assume the following service contract has been generated.

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

To connect to an ISampleService service, use the generated contract interface directly with a channel factory (ChannelFactory). Once you create and configure a channel factory for a particular contract, you can call the CreateChannel method to return client channel objects that you can use to communicate with an ISampleService service.

When using the ChannelFactory class with a service contract interface, you must cast to the IClientChannel interface to explicitly open, close, or abort the channel. To make it easier to work with, the Svcutil.exe tool also generates a helper interface that implements both the service contract interface and IClientChannel to enable you to interact with the client channel infrastructure without having to cast. The following code shows the definition of a helper client channel that implements the preceding service contract.

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]
public interface ISampleServiceChannel : ISampleService, System.ServiceModel.IClientChannel
{
}

Creating a New WCF Client Channel Object

To use a client channel to connect to an ISampleService service, use the generated contract interface (or the helper version) directly with a channel factory, passing the type of the contract interface as the type parameter. Once a channel factory for a particular contract has been created and configured, you can call the System.ServiceModel.ChannelFactory.CreateChannel method to return client channel objects that you can use to communicate with an ISampleService service.

When created, the client channel objects implement IClientChannel and the contract interface. Therefore, you can use them directly to call operations that interact with a service that supports that contract.

The difference between using client objects and client channel objects is merely one of control and ease of use for developers. Many developers who are comfortable working with classes and objects will prefer to use the WCF client object instead of the WCF client channel.

For an example, see How to: Use the ChannelFactory.