Yet another layer of indirection

REST Raiding. WebApi

2012-02-09T16:00:00.000+01:00

WebApi looked as one of the strongest contenders at first, just by its lineage (MSFT is his champion). But when I saw its pre-beta status I had second thoughts. And third thoughts remembering all the horror stories I have had with its father: Windows Communication Foundation. Since I spent less time than I wanted evaluating OpenRasta I gave WebApi a spin. And here are my thoughts.

Get It!

Getting WebApi up and running is simple enough: install the WebApi package and you are good to go. There are a number of other packages that add some interesting features, but I only went for the simple, barebones, server side of things.

Documentation

The walkthrough is pretty comprehensive but the site does not have a whole lot of “official” documentation. But the package comes with a pair of .chm files that are really handy.

And one cannot complain about the number of people writing about the product in their blogs. The information might be outdated, but it should give an idea of the activity of the community around the product, which is pretty nice, in my opinion.

The Services

Creating services (or APIs, as they are called in WebApi jargon) is a two step thing out-of-the-box.

Create a class decorated with the ServiceContract attribute that contains one or more related methods (and related means URL-related) and implement your logic:
```
[WebGet(UriTemplate = "")]
public Resources.Catalog[] GetCatalogs()
{
    // fancy population of 'resource'
    return resource;
}
```

And register the route corresponding to the resource you are serving when the application starts:

RouteTable.Routes.Add(
        new ServiceRoute(
            "catalogs",
            new HttpServiceHostFactory(),
            typeof(CatalogsApi)));

Some content negotiation is included out of the box by adding an Accept request header, being the default XML and JSON is also included. A nice touch is that it supports qualified values (see the spec), meaning that will return the supported type with the higher relative quality factor or default to XML. Another nice touch is the fact that the response includes the codification charset of the data, which helps with those “weird” characters that we all love (ñ, æ, å,…)

One of the things that impressed me the most was how the whole URL placeholder and extra request information is handled. If one wants to have another API hanging from an already defined base route (in this case, /catalogs) another method in the api class is created and decorated with the WebGet attribute, setting the UriTemplate property to a string that will contain the placeholder information for that route, including any query string information that we may want to get and that information will be set in the parameters defined for the method. Pretty nifty.

[WebGet(UriTemplate = "{catalogName}?lang={lang}")]
public Resources.Catalog Get(string catalogName, string lang)
{
    // even more fancy stuff
    return resource;
}

And the icing of the cake for those who need it? Easy OData support. Apparently it does not get on well with REST according to some, but it is a pretty popular format of delivering information.

Opinion

I was pleasantly surprised by how smooth WebApi looks like. That only mean they did a good job to come up with a nice to work with API on top of the configuration hell that WCF is. And that is a compliment, by the way.
It does what it does in a nice manner but I do not have an opinion about extensibility points and customizations as I did not push it. But I know from my light reading about the subject that it supports the concept of resource factory, allowing to use your IOC container of choice to inject the dependencies your service might have in an easy manner.

Probably one the nicest things one can say is that it gets the job done without getting in one’s way, with a simple api, meaningful defaults and adherence to the spec. Do not know about relative performance, compared to some of the other contenders, though.

I have very few bad things (if any) to say. The only but is the two step creation of services (service plus the route), but I am confident there might be an extension to have it in one single step.

Would I use WebApi? I cannot see why not.
Was it the one I chose? No, it was not. Only because I tried it by chance and expected worse (due to its WCF heritage) it did not get higher in my list of preferences.
Would I recommend its use? Yeah, give it a go. It may suit your needs.

REST Raiding. OpenRasta

2012-01-29T09:13:00.001+01:00

I had very high hopes for this one. I was really, really, ready to like it. I had the preconceived idea that this was going to be the one to be chosen. But…

Get It!

I really do not want to be mean or sound (too) rant-y. But I need to tell the whole story.

Let’s face it, looks matter. Compare these two sites. If they were a web-shop, from which you would buy from? If they were a web framework, which one projects quality and care? I do not intend to be cheap, but… seriously?

Ok, dodgy as it looks I bit the bullet and tried my luck finding a NuGet package. None. Nil. Zero. If you want a package, go install OpenWrap and let it take over the soul and guts from your .csproj. Not an option. Not for me, at least.
Ok, let’s find a binary download… Hitting the documentation page… Looks promising. Darn! It points to an apparently outdated source code repository. Well, it links to a list of the various repositories (and no links to them?). Fine, I know how the Web works and how to navigate GitHub, so stop complaining already! What? No binaries? I already broke my rules with this project, that is how ready to like it I was…
Cloning a couple of repositories and for once in my life I will read the doc first, as I know these guys can get funky with the build process. Oh dear, the instructions are outdated, there is no make.bat anywhere the new source tree. Some investigation tells me it is just a shortcut for msbuild. Fire it and… what is the result? An assembly with version 0.0.0.0. WTF?

Documentation

Being the most mature of the contenders I was expecting documentation to be more comprehensive and a wealth blog posts about how to get started. And I was not disappointed. I have little to none complaints in the documentation are.

The Services

Or handlers as they are called in Open Rasta are the classes that give access to our resources (the snapshots of information). They are truly POCOs, not needing any parent class, interface or attribute. Just name the methods wisely (correlating to HTTP verbs) or drive the default behavior with the configuration:

public class CatalogsHandler
{
    public CatalogCollection Get()
    {
        var resource = // get the resource 

        return resource;
    }
}

Speaking of which, one of the things that caught my attention when I first saw the framework was how much it relied in configuration and how “beautiful” was the API to handle it. I still think the effort they put in having an elegant configuration API was worthy, but having seen other frameworks in which configuration is superfluous it now seems almost like a waste. An exercise of waste, nonetheless.

public class Configuration : IConfigurationSource
{
    public void Configure()
    {
        using (OpenRastaConfiguration.Manual)
        {
            ResourceSpace.Has
                .ResourcesOfType<CatalogCollection>()
                    .AtUri("/catalogs")
                    .HandledBy<CatalogsHandler>()
                    .AsXmlDataContract().And.AsJsonDataContract();
        }
    }
}

And precisely with configuration came the last sin I committed with the framework. I got overconfident with the usage of the API and I forgot to include the using (OpenRastaConfiguration.Manual) statement. It may not look as much, but was capital in me giving up. Because it makes nothing work with a dreadful ArgumentNullException. Swallowing my pride again I dived in the code but could not make any sense of such a complex framework in such short period of time. So I reverted to community support, which turns out to be just StackOverflow (having read that the Google Groups is dead). I cannot complain, as I got my question answered and my thanks were given in less than a week.
By that time it was too late. I had seen enough, given up and tagged the framework as not viable for this project, thanks for asking.

Opinion

As one can imagine, I cannot be too happy about my time with the framework. And definitely was not the chosen one.

I tried very hard to like it. And being disappointed is partly my fault (a combination of high expectations and carelessness in reading the walkthrough).
I still believe is one the nicest frameworks to work with (once you get it up and running) with tons of places to hook up your own behavior and probably the most HTTP-friendly of them all (for example, requesting a resource in a format that is not configured, returns a proper 406 Not Acceptable code).
Their support for dependency management is kind of nice, but a bit verbose for my liking, but one can use of of the multiple hooks to have the IOC container of the month working with the framework and using all the coolness of the container for dependency registration.

Final sayings? It will be a killer framework once it settles down from the code/project/repository migrations turmoil, the new version is released and contributors fix the build and the doc. Until that happens, I won’t be getting anywhere close for production purposes.

And for pity’s sake! Include some sort of binary distribution for those that have not drunk from the OpenWrap chalice! I am not even suggesting a lame NuGet package. That would be too low, wouldn’t it?

REST Raiding. Nancy

2012-01-20T20:37:00.001+01:00

The first contender has a lovely woman’s name: Nancy.

Get it!

Getting Nancy up and running is as straightforward as it can be: create a Visual Studio Web Application project and install the nuget package. That is it.

Documentation

If the homepage was both elegant and useful, the documentation page is mouth watering. Simple and straight to the point. I was pleasantly surprised by the quality and the general vibe of the project.
This one is for those that claim that all OSS projects are a waste of time and lack documentation. Watch and cry.

The services

The service that returns all snapshots will be hosted in the url /catalogs and the one that returns the single detail in /catalogs/{catalog_name}. Resources are accessed in Nancy via modules (inheritors of NancyModule). Modules specify the URL and the HTTP method using a very neat indexer-function syntax. Since both services are related by the base URL, Nancy allows them to be grouped in the same module. No more configuration. As DRY and simple as it gets.

public class CatalogsModule : NancyModule
{
    public CatalogsModule() : base("/catalogs")
    {
        Get["/"] = parameters =>
        {
            var model = new[]
            {
                // define the model
            };

            return Response.BarebonesContentNegotiation(Request, model);
        };

        Get["/{catalogName}"] = parameters =>
        {
            string name = parameters.catalogName;
            CultureInfo language = Request.GetLanguage();
            var model = new Catalog
            {
                // model
            };
            return Response.BarebonesContentNegotiation(Request, model);
        };
    }
}

The /catalogs service is as simple as it gets as no argument is needed and uses no globalization. The only thing to point out is the Response.BarebonesContentNegotiation() method. Since Nancy does not implement (yet) any content negotiation or dynamic response formatting I developed a coarse method to find out whether to return XML or default to JSON, using the Nancy extensions .AsXml() and .AsJson(). It is clumsy and incorrect to an extreme, but since it is a POC I am not that embarrassed

public static Response BarebonesContentNegotiation<TModel>(this IResponseFormatter response, Request request, TModel model)
{
    bool acceptsXml = request.Headers.Accept
        .Any(a => a.IndexOf("xml", StringComparison.OrdinalIgnoreCase) >= 0);

    return acceptsXml ? response.AsXml(model) : response.AsJson(model);
}

For the /catalogs/{catalog_name} service there are some more interesting points. The first one is how route parameters are passed: that is what the function argument parameters is for. It cleverly uses dynamics to give access to the parameters by name. The other thing to point out is how the language is retrieved by extending the Nancy type Request. It should be easy enough since it exposes the Headers.AcceptLanguage property. Unfortunately, the language string is not parsed and weighed as it should be (yet) and the whole language string is passed in the first element of the collection. Well, since I am hosting Nancy in ASP.NET, I have all the “power” of the ASP.NET pipeline, and the weighed collection of languages can be accessed from the current HttpRequest.UserLanguages property (as long as testability is not a big concern).

public static CultureInfo GetLanguage(this Request request)
{
    HttpRequest http = HttpContext.Current.Request;

    return request.Query.lang.HasValue ?
        CultureInfo.GetCultureInfo(request.Query.lang.Value) :
        fromRequestOrInvariant(http);
}
private static CultureInfo fromRequestOrInvariant(HttpRequest request)
{
    return (request.UserLanguages ?? Enumerable.Empty<string>())
        .Select(CultureInfo.GetCultureInfo)
        .FirstOrDefault(ci => !ci.IsNeutralCulture) ?? CultureInfo.InvariantCulture;
}

In the above snippet one can see the clever use of dynamics to access query-string values (via a dynamic property with the key of the element that gives access to an object that let know whether the key has a value and which value is that).

Opinion

I have to admit I did not expect Nancy to be in such a good shape. The site looks gorgeous, documentation is available, community is growing and getting it up and running was a pleasure.

And what is more important: what they preach about low ceremony and simplicity cannot be more true. Most of the decisions make sense and look clean and approachable.

Its simplicity and youth make it lack some features I needed out of the box (such as dynamic response formatting) but I am certain that they will come.

Definitely a strong candidate to be taken very seriously.

UPDATE: I mentioned that how the Accept-Language header was not parsed correctly. Well, I created a new issue in their GitHub repository. Literally, minutes passed until I received feedback and hours until a pull request was issued with the fix. That, dear readers, is just another testimony of how awesome OSS can become.

RESTing in the Laurels

2012-01-11T20:56:00.001+01:00

Late Happy New Year to everyone!

For the first of 2012 let’s start with a short series of post about my adventures in finding a suitable web framework that makes likeable building REST services.

Corralling the Problem

Very rarely I write about concrete pieces of work I perform for my customers. This time I will break the rule, since this instance is about a proof of concept and no details are going to be given away.
Hopefully, someone that faces the same problem I faced when choosing, can find my journey interesting.

The proof of concept that scopes my findings is about creating simple URL-accessible read-only services. The information returned can be localized and be returned in various formats (XML and JSON), chosen by the consumer. Of the services to be built, the most “complex” is returning some sort of catalog information, having two endpoints: one that returns a snapshot of all of them and another endpoint that returns an extended version of a single one.

Non-Functional

As the reader can see, the functional requirements aforementioned are really simple. The non-functional requirements will, as well, be concrete.

For one, services need to be easy to develop. That rules out any framework that require extensive configuration and/or a great deal of ceremony (yeah, WCF I am looking at you!).

They also need to be HTTP-friendly. HTTP is a simple protocol but often misunderstood and underestimated. It covers all my requirements and a great deal more. For example, content negotiation is possible by expressing a rich set of formats accepted by the client in the headers, and extra formats can be defined to cover scenarios such as versioning. Likewise, localization is achieved with the same technique, including a weighted list of languages the client request the information in. Standard return codes provide a standard vocabulary of possible outcome and caching information can be specified.

Unfortunately, as rich as HTTP is, there are a wealth of bad clients to the protocol and shortcuts to be taken. Of those, we contemplate an easy way to override both the language and format of the response by the means of providing query-string arguments.

Nice-to-have extras that won’t probably be needed in the firsts versions are:

performance: it should lightweight enough to not become a problem when multiple clients perform requests. I want my code to be the scalability problem if they ever exists

extensibility: being able to easily get in the middle of the request pipeline at several stages in order to clean up the implementation of the service itself

coolness: it should be pleasant to work with and have a strong community that can provide knowledge when newer features that need advanced usages come. OSS is a plus, but not required. Oddly enough all the frameworks analyzed give access to their source code.

The Contenders

My time is limited for the task and there are lots of such frameworks that can be used for my problem. So I framed the products to evaluate to:

Nancy
OpenRasta
ServiceStack
WebApi

Contract Verification in NUnit. Comparisons

2011-12-12T19:43:00.001+01:00

Before anyone gets confused I am using a very broad definition of contract that it is not related at all with Code Contracts or Design by Contract.
What I mean by contract is the correct implementation of an interface that has become idiomatic. And before you ask, an interface is not a contract. I consider it part of the definition of a contract, but it lacks on the definition of the obligations of client and supplier and most importantly, the verification of such contract. And also before you ask, no, Code Contracts do not provide all the means to express complex obligations and outcomes when conditions are met.

One of such contracts that are pervasive in the .NET Framework is IComparable<T>. This useful interface define how two types can be compared for the purpose of sorting. As a matter of fact, it is so useful I have already written about it in the past in the Equality and Comparison series. One missing point in such series is how to check that we have fulfilled all the un-checked obligations (they are written, although scattered, in the interface and operators documentation).

Greener Pastures

Other testing frameworks, such as MbUnit, have had a way to verify those obligations for some time now, in the shape of contract verifiers. Their implementation of the idea is such that complete test fixtures are created for the verification purpose, making my endeavor of porting such functionality to the NUnit I use and almost love a pretty difficult one, as that would make me dig deeper than I feel compelled to in the inner working of its provider model. Besides, MbUnit’s syntax is not something I am very fond of, so a re-write was bound to happen.

Framing the Problem

The problem with comparison if not very complex, but it has to be done right.

In its simplest form, can be defined that types should return a negative value when compared against a bigger value, a positive value when compared against a smaller value and zero when compared against an equal value. Oh, and one has to keep in mind those pesky nulls. Oh, and one has a handful operators that could ne checked too. Oh, and one can compare types against other types, not just itself. Oh, and what we have to check is the same regardless of the type that implements the comparison we are testing.

It is easy to see that the number of combinations and the fact they are repetitive make the subject a perfect candidate to receive a helping hand.

The helping hand

Testing? Asserting for correctness? Looks like a task for Testing.Commons.NUnit. And indeed it is.

To start with, the problem can be presented like an assertion over several values and can be split into several parts: the implementation of IComparable<T>, being T the same type of the instance being asserted; the implementation of IComparable<T>, where T is not the same type as the instance being asserted; the implementation of comparison operators (<, >, >=, <=) against the same type as the instance being asserted; and the implementation of comparison operators against other types.

For the first two cases (the implementation of IComparable<T>), the custom constraint ImplementsComparableConstraint is used, maybe through the Must.Satisfy.ComparableSpecificationAgainst() extension. Its usage is really simple:

[Test]
public void ComparableToSelf()
{
    ComparableSubject target = //...
    ComparableSubject lessThanTarget = //... 
    ComparableSubject greaterThanTarget = //... 

    Assert.That(target, new ImplementsComparableConstraint<ComparableSubject>(lessThanTarget, lessThanTarget));
    Assert.That(target, Must.Satisfy.ComparableSpecificationAgainst(lessThanTarget, lessThanTarget));
}

[Test]
public void ComparableToOther()
{
    string eq = "eq", lt = "lt", gt = "gt";
    ComparableSubject target = //...

    Assert.That(target, Must.Satisfy.ComparableSpecificationAgainst(lt, gt, eq));
}

Provide either two or three instances of the type it is being compared against, one that is greater and one that is smaller and maybe one that is equal (when comparison to itself is not possible) and the combinations with null and not null values will be checked, providing a nice informative message when the type does not honor the contract.

A type that implements comparison operators to <ComparisonAgainstSelf>.
<target> must be <= (less than or equal to) <target>
  Expected: True
  But was:  False

A type that implements comparison operators to <String>.
<target> must be < (less than) "gt"
  Expected: True
  But was:  False

A type that implements IComparable<ComparableSubject> contract.
<target> must be greater than <lt>
  Expected: greater than 0
  But was:  -1

A type that implements IComparable<String> contract.
<target> must be less than null
  Expected: less than 0
  But was:  2

For the next two cases (the implementation of comparison operators) the custom constraint ImplementsComparisonConstraint is used, maybe using the Must.Satisfy.ComparisonSpecificationAgainst(). Again, the usage is really simple:

[Test]
public void ComparableToSelf()
{
    ComparisonAgainstSelf target = //...
    ComparisonAgainstSelf lt =  //...
    ComparisonAgainstSelf gt =  //...

    Assert.That(target, Must.Satisfy.ComparisonSpecificationAgainst(lt, gt));
}

[Test]
public void CanBeCreatedWithExtension_ComparableToOther()
{
    ComparisonAgainstReference target = //...
    string eq = "eq", lt = "lt", gt = "gt";

    Assert.That(target, Must.Satisfy.ComparisonSpecificationAgainst<ComparisonAgainstReference, string>(lt, gt, eq));
}

Again, just provide some instances to compare against and the right combinations of null and not null values would be checked. Error messages are likewise descriptive:

A type that implements comparison operators to <String>.
<target> must be < (less than) "gt"
  Expected: True
  But was:  False

Peek inside

The implementation itself is not terribly sophisticated once the problem is laid out. But there are a few important tricks that made the code so much easier to write (and much DRY-er).

One of the most important internals is the concept of ChainedContraints. This is just a simple chain-of-responsibility collection of constraints, that will be lazily executed until one of them fail, in which case, it will be surfaced in order for part of the error message to be written by that failing constraint.

Another interesting trick has to do with the fact that operators are static constructs and, therefore, there is no way to represent them as an interface or a generic class. What one can do is, instead, use code generation to build a delegate that represents the operation. I used (and changed a bit) a working implementation from MiscUtil after remembering an article about generic numeric operations. Basically it uses expression trees to generate the delegates the execute the operators. Clever thing indeed.

What else?

So far, nothing else. Go get, use and give feedback Testing.Commons.NUnit from its Nuget home. And stay connected, if you will, for more of these contract checkers/verifiers.

The Sixth OSSense

2011-12-01T16:55:00.000+01:00

I think I heard Mr. Hanselman say once that a .NET Open Source project does not exist if was not available through Nuget. That was said very, very early in the “packaging game”, but hey, bluffs are so cheap to make!
I did not take it seriously, of course. My lack of vision is legendary as I genuinely believed that finding the OSS project page, downloading a zip and adding an assembly reference was not that painful.

Oh, The Pain

I was wrong. Well, it is not that painful. But there are two steps in the process that can go horribly wrong.
First: finding the project. Even with pages and search engines devoted to the noble task of finding Open source projects, it is not a simple task to get a useful project found.
Second: downloading the binaries. Let’s face it, some of the people that write wonderfully handy tools and library are the same that do not know how to put together a nice, usable site for a fellow programmer to get a glimpse of what your useful piece of software can do and most importantly: how to even download it and get it running. And do not get me started with those projects that you have to build (compile is so unfashionable these days) in order to use. You should be writing OSS for people to use and for the clever, helping ones to contribute and improve it. But do not scare the hell of the less knowledgeable ones with a stupidly complex process when what they only want is use what you have created and, maybe, thank you.

Sucking a bit less

With the advent of packaging systems one of the steps is dead easy: finding the project becomes navigating the equivalent of an App Store (I hope I do not get sued for using the term) and read the more or less descriptive synopsis. That is how spoiled we have become.
Has “I want if now, fast and free” attitude, the instant gratification society, the epicureal orgy ruined the hippy OSS mindset? I do not think so. Everything evolves. What was acceptable some time ago it is not anymore, because something better/more accessible substituted it. And now, there is little to none excuse to be snobbish and not making your OSS project available for the masses.

Not so fast, Tiger

Is it enough? Not for me. Let me tell you how it goes with me, dear OSS project:

Summing it up: if you are not in Nuget chances of finding you are slim and if you are up there, you better have a half-decent project page.

Mind you, I am not being spoiled or arrogant. Do not take it personally. It will be a loss for us both if we do not get to know each other.

Less is… uh, less?

2011-11-30T16:50:00.001+01:00

Or so the saying goes, right? The ~~lazy~~ minimalist in me wants to say the utterly wrong “Less is More”.
Wrong as I am writing about Solid State. Which is a mystery itself… was there ever a Liquid one?

When talking about screen size (and many other less interesting subjects), the more and bigger the better. I, myself, have been spoiled for so long with plenty. I had been a happy member of the triple-monitor club, but my membership was put on hold when I moved out from the office office to work most of the time from my home office. Neither my desk nor my work laptop were up for it, but I was content enough with a dual arrangement: my valuable own 22” Samsung 225BW paired with the 20” HP LP2065 kindly provided by my employer (which is indeed a nicer display with a higher resolution then mine’s).

Nice and all that, but Julemand (the local version of good-old Santa Claus –amongst other names–) came early this year to take advantage of a nicely priced offer on a stunning 27” IPS-paneled Dell U2711. Julemand also left some seriously stiff neck that prevented me from jumping to unpack it and install it as soon as I got it, but that’s another story.

The Subject

Important thing is: boy it is huge! Place it facing upwards, pour some water and you have a freaking swimming pool. Do you think I am exaggerating? You may be right, but that’s how excited I am. I have not had the chance to spare the time it deserves, but I think it is a cutie. A cutie beefy screen. It does not matter it won’t earn many design prizes, but to me, hideous it is not.

My Relationship with the Subject

I have another confession. I know nothing of displays, calibration reviews and articles are gibberish to me. Reading them makes me feel as ignorant and visually-crippled as I feel hearing-challenged when I read discussions about audiophile headphones. I notice when something looks better when compared to another display, regardless of gamut, deltas and all the other jargon; just as I can hear differences between cheap-o headphones and the more expensive ones. Just do not make me choose amongst the quality ones as I simply cannot tell the difference.
I am not a designer. I like my home pictures stunning with real colors; I like my IDE windows happily sharing space and I hate scrolling in order to compare two-plus pieces of text. And I like, not, love, durable, quality pieces of equipment. And a quality display is one of the best investments one can do. You are going to be using it all the time and it is not going to become “obsolete” in 2-3 years time, like most of computing equipment you are currently using.

Facts of Life

Not all is candy floss and bouncing elves. Having a set up with such disparate displays comes with some quirks. the first one is that the difference of resolution makes impossible to span a window amongst the two displays. Not that I do it that often, but I have done it. I tried and it dos not work. It feels like major refraction. In fact, it is so big that makes dragging from one screen an uncannily weird experience.

But the most annoying one? Here’s a fact for you: it is impossible to calibrate two monitors side by side, unless they are the same model. And even there you’ll find subtle differences. And mine do not even use the same technology! They look crazy different. I will give it another frustrating shot when the new monitor image settles down (or is it just another urban legend?)

What else can I say? Oh, yeah, I like them big.

Tak for i går

2011-11-18T09:03:00.001+01:00

Con esta expresión danesa quiero dar las gracias a todos los asistentes a mi charla de ayer en el grupo de usuarios de Madrid.NET. Fue un placer y espero que lo hayáis disfrutado casi tanto como yo. Todo el material (código, enlaces y notas) está disponible en https://github.com/dgg/Dgg.Cqrs.Sample.

With this very Danish expression I want to thank all the attendance of my yesterday’s talk. It was awesome to speak to you all. I hope you enjoyed it as much as I did.

All the material from the talk (“slides” + code + all links) is available from https://github.com/dgg/Dgg.Cqrs.Sample,

Heading Motherland

2011-11-12T08:13:00.001+01:00

no, I am not leaving beautiful, cloudy Denmark. Well… I am, but just for some days.

Why anyone cares? Because it is not for (all) pleasure. As a matter of fact I will be doing something that I had liked to do for long time: speaking in a Spanish User Group. And the guys of Madrid .NET gave me the chance to do it (thanks Luis!)

The topic is one I am very fond of: CQRS. And one that I touched both in the Århus User Group and for my colleagues in Vertica.

Some time has passed since I envisioned the contents and new technologies have settled down, so I did a small rewrite of the sample code and I am going to try a new concept of slides.
Besides, timing is a bit off, as Eric Evans and Udi Dahan have been touching some of the same topics just this past week Ok, they have the names, the brains, the experience and the books. But I do have… uh, well… yes! the charms… and the jokes… and I hope they don’t speak Spanish, so I can have one more on my side.
Mix it with the fact that it is going to be my first time speaking technical jargon in my mother tongue and that (I hope) there’ll be familiar faces in the attendance and one can understand why I am thrilled about it.

So, what are you waiting for? Go and register and see me sweat my beers.

One After the Other

2011-10-31T23:47:00.001+01:00

That is an enigmatic title to write about serialization. Well, sort of, as one of the meanings of the word refers to that concept.
But writing about successions is not my intention. My intention is to write about the technique that allows objects to be persisted to another medium different from their native memory space and more specifically on how to test serialization of objects.

Freeze!

That is kind of what the values on an object do when it gets serialized. The values of the properties (the state of the object) are saved to the serialization medium (a stream) hoping they will be reconstituted into another instance of the type.

Once the type developer decides that his/her creation needs some flavor of serialization (the .NET framework offers some flavors on its own and third party libraries expand the choice) comes the time in which tests are written to either guide the implementation or check it against some assumptions.

In my limited experience designing serializable types I have faced several scenarios that I needed to test:

check that the type can be successfully serialized and de-serialized
check that the serialized form of an object contains the same values as the original
provide examples of the serialization format

Return Ticket, Please

The first two scenarios can be tested by serializing the type, then de-serializing it, and comparing the values to the original object (the one that was serialized in the first place). Depending of the flavor of serialization, different objects are involved in the serialization sprinkling some I/O over the mixture.

The serialization target is, more often than not, rather unimportant, as so are the mechanics of the serialization flavor. Remember, we are not testing serialization per se, we are checking that our type can be serialized and the state is maintained. Once we have taken from the picture the repetitive and unimportant code, we can use an abstraction of the process of serializing and de-serializing an object to a stream. And that abstraction is provided by IRoundtripSerializer, included in Testing.Commons.

public interface IRoundtripSerializer<T> : IDisposable
{
    string Serialize(T toSerialize);
    T Deserialize();
}

For that abstraction, some implementations are provided for popular types of serialization provided by the .NET Framework: BinaryRoundtripSerializer, XmlRoundtripSerializer, DataContractRoundtripSerializer and JsonRoundtripSerializer.

But such types only implement the mechanics. How about actual checking the properties of the de-serialized object? For that purpose the SerializationConstraint, provided by Testing.Commons.NUnit can be used. Its usage is really simple, just use the Must extension to choose the flavor and provide constraints to be used over the de-serialized instance:

Assert.That(new Serializable { D = 3m, S = "s" },
    Must.Be.BinarySerializable<Serializable>(
        Has.Property("S").EqualTo("s")
        .And.Property("D").EqualTo(3m)));

Assert.That(Serializable.DataContractString("s", 3m),
    Must.Be.DataContractDeserializable<Serializable>(
        Has.Property("S").EqualTo("s")
        .And.Property("D").EqualTo(3m)));

Assert.That(Serializable.DataContractString("s", 3m),
    Must.Be.XmlSerializable<Serializable>(
        Has.Property("S").EqualTo("s")
        .And.Property("D").EqualTo(3m)));

Assert.That(Serializable.DataContractString("s", 3m),
    Must.Be.JsonSerializable<Serializable>(
        Has.Property("S").EqualTo("s")
        .And.Property("D").EqualTo(3m)));

But imagine you want to check the serialization of your type using a third party library (like the excellent JSON.Net).
Well, nothing prevents the implementation of a IRoundtripSerializer that uses that third party library and the usage of the extension created for such scenario:

var serializer = MockRepository.GenerateStub<IRoundtripSerializer<Serializable>>();
serializer.Stub(s => s.Deserialize()).Return(serializable);
Assert.That(serializable,
    Must.Be.Serializable(serializer, 
        Has.Property("S").EqualTo("s")
        .And.Property("D").EqualTo(3m)));

By Example

For the third supported scenario (providing the serialization representation), the abstraction IDeserializer is provided by Testing.Commons:

public interface IDeserializer
{
    T Deserialize<T>(string toDeserialize);
}

And the same implementation for usual .NET serialization methods: XmlDeserializer, DataContractDeserializer and JsonDeserializer. Binary serialization is left out as it is pretty useless to provide a string representing the internal binary format. As before, one can use a constraint provided by Testing.Commons.NUnit, DeserializationConstraint instatiable by Must extensions.

Assert.That(Serializable.XmlString("s", 3m),
            Must.Be.XmlDeserializable<Serializable>(
                Has.Property("S").EqualTo("s")
               .And.Property("D").EqualTo(3m)));

Assert.That(Serializable.DataContractString("s", 3m),
    Must.Be.DataContractDeserializable<Serializable>(
        Has.Property("S").EqualTo("s")
        .And.Property("D").EqualTo(3m)));

Assert.That(Serializable.JsonString("s", 3m),
    Must.Be.JsonDeserializable<Serializable>(
        Has.Property("S").EqualTo("s")
        .And.Property("D").EqualTo(3m)));

And again, one can go custom implementing the interface and passing the instance to the extension:

var deserialized = new Serializable { D = 3m, S = "s" };

var deserializer = MockRepository.GenerateStub<IDeserializer>();
deserializer.Stub(s => s.Deserialize<Serializable>(serializationRepresentation)).Return(deserialized);
Assert.That(serializationRepresentation,
    Must.Be.Deserializable<Serializable>(deserializer, 
        Has.Property("S").EqualTo("s")
        .And.Property("D").EqualTo(3m)));

Using it Already

If you want to be testing the serialization of your types, you can get the latest version of Testing.Commons and Testing.Commons.NUnit from NuGet, which will be, from now one, the only way of getting the binaries (apart from building fro the source).

It…is…not…dead… Yet

2011-10-21T16:45:00.001+02:00

Sure not many people know what a Zune player is (and even less own one).
But those who know it and are more or less up to date on what is going on in the Microsoft arena keep reminding me “oh… and by the way, your Zune is dead. Microsoft killed it.”

But it isn’t…

…even though they program us to think it is. A company made a business decision of stop producing a product.

No one killed anyone.
No one knocked on my door with the intention to take away my device.
No one is erasing my devices' content remotely or making it fail on purpose with an invisible remote.

The only thing just happened is that no new units of the product are going to be produced. How that could affect me?

No more device updates

I have not experienced any bugs in my player. So if everything stays as it is I am as happy as I was before the announcement. Besides, when was the last time my player was updated with a major feature? Either I cannot remember or was not a major feature I use. No problem here for me.

No replacements

I think I have been so lucky that I never had to send something to repair after the warranty expired. Sure, devices crashed, but getting a newer device that does much more for a fraction of what the broken device cost or slightly higher than the repair itself was the way to go. Again, not a problem.

No more apps

Is this a joke? Since when app development was a factor for getting a Zune? If that was your case you should have been disappointed way earlier.
I bought my Zune knowing its lousy app support. But I did not need apps. I needed high capacity, good sound quality, lightness and long battery life. I got all of that when I bought it and those features are not going anywhere

No new versions

I like the device that much that when it does not work anymore I would buy the newest version, sure… or not, because a better solution from other vendor will be available, or I simply fancy a change. Besides, one of the biggest assets of the device is being able to use the Zune Marketplace accessible though the Zune software. That is alive, kicking an improving since Microsoft is leveraging its telephony strategy on it. When Microsoft removes support for Zune HD devices for newer versions of the Zune software (if it ever happens) then I will be pissed and I will rant in my blog again. Not now.

There I say it

I could not care less if there are going to be any more Zunes. I am happy with mine. And despite my (already tamed) impulses of getting a second unit as a replacement I have only one thing in my head: Microsoft blew it, once again. They killed a great device. When my beloved sexy Zune dies (let it live a long life) I will go for the best high capacity, longer battery life and lighter device I can get at that time, and sure as hell it won’t be a telephone.

Testing with ExpectedObjects

2011-10-16T21:13:00.001+02:00

The other day I read an interesting post about testing and a library that might help in some cases, its title is “Introducing the Expected Objects” library. I thought it might be useful and so I spent a spare evening writing some code to check whether is something that could be useful for my team.

The Problem

Imagine you are testing a complex object: multiple properties, graphs of objects, collections… and you want to test the outcome of some operation on it and you are using NUnit as your testing framework.
Which strategies are available?

Multiple Assertions

Most of the time, this is accomplished by using one or more assertions (watch it) that will check the values of certain properties. As the object is complex, the assertion might be complicated or I might not communicate correctly what we are trying to achieve.

IEqualityComparer

Another way of checking it is creating an instance with the members that are relevant to the test and providing a custom equality comparer to check just those values. This approach has some drawbacks:

it might no be easy to have the expected object in the desired state and in any case we are using a great deal of logic inside our test, which can lead to false positives
whenever the assertion fails, we have no useful feedback about what went wrong
the comparer has to be created ad-hoc and, as always, unless tested, needs to be taken as a source of false positives

Composite of constraints

This is probably your best choice as it is not too difficult to create something that communicates intent properly and the feedback when the assertion fails contains all sorts of useful information. The drawback lies in the amount of artifacts that one need to create in order to achieve the goals.

Another solution

Most of the time the composite of constraints is the best solution, but for simpler scenarios the extra work might not look appealing. After all the test is focusing in just a a subset of the properties of the actual object, isn’t there an easier/cheaper way?

And here is where ExpectedObjects can lay its helping hand. Amongst other features it allows checking the equality of instances of types that do not have to be the same type but have the same “shape” and values. Thus, one can create an anonymous object containing just the values needed and assert the actual objects against it.

In this example, complex is an instance of CustomWithCollection that it is pretty complex (although feasible to create, for the sake of the example). This instance might be returned by the method we are testing and we are only interested in its Name property and certain properties of its Addresses collection. An anonymous object is created with just the properties that are of interest for the test, and the Must.Match.Expected() magic (powered by ExpectedObjects and sprinkled with a bit of adaptation logic) does it job beautifully.

var complex = new CustomerWithCollection
{
    Name = "name",
    PhoneNumber = "number",
    Addresses = new[]
    {
        new Address { AddressLineOne = "1_1", AddressLineTwo = "1_2", City = "city_1", State = "state_1", Zipcode = "zip_1"},
        new Address { AddressLineOne = "2_1", AddressLineTwo = "2_2", City = "city_2", State = "state_2", Zipcode = "zip_2"}
    }
};

var expected = new
{
    Name = "name",
    Addresses = new object[]
    {
        new { State = "state_1"},
        new { Zipcode = "zip_2"}
    }
};

