Specification Pattern

The Specification Pattern. Yet another one I find useful in daily business. But a few enhancements can make it even more useful and a lot nicer to handle.

1, 2, many!

The CompositeSpecification is most often implemented with two fields for spec1 and spec2 or left and right. The AndSpecification and OrSpecifications evaluate these fields with their respective operator.

public class Or<T> : CompositeSpecification<T>
{
  // ...

  public override bool IsSatisfiedBy(T candidate)
  {
    return spec1.IsSatisfiedBy(candidate) || spec2.IsSatisfiedBy(candidate);
  }
}

This can result in a degenerated tree structure when you link many specifications with the same operator (e.g. a.Or(b).Or(c)...Or(n)).

To avoid this I decided to change the behavior of the composite. Instead of two fields it uses a list of children. If you try to link two specifications the code checks wether either one of them is of the same type as the composite and adds the other composites children instead of the composite itself to the list.

Sounds more complicated than it is. Let’s see some code.

public abstract class CompositeSpecification<T> : Specification<T>
{
  private readonly List<Specification<T>> children;
  public CompositeSpecification()
  {
    this.children = new List<Specification<T>>();
  }
  public IEnumerable<Specification<T>> Children
  {
    get { return children; }
  }
  public int Count
  {
    get { return this.children.Count; }
  }
  protected void Add(Specification<T> specification)
  {
    this.children.Add(specification);
  }
  protected void AddRange(IEnumerable<Specification<T>> specifications)
  {
    this.children.AddRange(specifications);
  }
}

public class Or<T> : CompositeSpecification<T>
{
  public Or(Specification<T> specification, Specification<T> other)
  {
    this.Include(specification);
    this.Include(other);
  }
  public override string Description
  {
    get { return " || "; }
  }
  public override bool IsSatisfiedBy(T candidate)
  {
    foreach (Specification<T> specification in this.Children)
    {
      if (specification.IsSatisfiedBy(candidate))
      {
        return true;
      }
    }
    return false;
  }
  private void Include(Specification<T> specification)
  {
    Or<T> or = specification as Or<T>;
    if (or != null)
    {
      this.AddRange(or.Children);
    }
    else
    {
      this.Add(specification);
    }
  }
}

And this is how two specifications can be linked with an Or operator.

public abstract class Specification<T>
{
  // ...
  
  public abstract bool IsSatisfiedBy(T candidate);
  public Specification<T> Or(Specification<T> other)
  {
    return new Or<T>(this, other);
  }
}

In the end this will put all successive Or’s in a single list, which makes finding the right specification in the tree a lot easier.

What do we have?

Generating a human readable representation of the specification tree can be tedious but is often beneficial if you need to see “what you have”. The easiest way to traverse a tree structure is a Visitor. The same pattern is used by Microsoft in their expression trees.

We add an Accept method and a property for the description of the specification to the base classes

public abstract class Specification<T>
{
  // ...
  public abstract string Description { get; }
  public virtual void Accept(SpecificationVisitor<T> visitor)
  {
    visitor.Visit(this);
  }
}

public abstract class CompositeSpecification<T> : Specification<T>
{
  // ...
  public override void Accept(SpecificationVisitor<T> visitor)
  {
    visitor.Visit(this);
  }
}

public class Or<T> : CompositeSpecification<T>
{
  // ...
  public override string Description
  {
    get { return " || "; }
  }
}

Define a base class for the SpecificationVisitor

public abstract class SpecificationVisitor<T>
{
  public abstract void Visit(Specification<T> specification);
  public abstract void Visit(CompositeSpecification<T> composite);
}

And the implementation of a PrettyPrinter becomes as simple as that

public class PrettyPrinter<T> : SpecificationVisitor<T>
{
  private readonly StringBuilder sb;
  public PrettyPrinter()
  {
    this.sb = new StringBuilder(250);
  }
  public override void Visit(Specification<T> specification)
  {
    this.sb.Append(specification.Description);
  }
  public override void Visit(CompositeSpecification<T> composite)
  {
    this.sb.Append("(");
    foreach (Specification<T> child in composite.Children)
    {
      child.Accept(this);
      this.sb.Append(composite.Description);
    }
    int l = composite.Description.Length;
    this.sb.Remove(sb.Length - l, l);
    this.sb.Append(")");
  }
  public override string ToString()
  {
    return this.sb.ToString();
  }
}

And this gives you a nice and friendly printout of your graph

var spec = new AlwaysFalse().Or(new AlwaysTrue().And(new Odd())).Or(new AlwaysTrue());
var printer = new PrettyPrinter<T>();
spec.Accept(printer);
string friendly = printer.ToString(); // (false || (true && Odd) || true)

