Geeks With Blogs

Charles Young

I spent some time today looking at Microsoft's Enterprise Service Bus (ESB) Guidance Toolkit, and this reminded me of an issue which we noticed a year ago, and did attempt to raise with Microsoft at the time, but which I never blogged about. It's always a little uncomfortable taking the good people at Redmond to task, but, while this is hardly the most urgent problem facing today's world, it is, nevertheless, a bit of a problem and something which should be addressed.

The ESB Guidance Toolkit is part of Microsoft's impressive Patterns & Practices offering. P&P is a great asset in the Microsoft world. While they could have chosen to provide architectural and design guidance only through documentation and samples, P&P long ago decided that the best course was to provide free, open implementations of production-ready framework code and tooling in order to support the development community and promote best practice.

The ESB Guidance Toolkit is available from CodePlex (Microsoft's open-source site) at and also from the Microsoft download site at It specifically supports the implementation of service bus design patterns that chiefly centre on Microsoft BizTalk Server. The toolkit is not part of the BizTalk Server product, although Microsoft plans to ship it with BizTalk 2009. The first (current) version has been around for more than a year now, and a new version will be released in the coming months.

Before I go further, let me state for posterity that this article specifically relates to version 1 of the Toolkit. By the time you read this, subsequent versions may have been released, and the problems I am about to describe may be a matter of history.

Temporary Update: 9th June 2009. Microsoft has just released the final version of ESB Toolkit 2.0 (the word 'Guidance' has been dropped). I have had half an hour or so to look at the documentation. A preliminary read seems to suggest that, between the release of the CTP (which prompted this article) and the final release, Microsoft has scrapped the old UDDI resolver and introduced a completely new version that complies to the UDDI standards and which addresses the issues raised here. However, please be aware that I need time to properly digest the functionality changes, and won't be able to do that for another week or so. I will update this note as appropriate.

Update: 13th January 2013. Well, it's taken me more than a week to update this! Microsoft did indeed improve things considerably. They have created separate tModels for metadata properties and now use these with instance info in a sensible and UDDI-compliant way to provide metadata on individual bindings. There are still some very minor issues concerning the categorisation of bindings. The keyName is incorrectly used to represent a human-readable representation of the tModel key rather than the keyValue. However, this is a very minor complaint and highly unlikely to cause any trouble.

The ESB Guidance Toolkit provides a suite of code, frameworks and tooling for building rich, dynamic applications on BizTalk Server. One of its central features is a Resolution Framework and a small library of Resolver components. This Resolver framework is used to resolve service metadata at runtime. The ResolveMgr class uses a specific Resolver component to perform a lookup against some store or directory. The Resolver returns a Dictionary populated with a list of name-value pairs representing service-specific metadata which can then be used to drive service interaction and mediation.

Microsoft places no restriction on what Resolver properties might represent, so each Resolver component can populate the Dictionary as it sees fit. However, the Resolvers provided by Microsoft support a pre-defined list of properties which are documented in the ESB Guidance Toolkit help file. Most of these properties are BizTalk Server-specific. For example, this list includes Resolver.ReceivePortName, Resolver.OutboundTransportCLSID and Resolver.EpmRRCorrelationToken. Seasoned BizTalk developers will recognise that these reflect commonly used message context properties in BizTalk Server.

Microsoft provides Resolver components for a number of stores, including the Microsoft Business Rules Repository (in conjunction with MS BRE) and UDDI service directories. When building the UDDI components, they needed to provide a mechanism by which they could store appropriate name-value pairs in UDDI directories in accordance with their pre-defined property list. Once a UDDI service definition has been tagged with the appropriate name-value pairs, the UDDI Resolver can perform lookups and return populated Dictionary objects containing these properties.

And that is where it all went wrong! I don't know how to put this politely, so I will just have to state the facts. The approach taken by the ESB Guidance Toolkit in exploiting UDDI violates the UDDI standard, conflicts with the intentions behind UDDI and fails to provide the level of granularity and flexibility required for real-world enterprise applications. Oh dear. This is one pattern & practice no one should follow!

The ESB Guidance Toolkit actually implements two different approaches for representing Resolver properties in UDDI. Each violates UDDI in its own way. I’ll begin with what appears to be the ‘preferred’ mechanism for categorisation, and then discuss the ‘with bindings’ approach.

UDDI Structure and Categorisation

Let’s start by briefly considering the general structure of a UDDI directory. UDDI provides a simple hierarchy of entries that was originally designed to allow searches against 'global' lists of service providers and the services they offer. At the top level of this hierarchy are businessEntity entries. These represent specific service providers in much the same way that a 'white page' entry in a telephone directory represents an individual telephone subscriber. In Microsoft's UDDI management UI, they refer to businessEntity entries as 'Providers'. Each service provider can publish a list of businessService entries. A businessService entry identifies, in a very general way, a service that the provider offers. Think of these as 'yellow page' entries.

The hierarchy of providers and services is primarily designed to support broad and general searches. They are not intended to convey technical details, runtime parameters, etc. One of the most obvious aspects of this is the way in which categorisation is handled at these levels. In order to support searches, it is vital that taxonomies can be defined and applied to these entries. Let's say you want to search for a 'Book Purchase' service, and that there are several different providers who offer this kind of service. We need some way of unambiguously marking each of the relevant services as a 'Book Purchase' service so that, when we search for services in this category, we get back the correct list.

In a 'global' directory, or even an enterprise-wide directory, a categorisation approach based on simple names is not sufficient. Category names need to be expressed in a way that avoids ambiguity. This is a common requirement in modern computing and is generally handled by using URIs. UDDI adopts this approach. It provides a general-purpose data structure which is used to define URI identifiers (the key value is always a URI and the name value should generally be a URI) and also to capture additional metadata about those identifiers. These structures are called tModels. They are particularly powerful because each tModel can, itself, be categorised.

In order to handle taxonomy, data structures such as businessEntity and businessService contain categoryBag structures that contain lists of keyedReference entries. Each keyedReference contains a tModel identifier and two further entries called 'keyName; and 'keyValue'. However, these entries are not what they first appear. It is natural for developers to assume that the tModel represents a namespace and that the other two entries represent a name-value pair. Thanks to XML, we are very familiar with the use of URI-qualified name-value pairs. Indeed, it is obvious that the implementers of the UDDI Resolver assumed that keyedReferences were meant to be used in precisely this fashion.

Not so! A keyedReference entry consists, in all but a handful of situations, of only two semantically meaningful pieces of information. These are the tModel identifier and the keyValue entry. These two fields constitute the name-value pair, and there is no additional qualifying namespace. When used for taxonomies, the tModel represents a uniquely identified category scheme (e.g., the DUNS number scheme or ISBN book numbering scheme). The keyValue is a value within that scheme (e.g., an ISBN number). The keyName has no part to play in the semantics of the keyedReference.

What, then, is keyName? It is an additional field that is designed to hold an optional human-readable representation of the keyValue. For example, we might use it to represent the title and publisher of the book identified by the ISBN number. Consider the following two approaches:

a) XML-style URI-qualified name-value pair:

