Sunday, 2 June 2013

Instrumentation with Semantic Logging Application Block from Microsoft Enterprise Library 6

Introduction

Instrumentation, the process of auditing and logging in your applications, is a vital part of any enterprise solution. When you are developing applications with Service Level Agreements and specific Auditing requirements, logging is a big deal. Add in the complexity of the decoupled nature of the cloud with Service Orientated Architecture, piecing together a clear view of a business process from end to end can be a challenge.

Microsoft has recently released the Semantic Logging Application Block (SLAB) to the enterprise library. This article will form the first part of a mini-series, detailing the benefits, pitfalls and examples of how to make use of it in your enterprise.

Although new to the Enterprise Library, Semantic logging is not a new concept. It has been adopted for years under different names such as "structured logging", "strongly typed logging" and "schematised logging" to name a few.

What is it?

SLAB inherits event structure from the Event Tracing for Windows (ETW) pipeline, allowing it to store the payload of the event along with it's metadata. In this case you have data along with data which describes the format. ETW has built in support for logging a stack trace along with the event and can also be extended which enables you to add your own event data.

SLAB's secret source is to make light work of using a reliable and robust logging infrastructure that has been around since Windows 2000 in a way that abstracts us as developers from the messy details of manifests and publishing to ETW, which is typically overly complex, focusing on What you want to log and Where you want to store those logs. 

What you want to log 

The abstraction of what you want to log comes in the form of an EventSource. You create a class which inherits from the EventSource class and decorate a set of methods with attributes which determine the following:

  • The parameters the log method expects 
  • The Logging Level
  • The Event Id
  • The Task (optional)
  • Operational Codes (optional)

ETW will also provide a TimeStamp for you.

This upfront design approach allows you to separate your design of what will be logged into a discrete, specific set of methods that will be called from your business logic. 

The downside to this approach as you will find when you start using it in earnest is the amount of different methods you will have to create in order to log each and every log or audit event. The current docs recommend splitting your EventSources into partial classes to help with the manageability. My current preference is to create an EventSource for each business process which i will demonstrate shortly.

Where you want to log

To store a log with SLAB you need to configure a listener and one or more Event Sinks. An event sink receives events, by default as an EventEntry type, and has the responsibility of storing the event data in a text file, event trace, database or other storage medium. Out of the box the SLAB contains the following sinks:
  • Console
  • Flat File
  • Rolling File
  • Sql Database
  • Windows Azure Table
You can configure sinks either in code or in xml configuration. Which you use is determined by whether you are listening for events 'In Process' or 'Out of Process'

In-Process

When using the SLAB in-process, all configuration is performed in code. You first create an ObservableListener<EventEntry> (default) and you subscribe to the listener with one or more event sinks.

Note*
If you are using the block in-process, the ETW infrastructure is not used to collect events but it does use the same semantic approach to logging as ETW.

For the purposes of our sample, we will use in process.

Out-of-Process

When using the SLAB out-of-process, all configuration is performed in xml. A windows service acts as a listener which receives events from ETW and configuration sets up the subscriptions for the event sinks. The event sinks are then hosted by the windows service.

*the next article will highlight the configuration and benefits of using out of process.

Sample Code

The code sample associated with this article contains a console application which makes use of the SLAB in process and logs to the console.

Road Map

At this time i envisage at least 3 parts consisting of:


  • Part 1 - Semantic Logging Application Block - Microsoft Enterprise Library 6 (In Process)
  • Part 2 - Semantic Logging in Windows Azure (Out of Process)
  • Part 3 - Extending Semantic Logging - Creating Custom Sinks for Windows Azure

Additional Reading - What is the Enterprise Library?

If you have used other blocks from the Enterprise Library before, feel free to skip this section. "Enterprise Library is made up of a series of application blocks, each aimed at managing specific crosscutting concerns. In case this concept is unfamiliar, crosscutting concerns are those annoying tasks that you need to accomplish in several places in your application. When trying to manage crosscutting concerns there is often the risk that you will implement slightly different solutions for each task at each location in your application, or that you will just forget them altogether. Writing entries to a system log file or Windows Event Log, and validating user input are typical crosscutting concerns. While there are several approaches to managing them, the Enterprise Library application blocks make it a whole lot easier by providing generic and configurable functionality that you can centralise and manage. What are application blocks? The definition we use is "pluggable and reusable software components designed to assist developers with common enterprise development challenges." Application blocks help address the kinds of problems developers commonly face from one line-of-business project to the next. Their design encapsulates the Microsoft recommended practices for Microsoft .NET Framework-based applications, and developers can add them to .NET-based applications and configure them quickly and easily." -  Direct quote: Enterprise Library Developers Guide.

The diagram below taken from the Enterprise Library Developers Guide (preview) shows the different blocks, their dependencies and the highlighted block we will be focusing on

 Figure 1


Why another Logging Framework?

Like me you have probably been using logging frameworks such as Log4net, nLog and the Logging Application Block for many years. So why another framework when Microsoft in particular already have the Logging Application Block?