First time I tried to attach some zipped source code and found out that WordPress won’t let me… Get the source code here (project TecX.Common folder Specifications and the test suite that puts them to use in TecX.Common.Test).

Composition over Inheritance: Custom Collections

Composition over inheritance is a known but unfortunately not very well understood OOD principle.

All too often I see code like this:

public class MyFooList : List<Foo> { /* .. */ }

or this:

public class MySomething
{
  public List<Foo> Foos { get; set; }
}

The derived class adds a method or two. Maybe a property. And it carries all the weight of the super-class List<T>. The property of type List<Foo> is there for anybody to fill with content of unverified qualities. Why?!

List is a powerful class but it does not give you any control over the objects that are added to it. What if your custom collection needs to protect invariants like “You can only add Foos with a Bar > 7?” Or you can only append to your collection but not remove objects from it. There is no easy way to model this when you are inheriting from List<T> or providing raw lists as part of your API.

If you don’t need the majority of the 30-some methods and the ~10 properties why would you show them? They just blur your interface. A simple custom collection that only offers what your consumers need to know is simple enough to write. If you implement IEnumerable<T> you can even unleash all the power of LINQ to select items from your collection.

If you have many or very complex invariants encapsulate them in validators to protect your collection. Let the collection tell its consumers about the rules a Foo instance violates when they are trying to add it to the collection.

[TestMethod]
public void Should_NotifyOnViolatedInvariants()
{
  var collection = new MyFooCollection(new IFooValidator[] { new NotNullValidator(), new MinBarValidator(7) });
  
  IFooValidator violatedInvariant;
  Assert.IsFalse(collection.Add(null, out violatedInvariant));
  Assert.IsInstanceOfType(violatedInvariant, typeof(NotNullValidator));

  Assert.IsFalse(collection.Add(new Foo() { Bar = 1 }, out violatedInvariant));
  Assert.IsInstanceOfType(violatedInvariant, typeof(MinBarValidator));
  Assert.IsTrue(collection.Add(new Foo { Bar = 8 }, out violatedInvariant));
}

public class MyFooCollection : IEnumerable<Foo>
{
  private readonly IEnumerable<IFooValidator> validators;
  private readonly List<Foo> foos;
  public MyFooCollection(IEnumerable<IFooValidator> validators)
  {
    this.validators = validators ?? new IFooValidator[0];
    this.foos = new List<Foo>();
  }
  public bool Add(Foo foo, out IFooValidator violatedInvariant)
  {
    violatedInvariant = this.validators.FirstOrDefault(v => v.ViolatesInvariant(foo));
    if (violatedInvariant == null)
    {
      this.foos.Add(foo);
      return true;
    }
    return false;
  }
  public IEnumerator<Foo> GetEnumerator()
  {
    return this.foos.GetEnumerator();
  }
  IEnumerator IEnumerable.GetEnumerator()
  {
    return this.GetEnumerator();
  }
}
public interface IFooValidator
{
  string Description { get; }
  bool ViolatesInvariant(Foo foo);
}
public class MinBarValidator : IFooValidator
{
  private readonly int minBar;
  public MinBarValidator(int minBar)
  {
    this.minBar = minBar;
  }
  public string Description
  {
    get { return string.Format("foo.Bar must be greater than {0}", this.minBar); }
  }
  public bool ViolatesInvariant(Foo foo)
  {
    return foo.Bar <= this.minBar;
  }
}
public class NotNullValidator : IFooValidator
{
  public string Description
  {
    get { return "foo must not be null."; }
  }
  public bool ViolatesInvariant(Foo foo)
  {
    return foo == null;
  }
}
public class Foo
{
  public int Bar { get; set; }
}

You are still using the list under the covers. But your custom collection (just a couple of lines long!) is now stream-lined to only provide the functionality that is really needed. If you expose a raw List<T> anybody can modify the contents of that list. There is no way to enforce the collections invariants. With the custom collection your intentions became clearer and you made using your API safer. Isn’t that worth the bit of extra effort?

IntelliSense for custom ConfigurationSections

To be frank: I don’t like XML for configuration purposes. I think it’s a plague and nothing less. It is verbose and prone to typos. It does not give you any type safety. Thus I wage a constant war against XML config files in my projects.
But sometimes you can’t avoid XML for one reason or another. And if you can’t avoid it you have to cope with its shortcomings. Configuration in code gives you (among many other things I value) IntelliSense support. You get help with possible values for variables, properties or parameters, method names and much more. To get (some of) the same convenience for config files you have to provide xsd schema files. Established frameworks sometimes ship with those schemas. But if you write custom config sections you are completely on your own.

