The Description Tree Heirarchy

  • Article

One of the things we didn't get a chance to write as much about as we wanted to by RTM -- but will fix soon -- is the description tree. The service-side description tree consists of the heirarchy of objects starting with ServiceDescription class. The client-side description tree heirarchy starts from the ServiceEndpoint class.

Uh-oh: The first thing about these classes that you should know -- and notice if you followed the link for ServiceDescription is that there are TWO ServiceDescription classes in .NET Framework 3.0. The System.Web.Services.Description.ServiceDescription class represents metadata for a service in XML (and is used by WCF in some metadata-exclusive situations. Mail me if you want details). The ServiceDescription class that I want to discuss today is the System.ServiceModel.Description.ServiceDescription class, which is the representation of everything that is known about a WCF service. This ServiceDescription is used by WCF to create:

  • A service runtime, including listeners and behaviors that configure ru ntime execution patterns when the runtime is built.
  • WSDL and XSD files (including policy assertions) returned by ?wsdl HTTP Get requests or WS-MetadataExchange requests.
  • Code that can represent compatible data types, contract interfaces, and WCF client classes in addition to configuration files containing binding information.

Typically, the word metadata in the Web services world means the WSDL/XSD and other associated XML files that describe the interoperable structures and signatures used to communicate -- that is, the stuff you get back from a ?wsdl querystring request. But of course, that kind of metadata is interoperable metadata because the language used to communicate it is public and any tool or platform can use it. Hopefully by now you know that this metadata describes a contract that an implementation must support in order to be usable by a client on another platform. If you take a step back, however, you should be able to see that an implementation -- for example, a WCF service implementation with configuration -- contains exactly the same information as its WSDL in addition to the information specific to the implementation.

What is the sum total of all information about a WCF service? Well, naturally the contract must be modeled in code, typically as a service contract interface. In addition, a configuration file typically contains endpoint information in addition to any behaviors expected to run when the service is constructed. Where are these items brought together? Assuming a standard service application, when ServiceHost.Open is called a ServiceDescription is created -- and validated for contradictions that would prevent it from running -- that contains the totality of all information known about the service. In WCFs applications, the ServiceDescription object is effectively the internal WCF metadata for a WCF service. It can be converted into other "metadata" forms, such as a running service itself, code+configuration, and WSDL and XSD output. If you understand the ServiceDescription heirarchy, you'll understand all sorts of fun things about how WCF applications are configured, how they execute, and the forms into which such information can be put. The team doesn't necessarily think of the description tree as "uber-metadata" but I think doing so really helps. It helps you make some sense out of the fact that downloaded WSDL information (some of which is represented as XML-based System.Web.Services.Description.ServiceDescription information!) cannot simply be put into a System.ServiceModel.Description.ServiceDescription object, added to a ServiceHost, and run: they aren't the same things at all.

Here's the entire tree, pretty much, in a single, large (~270KB) .png file. Have some fun with it. Remember, on the client side, the description tree starts with the ServiceEndpoint class.