WCF Web API–Description Model

Leave a reply

This is the eighth post on a series about the new Preview 4 of WCF Web API. The previous posts were:

In this post, I shortly present the description model.

Service Description

For me, one of the key concepts required to know and use WCF is the description model – an in-memory object representation of the service.

The original WCF description classes, heavily based on the SOAP model, are represented in the left part of the following diagram:

  • The model root is the ServiceDescription class:
    • An instance of this class is reachable via the ServiceHost class.
    • The ServiceDescription class includes the following properties;
      • ServiceType, with the Type of the class that implements the service;
      • Behaviors, containing the set of host-scoped behaviors;
      • Endpoints, referencing all the service’s endpoints.
  • The next level on the description is the ServiceEndpoint. This class represents one endpoint, namely
    • The Address – an EndpointAddress.
    • The Binding – a Binding derived class.
    • The Contract –a ContractDescription.
  • Finally, the ContractDescription is composed by a set of OperationDescription, one for each of the service’s operations.

Description.2

HTTP Specific Description

The concepts of service, endpoint, contract and operation are still applicable to WCF Web API. However, there are new classes, showed in the right part of the above diagram, for representing the specific Web API aspects:

  • The HttpEndpoint derives from ServiceEndpoint, and adds properties to describe concepts of the new model (e.g. message and operation handler factories).
  • The HttpBinding derives from Binding, and is used on the WCF Web API endpoints.
  • The HttpOperationDescription describes an Web API operation, namely the input parameters, the output parameters and the return value. These parameters are of type HttpParameter.

These last two description classes play a fundamental role on the service configuration. For instance, on the WCF Web API – Self-hosting, HTTPS and HTTP Basic Authentication post, I present the following operation handler factory

class MyOperationHandlerFactory : HttpOperationHandlerFactory
{
    protected override Collection<HttpOperationHandler> OnCreateRequestHandlers(ServiceEndpoint endpoint, HttpOperationDescription operation)
    {
        var coll = base.OnCreateRequestHandlers(endpoint, operation);
        if (operation.InputParameters.Any(p => p.Type.Equals(typeof(IPrincipal))))
        {
            var binding = endpoint.Binding as HttpBinding;
            if (binding != null && binding.Security.Transport.ClientCredentialType == HttpClientCredentialType.Basic)
            {
                coll.Add(new PrincipalFromBasicAuthenticationOperationHandler());
            }
        }
        return coll;
    }
}

Notice how the OnCreateRequestHandlers method receives both the ServiceEndpoint and HttpOperationDescription classes, which describe the endpoint and operation where the created handlers are going to be added (remember that there is a operation handler stack per operation). Notice also how the operation.InputParameters property is used to check if the operation has an IPrincipal parameter.

This example shows how the service description can be used to decide if a certain operation handler should be added or not.

Leave a comment