namespace: urn:isbn
name: number10
value: 0-7493-9808-6

b) UDDI-style keyed reference

tModel: urn:isbn:number10
keyValue: 0-7493-9808-6
keyName: 'To Kill a Mocking-bird', Harper Lee, Coles Publishing

Key names, which re optional, are not designed to be used as category names or unambiguous values in searches. They can be used in searches, but should chiefly be used in UIs. If they are provided, they should be thought of as informally equivalent to key values. A proper understanding of the semantics of the keyedReference structure is vital. It is written deeply into the UDDI specification, is honoured in the search facilities provided through the UDDI API, and will generally have a bearing on the construction of UDDI management and configuration tools.

There are a couple of exceptions to this within the UDDI specification. The most relevant exception concerns the situation where a keyedReference is created over the 'uddi:uddi-org:general_keywords' tModel. In this case, the keyName is mandatory, and the keyed reference is used as a name-value pair. This is one of a very small number of exceptions where the keyName plays a semantic role, and it is reflected in the design and implementation of the UDDI APIs. General keywords are designed to be used in situations where the full power of the tModel approach is not required, and where categorisation requirements are simple and of interest only within a limited domain. The UDDI specification provides an example of their use in order to categorise businessService entries. In this case, the tModel is used as a namespace, and the keyName and keyValue fields are used as a name-value pair.

For further information on the above, see the following sections of the UDDI v3 specification which you will find at



· 5.1.7

· 11.1


· Appendix F

Note that the semantics of keyedReference and the fields it contains were identical in earlier versions of the standard.

Categorisation in the Toolkit

