ploeh blog : Software Design

TechEd Sessions Sample Code

ploeh — Fri, 09 Nov 2007 05:34:00 GMT

Now that both of my TechEd sessions are over, I've had some request for the sample code that I demonstrated at both sessions.

The sample code I used at the interactive talk on TDD is attached to this post.

The code I demonstrated at my talk on manual and dynamic mocks is available upon request. I certainly don't mind sharing it, but for reasons I don't want to go into here, I'm not going to post it for general download, so if you are interested, drop me a line (if you use the Email link on this blog, I'll get an email that also contains your sender address, which means you don't have to publicly post your email address here).

If you didn't go to my sessions, you can still download the sample, but it probably doesn't make as much sense taken out of context.

As usual, the code is provided here "as is", etc.

CovariantCollection

ploeh — Sat, 29 Sep 2007 18:48:00 GMT

One of the known limitations of .NET generics is the limited support for covariance. This is sometimes a challenge when it comes to collections. As an example, consider this simple abstract class:

public abstract class MyClass

    protected MyClass() { }

Okay, so that's not the most exciting class you've ever seen, but it will serve my demonstration purposes nicely. Assume that you have another class that exposes a list of MyClass objects:

public abstract class MyContainer

    protected MyContainer() { }

    public abstract IList<MyClass> MyClasses { get; }

Here's a simple implementation that doesn't cause any problems at all:

public class SimpleContainer : MyContainer

    private List<MyClass> myClasses_;

    public SimpleContainer()

        this.myClasses_ = new List<MyClass>();

    public override IList<MyClass> MyClasses

        get { return this.myClasses_; }

This implementation simply encapsulates a List<MyClass>, which implements IList<MyClass>, and the compiler is happy. Now, assume that you need to write a more complex implementation of MyContainer. This class exclusively uses a list of MyDerivedClass, which derives from MyClass. For type safety reasons, you prefer to work on a list of MyDerivedClass, since you have complex internal logic and you want to ensure that you only add MyDerivedClass instances to the list. Here's an outline of what I'm describing:

public class NotSoSimpleContainer : MyContainer

    private List<MyDerivedClass> myClasses_;

    public NotSoSimpleContainer()

        this.myClasses_ = new List<MyDerivedClass>();

This class must also implement the MyClasses abstract property, or it isn't going to compile. However, due to the lack of covariance support in .NET, this attempt isn't going to compile either:

// Doesn't compile

public override IList<MyClass> MyClasses

    get { return this.myClasses_; }

The problem is that myClasses_ is an instance of List<MyDerivedClass>, and although MyDerivedClass derives from MyClass, List<MyDerivedClass> doesn't implement IList<MyClass>, but rather IList<MyDerivedClass>, which is an entirely different type. Any similarity to other types is purely coincidental and does not imply any specific intent of the author, or something...

Actually, this is quite annoying, so how can you solve this? My approach is to create a collection that wraps the original collection but exposes a different interface. It's a bit like how ReadOnlyCollection<T> works. In lack of a better idea, I've called this class CovariantCollection<TConcrete, TAbstract>. This collection doesn't copy the original list, but rather wraps it while exposing it differently. To see how it's used, let's look at the updated NotSoSimpleContainer implementation:

public class NotSoSimpleContainer : MyContainer

    private List<MyDerivedClass> myClasses_;

    private CovariantCollection<MyDerivedClass, MyClass> myClassesWrapper_;

    public NotSoSimpleContainer()

        this.myClasses_ = new List<MyDerivedClass>();

        this.myClassesWrapper_ =

            new CovariantCollection<MyDerivedClass, MyClass>(this.myClasses_);

    public override IList<MyClass> MyClasses

        get { return this.myClassesWrapper_; }

From within NotSoSimpleContainer, you would still manipulate the original list via the myClasses_ member variable, which ensures that only instances of MyDerivedClass are being used. However, the myClassesWrapper_ member variable wraps myClasses_ and exposes it as an IList<MyClass>.

Here comes the complete implementation of CovariantCollection<TConcrete, TAbstract>. It's a bit of a long code listing, but I think it will still be more readable if I present it in one piece. I still have a few comments about the implementation below, so just scroll past the code if you don't care about all the details:

public class CovariantCollection<TConcrete, TAbstract> :

    Collection<TConcrete>, IList<TAbstract> where TConcrete : TAbstract

    public CovariantCollection(IList<TConcrete> list)

        : base(list)

    #region IList<TAbstract> Members

    int IList<TAbstract>.IndexOf(TAbstract item)

        if (item is TConcrete)

            return this.IndexOf((TConcrete)item);

        throw CovariantCollection<TConcrete, TAbstract>.

            CreateWrongConcreteTypeException("item");

    void IList<TAbstract>.Insert(int index, TAbstract item)

        if (!(item is TConcrete))

            throw CovariantCollection<TConcrete, TAbstract>.

                CreateWrongConcreteTypeException("item");

        this.Insert(index, (TConcrete)item);

    void IList<TAbstract>.RemoveAt(int index)

        this.RemoveAt(index);

    TAbstract IList<TAbstract>.this[int index]

get

            return this[index];

set

            if (!(value is TConcrete))

                throw CovariantCollection<TConcrete, TAbstract>.

                    CreateWrongConcreteTypeException("value");

            this[index] = (TConcrete)value;

    #endregion

    #region ICollection<TAbstract> Members

    void ICollection<TAbstract>.Add(TAbstract item)

        if (!(item is TConcrete))

            throw CovariantCollection<TConcrete, TAbstract>.

                CreateWrongConcreteTypeException("item");

        this.Add((TConcrete)item);

    void ICollection<TAbstract>.Clear()

        this.Clear();

    bool ICollection<TAbstract>.Contains(TAbstract item)

        if (item is TConcrete)

            return this.Contains((TConcrete)item);

        throw CovariantCollection<TConcrete, TAbstract>.

            CreateWrongConcreteTypeException("item");

    void ICollection<TAbstract>.CopyTo(TAbstract[] array, int arrayIndex)

        TConcrete[] concreteItems = new TConcrete[array.Length];

        this.CopyTo(concreteItems, arrayIndex);

        concreteItems.CopyTo(array, 0);

    int ICollection<TAbstract>.Count

        get { return this.Count; }

    bool ICollection<TAbstract>.IsReadOnly

        get { return ((ICollection<TConcrete>)this).IsReadOnly; }

    bool ICollection<TAbstract>.Remove(TAbstract item)

        if (item is TConcrete)

            return this.Remove((TConcrete)item);

        throw CovariantCollection<TConcrete, TAbstract>.

            CreateWrongConcreteTypeException("item");

    #endregion

    #region IEnumerable<TAbstract> Members

    IEnumerator<TAbstract> IEnumerable<TAbstract>.GetEnumerator()

        foreach (TAbstract item in this)

            yield return item;

    #endregion

    private static Exception CreateWrongConcreteTypeException(string argumentName)

        return new ArgumentException(string.Format(

            "This collection only supports instances of {0} (or derived types).",

            typeof(TConcrete).AssemblyQualifiedName), argumentName);

You will probably notice a common pattern here. In most of the members, I need to test if the input is indeed an instance of TConcrete (MyDerivedClass in the example) and throw an exception if this is not so. If the input is okay, I delegate to the implementation provided by Collection<T>. Notice that I don't need to delegate to base, but can delegate directly to this, since the implementation of IList<TAbstract> is an explicit imteface implementation. Collection<T> also provides the basic wrapper functionality, so I don't need to implement this manually.

