Mark Gabarra's Blog : .NET Configuration

Configuration Merge Behavior

Mark Gabarra — Tue, 27 Jun 2006 21:21:00 GMT

.NET Configuration Merge Default Behavior

General Behavior

In general, the .NET configuration system operates as a hierarchical view of an application’s configuration expressed in XML. The hierarchy of the view takes on two dimensions: an XML hierarchy (nodes have parents and children) to organize the data; and multiple configuration files (i.e. machine.config, app.config, and web.config) whose contents merge together to provide a final view of an application’s configuration. This document intends to describe the later of the two hierarchies and help the reader understand the expected semantics around the merging of these files.

Configuration Sections and Elements

Configuration sections and elements follow the same merging semantics, with one exception detailed below. For simplicity’s sake this document will describe the merging semantics for configuration elements since all rules that apply to elements also apply to sections. Since this exception only applies to configuration sections, this document will explicitly describe that behavior as applying to a section.

For configuration elements, the merging behavior follows an override semantic where the configuration file closest to the application “wins”. For non-WebHosted applications the configuration file load order starts with the machine.config file and then merges the appropriate app.config file to produce the final configuration view for the application. This simply means that elements in app.config will overwrite elements in machine.config. The appropriate app.config file defaults to an application’s executable file name postfixed with “.config”. For example, “MyApplication.exe” will have a default app.config file “MyApplication.exe.config”.

For WebHosted applications the answer becomes a bit more complex since web.config files may be nested themselves. In this case the load order starts with machine.config, then merges the root web.config for the machine, then adds the web.config at the application’s VROOT (if it exists), and then walks the directory tree from the VROOT down to the application’s current directory looking for any additional web.config files to merge. As this merge happens, any duplicate elements found along the way overwrite the previous settings, thus the configuration file closest to the application “wins”.

This describes the general, default behavior for configuration element merging. However, for completeness, two special mechanisms need discussion here: locking, and “allow definition”. The locking mechanism allows a configuration owner to lock an element(s) and/or property(ies). If a subsequent configuration file attempts to overwrite a locked element or property, the configuration system throws an exception. Configuration owners should use this mechanism to prevent downstream configuration files from modifying settings.

The “allow definition” mechanism only applies to configuration sections and allows configuration developers to limit the locations where a section may appear. WCF makes use of this mechanism to limit the appearance of certain configuration sections to machine.config only. Further details of these elements appear below under WCF Configuration Merge Behavior – Configuration Elements. If a configuration file contains a section outside of its “allow definition” scope the configuration system throws an exception, halting the merge at that point.

Configuration Collections

.NET configuration collections come in four different base types; BasicMap, AddRemoveClearMap, BasicMapAlternate, and AddRemoveClearMapAlternate. Each collection type follows its own merge semantic regarding non-duplicate elements detailed below. Collections handle duplicate elements specially. Each collection type defines a default behavior, again detailed below, but also allows for configuration developers to change that behavior simply by overriding the virtual property ThrowOnDuplicates. When ThrowOnDuplicates returns true, a collection will throw an exception if the merged configuration view attempts to add a duplicate element. When ThrowOnDuplicates returns false, the addition of a duplicate element into a collection will result in the second element overwriting the first element (i.e. last one in wins).

In the case that duplicate elements exist in the same configuration file, the configuration system reads these collections from top to bottom. This means that the element listed first will be added to the collection first, and the later element will encounter the same merge semantic as if it came from a later configuration file (i.e. if ThrowOnDuplicates returns true an exception will be thrown, else the later element overwrites the first).

BasicMap Collections

BasicMap type collections are additive only. That means that once an element is added to the collection, it cannot be removed by a later configuration file, nor can the collection be cleared. BasicMap collections return false for ThrowOnDuplicates as a default. This means that although a later configuration file cannot remove an element, it can overwrite an element.

AddRemoveClearMap Collections

AddRemoveClearMap type collections are collections that support add, remove, and clear functionality. This means that once added to a collection, later configuration files may remove an element from the collection with a <remove> tag. Also, a configuration file can insure that a collection starts empty by including a <clear> tag. Since they support explicit removal of elements, AddRemoveClearMap collections return true for ThrowOnDuplicates as a default.