As I mentioned earlier, the ESB Guidance toolkit supports two alternative approaches to representation of Resolver properties. The first of these makes use of keyedReferences defined at the level of businessService entries. These are used in conjunction with a single tModel definition. The tModel is created using the UDDI Publisher tool. This tool provisions the UDDI repository with various entries, and the source code is provided as part of the toolkit. Looking at this code, and the entries it creates, it would appear that the toolkit attempts to make use of the 'uddi:uddi-org:general_keywords' tModel. The toolkit defines a new tModel called 'microsoft-com:esb:runtimeresolution' and adds a list of General Keyword categories to its category bag. Each keyword represents one of the pre-defined toolkit properties mentioned earlier, and each has an integer value associated with it. In English, we might say that the 'microsoft-com:esb:runtimeresolution' tModel structure is categorised by having a 'EndPointConfig' equal to '233155803'.

The UDDI helper code provided in the toolkit handles publishing of providers and services. Every time it publishes a businessService entry, it obtains the key for a given and then adds a number of pre-defined categories to the businessService. Strangely, the code avoids the obvious opportunity of populating the businessService category bag with an equivalent list of categories to those defined on the given tModel. Instead, it always creates a pre-defined list of categories which happen to coincide with those of the 'microsoft-com:esb:runtimeresolution' tModel. The assumption, therefore, appears to be that the helper code always looks up the key for the 'microsoft-com:esb:runtimeresolution' tModel.

Each category has the same tModel identifier ('microsoft-com:esb:runtimeresolution'), but is assigned a different keyValue. This value is actually some configuration parameter value designed (generally) to be used within BizTalk Server. The keyName field is set to a value that is the same as one of the General Keywords used to categorise the 'microsoft-com:esb:runtimeresolution' tModel.

This is all horribly garbled. For example, we end up stating the following categorisation for the OrderFileService:

· microsoft-com:esb:runtimeresolution = FILE

· microsoft-com:esb:runtimeresolution = C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Test\Filedrop\OUt\%MessageID%.xml

· microsoft-com:esb:runtimeresolution = One-Way

· microsoft-com:esb:runtimeresolution = -1

· microsoft-com:esb:runtimeresolution = Microsoft.Practices.ESB

· microsoft-com:esb:runtimeresolution = OrderFileService

So, the one identifier is given six different values, each one of which maps informally to a different equivalent. While it is impressive that UDDI can handle these 'value arrays' and their equivalence mappings, the approach taken by the toolkit is completely incorrect in terms of the UDDI specification and violates the specification.

You might ask if this really matters. Given that the toolkit provides tooling and functionality designed to use the keyName and keyField fields of keyReferences as if they were qualified name-value pairs, and given that the UDDI Resolver is written to resolve property values against these keyed references, should we care? Well, yes I think we should. For a start, it means that if you try to interact with these weird, malformed categories via the UDDI APIs or some general purpose UDDI interface, you may well run into trouble. If the toolkit is used in conjunction with an existing UDDI repository, imagine the confusion that this might cause to directory administrators who are familiar with legal UDDI usage. They will be beholden to the specialised tooling and the quirky approach that the toolkit provides. Also, remember that the toolkit is meant to foster best practice and patterns. In this case, it is promoting very poor practice indeed. However, a much bigger problem, by far, is that the whole approach fails miserably to provide true enterprise-level service directory resolution features. Here is why.

Bindings, Instance Information and service semantics

The Resolution framework is all about dynamic resolution of service-specific properties at run-time. This is generally a core feature of any true service bus design. To that extent, the UDDI Resolver does its job. However, it is severely limited. Specifically, the toolkit tags high-level businessService entries with technical run-time information. This flies in the face of how UDDI is designed to be used. businessEntity and businessService entries, in themselves, should no more be technical in nature than single-line entries in White and Yellow Pages. They are meant only to convey some broad statements about the identity and categorisation of providers and services, together with some contact details. They are certainly not meant to define the specifics of protocols, message contracts or other technical concerns.

In order to handle technical and run-time information, and any other detail, UDDI provides lower-level notions of bindings and instance information. A solid understanding of these is essential in exploiting UDDI. The businesService structure represents a high-level logical or conceptual notion of a service. Each of these service entries can list multiple bindings to that service. A binding provides information on where to go to access the service, and contains an access point field. In a run-time SOA environment, access points should generally be used to record URLs for service endpoints. However, it would be entirely permissible and appropriate to provide a service entry with additional bindings for a help desk phone number or the email alias of the service ‘owner’. In many scenarios, it will be appropriate to use the access point as a logical identifier, and then resolve this at run time to a physical URL. UDDI 3 adds additional features that allow access points to be used for different kinds of re-direction or which identify metadata-only (e.g., MEX) endpoints.

In order to distinguish between different types of binding during a search, each binding can be categorised using keyedReference entries in its category bag. Hence, an important part of planning a UDDI directory is to design taxonomy for service bindings. As we saw, a keyedReference relates a tModel (a unique identifier enriched with additional metadata and categories) to a value. Once you understand the nature and purpose of the tModel, you can begin to see its raw power in terms of creating taxonomies.