Assert.That(complex, Must.Match.Expected(expected));

What happens when the expectations are not met? In this example, a pretty deep-buried value does not match the one occurring in the actual object. The assertion will fail and the failure is pretty descriptive:

var complex = new CustomerWithCollection
{
    Name = "name",
    PhoneNumber = "number",
    Addresses = new[]
    {
        new Address { AddressLineOne = "1_1", AddressLineTwo = "1_2", City = "city_1", State = "state_1", Zipcode = "zip_1"},
        new Address { AddressLineOne = "2_1", AddressLineTwo = "2_2", City = "city_2", State = "state_2", Zipcode = "zip_2"}
    }
};

var expected = new
{
    Name = "name",
    Addresses = new object[]
    {
        new { State = "state_1"},
        new { Zipcode = "notSameValue"}
    }
};

Assert.That(complex, Must.Match.Expected(expected));

How about refactoring of the actual object? Bad news is that you have a failing test for structural change reason (annoying). Good news is that your tests running in your CI process caught it straight away and it is easy to change. Even better is that some refactoring tools are pretty good in “guessing” the rename and suggest a solution.

Wow. Exactly what I Needed

Isn’t Open Source Software amazing? If you think so, go and get Testing.Commons.NUnit (or snatch it from NuGet)and you can start using this feature and some others straight away!

Testing.Commons.NUnit sees the Light

2011-10-04T21:59:00.001+02:00

Yup, as I mentioned before, after the first “full release” of Testing.Commons, Testing.Commons.NUnit would start to receive more love (and code commits, now that we are at it).

The first version (0.1) has been released. Binaries can be downloaded from the project files area or from NuGet.

Inside the Box?

For this premier, I chose to include a base test fixture that makes easier to write AAA tests. Just inherit from ArrangingTest, implement the method that initializes the SUT, and the subject will be initialized for you and the beginning of each test.

public class UsefulWhenDealingWithSubjectsWithMockableDependencies : ArrangingTest<ISubjectWithDependencies>
{
    // dependencies go into fields for test to access them
    private IDependencyOne _one;
    private IDependencyTwo _two;

    protected override ISubjectWithDependencies initSubject()
    {
        // dependencies are initialized inside the arrange method
        _one = MockRepository.GenerateStub<IDependencyOne>();
        _two = MockRepository.GenerateStub<IDependencyTwo>();
        return new SubjectWithDependencies(_one, _two);
    }

    [Test]
    public void DoSomethingWithOne_InvokesDependencyOne()
    {
        // Act
        Subject.DoSomethingWithOne();
        // Assert
        _one.AssertWasCalled(o => o.DoSomething());
    }

    [Test]
    public void DoSomethingWithOne_InvokesDependencyTwo()
    {
        // Act
        // "Subject" is already initialized and reset
        Subject.DoSomethingWithTwo();
        // Assert
        _two.AssertWasCalled(o => o.DoSomethingElse());
    }
}

Also included goes the ConstrainedEnumerable constraint. That allows constraints to be applied to each member of an enumerable and provide meaningful feedback when it fails:

[Test]
public void CanBeCreatedWithExtension()
{
    Assert.That(new[] { 1, 2 }, new ConstrainedEnumerable(Is.EqualTo(1), Is.LessThan(3)));
    Assert.That(new[] {1, 2}, Must.Be.Constrained(Is.EqualTo(1), Is.LessThan(-3)));
}

Element # 1 from < 1, 2 > failed to satisfy constraint.
Expected: less than -3
But was:  2

Have fun using it and do not forget to give feedback and getting involved in the project!

Testing.Commons goes 1.0

2011-10-02T13:15:00.001+02:00

Let’s throw a party!

A Big Gap

Wait a second? Last release was 0.4.0.0, when stuff to test the profile system was added. “Either you have been terribly busy or you are tricking us.”

Well, more of the latter if you check the amount of code of the deltas committed. In reality my plan was to go 1.0 when all the code I previously had was ported. It turned out to be less than I thought as I trimmed out some parts I cannot use and clipped redundancies.

What’s in?

Besides the already mentioned in my previous ranting-entry CultureReseter, that allows scoped fine grained control over the culture of the thread, the bulk comes in the shape of helpers to ease testing web elements.

ControlLifeCyle allows calling protected method to simulate the life-cycle of a custom control and HttpContextBuilder eases the creation of the “800 lb gorilla” that HttpContext is.

ControlLifeCycle

It may sound like a small thing, but the coolest feature of the class is being able to infer the name of the protected method from a strongly-typed event name.
I cannot tell you how many times I have fought the war of C# syntax clumsiness for events. This time I spent more time and won it just by chance. change is because I found the solution while googling late in the evening for something else.
All the Expression code I have spiked and how many times I have looked Rhino-Mocks’ proxy based codebase (not the simplest codebase to grasp I have to say) in search of a way that allows me to get the name of an event using strongly-typed reflection will not see the light. The secret was MSIL parsing. But of course!

The inspiration came from a blog about Castle.Windsor facilities, which made me look into their facilities for event wiring, dig into their source code and pick the pieces that I needed, and re-organize them for my purposes. Don’t we love OSS software?

HttpContextBuilder

Yes, this one is got external inspiration: here and here. But Phil Haack’s reflective-heavy approach was making my tests fail and Jason Bock’s was felt aged and feature-short. So I merged the ideas from both, fluently lifted its API and voilà, one can create feature rich instances of the big guy.

Where you said?

I knew it, Testing.Commons is exactly what you were looking for! Go and get it from the project site or NuGet.

What now?

I told you I finished importing the bulk of my previously created code. That means that, unless people contribute we are going to see a slow down in the rate of releases.

That is not sad in itself, because it means that Testing.Commons.NUnit is ready to take-off!

Documentation Does Get Outdated

2011-10-02T12:09:00.001+02:00

I am not going to start another flame war about whether documentation is evil or not.

My personal stand is that is evil but mostly needed.

One of my biggest concerns with documentation is that, more often than not, tends to become obsolete no matter how hard you try to keep it current. One might seek several explanations, but my personal take is that updating documentation is not nearly as fun as changing code. When I say no matter how hard one try I mean it. I do not intend to disregards completely the value of documentation altogether, but I intend to point out just another example that supports by beliefs.

Busted!

How much do you think Microsoft spends on documentation? Well, they do have technical writers and correctors and probably proof-readers of corrections, so I would assume they spend more than the average software company does. Some people believe they are not in the bottom half of the table when it comes to documenting their software. At least I think the BCL documentation is not horrendous, although it has its WTF highlights.
And this praise would be all I’d to say if software was static, but, alas, it is not. Methods evolve, and internal changes sneak in unnoticed.

One of such changes is exceptions thrown by a method. .NET does not, fortunately I would say, have the concept of checked exceptions, in which the exceptions thrown by a method become a part of its signature. .Net has the concept of documenting the exceptions, but there is no compiler activity in checking whether the exception can actually be thrown in the execution path of the method. so one might happily add or remove exceptions inside a method and the compiler would silently do its job with no complaints.

That exact event happened to a pretty popular .NET class, the Thread. In version 4, a check was removed for the setter of the CurrentCulture property. In previous versions one could not set the current culture of the thread to a neutral culture or a NotSupportedException would be thrown.

Of course documentation was never updated to reflect that change in code.

How did you?

It happens that Testing.Commons contains a class that allows having fine control over the culture a piece of code (mostly a test) runs. Its name is CultureReseter. A variant of such class has been used for some time now in software running previous versions of the framework.

Such class had zero lines of documentation. Instead it came with a bunch of unit tests that told you how to use it and, most importantly, how not to use it. In one of such scenarios the potential user of my class was pointed out that a neutral culture is not valid when setting the current culture of the thread, as doing so would throw an exception.

Of course when I tried to run a similar test on .NET4 (the platform of choice of Testing.Commons), it automatically failed. I was puzzled. At first I double and tripled checked what I was doing wrong as I thought that such behavior had not changed. Hell! the documentation was telling me it had not changed!!! I had to fire my {decompiler-of-choice} to see with my own eyes that the change, indeed, happened and that my test was catching the change of behavior.

So?

Does that mean we should ditch documentation at all? Nop.
But what we could do is use documentation for things that cannot be expressed in code. And let code, in the shape of test, speak about the behavior of each class.

No offense for technical writers, but we would be better off with less of those and more developers engaged in the endeavor of writing good, expressive tests as a mean of documenting behavior and making it available for us developers.

There is no better documentation.

NMoneys.Exchange gets an Article as well.

2011-10-02T11:52:00.001+02:00

I am sure you are aware of both NMoneys and its companion.

I have written another article in The Code Project showing what can this extension to NMoneys can do for you.

Enjoy your reading and comment on it.

Configure Reality

2011-09-15T22:10:00.001+02:00

Configuration in enterprise application is a fact of life.
My take on it is as follows: delay it as late as possible and hard-code in anger until someone asks for a change. Then, accepting the fact that is likely to happen again, the value is pushed into configuration.

Configuration can be as simple as a collection of key-value pairs. But sometimes, configuration needs to be more complex than key-value pairs; just imagine some sort of hierarchical structure or a simple collection of related values.

For key-value pairs we can use the old appSettings section, with all its type un-safety (sorry, I forgot type-unsafe is derogative, nowadays we use dynamic to name things that blow up at runtime) and if we cannot wait so long and be old-fashioned and get earlier feedback from tools/compiler (boo!) application settings is another option.
For those edge cases in which more complexity is actually needed, there is also a wealth of information about how to use XML serialization to use strongly-typed classes, including various very last configuration sections ever to be written.

My preferred option, though, is using custom configuration sections, taking advantage of the well-thought set of classes living in System.Configuration. It is a pretty extensive topic which other people have covered in detail, but basically revolves around custom classes decorated with attributes with a semantic model that can be used to improve performance and live outside the rigid world of what can be done within attributes.

Dirt goes Under the Rug

The very fact that I am writing about it and deserves a place inside a testing library means that, in terms of testability, configuration can give you some headaches if configuration is used all over the place.

I consider configuration an infrastructure concern and as such I tend to abstract it away behind a interface; so consumers of configuration do not need to deal with configuration’s testing challenges.

But what happens when we need to test that our configuration object hierarchy is indeed correct? Furthermore, imagine for a second that your application behavior can be somehow tweaked once deployed by changing configuration values. What if those changes are done by people different from the ones that developed the application (or maybe the forgetful same ones)? What if, {insert_deity} forbids, whoever touches configuration makes a mistake? We would definitely want the error message to be descriptive. Or maybe we just want to provide some executable documentation about the usage of our configuration section and get some regression tests for free in the process.

My point is that we want to test not only the consumers of configuration (providing a test double), but the providers of configuration as well.

Behave!

Fact is that, regardless of the configuration strategy being used, only one set of configuration values tends to be loaded into the application. And such model does not really lend itself to testing multiple cases. The solution is simple enough: the class that provides the configuration can be instantiated differently while testing from the way is instantiated during application runtime. The trick is using an external configuration file via ConfigurationManager.OpenExeConfiguration(string).

Let’s exemplify with a complex configuration of a caching system in which each cache has a different time-to-life for its elements and each cache can have dependencies with other caches. The abstraction for this piece of configuration could be something like:

public interface ICachingConfiguration
{
    TimeSpan TimeToExpire(string cacheName);
    bool HasDependencies(string cacheName);
    IEnumerable<string> GetDependantCaches(string cacheName);
}

The class implementing the abstraction, uses a bunch of collection elements “hanging” from a custom ConfigurationSection, the CachingConfigurationSection. The default constructor will be used when the provider is instantiated “normally”, but the constructor receiving the path of an executable (or assembly) file is used during testing to inject a file that contains the configuration for the scenario being tested.

public class CachingConfiguration : ICachingConfiguration
{
    private readonly CachingConfigurationSection _section;
    public CachingConfiguration()
    {
        _section = (CachingConfigurationSection)ConfigurationManager.GetSection(CachingConfigurationSection.SectionName);
    }
    public CachingConfiguration(string configFile)
    {
    _section = (CachingConfigurationSection)ConfigurationManager.OpenExeConfiguration(configFile).GetSection(CachingConfigurationSection.SectionName);
    }
    public TimeSpan TimeToExpire(string cacheName)
    {
        ExpirationElement expiration = _section.Expirations[cacheName];
        if (expiration == null) throw new ConfigurationErrorsException();
        return expiration.Value;
    }
    public bool HasDependencies(string cacheName)
    {
        DependenciesCollection dependencies = _section.Dependencies;
        return dependencies != null && dependencies[cacheName] != null;
    }
    public IEnumerable<string> GetDependantCaches(string cacheName)
    {
        IEnumerable<string> cacheNames = Enumerable.Empty<string>();
        if (HasDependencies(cacheName))
        {
            cacheNames = _section.Dependencies[cacheName].DependantCaches
                .Cast<DependantCacheElement>()
                .Select(dependant => dependant.Name);
        }
        return cacheNames;
    }
}

Find and Fetch

So the provider can receive a path from a file… Other part if the puzzle is a helper class that allows a declarative way of expressing the configuration file to be loaded. That part is achieved by decorating our tests with ConfigurationAssemblyAttribute, specifying the path to an imaginary assembly named after the file that contains the piece of configuration to be tested. For instance, a configuration file named CachingCorrectConfig.dll.config can be loaded by decorating the test with the path to an assembly CachingCorrectConfig.dll. That assembly file does not even need to be a real assembly, it suffices being an empty file with the .dll extension. In order to ease the retrieval of the attribute the ExternalConfiguration.GetConfigurationAssemblyPath() method can be used within the test. Let’s see how easy it is:

[Test]
[ConfigurationAssembly("..\\..\\Configuration\\ConfigFiles\\CachingCorrectConfig.dll")]
public void GetConfigurationAssemblyPath_TestDecoratedWithAssemblyFile_AllowsAccessToConfigurationValuesFromCustomConfiguration()
{
    string assemblyPath = ExternalConfiguration.GetConfigurationAssemblyPath(MethodBase.GetCurrentMethod());

    ICachingConfiguration subject = null;
    Assert.That(() => subject = new CachingConfiguration(assemblyPath), Throws.Nothing);

    Assert.That(subject.TimeToExpire("expiration1"), Is.EqualTo(1.Seconds()));
    Assert.That(subject.HasDependencies("cache2"), Is.True);
    Assert.That(subject.GetDependantCaches("cache1"), Is.EqualTo(new[]{"cache1_1", "cache1_2"}));
}

When Things Go Wrong

A way to tell people what to do is telling them what NOT to do. That works for testing as well. We need to verify that our assumptions on what we consider incorrect configuration are indeed correct (weird stuff). Problem is, error messages are localized and we do not really want to couple the success of a test of ours to a text on a third party resource (the framework is a “third party” in this case).
Well, all of my machines run English versions of both OS and .NET Framework so I think it is OK that my default error message fragments are in that language. If that is not the case for you, the same extensibility model as for the Must provider is used, so feel free to provide your own extension method for whichever case you feel like testing to ExceptionMessagePart.For:

[Test, ConfigurationAssembly("..\\..\\Configuration\\ConfigFiles\\CachingIncorrectConfig_UndefinedElement.dll")]
public void UndefinedElement_ExceptionWithMessageContaining()
{
    string assemblyPath = ExternalConfiguration.GetConfigurationAssemblyPath(MethodBase.GetCurrentMethod());
    Assert.That(() => new CachingConfiguration(assemblyPath), Throws.InstanceOf<ConfigurationErrorsException>()
        .With.Message.StringContaining(ExceptionMessagePart.For.UndefinedElement(ExpirationElement.ElementName)));
}
[Test, ConfigurationAssembly("..\\..\\Configuration\\ConfigFiles\\CachingIncorrectConfig_MissingRequiredElement.dll")]
public void MissingRequiredElement_ExceptionWithMessageContaining()
{
    string assemblyPath = ExternalConfiguration.GetConfigurationAssemblyPath(MethodBase.GetCurrentMethod());
    Assert.That(() => new CachingConfiguration(assemblyPath), Throws.InstanceOf<ConfigurationErrorsException>()
        .With.Message.StringContaining(ExceptionMessagePart.For.MissingRequiredMember(ExpirationsCollection.CollectionName)));
}

I Want It!

You got it! It is in Testing.Commons! Binary or packaged, your choice.

Have many ideas for improvement? Share them and contribute to the project. Let the code speak.

The Magnificent Sixteen

2011-09-13T20:30:00.001+02:00

GUIDs are precious little things. Useful, annoying at times, but lovable nonetheless. Cherish them as if they were unique (all pun intended) and they will pay your love back.

I am one of those who despises wasting GUIDs. Some would go even further: They will say I am afraid that we are going to run out of them.
Reality is, I firmly believe they have a higher purpose in life than being stuck in some obscure testing project, never seeing the “production light”, test run, after test run, after test run…
But just imagine this other equally terrible fate: being born for a split second of a test run and die after it finished. The paradigm of purposeless life: be born in pain (and wasted CPU cycles), enjoy a brief life (microseconds) while the test runs, be in the middle of action without being noticed and die. No one remembers you. No one ever ask you what your value was. You are irrelevant, Dispensable. A mere thing used for the sole purpose of not using The One Whose Name Cannot Be Mentioned:

Guid.Empty

These apocalyptic scenarios are everywhere around us:

developers that use GUID generation shortcuts in test projects are preventing those otherwise very capable entities to be born where they are most needed: production code.
```
new Guid(“somethingThatWasCopiedFromATool”)
```
Some sadistic developers even generate new GUIDS for every run of the test! Heartless, cold-blooded GUID murderers, that will burn in hell listening to their victim’s screams, if you ask me.
```
Guid.NewGuid()
```

Stop the Slaughter

I cannot tell how many unborn GUIDs I have saved with my own hands. But I felt I could do better. How many times I have dreamt of using a team of well-trained GUIDs that can stop the massacre? Loads. But know I moved my lazy developer-ass and share with you someone that can introduce you to The Magnificent Sixteen: GuidBuilder.

My experience tells me that in most test one does not need trillions of GUIDs to compare. An upper limit close to the dozen is more accurate. Beyond that limit, I am in a position to assure you are getting yourself into a big mess with that test. But that dozen or so are important for your test scenario. You are probably identifying some objects with those, so it is important that:

they are different
no innocent GUID suffers