Alternate Collections

The “Alternate” prefix for both collection types simply refers to a change in the collection ordering. Normally, the deserialization process postfixes new collection items; adding an element places it at the end of the list. For collections whose items span multiple configuration files (i.e. machine.config and app.config), this results in items contained in later configuration files always showing up at the end of the collection. For collections where ordering affects behavior (i.e. registering importers where the first importer that can handle a request halts further processing), this solution could result in app.config entries never affecting the product.

In alternate configuration maps, deserialization preserves collection ordering within a configuration file, but essentially reverses the ordering of the files. This means that app.config entries exist before machine.config entries. For example, given a configuration collection <behaviorExtensions> with machine.config entries:

</behaviorExtensions>

and app.config entries:

</behaviorExtensions>

If this collection were either a BasicMap or AddRemoveClearMap (i.e. not an Alternate collection), the resulting merged collection would look like:

</behaviorExtensions>

However, if this were an Alternate collection type the resulting merged collection would look like:

</behaviorExtensions>

Notice that in the Alternate collection the merged view preserves ordering within each file; however, reverses the ordering of those files.

WCF Configuration Merge Behavior

General Behavior

Except where noted specifically below, the WCF configuration merge behavior follows the .NET configuration merge behavior exactly.

Configuration Elements

WCF configuration only contains two sections that use the “allow definition” mechanism to limit their valid locations: system.serviceModel/commonBehaviors and system.serviceModel/machineSettings. In both cases, the sections limit their location to machine.config, preventing app.config and web.config owners from including their own values, or overwriting machine.config settings.

The common behaviors section includes two children collections of behaviors intended to apply to all services and endpoints on the local machine respectively.

The machine settings section includes machine specific settings for WCF. Currently, this only includes the machine wide switch enableLoggingKnownPii. This turns on the ability for app.config and web.config owners to turn on logging of PII in their own applications by flipping on the logKnownPii switch on their trace source.

Configuration Collections

WCF configuration collections can be broken into three distinct categories: collections that inherit from ConfigurationElementCollection, ServiceModelEnhancedConfigurationElementCollection, and custom collections. Collections that inherit from ConfigurationElementCollection follow the .NET configuration collection merge semantics and a detailed table follows the discussion of custom collections.

Collections that inherit from ServiceModelEnhancedConfigurationElementCollection follow the .NET configuration collection merge semantics with one difference. These collections keep track of whether or not a duplicate entry exists within the same configuration file. If the duplicate entries exist in the same configuration file, the collection throws an appropriate exception. If the duplicate entries exist in different configuration files, the collection follows the appropriate semantic based on the value of the ThrowOnDuplicates property. The following WCF configuration collections inherit from ServiceModelEnhancedConfigurationElementCollection:

XPath Location of Collection

system.serviceModel/behaviors/endpointBehaviors

system.serviceModel/behaviors/serviceBehaviors

system.serviceModel/bindings/XXX

system.serviceModel/client

system.serviceModel/client/metadata/policyImporters

system.serviceModel/client/metadata/wsdlImporters

system.serviceModel/comContracts

system.serviceModel/comContracts/exposedMethods

system.serviceModel/comContracts/persistableTypes

system.serviceModel/comContracts/userDefinedTypes

system.serviceModel/services

system.serviceModel/services/service

Custom collections are configuration elements that implement the ICollection interface directly. These collections have much more control over the merge semantics of their collection, but require significantly more code. The WCF configuration contains five such collections: the common endpoint behavior element, the common service behavior element, the endpoint behavior element, the service behavior element, and the custom binding element. All of these elements required the custom implementation because the collections do not have foreknowledge of the complete set of xml tag names valid for the contained elements. However, the merge semantics are simplified because of their location in the configuration xml tree.

The behavior element collections exists in either the appropriate child collection of the commonBehaviors section (which can only exist in machine.config, so there is no merging), or as an element in the appropriate behaviors collection (appropriate behaviors collection refers to either the service or endpoint behaviors). As an AddRemoveClearMap that does not throw on duplicates (see table below), the behaviors collections will override an entire behavior element when a duplicate exists. This prevents the behavior element collections from ever encountering a condition that requires any sort of merge.

Likewise, the custom binding element collection never encounters a merge condition because the customBinding collection also exists as an AddRemoveClearMap that does not throw on duplicates.

The following table describes the configuration objects that inherit from ConfigurationElementCollection within System.Runtime.Serialization.dll and System.ServiceModel.dll in terms of the collection type (BasicMap vs. AddRemoveClearMap) and value returned by ThrowOnDuplicates. For details on how these values affect a collection’s merge semantics see Configuration Collections above.

XPath Location of Collection	Collection Type	ThrowOn Duplicates
system.runtime.serialization/dataContractSerializer/declaredTypes	AddRemove ClearMap	True
system.runtime.serialization/dataContractSerializer/declaredTypes/add	BasicMap	False
system.runtime.serialization/dataContractSerializer/declaredTypes/add/add	BasicMap	False
system.runtime.serialization/dataContractSerializer/declaredTypes/add/add/add	BasicMap	False
system.serviceModel/extensions/behaviorExtensions	BasicMap	True
system.serviceModel/extensions/bindingElementExtensions	BasicMap	True
system.serviceModel/extensions/bindingExtensions	BasicMap	True
system.serviceModel/behaviors/endpointBehaviors	AddRemove ClearMap	False
system.serviceModel/behaviors/serviceBehaviors	AddRemove ClearMap	False
system.serviceModel/behaviors/endpointBehaviors/behavior/ clientCredentials/issuedToken/issuerChannelBehaviors	AddRemove ClearMap	True
system.serviceModel/behaviors/endpointBehaviors/behavior/ clientCredentials/serviceCertificate/scopedCertificates	AddRemove ClearMap	True
system.serviceModel/behaviors/serviceBehavior/behavior/ serviceAuthorization/authorizationPolicies	AddRemove ClearMap	True
system.serviceModel/behaviors/serviceBehavior/behavior/ serviceCredentials/issuedTokenAuthentication/knownCertificates	AddRemove ClearMap	True

XPath Location of Collection	Collection Type	ThrowOn Duplicates
system.serviceModel/bindings/XXX	AddRemove ClearMap	False
system.serviceModel/bindings/customBinding/binding/security/ issuedTokenParameters/additionalRequestParameters	BasicMap	False
system.serviceModel/bindings/customBinding/binding/security/ issuedTokenParameters/claimTypeRequirements	AddRemove ClearMap	True
system.serviceModel/bindings/customBinding/binding/security/ secureConversationBootstrap/issuedTokenParameters/ additionalRequestParameters	BasicMap	False
system.serviceModel/bindings/customBinding/binding/security/ secureConversationBootstrap/issuedTokenParameters/ claimTypeRequirements	AddRemove ClearMap	True
system.serviceModel/bindings/wsFederationHttpBinding/binding/ security/message/claimTypeRequirements	AddRemove ClearMap	True
system.serviceModel/bindings/wsFederationHttpBinding/binding/ security/message/tokenRequestParameters	BasicMap	False
system.serviceModel/client	AddRemove ClearMap	False
system.serviceModel/client/metadata/policyImporters	AddRemove ClearMap	False
system.serviceModel/client/metadata/wsdlImporters	AddRemove ClearMap	False
system.serviceModel/comContracts	AddRemove ClearMap	False
system.serviceModel/comContracts/exposedMethods	AddRemove ClearMap	False
system.serviceModel/comContracts/persistableTypes	AddRemove ClearMap	False
system.serviceModel/comContracts/userDefinedTypes	AddRemove ClearMap	False
system.serviceModel/diagnostics/messageLogging/filters	AddRemove ClearMap	True
system.serviceModel/serviceHostingEnvironment	AddRemove ClearMAp	True
system.serviceModel/services	AddRemove ClearMap	True
system.serviceModel/services/service	AddRemove ClearMap	False
system.serviceModel/services/service/host/baseAddresses	BasicMap	True
system.serviceModel.activation/netPipe/allowAccounts	AddRemove ClearMap	True
system.serviceModel.activation/netTcp/allowAccounts	AddRemove ClearMap	True