There a lot of similarities in terms of the features and the things you can do when compared to other frameworks including logging events to multiple destinations, filtering and formatting. The real power of Semantic Logging comes from the way SLAB events get written to the logs. Your events are strongly typed which allows for a consistent format and structure. There is no chance of a developer making a coding error when the log event is written such as passing in the wrong event id or verbosity. It is easier to post analyse and query the log results due to their strongly types nature and formatting. It becomes easier to consume log data from other applications. You can more easily see the big picture in terms of correlation between business processes. Automation can take place in a much cleaner way as the sinks available can utilise database and cloud storage mechanisms, preserving the actual state, already in use and being actively consumed by existing applications. 

Responsibility of concerns

While great and easy to adopt in your applications, much responsibility for logging with traditional frameworks rests with the developers. For example, setting the logging level or deciding what gets logged is constrained by what the developer at the time of writing a piece of logic deemed to be appropriate. In a world of auditing where systems require specific checkpoints and requirements, this responsibility can very easily miss some vital information, purely because a new developer adjusting some existing code never fully understood the context or simply makes a mistake in choosing the type of event to be logged. Semantic Logging removes this responsibility from the developers consuming the Logging object and places it with the design of the logging requirements. 

Rich Data - keeping the context

One of the biggest problems i have experienced when dealing with logs is the flattened nature of them and the different types of information recorded for each log entry. Some class with some method has logged an event which contains information very specific to the operation and very often not generalised enough to see a picture or view of a business process from end to end when viewing the log data that has been recorded.

Putting some meat on the bone (What do i need to do as a dev)

I created a simple console app to demonstrate using the SLAB in process.

Get References

The first thing you will want to do is add references to the SLAB. The recommended approach is to install a package via NuGet as shown below:



Click 'Accept' to the license agreement and after a few moments you will see the following added to your references:



Designing an EventSource (The What)

We first create a class which derives from EventSource. EventSource can be found in System.Diagnostics.Tracing so you will need to add a using statement as well.

The next step is to define a method that will represent a log. This is simply a method with a void return type that takes as arguments one or more of the following CLR types:
  • String
  • int32
  • int64
  • Guid 
  • Long
Surprisingly as of writing this article, the DateTime type is not supported, neither are complex types.

After you have defined your method/s, you need to decorate them with the [Event] attribute and add the necessary values. The minimum required is to specify the Event Id.

Note* The same value needs to make it into the WriteEvent() method call inside the body of the method as shown in the sample.

The EventSource from the sample code looks like the following:



The sample demonstrates two log events: Start and End application.

Although the sample is very basic, the real challenge starts to emerge as your event requirements grow. Future articles will address this in the samples.

The next step is to enable the eventsource to be consumed by providing an instance of it. The simplest way of achieving this is to create a singleton instance of the eventsource and expose it via a public property as shown in the code sample.

Logging an Event

Now the design of our events has been completed, it's time to put the hat of the developer on and log some events on our event source as shown below:




At this point, we have performed all the upfront tasks that are required. A developer could start logging the points in the application that are appropriate for each event without needing to know any of the internals as to what logging levels have been set, the event id that is associated with the event or even where the events will be stored. All this is taken care of by the design of the EventSource. It maybe that this level of detail has not yet been decided upon and yet development can move ahead seamlessly.

Consuming events (The where)

Before any events can be stored anywhere, an event source listener needs to be setup and sinks need to subscribe to it.

As  mentioned earlier, there are a number of sinks available out of the box.
  • Console
  • Flat File
  • Rolling Flat File
Also by adding further references, available via NuGet packages it is suprisingly easy to add and configure:
  • Sql Database Sink
  • Windows Azure Table Sink
* We will demonstrate these in the next article


For our first sample we will use the Console Sink. But first we need to create a listener as shown below:




Simple Output

After running the console application we can see two events being output, demonstrating 
the Event Id, Message, Event Name and Level.
The Console output can be seen below:




Adding another listener

Next we add another listener, this time making use of the out of the box 'FlatFile' sink. As shown below, with just two lines of code, our logs are being stored in a text file 'Log.txt'


Opening the log file shows the expected results as shown below:




Formatting the results
One nice feature of the sinks is the ability to add a formatter. This will be quite attractive to those wanting to migrate from existing logging frameworks to Semantic Looging but still want to retain the current log format so that post analysis can continue without interuption after moving to SLAB. There are a number of formatters available out of the box for example a Json formatter.

To show how simple it is to add a formatter, we have added a simple Console Mapper which changes the color of the console based on the Event Level.

First we add an Event Level to the Event Source [Event] attribute as shown below:



Now the design of the Event Source has been updated, the color mapper is added as shown:


With very little effort, we have formatted our output in a way that adds real value. The results when running the console, which uses the formatter, are shown once more below:




Source Code

Semantic Logging Console Part1 (Updated 8th June 2013)

References (recommended reading)


Conclusion

Does Semantic Logging solve all our logging desires?

In two words, Kinda and It depends. It does come a long way to separating concerns, enabling a true design of auditing and logging needs and adds that process as a first class citizen. If you have specific auditing requirements that can map individually to specific logging methods, it gets you a long way out of the box. If you want a more generic solution, although you can create custom event sources to map against logging frameworks which take a level and an exception for example, it's not as flexible yet. That said, you can always come up with creative ways to bend any technology to suit where necessary. Semantic Logging has enough extensibility points to customise what you need and I aim to highlight those in future articles as mentioned. 

It's definitely a shift in thinking and forces more thought into designing logs before consumption, which I am certainly in favour of from certain design perspectives. Also it separates instrumentation from your business logic and enables the two tasks to run in parallel, useful for larger teams.

Deriving and EventSource from an interface caused me a few problems such that I left it out of the sample code where ordering of the methods appears crutial. This makes testing a bit of a pain although there are some specific test methods that exist for an EventSource which help to validate it out of the box. These will be detailed in the next article. 

Bear in mind this is a version 1 addition to the block so we can hopefully expect some improvements for authoring, configuration and features.

More to come soon...

Thursday, 4 April 2013

Online Windows Azure Diagnostics


Azure Diagnostics is extremely powerful when setup correctly and being fully utilised. That said, quite a bit of burden is still left with us developers to pull out the juicy bits and present that as information that can potentially be consumed and mean something to the other, often not quite so technical, stake holders. Maybe more importantly from a developer standpoint is being able to fault find a collection of services when something does go wrong or is about to go wrong. 

A useful tool which I have used with Windows Azure and comes in very handy for diagnosing and monitoring is Stackify. It is online which immediately gets a thumbs up from me but the good part is that it supports all the Azure Diagnostics in near to real time.

You can see below that it is showing some useful stats from some Web and Worker roles. 



There are a number of different views that can be selected such as the one shown below.






Going beyond the stats which are absolutely invaluable when trouble shooting problems, there are a whole host of other features and views which make this rather like a Swiss army dev ops tool as show below.

Process List





Schedule Jobs





Start and stop Services






Browse and download Files and Folders





Like me, you have probably written some similar features into your own set of utilities in the past. 
There are other features as well which are worth checking out.  


The Setup

Setup is very straight forward.
  • Create an account with Stackify, login and download the zip archive for Azure (see fig 1 above) 
  • Extract the files to your Web or Worker Role project
  •  Set 'Always Copy to Output Directory' to ensure they get deployed from properties
  • Set the Build action to 'None' from properties
  • Add a startup task to your ServiceDefinition.csdef as shown below:


<Startup>
 <Task commandLine="Install.cmd" executionContext="elevated" taskType="background">
  <Environment>   <Variable name="ACTIVATIONKEY" value="<Replace with your Activation Key>" />
  </Environment>
 </Task>
</Startup>


  • Replace the value for the 'ACTIVATIONKEY' with your new activation key obtained from creating your new Stackify account.

This can be seen below from my project:



Now go ahead and perform a deployment as usual.

As soon as your services have been deployed and started, you will be able to see an item for each instance inside Stackify and drill down into the features. Now you can check the current status of a deployment and perform some pretty cool stuff just with your IPad. Not Bad...

One thing to note is that some of the other features focus on developer productivity! Your project manager will love it!!! :)

Monday, 11 March 2013

.Net TDD (Test Driven Development) by example - Part 1


Introduction

In part 1 of this mini-series, we will develop a trivial business logic layer from scratch with a TDD approach with the goal of achieving the following:

  • Better code quality through Red, Green, Refactor
  • Documentation that grows as we develop and remains up to date
  • Automatic regression test harness

This will primarily involve creating unit tests first, having them fail, making them pass and then refactoring the code to be of better quality and then re-running the tests. When using tools such as resharper to aid in refactoring code, having the tests in place right from the beginning really gives you peace of mind that you haven't broken anything. It also helps the thought processes while designing and developing an application or feature to be more targeted.

We will further develop the application in part 2 to add an MVC4 web client and continue the TDD story... 


Some Background

Test First or Test Driven development is a valuable software engineering practice. It comprises of much more than this article could attempt to cover such as Acceptance Test Driven Development (ATDD) and Behaviour driven development (BDD). We will focus on a subset of TDD that encourages developer testing and aids tremendously in shipping software rather than traditionally having testing as a secondary phase or responsibility of a tester and promotes testing as a first class citizen in our everyday software development lifecycle (SDLC). 
How many times have you intended to write unit tests after a feature has been created and due to time constraints ended up leaving it and moving onto the next part of the application with an uncertain feeling that it would have been better to have them in place before adding more complex layers? Following a TDD approach eliminates this as the tests are the first thing to consider as part of an initial implementation.

Development Costs

Fixing bugs after software is shipped has been proven to be much more expensive than having unit tests in place that can be run each time code is about to be checked into source control for minor or substantial changes to the system. Unit testing is also cheaper than Integration testing, System testing and Functional testing. Although not a direct replacement for any of the above, having a large set of unit tests in place gives piece of mind that each days development has been a cost effective one and the code is still in good shape. 

Sample Code

The sample code consists of a library that will return a string Roman numeral representation when passed an integer between 1 and 3000.

The sample code, written using Visual Studio 2012, is deliberately left simple to allow focus on development style rather than getting side tracked with implementation details. It consists of two C# class libraries. The first contains an MS Test class library which will contain our unit tests and the second is a standard class library which we will use to develop the functionality. The unit test project class library is kept separate to ensure we are only testing the public parts of our business logic, without exposing internals to the tests, which are likely to change over time.

The Tools

There are numerous unit testing frameworks available. This article uses the one out of the box with Visual Studio, MS Test. Using NUnit, one of my favourites, or other frameworks would work also and is down to personal preference or the infrastructure you work in. Using MS Test helps the article code to run with no other dependencies.

  • Visual Studio 2012
  • MS Test (included as part of Visual Studio 2012)


Creating the libraries

Because we are working with a TDD approach, it has forced me to think a little ahead of time, even before naming my project. I know I want to provide a library for roman numerals but if I want to test it, the more loosely coupled I keep it, the more it will remain testable. As a result I will name the solution 'AssemblySoft.NumberSystems' to support future number system conversions. Choosing the 'Blank Solution' from Visual studio will get us started as shown below:



Next we will add the Unit Test project as show below:



Lastly for this step, we will create the class library to hold our business logic under test as shown below:



We can go ahead and perform the following:
  •  Delete the default classes created for us in the two projects
  •  Create a new Unit Test as shown and build



If you open the new 'UnitTest1.cs' class file you will be presented with the following:

using System;
using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace NumberSystemConverter_UnitTests
{
    [TestClass]
    public class UnitTest1
    {
        [TestMethod]
        public void TestMethod1()
        {
        }
    }
}

As you can see, it is just a standard class with three noticeable differences
  1. There is a using statement for 'Microsoft.VisualStudio.TestTools.UnitTesting'.
  2. The 'UnitTest1' class is decorated with a [TestClass] attribute.
  3. The 'TestMethod1' method is decorated with a [TestMethod] attribute.
What this tells us is that a reference assembly has been added to our test project and if we look it is named 'Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll'. It further uses this reference with the using namespace and adds attributes to both the class and method, allowing it to know what classes should be used for testing runs and which classes just act as helpers or are just our own code.

In TDD, we are encouraged to first make our test fail with as minimal code as possible. As you get more familiar with the process you can use some reasonable judgement on this and my particular take is to create the minimal piece of usable code as a first step and ensure the test fails. Now you could approach this with a method that does not have a body and just throws a 'NotImplemented' exception or you could think of a valid exception when consumers start using your library to kick things off.

Going Back to the Requirements

My loose requirements dictate that i can get a roman numeral for numbers between 1 and 3000. So here we could also say that entering numbers less than 1 and greater than 3000 should fail both the library but more importantly at this stage the test as we are working in test first. Now although we haven't written a line of meaningful code yet, hopefully, already the thinking surrounding test first is starting to have an effect.

Our First Two Tests - RED

We will leave the existing test method in place and in the code editor, add two new tests, following the same attribute guidelines and the results will be as follows:

        [TestMethod]
        [ExpectedException(typeof(IndexOutOfRangeException))]
        public void Number_Greater_Than_ThreeThousand_Throws_IndexOutOfRangeException_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            converter.ConvertRomanNumeral(3001);
        }

        [TestMethod]
        [ExpectedException(typeof(IndexOutOfRangeException))]
        public void Number_Less_Than_One_Throws_IndexOutOfRangeException_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            converter.ConvertRomanNumeral(-1);
        }

So after adding the above code you are maybe concerned that you don't have a 'RomanNumeralConverter' with a 'ConvertRomanNumeral' method and your code doesn't build. That's ok, it's expected. 

Get the Tests Failing with the Minimal Amount of (useful) Code

We can use visual studio to stub out the class and method declarations for us, all within the test project for now, by using the context menu when selecting the 'RomanNumeralConverter' and selecting 'Generate class for RomanNumeralConverter' as shown below:


Do the same for the method definition as well.

At this stage we have a new .cs file in our test project named 'RomanNumeralConverter.cs' with a class and method definition with no useful implementation. The test methods are now satisfied and the project builds.

The new class is shown below:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace NumberSystemConverter_UnitTests
{
    class RomanNumeralConverter
    {
        internal void ConvertRomanNumeral(int p)
        {
            throw new NotImplementedException();
        }
    }
}

Notice the 'NotImplemented' exception in the body of the method. Going back to our test methods, we added another attribute '[ExpectedException(typeof(IndexOutOfRangeException))]' to each method that states we are expecting an IndexOutOfRange exception, not a NotImplementedException.
If we run our tests now, we should be in that all important first state of 'Fail' or sometimes referred to as 'Red' (from our article heading image).


Using the Test Explorer to View and Run our Tests

Now are tests are in place, let's run the tests by right clicking on the test project and selecting 'Run Tests' as shown below:



This will start the MS Test runner and show the Test Explorer window as shown below:


The Test Explorer allows drilling down into individual tests and aids in diagnosing the reason for a test failure. The screenshot above highlights the exception that was thrown by the 'ConvertRomanNumeral' method. Have a play with the test explorer and get familiar with it. You can run tests in different ways also, you will find what works best for you.

One thing we can go ahead and do is delete the 'TestMethod' that visual studio added as this is passing our test run which is not what we want for the 'red' phase.

We are now ready to move to the next phase which is to pass the test or make it 'Green'

Make the Test Pass (Green)

Our two methods should fail if the number passed into the 'ConvertRomanNumeral' method are less than 1 or greater than 3000. Our tests are expecting an IndexOutOfRangeExcpetion in these cases so let's throw one of those from the method instead if the number supplied is indeed <1 || > 3000.

The amended code is shown below:

internal void ConvertRomanNumeral(int p)
        {
            if (p < 1 || p > 3000)
            {
                throw  new IndexOutOfRangeException("The number supplied is out of the expected range (1 - 3000).");
            }
        }


If we run the two tests again, we will see the tests indeed passing as expected. (Green)

One thing to note at this point is that it is generally good practice to perform the test as a single statement, rather than having branching logic inside the test, this really aids in ensuring the tests are still valid and also deterministic each time you run them. In this case the test is always expecting one thing to happen, an IndexOutOfRange exception.

Refactor

Refactoring is an important step in the TDD lifecycle. When we refactor we are making changes to the internals of our business logic without affecting the public API that our tests are consuming. This step may involve a complete re-write of our implementation, renaming variables, adding further abstractions or design patterns. The important thing to remember though is our test library is a client or consumer of our business library as are other clients. Not changing the public external functionality or API will ensure our tests will still validate our system under test, regardless of internals. In fact this acts as a great way to ensure that when we use tools such as resharper to make our code smarter, we can quickly determine if anything has broken by simply re-running the tests.

Our first stab at making something work when designing and developing a new feature is most often quite different looking than our final code that has been reviewed, sanity checked and is considered a final implementation. The refactor step encourages this in that you can leave the process of housekeeping and as the term indicates, 'refactoring', as a phase in the lifecycle. This really helps with not getting too bogged down trying to create a perfect set of code first time round but rather focus on the design of the API or public interface and on what you want to test, leaving refactoring to this point in the lifecycle.

It gives you a warm feeling to know it's OK to produce a rough first implementation which may contain stubs or whatever it takes to satisfy the API at first. If of course in reality you can craft a useful first implementation in a reasonable time frame as your first cut, then go for it. These are guidelines and should be adopted to suit making you productive but at the same time create a testable system.

Make Some Changes


At this point we can get things tidied up, work some more on the implementation and add features, all with the safe knowledge that we can test (at least two scenarios) after making changes.

Let's do the following to the 'NumberSystemConverter' project:
  • Move the 'RomanNumeralConverter' class into the 'NumberSystemConverter' project
  • Change the namespace for 'RomanNumeralConverter' class to 'NumberSystemConverter' 
  • Add the class access modifier to 'public' for the 'RomanNumeralConverter' class
  • Set the access modifier for 'ConvertRomanNumeral' to 'public'
  • Change the name of the parameter from 'p' to 'number' inside 'ConvertRomanNumeral'
  • Change the return type to string and return an empty string below the if statement block
  • Ensure the project builds

The code for the NumberSystemConverter should be as follows:

using System;

namespace NumberSystemConverter
{
    public class RomanNumeralConverter
    {
        public string ConvertRomanNumeral(int p)
        {
            if (p < 1 || p > 3000)
            {
                throw  new IndexOutOfRangeException("The number supplied is out of the expected range (1 - 3000).");
            }

            return string.Empty;
        }
    }
}


Let's do the following to the 'NumberSystemConverter_UnitTests' project:
  • Remove the 'RomanNumeralConverter' class from the test project
  • Add a reference to the 'NumberSystemConverter' project to the test class
  • Add a using statement to the 'UnitTest1.cs' file to  'NumberSystemConverter'
  • Rename the 'UnitTest1' class to 'RomanNumeralConverterUpperAndLowerBoundsUnitTests'
  • Rename the .cs file the same 
  • Ensure the project builds
  • Run the tests and ensure the results are the same (Fix any bugs introduced in this step if not)

The code for the NumberSystemConverter_UnitTests should be as follows:

using System;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using NumberSystemConverter;

namespace NumberSystemConverter_Tests
{
    [TestClass]
    public class RomanNumeralConverterUpperAndLowerBoundsUnitTests
    {
        [TestMethod]
        [ExpectedException(typeof (IndexOutOfRangeException))]
        public void Number_Greater_Than_ThreeThousand_Throws_IndexOutOfRangeException_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            converter.ConvertRomanNumeral(3001);
        }

        [TestMethod]
        [ExpectedException(typeof (IndexOutOfRangeException))]
        public void Number_Less_Than_One_Throws_IndexOutOfRangeException_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            converter.ConvertRomanNumeral(-1);
        }

        [TestMethod]
        [ExpectedException(typeof (IndexOutOfRangeException))]
        public void Number_Zero_Throws_IndexOutOfRangeException_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            converter.ConvertRomanNumeral(0);
        }

    }

}

After some minor refactoring, we are able to still satisfy that our tests are still passing as they did before.


Introduce More Tests (Red)

Let's add a few more tests for our 'ConvertRomanNumeral' method and also flesh out its implementation some more to cater for the numbers 1 - 3000.

Let's do the following to the 'NumberSystemConverter_UnitTests' project:
  • Add a new TestClass in the same file named 'RomanNumeralConverterExpectedValuesUnitTests'
  • Add method: Number_Equal_One_Expected_Result_I_TestMethod
  • Add method: Number_Equal_ThreeThousand_Expected_Result_MMM_TestMethod
  • Add method: Number_Equal_55_Expected_Result_LV_TestMethod
  • Add method: Number_Equal_100_Expected_Result_C_TestMethod
  • Add method: Number_Equal_500_Expected_Result_D_TestMethod
  • Add method: Number_Equal_599_Expected_Result_DLXXXXVIIII_TestMethod
  • Add method: Number_Equal_2013_Expected_Result_MMXIII_TestMethod
The code for the new methods is shown below:

[TestClass]
    public class RomanNumeralConverterExpectedValuesUnitTests
    {
        [TestMethod]
        public void Number_Equal_One_Expected_Result_I_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            var result = converter.ConvertRomanNumeral(1);

            Assert.AreEqual(result, "I");

        }

        [TestMethod]
        public void Number_Equal_ThreeThousand_Expected_Result_MMM_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            var result = converter.ConvertRomanNumeral(3000);

            Assert.AreEqual(result, "MMM");

        }

        [TestMethod]
        public void Number_Equal_55_Expected_Result_LV_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            var result = converter.ConvertRomanNumeral(55);

            Assert.AreEqual(result, "LV");
        }

        [TestMethod]
        public void Number_Equal_100_Expected_Result_C_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            var result = converter.ConvertRomanNumeral(100);

            Assert.AreEqual(result, "C");
        }

        [TestMethod]
        public void Number_Equal_500_Expected_Result_D_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            var result = converter.ConvertRomanNumeral(500);

            Assert.AreEqual(result, "D");
        }

        [TestMethod]
        public void Number_Equal_599_Expected_Result_DLXXXXVIIII_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            var result = converter.ConvertRomanNumeral(599);

            Assert.AreEqual(result, "DLXXXXVIIII");
        }

        [TestMethod]
        public void Number_Equal_2013_Expected_Result_MMXIII_TestMethod()
        {
            var converter = new RomanNumeralConverter();
            var result = converter.ConvertRomanNumeral(2013);

            Assert.AreEqual(result, "MMXIII");
        }

    }

There are a few things worth noting about the methods. Their names are descriptive of their purpose. This makes it easy to understand what the purpose of the test is. Secondly by adding classes for specific types of test, we have been able to isolate bounds checking tests from those that are for specific numeric values. This also aids dramatically further down the road when you need to come back and find the tests that you're new fix or feature my well impact.

You will notice the heavy use of the 'Assert' keyword for comparing the results from the majority of tests in this section. This is a common practice but it should be stated that this is only the tip of the iceberg in terms of options on how to determine and compare results. Each framework has a multitude of different options, some dealing with collections, strings, bools and other types. Needless to say, this is a learning adventure and each time you adhere to and grow your understanding of this way of developing new features, your arsenal of best ways to test a value will also increase.

We should now be able to run our new tests and indeed see them fail as our 'ConvertRomanNumeral' method will in all but two cases return an empty string. This can be seen below:



Well that was what we expected and we can also see that the return value is indeed an empty string inside the expected result for the test.

You will notice as before that each test is attempting to evaluate a single statement, in this case with a single dedicated Assert.

Make the Test Pass (a second time) (Green)

We will add some implementation to the 'ConvertRomanNumeral' method and some supporting data to aid in providing passes for the new tests.

The first thing we will do is add some supporting types as shown below:

    #region Supporting Types

    /// <summary>
    /// Roman Numerals
    /// </summary>
    /// <remarks>
    /// There are seven symbols that can be used to write any roman numeral
    /// </remarks>
    enum RomanNumeralsType
    {
        M = 1000,
        D = 500,
        C = 100,
        L = 50,
        X = 10,
        V = 5,
        I = 1
    }

    internal class RomanNumeralPair
    {
        public int NumericValue { get; set; }
        public string RomanNumeralRepresentation { get; set; }
    }

    #endregion

As roman numerals are only made up of seven different symbols, this should suffice.

The next part is to use the data to create an in memory list of number / roman numeral pairs so that we can later use it inside our 'ConvertRomanNumeral' method. This is shown below:

