Configuring Bindings for Windows Communication Foundation Services

Article
08/31/2009

When creating an application, you often want to defer decisions to the administrator after the deployment of the application. For example, there is often no way of knowing in advance what a service address, or Uniform Resource Identifier (URI), will be. Instead of hard-coding an address, it is preferable to allow an administrator to do so after creating a service. This flexibility is accomplished through configuration.

Note

Use the ServiceModel Metadata Utility Tool (Svcutil.exe) with the /config switch to quickly create configuration files.

Major Sections

The Windows Communication Foundation (WCF) configuration scheme includes the following three major sections (serviceModel, bindings, and services):

<configuration>
    <system.serviceModel>
        <bindings>
        </bindings>
        <services>
        </services>
        <behaviors>
        </behaviors>
    </system.serviceModel>
</configuration>

ServiceModel Elements

You can use the section bounded by the system.ServiceModel element to configure a service type with one or more endpoints, as well as settings for a service. Each endpoint can then be configured with an address, a contract, and a binding. For more information about endpoints, see Endpoint Creation Overview.

A binding specifies transports (HTTP, TCP, pipes, Message Queuing) and protocols (Security, Reliability, Transaction flows) and consists of binding elements, each of which specifies an aspect of how an endpoint communicates with the world.

For example, specifying the basicHttpBinding element indicates to use HTTP as the transport for an endpoint. This is used to wire up the endpoint at run time when the service using this endpoint is opened.

There are two kinds of bindings: predefined and custom. Predefined bindings contain useful combinations of elements that are used in common scenarios. For a list of predefined binding types that WCF provides, see System-Provided Bindings. If no predefined binding collection has the correct combination of features that a service application needs, you can construct custom bindings to meet the application's requirements. For more information about custom bindings, see <customBinding>.

The following four examples illustrate the most common binding configurations used for setting up a WCF service.

Specify an Endpoint to Use a Binding Type

The first example illustrates how to specify an endpoint configured with an address, a contract, and a binding.

<service name="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null">
  <endpoint 
      address="/HelloWorld2/"
      contract="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null"
      binding="basicHttpBinding" />
  </endpoint>
</service>

In this example, the name attribute indicates which service type the configuration is for. When you create a service in your code with the HelloWorld contract, it is initialized with all of the endpoints defined in the example configuration. If the assembly implements only one service contract, the name attribute can be omitted because the service uses the only available type. The attribute takes a string, which must be in the format Namespace.Class, AssemblyName, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null

The address attribute specifies the URI that other endpoints use to communicate to the service. The URI can be either an absolute or relative path. If a relative address is provided, the host is expected to provide a base address that is appropriate for the transport scheme used in the binding. If an address is not configured, the base address is assumed to be the address for that endpoint.

The contract attribute specifies the contract this endpoint is exposing. The service implementation type must implement the contract type. If a service implementation implements a single contract type, then this property can be omitted.

The binding attribute selects a predefined or custom binding to use for this specific endpoint. An endpoint that does not explicitly select a binding uses the default binding selection, which is BasicHttpBinding.

Modifying a Predefined Binding

In the following example, a predefined binding is modified and named. It can then be used to configure any endpoint in the service. The binding is modified by setting the ReceiveTimeout value to 1 second. Note that the property returns a TimeSpan object.

That altered binding is found in the bindings section, and the altered binding is given a unique name, shortTimeout, set by the name attribute. This altered binding can now be used when creating any endpoint by setting the binding attribute in the endpoint element to the unique name. This allows you to have a nearly unlimited number of variations of the standard binding.

Note

If you do not create any variations of a standard binding, you do not have to set the bindingConfiguration attribute to any value. In that case, the unmodified predefined binding is used.

<service name="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null">
  <endpoint 
      address="/HelloWorld2/"
      contract="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null"
      binding="basicHttpBinding" />
  </endpoint>
</service>
<bindings>
    <basicHttpBinding 
        name="shortTimeout"
        receiveTimeout="00:00:01"
    />
</bindings>

Configure a Behavior to Apply to a Service

In the following example, a specific behavior is configured for the service type. The metadataPublishing element is used to enable the ServiceModel Metadata Utility Tool (Svcutil.exe) to query the service and generate Web Services Description Language (WSDL) documents from the metadata.

<behaviors>
    <behavior name="MetaPlusExceptions" >
        <metadataPublishing enableGetWsdl="true" /> 
    </behavior>
</behaviors>
<services>
    <service 
       name="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null"
       serviceBehaviorName="MetaPlusExceptions">
       <endpoint 
          address="http://computer:8080/Hello"
          contract="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null"
          binding="basicHttpBinding" />
       </endpoint>
    </service>
</services>

The preceding configuration enables a client to call

svcutil /config:Client.exe.config http://computer:8080/Hello?wsdl

and get the metadata of the "HelloWorld" typed service.

Specify a Service with Two Endpoints Using Different Binding Values

In this last example, two endpoints are configured for the Hello service type. Each endpoint uses a different customized bindingConfiguration attribute of the same binding type (each modifies the basicHttpBinding).

<service name="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null">
    <endpoint
        address="http://computer:8080/Hello1"
        contract="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null"
        binding="basicHttpBinding"
        bindingConfiguration="shortTimeout"
    </endpoint>
    <endpoint
        address="http://computer:8080/Hello2"
        contract="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null"
        binding="basicHttpBinding"
        bindingConfiguration="Secure"
     </endpoint>
</service>
<bindings>
    <basicHttpBinding 
        name="shortTimeout"
        timeout="00:00:00:01" 
     />
     <basicHttpBinding 
        name="Secure" />
        <Security mode="Transport" />
</bindings>