Mark Gabarra's Blog : WCF Configuration

WCF July CTP Missing Config Intellisense

Mark Gabarra — Wed, 02 Aug 2006 02:21:00 GMT

Recently, I received a question about the WCF configuration intellisense in our July CTP release from Nilesh Pagare. After installing the July WCF CTP Nilesh no longer had our configuration intellisense when modifying either app.config or web.config files in Visual Studio. The dotnetconfig.xsd file did not include the System.ServiceModel configuration schema.

After tracking down the correct contact regarding the installation of WCF configuration intellisense, it appears that you have run into an unfortunate known issue. Here are the details that have been provided to me, which include a work around:

VS extension should be installed for Intellisense to work correctly.

However, we did not ship such an extension package with July CTP. This is the major problem.

To workaround, one can install the VS extension for Jun CTP on the July CTP with the following command line (direct install will fail):

msiexec /i vsextwfx.msi WRC_INSTALLED_OVERRIDE=1

The VS extension package for June CTP can be found at:

http://www.microsoft.com/downloads/details.aspx?FamilyID=1a994549-94cb-4f61-903d-a8c8e453eef4&DisplayLang=en

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

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

So What Is A WCF Configuration Extension Anyways?

Mark Gabarra — Fri, 26 May 2006 23:44:00 GMT

I apologize in advance for the rushed tempo of this discussion. Unfortunately, I still struggle with finding (or in some cases creating) time dedicated for writing blog posts; however, I wanted to make sure and get the bulk of this content posted this week. I briefly struggled with the trade off of posting less polished content quickly with more polished content at less regular intervals. Feel free to let me know if you would rather me wait until the content reaches a more coherent quality level.

My previous posts focused on how to enumerate the three Windows Communication Foundation (WCF) configuration extension points: bindings, behaviors, and binding elements. Normally, I would like to actually introduce a topic in a general sense before diving into specific coding examples; however, those specific coding questions provoked the very existence of this blog. Thus the slightly backward approach at this topic. So now that I have described in detail how, and in some cases why, you enumerate the various configuration extensions in WCF configuration, allow me to describe what are WCF configuration extension points, why we have them, and why we chose these three.

What are these things?

Simply put, the WCF configuration extension points allow developers external to the WCF product team extend specific points of the WCF configuration schema and object model. The <extensions> section in the WCF configuration schema exists to allow developers to create their own configurable objects that plug into the WCF configuration schema as if they existed as part of the WCF product. Allow me to give a specific example.

The WCF product will ship with a set of configurable transport elements that can be consumed by a custom binding. To configure a custom binding that uses the tcp transport, you would include the following block in your application’s configuration file:

<system.serviceModel>

</binding>

</customBinding>

</bindings>

</system.serviceModel>

</configuration>

Instead of trying to create every possible transport at the time WCF goes out the door, we decided to create a mechanism to allow developers to create their own custom transports. Further, through this extension mechanism, we allow developers to expose their transports through the WCF configuration system. Ideally, we would allow a developer to create “customTransport” and attach it to a custom binding with the following configuration:

<system.serviceModel>

</binding>

</customBinding>

</bindings>

</system.serviceModel>

</configuration>

Why have them?

After all, the WCF configuration system extends the .NET 2.0 System.Configuration system. Why create an additional extension mechanism for the WCF configuration portion? Simply put, the System.Configuration extension points did not cover this particular scenario. System.Configuration allows developers to plug in custom ConfigurationSectionGroup and ConfigurationSection objects. ConfigurationSectionGroups can only contain ConfigurationSection objects and cannot include any attributes or configuration data. In other words, section groups exist to define hierarchy and scope only. ConfigurationSections, on the other hand, can contain attributes as well as child nodes of type ConfigurationElement and/or ConfigurationElementCollection. They cannot, however, contain other ConfigurationSections. The WCF configuration system required the ability to plug in custom ConfigurationElement objects.