private readonly List<RomanNumeralPair> _romanNumeralList;

        public RomanNumeralConverter()
        {
            _romanNumeralList = new List<RomanNumeralPair>()
                {
                    new RomanNumeralPair()
                        {
//... 1000
                            NumericValue = Convert.ToInt32(RomanNumeralsType.M),
                            RomanNumeralRepresentation = RomanNumeralsType.M.ToString()
                        },
                    new RomanNumeralPair()
                        {
//... 500
                            NumericValue = Convert.ToInt32(RomanNumeralsType.D),
                            RomanNumeralRepresentation = RomanNumeralsType.D.ToString()
                        },
                    new RomanNumeralPair()
                        {
//... 100
                            NumericValue = Convert.ToInt32(RomanNumeralsType.C),
                            RomanNumeralRepresentation = RomanNumeralsType.C.ToString()
                        },
                    new RomanNumeralPair()
                        {
//... 50
                            NumericValue = Convert.ToInt32(RomanNumeralsType.L),
                            RomanNumeralRepresentation = RomanNumeralsType.L.ToString()
                        },
                    new RomanNumeralPair()
                        {
//... 10
                            NumericValue = Convert.ToInt32(RomanNumeralsType.X),
                            RomanNumeralRepresentation = RomanNumeralsType.X.ToString()
                        },
                    new RomanNumeralPair()
                        {
//... 5
                            NumericValue = Convert.ToInt32(RomanNumeralsType.V),
                            RomanNumeralRepresentation = RomanNumeralsType.V.ToString()
                        },
                    new RomanNumeralPair()
                        {
//... 1
                            NumericValue = Convert.ToInt32(RomanNumeralsType.I),
                            RomanNumeralRepresentation = RomanNumeralsType.I.ToString()
                        }

                };

Now we have a lookup, it's time to attempt to use it (newly added code in bold) as shown below:

        public string ConvertRomanNumeral(int number)
        {
            if (number < 1 || number > 3000)
            {
                throw new IndexOutOfRangeException("The number provided is outside the expected range ( 1 - 3000)");
            }

            var builder = new StringBuilder();
            
            //iterate through the list, starting with the highest value
            foreach (var currentPair in _romanNumeralList)
            {
                while (number >= currentPair.NumericValue)
                {//...number is greater than or equal to the current value so store the roman numeral and decrement it's value 
                    builder.Append(currentPair.RomanNumeralRepresentation);
                    number -= currentPair.NumericValue;
                }
            }

            return builder.ToString();
        }
After adding some new implementation as part of the green phase, we are now able to perform our next round of testing.

Debugging Tests

One thing worth mentioning at this point is that sometimes you will write code that you are convinced will pass the test but doesn't, usually because of something you have overlooked, at least that's what happens in my case ;) So the thing to do here as you would normally is to crack open the debugger. In our example here it fits quite well as it is generally more difficult to debug two class libraries without some kind of client or without attaching a debugger explicitly. Fortunately in this case with using the MS Test Framework which is already baked into visual studio, using the debugger to debug a test is as easy as right clicking on the specific test in test explorer, or right clicking while in the test method in the visual studio code editor and selecting 'debug tests' This will automatically attach the debugger in context where you can step through normally.

So the results of the last implementation and test run can be seen below:



Refactor (round two)

At this stage I went ahead and tidied up some more, moved some logic into a lookup, added some comments and did a round of refactoring. I would recommend using resharper or another code quality tool, make your changes, run the tests again, make sure your happy and get the code checked in for the day.


Conclusion

We have really only touched on the TDD story but hopefully some of you find it useful, especially if not familiar with Red, Green Refactor. Creating unit tests as a first step in developing new features has many benefits. Once the tests are in place, you have a live set of documentation which not only demonstrates the requirements but helps enforce them every day you develop, acting as an automatic regression test harness. It may at first seem like more work than just focusing on an implementation detail but as you adopt these kinds of approaches it lends a hand in both the way you think about a problem and also acts as a safeguard for every new change that gets made to the code base.

The next article will take this approach further, looking at the client testing challenges as well as applying similar techniques to existing legacy code (brownfield).  

The areas we looked at
  • Red, Green, Refactor - Fail, Pass, Change
  • Well structured code - the process encourages more decoupled design 
  • Self documenting - start with a specification and then enforce it
  • Automatic regression test harness - if someone breaks something, the tests will scream

Revision History

11th March 2013 - First revision with code.

Friday, 1 March 2013

Adding mobile support for MVC4 Web Applications

A few years ago, mobile web sites were more of an after-thought for many developers unless you were involved in developing apps specifically targeted for mobile devices. I was surprised to read on wiki that it was only March 2010 when Apple began taking pre-orders for the iPad. What a different landscape we have seen since. Desktops, Tablet and Mobile support are now a major design goal for any site that needs a broad reach and this is only set to increase.


 


This article will demonstrate how MVC4, almost out of the box allows us to deliver views that cater for specific mobile devices and keep the code base shared as much as possible, creating mobile friendly web applications. Read complete article...

Wednesday, 27 February 2013

Staying healthy == better code...




As developers on any given day we may put on the hat of many different roles such as the requirements gatherer, interpreter, problem solver, designer, coder, user, tester and many more...

This article aims to highlight links between good coding, more productive development and some best practices for the most sophisticated of systems, our bodies. I encourage you to comment and suggest other techniques that you have found beneficial also.


