Accessing Services Using a WCF Client


After you create a service, the next step is to create a WCF client proxy. A client application uses the WCF client proxy to communicate with the service. Client applications usually import a service's metadata to generate WCF client code that can be used to invoke the service.

The basic steps for creating a WCF client include the following:

  1. Compile the service code.

  2. Generate the WCF client proxy.

  3. Instantiate the WCF client proxy.

The WCF client proxy can be generated manually by using the Service Model Metadata Utility Tool (SvcUtil.exe) for more information see, ServiceModel Metadata Utility Tool (Svcutil.exe). The WCF client proxy can also be generated within Visual Studio using the Add Service Reference feature. To generate the WCF client proxy using either method the service must be running. If the service is self-hosted you must run the host. If the service is hosted in IIS/WAS you do not need to do anything else.

The ServiceModel Metadata Utility Tool (Svcutil.exe) is a command-line tool for generating code from metadata. The following use is an example of a basic Svcutil.exe command.

Svcutil.exe <service's Metadata Exchange (MEX) address or HTTP GET address>   

Alternatively, you can use Svcutil.exe with Web Services Description Language (WSDL) and XML Schema definition language (XSD) files on the file system.

Svcutil.exe <list of WSDL and XSD files on file system>  

The result is a code file that contains WCF client code that the client application can use to invoke the service.

You can also use the tool to generate configuration files.

Svcutil.exe <file1 [,file2]>  

If only one file name is given, that is the name of the output file. If two file names are given, then the first file is an input configuration file whose contents are merged with the generated configuration and written out into the second file. For more information about configuration, see Configuring Bindings for Services.

System_CAPS_ICON_important.jpg Important

Unsecured metadata requests pose certain risks in the same way that any unsecured network request does: If you are not certain that the endpoint you are communicating with is who it says it is, the information you retrieve might be metadata from a malicious service.

With the service running, right click the project that will contain the WCF client proxy and select Add Service Reference. In the Add Service Reference Dialog type in the URL to the service you want to call and click the Go button. The dialog will display a list of services available at the address you specify. Double click the service to see the contracts and operations available, specify a namespace for the generated code and click the OK button.

The following code example shows a service contract created for a service.

// Define a service contract.  
public interface ICalculator  
    double Add(double n1, double n2);  
    // Other methods are not shown here.  

The ServiceModel Metadata utility tool and Add Service Reference in Visual Studio generates the following WCF client class. The class inherits from the generic ClientBase<TChannel> class and implements the ICalculator interface. The tool also generates the ICalculator interface (not shown here).

public partial class CalculatorClient : System.ServiceModel.ClientBase<ICalculator>, ICalculator  
    public CalculatorClient(){}  
    public CalculatorClient(string configurationName) :   
    public CalculatorClient(System.ServiceModel.Binding binding) :   
    public CalculatorClient(System.ServiceModel.EndpointAddress address,  
    System.ServiceModel.Binding binding) :   
            base(address, binding)  
    public double Add(double n1, double n2)  
        return base.InnerChannel.Add(n1, n2);  

To use the WCF client, create an instance of the WCF client, and then call its methods, as shown in the following code.

// Create a client object with the given client endpoint configuration.  
CalculatorClient calcClient = new CalculatorClient("CalculatorEndpoint"));  
// Call the Add service operation.  
double value1 = 100.00D;  
double value2 = 15.99D;  
double result = calcClient.Add(value1, value2);  
Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result);  

Many exceptions thrown by a WCF client are caused by an exception on the service. Some examples of this are:

  • SocketException: An existing connection was forcibly closed by the remote host.

  • CommunicationException: The underlying connection was closed unexpectedly.

  • CommunicationObjectAbortedException: The socket connection was aborted. This could be caused by an error processing your message, a receive time-out being exceeded by the remote host, or an underlying network resource issue.

When these types of exceptions occur, the best way to solve the problem is to turn on tracing on the service side and determine what exception occurred there. For more information about tracing, see Tracing and Using Tracing to Troubleshoot Your Application.

How to: Create a Client
How to: Access Services with a Duplex Contract
How to: Call Service Operations Asynchronously
How to: Access Services with One-Way and Request-Reply Contracts
How to: Access a WSE 3.0 Service
Understanding Generated Client Code
How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer
Specifying Client Run-Time Behavior
Configuring Client Behaviors