You may also wonder about another implementation detail: In several cases (e.g. IndexOf), I first test the type of the input using the is keyword, and then subsequently cast to TConcrete. Since the is keyword causes a cast, I'm actually performing the same cast twice, which isn't terribly efficient. Normally, I'd resort to the as keyword and then test for null, but this isn't possible in this case since TConcrete may be a value type (in which case the as keyword is illegal).

It's worth noting that CovariantCollection<TConcrete, TAbstract> implements two different generic IList interfaces: IList<TConcrete> is implemented by Collection<TConcrete>, which also means that IList<TAbstract> has to be implemented explicitly, since some of the IList members (such as the indexer) only differ in return type, and .NET doesn't allow return type covariance.

You may not encounter this collection covariance conundrum every day, but I've personally found myself in this situation enough times that I'm happy that I have this totally reusable class to solve the problem. Now you have it too.

User Context

ploeh — Mon, 20 Aug 2007 23:38:00 GMT

Besides logging, one of the most common types of ambient context is the user. Who is the user? Was the user authenticated? What is the user allowed to do?

Since being able to answer these questions are such common requirements in software development, the BCL includes the IPrincipal interface that allows you to create implementations to meet that goal. In many cases, however, you need to know more about your user than just a name, authentication flag and role. You may need separate properties for first and last name, title, the user's age, gender or color preference, contact information, relationships to other users, etc.

Obviously, you can define your own user object that implements IPrincipal and IIdentity while also containing all this extra information. If you do this, here's a couple of design guidelines you should consider:

If you have any sort of volatile dependency in your User object, you should consider making the definition of your class abstract and otherwise abstracting away the dependencies. A simple example concerns the extraction of information. Imagine that you have a database that contains the user's first and last name, as well as a user ID. When you first create the User object, you may only know the user ID, and since you expect that not all callers will ever access the FirstName and LastName properties, you may want to implement lazy loading from the database. However, you should really make those properties abstract, so that other implementations (such as a test double) of your User class can implement different behavior.
If the distinction between IPrincipal and IIdentity doesn't make a lot of sense to you, you can easily let your User class implement both interfaces.
Consider creating a static convenience property for accessing the underlying user-specific store (see the example below).

Let's look at an example illustrating these guidelines. Imagine that you have a need to track and access the user's first and last name, as well as a display name:

public abstract partial class User : IPrincipal, IIdentity
{
    protected User()
    {
    }
 
    public abstract string FirstName { get; }
 
    public abstract string LastName { get; }
 
    public abstract string DisplayName { get; }
 
    // More members...
}

The class is abstract since I want to give inheritors some leeway in how they implement the behavior. In a web application, a derived class may look up the user's properties in a table, perhaps even utilizing lazy loading. An enterprise application may look up the data in Active Directory. A federated service may extract the data from a SAML token. Unit testers will probably want to create a stub or similar.

When implementing IPrincipal and IIdentity, a question that sometimes arises regards the distinction between IPrincipal and IIdentity: Which behavior and data should be implemented where? Should I create both a UserPrincipal and a UserIdentity class? In some cases, it makes sense, while in others, it doesn't. If it doesn't make sense to you in your particular case, you can collapse the implementation of both interfaces into the same class. Notice how in the declaration of the User class, I specified that it implements both IPrincipal and IIdentity. Here's the abstract implementation:

#region IPrincipal Members

public IIdentity Identity

    get { return this; }

public abstract bool IsInRole(string role);

#endregion

#region IIdentity Members

public abstract string AuthenticationType { get; }

public abstract bool IsAuthenticated { get; }

public string Name

    get { return this.DisplayName; }

#endregion

The most tricky aspect is linking the two interfaces to each other via the Identity property, and as you can see, that's dead simple: Just return the object itself. Again, I've cheated a bit since I've just delegated most of the rest of the interface implementation to child classes, but that makes sense, since inheritors may want to implement this functionality in quite different ways: If the backing store is AD, you can basically just wrap WindowsPrincipal and WindowsIdentity. If the backing store is a database, you may want to implement IsInRole with a (cached) stored procedure call. And once more, unit testers will just want to use some sort of test double.

Storing the User object in a user context can obviously be done manually. On Thread.CurrentPrincipal, it's as easy as this:

Thread.CurrentPrincipal = new FakeUser("Jane", "Doe");

Retriving the User instance, on the other hand, requires a bit more code:

User u = Thread.CurrentPrincipal as User;

if (u == null)

    throw new InvalidOperationException("Boo hiss");

// Use u

It's straightforward code, but tedious to have to write over and over again. At this point, many people might be tempted to move this code to a static method on a helper class, but object-oriented design principles recommend that you locate behavior in the class where it belongs - in this case the User class:

public static User Current

get

        /* Possibly use further abstraction here to

         * enable use of HttpContext or similar, as

         * described in previous post. */

        User u = Thread.CurrentPrincipal as User;

        if (u == null)

            // Alternatively use Null Object pattern here.

            throw new InvalidOperationException(

                "CurrentPrincipal is not a User instance.");

        return u;

set

        if (value == null)

            throw new ArgumentNullException("value");

        /* Possibly use further abstraction here to

         * enable use of HttpContext or similar, as

         * described in previous post. */

        Thread.CurrentPrincipal = value;

The static Current property is just a convenience property that encapsulates the behavior described above. In this example, I'm just using Thread.CurrentPrincipal as is, but as described in one of my previous posts, this will not work in ASP.NET. For full flexibility, you could then modify the Current property to use an abstract context container for storing and accessing the IPrincipal instance, as is also described in that post.

In this implementation, I'm also throwing an InvalidOperationException if the current IPrincipal context is not a User instance. One alternative to that would be to return a Null Object, in this case perhaps something like this:

internal class NullUser : User

    internal NullUser()

        : base()

    public override string FirstName

        get { return string.Empty; }

    public override string LastName

        get { return string.Empty; }

    public override string DisplayName

        get { return "Unknown"; }

    public override bool IsInRole(string role)

        return false;

    public override string AuthenticationType

        get { return "Null"; }

    public override bool IsAuthenticated

        get { return false; }

When using a Null Object, however, you should consider whether hiding another IPrincipal instance is the desired behavior. If the current principal is null, it's pretty easy, but it's more difficult to decide on the correct behavior when the current instance implements IPrincipal, but doesn't derive from User. Implicitly suppressing data in this way may lead to logical bugs or unintended behavior, which is why I chose to throw an exception in the above example.

The static Current property provides a convenient and safe way to code against the current user context, since it allows you to write code like this:

string firstName = User.Current.FirstName;

Writing to the User instance is just as easy, if you have writable properties.

A custom User class can evidently be much more complex than the above example, containing complex behavior and relationships to other users, etc. In any case, the general approach outlined here provides a few guidelines for effectively modeling your application's user context.

Call Contexts vs. ASP.NET

ploeh — Sat, 28 Jul 2007 21:56:00 GMT

