How About IoC?

The code examples can be found here. Do what you will with it, but as always, no warranty for you!

Sweet sweet abstraction. Its a pretty powerful thing, right? From a clients perspective everything is nice and tidy, while all of the nasty not so pretty details are tucked away under the covers. And as we all know, in statically typed languages, the king of abstraction is the mighty mighty interface. But it might surprise you, that with the ASP.Net Web API,  you cannot use interfaces as parameters to your action methods (say what!!!!!). To be fair, if you think about it, it actually does make sense. After all, how can model binders and formatters possibly know what concrete type you want when they encounter an IFoo interface at run-time. In fact, if you try it, the formatters wont even try, resulting in a lovely null reference exception somewhere down the stack. So if you wanted to do something similar to the code snip below, you are out of luck my friend.

using System.Web.Http;
using WebApiInterface.Models;

namespace WebApiInterface.Controllers
{
    public class FooController : ApiController
    {
        public void Post(IFoo foo)
        {
            //Do some stuff to foo
        }
    }
}

So why doesn’t this work? Again, because the JSON formatter cannot determine the desired run-time type of IFoo you want, it simply skips it. And as a result, you will be left with null. Like I said, its very sad, but it makes sense.

So, what can we do to support this? 

At first glance it may seem like simply plugging in some good ol’ inversion of control might be the answer. After all IoC fixes everything, right? For those of you not familiar with some of the extension points of the Web API, let me explain how leveraging IoC might help. In the Web API’s Global Configuration there is a DependencyResolver property exposed.

GlobalConfiguration.Configuration.DependencyResolver

By setting this configuration option to an IoC enabled dependency resolver, we can control how the Web API resolves dependencies. So for example, when the Web API creates our controllers and it comes across an interface parameter, we can tell it to look in our IoC container for the run-time type bound to the specified interface. This is very useful for injecting a UnitOfWork a Service or any other object we need in our controller. While this is a great first step, it does not directly help us with our desire to have interface types as action parameters.  But it is a very important first step, so lets take a look at how we plug IoC into the ASP.Net Web API

Setting Up IoC

OK, let me first say that I know most of the cool kids hate on Unity. But hey, I don’t wear skinny jeans, I still have a PC, and I have grown used to the judgmental glares I get at my local coffee shop as I proudly play with my windows phone. That said, for simple no frills IoC support I still think its a really nice option. So with some help from the great NuGet package we are going to set up our Web API to use unity as our dependency resolver. First run the NuGet package, here are some details on the set up. Once Unity is set up, we need to configure our container like so.

namespace WebApiInterface
{
    public static class UnityConfig
    {
        public static void RegisterComponents()
        {
	    var container = new UnityContainer();
            container.RegisterType<IFoo, Foo>();
            GlobalConfiguration.Configuration.DependencyResolver = new UnityDependencyResolver(container);
        }
    }
}

Nothing too fancy, just a simple registration stating that when a controller constructor asks for an IFoo, it should get an instance of  type Foo.  Additionally, you can see  that I am setting the DependencyResolver configuration option I mentioned above to the a new instance of the UnityDependencyResolver supplied by the Untiy.WebApi Nuget package. This is what does the actual work of resolving the object instances from the container. With these changes our IoC configuration is ready to go. And god willing, when our controllers are created any dependencies they declare will be resolved by way of our unity container.

We have a Foo Instance!

And there it is.

But What About Our Action Methods

While setting up IoC this way works great to resolve interface types when our constructors ask for them.  It does nothing to help us in our action methods. The image below shows an http post to our Foo controller. As you can see we end up with a null, not a Foo.

No Foo 😦

 

 

Custom Creation Converter

OK so how can we leverage our IoC container setup to resolve interface types in our action methods. As it turns out, for that we need to look for extension points within our configured formatter for a solution.  While the Web API’s Dependency Resolver will help us with constructor injection, it does nothing to help us with our action methods. For that we need something a a little different.

For those of you who want a wonderful explanation of model binding and formatters: read this, its a great article.

Looking at our problem it turns out that  JSON.Net has one very slick extension option that can help us.  And that is the Custom Creation Converter. Much like our dependency resolver gives the Web API the ability to do constructor injection, Custom Creation Converters give JSON.Net specific instructions on how to create object instances during the deserialization process. So when JSON.Net is walking down our object graph, as it finds interface types, it will look for a configured Custom Creation Converter to delegate the object creation process to. This allows us to explicitly influence how objects are created when specific interfaces are found during the model binding process.

The Custom Converter

Here is the code for our custom creation converter.

 public class FooCustomConverter : CustomCreationConverter<IFoo>
    {
        public override IFoo Create(Type objectType)
        {
            return new Foo();
        }

        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
        {
            if (reader.TokenType == JsonToken.Null)
            {
                return null;
            }

            IFoo obj = Create(objectType);
            serializer.Populate(reader, obj);
            return obj;
        }
    }

And in order to tell JSON.Net to use this converter we also need to register it. Again we can use the global configuration objects for this.

GlobalConfiguration.Configuration.Formatters.JsonFormatter.SerializerSettings.Converters.Add(new FooCustomConverter());

As you can see there is not much to this at all. First we simply derive from the CustomCreationConverter<T> given to us by the JSON.Net framework. This gives us two methods we need to override. First, the Create method. This method creates a new instance of our Foo object. Second, the ReadJson method. This method is called for us by JSON.Net as it reads each JSON element. There are a few things to note here. We want to return null when the token type is null. This happens when no value is supplied for the JSON element. If the token type is not null, we call the Create method to create the new Foo object. Then we use the supplied serializer instance to map the JSON bits into the new Foo object by calling the populate method. And last we return the newly created and mapped object so JSON.Net can add it to the object graph that is being created.

All and all this is pretty simple, but this design has some very serious flaws. For one, it would required a CustomCreationConverter for every interface type you want to support, boo. Secondly since our converters are not using IoC, if we want to support multiple derived types, that logic needs to be put into the converters somehow, booooooooooo.  So, lets tighten up our implementation so both of those problems go away.

Enter The IoC Custom Creation Converter

Since we have IoC all ready wired up, it is possible to create a single CustomerCreationConverter to service all of our needs. Notice in the code below, that in our override of the ReadJson method  JSON.Net is kind enough to supply us with the type information for each object it is trying to deserialize. This information is precisely what we need to delegate object creation to our unity container. Lets take a look at what this might look like.

public class IocCustomCreationConverter<T> : CustomCreationConverter<T>
    {
        public IocCustomCreationConverter() { }

        public override T Create(Type objectType)
        {
            return (T)ServiceLocator.Current.GetInstance(objectType);
        }

        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
        {
            if (reader.TokenType == JsonToken.Null)
            {
                return null;
            }

            var obj = Create(objectType, reader, serializer);
            serializer.Populate(reader, obj);
            return obj;
        }
    }

As you can see, we did not have to change the code very much. In fact the only major change is in the Create method. Here we ask the container (via the service locator) to create the object instance for us, as opposed to us manually ‘newing’ up the object. We are using the ServiceLocator pattern so we do not need direct access to the container in our JSON serilaizer.  If you are not familiar with the ServiceLocator pattern, here is a quick primer on it. Now that we have our IoCCustomerCreationConverter ready to go we need to register this with JSON.Net with the simple one-liner below.

GlobalConfiguration.Configuration.Formatters.JsonFormatter.SerializerSettings.Converters.Add(new IocCustomCreationConverter<IActionParameter>());

One thing you might notice here is that I am registering the custom creation converter to only work with types that derive from IActionParameter. This is not required but there are some things that we may not want to use our Custom Creation Convert for. For primitive types such as an int or bool, it does not make any sense to ask JSON.Net to use a custom converter. So by using this simple marker interface we can control what types are actually resolved using our new converter.

Wrapping Up

So there you have it! By configuring IoC and adding a single JSON.Net Custom Creation Converter, we are now able to abstract the parameters to our action methods. This is great for testability, as well as creating APIs that may need to serve multiple clients with varying data structures. And that is a pretty cool thing!

BDN

 

 

Web API and Interface Parameters

Securing The ASP.NET Web API

A question I get over and over again when presenting on the ASP.NET Web API is, “How does Authentication and Authorization work in the Web API?” This seemingly simple question is actually one of the most complex aspects of the Web API; largely because the framework ignores any formal support for it. Sure, we have the AuthorizeAttribute, but as we’ll see, this has many limitations that prevent it from being a viable option. We can rely on a hosting environment such as IIS, but this also has its limitations. At the end of the day, to address security, we as service developers need to get our hands dirty and do some actual work. The trouble is that, with a plethora of approaches out there, navigating the topic gets overwhelming very quickly. As such, my modus operandi for this blog series is to present and demystify some of the common options available. I will not cover all of them (that would take a book or twelve), but I will cover the most common solutions to the problem. The intention is to give the .NET community what I wished I had when I started working with the ASP.NET Web API.

So for all of the folks out there who have asked me about the Web API’s security model and been given sub-par explanations, I hope this blog series can help clear up some of the confusion for all of us!

What the Series Will Cover

From a bird’s eye view, the list below outlines the concepts this series will cover. The truth is, one could write a blog series on these concepts individually;  but, I will attempt to distill the information in a way that is practical and still covers the essential aspects of each topic.

1. AuthorizeAttribute
2. Basic Authentication
3. Digest Authentication
4. Security Token Services
5. OAuth and OpenID

Security Primer

When looking at the topic of application security, there are many factors involved. Depending on your situation, your idea of secure may be different from someone else’s. For example, the security demands on a banking system will likely be much more stringent than that on a reservation system for a hair salon. That being said, I do want to review the core concepts involved in system security. If you find yourself hungry for more; a much more in-depth summary can be found here.