Because we cannot simply take a element name (“customTransport” in the previous case) and “auto magically” determine how to deserialize the associated XML, we created a registration point that allows developers to register a ConfigurationElement object that knows how to deserialize the given XML with an element name. This results in the actual configuration looking like:

<system.serviceModel>

</bindingElementExtensions>

</extensions>

</binding>

</customBinding>

</bindings>

</system.serviceModel>

</configuration>

The <extensions> section provides a centralized location for this registration of XML element name to ConfigurationElement object required for creating a relatively open extensibility point to the WCF configuration system. Each configuration extensibility point connects to one of three collections within this section: behaviorExtensions, bindingElementExtensions, and bindingExtensions.

Why these three and only these three?

Those of you who dive deeply into the WCF configuration system may complain that the WCF configuration system contains more extensibility points than just these three. Yes, a few more extensibility points exists; however, for the scope of this discussion allow me to limit “configuration extensibility points” to mean the extensibility points contained in the <extensions> section of the WCF configuration schema, of which only three exist: behavior extensions, binding element extensions, and binding extensions. Looking at the WCF object model, and ignoring the configuration surface for the moment, five basic extensibility points jump out, at least to me: ServiceHost, IEndpointBehavior, IServiceBehavior, BindingElement, and Binding. These objects make up the basic building blocks of WCF services and communication channels. When looking to include this extensibility in the WCF configuration system, the last four objects all have very custom configuration surfaces for each distinct implementation. The ServiceHost configuration surface exposes itself in a very generic manner, and thus does not need its own configuration extension. The IEndpointBehavior and IServiceBehavior interfaces allow for a single object to fit both categories, thus requiring a single configuration object to service both extensions. This leads us to requiring three configuration extension points.

I hope this helps plug in some of the background information holes regarding the WCF configuration extensions that my previous “How To” posts may have left open.

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

Enumerating Binding Element Extensions

Mark Gabarra — Tue, 09 May 2006 04:03:00 GMT

As a follow up to my previous posts “Is there an easy way to enumerate the bindings listed in configuration?” and “Enumerating Behavior Extensions”, this week I discuss how to enumerate the last WCF configuration extension points: binding elements.

Before I go further into this discussion, I need to define a few terms.

· Binding element – An element that defines a specific entry in the binding stack. Binding elements examples include encodings, transports, security, etc.

· Runtime binding element – The binding element object used by the WCF runtime as part of the binding stack. When binding element appears without “runtime” specified this references the configuration object responsible for exposing the runtime binding element to the WCF configuration system.

· Custom binding – A binding constructed in configuration by explicitly adding the specific binding elements desired and configuring those elements directly.

· Configured custom binding – An entry in the custom binding configuration collection (i.e. <customBinding>) that correlates to a named set of binding element extensions and their configuration.

· “Available to my app” – Exists in the configuration merged view created when opening the application.config file associated with “my app”.

Now, without further ado, the discussion begins.

Similar to enumerating behaviors listed in configuration, when I get asked about binding elements people really do want to enumerate these extensions. The only point of clarification lies around whether they want all extension elements available to an application, or just those used in a specific configuration. For the purpose of this posting, I will explore the following four scenarios:

1. Enumerate all of the binding element extensions available to my app

2. Enumerate all of the binding elements in a configured custom binding

Enumerate all of the binding element extensions available to my app

The specific scenario I hear most for this question involves creating a dynamically configurable service / client making use of custom bindings. Essentially, the enumeration will fill some type of editor control for setting the binding elements on a custom binding used by an endpoint (think wizard type application here). The solution I describe for this scenario actually accomplishes two things. First, it discovers all of the binding element configuration element names available to an application. Second, it examines each of the binding elements found and discovers the underlying runtime binding element associated with that configuration element.

