Accessing Services Using a WCF Client

Article
03/22/2023

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:

Compile the service code.
Generate the WCF client proxy.
See Also
WCF services and ASP.NET - WCF Working with WCF Services through ASP.NET (A step-by-step guide)Service Trace Viewer Tool (SvcTraceViewer.exe) - WCF Consuming WCF Web Services in .NET Core - Best Practices
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.

Add Service Reference in Visual Studio

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.

Example

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

// Define a service contract.[ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")]public interface ICalculator{ [OperationContract] 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 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 endpointConfigurationName) : base(endpointConfigurationName) {} public CalculatorClient(string endpointConfigurationName, string remoteAddress) : base(endpointConfigurationName, remoteAddress) {} public CalculatorClient(string endpointConfigurationName, System.ServiceModel.EndpointAddress remoteAddress) : base(endpointConfigurationName, remoteAddress) {} public CalculatorClient(System.ServiceModel.Channels.Binding binding, System.ServiceModel.EndpointAddress remoteAddress) : base(binding, remoteAddress) {} public double Add(double n1, double n2) { return base.Channel.Add(n1, n2); }}

Partial Public Class CalculatorClient Inherits System.ServiceModel.ClientBase(Of ICalculator) Implements ICalculator Public Sub New() MyBase.New End Sub Public Sub New(ByVal endpointConfigurationName As String) MyBase.New(endpointConfigurationName) End Sub Public Sub New(ByVal endpointConfigurationName As String, ByVal remoteAddress As String) MyBase.New(endpointConfigurationName, remoteAddress) End Sub Public Sub New(ByVal endpointConfigurationName As String, ByVal remoteAddress As System.ServiceModel.EndpointAddress) MyBase.New(endpointConfigurationName, remoteAddress) End Sub Public Sub New(ByVal binding As System.ServiceModel.Channels.Binding, ByVal remoteAddress As System.ServiceModel.EndpointAddress) MyBase.New(binding, remoteAddress) End Sub Public Function Add(ByVal n1 As Double, ByVal n2 As Double) As Double Implements ICalculator.Add Return MyBase.Channel.Add(n1, n2) End FunctionEnd 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.00DDim value2 As Double = 15.99DDim 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. For more information about tracing, see Tracing and Using Tracing to Troubleshoot Your Application.

Accessing Services Using a WCF Client - WCF (2024)

Add Service Reference in Visual Studio

Example

Using the WCF Client

Debugging Exceptions Thrown by a Client

See also

References