1. Confidentiality – Ensuring that only those intended to have access to your data can gain access to it.
2. Integrity – Ensuring accuracy of your data
3. Authenticity – Ensure that both parties involved in a transaction are who they say they are

There are several other concepts involved such as Non-repudiation and Availability. However, I am going to focus on what I consider the core concepts and what is most often needed when building a system.

Part 1 – Moving Towards Basic Authentication

The code examples can be found here. Do what you will with it, but as always, no warranty for you!

The ASP.NET Web API does very little address to the security story. For better or worse it is not addressed. Much of the documentation and examples out there show the usage of the AuthorizeAttribute, or the heavy reliance on IIS to manage Authentication and Authorization. In Part 1 of this series, we will explore why the AuthorizeAttribute falls short, and how we can make some minor enhancements to our API to move to the HTTP Basic Authentication Standard. So, with introductions out of the way, let’s get started!

Your Friend/Foe – the AuthorizeAttribute

Oh… if only the security story was as easy as adding an attribute to your controller actions, what a great world it would be. It would also be nice if we did not need to worry about security. Unfortunately, both of these niceties are a pipe dream. For now let’s play the devil’s advocate and take a quick look at how the AuthorizeAttribute works. Then we can talk about why you should never use with a production grade service.

Using the AuthorizeAttribute is very simple. As with its MVC counterpart all you need to do is decorate your action method or controller class with it and BAAAM! Now you have security. Let’s look at a quick example.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace WebAPIAuth.Controllers
{
    public class TestController : ApiController
    {
        [Authorize]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }
    }
}

By simply adding this attribute to your action method, any unauthenticated requests to our Web API will reply with a HTTP 401 (unauthorized) response. Take a look at the request below to the TestController.

Pretty slick right? Well, not so fast. Though this is simple enough to implement, there are several serious limitations to doing things this way. The central problem with this approach is the underlying mechanism it uses to do its work. Both the ASP.NET Web API’s AuthorizeAttribute and its MVC counterpart rely on  Forms Based Authentication to authenticate incoming requests. In Forms Based Authentication, cookies are used to transport the authentication ticket between client and server. Not only does the use of cookies add state to our services that should be stateless, they also limit the potential set of clients to only those that understand how to work with them. This limitation is unacceptable in today’s landscape with such a disparate set of potential clients. From an architectural stand point, there are additional concerns to consider. Chief among them that the AuthorizeAttribute deals only with Authorization. For Authentication, it relies on the ASP.NET Pipelines FormsAuthenticationModule. Therefore, unless you are using it in conjunction with an ASP.NET application you really cannot rely on this approach at all. From a security standpoint let’s look at how this approach holds up to our security concepts.

Does it support Confidentiality?

No. Any servers between a request and your Web API would be able to see the content of the request and response.

Does it support integrity?  

No. It does nothing to ensure that data has not been tampered with by the time a request reaches your Web API.

Does it support Authenticity?

At some level this is supported. The authentication ticket is passed from client to the server via cookies. However, these kinds of ad-hoc implementations are inherently susceptible to phishing and unless some sort of transport security is used in conjunction with cookies, credentials are sent across the wire in clear text.

To sum it up, because the AuthorizeAttribute relies on Forms Based Authentication, we cannot and should not ever use it to secure our Web API.

Basic Authentication

So now that we know using Forms Based Authentication is a non-starter, the next thing we can consider is Basic Authentication. Basic Authentication is a very attractive option since it is part of the HTTP standard. Moreover, as the name states it is a very simple form of authentication. Let’s quickly outline the steps involved in Basic Authentication.

1. Client makes a HTTP Request to a protected resource
2. Server responds with the HTTP 401 (unauthorized) status code. The response should also contain the ‘WWW-Authenticate’ header
3. The presence of the ‘WWW-Authenticate’ header indicates to the client that authentication is required
4. Client makes the same request passing along the credentials in the ‘authorization’ header
5. Server authenticates the user using the supplied credentials
6. Server authorizes that the user has access to the request resource
7. If the user is authorized the resource is returned to the client, if not an HTTP 401 (unauthorized) is returned

Here is a simple sequence diagram outlining Basic Authentication from one of my favorite tools.

This simple approach does not require cookies, session, or any other type of state to be managed by our Web API. However, there are some concerns worth noting here. First, because our Web API is supposed to be stateless, Basic Authentication requires the client to send its credentials with every request. This forces the server to authenticate and authorize each request, potentially introducing some unwanted overhead depending on how your application does these things. Secondly, Basic Authentication does nothing to protect the credentials being sent across the wire.  Looking at the example of the authorization header below; you may be led to believe that there is some sort of encryption going on, I assure you there is not.

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

The value of the Authorization header may look encrypted, but it is actually the name and password encoded in Base64. This means the clients credentials are essentially sent to the server in clear text. For Basic Authentication to be viable at all, we must always use it in conjunction with some form of TLS (think SSL all the time).  Let’s take a look at how we might implement Basic Authentication with the ASP.Net Web API.

Basic Authentication Implementation

The first instinct one may have for an implementation might be to roll your own AuthorizeAttribute. This attribute can then be applied to any actions that you want to protect. But from a  Separations of Concerns (SoC) perspective, Authentication and Authorization are completely different animals. Authentication focuses on identifying the user, Authorization focuses on what the user can do in a given system. Having an action filter responsible for both concepts goes against most core object-oriented principles. Even more troubling is how close to your action method the Authentication and Authorization would happen. If we wait until the request makes its way to an Action Filter before even Authenticating the user, a malicious request could make its way much deeper into our call stack than is comfortable. Think of it this way. Is it better lock only your bedroom door while you are sleeping, allowing burglars to make their way into your house, up the stairs, only to be stopped at your bedroom door? Of course not! A more reasonable approach would be to lock all the doors of your house, so burglars cannot intrude in the first place! Similarly, we should reject all unauthenticated requests as soon as possible, limiting the potential damage a malicious request could cause. This is where the Web API’s Message Handlers come in handy. Message Handlers are executed very early in the life cycle of the request/response pair. Message Handlers receive requests when they come in as well as the responses before they are sent back. This allows Message Handlers to inspect and reject a request before it makes its way to our controllers. Message handlers are chained together, much like a linked list, where one handler passes the request to the next. Once the last handler is executed the response is processed much the same way but in reverse. The image below illustrates the ‘pipeline’ style architecture of Message Handlers.

By creating a custom message handler to manage Authentication we can inspect the request as well as alter the response, but better yet, we can do it at a very early stage of the request/response life-cycle.  Let’s take a look at how we might implement this.

The Message Handler

using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading;
using System.Threading.Tasks;
using System.Web;

namespace WebAPIAuth
{
    public class AuthenticationMessageHandler : DelegatingHandler
    {
 protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request
 , System.Threading.CancellationToken cancellationToken)
        {
            if (request.Headers.Authorization != null
                && request.Headers.Authorization.Scheme.Equals("basic", StringComparison.OrdinalIgnoreCase))
            {
                var credentials = request.Headers.Authorization.Parameter.Split(':');

                //Look up user
                var user = new UnitOfWork().Users.GetByCredentials(credentials[0], credentials[1]);
                if (user != null)
                {
                    HttpContext.Current.User = user.ToClaimsPrincipal();
                    Thread.CurrentPrincipal = HttpContext.Current.User;
                }
            }

            var httpResponse = await base.SendAsync(request, cancellationToken);
            if (httpResponse.StatusCode.Equals(HttpStatusCode.Unauthorized))
            {
                httpResponse.Headers.WwwAuthenticate.Add(new AuthenticationHeaderValue("basic"));
            }

 return httpResponse;
        }
    }
}

This simple message handler does everything needed to support Basic Authentication.

1. It checks the request for the presence of the Authorization header.
2. If found it parses the header and extracts the username and password.
3. It then looks up the User based on those credentials, converts the User to a Claims Principal and finally assign it to HttpContext.Current.User and the Thread.CurrentPrincipal.
4. From there it passes execution to the next handler.
5. Once the response comes back it checks the response HttpStatusCode for a 401 (unauthorized) status. If the response is a 401 we add the ‘WWWAuthenticate’ header to indicate to the client that they need to supply their credentials.

One last thing worth mentioning is the use of the ToClaimsPrincipal extension method. This extension method converts our User object into a ClaimsPrincipal object.  Click here for more information about Claims Based Authentication. The code for this is very straight forward. The only thing we are doing here is creating a ClaimsPrincipal object and adding a few claims to its claims collection.

using System.Collections.Generic;
using System.Globalization;
using System.Security.Claims;
using System.Security.Principal;
using WebAPIAuth.Models;

namespace WebAPIAuth
{
    public static class UserExtensions
    {
 public static IPrincipal ToClaimsPrincipal(this User user)
        {
            var claims = new List<Claim>
                {
                    new Claim("UserName", user.UserName),
                    new Claim("UserId", user.Id.ToString(CultureInfo.InvariantCulture)),
                    new Claim(ClaimTypes.Role, user.Role),
                };

            var claimsIdentity = new ClaimsIdentity(claims, "Basic", "UserName", ClaimTypes.Role);
 return new ClaimsPrincipal(claimsIdentity);
        }
    }
}

Now that our message handler is ready, we need to make sure it is executed for each request. To do this, you need to add the following configuration to your WebApiConfig.cs.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace WebAPIAuth
{
    public static class WebApiConfig
    {
 public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );

            config.MessageHandlers.Add(new AuthenticationMessageHandler());
        }
    }
}

With the message handler intact, it will now handle Authentication for us. However, that is not the entire story; we still have the matter of Authorization. Thankfully for that problem we can still rely on the AuthorizeAttribute as it is. When a request reaches our action method, the AuthorizeAttribute will look for an authenticated principal on the current thread. If the principal is present and authenticated, the next step is user authorization. If the current principal is authorized to access the requested action, the action will be executed, and the result return to the client. On the other hand, if there is no authenticated user present, or the user does not have access to the requested action a HTTP Status 401 (unauthorized) will be returned.

In Action

With all of the moving parts ready to go, let’s take a look at this approach in action.

The First Request

The first thing we will do is make a HTTP Request for a protected resource. We will not include our credentials in the authorization header to get a HTTP Response with a status code of 401 (unauthorized).

Looking at the highlighted lines above you can see the request to the protected resource and the 401 (unauthorized) response that was returned. You also can see that the ‘WWW-Authenticate’ header was included. This tells the client that credentials are required.

The Second Request

When clients receive a 401 (unauthorized) response, they can send an additional request, one that contains the authorization header and the credentials of the user making the request. Let’s look at an example of this.

With the presence of the Authorization header complete with the user’s credentials, the user can be authenticated, and all is well with the world.

Wrapping Up

In part one of this series, we looked at a few different things. We looked at the limitations of the AuthorizeAttribute and its reliance on Forms Based Authentication. We looked at how we can support Basic Authentication in our Web API’s. Although Basic Authentication is a very attractive solution because it is both simple, and part of the HTTP standard, it does have some limitations. First and foremost because it offers no type of transport layer security using it without SSL is a not an option. If you are going to use basic authentication, make sure you do it in concert with SSL. Another area of concern is that the credentials are sent to the server with each request, which creates a potential for additional processing overhead. Finally, if your browser caches these credentials, there is some risk of Cross Site Forgery attacks. Even with these limitations, Basic Authentication is the first step to a much more secure Web API. We will take this implementation much further in Part 2 of this series, where we will take a look at Digest Authentication. Digest Authentication is very similar to Basic Authentication, but it is substantially more secure. The additional security precautions of Digest Authentication address most of the concerns that arise from Basic Authentication.

Until next time keep your services safe!

BDN

The Tale of the ASP.NET Web API

As most of you probably know, with the drop of the of the MVC 4 Framework Microsoft introduced us to a shiny new framework called the ASP.NET Web API. Anytime new frameworks come out open source or otherwise, you have to ask yourself a few important questions.

What?

The first and most obvious question we need to ask is “What the heck is this new framework?”.  In the case of the ASP.NET Web API this is a pretty simple question to answer. The ASP.NET Web API is now the recommended approach for developing HTTP based services and REST based services in the .NET stack. See it’s simple!

Why?

Secondly, and more importantly, is the question “Why did the create this framework?”. After all, we have WCF; we have MVC; so why introduce another framework into an area that is already a bit confusing?

An Illustration of Pain

To help illustrate why this framework was introduced, I would like you to look at a few images. While looking at them ask yourself a question. Why are these people feeling so much pain? What is it that is making them look miserable?

Our Distressed Woman

Frustration

Anger

 

So what is going on here? What is it that’s making these folks so angry? As I look at these pictures, this is the story that plays out in my mind.

The Story

This is a group of .NET developers, who for the last three years have been working on a suite of REST based services, but because of the corporate standards of the company they work for they have been forced to do this using WCF. So for the greater part of three to four years, these people have been fighting against a technology that was not necessarily designed to solve the problems they were facing.

HTTP + WCF = 😦

Now I don’t mean any disrespect to WCF. But the truth is that from its inception and from the ground up, WCF was designed with SOAP based web services in mind. It was developed to be highly scalable, highly pluggable, highly configurable as well as any other ‘able’ you can think of. It was also designed to work across multiple transport protocols be it TCP/IP, Named Pipes and most recently even HTTP. All this is extremely powerful stuff  if it is what you want. However,  if what you need is a simple HTTP service to send data to, or to obtain data from, the WCF development experience starts to feel heavy, its hard, its complicated and honestly just not much fun. Thankfully, Microsoft acknowledged this, and as HTTP services became more prevalent they took steps to make things easier on us.

The WebHttpBinding

Enter .NET 3.5 and the introduction of the WebHttpBinding. For the first time,  WCF developers could now expose their WCF services as HTTP end points. A step in the right direction? Absolutely.  However, it did not quite go far enough. Relegating HTTP to more of a transport protocol as apposed to application protocol the WebHttpBinding was more a way to transfer data from one server to another then it was anything else. But the HTTP semantic is much richer than just a transport protocol.  We have things like caching, etags, and many other things that have become more and more important as HTTP services have taken over the service landscape. And its these things that HTTP service developers need to be able to target when building their services. So was the WebHttpBinding  a step in the right direction? Yes. But unfortunately for us it did not go far enough.

The Rest Starter Kit

Next we got something called the Rest Starter Kit. I never actually got to work with this;  however, I have read that it was actually well received by many. However as it is with many things from Microsoft the Rest Starter Kit never made it past the community preview, and as such is just a blip in the .NET history book.

The WCF Web API

The WCF Web API, the third and final attempt to build on top of WCF strong support for HTTP based services. In all fairness to the WCF team,  this was a giant leap in the right direction. We started to see a convention a based approach opposed to the massive WCF configuration files. We were given a nice client to interact with our services, and we even started to see the support for content negotiation. However, this all fell into a category of a too little and too late. .NET developers frustrated with the lack of support for HTTP based services and with open source solutions available, things like OpenRasta, and Service Stack, .NET developers had moved on. Some of the savvier .NET folks even started to build their HTTP services on top of MVC, and even this approach proved to be more straight forward than using the latest WCF Web API.

What To Do

At this point,  Microsoft found themselves in a bit of a precarious position, and they had to make a choice. Do they continue to push WCF into a box it was never intended to fit into or do they stop, look around at the community, and create something directly targeted at the problem of HTTP based services and REST based services. Thankfully for us they chose the latter. And with the release of Visual Studio 2012 and MVC 4 we were given the brand new shiny ASP.NET Web API.

Taking the good from the WCF Web API, and what they have learned form the MVC stack. They created a new framework that brings a slew of desirable features.

Modern

A much more modern HTTP programming model. Largely convention based, Asynchronous from top to bottom, we have a really nice HttpClient to interact with our services, and quite frankly it just a lot of fun to work with.

MVC

Because the ASP.NET Web API is based on top of the MVC framework we get a lot of the magic that exists in the MVC stack. Things like routing, action filters, model validation and of course the added benefit of the development experience feeling very much at home if you are already a MVC developer.

Content Negotiation

As service developers,  we need to be cognisant of the types of data our clients want to work with. Maybe they want XML maybe they want JSON out of the box the ASP.NET Web API supports both. And of course the extensions points are there if you want to create your custom media type, or use something RSS or ATOM.

OData

If you want to expose your HTTP service to URI based queries, there is OData support for that, and it gets better all the time with the ongoing nightly builds.

Testable

And last but not least the framework is testable. If any of you remember how hard it is to unit test, and integration test WCF services, you will understand why this is such a beautiful thing. Built with testability in mind from top to bottom it is one of the most testable frameworks in all of the .NET stack.

Why HTTP?

The last thing I want to address is a question I was first asked when I presented this topic at MDC last year. Someone in the audience asked ‘Why so much emphasis on HTTP, is there something wrong with SOAP based services?’

The answer to that question is simple. There is nothing wrong with SOAP based services. However, in the gadget landscape of today, many devices know how to work with HTTP natively. Far less understand the different abstractions that sit on top HTTP, such as SOAP. So it should not surprise anyone  that HTTP based services are the new standard.

Does this mean SOAP and WCF are dead? No, not at all. WCF and SOAP just solve different problems. If you need to work with multiple transport protocols, or if you need WS-* style security WCF is still the king. Where the ASP.NET Web API shines, is in the space of HTTP. So in short, each solves a different problem, and each solves does it exceptionally well.

-BDN

ASP.NET WEB API Validation (A One More Better Approach)

Before We Start

This post is based on the nightly builds of the ASP.NET Web API. The Web API team is constantly making improvements to the framework, and publishing them with nightly builds on NuGet. Click here for more information on getting setup with the nightly builds, there is a lot of exciting things in them.

I would also like to extend a giant thank you, to Youssef Moussaoui over at Microsoft for fixing the following defect. Without this fix,  the IValidatableObject support outlined in this post would be much more difficult. So thanks Youssef!

And finally, to get the source code for the sample application ‘ResIt’ outlined in this post, click here. And as always no warranty for you!

Background

If you ask me what the most difficult aspect of Business Application Development is, I will say, quickly and confidently, validation! Add to the mix a distributed architecture like Http, and you have the makings for a real bugger of a problem. With rules on the server, rules on the client, and a pile of plumbing code in between, there is a plenty of opportunity for things to get mucked up. Yet, despite all of this complexity, we still need to  provide the user a reasonable validation experience.

So all together now…Validation is hard!

With the ASP.NET MVC Framework we were given lots of fancy tools to help support the validation story. Of course,  we got all kinds of DataAnnotation support, and with MVC 3 we were given another option with the added support for the IValidatableObject interface.  But what does this have to do with the ASP.NET Web API? Well, as it turns out it has a lot to do with it. Because the ASP.NET Web API is build on top of the MVC framework the Web API can take advantage of many of the features that we all know and love in the MVC stack.  Things like Action Filters, Routing, and of course all of the goodness that is Model Binding.

Model Binding Review

For a detailed description of Model Binding please look here. For now, here are the Cliff Notes. Model Binding is how form, querystring, and any other type of data coming in via the Http Request gets converted into the CLR types defined as the input parameters to our action methods. This magic allows us to work with typed .Net objects in our actions, as opposed to developers having to interrogate the HTTP Request directly. And this is my friend is a marvellous thing! Oh, but there’s more! Not only does Model Binding handle the nasty right to left mapping between the incoming HTTP Request and our .Net types. Model Binding validates our model using Model Validation, and it’s this part of the MVC stack that we are interested in, at least for this post.

Model Validation is the process where the framework takes our objects already created by Model Binding  and inspects their properties for any DataAnnotations. If  found, the Validate method of the each DataAnnotation is executed. This process then invalidates any objects that don’t meet the business rules as defined by the supplied DataAnnotation. So why is this relevant to the Web API? Simply put, because the Web API has complete Model Binding and  Model Validation support, any of the techniques we use for validation in  MVC is fair game. This includes both DataAnnotations and the IValidatableObject interface.

Boo To You Mr. Data Annotation

Generally speaking, I am not a fan of the ever so popular attribution method of validation.  First of all they tend to break down as soon as something difficult arises. Secondly, they are not terribly explicit, and out of sight out of mind, right? Thirdly, and most importantly, I have never been able to figure out how to use the hooks for client validation when creating custom validators (Just can’t find the energy to do it). I will admit that in the context of ASP.NET MVC DataAnnotations do have one tantalizing benefit with the added JavaScript support (sometimes). However, with the ASP.NET Web API that benefit does not actually exist, after all we are not returning markup and JavaScript to the client, we are returning resources formatted in JSON or XML. With the absence of the JavaScript benefit,  I assert that DataAnnotations make validation harder when working with the Web API, and as such, I avoid them as a rule.

One More Better Validation

The technique I am going to outline here is one that I have used  successfully in several projects. It leverages one of my favorite open source frameworks, Fluent Validation, coupled with the WEB API’s  support for the IValidatableObject interface. Using Fluent Validation, we will make individual validators for each our domain objects. These validators are both explicit and testable, both traits that get two thumbs up from me. Combing these validators with the Web API support for the IValidableObject interface, we will create what I consider a pretty slick solution to the validation problem.

How It Works

Before we get into the dirty details, let’s talk  about the sequence events we are going to look at.

1. Using JQuery, we send an invalid HTTP Post Request to our Web API
2. Model Binding does its thing, converting the request into a Reservation object
3. Model Validation honors the IValidatableObject contract, calling the Validate method of our Reservation object
4. The Validate method delegates to our Fluent Validator, invalidating the Reservation object
5. Our WEB API returns an HTTP Response, with a Status Code 400 (bad request) back to the client, along with a list of error messages
6. jQuery unobtrusive will then render these errors to the screen

This image below illustrates the sequence of events using a  super slick tool.

Basic Validation Sequence

Our Sample Application

Before we get into the meat of this example, I want to introduce to you our sample application. Our sample application is a fictional Reservation web site called ‘Resit’. Resit is a simple application, it consists of a single screen, that allows users to add reservations. In addition to the screen, we also have a Web API that will be responsible for the validation of our models and any data access required. Finally, we have a single domain object named Reservation. The Reservaion object  implements the IValidatableObject interface and leverages Fluent Validation to execute any validation rules that may be needed.

The View

Our view is nothing more than a simple Html form with the following fields.

1. First Name
2. Last Name
3. Reservation Date

It looks a little something like this (yeah I know it is not real purty!)

Not a Picasso

Not much going on here, just a simple HTML form taking advantage of the boilerplate MVC look and feel. Oh, and of course, the very ugly HTML 5 control that is rendered for dates automagically. Lets take a look at the code for the view.

@model BetterValidation.Models.Reservation
@{
    ViewBag.Title = "ResIt!";
    Layout = "~/Views/Shared/_Layout.cshtml";
}
<header>
    <div class="content-wrapper">
        <div class="float-left">
            <p class="site-title">
                <a href="~/">ResIt</a>
            </p>
        </div>
    </div>
</header>
<div id="body">
    <section class="featured">
        <div class="content-wrapper">
            <hgroup class="title">
                <h1>Welcome To ResIt!</h1>
                <h2>A generally useless reservation system</h2>
            </hgroup>
            <p>
                ResIt allows you to create a reservation. Your reservation will not be saved to any kind of database. You will not be
                able to edit your reservation. But you will be able to see validation messages. 🙂
            </p>
            <p>
                To learn more about FluentValidation Visit
                <a href="http://fluentvalidation.codeplex.com/" title="FluentValidation">FluentValidation</a>.
                <br />
                <br />
                To learn more about Me Visit <a href="http://www.brette.net" title="Brette.Net">Brette.Net Consulting</a>.
            </p>
        </div>
    </section>
    <section class="content-wrapper main-content clear-fix">
        <h2>Create A New Reservation</h2>
 <form id="createReservationForm">
            <fieldset>
                <legend>Reservation</legend>

                <div class="editor-label">
                    <label class="required" for="FirstName">
                        First Name</label>
                </div>
                <div class="editor-field">
                    <input class="text-box single-line" id="FirstName" name="FirstName" type="text" />
                    <span class="field-validation-valid" data-valmsg-for="FirstName" data-valmsg-replace="true" />
                </div>
                <div class="editor-label">
                    <label class="required" for="LastName">
                        Last Name</label>
                </div>
                <div class="editor-field">
                    <input class="text-box single-line" id="LastName" name="LastName" type="text" />
                    <span class="field-validation-valid" data-valmsg-for="LastName" data-valmsg-replace="true" />
                </div>
                <div class="editor-label">
                    <label class="required" for="Date">
                        Date</label>
                </div>
                <div class="editor-field">
                    <input class="text-box single-line" id="Date" name="Date" type="date" />
                    <span class="field-validation-valid" data-valmsg-for="Date" data-valmsg-replace="true" />
                </div>

 <input type="button" id="cancelButton" value="Cancel" />
 <input type="submit" id="saveButton" value="Save" />
            </fieldset>
        </form>
    </section>
</div>
@section scripts{
    <script type="text/javascript">
 $('#createReservationForm').submit(function (submitEvent) {
            submitEvent.preventDefault();
            var form = $('#createReservationForm');
            $.validator.unobtrusive.parse(form);
            if (form.valid()) {
                $.ajax({
 url: "api/Reservation/Create",
                    data: $("form").serialize(),
                    type: "POST",
 statusCode: {
                        200: function () {
 clearErrors($('#createReservationForm'));
                            alert("You created a reservation");
                        },
                        400: function (response) {
 var validationErrors = $.parseJSON(response.responseText);
 $.each(validationErrors.ModelState, function (i, ival) {
 remoteErrors(form, i, ival);
                            });
                        }
                    }
                });
            }
        });
    </script>
}

The Form

The first thing you will notice is the presence of our Html form. A simple little form that contains the inputs for the First Name, Last Name, and Date. Additionally we also have included the data-attributes  required to support jQuery validation. Finally, you will see the empty span element that will eventually render our error messages sent back from our Web API.

The JavaScript

Of course,  no html form is complete without a bunch of messy JavaScript at the bottom of the screen, and this form is no exception! Looking at the JavaScript, we are really only doing a few things. First, when the form is submitted I use JQuery to make an Ajax HTTP Post Request to our Web API. With it, I send along the serialized form data. If the HTTP Response comes back with a HTTP Status Code 200 (OK), I pop up a very visually pleasing alert dialog, indicating that the reservation has been created. If, however, the HTTP Response from the server  has a HTTP Status Code 400 (Bad Request), I do a few additional things. First, I parse the responseText converting the returned JSON into a living and breathing JavaScript object. I then iterate over the errors in the Model State calling the remoteErrors method (more on this later). For now just know that the remoteErrors function is responsible for rendering the error messages to the screen.

Reservation Object

Next lets talk briefly about our Reservation object. This is not very exciting containing only a few properties (FirstName, LastName, Date) however one important thing to notice is that it implements the IValidatableObject interface. And if you remember our conversation about Model Binding you will know that both the the MVC framework and the Web API honor this contract when running through the Model Validation process.

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using BetterValidation.Extensions;
using FluentValidation;
using ValidationContext = System.ComponentModel.DataAnnotations.ValidationContext;

namespace BetterValidation.Models
{
    ///
    /// Simple Domain Object
    ///
    public class Reservation : IValidatableObject
    {
        #region Private Members

        private readonly IValidator _validator;

        #endregion

        #region Properties

        ///
        /// Gets or sets the date time.
        ///
        ///
        /// The date time.
        ///
        public DateTime DateTime { get; set; }
        ///
        /// Gets or sets the name.
        ///
        ///
        /// The name.
        ///
        public string FirstName { get; set; }
        ///
        /// Gets or sets the name.
        ///
        ///
        /// The name.
        ///
        public string LastName { get; set; }

        #endregion

        #region Constructor

        ///
        /// Initializes a new instance of the  class.
        ///
        public Reservation()
        {
            _validator = new ReservationValidator();
        }

        #endregion

        #region IValidatableObject

        ///
        /// Determines whether the specified object is valid.
        ///
        ///The validation context.
        ///
        /// A collection that holds failed-validation information.
        ///
        ///
        public IEnumerable Validate(ValidationContext validationContext)
        {
            return _validator.Validate(this).ToValidationResult();
        }

        #endregion
    }
}