Rob Seder has a great post on writing custom configuration sections. The last paragraph explains how you can create xsd’s for your components.

While playing with Enumeration Classes I also wanted to see how I can use them with config files. So I wrote a custom config section for evaluation purposes.

public class MyConfigSection : ConfigurationSection
{
  private readonly ConfigurationProperty myEnum;
  public MyConfigSection()
  {
    this.myEnum = new ConfigurationProperty(
      "myEnum", 
      typeof(Numbers),
      Numbers.None,
      new EnumClassConverter<Numbers>(),
      null,
      ConfigurationPropertyOptions.IsRequired);
    this.Properties.Add(this.myEnum);
  }
  public Numbers MyEnum
  {
    get { return (Numbers)base[this.myEnum]; }
    set { base[this.myEnum] = value; }
  }
}

Numbers is an enumeration class from a prior article.

[side note] I love the way Microsoft’s engineers allow you to control how the configuration system handles your custom classes by letting you specify a TypeConverter [/side note]

I followed the steps outlined in Rob’s post and created a schema using the XML –> Create Schema option from Visual Studio. I stripped away all the fluff that belonged to the config file schema until all that was left was the part for my custom section. I then added comments and allowed values for Numbers along with some more comments. I ended up with the following xsd.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           targetNamespace="http://tecx.codeplex.com/tecx/2012/enum"
           attributeFormDefault="unqualified"
           elementFormDefault="qualified">
  <xs:element name="mySection">
		<xs:annotation>
			<xs:documentation>This demonstrates IntelliSense for config files</xs:documentation>
		</xs:annotation>
    <xs:complexType>
      <xs:attribute name="myEnum" use="required" >
        <xs:annotation>
          <xs:documentation>Predefined set of numbers</xs:documentation>
        </xs:annotation>
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="None">
              <xs:annotation>
                <xs:documentation>NaN</xs:documentation>
              </xs:annotation>
            </xs:enumeration>
            <xs:enumeration value="One">
              <xs:annotation>
                <xs:documentation>Number 1.</xs:documentation>
              </xs:annotation>
            </xs:enumeration>
            <xs:enumeration value="Two">
              <xs:annotation>
                <xs:documentation>Number 2.</xs:documentation>
              </xs:annotation>
            </xs:enumeration>
            <xs:enumeration value="Four">
              <xs:annotation>
                <xs:documentation>Number 4.</xs:documentation>
              </xs:annotation>
            </xs:enumeration>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
</xs:schema>

That’s a lot of xml for one single property but there you are… One important thing to notice is the targetNamespace attribute in the schema element. This will be used to reference the schema in your config file.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="mySection" type="TecX.EnumClasses.Test.MyConfigSection, TecX.EnumClasses.Test"/>
  </configSections>
  <mySection myEnum="Four" xmlns="http://tecx.codeplex.com/tecx/2012/enum" />
</configuration>

The section contains a reference to the targetNamespace of your custom schema. Now you need to add the xsd to the list of schemas for your config file. VS did that automatically for me when I placed the schema file in the same folder as the config file. If your’s doesn’t you can add the schema manually. Right click in the editor window for your app.config, select Properties from the context menu and the properties view will show up. It lists a setting called Schemas where the path to the DotNetConfig.xsd will already be listed. Click the […] button and add your custom schema using the dialog that pops up.

IntelliSense for custom configuration sections

And finally Visual Studio will give you some help with the tedious task of handling configuration through XML.

On top of writing the code for the configuration section you have to put some effort into writing the schema. I would not make that investment until the API is mostly stable for the current release. But then it definitely makes sense and developers that use your components will love you for that. Its the kind of documentation that does not force them to leave their working environment, lookup something in a .chm help file or a wiki page but instead they can stay focused on their current task.

Enumeration Classes as Flags

In my last post I talked about serializing Enumeration Classes for use with WCF. In this post I’m gonna show you how to add a feature that real enums have but enumeration classes don’t. Yet!

Enums can be decorated with the FlagsAttribute. This allows you to combine single enum values using the ‘|’ operator. A sample from the System.Reflection namespace are BindingFlags.

BindingFlags flags = BindingFlags.Public | BindingFlags.Instance;

To find out wether a single value is part of such a combination you use the ‘&’ operator.

var flags = (BindingFlags.Public | BindingFlags.Instance) & BindingFlags.Public;

The result will be BindingFlags.Public.

To implement the same functionality for enumeration classes we need to define a class that implements both operators ‘|’ and ‘&’. This will be the base class for all flags classes

public abstract class Flags<T> : Enumeration where T : Flags<T>
{
  public Flags(int value, string displayName, string name)
    : base(value, displayName, name)
  {
  }
  public static T operator |(Flags<T> x, Flags<T> y)
  {
    return x.Or(y.ToEnumeration());
  }
  public static T operator &(Flags<T> x, Flags<T> y)
  {
    var f1 = x.ToArray();
    var f2 = y.ToArray();
    var f3 = f1.Intersect(f2).ToArray();
    if (f3.Length == 0)
    {
      return FromValue<T>(0);
    }
    if (f3.Length == 1)
    {
      return f3[0];
    }
    var or = f3[0].Or(f3[1]);
    for (int i = 2; i < f3.Length; i++)
    {
      or = or.Or(f3[i]);
    }
    return or;
  }
  protected internal virtual T[] ToArray()
  {
    return new[] { this.ToEnumeration() };
  }
  protected abstract T ToEnumeration();
  protected abstract T Or(T x);
}

To make our lives easier when implementing flags based on enumeration classes we will also use a generic helper class Or<T>.

public class Or<T> where T : Flags<T>
{
  private readonly List<T> flags;
  public Or(T x, T y)
  {
    this.flags = new List<T>();
    this.flags.AddRange(x.ToArray());
    this.flags.AddRange(y.ToArray());
  }
  public string Name
  {
    get
    {
      string[] names = this.flags.OrderBy(f => f.Value).Select(f => f.Name).ToArray();
      return String.Join(" ", names);
    }
  }
  public int Value
  {
    get { return this.flags.Sum(f => f.Value); }
  }
  public string DisplayName
  {
    get
    {
      string[] names = this.flags.OrderBy(f => f.Value).Select(f => f.DisplayName).ToArray();
      return String.Join(" ", names);
    }
  }
  public T[] ToArray()
  {
    return this.flags.ToArray();
  }
  public void Add(T x)
  {
    this.flags.AddRange(x.ToArray());
  }
}

Now we are armed to build a custom flags class with minimal effort.

public class Numbers : Flags<Numbers>
{
  public static Numbers None = new Numbers(0, "None");
  public static Numbers One = new Numbers(1, "One");
  public static Numbers Two = new Numbers(2, "Two");
  public static Numbers Four = new Numbers(4, "Four");

  private Numbers(int value, string name)
  : base(value, name, name)
  {
  }
  protected override Numbers ToEnumeration()
  {
    return this;
  }
  protected override Numbers Or(Numbers x)
  {
    return new OredNumbers(this, x);
  }
  private class OredNumbers : Numbers
  {
    private readonly Or<Numbers> flags;
    public OredNumbers(Numbers x, Numbers y)
      : base(-1, String.Empty)
    {
      this.flags = new Or<Numbers>(x, y);
    }
    public override string Name
    {
      get { return this.flags.Name; }
    }
    public override string DisplayName
    {
      get { return this.flags.DisplayName; }
    }
    public override int Value
    {
      get { return this.flags.Value; }
    }
    protected internal override Numbers[] ToArray()
    {
      return this.flags.ToArray();
    }
    protected override Numbers Or(Numbers x)
    {
      this.flags.Add(x);
      return this;
    }
  }
}

Admittedly this is much more code than you would have to write for simple flags based on an enum. But the additional power of enumeration classes can also be found in the flags classes. Think of a user selecting from a set of predefined filter criteria. As long as Microsoft does not make expressions serializable you have no way of dynamically building the desired filter on the client side and send it to the server for evaluation other than directly accessing your database (be it SQL or NoSQL) and let some LINQ provider do the translation from expression to native query for you. With flags classes you can combine an abstraction of your filters on the client side, send the flags and let WCF do the reconstruction of the filters on the server side.

The complete source code is available here (project TecX.EnumClasses and the test suite that puts them to use can be found in TecX.EnumClasses.Test). There is a separate solution file TecX.EnumClasses as well.

Enumeration Classes and WCF

During the last week I was working on a real fun project. It started after I stumbled across an old article by Jimmy Bogard, author of the famous AutoMapper library. In his post he talks about Enumeration Classes. What they are, how they work and what their advantages over simple enums are.

He started by stating that a certain question evolved from a discussion on ALT.NET: “What do you do about enumerations crossing service boundaries?”. His post is inspiring but he did not really give an answer to that exact question.

Although WCF is by no means the only way to implement “services” this unanswered question got me thinking: “What if I want to use functionality-enhanced enumeration classes in a WCF service and simple enums on the client side?”

I know that WCF was designed to “talk dirty” when it comes to conversion between client- and server-side objects. It doesn’t matter if you have classes on one and structs on the other side. They don’t have to have the same (number of) fields. Using the DataMemberAttribute you can name the fields differently or even forward information a certain client does not use in its contracts further down the stream when that client calls another service by implementing IExtensibleDataObject in your objects.

But can it talk enums on the client and enumeration classes on the server? As it turns out: Yes it can!

The SortOrder Enumeration Class

For the following sample I will use a modified version of the SortOrder enumeration class I grabbed from the Tarantino project Jimmy mentions in his article. One of the changes I made to the enumeration base class is to introduce a Name property in addition to the DisplayName. That allows you to handle enumeration classes in a very similar way to real enums. I also added non-generic overloads for the FromValue and FromName methods. This is the modified SortOrder enumeration class.

[Serializable]
public class SortOrder : Enumeration
{
  public static readonly SortOrder Ascending = new AscendingSortOrder();
  public static readonly SortOrder Descending = new DescendingSortOrder();
  private readonly IComparer comparer;
  public SortOrder()
  {
  }
  public SortOrder(int value, string displayName, string name, IComparer comparer)
    : base(value, displayName, name)
  {
    this.comparer = comparer;
  }
  public IComparer Comparer
  {
    get { return comparer; }
  }
  private class AscendingSortOrder : SortOrder
  {
    public AscendingSortOrder()
      : base(0, "Sort ascending", "Ascending", StringComparer.OrdinalIgnoreCase)
    {
    }
  }
  private class DescendingSortOrder : SortOrder
  {
    public DescendingSortOrder()
      : base(1, "Sort descending", "Descending", new DescendingStringComparer())
    {
    }
    private class DescendingStringComparer : IComparer
    {
      public int Compare(string x, string y)
      {
        return -StringComparer.OrdinalIgnoreCase.Compare(x, y);
      }
    }
  }
}

Control (De-)Serialization with IDataContractSurrogate

The task is not quite as easy as I thought at first. The WCF infrastructure gives us the IDataContractSurrogate interface. By implementing this interface you can control how WCF serializes and deserializes specific objects.

Serialization is easy. When WCF calls the GetDataContractType method you return typeof(string) and in your implementation of the GetObjectToSerialize method you return the value of the Name property of your enumeration class and the resulting XML looks exactly as if you were serializing a simple enum. But the real deal is the deserialization. WCF matches the incoming serialized enum to the enumeration class. So far so good. But WCF is not able to convert the serialized input value to the matching enumeration class. If you try to use that enumeration type directly without modifying it on the call to GetDataContractTye WCF will fail with an exception. It can’t do the deserialization with the information it has. But it won’t call GetDeserializedObject for help either. If you return typeof(string) WCF will fail as well telling you it can’t cast a string to your enumeration class type. Even if you implement an implicit or explicit cast operator from string to your enumeration you will get that exception. And it also won’t call GetDeserializedObject. A somewhat strange behavior but there you are.

But I was not willing to give up. If WCF can’t handle primitive values like strings and can’t handle your enumeration class directly but it can handle enums, why not try to treat the incoming value as a custom enum and convert that enum to your enumeration class? I know that sounds stupid. You don’t want to write and maintain code for an enumeration class and an enum on the server side. But you don’t have to. Some prior experiments with emitting IL code taught me that it is very easy to generate such an enum on-the-fly.

Reflection.Emit to the Rescue

So what I did is I created an IL generator that checks wether it already emitted an enum type for a specific enumeration class. If not it dynamically creates an enum type that has the same name as the enumeration class plus a short suffix. It also creates an enum member for every static field in your enumeration class (like SortOrder.Ascending) with the name of the field and the value of the enumeration class, decorates type and members with the DataContract- and EnumMemberAttributes and remembers that type for future use.

For SortOrder the generator creates the following enum:

[DataContract(Name="SortOrder")]
public enum SortOrder_Enum
{
  [EnumMember]
  Ascending = 0,
  [EnumMember]
  Descending = 1
}

See no Evil…

And all of a sudden everything works like a charm. The modified surrogate returns the enum type when asked for the DataContractType and you can handle conversion from enum to enumeration class by using the non-generic methods Enumeration.FromValue(Type, int) or Enumeration.FromName(Type, string) in the call to GetDeserializedObject.

public class EnumerationClassesSurrogate : IDataContractSurrogate
{
  private readonly EnumGenerator generator;
  public EnumerationClassesSurrogate()
  {
    this.generator = new EnumGenerator();
  }
  public Type GetDataContractType(Type type)
  {
    if (typeof(Enumeration).IsAssignableFrom(type))
    {
      Type enumType;
      if (this.generator.TryGetEnumByType(type, out enumType))
      {
        return enumType;
      }
    }
    return type;
  }
  public object GetObjectToSerialize(object obj, Type targetType)
  {
    Enumeration enumeration = obj as Enumeration;
    if (enumeration != null)
    {
      Type enumType;
      if (this.generator.TryGetEnumByType(obj.GetType(), out enumType) &&
          Enum.IsDefined(enumType, enumeration.Name))
      {
        return Enum.Parse(enumType, enumeration.Name);
      }
    }
    return obj;
  }
  public object GetDeserializedObject(object obj, Type targetType)
  {
    Type objType = obj.GetType();
    if (this.generator.IsGeneratedEnum(objType) &&
        typeof(Enumeration).IsAssignableFrom(targetType))
    {
      string name = Enum.GetName(objType, obj);
      return Enumeration.FromName(targetType, name);
    }
    return obj;
  }

  // other methods are not implemented for this sample
}

Serialization works in the same way. You map the enumeration class type to the generated enum type and convert the enumeration value to the matching enum value. All of this is completely transparent for client and server code.

[TestMethod]
public void Should_TransparentlyConvert_BetweenSimpleEnumOnClient_AndComplexEnumClassOnServer()
{
  IEnumerable sms = new[]
    {
      new SerializeMe2 { Text = "1" },
      new SerializeMe2 { Text = "3" },
      new SerializeMe2 { Text = "2" }
    };
  using (ServiceHost host = new ServiceHost(typeof(SortingService), new Uri("http://localhost:12345/svc")))
  {
    host.Open();
    var factory = new ChannelFactory(new BasicHttpBinding());
    var proxy = factory.CreateChannel(new EndpointAddress("http://localhost:12345/svc"));
    var result = proxy.Sort(sms, SortOrderEnum.Ascending).ToList();
    Assert.AreEqual("1", result[0].Text);
    Assert.AreEqual("2", result[1].Text);
    Assert.AreEqual("3", result[2].Text);
  }
}

[ServiceContract]
public interface ISortingService
{
  [OperationContract]
  IEnumerable Sort(IEnumerable itemsToSort, SortOrder sortOrder);
}
[ServiceContract(Name = "ISortingService")]
public interface ISortingServiceClient
{
  [OperationContract]
  IEnumerable Sort(IEnumerable itemsToSort, SortOrderEnum sortOrder);
}
[PutDataContractSurrogateBehavior]
public class SortingService : ISortingService
{
  public IEnumerable Sort(IEnumerable itemsToSort, SortOrder sortOrder)
  {
    return itemsToSort.OrderBy(s => s.Text, sortOrder.Comparer);
  }
}
[DataContract(Name = "SortOrder")]
public enum SortOrderEnum
{
  [EnumMember]
  Ascending,
  [EnumMember]
  Descending
}

What you get

Maybe you don’t consider sorting to be a worldshaking example to demonstrate the advantages of enumeration classes. But I believe that, within the boundaries of a HelloWorld! sample, it shows you quite nicely what this pattern has to offer. Enumeration classes are yet another tool in your toolbox. Use them when they seem to fit your requirements.

The posiblity to use simple enums in your clients while you reserve the much more powerful enumeration classes for the server side helps you to decouple client and server and reduce the complexity of your code. See how simple it is to sort values based on the additional information stored in your enumeration classes. The client does not have to know about that. And the server does not need to know that the client doesn’t know…

The complete source code is available here (project TecX.EnumClasses and the test suite that puts them to use can be found in TecX.EnumClasses.Test). There is a separate solution file TecX.EnumClasses as well.

The Invisible Guard

They are called Guards or Validators. It’s their duty to keep your business logic safe. Invalid input values are rejected by throwing exceptions at the caller to notify him about his wrong-doing. Guards enforce the contracts of your API. If you fail to get past them, it’s your problem, not that of the author of said logic.

But do you really want to see them in the StackTrace of each exception they throw? They are not the reason an exception occured. They just contain the location where the exception originated. But the cause for the exception is the call to a method using the wrong parameter values.

Hide Guards in StackTraces

I first saw that code in a colleague’s project. But it is also documented on StackOverflow.

Create a custom Exception that will be thrown by your Guard class. Override the StackTrace property and remove all lines that are related to that Guard class before you return the trace.

public static class Guard
{
  [DebuggerStepThrough]
  public static void AssertNotNull(object param, string paramName)
  {
    if (param == null)
    {
      throw new GuardNotNullException(paramName);
    }
  }
}
public class GuardNotNullException : ArgumentNullException
{
  public GuardNotNullException(string paramName)
    : base(paramName)
  {
  }

  public override string StackTrace
  {
    get
    {
      var stacktrace = base.StackTrace
        .Split(new[] { Environment.NewLine }, StringSplitOptions.RemoveEmptyEntries)
        .Where(l => !l.StartsWith("   at " + typeof(Guard).FullName));
      return string.Join(Environment.NewLine, stacktrace);
    }
  }
}

Hide Guards in the Debugger

With this little trick your Guards won’t show up in StackTraces. But you don’t want to step through them whenever you debug a method they guard either. After all they are not part of the logic of the method they just enforce the method’s invariants.
You might have noticed the DebuggerStepThroughAttribute on the AssertNotNull method. This attribute instructs the Visual Studio debugger to ignore this method completely.

It’s easy. It’s neat. It helps your developers and administrators to focus on the actual source of the problem instead of distracting them with the noise of your validation code.

Transparently Caching Queries

The How and the What are often discussed when it comes to caching. As always, there is no Silver Bullet that solves all issues at once.

TecX offers one solution for the following scenario: Say you have a datasource that provides access to your data via a set of IQueryable<T> properties. The interface might look like this:

public interface ICustomerRepository
{
  IQueryable<Customer> Customers { get; }
}

Now you want to add caching but you don’t want to have to change how the consumers work with that repository. So you need some transparent caching mechanism that isolates your consumers (and your developers) from the actual implementation of caching. You are then able to run your application without caching or you can use the new features from System.Runtime.Caching, the AppFabric Cache or something completely different.

Two classes from TecX.Caching (namely QueryInterceptor and QueryInterceptorProvider) allow for transparent interception of queries against an IQueryable<T>. They are wrappers for IQueryable and IQueryProvider that use the Expression property of the IQueryable to generate a unique cache key. A simple ToString() operation won’t give you a key that is “uniqe enough” so a technique presented by Pete Montgomery is used to partially evaluate the expression tree of the query.

The sample CachingCustomerRepository demonstrates how this interception can be used to introduce a transparent caching layer into your application and swap it out for arbitrary implementations using different caching technologies at any time.

public class CachingCustomerRepository : ICustomerRepository
{
  private readonly ICustomerRepository inner;
  private readonly ObjectCache cache;
  private readonly QueryInterceptor<Customer> customers;
  private readonly ExpirationToken expirationToken;
  public CachingCustomerRepository(ICustomerRepository inner)
  {
    this.inner = inner;
    this.cache = new MemoryCache(typeof(CachingCustomerRepository).Name);
    this.customers = new QueryInterceptor<Customer>(this.inner.Customers);
    this.customers.QueryProvider.Executing += this.OnQueryExecuting;
    this.customers.QueryProvider.Executed += this.OnQueryExecuted;
    this.expirationToken = new ExpirationToken();
  }
  public IQueryable<Customer> Customers { get { return this.customers; } }
  public void Add(Customer customer)
  {
    this.inner.Add(customer);
    this.expirationToken.Expire();
  }
  private void OnQueryExecuted(object sender, ExpressionExecuteEventArgs e)
  {
    IQueryable<Customer> cachedResult = this.cache[e.CacheKey] as IQueryable<Customer>;
    if (cachedResult == null)
    {
      var evaluatedQueryable = ((IEnumerable<Customer>)e.Result).ToList().AsQueryable();
      CacheItem cacheItem = new CacheItem(e.CacheKey, evaluatedQueryable);
      CacheItemPolicy policy = new CacheItemPolicy { SlidingExpiration = 1.Minutes() };
      ExternallyControlledChangeMonitor monitor = new ExternallyControlledChangeMonitor
        {
          ExpirationToken = this.expirationToken
        };
      policy.ChangeMonitors.Add(monitor);
      this.cache.Add(cacheItem, policy);
    }
  }
  private void OnQueryExecuting(object sender, ExpressionExecuteEventArgs e)
  {
    IQueryable<Customer> cachedResult = this.cache[e.CacheKey] as IQueryable<Customer>;
    if (cachedResult != null)
    {
      e.Handled = true;
      e.Result = cachedResult;
    }
  }
}

Using a framework like Moq you can easily mock your actual data access in order to run tests against your cache.

var mock = new Mock<ICustomerRepository>();
mock.SetupGet(r => r.Customers).Returns(
new[]
{
  new Customer { Id = 1, Name = "1" },
  new Customer { Id = 2, Name = "2" },
  new Customer { Id = 3, Name = "3" }
}.AsQueryable());
var cache = new CachingCustomerRepository(mock.Object);

// Actual testing code

mock.VerifyGet(r => r.Customers, Times.Once());

At the heart of the CachingCustomerRepository are the QueryInterceptor (comes in a generic and a non-generic version)

public class QueryInterceptor<T> : QueryInterceptor, IQueryable<T>
{
  public QueryInterceptor(IQueryable<T> wrapped)
    : this(wrapped, new QueryInterceptorProvider(wrapped.Provider))
  {
  }
  public QueryInterceptor(IQueryable<T> wrapped, QueryInterceptorProvider provider)
    : base(wrapped, provider)
  {
  }
  public IEnumerator<T> GetEnumerator()
  {
    var enumerable = this.Provider.Execute<IEnumerable<T>>(this.Expression);
    var enumerator = enumerable.GetEnumerator();
    return enumerator;
  }
}
public class QueryInterceptor : IQueryable
{
  private readonly IQueryable wrapped;
  private readonly QueryInterceptorProvider queryProvider;
  public QueryInterceptor(IQueryable wrapped, QueryInterceptorProvider provider)
  {
    this.wrapped = wrapped;
    this.queryProvider = provider;
  }
  public Type ElementType { get { return this.wrapped.ElementType; } }
  public Expression Expression { get { return this.wrapped.Expression; } }
  public IQueryProvider Provider { get { return this.queryProvider; } }
  public QueryInterceptorProvider QueryProvider { get { return this.queryProvider; } }
  IEnumerator IEnumerable.GetEnumerator()
  {
    var enumerable = (IEnumerable)this.Provider.Execute(this.Expression);
    var enumerator = enumerable.GetEnumerator();
    return enumerator;
  }
}

and the QueryInterceptorProvider.

public class QueryInterceptorProvider : IQueryProvider
{
  private readonly IQueryProvider wrapped;
  public QueryInterceptorProvider(IQueryProvider wrapped)
  {
    this.wrapped = wrapped;
  }
  public event EventHandler<ExpressionExecuteEventArgs> Executing = delegate { };
  public event EventHandler<ExpressionExecuteEventArgs> Executed = delegate { };
  public IQueryable<TElement> CreateQuery<TElement>(Expression expression)
  {
    var rawQuery = this.wrapped.CreateQuery<TElement>(expression);
    var interceptor = new QueryInterceptor<TElement>(rawQuery, this);
    return interceptor;
  }
  public IQueryable CreateQuery(Expression expression)
  {
    var rawQuery = this.wrapped.CreateQuery(expression);
    var interceptor = new QueryInterceptor(rawQuery, this);
    return interceptor;
  }
  public TResult Execute<TResult>(Expression expression)
  {
    string cacheKey = expression.GetCacheKey();
    object value;
    bool handled = this.NotifyExecuting(expression, cacheKey, out value);
    TResult result = !handled ? this.wrapped.Execute<TResult>(expression) : (TResult)value;
    this.NotifyExecuted(expression, cacheKey, result);
    return result;
  }
  public object Execute(Expression expression)
  {
    string cacheKey = expression.GetCacheKey();
    object value;
    bool handled = this.NotifyExecuting(expression, cacheKey, out value);
    object result = !handled ? this.wrapped.Execute(expression) : value;
    this.NotifyExecuted(expression, cacheKey, result);
    return result;
  }
  private bool NotifyExecuting(Expression expression, string cacheKey, out object result)
  {
    var e = new ExpressionExecuteEventArgs
      {
        Expression = expression,
        CacheKey = cacheKey
      };
    this.Executing(this, e);
    if (e.Handled)
    {
      result = e.Result;
      return true;
    }
    result = null;
    return false;
  }
  private void NotifyExecuted(Expression expression, string cacheKey, object result)
  {
    var e = new ExpressionExecuteEventArgs
      {
        Expression = expression,
        CacheKey = cacheKey,
        Result = result
      };
    this.Executed(this, e);
   }
}

The code above illustrates one possible solution for one problem: How can I introduce a completely transparent caching layer around my data access?

Explicit caching on the contrary allows you to optimize what you put in the cache and when. This video by the guys behind StackOverflow shows which performance improvements and hardware savings are possible when you make caching very explicit.

Whenever you introduce caching to your application there are some questions that need to be answered:

  • Do I really have to cache every query?
  • Can I reuse parts of my results?
  • Will I run this exact query often enough to justify caching?
  • What happens when data changes (e.g. by calling UpdateCustomer)?
  • How much does performance really improve by introducing caching?
  • Does caching have an influence on the consistency of my results?

Don’t use caching if you can’t reason that the benefits outweigh the costs. Caching can cause a lot of trouble if it’s not done the right way…

Get the source code for transparent caching here (project TecX.Caching and the test suite that shows how to use it in TecX.Caching.Test).