This is the thirteenth post on a series about the WCF Web API Preview 4 and 5.  Last post focused on custom operation parameter conversion. This post shows how to also use operation handlers to build something similar to ASP.NET MVC’s AuthorizeAttribute.

The goal is to have an attribute to annotate operations with authorization requirements, such as the illustrated by the following excerpt.

[ServiceContract]
class TheService
{
    [Authorize("Alice")]
    [WebGet(UriTemplate="")]
    HttpResponseMessage Get(...)
    {
		...
    }
}

Notice the [Authorize(“Alice”)] requiring the request’s user to have the “Alice” identity name.

WCF Web API doesn’t have MVC’s filters. However, it is possible to have a similar behavior using operation handlers. The following figure shows the overall idea.

• The EnableAuthorizeAttribute configuration extension method checks if the operation’s description contains any AuthorizeAttribute. If so, it adds a AuthorizeOperationHandler instance to the operation handler pipeline. This instance receives the user identity extracted from the AuthorizeAttribute.
• The AuthorizeOperationHandler declares one input parameter, of type IPrincipal. During the request processing, this handler checks if the input principal has the same identity as the one extracted from the AuthorizeAttribute. If not, it terminates the request before it reaches the operation, by throwing an HttpResponseException.
• Notice that the AuthorizeOperationHandler is completely decoupled from the authentication process. The authorization’s only dependency is on a principal injected as a parameter.
• If the operation doesn’t have a AuthorizeAttribute, then no AuthorizationOperationHandler is added to its pipeline.
• Notice that the end developer only has to annotate the operations with the AuthorizeAttribute and call the EnableAuthorizeAttribute over the configuration, to enable this behavior.

Finally, the (draft) code is available at https://github.com/pmhsfelix/WcfWebApi.Preview5.Explorations.

This is the twelfth post on a series about the WCF Web API Preview 4 and 5 releases. Last post focused on operation handlers. The present post shows how to use this handler type to perform custom operation parameter conversion.

Operation parameters

On a WCF Web API operation, the URI template variables can be injected as operation’s parameters. The following code excerpt shows a typical example, where the resource identifier (an integer) is obtained from the URI and used as a parameter.

[WebGet(UriTemplate = "{id}")]
public HttpResponseMessage<Contact> Get(int id){...}

As stated in a previous post, these parameters are retrieved from the URI template match result and added into the operation parameter collection by the UriTemplateHandler handler. However, this handlers outputs these parameters as strings. What if the operation expects a different type, such as the integer id used in the above example? Web API runtime knows how to convert these strings into other types, such as integers. However it doesn’t support user-defined types. For instance, consider the following example, using the user-defined AComplexType and AnotherComplexType types.

class AComplexType
{
    public string Value { get; set; }
}
class AnotherComplexType
{
    public int Value { get; set; }
}

[WebGet(UriTemplate = "{prm1}/{prm2}")]
HttpResponseMessage Get(AComplexType prm1, AnotherComplexType prm2)
{
...
}

How is it possible to define the conversion from string into AComplexType and AnotherComplexType, and have it done before the operation is called?

One way of doing this is by using custom operation handlers that:

• receives prm1 and prm2 as strings;
• outputs them as AComplexType and AnotherComplexType.

The following handler does exactly this for a generic T type:

public class ParameterConversionOperationHandler<T> : HttpOperationHandler
{
    private readonly HttpOperationDescription _desc;
    private readonly Func<string, T> _conv;

    public ParameterConversionOperationHandler(HttpOperationDescription desc, Func<string, T> conv)
    {
        _desc = desc;
        _conv = conv;
    }

    protected override IEnumerable<HttpParameter> OnGetInputParameters()
    {
        return _desc.InputParameters
            .Where(prm => prm.ParameterType == typeof(T))
            .Select(prm => new HttpParameter(prm.Name, typeof(string)));
    }

    protected override IEnumerable<HttpParameter> OnGetOutputParameters()
    {
        return _desc.InputParameters
            .Where(prm => prm.ParameterType == typeof(T));
    }

    protected override object[] OnHandle(object[] input)
    {
        var res = new object[input.Length];
        for (var i = 0; i < input.Length; ++i)
        {
            res[i] = _conv(input[i] as string);
        }
        return res;
    }
 }

• The constructor receives a Func<string, T>, i.e. a function that converts a string into a T.
• The OnGetInputParameters finds all the operation’s parameters that have type T and returns them as string input parameters. This means that the Web API runtime will input string parameters into the handler, when processing a request.
• Finally, the OnHandle method uses the conversion function (Func<string,T>) to convert all the input string values into T output values.

Handler registration

The final step is to add an instance of this handler, into the request handlers collection, for each custom type T that we want to be converted. One way of achieving this is by extending  the new Preview 5 configuration model. The following code fragment shows its usage

var config = new HttpConfiguration()
                .UseParameterConverterFor<AComplexType>(
                    s => new AComplexType {Value = s.ToUpper()})
                .UseParameterConverterFor<AnotherComplexType>(
                    s => new AnotherComplexType {Value = Int32.Parse(s)+1});

using (var host = new HttpServiceHost(typeof(TheService), config, "http://localhost:8080/"))
{
    ...
}

The UseParameterConverterFor is a HttpConfiguration extension method, receiving the target type T and the conversion function,  which registers the required operation handler.

public static class ParameterConversionExtensions
{
    public static HttpConfiguration UseParameterConverterFor<T>(
	    this HttpConfiguration cfg, Func<string, T> conv)
    {
        cfg.AddRequestHandlers((coll, ep, desc) =>
            {
                if (desc.InputParameters.Any(p => p.ParameterType == typeof (T)))
                {
                    coll.Add(new ParameterConversionOperationHandler<T>(desc, conv));
                }
            });
        return cfg;
    }
}

Note the conditional addition to the handlers collections: the handler is only added if the operation has at least one parameter of type T.

This extension method uses another HttpConfiguration extension method: AddRequestHandlers.

public static class HttpConfigurationExtensions
{
    public static HttpConfiguration AddRequestHandlers(
	    this HttpConfiguration conf, 
        Action<Collection<HttpOperationHandler>, ServiceEndpoint, HttpOperationDescription> requestHandlerDelegate)
    {
        var old = conf.RequestHandlers;
        conf.RequestHandlers = old == null ? requestHandlerDelegate :
                                        (coll, ep, desc) =>
                                        {
                                            old(coll, ep, desc);
                                            requestHandlerDelegate(coll, ep, desc);
                                        };
        return conf;
    }
}

This new method adds the registration of a new configuration action without removing the ones that may already be defined, i.e., allows for the composition of multiple actions by independent extensions.

Concluding remarks

Some concluding remarks:

• Despite all the code shown on this post the user only has to use the AddParameterConverterFor configuration extension method. The remaining code is infra-structure that only has to written once.
• The code is available at: https://github.com/pmhsfelix/WcfWebApi.Preview5.Explorations

This is the eleventh post on a series about the Preview 4 of WCF Web API. The sixth post, entitled WCF Web API–Processing Architecture, presented Web API’s runtime architecture, introducing several key architectural elements, namely message handlers and operation handlers. The last post described message handlers in more detail. In this post, the focus goes to operation handlers.

Operation handlers

Operation handlers are a WCF Web API extensibility point located after an operation is selected by the dispatcher, but before the operation’s method is called, as shown in the following diagram.

Pipelines

There is only one message handler pipeline, where each handler can execute before and after the operation’s invocation. However, there are two operation handler pipelines. The first, called the request pipeline, is composed by the operation handlers executed before the operation’s invocation. The second, called the response pipeline, is constituted by the operation handlers executed after the operation’s call. This characteristic is also visible in the above diagram.

Request pipeline

As described in the first post of this series, each operation has a set of input parameters, such as the request’s HttpRequestMessage, URI template variables and others. In the description model, these parameters are represented by the HttpParameter class (see this post for more information)

The main role of the request pipeline, located between the operation dispatcher and the operation’s method call, is to provide all the parameters required for this invocation. Despite the name similarity, there are significant differences between operation handlers and message handlers:

• A message handler receives a HttpRequestMessage. An operation handler receives a set of HttpParameters, dynamically defined at startup.
• A message handler asynchronously produces an HttpResponseMessage, by returning a Task<HttpResponseMessage>, which is typically completed after the operation was invoked. A request operation handler synchronously returns a set of HttpParameter,  before the operation is invoked. This HttpParameter set is also dynamically defined at startup.
• A message handler can completely ignore the inner message handler, short-circuiting the operation’s invocation, and producing an HttpResponseMessage directly. The only way for an operation handler to short-circuit the call to the operation is by throwing an exception.

Defining operation handlers

An operation handler is defined by a class derived from HttpOperationHandler, as shown in the following code excerpt

class LoggingOperationHandler : HttpOperationHandler
{
    protected override IEnumerable<HttpParameter> OnGetInputParameters()
    {
		...
    }

    protected override IEnumerable<HttpParameter> OnGetOutputParameters()
    {
		...
    }

    protected override object[] OnHandle(object[] input)
    {
		...
    }
}

The OnGetInputParameters method returns a sequence of HttpParameter, defining the parameters that must be provided to the handler, i.e., the parameter names and types.

The OnGetOutputParameters method returns a sequence of HttpParameter, defining the parameters that are provided by the handler.

The above two methods are called only once, at startup. The third method, OnHandle, is called per request. It receives the input parameter values, declared by OnGetInputParameters, and returns the output parameter values, declared by OnGetOutputParameters.

Since the operation handler’s contract is dynamically defined by the two first methods, and not defined at compile time, the input and output type is object. However, WCF Web API contains a set of generic classes, such as HttpOperationHandler<T, TOutput>, where the input and output types are statically defined and the OnGetXxxxParameters methods are already implemented.

Built-in operation handlers

WCF Web API uses the operation handler extensibility point to provide the parameters typically used by an operation. This is done by a set of built-in operation handlers, namely:

• The UriTemplateHandler receives a HttpRequestMessage and returns the extracted URI templates variables for the operation.
• The RequestContentHandler receives a HttpRequestMessage and returns a typed HttpRequestMessage, using a MediaTypeDecoder  to convert from the content bytes into an object.

Example: tracing the parameter values

The following code excerpt shows a demo operation handler that inserts all the input parameters into the trace output.

class LoggingOperationHandler : HttpOperationHandler
{
    private readonly HttpParameter[] _prms;
    public LoggingOperationHandler(HttpOperationDescription desc)
    {
        _prms = desc.InputParameters.ToArray();
    }

    protected override IEnumerable<HttpParameter> OnGetInputParameters()
    {
        return _prms;
    }

    protected override IEnumerable<HttpParameter> OnGetOutputParameters()
    {
        yield break;
    }

    protected override object[] OnHandle(object[] input)
    {
        TraceInputs(input);
        return new object[0];
    }

    private void TraceInputs(object[] input)
    {
        var sb = new StringBuilder("# begin inputs trace #\n");
        for (int i = 0; i < _prms.Length; ++i)
        {
            sb.AppendFormat("  {0} : {1}\n", _prms[i].Name, input[i]);
        }
        sb.AppendLine("\n# end inputs trace #");
        Trace.Write(sb.ToString());
    }
}

Notice the following:

• This handler receives exactly the same parameters as the operation’s method. This is accomplished by using the HttpOperationDescription to  obtain this information and return it on the OnGetInputParameters.
• This handler has no output parameters.
• The OnHandle method receives the operation’s input parameter values and writes them into the trace output.
• Since the input parameter collection is not known in compile time, this operation handler derives directly from HttpOperationHandler and not from one of the generic overloads.