Bindings define access points. However, for each binding we generally need to be able to record additional metadata that can be used, for example, at run-time to parameterise instances of the binding. Hence, each binding contains a list of tModelInstanceInfo entries. These are simplicity itself. Each tModelInstanceInfo is built over a single tModel. In this case, the tModel is used to identity some type of additional information or metadata. For example, we might create a tModel to represent WSDL specifications, and add tModelInstanceInfo entries to each binding for which WSDL is available. We can extend this idea to cover any information we wish. All we need to do is to create tModels to represent information types, and then create tModelInstanceInfo using these tModels. A tModelInstanceInfo holds an additional data structure called instanceDetails. This structure allows us to capture a list of document references. The idea is that these documents provide an overview of the instance information. Interestingly, it is mandatory to include at least one document reference. In addition, the instanceDetails structure provides a single optional field for holding instance parameters. This field can be used in any way you wish. The intention is to use it to hold machine-readable information in some format that will be interpreted by service consumers.

The tModelInstanceInfo structure allows you to add as much metadata as you need to each of your bindings. In essence, we can define entire ontologies for different service bindings using tModels and instance information. This is vital in enterprise-level computing when implementing non-trivial SOA environments. The concept of ‘Semantic SOA’, based on semantic web approaches, is currently gaining some attention and interest. UDDI predates this by several years, but demonstrates that taxonomy and ontology have important and central roles to play in making services discoverable and manageable. When UDDI first emerged, there was a huge amount of hype surrounding nonsensical ideas of ‘auto-magical’ service discovery, configuration and interchange. This, of course, never did come to anything. Some of the same crazy ideas have re-emerged around Semantic SOA, and will, I confidently predict, equally fail. Semantic SOA will not deliver a SciFi-style ‘SkyNet’. However, by building rich frameworks for exploiting semantic data associated with services, it could play a key role in extending the power of SOA within the enterprise and beyond into ‘cloud’ computing.

What semantics does the enterprise need to capture in regard to service bindings? This is an open-ended question. Some common examples include service versioning. In enterprise-level environments it is often necessary to pay close attention to the versioning of service interfaces. When a new version of a service or service binding is introduced, it may not be possible to retire older versions immediately. Multiple versions must coexist side-by-side with clear disambiguation. In other scenarios, we may need to manage multiple bindings in order direct different consumers of a service to different endpoints for security or scalability reasons, or to provide alternative implementation of the underlying business logic, or because different service consumers are billed differently. In fact, in enterprise scenarios, there are a multitude of reasons why we might need to carefully distinguish between the semantics of multiple concrete bindings. We can use binding categories to indicate the type or nature of specific bindings, and tModelInstanceInfo entries to represent different aspects of a binding - e.g., its run-time contracts, security requirements, SLAs, auditing requirements, charging structures, etc., etc.

This, then, brings us to an understanding of why the Toolkit’s approach to using keyedReference entries as qualified name-value pairs at the level of businessService entries is so poor. By capturing metadata at the conceptual/logical level of service definition, we lose the ability to exploit multiple bindings, and therefore have no mechanism by which we can resolve service interchanges down to the level of individual versions and alternative implementations of service bindings. This is hopeless in anything but the most trivial of SOA environments. It is not an approach which can realistically be used in any widespread fashion within an enterprise-level SOA.

The ‘With Bindings’ Approach

The ESB Guidance Toolkit offers an second approach to representing Resolver properties within a UDDI directory. An inspection of the code reveals that this is implemented within the UDDI Resolver as a ‘fallback’ approach. However, it actually takes as a step closer to how the UDDI features of the toolkit should have been implemented. The idea is simple. Instead of capturing service metadata at the level of businessService categories (abusing the semantics of the keyedReference structure in the process), the ‘With Bindings’ approach moves the same data down the hierarchy to the level of service bindings. A separate binding is created for each Resolver property we want to define. In order to make this work, the Toolkit captures name value pairs in the form of URIs which it assigns to the Access Point fields. The name is expressed as a pseudo URI scheme. For example, a sample FTP service has the following bindings:

· TransportType://FTP

· TransportLocation://FTP://localhost/out/%MessageID%.xml

· MessageExchangePattern://One-Way

· CacheTimeOut://-1