IValidatableObject gives us a single method aptly name Validate. This method takes in a ValidationContext object, and as you can see simply delegates to our ReservationValidator (a Fluent Validator) object. During Model Validation,  the Web API will call this method on any object that implements this interface giving us a chance to run any validation rules for each object as its Model Bound.

Reservation Validator

This class represents all of the business rules for our Reservation object. Notice that it derives from the AbstractValidator<T> class. This class is one of the base classes available to us from the Fluent Validation framework. The only other interesting thing here is the rule definitions in the constructor of our validator. Notice I create two rules, the first, requires the FirstName property to be valued, and the second, requires the LastName to be valued.

using FluentValidation;

namespace BetterValidation.Models
{
    public class ReservationValidator : AbstractValidator
    {
        ///
        /// Initializes a new instance of the  class.
        ///
        public ReservationValidator()
        {
            RuleFor(item => item.FirstName)
                .NotEmpty();

            RuleFor(item => item.LastName)
              .NotEmpty();
        }
    }
}

The last thing I want to point out here, is a simple extension method I have added to the FluentValidation.Results.ValidationResult type. This extension method simply converts the FluentValidation ValidationResult type to the  System.ComponentModel.DataAnnotations.ValidationResult type that both the MVC and the Web API expect. It’s only a few lines of code, but this is required since the types are actually different.

using System.Collections.Generic;
using System.Linq;
using ValidationResult = System.ComponentModel.DataAnnotations.ValidationResult;

namespace BetterValidation.Extensions
{
    /// <summary>
    /// Extension to the Fluent Validation Types
    /// </summary>
    public static class FluentValidationExtensions
    {
        /// <summary>
        /// Converts the Fluent Validation result to the type the both mvc and ef expect
        /// </summary>
        /// <param name="validationResult">The validation result.</param>
        /// <returns></returns>
        public static IEnumerable<ValidationResult> ToValidationResult(
            this FluentValidation.Results.ValidationResult validationResult)
        {
            var results = validationResult.Errors.Select(item => new ValidationResult(item.ErrorMessage, new List<string> { item.PropertyName }));
            return results;
        }
    }
}

So Far

Just a quick recap. So far we have a Simple view with a Html form, a Reservation domain object that implements IValidatableObject, a single Validator object called ReservationValidator. Based on what we now know about Model Binding and Model Validation, we know that when our form is posted to our Web API, Model Validation will call the Validated method on our Reservation object. That method creates the instance of the ReservationValidator, and all the validation rules are executed. The results are converted into the System.ComponentModel.DataAnnotations.ValidationResult object that is eventually stuffed into Model State and streamed back to our client.

Our Web API

The last major component of our validation solution is our Web API,  this is, after all what the post is all about right?

using System.Net;
using System.Net.Http;
using System.Web.Http;
using BetterValidation.ActionFilters;
using BetterValidation.Models;

namespace BetterValidation.Controllers
{
    public class ReservationController : ApiController
    {
        [ValidationResponseFilter]
        public HttpResponseMessage Post(Reservation reservation)
        {
            return Request.CreateResponse(HttpStatusCode.OK, reservation);
        }
    }
}

Looking at the ReservationController,  you know this is our Web API because it derives from ApiController. Our Web API boasts a single Post action; this action takes in an instance of our Reservation domain object, created for us by Model Binding of course. Assuming there are no validation errors, this action  simply streams the reservation back to the client with a HTTP Status Code of 200 (OK), and all is well with the world. However, what happens if the incoming HTTP Request is incomplete, or if it’s invalid? How can we communicate this information back to the client? This brings us to the ValidationResponseFilter that decorates our fancy Post action.

Action Filters a Primer

Just a quick refresher on Action Filters. Action Filters are a terrific way to support cross cutting concerns in our applications. As such, they let us execute code just before an action is executed by overriding the OnActionExecuting method. They also let us execute code just after an action executes by overriding the OnActionExecuted method. This gives us a excellent way to add aspect oriented behavior to any action by simply decorating an action method with an attribute. One important thing to note about the OnActionExecuting method  is that it executed after  the Model Binding process. What this means is, that by the time the OnActionExecuting method is executed, both Model Binding and Model Validation have already run. This results in any validation errors being stuffed into Model State just before our action filter is executed. Using this little tidbit of life cycle knowledge we can do something pretty slick. Enter the ValidationResponseFilter!

ValidationResponseFilter

Looking at the action filter below, notice the implementation of the OnActionExecuting method is checking to see if any validation errors were found. After all, Model Binding has already done its magic, so all errors would be present in Model State at this point. If the Model State is invalid, I ask the HttpRequest object to create for us a special kind of HttpResponse using the CreateErrorResponse method. This overload is special because it actually takes in as an input parameter the Model State information containing all of the validation errors. Using the Model State information, CreateErrorResponse creates an HttpResponseMessage that includes a list of validation messages in such a way that JavaScript frameworks like JQuery can consume them. So by simply annotating a method with this attribute, any validation errors found during the Model Validation process are sent back to the client structure in a JavaScript friendly way.

using System.Net;
using System.Net.Http;
using System.Web.Http.Filters;

namespace BetterValidation.ActionFilters
{
    public class ValidationResponseFilter : ActionFilterAttribute
    {
        ///
        /// Called when [action executing].
        ///
        ///The action context.
        public override void OnActionExecuting(System.Web.Http.Controllers.HttpActionContext actionContext)
        {
            if (!actionContext.ModelState.IsValid)
            {
                //actionContext.ModelState.Keys
                actionContext.Response = actionContext
                        .Request
                        .CreateErrorResponse(HttpStatusCode.BadRequest, actionContext.ModelState);
            }
        }
    }
}

Remote Errors

The last thing I need to touch on, is the  JavaScript method remoteErrors. This method is called when our Web API returns a Http Status Code 400 (Bad Request), and it has a few responsibilities. First, it is in charge of inspecting the Model State errors that came back from the server and locating the related input elements. This is done by parsing the dot path information supplied in Model State, and matching it to the data-valmsg-for data attribute of our input controls. Once found, the correct style is applied, and the error message is placed the span element next to the input control. This approach was inspired from a post I found on stack overflow, you can find it here. I have found this to be a pretty straight forward way to deal with the Model State errors that come back from the server. While I am sure there are a million other ways you can do the same thing, I found this to be clean and simple, so I ran with it.

function remoteErrors(jForm, name, errors) {

    function inner_ServerErrors(name, elements) {
        var ToApply = function () {
            for (var i = 0; i < elements.length; i++) {
                var currElement = elements[i];
                var currDom = $('#' + name.split('.')[1]);
                if (currDom.length == 0) continue;
                var currForm = currDom.parents('form').first();
                if (currForm.length == 0) continue;

                if (!currDom.hasClass('input-validation-error'))
                    currDom.addClass('input-validation-error');
                var currDisplay = $(currForm).find("[data-valmsg-for='" + name.split('.')[1] + "']");
                if (currDisplay.length > 0) {
                    currDisplay.removeClass("field-validation-valid").addClass("field-validation-error");
                    if (currDisplay.attr("data-valmsg-replace") !== false) {
                        currDisplay.empty();
                        currDisplay.text(currElement);
                    }
                }
            }
        };
        setTimeout(ToApply, 0);
    }

    jForm.find('.input-validation-error').removeClass('input-validation-error');
    jForm.find('.field-validation-error').removeClass('field-validation-error').addClass('field-validation-valid');
    var container = jForm.find("[data-valmsg-summary=true]");
    list = container.find("ul");
    list.empty();
    if (errors && errors.length > 0) {
        $.each(errors, function (i, ival) {
            $("<li />").html(ival).appendTo(list);
        });
        container.addClass("validation-summary-errors").removeClass("validation-summary-valid");
        inner_ServerErrors(name, errors);
        setTimeout(function () { jForm.find('span.input-validation-error[data-element-type]').removeClass('input-validation-error') }, 0);
    }
    else {
        container.addClass("validation-summary-valid").removeClass("validation-summary-errors");
    }
}

function clearErrors(jForm) {
    remoteErrors(jForm, []);
}

Summary

