Merge Rules for Inherited Configuration

When you specify a parent source from which you inherit shared configuration information, all of that configuration information is read and the settings are merged at run-time at the level of individual setting elements. For example, you can add exception handlers to an existing policy, or add a property to an element in the local configuration that does not exist in the default settings. The run time merge basically behaves like a logical OR. If the element or property is in one of the configuration files, it will be present in the merged configuration.

If an element or property is present in both sources when you inherit a section, the element in the local configuration (the local source) is the one present in the resulting merged configuration. Inheritance can only be one level deep; you cannot define a parent source for a configuration source that is itself used as a parent source. This prevents the accidental creation of circular references and endless recursion.

Note

When you use environmental overrides to specify different configurations for different deployment environments in conjunction with settings inherited from a parent source, the merge rules described here do not apply to the inherited configuration settings. The merged configuration is specified by the combination of the common and the delta (differences) configuration files that you merge.

When you use redirected sections, and an element or property is present in both sources, the element from the shared configuration (the source you redirect the section to) is the one present in the resulting merged configuration. Local settings in a redirected section are ignored. If you specify a parent source as well as redirected sections, the merge behavior applies to the redirected sections.

To avoid issues when you use different tools to manage your configuration, you should avoid inheriting the standard .NET configuration sections that are also used by Enterprise Library, such as appSettings and connectionStrings.

When creating a composite configuration, there is a hierarchy to the components merged into your Enterprise Library configuration at run time, as described in Additive Merge below. In addition, there is a hierarchy for merging of the collections from the specified sources, described in the section Merged Collections Order later in this topic.

Additive Merge

The additive merge behaves like a logical OR. If the element or property is in one of the configuration files being read, it will be present in the run-time Enterprise Library application configuration. An additive merge has the following behavior where App.config is your primary/default application configuration and Shared.config is the shared source from which to read additional configuration information.

App.config contains element X	Shared.config contains element X	Result contains element X
Yes	No	Yes
No	Yes	Yes
Yes with property Y	Yes (without property Y)	Yes with property Y
Yes (without property Y)	Yes with property Y	Yes with property Y
Yes with property Y	Yes with property Z	Yes with property Y

Notice that the local configuration overrides the shared and inherited configuration where as element with the same name has different sets of properties or property values. The following will help you to understand how the name that is used by the merge process is determined for elements:

• The identity of an element inside a NamedElementCollection is based on its element name and the names of all ancestor elements in the configuration hierarchy such that:

  <logFilters>
    <add name="Category" categoryFilterMode="AllowAllExceptDenied">
  

  is the same element as:

  <logFilters>
    <add name="Category" categoryFilterMode="DenyAllExceptAllowed">
  

• Incompatibility of Type attributes inside a NameTypeConfigurationElementCollection throws an exception when merging, as in the following example when this:

  <listeners>
    <add name="Event Log Destination" type="EventLogListener" ... />
  

  is merged with:

  <listeners>
    <add name="Event Log Destination" type="DatabaseTraceListener" ... />
  

• If the identity of elements inside a collection does not derive from namedElementCollection, you can establish their identity based on the ConfigurationProperty property IsKey.

Merged Collections Order

When multiple configuration files are read and their contents merged at run time, collections have a merge hierarchy. The shared configuration file collection elements appear first in the merged configuration, followed by the local configuration file collection elements. Elements within the collection with different names are merged. Elements with the same name are replaced.