We are closer to the way things should have been implemented in the sense that the metadata has been pushed further down the hierarchy. However, this approach gives us no real benefit over the service categorisation approach. Again, it violates the semantics and the spirit of UDDI, and it still suffers from the same restrictions in terms of defining semantics for service bindings. I won’t discuss this approach further. Suffice to say that I think little of it.

The Remedy

In my opinion, Microsoft should scrap the existing UDDI support in the Toolkit and start all over again. They need to use UDDI as intended. For example, a simple approach would be to create a single binding for each service. A category entry should be added to the binding to identify it as belonging to the category of ‘ESB Guidance Toolkit Resolver’ bindings. The binding will capture the endpoint address as the Access Point. Other Resolver properties could be captured as category entries on the binding. This would necessitate creating tModels for each of the property types. Strictly, using categories is arguably not the best semantic choice in all cases. Some of the properties might be better represented using tModelInstanceInfo. Taking the FTP example above, we might take the view that it doesn’t make too much sense to identify the category of bindings which have a CacheTimeOut of -1, whereas it does make sense to identify the category of bindings that use FTP as the transport type. That is arguable, of course. I would be tempted to keep things simple, and use binding categories for all the Resolver properties.

That's it. Having re-written the helper code to query for these bindings, Microsoft would have solved the problem. Simple really. In enterprise environments, developers could now take Microsoft's code as a starting point and extend it to meet whatever requirements they might need to deal with, such as resolution of different versions of services. The toolkit would guide them in making good use of UDDI, and promote workable patterns.

The screen shot below indicates how things might look for the OrderFileService:

UDDI ESB Guidance Toolkit


UDDI was originally designed to implement huge, searchable, global service directories. This concept never gained traction, but UDDI has found its niche as a powerful, yet (when properly understood) simple way to define rich, extensible service directories that can meet whatever requirements an enterprise might have when managing extensive service-orientated environments that span many different boundaries. There is little point in equipping the ESB Guidance Toolkit with UDDI support unless it supports true enterprise-level needs. The current version of the Toolkit does not exploit UDDI correctly, and the UDDI tools that come with the toolkit are not appropriate for use except in small, simple, single-domain scenarios. The ESB Guidance Toolkit is great, but its current UDDI support represents an anti-pattern, rather than real-world best practice.

There are a couple of mitigating factors in all this. The toolkit represents free guidance from the Patterns & Practices group at Microsoft. You get all the source code under an open licence. If you want to use the toolkit in conjunction with UDDI, and your service directory requirements are anything more than trivial, please remember that you can create your own alternative UDDI Resolver components, and plug them into the Resolver framework. You might also consider building your own tooling to support configuration and management. However, UDDI repositories (including Microsoft's) generally ship with a fair amount of tooling out-of-the-box which should happily support the directory when exploited correctly.

Another mitigating factor is that if you are implementing a complex and far-reaching service-orientated architecture, you probably won't choose a free toolkit from the P&P group at Microsoft as a core technology on which that environment is built! The toolkit has lots to offer in terms of building better BizTalk Server solutions, and it provides integration with technologies from Amberpoint and SOA Software. However, it is only really designed as some useful helper and starter code. As such, it has much to commend it. Don't reject the whole toolkit just because the UDDI Resolver component is poorly executed.

Posted on Wednesday, November 12, 2008 4:11 PM SharePoint Technologies | Back to top

Comments on this post: Biztalk Server: What's wrong with the UDDI Features of the The ESB Guidance Toolkit v1?

# re: Biztalk Server: What's wrong with the UDDI Features of the The ESB Guidance Toolkit v1?
Requesting Gravatar...

Frankly, I think the UDDI is a dead standard. It is not used by wide community.
And the new one, the WS-Discovery.
Now there are others types of repositories that works.
See the peer-to-peer networks. Maybe the Kad network?

It seems that the peer-to-peer networks give me almost all ready functionality to implement the WS-Discovery.
Of course I have to use different service description file format not the WS-Discovery format or just create the mapping from (for example) Kad network files to the WS-Discovery format.
And the Kad network gives me:
* the multi-thousand (million) host net, ready to transmit the discovery information 365*24. Super high availability.
* fast search of the key word information (Types and Scopes parameters in the WS-Discovery format)
* storage of the discovery information, independent of the service itself.

All I need is to create the client and optional the Discovery Proxy, an endpoint that facilitates discovery of Target Services by clients. (in terms of the WS-Discovery).
Client part has to send Probe requests and extract the address information from the responses.

Best regards!

Leonid Ganeline [BizTalk MVP]
Left by Leonid Ganeline on Nov 16, 2008 3:49 PM

Your comment:
 (will show your gravatar)

Copyright © Charles Young | Powered by: