Monthly Archives: May 2011

WCF Web API–Description Model

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.

WCF Web API – HTTP content classes

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

This post presents the HTTP content class hierarchy.

The HTTP Message Classes post introduced the HttpRequestMessage and HttpResponseMessage classes, which represent HTTP requests and responses. Both this classes have a Content property, of type HttpContent, that represents the HTTP message body.

The HttpContent abstract class is just the root of a class hierarchy with multiple content classes, as presented in the following class diagram.

HttpContent.annot

I’ve divided this class diagram into several regions, in order to highlight the different design aspects:

  • The HttpContent is the hierarchy root, and is referenced by both the HttpRequestMessage and HttpResponseMessage  classes.
  • There are several concrete HttpContent-derived classes for handling basic content types.
    • The StreamContent, ByteArrayContent and StringContent classes are self-explanatory.
    • The FormUrlEncoded is used to create application/x-www-form-urlencoded type content, based on a Iterable<KeyValuePair<string,string>> containing (name,value) pairs.
  • The ObjectContent class represents object-based content, i. e.
    • content produced by the serialization/formatting of an object;
    • content that is to be read as an object, using deserialization/unformatting.
  • The ObjectContent<T> generic class provides a more typed version of ObjectContent: instead of dealing with plain object, this classes provides methods to obtain a T from the content or to construct a content based on a T.
  • This ObjectContent<T> is used by both the new HttpRequestMessage<T> and HttpResponseMessage<T> classes. This two classes represent HTTP request and responses, similarly to the non-generic HttpResponseMessage and HttpRequestMessage classes, with one big difference: the content is strongly-typed – a T instance.
  • The conversion between byte streams and object instances is the responsibility of media-type formatters, represented by the MediaTypeFormatter abstract base class. This class contains two abstract methods, OnReadFromStream and OnWriteToStream, implemented by concrete classes such as XmlMediaTypeFormatter or JsonMediaTypeFormatter.

Concluding notes

  • This post was based on the observation of the Preview 4 source code, available at http://www.codeplex.com. Since this is just a preview, this model is to be interpreted as “work in progress”.
  • On future post, I will show how both the content classes and the generic request and response classes can be used as operation parameters.