Let’s get one thing said before we kick off. I for one have been on projects where caffeine and junk food where absolutely necessary to crank out a big ‘go live’ or update code over a 24hr period that could affect hundreds of thousands of people or involved in a hackathon guerrilla event where commodes were more efficient than using the bathroom J. However, when the dust settles and things are a little more normal and day to day, good health habits can make a big difference to not only help you think more clearly but deal with those high pressure situations when they arise tomorrow.




Diet

When I was a kid I remember a book entitled “You are what you eat”. It’s a phrase that stuck and sometimes makes a difference when I am choosing my lunch.
There is a ton of differing opinions when it comes to diet so here goes mine. “Balance” That single word gives me complete freedom to eat what I want but at the same time keeps me conscious of what my body needs.
I recently did a 2 week Juice diet in an attempt to lose a bit of weight and fill my body with nutrients, enzymes and basically feel more energised. It worked, I lost about 7lbs and genuinely felt better. Now I have that as a plan at least once a year to do something similar.
Drinking plenty of water each day has been proven to increase concentration, something as developers we need a lot of.
Avoiding a big lunch can aid in productivity because needed energy is not spent breaking down food and means you escape the urge to have nap under your desk.


Posture

We have all had the memo or meeting about screen height or keyboard position. I bought a chair last year which forces good posture. If I sit in it for longer than 2 hours my knees have no feeling J but the point is that switching position and being aware of your sitting position is really important. Our bodies have not been designed for long hours of sitting in the same position so the more you move in between or change position the better. 

Below is a chair I have in my office which you are supposed to switch over to for a while each day, it claims to force good posture. It looks a little like a torture device but it does seem to work. The Knees go in first with the bottom on the top part, guiding the back in a vertical angle. The main benefits focus around the lower back which tends to take a lot of strain during a day of sitting.






Exercise

On a previous developer role we were given a reduced membership at a local health club. So once or twice a week I embarked on having a swim over lunch. Wow what a difference, that complete somewhat forced break really helped me focus better in the afternoon. Swimming is renowned for working many muscles in the body including the lower back which any coder sitting for long periods of time can suffer a bit with.
What about getting to and from work? I was working on a train route for a while and was able to cycle from home to the train and at the other end for a total of about 4 miles. Then at the end of the day it’s all reversed. I can honestly say it was great. Sure I got wet a few times but nothing a pair of waterproofs couldn’t solve, but also I enjoyed many sunny mornings and evenings which is surprisingly relaxing before getting home. There is something very satisfying about arriving home after work, knowing that you already did your exercise for the day during normal work hours.
Everyone’s schedule is different and only you know yours. The point is try and make room for something each day which gets your heart pumping a little and produces stress relieving endorphins.  


Take a break

I was one of the world’s worst at just working through problems without taking a break. However by taking a break, and by that I mean leaving your desk, going for a walk outside the office for some minutes, even when under pressure can make a massive difference to your whole approach to a problem.       



Sleep on it

Sometimes you take a break and you still spend the rest of the day on that, and I quote “Impossible Problem” and can’t see the wood for the trees. Don’t despair, sometimes you need to put the problem down, shift your attention to something a little lighter and just sleep on it. If I had a pound for the times I woke the next morning with a solution to a problem or sometimes in the middle of the night I would be a rich man. The brain is very powerful and sometimes we just need to let its thing.

You may have heard of young developer named Santiago Gonzalez on YouTube where he says "I Dream In Code". Well Santiago, we have news for you, we all do if we just let go and let our brain do it's thing as we sleep.

Don’t take yourself too seriously

Some studies suggest that some seemingly healthy lifestyle’s can lead to stress. My take is that some can worry so much about health and body matters that they basically fail to enjoy life along the way, causing more anxiety and stress than the efforts to avoid it. Don’t be afraid to laugh at yourself once in a while. As developers we can sometimes get a bit proud of our code and not take criticism easily. Remember that every system ever written contains bugs. If another dev. points out something in a code review, embrace it, learn and let go. Life is too short for perfection. Find something to make you chuckle each day, and remember the healing power of laughter.



Mind

To develop software well requires a certain amount of discipline. Adding comments, creating unit tests, refactoring, just to mention a few, requires effort on our part. If we train our minds to be disciplined outside of work, it becomes a lot less effort in work to desire that all the planets are aligned and our code and supporting documentation is kept up to date. Having said that creative minds are often not very tidy ones.
As the mind is the most complex of all body parts it is important to avoid stress outside of work. This allows it to focus and work out complex problems with a lot more ease. My personal observation has been that happy individuals with a good friend or family supporting network, tend to be able to focus better and find solutions to problems faster.


Checklist

·         Eat Well
·         Sit Well
·         Take Breaks
·         Exercise
·         Drink plenty of water
·         Laugh
·         Get enough sleep


Conclusion

I am certainly not a health freak, nor a fitness fanatic but I do believe that if you take a balanced approach and most importantly give it some thought, you can definitely increase your productivity and wellbeing which ends up making you more successful and productive as developers.