You can use GuidBuilder.Build() to create one of the Magnificent Sixteen. An hexadecimal figure is all you need, and a GUID with all digits set to that figure will be created. Pass it as a char or a byte.

Assert.That(GuidBuilder.Build('0'), Is.EqualTo(new Guid("00000000-0000-0000-0000-000000000000")));
Assert.That(GuidBuilder.Build(3), Is.EqualTo(new Guid("33333333-3333-3333-3333-333333333333")));

Where Do I Sign?

Luckily, no signature is needed. You get it alongside the rest of the wonders of Testing.Commons in their latest version (v0.2) which can also be obtained via Nuget Package.

Use it. Save those GUIDs. Delay the Doomsday that will happen when we run out of them. Decrease that crazy entropy growth. But remember, if it is not hexadecimal (0 to 15 or '0' to 'F'), it is not one of the Magnificent Sixteen.

NMoneys 2.1.0.0

2011-09-01T22:35:00.001+02:00

Not a lot of movement in NMoneys until now.

But the unthinkable, has happened: I have received an email notification for a change in the ISO standard for currencies!! After more than two years subscribed I finally received my first amendment newsletter. I totally attribute this event to changes in the maintenance agency, which changes are very welcome, Excel and XML tables of current and historic currencies, amongst others.

As a result I made some quick changes to support the latest standard and pushed the new version for everyone to enjoy.

And that is how it should be, shouldn’t it?

Clarity is The Theme of the Party

2011-08-28T01:03:00.001+02:00

While developing the improvements for the Generate class of Testing.Commons I faced an API design challenge that I, at least, consider challenging.

Imagine we have to model a TimeOfDay class, that puts a name to an important time of the day, such as noon or midnight and which members are used from within a delegate, to give a nice lambda-ish flavor to the API:

DateTime dt = 28.August(2006).At(t => t.Noon);

How could one design such a type?

Enumerations, Good Old Friends

MSDN: ”An enumeration type (also named an enumeration or an enum) provides an efficient way to define a set of named integral constants that may be assigned to a variable.”, which means that you can put a name on a constant value, as long as it is one of the supported types (integral type byte, sbyte, short, ushort, int, uint, long, or ulong).

As we want to represent that time of the day as the time elapsed since the day started, we are willing to represent it as a TimeSpan. Of course, TimeSpan is not one of the supported types, which rules out enumerations.

Static, Not Good Enough

One way to overcome this problem is declare the values either as constants. Since they are not constants as the compilers likes them, they could be public readonly fields, as in:

public class TimeOfDay
{
    public static readonly TimeSpan Noon = TimeSpan.FromHours(12);
    public static readonly TimeSpan Midnight = TimeSpan.Zero;
}

That is almost fine (we can use static to prevent instantiation), if what we want to use is the class in statements, as in:

TimeOfDay noon = TimeOfDay.Noon;

Unfortunately, in order to use it within the lambda an instance of TimeOfDay is required as static fields cannot be accesses from object instances .

Instance is the way to go

Instances if what is needed, instances is what will be provided.

public class TimeOfDay
{
    public readonly TimeSpan Noon = TimeSpan.FromHours(12);
    public readonly TimeSpan Midnight = TimeSpan.Zero;
}

That indeed allows the delegate usage, and instantiation is allowed. I do not see a lot of people willing to instantiate such a simple class (we have become so lazy as to consider the new operator as an annoyance) nor I want to instantiate one every time, just to access a “constant” field (serious case of micro-optimization, I know).

Thou Shall Not Instantiate

Preventing instantiation from the outside is as simple as to provide the lamest construction of all time: a singleton. I do not care about lazy initialization or anything, so the simplest construct is used:

public class TimeOfDay
{
    public readonly TimeSpan Noon = TimeSpan.FromHours(12);
    public readonly TimeSpan Midnight = TimeSpan.Zero;
    
    private TimeOfDay(){ }
    
    internal static readonly TimeOfDay Instance = new TimeOfDay();
}

Now, we are able to prevent instantiation from outside (and inside the assembly) and happily use the single instance exposed by Instance from within the assembly.

We could satisfy the users that want to consume static counterparts, but it would have to be using another name, as static and instance members cannot have the same name . But as that is not a use case that I foresee (famous last words) I decided not to add them.

Interesting?

Maybe. I, for one, enjoyed designing an API test-first.
Useful? Well, I think the API is intuitive and expressive. What do you think?

Testing.Commons. It’s a matter of time

2011-08-28T00:10:00.001+02:00

Face it: time is everywhere and cannot run away from it. That is why I chose time to be the subject of the first release of Testing.Commons, a mere 0.1.

Classes that deal with time in the BCL (DateTime, DateTimeOffset, TimeSpan) might have their issues. They might not be accurate. They might not be correct at all. There might be some better alternatives. But they are not going anywhere, anytime soon.

And code that make use of them needs to be tested and, honestly, those classes do not have the most expressive API when it comes to create instances of them. This feature is not that incredible useful in the “real world” (the world of production code) where dates are rarely hard-coded, but it does not hurt anyone if a bit of lipstick is put on top.

D-Day

DateTimes can be created in a very visual way using a set of cleverly named extension methods.

DateTime date = 2.January(2000);

Sometimes what one needs is whichever date between two bounds.

DateTime one = Generate.Between(11.March(1977)).And(27.August(2011)).Single();

And sometimes what one needs is a number of dates between two bounds. Careful, though; an infinite stream of dates takes a long time to enumerate, limit the number of results.

IEnumerable<DateTime> infinite = Generate.Between(11.March(1977)).And(27.August(2011)).Stream();
IEnumerable<DateTime> tenDates = Generate.Between(11.March(1977)).And(27.August(2011)).Stream(10);

Times Are A’ Changing

Dates are alright, but we have measures smaller than days.

DateTime withSeconds = 11.March(1977).At(12, 30, 45);
DateTime withMinutes = 11.March(1977).At(12, 30);
DateTime withHours = 11.March(1977).At(12);

We even have certain times of the day important enough to deserve a name on their own.

DateTime midday = 28.August(2006).At(t => t.Noon);
DateTime midnight = 30.September(2008).At(t => t.MidNight);

Where in the world is *

It took some time to figure out DateTime was not the best structure to deal with the artificial human-created trickeries that time zones are. Sometimes what we want to do is not performing some transformations between dates in different zones. We just want to specify exactly what we are creating.

DateTimeOffset utcPlusTwo = 11.March(1977).At(15, 30, 45).In(TimeSpan.FromHours(2)));
DateTimeOffset utc = 11.March(1977).At(13, 30, 45).InUtc())

The arrow of time

Time passes. And spans of time needs to be measured and compared. Another set of extension methods allows elegant creation of Timespans.

TimeSpan weeks = 2.Weeks();
TimeSpan days = 3.Days();
TimeSpan hours = 4.Hours();
TimeSpan minutes = 5.Minutes();
TimeSpan seconds = 6.Seconds();
TimeSpan allUnits = 5.Days().Hours(4).Minutes(3).Seconds(2).Milliseconds(1);

Get It While Fresh

You can get this first 0.1 release downloading the binaries from the project’s File Area or using the NuGet package.

Geek Note:

If the reader’s mind complete the phrase with “Carmen Sandiego” we have one of three cases:

old nerdy individual

really nerdy individual

facebook infected individual

A Little more OSS

2011-08-27T22:52:00.001+02:00

As the reader might have notice, I am a big advocate of testing. During the years that I have been practicing some flavor of testing I have been developing, borrowing and using small little classes (or bigger ones) and techniques to make my life easier and my code suck a little less.

I have decided that I might as well share them with more people and, who knows, the benefit might become mutual. That, and the fact that my code will be improved as it makes its way into the new projects, is why I am launching Testing.Commons.

Testing.Commons

This project will contains code that helps and supports testing in any way. No external dependencies on any framework or tool should be needed.

Testing.Commons.NUnit

NUnit is my weapon of choice when it comes to unit testing and I even use it to drive some other types of tests. One of the features I have come to love the most is the ability to extend its assertion model with custom-developed constraints. This project will contain, most than anything, some useful custom constraints I have used though the years.

Tool changes

This may sound a little harsh and will leave some people disappointed, but I will focus my efforts only in .Net 4 as there are newer features that I definitely want to explore, such as dynamic and default parameters, for their potential to improve code expressiveness and clarity.

I have been using Subversion for some time and used Google code to host my other OSS project: NMoneys.
Not that I have been let down or limited in any way by the tools or the hosting, but I a willing to get my head around Distributed Version Control Systems. Everyone is jumping onto Git and github and that is all fine. I am not (for the moment). I will give Git hosting in Assembla a try. If it does not work for me I can always change, can’t I? We are blesses with multiple very cheap (free) hosting choices, time to take advantage at last, right?

NuGet has been proved mature enough to be considered as the solely delivery method of libraries such as these, so I will continue leveraging two dependent packages. I am still no decided whether I am going to support Ruby Gems, but no door is closed.

Dead rich soon? Not with this Attitude

2011-07-17T22:55:00.001+02:00

Everyone of us dreams with this success stories: self-made, luck-stricken, hard working average Joe –or Jane– that once in a while hits the jackpot of a very successful application that makes him rich overnight (and still doing his –or her– dishes).