Validation is hard. In a distributed environment it’s harder. With so many moving parts and so many disparate technologies involved (Html, JavaScript, C#, Http), it can be a challenging thing to do in a testable and maintainable way. While there are many different ways one can approach this problem, the solution I have outlined here has held up to most requirements I have had to deal with when using the ASP.NET Web API. By avoiding DataAnnotations, and plugging into the support IValidatableObject interface, we can create clear, testable Validator objects, and still take full advantage of the Model Binding support of the framework. By leveraging the built in support given to us by CreateErrorResponse, we can send validation information back to the client in ways that are JavaScript friendly. This gives the illusion of client side validation with the power of the server. It also removes the need to write validation rules twice (once on the client, and again on the server), and that is a benefit I think we can all appreciate!

BDN

Provider Based Commands

To access the code discussed in this post click here. Feel free to do what you want with it. Though no warranty for you.

Commanding is a pretty amazing thing, and in WPF it is about as good as it gets. But as with all things cool, design decisions need to be made when considering their usage in an application. One such decision that I have had to make several times is how to best deal with core application commands such as the SaveCommand and CloseCommand. These global application commands are particularly tricky for a few reasons. First, you must ensure consistent behavior throughout the entire application. It is important that users do not have to relearn these commands on each screen the navigate to. Secondly and equally important, the development experience must be simple enough that the first point can be realized. These type of application commands all share three important traits.

1. Accessible– Commands must be accessible in consistent way across your application
2. Predictable – Commands must behave in a predictable way across the application when executed
3. Contextual– Commands must be able to consider application context

Over time I have started to use the term Contextual Commands when describing these types of commands. In this post I will outline the approach that I have used with success on a few different projects as well as provide a simple reference implementation. But before that, let us outline what each of the three traits listed above mean.

Accessible

Accessibility is a primary trait that Contextual Commands must have. This simply means that commands are presented to the user and executed by the user in a similar fashion throughout the entire application. A good example of this is how Microsoft Word handles the Save command. Several consistent options exists.

1. Control + S
2. The Save button on the tool bar
3. The Save menu item on the Ribbon application menu

In fact users have become so conditioned to this commands that many will hit control+s as part of their normal key press behavior, allowing them to save their work as they go.

To accomplish Accessibility in a developer friendly way I choose to make all contextual commands singletons. (Take a deep breath, I know, I know). Utilizing the Singleton Pattern in this case frees developers from the pain of creating instances, command bindings, and all the other error prone work that would need to be done otherwise. Making Contextual Commands singletons allows us to expose commands in multiple ways while ensuring the basic buildup of a command will remain consistent. In short all visualizations of a Contextual Command use the same instance limiting its possible variation that could hurt overall usability.

Predictable

Predictability means that aside from contextual differences, the execution of a command will behave in the same way every time it is executed. For example if you decide the Save button will be disabled until a view is dirty that choice should hold true throughout all views. If you decide that your close command is going to prompt users for unsaved changes we need to make sure it always does. There should be no variation in overall experience of using these commands. Holding to the standard of predictability will ensure that developers need not worry about such choices preventing them from mucking up your beautiful framework code.

To accomplish Predictablility base implementations of each command will be provided. Using a combination of the Tempalate Method and Provider Pattern we can open the implementation of the command enough to developers so contextual differences can be supported yet at the same time closing off its core implementation ensuring its execution is predictable every time. Textbook Open Closed Principle.

Contextual

The last and most important point is that these commands must consider the current context of the application. For example clicking the save button in Microsoft Word it saves the document that is currently in view. This may seem simple, but often times this simple concept turns into some very nasty error prone code. Think about what it means to save a document. To save the document correctly there are several things that need to be considered. Is the file readonly? Is the file on a network share? Is the file in collaboration mode? Is the file a word document? Is it a html document? All of these decisions are contextual in nature and will likely differ on each view in an application.

Gathering enough context to correctly save something can often times be a lot of work. Using the Provider Pattern helps us keep this code encapsulated and clean. Each view/control will have a chance to provide to the commands the contextual details needed to handle the difference present in each view.

Disclaimer

As usual, the reference implementation I am providing here is illustrative at best. There are many things that should be done differently in a real application.

The Commands and Provider

A few months ago I posted my flavor of the RelayCommand . RelayCommand is a simple implementation of the ICommand interface adding to it support for asynchronous processing, Predicates and Actions, as well BusyCursor support.  Also for simplicity I usually group all Contextual Commands in a single class called ContextualCommands. If you prefer a more granular approach you could split this class apart into several separate classes, I will leave that up to you . Lets take a quick look at components needed to support the implementation. The image blow shows the core components of our the setup.

The IContextualCommands interface simply defines the commands I consider contextual (CloseCommand, SaveCommand). In addition to defining the commands this interface defines the SetProvider method. This method gives consumers the ability to change the command provider that is used for each of the command implementations. In the end it is the SetProvider that allows individual views to provide the contextual information needed by the commands. The SetProvider method will work with the IContextualCommandsProvider interface.

 IContextualCommand Interface

The IContextualCommandsProvider interface defines the methods each provider must implement. Since I have lumped the ContextualCommands into a single class the provider must provide the details for each command. The implementation provided by the provider will be used during command execution this is the key to supplying contextual differences from view to view.

</pre>
using System.Windows.Input;

namespace ProviderBasedCommands.Framework
{
 /// <summary>
 /// Interface for our Contextual Commands
 /// </summary>
 public interface IContextualCommands
 {
 /// <summary>
 /// Gets the save command.
 /// </summary>
 /// <value>The save command.</value>
 ICommand SaveCommand { get; }
 /// <summary>
 /// Gets the close command.
 /// </summary>
 /// <value>The close command.</value>
 ICommand CloseCommand { get; }
 /// <summary>
 /// Sets the provider for the contextual commands.
 /// </summary>
 /// <param name="contextualCommandsProvider">The contextual commands provider.</param>
 void SetProvider(IContextualCommandsProvider contextualCommandsProvider);
 /// <summary>
 /// Determines whether this instance [can close command execute] the specified param.
 /// </summary>
 /// <param name="param">The param.</param>
 /// <returns>
 /// <c>true</c> if this instance [can close command execute] the specified param; otherwise, <c>false</c>.
 /// </returns>
 bool CanCloseCommandExecute(object param);
 /// <summary>
 /// Closes the command executed.
 /// </summary>
 /// <param name="param">The param.</param>
 void CloseCommandExecuted(object param);
 /// <summary>
 /// Determines whether this instance [can save command execute] the specified param.
 /// </summary>
 /// <param name="param">The param.</param>
 /// <returns>
 /// <c>true</c> if this instance [can save command execute] the specified param; otherwise, <c>false</c>.
 /// </returns>
 bool CanSaveCommandExecute(object param);
 /// <summary>
 /// Saves the command executed.
 /// </summary>
 /// <param name="param">The param.</param>
 void SaveCommandExecuted(object param);
 }
}
<pre>

A IContextualCommandsProvider Implementation

</pre>
namespace ProviderBasedCommands.Framework
{
 public interface IContextualCommandsProvider
 {
 /// <summary>
 /// Determines whether this instance [can close command execute] the specified param.
 /// </summary>
 /// <param name="param">The param.</param>
 /// <returns>
 /// <c>true</c> if this instance [can close command execute] the specified param; otherwise, <c>false</c>.
 /// </returns>
 bool CanCloseCommandExecute(object param);
 /// <summary>
 /// Closes the command executed.
 /// </summary>
 /// <param name="param">The param.</param>
 void CloseCommandExecuted(object param);
 /// <summary>
 /// Determines whether this instance [can close command execute] the specified param.
 /// </summary>
 /// <param name="param">The param.</param>
 /// <returns>
 /// <c>true</c> if this instance [can close command execute] the specified param; otherwise, <c>false</c>.
 /// </returns>
 bool CanSaveCommandExecute(object param);
 /// <summary>
 /// Closes the command executed.
 /// </summary>
 /// <param name="param">The param.</param>
 void SaveCommandExecuted(object param);
 }
}
<pre>

Contextual Commands

The ContextualCommands class is the single implementation of the IContextualCommands interface and is registered with Unity as a singleton. This class exposes the Contextual Commands to the rest of the application. This class does a few important things for us.

1. It creates our CloseCommand and SaveCommand instances
2. It handles the registration of input bindings to these commands
3. It manages the current command provider via the SetProvider method
4. It delegates the command implementation to the current provider

Lets take a look a what this class looks like.

</pre>
using System.Windows;
using System.Windows.Input;
using ProviderBasedCommands.Command;

namespace ProviderBasedCommands.Framework
{
 public class ContextualCommands : IContextualCommands
 {
 #region Private Data Members

/// <summary>
 /// Close Command Input Key Binding
 /// </summary>
 private readonly InputBinding _closeCommandInputBinding;
 /// <summary>
 /// Save Command Input Key Binding
 /// </summary>
 private readonly InputBinding _saveCommandInputBinding;
 /// <summary>
 /// Current provider for command implementations
 /// </summary>
 private IContextualCommandsProvider _contextualCommandsProvider;

#endregion

#region Constructor

/// <summary>
 /// Initializes a new instance of the <see cref="ContextualCommands"/> class.
 /// </summary>
 public ContextualCommands()
 {
 //Create the actual command instances and related key bindings
 CloseCommand = new RelayCommand(CanCloseCommandExecute, CloseCommandExecuted);
 _closeCommandInputBinding = new KeyBinding(CloseCommand, Key.Escape, ModifierKeys.None);

 SaveCommand = new RelayCommand(CanSaveCommandExecute, SaveCommandExecuted);
 _saveCommandInputBinding = new KeyBinding(SaveCommand, Key.S, ModifierKeys.Control);
 }

#endregion

#region IContextualCommands Members

/// <summary>
 /// Gets the save command.
 /// </summary>
 /// <value>The save command.</value>
 public ICommand SaveCommand { get; private set; }
 /// <summary>
 /// Gets the close command.
 /// </summary>
 /// <value>The close command.</value>
 public ICommand CloseCommand { get; private set; }

/// <summary>
 /// Sets the provider for the contextual commands.
 /// </summary>
 /// <param name="contextualCommandsProvider">The contextual commands provider.</param>
 public void SetProvider(IContextualCommandsProvider contextualCommandsProvider)
 {
 //Set provider
 _contextualCommandsProvider = contextualCommandsProvider;

//If null lets clear the key bindings
 if (contextualCommandsProvider == null)
 {
 RemoveKeyBindings();
 }

 RegisterKeyBindings();
 }

/// <summary>
 /// Determines whether this instance [can close command execute] the specified param.
 /// </summary>
 /// <param name="param">The param.</param>
 /// <returns>
 /// <c>true</c> if this instance [can close command execute] the specified param; otherwise, <c>false</c>.
 /// </returns>
 public bool CanCloseCommandExecute(object param)
 {
 if (_contextualCommandsProvider == null)
 {
 return false;
 }

return _contextualCommandsProvider.CanCloseCommandExecute(param);
 }

/// <summary>
 /// Closes the command executed.
 /// </summary>
 /// <param name="param">The param.</param>
 public void CloseCommandExecuted(object param)
 {
 if (_contextualCommandsProvider != null)
 {
 _contextualCommandsProvider.CloseCommandExecuted(param);
 }
 }

public bool CanSaveCommandExecute(object param)
 {
 if (_contextualCommandsProvider == null)
 {
 return false;
 }

return _contextualCommandsProvider.CanSaveCommandExecute(param);
 }

/// <summary>
 /// Saves the command executed.
 /// </summary>
 /// <param name="param">The param.</param>
 public void SaveCommandExecuted(object param)
 {
 if (_contextualCommandsProvider != null)
 {
 _contextualCommandsProvider.SaveCommandExecuted(param);
 }
 }

#endregion

#region Private Methods

/// <summary>
 /// Registers the key bindings.
 /// </summary>
 private void RegisterKeyBindings()
 {
 if (!Application.Current.MainWindow.InputBindings.Contains(_closeCommandInputBinding))
 {
 Application.Current.MainWindow.InputBindings.Add(_closeCommandInputBinding);
 }

if (!Application.Current.MainWindow.InputBindings.Contains(_saveCommandInputBinding))
 {
 Application.Current.MainWindow.InputBindings.Add(_saveCommandInputBinding);
 }
 }

/// <summary>
 /// Removes the key bindings.
 /// </summary>
 private void RemoveKeyBindings()
 {
 Application.Current.MainWindow.InputBindings.Add(new KeyBinding(CloseCommand, Key.Escape, ModifierKeys.None));
 Application.Current.MainWindow.InputBindings.Add(new KeyBinding(SaveCommand, Key.S, ModifierKeys.Control));
 }

#endregion
 }
}
<pre>

Usage

With the basic components built out a discussion about their usage may be helpful before you look at the example code. Since the ContextualCommands class is a singleton the only moving part is the underlying provider implementation. Generally speaking the ContextualCommands class is supplied with a new provider each time a view is presented. In the example code you will notice I include a simple Controller object. This class is responsible for presenting views into the MainRegion of our application. Essentially when the Controller class is asked to present a view the following things happen.

1. The Controller first asks Unity to create our View
2. The Controller looks to see if the resolved View has a ViewModel that implements the IContextualCommandsProvider interface
3. If the View’s ViewModel implements the IContextualCommandsProvider interface, the Controller calls the SetProvider method on the ContextualCommands instance passing to it the the IContextualCommandsProvider implementation

Here is a quick look at the Controller class, again please look at the supplied example code for additional details about this implementation.

</pre>
using Microsoft.Practices.Unity;

namespace ProviderBasedCommands.Framework
{
 /// <summary>
 /// Controller used to present and close views
 /// </summary>
 public class Controller : IController
 {
 #region Dependency

/// <summary>
 /// Gets or sets the container.
 /// </summary>
 /// <value>
 /// The container.
 /// </value>
 [Dependency]
 public IUnityContainer Container { get; set; }

/// <summary>
 /// Gets or sets the region manager.
 /// </summary>
 /// <value>
 /// The region manager.
 /// </value>
 [Dependency]
 public IRegionManager RegionManager { get; set; }

/// <summary>
 /// Gets or sets the contextual commands.
 /// </summary>
 /// <value>The contextual commands.</value>
 [Dependency]
 public IContextualCommands ContextualCommands { get; set; }

#endregion

#region IController Members

/// <summary>
 /// Presents the dialog.
 /// </summary>
 /// <typeparam name="T"></typeparam>
 public void PresentDialog<T>() where T : IDialog
 {
 RegionManager.ApplyDialogSettings(null);
 RegionManager.DialogRegion.Content = Container.Resolve<T>();
 RegionManager.DialogRegion.ShowDialog();
 }

/// <summary>
 /// Closes the view.
 /// </summary>
 /// <typeparam name="T"></typeparam>
 /// <param name="view">The view.</param>
 /// <returns></returns>
 public bool CloseView<T>(T view) where T : IView<IViewModel>
 {
 RegionManager.MainRegion.Content = null;
 ClearCommandProviders(view);
 return true;
 }

/// <summary>
 /// Presents the view.
 /// </summary>
 /// <typeparam name="T"></typeparam>
 public void PresentView<T>() where T : IView<IViewModel>
 {
 var view = Container.Resolve<T>();
 SetViewAsCommandProvider(view);
 RegionManager.MainRegion.Content = view;
 }
 /// <summary>
 /// Presents the view.
 /// </summary>
 /// <typeparam name="T"></typeparam>
 /// <param name="dialogSettings">The dialog settings.</param>
 public void PresentDialog<T>(DialogSettings dialogSettings) where T : IDialog
 {
 RegionManager.ApplyDialogSettings(dialogSettings);
 RegionManager.DialogRegion.Content = Container.Resolve<T>();
 RegionManager.DialogRegion.ShowDialog();
 }

#endregion

#region Private Methods

/// <summary>
 /// Changes the command providers.
 /// </summary>
 /// <param name="view">The view.</param>
 private void SetViewAsCommandProvider(IView<IViewModel> view)
 {
 var contextualCommandProvider = view.ViewModel as IContextualCommandsProvider;
 if (contextualCommandProvider != null)
 {
 ContextualCommands.SetProvider(contextualCommandProvider);
 }
 }

/// <summary>
 /// Changes the command providers.
 /// </summary>
 /// <param name="view">The view.</param>
 private void ClearCommandProviders(IView<IViewModel> view)
 {
 var contextualCommandProvider = view.ViewModel as IContextualCommandsProvider;
 if (contextualCommandProvider != null)
 {
 ContextualCommands.SetProvider(null);
 }
 }

#endregion
 }
}
<pre>

In short, every time a view is presented that view becomes the provider to the ContextualCommands.

The Null Provider

In real life not all ViewModels would implement the IContextualCommandsProvider interface. This puts us in a tricky position when the current ViewModel implements the interface, and the ViewModel we are navigating to does not. Since the new ViewModel is not a provider the Controller will not call the SetProvider as a result the last ViewModel will remain the provider. This can lead to memory leaks, and all sorts of strange things.  To get around the disconnect the SetProvider method allow nulls to be passed in. This essentially disables all of the ContextualCommands. This problem would best be solved with the creation of a NullProvider type but for simplicity I have ignored that fact.

Sample Application

I created a very small sample implementation of this concept. To download it click here. This application contains the following things.

1. A very brief and limited MVVM Framework, simply used to illustrate how these commands may be used
2. The ContextualCommands implementation
3. Unity support to manage the moving parts
4. A RelayCommand implementation
5. A BusyCursor implementation

Please feel free to download the code and sort through all the details yourself, my intent with this post is simply to introduce the concept of Provider Based Commands. I hope the example code is clear enough to show you the power of this approach. I can tell you from personal experience, every time I go to a new client this is one of the first things I implement. And time and time again, I am happy I did it this way.

Enjoy!

Flatten It!

Often times you need to be able to take action on an entire object graph, or specific types in a graph. An example of this could be walking the graph and setting a single property on all of your business objects. Perhaps a bool indicating the state of an object like IsDirty. Well since graphs are all different shapes a handy way to do this is through c# iterators. The idea being you supply a root object and the type of object you want to deal with. The method will then return to you each instance of said type.

 

There are a couple of things we want to do with this implementation.

1. Ensure that it can be short circuited by the caller. After all you may want to use this method to inspect a graph for broken rules. And as soon as you find an InValid instance return and prevent further recursion.
2. Supply a list of types to ignore in the recursion allowing the caller to limit useless graph traversal.
3. Should be provided as an extension method so it can be used with all object graphs.

Lets take a look at how this might work.

 

	public static class ObjectExtensions
	{
		/// <summary>
		/// Finds all object of the supplect type parameter.
		/// </summary>
		/// <typeparam name="T"></typeparam>
		/// <param name="obj">The obj.</param>
		/// <param name="exclusionTypes">The exclusion types.</param>
		/// <returns></returns>
		public static IEnumerable<T> FindAll<T>(this object obj, params Type[] exclusionTypes) where T : class
		{
			if (obj is T)
			{
				yield return (obj as T);
			}

			var collection = obj as ICollection;
			if (collection != null)
			{
				foreach (var item in collection)
				{
					foreach (var child in FindAll<T>(item, exclusionTypes))
					{
						yield return child;
					}
				}
			}
			else
			{
				foreach (var property in obj.GetType().GetProperties().Where(item => !IsTypeExcluded(item.PropertyType, exclusionTypes)))
				{
					var propertyValue = property.GetValue(obj, null);
					if (propertyValue != null)
					{
						foreach (var item in FindAll<T>(propertyValue, exclusionTypes))
						{
							yield return item;
						}
					}
				}
			}
		}

		/// <summary>
		/// Determines whether [is type excluded] [the specified type].
		/// </summary>
		/// <param name="type">The type.</param>
		/// <param name="exclusionTypes">The exclusion types.</param>
		/// <returns>
		///   <c>true</c> if [is type excluded] [the specified type]; otherwise, <c>false</c>.
		/// </returns>
		private static bool IsTypeExcluded(Type type, params Type[] exclusionTypes)
		{
			if (type == typeof(string) || type.IsValueType)
			{
				return true;
			}

			if (exclusionTypes != null
				  && exclusionTypes.Length > 0)
			{
				if (exclusionTypes.Contains(type))
				{
					return true;
				}
			}
			return false;
		}
	}

Lets look at its usage.

	class Program
	{
		static void Main(string[] args)
		{
			var cat = new cat { Name = "Test", Arms = new List<Arm> { new Arm { FingerCount = 10 } }, Legs = new List<Leg> { new Leg { Size = 300 } } };
			var x = cat.FindAll<Arm>().ToList();
			Console.Read();
		}
	}

	public class cat
	{
		public string Name { get; set; }
		public List<Leg> Legs { get; set; }
		public List<Arm> Arms { get; set; }
	}

	public class Leg
	{
		public int Size { get; set; }

	}

	public class Arm
	{
		public int FingerCount { get; set; }
	}

Enjoy!

Frameworks and Austrian Economics

Inception

An interesting thing happened to me a few years back while sitting in a Sprint Retrospective. A nameless developer on our team voiced some frustration with our UI Framework. Person X stated that that the UI Framework was too constraining. Since I was largely responsible for this aspect of the system I was interested in hearing the developers concerns. When pressed to describe the areas Person X felt were too limiting, it became clear that the developer was trying to work out of band and out of pattern. The developer was trying to introduce a new UI pattern not yet discussed or agreed upon by our team and users.  It was in this moment it occurred to me that while frameworks need to support the needs of the system, they should also prevent developers from introducing things that are not well understood at a whim.  This particular conversation was the seedling for my particular view of how frameworks should support applications. I call it Framework Organics.

What is the Role of a Framework

This question will likely elicit 10 different answers if you ask 10 different people. And though you did not ask here is my answer.

A framework should box developers into the understood and agreed upon patterns while allowing for the necessary changes agreed upon over time.

In greater detail a framework should provide support for concepts that are relevant to the system being developed. In stark contrast a framework absolutely should not support any random concept a developer can dream up. It should limit the ability of developers to travel to far off into the weeds. Protecting your users from cowboy coders who are spinner happy!

Along with limiting developers from introducing new concepts, a well-designed framework should be able to adapt to change over time. It should be resilient and extendable to meet any reasonable need that may arise throughout the development lifecycle. This does not mean that you need to build an over engineered goliath of a framework that supports every possible permutation possible. Because you can’t and no one I have ever met can.

Organics and Austrians

One of my favorite economists F.A. Hayek wrote an entire book called ‘The Fatal Conceit’. In this book he makes the case against socialism. Political affiliation aside his premise is worth mentioning here. Hayek believed as many Austrian Economists did/do, that it was impossible for central planners to understand that millions of interactions of the millions of people they govern. He also argued that any attempt to plan around these interactions was a form of conceit that was doomed to fail. Austrians believe that the framework of society was grown overtime in a free market sort of way. If problems came up they were addressed and solved, it was this sort organic evolution that Austrians feel allow us to strive as we do today.

Again this is not meant to be a political rant. But parallels can be drawn between concepts in software design and economics.  The Agile Method and the various approaches of iterative development it has spawned clearly harness the power of organic growth over time. Short cycles of problem/solution/repeat are much more in line with Hayek’s ideas than they are with say the Keynesian approach to planned government. In contrast the Waterfall methodology is more in line with Socialism. Waterfall is far more plan centric it’s ridged, and less adaptable to change over time. Waterfall does what it can to make sure change is as painful and costly as possible. It’s no wonder at all why that methodology is for the most part dead.

Bringing Back In

Ok so I am not an economist and I really do not want to be tagged a right wing radical because of this post. But the point here is simple, frameworks should evolve organically overtime. Yes this means constant refactoring of your core code throughout the life of a project. When new patterns are introduced, your framework will change and code sweeps will need to happen. As your product grows so will the level of support your framework provides but on an as needed basis. Keeping in mind the framework should also limit developers to the current set of patterns that are supported by the current revision of your framework.

The benefit of framework limitation should not be underestimated. By limiting concepts allowed in your systems users start to learn and understand stereotypes. As a result new screens seem familiar to them, less support questions arise, and your application is usable unlike ITunes for the PC. The benefits are not only seen by users. Developers now have a common language when designing new screens. “This fits our Master Detail pattern”; “This fits our search pattern”. And if a scenario does not seem to fit existing patterns perhaps the introduction of something new is needed. And the cycle continues in a nice organic sort of way!

 

Enjoy

Lets Date!(An Approach)

Dates always seem to give me a headache when working with business apps. Trying to come up with framework level support for handling them is not always easy.  In this post I will outline an approach to dealing with dates that we are using with some success in my current project. Much praise to Matt Lindstrom for the actual implementation of what I am going to outline here.

ORM Mapping

In most databases columns defined as date types can be built to allow nulls. This makes sense when you consider the implications for reporting etc. In .Net the native DateTime object is a value type, thus it cannot represent null. To correct this inconsistency we leverage Nullable<DateTime> for all date properties. And to prevent all the nasty ‘HasValue’ checking in our ORM methods we use an extension method on Nullable<DateTime> as follows.

       /// <summary>
        /// Prepares for database.
        /// </summary>
        /// <param name="dateTime">The date time.</param>
        /// <param name="includeTimeStamp">if set to <c>true</c> [include time stamp].</param>
        /// <returns></returns>
        public static object PrepareForDatabase(this Nullable<DateTime> dateTime)
        {
            if (dateTime.HasValue)
            {
                return dateTime.Value;
            }
            return DBNull.Value;
        }

This method could be used the following way.

            /// <summary>
            /// Method used to build command
            /// </summary>
            /// <param name="database">Database to run command against</param>
            /// <returns>Fully loaded command object ready to execute</returns>
            public override DbCommand GetCommand(Database database)
            {
                DbCommand command = database.GetStoredProcCommand("MyInsertCommand");
                database.AddInParameter(command, "DATE_in", DbType.DateTime, SomeNullableDate.PrepareForDatabase());
                return command;
            }

Of course this code only covers the mapping to the data store some additional work is needed when saturating objects with data. Again to support this we added an extension method on the CSLA SafeDataReader. Here we also account for the MinDate assuming that it is the same as a null date.

        /// <summary>
        /// Gets the nullable date time.
        /// </summary>
        /// <param name="data">The data.</param>
        /// <param name="i">The i.</param>
        /// <returns></returns>
        public static DateTime? GetNullableDateTime(this SafeDataReader data, int i)
        {
            if (data.GetDateTime(i).Equals(DateTime.MinValue))
            {
                return null;
            }
            return data.GetDateTime(i);
        }

And in practice

        /// <summary>
        /// Method used for ORM mapping of CompRehabCase
        /// </summary>
        /// <param name="data">SafeDataReader</param>
        private void Populate(SafeDataReader data)
        {
            LoadProperty<Nullable<DateTime>>(SomeNullableDateTime, data.GetNullableDateTime(data.GetOrdinal("SOME_DATE")));
        }

And that all folks.

Nullable<DateTime>

BusinessListBase AuthorizationRules

I have never been a huge fan of how CSLA handles security. One drawback I have found is that you cannot secure a BusinessListBase without first wrapping it with a BusinessBase. I happen to think it is a perfectly valid use case for someone to call Save() on a root collection. I also think it is perfectly valid for someone to want to secure the CRUD operations at this level. So how can you do it?

First some design choices need to be made. For instance, can a user who is not authorized to call save on a root Customer object call save on a root CustomerCollection object? Or are these two independent user stories that should have separate security contexts? If you think like me you answer yes to the first question and no to the last. That is to say, if a user can’t save a root object the user should not be able to save a root collection of those same objects.

If you have already created you own set of CSLA base classes the solution to this is very easy. By overriding the void DataPortal_OnDataPortalInvoke(DataPortalEventArgs e) method on BusinessListBase you get a framework hook to do anything you so desire before the DataPortal operation is executed. I use it to check the AuthorizationRules! And since I have already stated that if a user can’t save a root object the user should not be able to save a root collection of those same objects, I can delegate the security checks to the actual business object. See my code below.

    [Serializable]
    public class MyBusinessListBase<T, C> : BusinessListBase<T, C>
        where T : BusinessListBase<T, C>
        where C : Csla.Core.IEditableBusinessObject
    {
        #region BusinessListBase overrides

        /// <summary>
        /// Called by the server-side DataPortal prior to calling the
        /// requested DataPortal_xyz method.
        /// </summary>
        /// <param name="e">The DataPortalContext object passed to the DataPortal.</param>
        protected override void DataPortal_OnDataPortalInvoke(DataPortalEventArgs e)
        {
            base.DataPortal_OnDataPortalInvoke(e);
            CheckCollectionAuthorization(e);
        }

        #endregion

        #region Private Methods

        /// <summary>
        /// Checks the collection authorization.
        /// </summary>
        private static void CheckCollectionAuthorization(DataPortalEventArgs e)
        {
            if (e.Operation == DataPortalOperations.Fetch)
            {
                if (!Csla.Security.AuthorizationRules.CanGetObject(typeof(C)))
                {
                    throw new System.Security.SecurityException(string.Format("User not authorized to {0} object type {1}",
                                                                              "get",
                                                                              typeof(C).Name));
                }
            }
            else if (e.Operation == DataPortalOperations.Create)
            {
                if (!Csla.Security.AuthorizationRules.CanCreateObject(typeof(C)))
                {
                    throw new System.Security.SecurityException(string.Format("User not authorized to {0} object type {1}",
                                                                              "create",
                                                                              typeof(C).Name));
                }
            }
            else if (e.Operation == DataPortalOperations.Update)
            {
                if (!Csla.Security.AuthorizationRules.CanEditObject(typeof(C)))
                {
                    throw new System.Security.SecurityException(string.Format("User not authorized to {0} object type {1}",
                                                                              "Update",
                                                                              typeof(C).Name));
                }
            }
        }

        #endregion
    }