Share via

Accessing Services Using a WCF Client

After you create a service, the next step is to create a WCF client. A client application uses the WCF client 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. Use the ServiceModel Metadata Utility Tool (SvcUtil.exe) to create the WCF client.

ServiceModel Metadata Utility Tool

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 Windows Communication Foundation Services.


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.


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.
' Define a service contract.
<ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")> _
Public Interface ICalculator
    <OperationContract()>  _
    Function Add(ByVal n1 As Double, ByVal n2 As Double) As Double 
    ' Other methods are not shown here.
End Interface 

The ServiceModel Metadata utility tool generates the following WCF client class. The class inherits from the generic ClientBase 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);
Partial Public Class CalculatorClient
    Inherits System.ServiceModel.ClientBase(Of ICalculator)
    Implements ICalculator
    Public Sub New()
    End Sub
    Public Sub New(ByVal configurationName As String)
    End Sub
    Public Sub New(ByVal binding As System.ServiceModel.Binding)
    End Sub
    Public Sub New(ByVal address As _
    System.ServiceModel.EndpointAddress, _
    ByVal binding As System.ServiceModel.Binding)
        MyBase.New(address, binding)
    End Sub
    Public Function Add(ByVal n1 As Double, ByVal n2 As Double) As _
    Double Implements ICalculator.Add
        Return MyBase.InnerChannel.Add(n1, n2)
    End Function 
End Class

Using the WCF Client

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);
' Create a client object with the given client endpoint configuration.
Dim calcClient As CalculatorClient = _
New CalculatorClient("CalculatorEndpoint")

' Call the Add service operation.
Dim value1 As Double = 100.00D
Dim value2 As Double = 15.99D
Dim result As Double = calcClient.Add(value1, value2)
Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result)

Debugging Exceptions Thrown by a Client

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. tracing, see WCF Tracing and Using Tracing to Troubleshoot Your Application.

See Also


How to: Create a Windows Communication Foundation Client
How to: Access Services with a Duplex Contract
How to: Call WCF Service Operations Asynchronously
How to: Access WCF Services with One-Way and Request-Reply Contracts
How to: Access a WSE 3.0 Service with a WCF Client
How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer


Understanding Generated Client Code
Specifying Client Run-Time Behavior
Configuring Client Behaviors