Certainly, I do not know what it takes, but to be honest with you, odds are against me in every front, so place your bets anywhere else. I mean it. Not kidding or being overly modest. I consider myself a good enough professional. I enjoy what I do and I possess a certain degree of passion. It just seems that I do not have it.
I will illustrate with a small anecdote. Of course, I do not imply that had I did differently I would be swimming in gold, or that the guy that actually did it is (I hope he is not, for the sake of my own sanity)

I have been attending to conferences for 4 years. The technological landscape has changed substantially, but something has remained constant: my desire to be prepared and organized. I would meticulously prepare my schedule in advance and load it onto my handheld device of the season.

My first experience was a bit nightmarish: the conference site would not offer the chance to export the session to a calendar application, so I had to enter by hand all information regarding titles, abstract, location and speaker on appointment items in Outlook and sync it with my PDA (Windows Mobile at that time). I might have lost a couple of afternoons doing so. It looked kind of cool, but to tell you the truth I was reverting back to good old printed program with an circle surrounding the session title.

Subsequent experiences improved as conferences realized that people might want to be prepared and offered a way to export session as iCal items. That improved the process but I only had to tweak it to have it displayed in a sensible way.

This year, broken the chains of Outlook and Windows I went “into the cloud” and prepared everything in Google Calendar. Did it improve the process? Hardly. And again, the problem of changes of agenda and my own schedule being useless manifested themselves,

The process is dead simple: have an overview of the sessions, pick the ones you are interested in and consult your schedule multiple times to figure out which room are you heading onto. And yet I wasted my own time 4 years in a row. Did I ever think of making my life easier with an application that did the job for me? Not a single one. What do you think I am? A programmer? So you can imagine my absolute face of utter disbelief and I guess you could hear the “SPLASH! But… of course!” when I saw all people checking their schedule in a app for the conference that did exactly what I wasted my time doing.
Its name is Oktaset, the front-end runs on multiple platforms (iOS, Android and Windows Phone) and supported this year’s NDC and the Tech-Ed.

I had the business case but I did not have the vision. They did. And they executed brilliantly. Shame on me. But when your brain does not click, it does not click.

NMoneys goes 2.0 and Gets Company

2011-06-30T23:41:00.001+02:00

Wow, after a 1.6 version I decided to jump straight to 2.0.
Is it that big of a change? Well, not really, maybe a couple of breaking changes and features. But NMoneys 2.0 is just a side dish, the entrée is… NMoneys.Exchange 1.0

Is NMoneys Already Dead?

Not a chance! NMoneys.Exchange might steal some of its older brother’s thunder for some time, but NMoneys still plays the star role.

Why Another Project?

Well, when NMoneys got its CodeProject article, just about the fist thing people asked was: “Why can’t you exchange currencies?”.

As it is stated in the vision of NMoneys, currency exchange was not in my radar. For one, I did not know the rules for the operations (I still don't) and the data needed is so volatile that companies make money out of providing services around it. So, clearly not a candidate for a library.

But since people asked, I started thinking. Why not? I turned the petition into an excuse to sketch an API… and the result is NMoneys.Exchange, which sits right of top on NMoney’s foundations: Money and CurrencyIsoCode and that will have a whole different lifecycle than NMoneys itself, with different releases, packages, but still close to its older brother.

What’s inside?

NMoneys.Exchange is not more than a framework that allows applying exchange rates to monetary quantities. I will repeat it again: “it’s a framework, not a service”. You need to be a developer to use it, just as you need to be a developer to use a library like NMoneys.

When imported into your project (alongside NMoneys) it offers a couple extensibility points in the shape of the Convert() and TryConvert() extension methods over Money. From those extensibility points you can use the provided To() method that will make things happen.

var tenEuro = new Money(10m, CurrencyIsoCode.EUR);

var tenDollar = tenEuro.Convert().To(CurrencyIsoCode.USD);
var tenPounds = tenEuro.Convert().To(Currency.Gbp);

Is that it? That easy? Then why all the fuss with exchange rates and services and your reluctance to implement it? Well, if you look at it closely it is not doing the right thing, unless the exchange rates between EUR, USD and GBP is 1, which I suspect it isn’t. By default, the framework does no harm, but not the correct thing either. Because correct in this context is not something a library can do, as rates change by the minute.

the trick is providing some exchange rates. How? Either implementing an interface, or using an included implementation of that interface and letting the framework know of it. This example shows how to use the included implementation, include some invented conversion rate and configure that provider:

var customProvider = new TabulatedExchangeRateProvider();
customProvider.Add(CurrencyIsoCode.EUR, CurrencyIsoCode.USD, 0);

ExchangeRateProvider.Factory = () => customProvider;

var tenEuro = new Money(10m, CurrencyIsoCode.EUR);
var zeroDollars = tenEuro.Convert().To(CurrencyIsoCode.USD);

How does one plug his favorite data feed? Implement a custom IExchangeRateProvider and configure the factory as in the previous example.

As I stated before, I have not become wiser with time and I still do not know the rules for applying rates to monetary quantities. What I have done, in the same extensibile spirit is provide a default implementation that does not harm (or so I believe) using the default decimal multiplication, and leave open the extension of the class that does the work: ExchangeRate. In this example, we subclass ExchangeRate to perform fake custom arithmetic:

public class CustomRateArithmetic : ExchangeRate
{
    public CustomRateArithmetic(CurrencyIsoCode from, CurrencyIsoCode to, decimal rate) : base(from, to, rate) { }

    public override Money Apply(Money from)
    {
        return new Money(0m, To);
    }
}

If you want to know more supported scenarios, go to the Quickstart that lives under the project Wiki.

Me Likes. Where?

You can go and get it from the project’s Dowload Area .

It also got its own Nuget package and gem. Download it, use it and do not wait to provide feedback!

NDC 2011. And Day 3

2011-06-22T21:42:00.000+02:00

My head was still spinning from the party of the day before. Not because of heavy drinking of wild partying (there was none of those) but because the stream of unleashed energy that Rob Ashton is. A quiet beer can turn into a heated discussion decorated with jewels such as “Javascript is the f… second coming of The Messiah”. Heretic, yes… but by Jove was funny!

Package Management deep-dive with Open Wrap

For this short last day I decided to look at Open Wrap again. My first contact with it was not very successful… and neither was this second one.

I agree that demoing nightly builds and bragging about it is nice. When things go as planned. Which was not the case. I have seen Sebastian, the speaker, have the same problems in another session and it’s not cool at all and projects an unprofessional image.

Problems aside I liked the tool and some of the ideas behind it but I won’t be using it for my projects as I do not like the idea of my package manager taking over my project’s build.

CQRS in the Wild

I was not expecting this session to become one of my favorites of the conference, so it is nicer when it catches you by surprise.
What made it become a favorite? Well, almost everything: the topic is interesting to me, the problem domain is familiar, the trade-offs are similar, there’s empathy to the approach to the solution, details of the solution were at the right level given the session’s time constraints, the speaker did a great job communicating the process and was extremely honest with the problems that they are facing and have not solved yet.

And besides the framework that he is using is Open Source. Another alternative to look into if and when the need comes.

Making your Rails App Sing

I knew this talk was almost completely away from my range of experience, but Rob is really enjoyable to listen to and I was not in the mood for more Javascript.

The session had almost anything to do with Rails but with a bunch of services you can use from a Rails application or from another sort of application (given there is a hook or you are in the mood to deal with a REST-y API) to solve problems that someone building a site selling some content might face. He spoke from his experience with his own business but I can see myself considering some of the services showcased in the future.

The Three Amigos

And another session for entertaining purposes only (almost). It is always fun to watch three guys having fun on stage and sharing jokes and laughs. The idea was sort of a competition between the ASP.NET MVC + Entity Framework platform and Ruby on Rails in order to build a simplistic web application.

The application/technology part was kind irrelevant and was an excuse to make fun of each other for a while. I have to point out that starting with Rails is easy (and blazing fast to get started once you are comfortable to spend lots of time in the console), but so it is with MVC scaffolding and EF code first. I have to point out the amount of goodness that was released recently in the MVC ecosystem that have substantially changed how to start a quick and dirty project and yet have something that can scale further the drag and drop data-source plus a grid.

Unit Testing with Auto-Fixture

Last session of an amazing conference. Luck was that the schedule was changed some time ago so that I could watch the session of someone I have been following from some time: Mark Seeman.

Some time ago a former colleague of mine pointed me the project that was the subject of the talk: AutoFixture. It looks great on paper and the dimension he was presenting was using the tool as a way to create your subject under test in a “maintainable manner”. And I quote it because I was left with the impression that the problem to solve has other alternative solutions that are, in my opinion, orders of magnitude simpler, less intrusive and more self-explaining. But hey, whatever push your boat.

Once again I have to be picky with the example chosen. Yes, it was guiding the audience towards the need to use the tool being presented, but the process, labeled as TDD, has little to do with TDD: why on Earth would anyone driving the implementation of an interface come up with a first set of tests that has nothing to do with the interface being test-driven? A more strict TDD would have most likely taken the developer towards another (simpler) solution. But that would have not made the tool appear as a desired solution.

All in all, I think AutoFixture is pretty elegant and I liked the session but I could not let the bitch in me go off a sample, could I?