In my former post on Ambient Contexts, I described how you can use CallContext or Thread Local Storage (TLS) to store a context that is specific to the current context of a call. As it turns out, ASP.NET uses a threading model that disables this approach, since you are not guaranteed that a single request will be entirely executed within a single thread. That's not particularly nice of the ASP.NET platform (to put it politely), but that's the hand we've been dealt. As described by Rockford Lhotka, your first approach should be to use HttpContext.Items when your code runs within a web application, and the CallContext or TLS when outside of ASP.NET.

However, even if you create a wrapper around your storage mechanism, you are still going to carry around a reference to System.Web, which may seem... weird... if you are writing a WPF application or Windows Service or whatever. Besides, this approach is not extensible, since you can't subsequently decide to use yet another context (perhaps you'd want to use WCF's OperationContext). If you've been working with software design for some years, it shouldn't be surprising that the answer is to add yet another level of indirection.

The basic idea is that instead of simply checking whether HttpContext.Current is null or not, you define an abstract context container that can store your custom context in whatever call context is available.

To illustrate this approach, I'll extend my former example to store the context in an abstract container defined by the FeatureContextContainer class:

public abstract class FeatureContextContainer

    protected FeatureContextContainer()

    public abstract FeatureContext Current { get; set; }

Since I don't want to carry around any (potentially) uneccessary references to System.Web or other implementation-specific context implementations, I want to be able to define concrete FeatureContextContainers in my application configuration file (remember that you should also consider including an imperative configuration option). Such a configuration might look something like this:

<configuration>

  <configSections>

    <section name="featureContext"

             type="Ploeh.Samples.FeatureControl.FeatureContextConfigurationSection, Ploeh.Samples.FeatureControl" />

  </configSections>

  <featureContext containerType="Ploeh.Samples.AspNetContext.HttpContextContainer, Ploeh.Samples.AspNetContext" />

</configuration>

In this case, the HttpContextContainer class would implement FeatureContextContainer by reading and writing the context to and from HttpContext.Items. The nice thing about this approach is that while the AspNetContext assembly has a dependency on System.Web, the rest of your application (including FeatureContext itself) doesn't.

The FeatureContext class itself must be modified to use whatever context container is provided to it:

[Serializable]

public abstract class FeatureContext

    private static FeatureContextContainer container_ =

        FeatureContextConfigurationSection.GetConfigurationSection().GetContextContainer();

    protected FeatureContext()

    public static FeatureContext Current

        get { return FeatureContext.container_.Current; }

        set { FeatureContext.container_.Current = value; }

    public abstract void Demand(FeatureLevel requestedLevel);

Instead of directly reading and writing the context to and from the CallContext as before, FeatureContext now delegates these operations to the configured FeatureContextContainer.

While it may seem that this approach now requires an application configuration file, this is actually not the case, since I implement FeatureContextConfigurationSection.GetConfigurationSection in this way:

public static FeatureContextConfigurationSection GetConfigurationSection()

    FeatureContextConfigurationSection config =

        ConfigurationManager.GetSection(

        FeatureContextConfigurationSection.ConfigurationName)

        as FeatureContextConfigurationSection;

    if (config != null)

        return config;

    return new DefaultFeatureContextConfigurationSection();

Notice that if the configuration section isn't found in the application configuration file (or if no such file exists at all), I return a DefaultFeatureContextConfigurationSection instead. This internal class simply overrides the virtual GetContextContainer method:

internal class DefaultFeatureContextConfigurationSection :

    FeatureContextConfigurationSection

    internal DefaultFeatureContextConfigurationSection()

        : base()

    public override FeatureContextContainer GetContextContainer()

        return new CallContextContainer();

Instead of using a configured type name to create an instance of that type, this implementation simply returns an instance of the CallContextContainer class:

internal class CallContextContainer : FeatureContextContainer

    private const string contextSlotName_ = "FeatureContext";

    internal CallContextContainer()

        : base()

    public override FeatureContext Current

get

            FeatureContext ctx = CallContext.LogicalGetData(

                CallContextContainer.contextSlotName_) as FeatureContext;

            if (ctx == null)

                ctx = new BasicContext();

                CallContext.LogicalSetData(

                    CallContextContainer.contextSlotName_, ctx);

            return ctx;

set

            CallContext.LogicalSetData(

                CallContextContainer.contextSlotName_, value);

If you recall the code from my former post, this is simply the original implementation of FeatureContext moved to a FeatureContextContainer implementation. By this, we have now come full circle: The default behavior of FeatureContextContainer is the same as described in my former post, and I have introduced no breaking changes, but now the implementation is extensible, which allows you to reuse this ambient context in an ASP.NET application.

In a unit testing scenario, CallContext works just fine, so you don't need to replace the default implementation in that case. This means that even if you would want to use FeatureContext in an ASP.NET application, you'd still write all your unit tests against the default implementation, and then, when you configure the entire application, you set it up with an HttpContextContainer. The HttpContextContainer class, on the other hand, is one of those software infrastructure types that you can't unit test, so if you really want to test it, you will need an integration test. On the other hand, the implementation is so simple that this will probably not be necessary.

Ambient Context

ploeh — Tue, 24 Jul 2007 00:06:00 GMT

These days, I'm becoming increasingly enamored with the idea of implementing cross-cutting concerns using Thread Local Storage (TLS) or the current call context. For the most typical aspects of software, such as security and logging, the .NET framework already takes this approach:

Security can be handled by reading or writing to Thread.CurrentPrincipal
Logging can be handled by using the methods of the Trace class. You configure the Trace class by adding or removing TraceListerners.

In both cases, you set up the context at the application's entry point (either imperatively or, in the case of logging, in the application's configuration), which makes it implicitly available for all other code in the call stack. Even if you are writing code in the data access layer (which is usually quite deep in the call stack), you can still access and use this ambient context. The nice thing about this approach is that it's just there, accessible by a static property or method on a well-defined class (i.e. Thread or Trace). This means that even though you might need to be able to address your cross-cutting concern in any layer in your application, you don't need to pass it around as a parameter value in every single method you implement.

Even though it's not passed to you explicitly as a parameter, you are allowed to assume that it's there; it's the responsibility of the hosting application to set up the ambient context in the correct way.

Since both IPrincipal and TraceListener are abstractions (one is an interface and the other an abstract class), these implementations offer full substitutability, so you can easily create test doubles of them when unit testing.

Obviously, you can just use Thread.CurrentPrincipal and the Trace class for security and logging, but if you have your own aspect to implement, you can use a similar approach. As always, I prefer to illustrate how to do this with an example. In order to avoid the usual suspects of security and logging, consider the following scenario:

We are building an application where you need to be able to control which features are available to the user at any given time. This is not a question of role-based security, but rather a decision which may be made based on licensing etc. One scenario may be a trial edition with certain features disabled (but where you can upgrade the installation to a full version without reinstalling). A more advanced scenario may be a SmartClient application (perhaps in a SaaS scenario) where the user can pay to upgrade the application's feature level for a limited time.

To keep things simple, we'll assume that we only need three levels of feature access:

public enum FeatureLevel

    Basic = 0,

    Silver,

    Gold

Since we must allow developers to create an implementation where a level of access is only available for a limited time, the API should allow a great deal of flexibility. With the pseudo-requirements set forth so far, our goal could be to enable our fellow developers to write code akin to this:

FeatureContext.Current.Demand(FeatureLevel.Silver);