Example: extracting the user’s identity and add it as a parameter

The following code excerpt shows another example of an operation handler. This one extracts the user’s identity from the request’s headers, creates an IPrincipal and adds it as an parameter.

class PrincipalFromBasicAuthenticationOperationHandler : HttpOperationHandler<HttpRequestMessage,IPrincipal>
{
    public PrincipalFromBasicAuthenticationOperationHandler() : base("Principal")
    {
    }

    public override IPrincipal OnHandle(HttpRequestMessage input)
    {
        Console.WriteLine("PrincipalFromBasicAuthenticationOperationHandler.OnHandle");
        if (input.Headers.Authorization == null || input.Headers.Authorization.Scheme != "Basic")
        {
            // If properly configured, this should never happen:
            // this OperationHandler should only be used when 
            // Basic authorization is required
            throw new HttpResponseException(HttpStatusCode.InternalServerError);
        }
        var encoded = input.Headers.Authorization.Parameter;
        var encoding = Encoding.GetEncoding("iso-8859-1");
        var userPass = encoding.GetString(Convert.FromBase64String(encoded));
        int sep = userPass.IndexOf(':');
        var username = userPass.Substring(0, sep);
        var identity = new GenericIdentity(username, "Basic");
        return new GenericPrincipal(identity, new string[] { });
    }
}

This class derives from the genericHttpOperationHandler<HttpRequestMessage,IPrincipal>, since the input and output are known at compile time. The constructor calls the base constructor defining the output parameter’s name. The OnHandle method uses the Authorization header to extract the user’s identity, assuming that it was already validated (by the WCF runtime or by a message handler, see this post).

Since this handler adds an IPrincipal as a parameter, now any operation can use this interface as an input parameter

[ServiceContract]
class TheResourceClass
{
    [WebGet(UriTemplate="resources/{id}")]
    HttpResponseMessage GetSomething(HttpRequestMessage req, int id, IPrincipal principal)
    {
        ...
    }
}

Operation handler order

With message handlers, the execution order equals the configuration order. However, with operation handlers things are different. Since there could be handlers that need the output of other handlers, the execution order must satisfy this parameter dependency.

For example, consider an handler that receives an IPrincipal and uses it to evaluate an authorization policy. This handler must be executed after the above PrincipalFromBasicAuthenticationOperationHandler, in order to receive the user’s identity.

On startup, the WCF runtime uses the input and output handler information (via the OnGetInputParameters/OnGetOutputParameters methods) to compute a permutation of the configuration order that satisfies the input-output dependencies. If such an order doesn’t exists, an exception is throwed when the service starts.

The following diagram illustrates these dependencies.

Configuration

The operation handlers can be configured via an operation handler factory, as the one showed in the next code excerpt

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 the following:

• The call to the base.OnCreateRequestHandlers, so that the built-in handlers are also included in the collection.
• The conditional addition logic, using service description information from the ServiceEndpoint and from HttpOperationDescription: the PrincipalFromBasicAuthenticationOperationHandler is only added if the operation requires an IPrincipal and the binding is using HttpClientCredentialType.Basic.

External resources

Finally, here are some interesting references about message handlers:

• A response operation handler for JSONP support, by Alexander Zeitler.
• Configuring your WCF APIs, by Pablo Cibraro.
• Message Handlers vs Operation Handlers which one to use?, by Glenn Block.

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

• Elementary programming model
• Self-hosting
• Self-hosting, HTTPS and HTTP Basic Authentication
• IIS Hosting
• HTTP Message Classes
• Processing Architecture
• HTTP Content Classes

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.

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.

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

• Elementary programming model
• Self-hosting
• Self-hosting, HTTPS and HTTP Basic Authentication
• IIS Hosting
• HTTP Message Classes
• Processing Architecture

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.

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.