How do I know what collections support , , ?

Mark Gabarra — Sun, 25 Jun 2006 21:56:00 GMT

I recently received this question on the WCF Forums and promised a more in depth answer on my blog. For those of you that have read my forums response, a lot of this may seem familiar. In fact, I have copied much of this content from that response and filled it out here with some more details (essentially, the code snippets at the end).

First, understand that the behavior I describe below comes from System.Configuration and holds true for all .NET v2.0 configuration element collections.

The short answer to your question involves looking at the containing configuration element collection type. The <add>, <remove>, and <clear> element tags describe collection behaviors. In .NET v2.0 there are four predefined configuration element collection types: BasicMap, BasicMapAlternate, AddRemoveClearMap, and AddRemoveClearMapAlternate. For this discussion, consider BasicMap and BasicMapAlternate identical as well as AddRemoveClearMap and AddRemoveClearMap. (For those from the forums, I promised to describe the differences here, but have decided to dedicate a follow up post to configuration merging semantics.)

BasicMap collections do not support <remove> and <clear> tags, thus they can only include <add> tags. AddRemoveClearMap collections support all three tags. This begs the question, "How do I tell the difference?" Unforunately, you cannot from the configuration XML; however, you can from the configuration object model in code.

There are two different ways of getting a configuration element collection's collection type: The ConfigurationElementCollection.CollectionType property and the ConfigurationCollectionAttribute.CollectionType property. The first requires you have an instance of the specific ConfigurationElementCollection you wish to explore, while the second requires that you get the custom attributes off of the Type associated with the ConfigurationElementCollection. The second also requires that the developer that created the ConfigurationElementCollection you wish to inspect properly decorated their collection with the ConfigurationCollectionAttribute and kept the two in sync.

To add a bit more confusion into the mix, a configuration element collection can change the XML element names for any or all of the <add>, <remove>, and <clear> tags. You can see this in the WCF configuration when you look at bindings. In the following configuration snippet, the <binding> element really describes an <add> element where configuration element collection has changed the <add> element name to <binding>:

Like the collection type, there are two different ways of getting a configuration element collection's XML element names. However, unlike the collection type, one is much (MUCH) easier. The ConfigurationElementCollection object contains three properties: AddElementName, RemoveElementName, and ClearElementName. However, all three of these properties are "protected internal", which means that using these properties requires utilizing Reflection. On the other hand, the ConfigurationCollectionAttribute has three public properties: AddItemName, RemoveItemName, and ClearItemsName. Again, the ConfigurationCollectionAttribute method requires that the developer that created the ConfigurationElementCollection you wish to inspect properly decorated their collection with the ConfigurationCollectionAttribute and properly set these values.

The code for these methods of inspection follow. First, let me include a single helper method that simply gets all types from an assembly (in this case System.ServiceModel.dll) that inherit from ConfigurationElementCollection:

static List<Type> GetServiceModelConfigurationCollectionTypes()

