Configuring Bindings for Windows Communication Foundation Services

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. If no endpoints are specified, the runtime adds default endpoints. For more information aboutdefault endpoints, bindings, and behaviors, see Simplified Configuration and Simplified Configuration for WCF Services.

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.

Specifying 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">
  <!—- This section is optional with the default configuration introduced
       in .NET Framework 4. -->
  <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. 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. This altered binding can now be used when creating any endpoint by setting the binding attribute in the endpoint element.

Note

If you give a particular name to the binding, the bindingConfiguration specified in the service endpoint must match with it.

<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 
        receiveTimeout="00:00:01"
    />
</bindings>

Configuring a Behavior to Apply to a Service

In the following example, a specific behavior is configured for the service type. The ServiceMetadataBehavior 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.

Note

If you give a particular name to the behavior, the behaviorConfiguration specified in the service or endpoint section must match it.

<behaviors>
    <behavior>
        <ServiceMetadata httpGetEnabled="true" /> 
    </behavior>
</behaviors>
<services>
    <service 
       name="HelloWorld, IndigoConfig, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null"
       <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 and get the metadata of the "HelloWorld" typed service.

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

Specifying a Service with Two Endpoints Using Different Binding Values

In this last example, two endpoints are configured for the HelloWorld 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>

You can get the same behavior using the default configuration by adding a protocolMapping section and configuring the bindings as demonstrated in the following example.

<protocolMapping>
    <add scheme=”http” binding=”basicHttpBinding” bindingConfiguration=”shortTimeout” />
    <add scheme=”https” binding=”basicHttpBinding” bindingConfiguration=”Secure” />
</protocolMapping>
<bindings>
    <basicHttpBinding 
        name="shortTimeout"
        timeout="00:00:00:01" 
     />
     <basicHttpBinding 
        name="Secure" />
        <Security mode="Transport" />
</bindings>

See Also

Concepts

Simplified Configuration
System-Provided Bindings
Endpoint Creation Overview
Using Bindings to Configure Services and Clients