Configuring Services Using Configuration Files

Article
08/07/2009

Configuring a Windows Communication Foundation (WCF) service with a configuration file gives you the flexibility of providing endpoint and service behavior data at the point of deployment instead of at design time. This topic outlines the primary techniques available.

A WCF service is configurable using the .NET Framework configuration technology. Most commonly, XML elements are added to the Web.config file for an Internet Information Services (IIS) site that hosts a WCF service. The elements allow you to change details such as the endpoint addresses (the actual addresses used to communicate with the service) on a machine-by-machine basis. In addition, WCF includes several system-provided elements that allow you to quickly select the most basic features for a service. In practice, writing configuration is a major part of programming WCF applications.

For more information, see Configuring Bindings for Windows Communication Foundation Services. For a list of the most commonly used elements, see System-Provided Bindings.

System.Configuration: Web.config and App.config

WCF uses the System.Configuration configuration system of the .NET Framework.

When configuring a service in Visual Studio, use either a Web.config file or an App.config file to specify the settings. The choice of the configuration file name is determined by the hosting environment you choose for the service. If you are using IIS to host your service, use a Web.config file. If you are using any other hosting environment, use an App.config file.

In Visual Studio, the file named App.config is used to create the final configuration file. The final name actually used for the configuration depends on the assembly name. For example, an assembly named "Cohowinery.exe" has a final configuration file name of "Cohowinery.exe.config". However, you only need to modify the App.config file. Changes made to that file are automatically made to the final application configuration file at compile time.

In using an App.config, file the configuration system merges the App.config file with content of the Machine.config file when the application starts and the configuration is applied. This mechanism allows machine-wide settings to be defined in the Machine.config file. The App.config file can be used to override the settings of the Machine.config file; you can also lock in the settings in Machine.config file so that they get used. In the Web.config case, the configuration system merges the Web.config files in all directories leading up to the application directory into the configuration that gets applied. For more information about configuration and the setting priorities, see topics in the System.Configuration namespace.

Major Sections of the Configuration File

The main sections in the configuration file include the following elements.

<system.ServiceModel>

   <services>
      <service>
         <endpoint/>
      </service>
   </services>

   <bindings>
   <!-- Specify one or more of the system-provided binding elements,
    for example, <basicHttpBinding> --> 
   <!-- Alternatively, <customBinding> elements. -->
      <binding>
      <!-- For example, a <BasicHttpBinding> element. -->
      </binding>
   </bindings>

   <behaviors>
   <!-- One or more of the system-provided or custom behavior elements. -->
      <behavior>
      <!-- For example, a <throttling> element. -->
      </behavior>
   </behaviors>

</system.ServiceModel>

Note:
The bindings and behaviors sections are optional and are only included if required.

The <services> Element

The services element contains the specifications for all services the application hosts.

<services> element reference

The <service> Element

Each service has these attributes:

name. Specifies the type that provides an implementation of a service contract. This is a fully qualified name which consists of the namespace, a period, and then the type name. For example "MyNameSpace.myServiceType".
behaviorConfiguration. Specifies the name of one of the behavior elements found in the behaviors element. The specified behavior governs actions such as whether the service allows impersonation.
<service> element reference

The <endpoint> Element

Each endpoint requires an address, a binding, and a contract, which are represented by the following attributes:

address. Specifies the service's Uniform Resource Identifier (URI), which can be an absolute address or one that is given relative to the base address of the service. If set to an empty string, it indicates that the endpoint is available at the base address that is specified when creating the ServiceHost for the service.
binding. Typically specifies a system-provided binding like WsHttpBinding, but can also specify a user-defined binding. The binding specified determines the type of transport, security and encoding used, and whether reliable sessions, transactions, or streaming is supported or enabled.
bindingConfiguration. If the default values of a binding must be modified, this can be done by configuring the appropriate binding element in the bindings element. This attribute should be given the same value as the name attribute of the binding element that is used to change the defaults.
contract. Specifies the interface that defines the contract. This is the interface implemented in the common language runtime (CLR) type specified by the name attribute of the service element.
<endpoint> element reference

The <bindings> Element

The bindings element contains the specifications for all bindings that can be used by any endpoint defined in any service.

<bindings> element reference

The <binding> Element

The binding elements contained in the bindings element can be either one of the system-provided bindings (see System-Provided Bindings) or a custom binding (see Custom Bindings). The binding element has a name attribute that correlates the binding with the endpoint specified in the bindingConfiguration attribute of the endpoint element.

For more information about configuring services and clients, see Configuring Windows Communication Foundation Applications.

<binding> element reference

The <behaviors> Element

This is a container element for the behavior elements that define the behaviors for a service.

<behaviors> element reference

The <behavior> Element

Each behavior element is identified by a name attribute and provides either a system-provided behavior, such as <throttling>, or a custom behavior.

<behavior> element reference

How to Use Binding and Behavior Configurations

WCF makes it easy to share configurations between endpoints using a reference system in configuration. Rather than directly assigning configuration values to an endpoint, binding-related configuration values are grouped in bindingConfiguration elements in the <binding> section. A binding configuration is a named group of settings on a binding. Endpoints can then reference the bindingConfiguration by name.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
 <system.serviceModel>
  <bindings>
    <basicHttpBinding>
     <binding name="myBindingConfiguration1" closeTimeout="00:01:00" />
     <binding name="myBindingConfiguration2" closeTimeout="00:02:00" />
    </basicHttpBinding>
     </bindings>
     <services>
      <service name="MyNamespace.myServiceType">
       <endpoint 
          address="myAddress" binding="basicHttpBinding" 
          bindingConfiguration="myBindingConfiguration1" />
       </service>
      </services>
    </system.serviceModel>
</configuration>

The name of the bindingConfiguration is set in the <binding> element. The name must be a unique string within the scope of the binding type—in this case the <basicHttpBinding>. The endpoint links to the configuration by setting the bindingConfiguration attribute to this string.

A behaviorConfiguration is implemented the same way, as illustrated in the following sample.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.serviceModel>
    <behaviors>
      <endpointBehaviors>
        <behavior name="myBehavior">
           <callbackDebug includeExceptionDetailInFaults="true" />
         </behavior>
       </endpointBehaviors>
    </behaviors>
    <services>
     <service name="NewServiceType">
       <endpoint 
          address="myAddress" behaviorConfiguration="myBehavior"
          binding="basicHttpBinding" />
      </service>
    </services>
   </system.serviceModel>
</configuration>

This system allows endpoints to share common configurations without redefining the settings. If machine-wide scope is required, create the binding or behavior configuration in Machine.config. The configuration settings are available in all App.config files. The Configuration Editor Tool (SvcConfigEditor.exe) makes it easy to create configurations.

Share via