{

List<Type> collectionTypes = new List<Type>();

// Use the known public type System.ServiceModel.ServiceHost as an

// anchor type from which to get a reference to the assembly.

Assembly serviceModelDll = typeof(System.ServiceModel.ServiceHost).Assembly;

foreach (Type type in serviceModelDll.GetTypes())

{

// Return all types that inherit from ConfiguraitonElementCollection.

// Each method of inspection will filter out this list further

// based on the limitations of that method.

if (type.IsSubclassOf(typeof(ConfigurationElementCollection)))

{

collectionTypes.Add(type);

}

return collectionTypes;

}

First, let me share the method of using the ConfigurationCollectionAttribute, the preferred method because of the simplicity of accessing this information. However, this requires the collection developer to properly decorate their collections (something I have done with the System.ServiceModel.Configuration namespace).

static void DisplayCollectionPropertiesUsingAttributes()

{

List<Type> collectionTypes = Program.GetServiceModelConfigurationCollectionTypes();

foreach (Type collectionType in collectionTypes)

{

// As long as a collection contains a ConfigurationCollectionAttribute,

// this method will allow the appropriate inspection.

object[] customAttributes = collectionType.GetCustomAttributes(typeof(ConfigurationCollectionAttribute), true);

if (0 < customAttributes.Length)

{

// Once acquiring the ConfigurationCollectionAttribute from the type,

// inspection is as easy as calling properties on the attribute.

ConfigurationCollectionAttribute collectionAttribute = (ConfigurationCollectionAttribute)customAttributes[0];

Console.WriteLine("**************************************************");

Console.WriteLine("{0}", collectionType.FullName);

Console.WriteLine(" Collection Type: {0}", collectionAttribute.CollectionType);

Console.WriteLine(" Add Element: {0}", collectionAttribute.AddItemName);

Console.WriteLine(" Remove Element: {0}", collectionAttribute.RemoveItemName);

Console.WriteLine(" Clear Element: {0}", collectionAttribute.ClearItemsName);

Console.WriteLine(" Collection Item Type: {0}", collectionAttribute.ItemType.FullName);

Console.WriteLine("**************************************************");

}

Next, let me share the brute force reflection method. Notice that this method requires instantiating the collection object, thus missing collections that have generic parameters (for example, all of the binding related collections in the System.ServiceModel.Configuration namespace).

static void DisplayCollectionPropertiesUsingReflection()

{

List<Type> collectionTypes = Program.GetServiceModelConfigurationCollectionTypes();

foreach (Type collectionType in collectionTypes)

{

// Since this method requires instantiating the collection, it cannot operate

// on collections that are either abstract or contain generic parameters.

if (!collectionType.IsAbstract &&

!collectionType.ContainsGenericParameters)

{

// This method requires first instantiating an instance of the collection and

// getting PropertyInfo and MethodInfo references to call the non-public properties

// and methods.

ConfigurationElementCollection collectionInstance = (ConfigurationElementCollection)Activator.CreateInstance(collectionType);

PropertyInfo _addItemName = collectionType.GetProperty("AddElementName", BindingFlags.Instance | BindingFlags.NonPublic);

PropertyInfo _clearItemsName = collectionType.GetProperty("ClearElementName", BindingFlags.Instance | BindingFlags.NonPublic);

PropertyInfo _removeItemName = collectionType.GetProperty("RemoveElementName", BindingFlags.Instance | BindingFlags.NonPublic);

MethodInfo _createNewElement = collectionType.GetMethod("CreateNewElement",

BindingFlags.Instance | BindingFlags.NonPublic,

null,

new Type[0],

null);

// Next, this method retrieves the desired information through those PropertyInfo

// and MethodInfo references.

string addItemName = (string)_addItemName.GetValue(collectionInstance, null);

string clearItemsName = (string)_clearItemsName.GetValue(collectionInstance, null);

string removeItemName = (string)_removeItemName.GetValue(collectionInstance, null);

ConfigurationElement elementInstance = (ConfigurationElement)_createNewElement.Invoke(collectionInstance, null);

Console.WriteLine("**************************************************");

Console.WriteLine("{0}", collectionType.FullName);

Console.WriteLine(" Collection Type: {0}", collectionInstance.CollectionType);

Console.WriteLine(" Add Element: {0}", addItemName);

Console.WriteLine(" Remove Element: {0}", removeItemName);

Console.WriteLine(" Clear Element: {0}", clearItemsName);

Console.WriteLine(" Collection Item Type: {0}", elementInstance.GetType().FullName);

Console.WriteLine("**************************************************");

}

I hope you find this at least somewhat helpful. I plan on following this post up next week with a post detailing the merge semantics of the WCF configuration collections. I hope that these two posts together help to give a more transparent picture of configuration collections in general, and specifically the WCF configuration collections.

Mark Gabarra

This posting is provided "AS IS" with no warranties, and confers no rights. Use of included script samples are subject to the terms specified at http://www.microsoft.com/info/cpyright.htm