The Demand method simply asserts that the requested feature level is currently enabled, and otherwise throws an exception. The FeatureContext class in itself is an abstract class:

[Serializable]

public abstract class FeatureContext

    private const string contextSlotName_ = "FeatureContext";

    protected FeatureContext()

    public static FeatureContext Current

get

            FeatureContext ctx = CallContext.LogicalGetData(

                FeatureContext.contextSlotName_) as FeatureContext;

            if (ctx == null)

                ctx = new BasicContext();

                CallContext.LogicalSetData(

                    FeatureContext.contextSlotName_, ctx);

            return ctx;

set

            CallContext.LogicalSetData(

                FeatureContext.contextSlotName_, value);

    public abstract void Demand(FeatureLevel requestedLevel);

There are two noteworthy details in this code: The first is the abstract Demand method that needs to be implemented by a derived class (I'll get back to that).

The second is the static Current property. Since it allows any client to read and write an instance of the abstract FeatureContext, substitutability is ensured. It also ensures that you can implement the Demand method in as simple or complex fashion as you need, and put this implementation on the ambient context. To keep things simple, I've not implemented the property in a thread-safe manner, which (obviously) you should do in a real production implementation.

In this implementation, I store the the FeatureContext in the CallContext; I could also have used TLS by using Thread.SetData, but there's a difference: Using TLS, the context only exists on the current thread; if you spawn a new thread, you must manually copy the context to the new thread if you want it to be available there as well. This happens automatically when you use the CallContext, but to store and retrieve an object via the CallContext, the class must be serializable, which is why FeatureContext is decorated with the Serializable attribute. Any derived class must also be serializable.

If no current context is not already set, it defaults to BasicContext:

[Serializable]

public class BasicContext : FeatureContext

    public BasicContext()

        : base()

    public override void Demand(FeatureLevel requestedLevel)

        if (requestedLevel > FeatureLevel.Basic)

            throw new FeatureUseDeniedException();

This implementation only allows basic functionality. If the requested feature level is higher than Basic, a FeatureUseDeniedException is thrown. Notice the Serializable attribute, which allows an instance of the class to be stored in the CallContext.

You can implement SilverContext and GoldContext classes in similar ways, so when you want to enable Gold functionality indefinitely, you'd do something like this:

FeatureContext.Current = new GoldContext();

This will enable Gold funtionality until you explicitly change the FeatureContext to something else. If you want to enable a scenario where there's a time limit, you could create an expiring implementation of FeatureContext:

[Serializable]

public class ExpiringGoldContext : FeatureContext

    private DateTime timeLimit_;

    public ExpiringGoldContext(TimeSpan allottedTime)

        : base()

        this.timeLimit_ = DateTime.Now + allottedTime;

    public override void Demand(FeatureLevel requestedLevel)

        if (DateTime.Now > this.timeLimit_)

            new BasicContext().Demand(requestedLevel);

            return;

        new GoldContext().Demand(requestedLevel);

When you set the current FeatureContext to ExpiringGoldContext, it will allow Gold features to be used until the time limit expires. Even when the time limit expires, the current instance remains, but its behavior changes to only allow Basic functionality. Obviously, you could optimize the implementation of ExpiringGoldContext by defining static readonly instances of BasicContext and GoldContext, but to keep things simple for the example, I just create new instances of these classes when I want to delegate implementation to them.

Whenever your need to ensure that a member allows execution only if a certain functionality level is granted, you can demand the level as a guard clause in your code:

public void DoSilverStuff()

    FeatureContext.Current.Demand(FeatureLevel.Silver);

    // Implementation here

To come full circle to aspect-oriented development, such a use of ambient context is an obvious candidate for the Enterprise Library Policy Injection Application Block, which would then allow declarative use of the ambient context by decorating your members with attributes (similar to PrincipalPermissionAttribute), but I'll leave that as an exercise for the interested reader (or, perhaps, a later post).

Imperative Configuration

ploeh — Wed, 11 Jul 2007 23:56:00 GMT

How can I unit test my application with different configuration settings? A couple of months back, a reader asked me this question, and while I provided an immediate response via email, I think that the question deserves a post of its own.

In .NET, using XML-based application configuration is easy and built into the framework, so it's common for applications or libraries to depend on a configuration file. The configuration system in .NET is essentially read-only. While you can write to a config file, this will not reload the configuration settings for a running application. To reload the configuration settings, the AppDomain must be restarted.

In unit testing, this is not particularly practical, since a test suite executes all test cases in a single AppDomain. As a consequence, once a configuration section is read from the configuration file, it cannot be changed by changing the declarative (that is: XML) configuration. This is a challenge if you need to test your code with different, mutually exclusive configuration settings.

This is another good reason for providing an imperative way to define configuration settings for your code. Essentially, file-based configuration should be treated as a fall-back mechanism that only applies if the configuration isn't supplied imperatively.

As a simplistic example, imagine that you are developing a library of Newtonian mechanics to calculate projectile trajectories. Your first take on the Trajectory class looks something like this:

public class Trajectory
{
    private const double gravitationalAcceleration_ = 9.80665;
    private double range_;
 
    public Trajectory(double angleInDegrees,
        double initialVelocity)
    {
        double angleInRadians = angleInDegrees * Math.PI / 180;
        this.range_ =
            (Math.Pow(initialVelocity, 2) * Math.Sin(angleInRadians)) /
            Trajectory.gravitationalAcceleration_;
    }
 
    public double Range
    {
        get { return this.range_; }
    }
}

For simplicity's sake, the Trajectory class only exposes the Range property, which provides the maximum range given the firing angle and initial velocity of the projectile. The formula used in the constructor is the formula for calculating the range, but the details of that are not terribly important besides the point that you need to know the gravitational acceleration. The constant value of 9.80665 is Earth's gravity.

Now, a new requirement occurs: Some customers on Mars want to use your library to calculate trajectories, but obviously while using Mars' gravitational acceleration (which is 3.69). For that reason, you decide to move the gravitational acceleration value to a custom configuration section.

<configuration>

  <configSections>

    <section name="newtonianConfiguration"

             type="Ploeh.Samples.Newtonian.NewtonianConfigurationSection, Ploeh.Samples.Newtonian" />

  </configSections>

  <newtonianConfiguration gravitationalConstant="9.80665" />

</configuration>

In this example, the custom configuration section is obviously very simple, but in a more realistic scenario, it would be much more complex. Here, we only have the single gravitationalConstant attribute, which is set to Earth's gravity.

Instead of using a constant, the Trajectory constructor must now read the gravitational acceleration from the application configuration.

public Trajectory(double angleInDegrees,

    double initialVelocity)

    NewtonianConfigurationSection config =

        ConfigurationManager.GetSection(

        NewtonianConfigurationSection.ConfigurationName)

        as NewtonianConfigurationSection;

    if (config == null)

        throw new InvalidOperationException("No configuration");

    double angleInRadians = angleInDegrees * Math.PI / 180;

    this.range_ =

        (Math.Pow(initialVelocity, 2) * Math.Sin(angleInRadians)) /

        config.GravitationalConstant;

The modified constructor now loads the custom configuration section from the configuration file and throws an exception if it's not found. Otherwise, it uses the gravitational acceleration from the configuration section to calculate the range.

This ought to effectively address the need to support other gravities, since the Mars customers can now configure their applications to use Mars' gravitational acceleration. The main problem that's left now is that you can't really unit test the Trajectory class with both Earth's and Mars' gravity.

While you can add an app.config file to your unit test project, you can only add one. Once the configuration is read from the configuration file, it's cached and never refreshed for the lifetime of the AppDomain, so you can't change the configuration from test case to test case.

In the very simple example, one solution could be to create two different unit test projects - one with Earth gravity, and one with Mars gravity, but if you have a more complex configuration schema with more possible permutations, this becomes impractical very fast.

The best solution is to provide an imperative override to the configuration. This is easily done in the example:

public class Trajectory

    private double range_;

    public Trajectory(double angleInDegrees,

        double initialVelocity)

        NewtonianConfigurationSection config =

            ConfigurationManager.GetSection(

            NewtonianConfigurationSection.ConfigurationName)

            as NewtonianConfigurationSection;

        if (config == null)

            throw new InvalidOperationException("No configuration");

        this.Initialize(angleInDegrees,

            initialVelocity, config.GravitationalConstant);

    public Trajectory(double angleInDegrees,

        double initialVelocity, double gravitationalAcceleration)

        this.Initialize(angleInDegrees, initialVelocity,

            gravitationalAcceleration);

    public double Range

        get { return this.range_; }

    private void Initialize(double angleInDegrees,

        double initialVelocity, double gravitationalAcceleration)

        double angleInRadians = angleInDegrees * Math.PI / 180;

        this.range_ =

            (Math.Pow(initialVelocity, 2) * Math.Sin(angleInRadians)) /

            gravitationalAcceleration;

The range calculation has been moved to the private Initialize method, and an overloaded constructor that takes the gravitational acceleration as a parameter has been added to the Trajectory class. This makes it very simple to test range calculations for both Earth and Mars in the same test suite:

[TestMethod]

public void UseEarthTrajectory()

    Trajectory t = new Trajectory(45, 250, 9.80665);

    Assert.AreEqual(4506.5515567659924923447632608029, t.Range, 0.001);

[TestMethod]

public void UseMarsTrajectory()

    Trajectory t = new Trajectory(45, 250, 3.69);

    Assert.AreEqual(11976.740873755886253401835401505, t.Range, 0.001);

In a more realistic scenario with a complex configuration schema, the overloaded constructor should take a parameter representing the entire configuration hierarchy instead of just a value type as the gravitational constant from the example.

Variations where you supply the configuration imperatively by setting a property or calling a method just after you've created your object, but before you begin using it, are valid alternatives in some cases.

As an example, the WCF ServiceHost uses this approach, where you can either use the class without further code, in which case it will use the configuration from the configuration file, or you can add bindings and other configuration settings imperatively (with the AddServiceEndpoint method and other members).

Designing your component with imperative configuration as an option not only lets you unit test different configuration scenarios much easier, but also provides more flexibility for any client consuming your code.

Using Decorators For Inter-Layer Communication

ploeh — Mon, 18 Jun 2007 22:33:00 GMT

While I hope that my previous post made it clear that Data Transfer Objects are not my first choice for transferring complex data between layers, I still owe my faithful reader(s) an outline of a better alternative.

One option is to define an abstraction (interface or base class) and pass objects implementing the abstraction between layers, using the Decorator design pattern to transform or enrich the implementation along the way. While I'm not saying this is the only, or even the best way, this approach at least has the benefit that it saves you from writing a lot of transformation and mapping code if your layer hierarchy is deep and you perform a fair amount of content enrichment along the way.

Using the same scenario as my former post as a scenario, we start out by defining an abstract Product class (it could also have been an interface):

public abstract class Product

    protected Product()

    public abstract int ProductId { get;}

    public abstract string Name { get;set;}

    public abstract decimal ListPrice { get;set;}

    public abstract decimal Discount { get;set;}

    public abstract int InventoryCount { get;set;}

One thing I aleady like better than the DTO option is that now I can model the Product with a read-only ProductId property. Creating a root Product instance in the data access layer is easy:

public Product ReadProduct(int productId)
{
    using (IDataReader r = this.GetProductReader(productId))
    {
        if (!r.Read())
        {
            throw new ArgumentException("No such product.", "productId");
        }
 
        return new DataProduct(r);
    }
}

The DataProduct class simply derives from Product. The constructor reads the data off the data reader and into private fields that backs the properties of the class:

internal DataProduct(IDataReader productReader)
{
    this.productId_ = (int)productReader["ProductId"];
    this.name_ = (string)productReader["Name"];
    this.listPrice_ = (decimal)productReader["ListPrice"];
    this.discount_ = (decimal)productReader["Discount"];
    this.inventoryCount_ = (int)productReader["InventoryCount"];
}

The DataProduct class is an internal class created and returned by the data access component. It constitutes the root of a potential Decorator hierarchy. As the Product passes up through application layers, we can add more features in each layer, and instead of writing cloning or wrapper code each time, we can define a single, basic Decorator:

public abstract class ProductDecorator : Product
{
    private Product innerProduct_;
 
    protected ProductDecorator(Product p)
        : base()
    {
        this.innerProduct_ = p;
    }
 
    public override int ProductId
    {
        get { return this.innerProduct_.ProductId; }
    }
 
    public override string Name
    {
        get { return this.innerProduct_.Name; }
        set { this.innerProduct_.Name = value; }
    }
 
    public override decimal ListPrice
    {
        get { return this.innerProduct_.ListPrice; }
        set { this.innerProduct_.ListPrice = value; }
    }
 
    public override decimal Discount
    {
        get { return this.innerProduct_.Discount; }
        set { this.innerProduct_.Discount = value; }
    }
 
    public override int InventoryCount
    {
        get { return this.innerProduct_.InventoryCount; }
        set { this.innerProduct_.InventoryCount = value; }
    }
}

The nice thing about this class is that you only have to write it once, and then you can keep reusing it to add more and more features.

In the next layer up from the data access layer (the business logic layer), we can just consume the Product instance served by the data access component. To add features to a Product instance, we can define another abstraction:

public abstract class BusinessProduct : ProductDecorator

    protected BusinessProduct(Product p)

        : base(p)

    public abstract decimal DiscountedPrice { get;}

    public abstract bool InStock { get;}

Creating an implementation of BusinessProduct is easy:

public class SimpleBusinessProduct : BusinessProduct

    public SimpleBusinessProduct(Product p)

        : base(p)

    public override decimal DiscountedPrice

        get { return this.ListPrice - this.Discount; }

    public override bool InStock

        get { return this.InventoryCount > 0; }

Notice that this is the same business logic as in my former post, but instead of dealing with arbitrary 'companion' classes or predefined DTOs, this approach is simply an extension of the Product class.

Since I defined BusinessProduct as an abstract class, I can use the abstraction in the next layer (e.g. the User Inteface Process layer) without referencing any particular implementation, effectively decoupling the UIP layer from the business logic layer:

public class ProductView : BusinessProduct

    private BusinessProduct innerProduct_;

    public ProductView(BusinessProduct bp)

        : base(bp)

        this.innerProduct_ = bp;

    public override decimal DiscountedPrice

        get { return this.innerProduct_.DiscountedPrice; }

    public override bool InStock

        get { return this.innerProduct_.InStock; }

    public virtual Color Color

get

            if (this.InStock)

                return Color.Black;

            return Color.Red;

Notice that this is simply a new Decorator that decorates BusinessProduct instead of simply decorating Product, but it still does this by leveraging the original ProductDecorator class (BusinessProduct derives from ProductDecorator).

Each time you want to extend the functionality of an abstract data object, you simple create a new abstract Decorator that inherits from a simpler Decorator. The more application layers and the more features you need to add along the way, the more you save on this approach, since you only have to write the basic plumbing code once.

While this is certainly not the only alternative to DTOs, it's at least an attractive alternative for applications with many layers and a lot of features added along the way.

What's An Entity, Anyway?

ploeh — Mon, 18 Jun 2007 22:29:00 GMT

These days, I seem to be encountering a lot of entities. Not in the sense of non-corporeal beings as usually depicted in certain science fiction TV shows, but in the sense of data structures. Sometimes, they are called business entities.

Although the concept of entities differ from project to project, I think I have identified at least one common trait of all the entities I come across: They contain (structured) data, but no behavior. Usually, these entities are being consumed and manipulated by something called the business logic. In some cases, entities are even used to transfer data from one layer of an application to the next layer (some people then call them data transfer objects). Since architecture diagrams with vertical columns adjacent to layers appear to be much in vogue these days, I'll use one as an example:

The idea here is to have a single definition for data that spans multiple levels so that you only have to write the data structure implementation once. The code in the different layers interact with the entities: The data access layer creates and stores the entities, the business logic layer modifies the data, and the UI layer presents the data. Pretty clean architecture, right?

No.

So what's wrong with it? First of all, what does the name entity tell us? Nothing, really. Entity is a synonym for object, but surely, the term business objects is so last year that any self-respecting architect would never use such a term. On the other hand, an object with structure but no behavior sounds awfully familiar.

Your code takes one or more structures of data as input, operate on them and outputs other structures. Fowler calls this pattern a Transaction Script; I call it procedural programming, and since I have had my experiences with this programming style early in my career, I never want to go back. Domain Model is where it's at.

In Patterns of Enterprise Application Architecture, Fowler wrote that "a Data Transfer Object is one of those objects our mothers told us never to write." While the pattern itself is valid, it's only supposed to be used for communication across process boundaries, not across layers in the same process.

If you are still not convinced about my arguments, let's take a look at an example. Imagine that you want to model a product catalog. Since we are modeling with entities, we create Product and Category classes. Both are just dumb classes with default constructors, read/write properties, and no behavior. To decouple data access, we also define a data access interface:

public interface ICatalogDataAccess

    Category ReadCategory(int categoryId);

    Product ReadProduct(int productId);

Implementing this interface is fairly straightforward, and goes something like this:

using (IDataReader r = this.GetProductReader(productId))

    if (!r.Read())

        throw new ArgumentException("No such product.", "productId");

    Product p = new Product();

    p.ProductId = (int)r["ProductId"];

    p.Name = (string)r["Name"];

    p.ListPrice = (decimal)r["ListPrice"];

    p.Discount = (decimal)r["Discount"];

    p.InventoryCount = (int)r["InventoryCount"];

    return p;

This code is actually fairly benign - trouble only starts to appear in the business logic layer. Imagine that we need the business logic to implement the calculation of the discounted price, and whether the product is in stock (yes, rather inane business logic, I know). Since the Product entity is just a structure without behavior, it's necessary to create another class to implement this business logic:

public class ProductOperator

    private Product product_;

    public ProductOperator(Product p)

        this.product_ = p;

    public decimal DiscountedPrice

        get { return this.product_.ListPrice - this.product_.Discount; }

    public bool InStock

        get { return this.product_.InventoryCount > 0; }

Now you are left with the problem of how to pass this information on to the next layer.

One alternative is to create an abstraction of ProductOperator (say; IProductOperator) and pass that to the next layer together with the Product entity. That approach can quickly grow quite unpleasant, since each layer adding content to the entity needs to define yet another auxiliary class to be passed along with the ProductOperator and the Product entity.

Another alternative is to model the Product entity to include properties for this information from the start. That would mean that the data access component would fill in only the properties of the Product entity that comes from the database, and a variant of ProductOperator would then fill in the DiscountedPrice and InStock properties in the business logic layer:

public partial class ProductOperator

    public ProductOperator()

    public void UpdateDiscountedPrice(Product p)

        p.DiscountedPrice = p.ListPrice - p.Discount;

    public void UpdateInStock(Product p)

        p.InStock = p.InventoryCount > 0;

Beware: Here be dragons.

One problem with this approach is that you'd end up with a lot of properties whose values may or may not be null (DiscountedPrice and InStock, in this case), so you always need to check for null before reading and using a property value.

The other problem with this design is that it railroads your components into a particular usage scenario. In the end, you model the entity in order to communicate it across your process boundary (via a UI, service interface, etc.). This boundary has a particular usage scenario; e.g. you need to show product information in a UI. Such a usage scenario then becomes the driver for the entity structure: You need to show the discounted price, so you need a property for that, etc. If you need to display product information in another screen, you include properties for this screen as well. In the end, you end up with a data structure that carries around a lot of data that may or may not be used in any particular scenario.

There are lots of nicer ways to pass data between layers in extensible ways, and in a future post, I'll describe one such approach.

State Your Dependency Intent

ploeh — Sun, 03 Jun 2007 00:11:00 GMT

There are several different ways to implement Dependency Injection (DI), and Martin Fowler describes four of them in his excellent article on IoC/DI. In this article, the first three approaches (Constructor, Property, and Interface Injection) are mainly described as a background for introducing the Service Locator pattern. In Fowler's example, a generic Service Locator is a registry (basically an in-memory table), but these days you most commonly see it implemented as a factory.

Consider this simple interface:

public interface IMyInterface

    void DoStuff();

Here's a class that uses a Service Locator to get an instance of IMyInterface:

public class ImplicitConsumer

    public void PerformOperation()

        IMyInterface mi = ServiceFactory.Create<IMyInterface>();

        mi.DoStuff();

The ServiceFactory class has a static method that returns an instance of the requested interface. Although not explicitly shown, the ImplicitConsumer class has a default constructor, since no constructor is defined and the C# compiler then automatically creates one.

Now, imagine yourself in a situation where you need to consume an instance of the ImplicitConsumer class and call its PerformOperation method. Also imagine that you have just been handed the class in a binary form, with documentation, but without source code. In this scenario, you would probably write code like this:

ImplicitConsumer ic = new ImplicitConsumer();

ic.PerformOperation();

Writing the first line is very straightforward, since there's only one way to create a new instance of the class. Next, with the ic instance, IntelliSense will quickly help you to find and invoke the PerformOperation method, and that's it: The code compiles and you are happy.

At run-time, however, this code is going to fail, since the Service Locator has not been configured. At this point, you may resort to the documentation, and if you are lucky, the documentation will tell you that the PerformOperation method expects the Service Locator to be configured to return an instance of IMyInterface. If you aren't so lucky, you will have to fire up Reflector to figure out what to do.

Depending on the Service Locator's implementation, this configuration may be done in the configuration file or in code. Here's how it might look in code:

ServiceFactory.Preset<IMyInterface>(new StubMyInterface());

ImplicitConsumer ic = new ImplicitConsumer();

ic.PerformOperation();

Here we have what looks like two pieces of totally unrelated code, yet they are very closely related at run-time. If you came by this code without prior knowledge, you'd probably mistake the first line of code for a piece of lava flow and delete it. If you were the author of those three lines, you might attempt to protect yourself from this risk by applying a comment to the first line, but that would be an apology.

In my opinion, an API should always strive to steer developers in the right direction. With respect to DI, the API should clearly state its intent to consume a particular dependency. Constructor Injection does this very explicitly:

public class ExplicitConsumer

    private IMyInterface mi_;

    public ExplicitConsumer(IMyInterface mi)

        if (mi == null)

            throw new ArgumentNullException("mi");

        this.mi_ = mi;

    public void PerformOperation()

        this.mi_.DoStuff();

With this implementation, any developer is forced to do the right thing. There's only a single constructor, and IntelliSense will show that it expects an instance of IMyInterface. While a developer could pass null as a parameter, he or she would do so in spite of the knowledge that was just communicated by IntelliSense (and there would still be a run-time error). There would be no need to read the documentation or fire up Reflector, because the class makes it very clear that it needs a working instance of IMyInterface to perform its work, and as a developer, you must supply it:

ExplicitConsumer ec =

    new ExplicitConsumer(new StubMyInterface());

ec.PerformOperation();

The only drawback of Constructor Injection that I have ever been able to identify is the need to initialize all dependencies at once if you have a complex hierarchy of dependencies, as described in my former post. If lazy initialization is a necessity, you can use Provider Injection, which is a variation of Constructor Injection. Although this is currently my favorite DI strategy, it's less well-known and more difficult to explain.

In any case, the main point is that if a component expects to consume a dependency which will be supplied at run-time, it should clearly state that intent through its API, instead of relying on out-of-band discovery mechanisms. Although the API may end up looking more complex, it's ensuring that mistakes are much harder to make. Even if there's a slightly more pronounced learning curve to get started with an API that uses Constructor Injection, it's easier to use in the long run. A developer with no prior knowledge of the component will sooner be able to produce code that compiles with a component relying on a Service Locator, but he or she will sooner be able to produce code that works with Constructor Injection.

Code As Dependency Configuration

ploeh — Wed, 30 May 2007 17:33:00 GMT

In his article on Inversion of Control and Dependency Injection, Martin Fowler has a quite interesting section towards the end where he talks about how to configure loosely coupled systems. One of his points is that in some cases, it makes more sense to tie it all together using code than by using a configuration system.

When I introduce the concept of Code As Configuration for most people, they seem to instantly stop listening to what I'm saying. Configuration (the ability to change the behavior of the application without changing its code base) is good, so why would you ever want not to enable configuration? In .NET, this notion is particularly strong because System.Configuration makes it so easy to create a rich configuration object model backed by XML configuration files.

With Dependency Injection, the configurable entities are types (defined in various assemblies). Because of Dependency Injection, each library in your application can be compiled in isolation, since its volatile dependencies are being injected at run-time. A design pattern such as Constructor Injection is fairly simple and intuitive to use as long as you use it in isolation during development (e.g. while unit testing), but when it comes to tying everything together in an executable application, all these dependencies must be loaded into an object hierarchy such as this one:

In this example, each class is defined in a separate assembly. Note that the arrows indicate usage, not dependencies. For the application to run in the desired configuration, ClassC must consume an instance of ClassE, and so forth. However, ClassC only knows about Abstraction5, which is being injected into it via its constructor:

public class ClassC : Abstraction3

    private Abstraction5 a5_;

    public ClassC(Abstraction5 a5)

        : base()

        this.a5_ = a5;

    protected override string DoStuffCore()

        StringBuilder builder = new StringBuilder();

        builder.AppendLine("I am really Class C. My dependency says:");

        builder.Append(this.a5_.DoStuff());

        return builder.ToString();

The other classes are implemented in a similar way; ClassB, for example, only communicates with Abstraction3 and Abstraction4 and doesn't have any knowledge of ClassD or ClassC (let alone that in this configuration, ClassC consumes ClassE).

The executable must somehow construct the correct object graph. A common approach is to use the app.config file to define this hierarchy (for an example, Spring.NET supports this option). To properly identify which type to instantiate when an abstraction is requested, an assembly-qualified type name is provided in the configuration file, and reflection is used to create instances of the configured types.

This very common approach comes with a rather painful drawback: Since the executable application has no dependencies on any of its servers, none of the containing assemblies are automatically copied to the output directory. Although the application compiles, it crashes when executed because Fusion is unable to locate the assemblies specified in the configuration file.

To work around this, you can either put all of your assemblies in the GAC or copy them to the relevant output directory, but both of these options are either repetitive or requires automation. In any case, this drawback can be a bit counter-productive during development.

Another approach is simply to code the desired configuration into the top-level executable. Whether this is a viable option depends on your reason for isolating your volatile dependencies in the first place. If your motivation is genuinely to support plug-ins or other extensibility models, configuration-driven Dependency Injection is certainly the right approach, and hard-coding a particular configuration is not an option. For other scenarios, however, this solves the problem of managing and deploying the correct assemblies.

In my example, the client will create the entire object hierarchy like this:

static void Main(string[] args)

    Abstraction1 a1 = Program.CreateAbstraction1();

    Abstraction2 a2 = Program.CreateAbstraction2();

    Console.WriteLine(a1.DoStuff());

    Console.WriteLine(a2.DoStuff());

    Console.ReadKey(true);

private static Abstraction1 CreateAbstraction1()

    return new ClassA();

private static Abstraction2 CreateAbstraction2()

    Abstraction5 a5 = new ClassE();

    Abstraction4 a4 = new ClassD();

    Abstraction3 a3 = new ClassC(a5);

    Abstraction2 a2 = new ClassB(a3, a4);

    return a2;

Since all implementations use Constructor Injection, the client can construct the entire object tree by starting with the leaves and working its way to the root of the tree. Notice that although this creates an object hierarchy as illustrated above, the dependency hierarchy is flattened:

Apart from the top-level executable, each assembly only has a dependency on an assembly containing the abstractions (base classes and interfaces). Since such an assembly is considered a stable dependency, isolation has been achieved for all libraries. The only assembly with volatile dependencies is the top-level executable, but that's commonly where your UI resides, so it's not going to be testable in any case (and should be kept as minimal as possible).

Since the top-level executable has all relevant dependencies for the desired configuration, all required assemblies will automatically be part of the build.

Obviously, if you ever need to run the application in a different configuration, you will need to change the code, compile and redeploy, but that's not particularly different from the pure configuration scenario. Even if you use a configuration file, you will still need to compile and deploy your new or changed modules. In my opionion, it's the overhead of actually deploying even a single file that carries the greatest cost; whether you copy one or all of your files is merely a question of network or disk transfer time.

For applications where you control the entire code base and no extensibility support is required, the Code As Configuration technique can make development teams more productive without sacrificing significant functionality.

Reasons For Isolation

ploeh — Wed, 30 May 2007 13:22:00 GMT

Object-oriented applications above some level of complexity are almost always modelled as a layered architecture. While the typical three-layer architecture remains the most widely known, n-layer architecture is also often utilized. Here's a typical design almost anyone can create (in Visio or Power Point, that is):

There seems to be an almost universal agreement that layering is the correct things to do, but do you know why layering is considered such an attractive design feature?

When I ask this question of people, most answer that this enables them to replace a certain implementation with another implementation. What's even more interesting is that the typical implementation of this design is best illustrated like this:

No clear separation of logic is implemented, modules tend to trample over each others' domains, but worst of all, there's a strong hierarchy of dependencies in place: Most assemblies have dependencies on other assemblies in the solution, and few of of the projects can be compiled without also compiling all the dependent projects. The only projects that can typically compiled without volatile dependencies are the ones in the bottom layer, but those are the ones you most need to be independent of.

When confronted with this fact, most project members don't think this is a big deal, since the ability to replace one implementation with another isn't important in their current project. To paraphrase a typical response: "Yes, it would be nice to be able to replace our relational database with XML files without recompiling, but we are never going to need this, so why bother?"

This attitude suggests to me that people are missing the point.

The reason why layering is important is because each module must be able to exist in isolation. This means that it should be possible to compile a project without having to load any other projects containing volatile dependencies. If you ever find that you have to load 35 projects into your solution to compile a single project, you are doing something wrong. Ideally, you should be able to define a self-contained solution containing a small subset of your projects; about five projects, and certainly no more than ten.

If the ability to replace one implementation with another is not the sole reason for isolation, then what is?

Personally, I can think of at least three independent reasons:

It's nice to have the ability to replace one implementation with another. Yes, I know I just implied that it's wrong to think that you don't need isolation if you don't need this feature, but I didn't say that this ability isn't valuable in some projects. In many Enterprise/Line of Business applications, this feature may not matter, but other application types (such as shrink-wrapped software) often offer some extensibility model where such a feature could be very valuable to customers.
In large projects, it enables development teams to work independently of each other. One team can work on the data access layer while another team works on the business logic. Even when it's not important that you can replace your complex data access component when you deploy the application, it's very valuable for the business logic team to be able to replace the data access component with a simple, temporary implementation. This will allow the business logic team to work without being blocked by the data access team.
Unit testing becomes possible. By definition, a unit is (a part of) a module isolated from its dependencies. When you can replace one implementation of a dependency with another, you can also replace it with a test double. Since unit testing is by far the most cost-effective type of test, this property alone makes isolation very attractive.

If just a single of these reasons seems valuable to you, isolation should be one of your top priorities as you are implementing your design.

Authorizing Services

ploeh — Sun, 20 May 2007 15:05:00 GMT

If you look at the default authorization model for WCF, you will notice that it expects you to implement centralized authorization. While centralized and pluggable authentication makes a lot of sense to me, that's not the case with authorization.

Does it really make sense to decouple authorization from implementation? Are you only going to check access rights at the perimeter and leave the rest of your code wide-open? Can you even fully authorize an operation at the perimeter?

My claim is that for a secure and maintainable solution you should answer no to all these questions. In this article, I'll will explain why I think so.

While it makes a lot of sense to decouple authentication (who you are) from implementation, authorization (what you can do) is tightly coupled with what you are trying to do. Put in other words: Authenticating a user requires no knowledge of the context; either the user's credentials are acceptable, or they are not. Authorizing an action, on the other hand, requires knowledge of not only the identity, but also the operation being attempted. As documented, the OperationContext provided to a ServiceAuthorizationManager contains information about which service and operation is being invoked, so you could certainly implement centralized authorization logic; basically, it's going to be one big switch statement.

Working with centralized authorization will mean having to switch back and forth between the authorization manager and the implementation code. To me, that's not particularly productive, when you can tie authorization and implementation together as simple as this:

[PrincipalPermission(SecurityAction.Demand, Role = "Administrator")]

public void MyMethod()

    // Implementation goes here...

With the PrincipalPermission attribute, you can define role-based security declaratively. This has the benefit of succinctly defining security in the most intuitive place. You could implement the same authorization logic in a centralized authorization manager, but it would require imperative code inspecting message properties. From a code maintainability perspective, decoupling authorization from implementation doesn't make a lot of sense to me.

Is checking access rights only at the perimeter a good idea, then? While the case could be made for turning away unauthorized calls at the service boundary, securing a system only at its perimeter is not considered to be particularly effective. In their book Writing Secure Code, Michael Howard and David LeBlanc endorse defense in depth as an important principle in secure systems. Multiple checkpoints should exist at separate layers of an application. This helps thwart a would-be attacker, who would then otherwise have full control of a system once he or she gets past the perimiter.

Pluggable authorization logic implemented at the perimiter doesn't follow this principle. What is worse is that since a WCF authorization manager is pluggable, a service operator may even accidentally deploy a service without correctly configuring the authorization manager.

Another scenario deals with extensibility. Imagine that your service delegates all work to a business logic component, and that you would like to reuse the business logic in other contexts: A web site, admistrative application, ETL job, etc. In these scenarios, your business logic will probably not be hosted by WCF, but rather accessed by in-process calls, so a WCF authorization manager will be bypassed in these cases.

Authorization logic should in my opinion be implemented as close to the resource it's protecting as possible; most likely in the data access layer itself, so that even if an application bypasses the default business logic component, authorization is still being checked. For that reason, checking only at the perimeter is not particularly secure.

As it turns out, it's not even possible to perform any sort of authorization check at the perimiter, since additional data may be required. A simple role-based access check as in the example given above can also be performed at the perimeter, but more complex access rules cannot. Consider this example:

Imagine a service providing details about registered users. This service contains a GetUserData operation that returns user data for the requested user ID. The authorization logic for such an operation could be something like this:

A member of the Administrator role can request data on any user.
A member of the User role can only request his or her own data.

However, in this example, user IDs are particular to the application and not equal to the callers' credentials. The callers' credentials may represent a Windows account, while users IDs are defined be a table key in a database. While there's a one-to-one correspondence between credentials and user IDs, this relationship is defined at the data level. As such, the message available to a perimeter-based authorization manager contains the requested user ID, as well as the caller's credentials, but no data indicating any relationship between the two are available at that level.

In imperative code, however, you could implement the above authorization rules like this:

public UserData GetUserData(Guid userId)

    UserData user = DataAccess.FindUser(userId);

    PrincipalPermission administratorPermission =

        new PrincipalPermission(null, "Administrator");

    PrincipalPermission selfPermission =

        new PrincipalPermission(user.DisplayName, "User");

    administratorPermission.Union(selfPermission).Demand();

    return user;

In this case it's necessary to first get the data from the data store, since a security decision requires more data than supplied by the caller. Notice that administratorPermission allows any user to make the call if he or she is a member of the Administrator role. On the other hand, selfPermission only allows users through whose credentials are the same as the DisplayName of the user they requested. The Union of these two IPermission objects is then demanded, ensuring that at least one of them is satisfied.

Authorization logic like this example cannot be implemented at the perimeter, since required data is not available.

By now, I hope I have demonstrated why I think centralized authorization managers don't make a lot of sense in a complex, n-layer architecture.

Note that the use of PrincipalPermission and PrincipalPermissionAttribute requires that Thread.CurrentPrincipal is populated with an instance of IPrincipal representing the caller. Using IPrincipal and thread local storage to represent and flow information about the caller is considered a .NET best practice, since the framework itself contains support for it (such as declarative role-based security).

Interestingly, a WCF ServiceAuthorizationManager is a very correct place to map foreign user credentials to IPrincipal objects, as I've described in an earlier post.