The solution becomes straight forward when you, once again, understand that all of the WCF configuration extensions (including those built into the WCF product) are registered in one of three collections under the Extensions configuration section in the System.ServiceModel configuration section group. For this post I will focus on the BindingElementExtensions collection. These extension collections contain a number of add elements that include a name and type property. The name property corresponds to the xml element name that references this binding. The type property corresponds to the type that knows how to deserialized the configuration XML for this binding.

<system.serviceModel>

</bindingElementExtensions>

</extensions>

</system.serviceModel>

</configuration>

The first part of this solution simply involves enumerating the entries in the BindingElementExtensions collection and capturing each entries' name.

The second part of this solution involves enumerating the entries in the extension collection and capturing each entries’ type. Since this type will implement the BindingElementExtensionElement base class, the solution can create an instance of the binding element extension type and cast it to BindingElementExtensionElement. To facilitate enumerations like this, BindingElementExtensionElement contains a helper property (get only), BindingElementType, which returns the type of the underlying runtime binding element configured by this extension, which satisfies the second part of this solution.

Here is a quick bit of code that accomplishes this task and displays the information to the console:

static void EnumerateAllAvailableBindingElementExtensions()

{

ExtensionsSection serviceModelExtensions = (ExtensionsSection)ConfigurationManager.GetSection("system.serviceModel/extensions");

if (97 > Console.WindowWidth)

{

Console.WindowWidth = 97;

}

Console.WriteLine("{0,-22} : {1}",

"Xml Element Name",

"Underlying Binding Element Type");

foreach (ExtensionElement bindingElementExtension in serviceModelExtensions.BindingElementExtensions)

{

BindingElementExtensionElement bindingElement = (BindingElementExtensionElement)Activator.CreateInstance(Type.GetType(bindingElementExtension.Type));

Console.WriteLine("{0,-22} : {1}",

bindingElementExtension.Name,

bindingElement.BindingElementType.FullName);

}

Enumerate all of the binding elements in a configured custom binding

<system.serviceModel>

</binding>

</customBinding>

</bindings>

</system.serviceModel>

</configuration>

This solution also starts with enumerating through each of the configured custom bindings. A CustomBindingElement can be seen as a collection of BindingElementExtensionElements, thus I enumerate through each extension included in a given custom binding. To help identify WCF configuration extension objects where consumed, the abstract base class for all WCF extension elements (ServiceModelExtensionElement) contains the helper property (get only) ConfigurationElementName. This returns the XML element name corresponding to a particular extensions element, and tracks back to that extension’s name attribute in the ‘extensions’ section registration. When enumerating configured binding elements for this scenario, my solution makes use of this property to list each binding element extension’s element name as well as the underlying runtime binding element type.

Here is a quick bit of code that accomplishes this task and displays the information to the console:

static void EnumerateConfiguredCustomBindings()

{

BindingsSection bindings = (BindingsSection)ConfigurationManager.GetSection("system.serviceModel/bindings");

if (97 > Console.WindowWidth)

{

Console.WindowWidth = 97;

}

foreach (CustomBindingElement customBinding in bindings.CustomBinding.Bindings)

{

Console.WriteLine("Binding '{0}':", customBinding.Name);

foreach (BindingElementExtensionElement bindingElement in customBinding)

{

Console.WriteLine("{0,-22} : {1}",

bindingElement.ConfigurationElementName,

bindingElement.BindingElementType.FullName);

}

I hope this sheds some light on the various methods of enumerating binding elements available to an application using the WCF configuration system.

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

Enumerating Behavior Extensions

Mark Gabarra — Wed, 03 May 2006 18:00:00 GMT

As a follow up to my previous post “Is there an easy way to enumerate the bindings listed in configuration?”, today I will discuss how to enumerate one more of the WCF configuration extension points: behaviors.

Before I go further into this discussion, I need to define a few terms.

· Behavior – An element that defines how an endpoint or service acts (as opposed to communicates). A behavior configures service timeouts, for example.

· Runtime behavior – The behavior object used by the WCF runtime as part of the service and/or endpoint. When behavior appears without “runtime” specified this references the configuration object responsible for exposing the runtime behavior to the WCF configuration system.

· Configured behavior – An entry in the behaviors configuration collection that correlates to a named set of behaviors and their configuration.

· “Available to my app” – Exists in the configuration merged view created when opening the application.config file associated with “my app”.

Now, without further ado, the discussion begins.

Unlike enumerating bindings listed in configuration, when I get asked about behaviors people really do want to enumerate these extensions. The only point of clarification lies around whether they want all extension elements available to an application, or just those used in a specific configuration. For the purpose of this posting, I will explore the following two scenarios:

1. Enumerate all of the behavior extensions available to my app

2. Enumerate all of the behaviors included in a configured behavior

Enumerate all of the behavior extensions available to my app

The scenario I hear most when I get this question involves creating a GUI application for dynamically defining services and/or endpoints that uses the configuration system to persist those definitions. You can think of the WCF configuration editor as an example of such an application, or a custom application scoped specifically to creating services and/or endpoints instead of managing the entire WCF configuration model. The solution I describe for this scenario actually accomplishes two things. First, it discovers all of the behavior configuration element names available to an application. Second, it examines each of the behaviors found and discovers the underlying runtime behavior associated with that configuration element.

Just like binding extensions, you find the behavior extensions registered under one of the three collections contained in the ‘extensions’ section of the ‘system.serviceModel’ section group. Specifically, the ‘behaviorExtensions’ collection contains all of the registered behavior extensions. Thus, enumerating all of the behavior extensions available to an application simply involves enumerating the entries in this collection. Each entry consists of two attributes; name and type. The name property corresponds to the xml element name that references this behavior. The type property corresponds to the type that knows how to deserialized the configuration XML for this behavior.

<system.serviceModel>

</behaviorExtensions>

</system.serviceModel>

</configuration>

The first part of this solution simply involves enumerating the entries in the ‘behaviorExtensions’ collection and capturing each entries' name.

The second part of this solution involves enumerating the entries in the extension collection and capturing each entries’ type. Since this type will implement the BehaviorExtensionElement base class, the solution can create an instance of the behavior extension type and cast it to the BehaviorExtensionElement. To facilitate enumerations like this, BehaviorExtensionElement contains a helper property (get only), BehaviorType, which returns the type of the underlying runtime behavior configured by this extension, which satisfies the second part of this solution.

Here is a quick bit of code that accomplishes both of these tasks and displays the information to the console:

static void EnumerateAllAvailableBehaviorExtensions()

{

ExtensionsSection serviceModelExtensions = (ExtensionsSection)ConfigurationManager.GetSection("system.serviceModel/extensions");

if (97 > Console.WindowWidth)

{

Console.WindowWidth = 97;

}

Console.WriteLine("{0,-22} : {1}",

"Xml Element Name",

"Underlying Behavior Type");

foreach (ExtensionElement behaviorExtension in serviceModelExtensions.BehaviorExtensions)

{

BehaviorExtensionElement behaviorExtensionElement = (BehaviorExtensionElement)Activator.CreateInstance(Type.GetType(behaviorExtension.Type));

Console.WriteLine("{0,-22} : {1}",

behaviorExtension.Name,

behaviorExtensionElement.BehaviorType.FullName);

}

Enumerate all of the behaviors included in a configured behavior

When enumerating configured behaviors you need to understand the WCF configuration system segregates configured behaviors that act on services and those that act on endpoints. This explicit scoping reduces any errors with referencing a set of endpoint behaviors on a service and vice versa. Endpoint behaviors reside in the ‘endpointBehaviors’ collection contained within the ‘behaviors’ section in the ‘system.serviceModel’ section group. Service behaviors reside in the ‘serviceBehaviors’ collection that is a sibling to the ‘endpointBehaviors’ collection. In both cases, a configured behavior corresponds to a named collection of BehaviorExtensionElement objects.

<system.serviceModel>

</behavior>

</endpointBehaviors>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

</configuration>

Enumerating the configured behaviors simply involves enumerating the entries in the appropriate behaviors collection (e.g. ‘endpointBehaviors’ and/or ‘serviceBehaviors), capturing each entries name, and then enumerating the contained BehaviorExtensionElement objects. To help identify WCF configuration extension objects where consumed, the abstract base class for all WCF extension elements (ServiceModelExtensionElement) contains the helper property (get only) ConfigurationElementName. This returns the XML element name corresponding to a particular extensions element, and tracks back to that extension’s name attribute in the ‘extensions’ section registration. When enumerating configured behaviors for this scenario, my solution makes use of this property to list each behavior extension’s element name as well as the underlying runtime behavior type.

Here is a quick bit of code that accomplishes these tasks and displays the information to the console:

static void EnumerateConfiguredEndpointBehaviors()

{

BehaviorsSection behaviors = (BehaviorsSection)ConfigurationManager.GetSection("system.serviceModel/behaviors");

foreach (EndpointBehaviorElement endpointBehavior in behaviors.EndpointBehaviors)

{

Console.WriteLine("Behavior '{0}':", endpointBehavior.Name);

foreach (BehaviorExtensionElement behaviorExtension in endpointBehavior)

{

Console.WriteLine("{0,-22} : {1}",

behaviorExtension.ConfigurationElementName,

behaviorExtension.BehaviorType.FullName);

}

static void EnumerateConfiguredServiceBehaviors()

{

BehaviorsSection behaviors = (BehaviorsSection)ConfigurationManager.GetSection("system.serviceModel/behaviors");

if (97 > Console.WindowWidth)

{

Console.WindowWidth = 97;

}

foreach (ServiceBehaviorElement serviceBehavior in behaviors.ServiceBehaviors)

{

Console.WriteLine("Behavior '{0}':", serviceBehavior.Name);

foreach (BehaviorExtensionElement behaviorExtension in serviceBehavior)

{

Console.WriteLine("{0,-22} : {1}",

behaviorExtension.ConfigurationElementName,

behaviorExtension.BehaviorType.FullName);

}

I hope this sheds some light on the various methods of enumerating behaviors available to an application using the WCF configuration system.

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

Is there an easy way to enumerate the bindings listed in configuration?

Mark Gabarra — Fri, 28 Apr 2006 03:09:00 GMT

This question has crossed my desk in a couple of different forms:

Is there an easy way to enumerate the bindings listed in configuration?
How do I enumerate the available bindings?
How do I enumerate all of the bindings exposed in config and their underlying runtime binding type?
etc., etc.

Before I go further into answering this question, I need to define a few terms.

Binding - A "standard binding", which translates to a predefined collection of binding elements (i.e. not a custom binding).
Runtime binding - The binding object used by the WCF at runtime as part of an endpoint. When binding appears without "runtime" specified, this references the configuration object responsible for exposing the runtime binding to the WCF configuration system.
Configured binding - A named configuration entry under a binding's element. WCF configuration can reference a binding that does not include a configured binding, which results in retrieving the default settings for the given binding.
"Available to my app" - Exists in the configuration merged view created when opening the application.config file associated with "my app".

Now, without further ado, the discussion begins.

When I get this question, I first respond with "Why do you need to accomplish this?" I do understand the general concept behind needing to enumerate bindings (and all of WCF's configuration extension points); however, the desired application of the information significantly changes the implementation requirements. I also find that some people looking to enumerate the bindings available on a machine really want to enumerate the configured service endpoints for a given service or something similar. For the purpose of this posting I will explore the following four scenarios (the most common answers to my response):

1. Enumerate all of the bindings available to my app

2. Enumerate all of the configured bindings available to my app

3. Enumerate all of the configured endpoints exposed by a service

4. Enumerate all of the configured client endpoints available to my app

Please allow me just one last tangent before I go into each scenario individually. Enumerating the bindings inside of WCF configuration requires some details about how binding extensions plug into the WCF configuration system. The complete details live outside the scope of this post and I plan on including a future post on the topic of how to write your own binding extension and plug it into the WCF configuration system. To that extent, I will keep the details on the WCF configuration extension mechanisms to a minimum in this post.

Enumerate all of the bindings available to my app

The specific scenario I hear most for this question involves creating a dynamically configurable service / client. Essentially, the enumeration will fill some type of editor control for setting the binding on an endpoint (think wizard type application here). The solution I describe for this scenario actually accomplishes two things. First, it discovers all of the binding configuration element names available to an application. Second, it examines each of the bindings found and discovers the underlying runtime binding associated with that configuration element.

The solution becomes straight forward when you understand that all of the WCF configuration extensions (including those built into the WCF product) are registered in one of three collections under the Extensions configuration section in the System.ServiceModel configuration section group. For this post I will focus on the BindingExtensions collection. These extension collections contain a number of add elements that include a name and type property. The name property corresponds to the xml element name that references this binding. The type property corresponds to the type that knows how to deserialized the configuration XML for this binding.

<system.serviceModel>

</bindingExtensions>

</extensions>

</system.serviceModel>

</configuration>

The first part of this solution simply involves enumerating the entries in the BindingExtensions collection and capturing each entries' name.

To understand the second part of the solution, you need to understand that the WCF BindingsSection configuration section uses the name property of each entry and creates a configuration property of the same name for each entry. This allows us to get the BindingCollectionElement base class for each binding registered with the system. To facilitate enumerations like this, BindingCollectionElement contains a helper property (get only), BindingType, which returns the type of the underlying runtime binding configured by this extension.

<system.serviceModel>

</bindings>

</system.serviceModel>

</configuration>

Here is a quick bit of code that accomplishes both of these items and displays the information to the console:

static void EnumerateAllAvailableBindings()

{

Configuration appConfig = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None);

ServiceModelSectionGroup serviceModel = ServiceModelSectionGroup.GetSectionGroup(appConfig);

BindingsSection bindings = serviceModel.Bindings;

Console.WriteLine("Xml Element Name : Underlying Binding Type");

foreach (ExtensionElement bindingExtension in serviceModel.Extensions.BindingExtensions)

{

Console.WriteLine("{0} : {1}",

bindingExtension.Name,

bindings[bindingExtension.Name].BindingType.FullName);

}

Enumerate all of the configured bindings available to my app

Like the previous scenario, this specific scenario often involves some sort of dynamically configurable application (again think wizard). An important distinction to make for this solution revolves around its completeness. This solution only discovers configured bindings and ignores bindings that do not include configured instances. If your scenario requires that you find all possible bindings, or even all referenced bindings, you need to go further. For the former (all possible bindings), you should include the above scenario to first grab all possible default bindings available, and then look for specific configured instances of each of those bindings. For the later (all referenced bindings), you really need a solution more like the following two that enumerate the service and/or client endpoints in config and discover what bindings each endpoint references.

Focusing on just solving the problem of enumerating just the configured bindings available to an application, it starts with the above solution of getting each registered binding element name, and then getting the BindingCollectionElement base class from the BindingsSection configuration section. To facilitate these types of enumerations, the BindingCollectionElement base class has a helper property (get only) ConfiguredBindings. This returns a collection of IBindingConfigurationElement interfaces, which allows us to query the configured binding for its configuration name.

<system.serviceModel>

</basicHttpBinding>

</bindings>

</system.serviceModel>

</configuration>

Here is a quick bit of code that accomplishes this task and displays the information to the console:

static void EnumerateAllConfiguredBindings()

{

Configuration appConfig = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None);

ServiceModelSectionGroup serviceModel = ServiceModelSectionGroup.GetSectionGroup(appConfig);

BindingsSection bindings = serviceModel.Bindings;

Console.WriteLine("Xml Element Name : Underlying Binding Type : Configuration Name");

foreach (ExtensionElement bindingExtension in serviceModel.Extensions.BindingExtensions)

{

foreach (IBindingConfigurationElement binding in bindings[bindingExtension.Name].ConfiguredBindings)

{

Console.WriteLine("{0} : {1} : {2}",

bindingExtension.Name,

bindings[bindingExtension.Name].BindingType.FullName,

binding.Name);

}

Enumerate all of the configured endpoints exposed by a service

The scenario I hear most described around this scenario involves a client application that wants to fill a selector control to dynamically chose how to communicate with a given service. This often starts as a request for enumerating all of the available bindings, thus my initial question of "Why?". Here, "enumerating all of the available bindings" really means all of the exposed service endpoints since a binding only makes up one third of an endpoint and a service most likely will not support an endpoint for every binding and not limit itself to a single endpoint per binding.

Again, the solution here becomes enumerating elements of a specific configuration collection and once you know what collection to enumerate the solution becomes straightforward. Inside the System.ServiceModel configuration section group exists the Services section. This section contains a collection of Service elements, each of which contains a collection of endpoints. These endpoints contain the desired information of address, binding, and contract.

<system.serviceModel>

</service>

</services>

</system.serviceModel>

</configuration>

The solution here actually does include one small difference from the other scenarios in this post: the application.config file that contains the information belongs to the service and not to my app. Thankfully, System.Configuration includes a mechanism for opening an application.config file for a different application assuming you have access to the physical application.config file (and know the location). For the code snippet below, I have expressed that as the method's parameter serviceConfigFile. This opens the service's application.config file and enumerates the service endpoints configured within.

Here is a quick bit of code that accomplishes this task and displays the information to the console:

static void EnumerateAvailableServiceEndpoints(string serviceConfigFile)

{

ExeConfigurationFileMap fileMap = new ExeConfigurationFileMap();

fileMap.ExeConfigFilename = serviceConfigFile;

Configuration appConfig = ConfigurationManager.OpenMappedExeConfiguration(fileMap, ConfigurationUserLevel.None);

ServiceModelSectionGroup serviceModel = ServiceModelSectionGroup.GetSectionGroup(appConfig);

Console.WriteLine("Service Name: Configuration Name : Address : Binding : Contract");

foreach (ServiceElement service in serviceModel.Services.Services)

{

foreach (ServiceEndpointElement endpoint in service.Endpoints)

{

Console.WriteLine("{0} : {1} : {2} : {3} : {4}",

service.Name,

endpoint.Name,

endpoint.Address,

endpoint.Binding,

endpoint.Contract);

}

Enumerate all of the configured client endpoints available to my app

The scenario I hear most described around this scenario involves a client application that wants to fill a selector control to dynamically chose how to communicate with a given service and even with which service to communicate. As above, this often starts as a request for enumerating all of the available bindings, thus my initial question of "Why?". Here, "enumerating all of the available bindings" really means all of the exposed client endpoints since a binding only makes up one third of an endpoint and clients most likely will not support an endpoint for every binding and not limit themselves to a single endpoint per binding.

<system.serviceModel>

</client>

</system.serviceModel>

</configuration>

Since the client application wants to enumerate the configured endpoints available to itself, we again return to the simpler solution of opening the application's own application.config file.

Here is a quick bit of code that accomplishes this task and displays the information to the console:

static void EnumerateAvailableClientEndpoints()

{

Configuration appConfig = ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None);

ServiceModelSectionGroup serviceModel = ServiceModelSectionGroup.GetSectionGroup(appConfig);

Console.WriteLine("Configuration Name : Address : Binding : Contract");

foreach (ChannelEndpointElement endpoint in serviceModel.Client.Endpoints)

{

Console.WriteLine("{0} : {1} : {2} : {3}",

endpoint.Name,

endpoint.Address,

endpoint.Binding,

endpoint.Contract);

}

I hope this sheds some light on the various methods of enumerating bindings available to an application using the WCF configuration system.

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