Ludwig's Blog

Blog moved

Ludwig Stuyck — Sat, 29 May 2010 22:21:35 +0000

I moved my blog to http://www.dunatis.be.

Visual Studio 2010 style

Ludwig Stuyck — Mon, 03 May 2010 08:07:06 +0000

The default colors of visual studio are, well, kind of boring. But now it’s possbible to change that with only a few mouse clicks! First go to http://studiostyles.info and download your favorite style. Then, in visual studio 2010, select Tools > Import and Export Settings:

Check the Import selected environment settings, and click Next.

You probably want to save the current settings, so accept the default and click Next.

Then click the Browse button and select the template you downloaded:

…and then the Next button.

Finally click the Finish button.

And if everything was ok:

Click Close, and behold the new style

Transform collection to comma separated list

Ludwig Stuyck — Tue, 27 Apr 2010 08:47:02 +0000

Today I had to transform a collection of integers into a string in the form of a comma separated list. In the ‘old-style- approach it would probably be something like:

List numbers = new List() { 1, 2, 3, 4, 5 };
StringBuilder strb = new StringBuilder();
foreach (int number in numbers)
{
    strb.Append(number.ToString());
    strb.Append(",");
}
string commeSeparatedList = strb.ToString().TrimEnd(',');

But actually this can be done in a short way, like:

List numbers = new List() { 1, 2, 3, 4, 5 };
string commeSeparatedList = string.Join(",", numbers.Select(n => n.ToString()).ToArray());

which produces the same result. In my case it was not a collection of integers, but a list of objects; but is the same approach:

string commaSeparatedListOfGroups = string.Join(",", allRelatedGroups.Select(g => g.Id.ToString()).ToArray());

Visual Studio 2010 installation

Ludwig Stuyck — Tue, 13 Apr 2010 08:00:19 +0000

Visual Studio 2010 is out, and of course I installed it right away. During installation, it seemed that someone was getting really jealous

Sort projects alphabetically in Visual Studio

Ludwig Stuyck — Wed, 10 Mar 2010 12:47:23 +0000

It is a well-known bug in Visual Studio that projects in solution folders are not sorted alphabetically. In solutions with a lot of projects this is often a problem, because it’s kind of hard to find the project you need. So I needed a way to permanently sort projects in solution folders, and it’s actually very easy to do.

Let’s say you have the following visual studio solution:

The project AAA was added after the project ZZZZZZ, so it’s not alphabetically sorted. In order to sort it, right click the ZZZZZZ project and select Rename. Then select another project to end the edit. As you will see, the projects will be sorted:

And then, and this is important, be sure to collapse the solution folders, and then quit and restart Visual Studio. You will then see that the projects remain sorted!

Clone objects

Ludwig Stuyck — Wed, 03 Mar 2010 15:17:47 +0000

Today a collegue asked for a clean way to clone objects in C#, so that you really have different objects instead of a reference copy . So imagine that you have a class Employee as follows:

public class Employee
{
  public string FirstName { get; set; }
  public string LastName { get; set; }
}

and you would copy it:

Employee original = new Employee()
{
  FirstName = "Homer",
  LastName = "Simpson",
};
Employee copy = original;
copy.FirstName = "Marge";
Console.WriteLine(string.Format("{0} {1}", original.FirstName, original.LastName));
Console.WriteLine(string.Format("{0} {1}", copy.FirstName, copy.LastName));

Changing the first name of the copied object obviously also changes the first name of the original object, because it has been copied by refererence and so original and copy refer to the same object:

And this was not wat we wanted.

To solve it, we first write an extension method that will be available on each class that implements the ICloneable interface:

static class Extensions
{
  public static T Clone(this T objectToClone) where T : ICloneable
  {
    return (T)objectToClone.Clone();
  }
}

Next we have to make the Employee class implement the ICloneable interface:

public class Employee : ICloneable
{
  public string FirstName { get; set; }
  public string LastName { get; set; }

  #region ICloneable Members
  public object Clone()
  {
   return new Employee() {FirstName = FirstName, LastName = LastName};
  }
 #endregion
}

And if we now use the Clone method like:

Employee copy = (Employee)original.Clone();

then the new object is really a copy of the original:

If you want to clone a list of objects, add an extension method like this:

static class Extensions
{
  public static IList Clone(this IList listToClone) where T : ICloneable
  {
    return listToClone.Select(item => (T)item.Clone()).ToList();
  }
}

and to clone this list is then very simple:

IList copiedList = originalList.Clone();

This example clones only the Employee object (known as shallow copy, see here), but what if the Employee class contains other reference types? In this case we have to implement a deep copy, meaning that every subclass has to implement ICloneable too, for example, if you have a City:

public class City: ICloneable
{
  public string CityName { get; set; }
  #region ICloneable Members
  public object Clone()
  {
    return new City() { CityName = CityName };
  }
  #endregion
}

then Employee has to clone it like:

public class Employee : ICloneable
{
  public string FirstName { get; set; }
  public string LastName { get; set; }
  public City City{ get; set; }
  #region ICloneable Members
  public object Clone()
  {
    return new Employee() {FirstName = FirstName, LastName = LastName, City = (City)City.Clone() };
  }
  #endregion
}

We can do one other improvement. As you see we always have to cast the Clone operation to its actual type. To solve that we can create a generic ICloneable interface:

interface ICloneable : ICloneable
{
  new T Clone();
}

and adapt the classes to it:

public class Employee : ICloneable
{
  public string FirstName { get; set; }
  public string LastName { get; set; }
  public City City{ get; set; }
  #region ICloneable Members
  Employee ICloneable.Clone()
  {
    return new Employee() { FirstName = FirstName, LastName = LastName, City = City.Clone() };
  }
  #endregion

  #region ICloneable Members
  object ICloneable.Clone()
  {
    return new Employee() { FirstName = FirstName, LastName = LastName, City = City.Clone() };
  }
  #endregion
}

public class City : ICloneable
{
  public string CityName { get; set; }
  #region ICloneable Members
  public City Clone()
  {
    return new City() { CityName = CityName };
  }
  #endregion

  #region ICloneable Members
  object ICloneable.Clone()
  {
    return new City() { CityName = CityName };
  }
  #endregion
}

Castle MicroKernel/Windsor QuickStart 2: LifeStyle and LifeCycle

Ludwig Stuyck — Mon, 01 Mar 2010 08:28:39 +0000

…continued from part 1.

Objectives

In this Hands-On Lab, you will be introduced to the Castle MicroKernel/Windsor framework. In particular, you will:

Understand LifeStyle
Understand LifeCycle

System requirements

You must have the following items to complete this lab:

Microsoft Visual Studio 2008 SP1 (professional edition)

Prequisites

You must have the following skills to understand this lab:

Fundamental knowledge of software development in .NET 3.5
Basic knowledge of Castle

Understand LifeStyle

LifeStyle is a strategy that is related to an instance of a component. The supported lifestyles are:

Singleton: only one instance will be created for the whole life of the container. This is the default lifestyle.
Transient: for each request a new instance if the component is created
PerThread: for each thread there exists only one instance of a component
Pooled: Instances will be pooled to avoid unnecessary constructions
Custom: the instantiation of components is handled by your custom ILifestyleManager implementation

The default lifestyle is singleton. To indicate which lifestyle you want to use, you can use attributes to decorate the class:

[Transient]
public class CustomerRepository : ICustomerRepository
{
    …
}

or in the configuration file:



  
    
  
  
    
      lifestyle="transient"
        type="CastleExample.CustomerBusiness, CastleExample" />
      lifestyle="transient"
        type="CastleExample.MockCustomerRepository, CastleExample" />

I prefer to do it in configuration because otherwise the code will be coupled again to the Castle container, or, in complicated projects, it may be handier to do it in code but in that case, create specific classes that are responsible for these configuration tasks, so that in your code you have as little as dependencies to Castle as possible.

So try this: add a transient lifestyle to the components in the configuration file, and to see the effect, modify the constructor of CustomerBusiness and add constructors to CustomerRepository and MockCustomerRepository as follows:

public class CustomerBusiness : ICustomerBusiness
{
  private ICustomerRepository customerRepository;
  public CustomerBusiness(ICustomerRepository customerRepository)
  {
    // using constructor injection the concrete customer repository is injected
    this.customerRepository = customerRepository;
    Console.WriteLine("CustomerBusiness constructor");
  }
  …
}

public class CustomerRepository : ICustomerRepository
{
  public CustomerRepository()
  {
    Console.WriteLine("MockCustomerRepository constructor");
  }
  …
}

public class MockCustomerRepository : ICustomerRepository
{
  public MockCustomerRepository()
  {
    Console.WriteLine("MockCustomerRepository constructor");
  }
  …
}

Modify Program.cs:

static void Main(string[] args)
{
  …
  // Use business
  UseRegisteredBusiness();
  UseRegisteredBusiness();
  UseRegisteredBusiness();
}

If you run the application, you will notice that each constructor is only called once and so there is only one instance created of the components for all calls:

Change the configuration that components use the transient lifestyle, and then run the application again to see the difference:

Now for each call of the business component, the constructors are called, which means that new objects are created for each call.

Understand LifeCycle

On the other hand there is LifeCycle, which is a strategy that is related to the different phases of an instance. It means that we can implement a number of interfaces; and these implementations are executed at the right time. Out of the box there are two groups of lifecycles:

Commission: these are executed when the component is being created. Interfaces are:
- Castle.Model.IInitializable
- System.ComponentModel.ISupportInitialize
Decommission: these are executed when the component is being destructed. Interface is:
- System.IDisposable

So, bottom line: if you implement one of these interfaces for your component, Castle will take care of calling your implementations at the right time. Notice that if you use these, the coupling to Castle container will be higher.

Castle MicroKernel/Windsor QuickStart 1: introduction

Ludwig Stuyck — Fri, 26 Feb 2010 16:38:18 +0000

Objectives

In this Hands-On Lab, you will be introduced to the Castle MicroKernel/Windsor framework. In particular, you will:

Understand IoC and DI
Download Castle Windsor
Create a test application
Use configuration file

System requirements

You must have the following items to complete this lab:

Microsoft Visual Studio 2008 SP1

Prequisites

You must have the following skills to understand this lab:

Fundamental knowledge of software development in .NET 3.5

Understand IoC and DI

Inversion of Control (IoC) and Dependency Injection (DI) are two related practices in software development which are known to lead to higher testability and maintainability of software products.

In the traditional way of coding, you instantiate the objects you want to use, so this means that at compile time you know which are the real classes you are going to interact with – you call them directly. So it means that you are in control, and not the consumers of your code. If you invert this, it would mean that you don’t know what the real classes are: someone else (the consumer) decides which will be the real classes, and how they will be instantiated. In this case you don’t know the concrete classes, but you only know the interfaces, and you don’t care about the actual implementation that is used. Therefore there are less dependencies and the coupling in a system is reduced. In fact, the control of dependency creation is pushed outside of the class itself. It is all about removing dependencies from your code.

A simple example: have a look at the following code:

public class Car
{
  Engine engine;
  public Car()
  {
    engine = new Engine();
  }
}

We have a extremely strongly dependency between Car and Engine, because the Engine is instantiated in the Car, so we can’t install any other engine inside this car. To make this code better, we change it slightly:

public class Car
{
  IEngine engine;
  public Car(IEngine engine)
  {
    this.engine = engine;
  }
}

Notice the difference? The control of creation of the engine has been moved out of the car. Now the code that creates the car also chooses the engine: this is inversion of control. Inversion of control is also known as the Hollywood principle: ‘don’t call me, I call you’, so in this case it’s like the Engine class saying to the Car class: ‘don’t create me, I will be created by someone else’.

Another concrete (simplified) example: in the following picture, a client uses the CustomerBusiness component, which uses the CustomerRepository component to access the database. You see that CustomerBusiness has a hard reference to the concrete CustomerRepository:

Now imagine that we want to add unit tests to test the business component:

Now we have a problem, because when we test the business component we don’t want it to use the real CustomerRepository but a mock implementation of it. In the current architecture, we do not have this flexibility. To solve this, we can use the IoC pattern: let the Client and Unit test decide which repository the business component should use. So, the CustomerBusiness component no longer decides what repository it uses. To achieve this, we create a ICustomerRepository interface. This interface is then implemented by the CustomerRepository (this implementation uses the real database) and also by the MockCustomerRepository (this implementation uses no database, but mock data). The CustomerBusiness component now has only a reference to the ICustomerRepository interface, and it doesn’t know what the real implementation is, and it doesn’t care:

The control of which repository is used is inverted to the client (wants the business component to use CustomerRepository) and the unit test (wants the business component to use MockCustomerRepository).

In a further step we can do the same for every component: create your interface first and then one or more implementations. So in our example also the business component can be abstracted, although we have only one implementation at this time:

It takes a while to understand this approach because it’s a mind shift and has a certain learning curve: the way you build your software changes. But using these principles eventually lead to better structured, modularized, testable and maintainable applications. Once you get used to it, it actually becomes a habit to build software this way.

To summarize, the advantages are:

loose coupling between components: you share contracts, not implementations
flexibility: it’s easy to change behavior
easy to test components: replace dependencies by mocking components so that you can really test what you want to test
improve code reuse: each component has its responsibility
extensibility: future changes can be implemented easily by injecting new implementations

Dependency creation is often delegated to inversion of control containers, frameworks that allow needed dependencies to be injected automatically; this process is called dependency injection.

There are a number of such frameworks that supply these patterns, like Castle, StructureMap, Spring.NET, Autofac, Unity, NInject and others, but they all implement about the same principles; although Castle has also a number of aspect oriented features. In these quickstarts we will be using Castle.

Download Castle

You need the Castle Project assemblies on your local machine, so download the project release at http://www.castleproject.org/castle/download.html.

Create a test application

We are going to create a simple test application to demonstrate the basics of Castle. Start Visual Studio and create a new console application called CastleExample. Add references to the following assemblies:

Castle.Core.dll
Castle.DynamicProxy2.dll
Castle.MicroKernel.dll
Castle.Windsor.dll

We are going to implement the example from previous chapter in a simple way, focusing on how to use Castle to achieve dependency injection. We start by defining the domain object for customer, so add a new class Customer:

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

namespace CastleExample
{
    public class Customer
    {
        public int Id{ get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
    }
}

Then we design the interface for the customer repository. Add a new class ICustomerRepository:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace CastleExample
{
    public interface ICustomerRepository
    {
        Customer CreateCustomer(Customer customer);
        List ReadCustomers();
        void DeleteCustomer(int Id);
    }
}

We already now that we will have two implementations for this interface: a real one, using a database; and one that uses mock data. For the real one, add a class CustomerRepository:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace CastleExample
{
    public class CustomerRepository : ICustomerRepository
    {
        #region ICustomerRepository Members
        public Customer CreateCustomer(Customer customer)
        {
            // TO DO: Create customer in database here
            Console.WriteLine("CreateCustomer in CustomerRepository");
            return null;
        }
        public List ReadCustomers()
        {
            // TO DO: Read customers from database here
            Console.WriteLine("ReadCustomers in CustomerRepository");
            return null;
        }
        public void DeleteCustomer(int Id)
        {
            // TO DO: Delete customer in database here
            Console.WriteLine("DeleteCustomer in CustomerRepository");
        }
        #endregion
    }
}

For the mock repository, add a class MockCustomerRepository:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace CastleExample
{
    public class MockCustomerRepository : ICustomerRepository
    {
        #region ICustomerRepository Members
        public Customer CreateCustomer(Customer customer)
        {
            // Mock a newly created customer
            Console.WriteLine("CreateCustomer in MockCustomerRepository");
            return null;
        }
        public List ReadCustomers()
        {
            // Mock a list of customers
            Console.WriteLine("ReadCustomers in MockCustomerRepository");
            return null;
        }
        public void DeleteCustomer(int Id)
        {
            // Mock delete
            Console.WriteLine("DeleteCustomer in MockCustomerRepository");
        }
        #endregion
    }
}

Note that we don’t actually implement CustomerRepository and MockCustomerRepository, we just use Console.WriteLine to demonstrate the effect later.

Now let’s write the Main method in the Program.cs file:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Castle.Windsor;
namespace CastleExample
{
    class Program
    {
        private static IWindsorContainer container;
        static void Main(string[] args)
        {
            // Register components
            container = new WindsorContainer();
            container.AddComponent("customer.repository");
            // Use repository
            UseRegisteredRepository();
        }
        public static void UseRegisteredRepository()
        {
            // Get the actual registered customer repository
            ICustomerRepository customerRepository =
                    container.Resolve();
            customerRepository.ReadCustomers();
        }
    }
}

In the Main method we first initialize a new WindsorContainer object, and then we indicate that whenever a ICustomerRepository interface is used in our code, we want the actual object to be of type CustomerRepository. So here we register the component, which doesn’t mean that it is already instantiated – this is only done when it’s needed.

Then, in the UseRegisteredRepository method, we use the container again to get the actual customer repository and we can use its methods.

Run the application, and as expected we can see that the ReadCustomers of the CustomerRepository class is being called:

Now let’s change this so that the MoclCustomerRepository is used:

static void Main(string[] args)
{
    // Register components
    container = new WindsorContainer();
    container.AddComponent("customer.repository");

   // Use repository     UseRegisteredRepository();
}

Run the application again, and verify that this time the ReadCustomers of the MockCustomerRepository class is being called:

Let’s add the business component. Again, first add a class ICustomerBusiness for the interface:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace CastleExample
{
    public interface ICustomerBusiness
    {
        Customer AddCustomer(Customer customer);
        List GetCustomers();
        void RemoveCustomer(int Id);
    }
}

We know we have one implementation at the moment, so add a class CustomerBusiness as follows:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace CastleExample
{
    public class CustomerBusiness : ICustomerBusiness
    {
        private ICustomerRepository customerRepository;
        public CustomerBusiness(ICustomerRepository customerRepository)
        {
            // using constructor injection the concrete customer repository is injected
            this.customerRepository = customerRepository;
        }
        #region ICustomerBusiness Members
        public Customer AddCustomer(Customer customer)
        {
            return customerRepository.CreateCustomer(customer);
        }
        public List GetCustomers()
        {
            return customerRepository.ReadCustomers();
        }
        public void RemoveCustomer(int Id)
        {
            customerRepository.DeleteCustomer(Id);
        }
        #endregion
    }
}

Note that we never instantiate the customer repository that is to be used. Instead, in the constructor we accept a parameter of type ICustomerRepository, and we use that in the business component without caring about what the real implementation looks like. Thanks to constructor injection, the real object to be used will be injected by the caller.

Finally, modify Program.cs to test this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Castle.Windsor;
namespace CastleExample
{
    class Program
    {
        private static IWindsorContainer container;
        static void Main(string[] args)
        {
            // Register components
            container = new WindsorContainer();
            container.AddComponent("customer.business");
            container.AddComponent("customer.repository");
            // Use repository
            UseRegisteredRepository();
            // Use business
            UseRegisteredBusiness();
        }
        public static void UseRegisteredRepository()
        {
            // Get the actual registered customer repository
            ICustomerRepository customerRepository =
                container.Resolve();
            customerRepository.ReadCustomers();
        }
        public static void UseRegisteredBusiness()
        {
            // Get the actual registered customer business
            ICustomerBusiness customerBusiness =
               container.Resolve();
            customerBusiness.GetCustomers();
        }
    }
}

Now the Main method decides what business component will be used (CustomerBusiness), and what repository component will be used (MockCustomerRepository). When the CustomerBusiness object is created, Castle notices that it has a constructor that accepts an interface (ICustomerRepository) and injects the actual implementation for this interface as configured in the beginning of the Main method.

Run the application again to see if the second line in the console output is indeed MockCustomerRepository:

To summarize, what we have done it enabled the client to choose which actual implementations of ICustomerBusiness and ICustomerRepository it wants to use. The business component itself only knows the interface of the repository, not the actual implementation. It means that we now have a way to easily change the implementation: a real client would register the real CustomerRepository, a unit test would register the MockCustomerRepository.

To demonstrate another form of injection, property injection, create a new class Tester that contains our testing methods and also two properties customerBusiness and customerRepository :

public class Tester
{
  // These properties will be injected
  public ICustomerBusiness customerBusiness { get; set;}
  public ICustomerRepository customerRepository { get; set; }
  public void UseRegisteredRepository()
  {
    // Get the actual registered customer repository
    customerRepository.ReadCustomers();
  }

  public void UseRegisteredBusiness()
  {
    // Get the actual registered customer business
    customerBusiness.GetCustomers();
  }
}

and change the Main() method as follows:

static void Main(string[] args)
{
  // Register components
  container = new WindsorContainer();
  container.AddComponent("customer.business");
  container.AddComponent("customer.repository");
  container.AddComponent("tester"); 
  Tester tester = container.Resolve();
  tester.UseRegisteredRepository();
  tester.UseRegisteredBusiness();
}

As you can see the Tester class has to properties that will be injected automatically by Castle when they are used.

Note however that the use of constructor injection is preferred, because when you use this you have an explicit indication of a dependency that has to be fulfilled – you know it at compile time. If you use property injection, run-time exceptions may occur.

Use configuration file

In the previous example we used code to configure the container, but of course we have more flexibility if we would be able to do that in a configuration file.
Add a configuration file to the project, and add a section to configure Windsor Container:

Then add the components we need:

Finally, we need to create the Windsor Container passing a configuration interpreter and a resource in the Main method:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Castle.Core.Resource;
using Castle.Windsor;
using Castle.Windsor.Configuration.Interpreters;
namespace CastleExample
{
    class Program
    {
        private static IWindsorContainer container;
        static void Main(string[] args)
        {
            // Register components
            container =
                new WindsorContainer(
                    new XmlInterpreter(new ConfigResource("castle")));

            // Use repository
            UseRegisteredRepository();
            // Use business
            UseRegisteredBusiness();
        }
        public static void UseRegisteredRepository()
        {
            // Get the actual registered customer repository
            ICustomerRepository customerRepository =
                container.Resolve();
            customerRepository.ReadCustomers();
        }
        public static void UseRegisteredBusiness()
        {
            // Get the actual registered customer business
            ICustomerBusiness customerBusiness =
                container.Resolve();
            customerBusiness.GetCustomers();
        }
    }
}

Run the application and it will now use the configuration file.

In the next part we will investigate LifeStyle and LifeCycle.

A reference architecture (Part 2)

Ludwig Stuyck — Wed, 20 Jan 2010 09:25:45 +0000

…continued from part 1.

In the previous part of this series I explained the general architectural guidelines. Of course it is very important to have a consistent organization of all the solutions and projects in an organization, so that’s what I will discuss in this post.

Solution structure

The general pre-defined structure of solution and projects looks like this:

Solution structure

As you can see this structure reflects the architectural layers as described in previous part of this series:

The Manager solution folder contains all managers
The Agent solution folder contains all agents
The Utility solution folder contains all utilities
The BusinessEntity solution folder contains all business entities
The Client solution folder contains all client applications

Manager solution folder in detail

Each manager has the same structure. As an example, this is how the structure of the Stock manager looks like:

Manager structure

Again, this reflects the architectural design as described earlier: the Stock manager is located in the solution folder Manager\Stock. This folder has the following projects:

Schepers.Manager.Stock.ServiceInterface: service contracts, message contracts and data contracts of the Stock manager
Schepers.Manager.Stock.ServiceAdapter: service adapter of the Stock manager
Schepers.Manager.Stock.Business: business logic of the Stock manager

Agent and utility solution folder in detail

The agent and utility structure is identical to the manager structure, except that we also have ResourceAccess projects. As an example, have a look at the structure of the Email utility:

Agent/Utility structure

the Email utility is located in the solution folder Utility\Email, and has the following projects:

Schepers.Utility.Email.ServiceInterface: contains service contracts, message contracts and data contracts of the Email utility
Schepers.Utility.Email.ServiceAdapter: service adapter of the Email utility
Schepers.Utility.Email.Business: business logic of the Email utility
Schepers.Utility.Email.ResourceAccess.Repository: repository of the Email utility
Schepers.Utility.Email.ResourceManager.NetMail: resource manager of the Email utility

BusinessEntity folder in detail

The project containing all business entities looks like:

Business entities

In more complicated environments you can use solution folders to divide the various business entities in categories.

Client folder in detail

The client folder contains all client projects:

Client projects

Other folders

If needed, you can add other solution folders, for example a Test folder that contains all unit tests for your projects.

Solution separation

Solutions are all put in a separate folder, and we define two types of Visual Studio solutions: entity and master solutions.

Entity solutions

The idea of an entity solution is that it should contain only those projects relevant for the solution, and relevant to one deployable entity (that may consist of a number of assemblies). So entity solutions never mix separate deployable projects, for example:

Solutions
\Schepers.Utility.Email.ResourceAccess-VS2008.sln (contains only resource access projects)
\Schepers.Manager.Stock.Business-VS-2008.sln (contains only business project)

Obviously, this approach has a number of advantages:

You see only what is relevant for the project
You only build the smallest relevant deployable entity
Various team can work on separate solutions without having to worry about conflicts

Master solutions

A master solution contains all projects that are involved in a business application, so it moves beyond the boundaries of the entity solution because it contains parts that are going to be deployed separately. A master solution is typically used for testing purposes, that is to say: to test the entire business solution. Example:

Solutions
\Schepers.Master-VS2008.sln (contains all projects for this customer)
\Schepers.Manager.Stock-VS-2008.sln (contains all projects related to the Stock manager)

Guidelines

Folder and file names

Inside visual studio, folder names are short: Utility, Agent, Client,… but project names contain the full namespace: Schepers.Manager.Stock.ServiceInterface, Schepers.Utility.Email.ResourceAccess.ResourceManager.netMail,…

Naming conventions

This one is easy: we use the naming conventions as defined at http://msdn.microsoft.com/en-us/library/xzf533w0(VS.71).aspx.

Contract namespaces

It’s important to have naming conventions for the contract namespaces and that we apply them in a consistent way.

Starting points

These are some starting points concerning naming guidelines:

a contract namespace should make clear to what domain data and message contracts belong to. It does not care about the solution structure (the .NET namespace) that is being used.
a contract namespace includes a version indication
a contract namespace is in lower case
a contract namespace does not care about it’s an enumeration or other specific type
a contract namespace does not contain the name of the property itself

Conventions

Convention for data contracts: http://schemas.schepers.com/servicetype.servicename/subspecification/yyyy/mm/dd

Convention for message contracts: http://schemas.schepers.com/servicetype.servicename/request-response-name/yyyy/mm/dd

where

servicetype is the type of service (agent, manager, utility, cross,…) without ‘service’ (mandatory)
servicename is the name of the service (storage, user,…) (mandatory)
subspecification is a sub-category when needed (render, view, abstract,…) (optional)
yyyy is the year in four digits (2009, 2010,…) (mandatory)
mm is the month in two digits (04, 11,…) (mandatory)
dd is the day in two digits (06, 24,…) (mandatory)
request-response-name is the name of the request or response it belongs too (addbookmarkrequest, addbookmarkresponse,…) (mandatory)

For versioning we choose a date indication yyyy/mm/dd instead of version number, because it’s a W3C standard and has more meaning.

Example

The contract namespaces for the EmailService are named as follows:

data contracts
- EmailAddress: http://schemas.schepers.com/utility.email/2009/07/02
- EmailAttachment: http://schemas.schepers.com/utility.email/2009/07/02
- EmailPriority: http://schemas.schepers.com/utility.email/2009/07/02
message contracts
- SendEmailRequest: http://schemas.schepers.com/utility.email/sendemailrequest/2009/07/02

Advantages and disadvantages

Although the amount of layers may seem overwhelming at first, evolving to a service oriented design has undoubtedly advantages for IT as well as business.

Advantages for IT

Loose coupling

Services are loosely coupled, meaning that they work entirely independent from each other; so changing one service does not affect another service in anyway. Because of the layered approach, this is also true for each other component in the architecture. Examples:

If a resource manager changes or is replaced, it has no impact on the existing assets and consumers won’t even notice.
A real implementation can easily be replaced by a mock implementation

Single-Responsibility

The Single-Responsibility principle means that a class should have only one responsibility, and has therefore only one reason to change. Examples:

The resource manager’s task is to implement resource access to a specific resource and using a specific technology (for example, using LINQ). It’s about data logic, no business or other logic.
A repository is an abstraction of the data functionality needed for a service. It contains only the abstraction for that particular service, and only uses the resource manager(s) needed for its scope.
An agent is fine-grained; it offers functionality within its limited scope only.

Interface Segregation Principle

According to the Interface Segregation Principle, many client specific interfaces are better than one general purpose interface, so we design our services in such a way that they expose tailored business functionality to clients and only what they really need. Because of this, services are more robust and better maintainable, due to fewer dependencies. Of course, a service should describe its capabilities and characteristics in a clear and stateless (no shared context) way without hidden assumptions. If this is done well, redundancy is low and by combining and recombining services project delivery will speed up – with lowered costs as a logical consequence. It promotes reuse on business and technological level: use what’s already there and extend what you already have. It also results in a very scalable solution: it is easy to scale out your services by deploying them into a load-balanced server farm, using software load balancers as well as hardware solutions.

Same mindset

If everyone has the same mindset, it’s easier to work together. Same approach, same methodology, same vision makes it possible to better understand what everyone is doing and how things work. There is a one-time investment of learning this – but because the entire team uses it, the inter-group collaboration becomes a lot better because we are already speaking the same architectural language.

Advantages for business

Think business, not technology

The design forces you to think in terms of business processes and service interactions, instead of monolithic applications. Therefore business has a clear view on what capabilities are available without having to worry about implementation details or technology choices. Example: business should not care how data is stored! Business changes can be implemented faster, because business handling is done in 1 place only by the development team in collaboration with business team. Moreover, business and IT speak the same business language – not technology!

Eliminate redundancy

Services can be leveraged cross multiple business projects – reducing redundancy. Reuse and (re)combining services allows faster project delivery and lower costs. Use what’s already there and extend what you already have (reuse on business level).

Disadvantages

The downside is that this flexibility comes at a price: the initial investment of setting up the design and basic services is higher, and there’s a lot of boilerplate code needed to achieve the layered structure (which can be auto generated for the most part). You also need a clear view on what you are trying to achieve; and last but not least: real sponsorship from the business to be able to succeed.

To be continued…

A reference architecture (Part 1)

Ludwig Stuyck — Tue, 12 Jan 2010 14:20:35 +0000

Introduction

IT and business needs have changed over the years, demanding system design to follow. In today’s tough economical conditions, there is more than ever the need to control costs and as such it is indispensable that an enterprise has to be able to respond very quickly to change with minimal effort. Traditionally projects start in the IT department, mostly without taking into account business requirements, but this just doesn’t work anymore. Instead, projects should be driven by business needs, and evidently the underlying IT solution has to support this.

I have built a systems architectural design template, adhering to proven SOA guidelines, to tackle this challenge. Of course, every environment is different – and so is every design – but the idea is to have a template that uses best practises and that is extensible to your own needs. The result is a multi-layered architecture based on resources like Juval Lowy’s master class, the Web Service Software Factory guidelines, feedback from other architects and experiences with developers using this architecture.

Architectural guidelines

To begin, the template below visually represents the multi-layered systems architecture I have developed:

Description of the layers

The client layer represents all components that consume the underlying managers. It’s more than just a presentation layer, because other than graphical user interface clients this layer also contains non-visible clients that can trigger managers (for example, an email or an incoming file on an FTP server). These clients can perform non-business related validation on user input, but they don’t contain other business or data access logic. A client can never talk directly with agents or utilities, it only talks to managers.

The manager layer contains the top-level coarse-grained systems, and uses the agents/utilities to delegate work:

Processes:
- Expose business processes
- Typically long running (workflow) and invoked using a one-way or notification (reservation) pattern
- Encapsulates rules particular to the business process
- Includes transaction control using compensation
- One process may act as a controller for another and invoke it
- Can be stateful
- Invoke underlying agents/utilities
Activities:
- Expose business activities that encapsulate calls to multiple agent and/or utilities to perform a single activity
- Each operation scoped as a logical unit of work
- Typically immediate request-response pattern
- Includes rules that are common to the organization

The agent and utility layer contains the low-level granular and fine-grained components. Agents provide business-centric functional context, while utilities are more related to infrastructure functionality like logging and emailing.

An agent:

Exposes business entity data
Typically immediate request-response pattern
Encapsulates data consistency rules and CRUD that are common to the entire organization
May invoke utilities
Each operation scoped as a logical unit of work

There are different types of agents, for example:

Proxy agent: referred to as wrapper, broker, or gateway, they act as a bridge between other members of the service-oriented system and incompatible subsystems
Device agent: a specialized type of proxy that stands in front of a hardware device.
Entity agent: exposes a single uncluttered concept that represents a business entity. They are independent from the business processes.

An utility :

Exposes shared functionality that is not specific to a business process or entity (not domain specific)
Typically immediate request-response
Does not invoke other agents

The business entities layer models the real-world, global domain-specific objects, like Customers and Orders.

The resource layer contains resources, which can be a database, external service or any other kind of resource.

Important to know is that managers are service-enabled, and that agents and utilities can be service enabled but don’t have to.

Communication flow

Communication between clients, managers, agents, resource access layer and resource layer is only allowed from top to bottom. These are the rules:

A client can consume the services from manager layer, but it cannot access the agent or resource access layer directly.
A component from the manager layer can consume the agent and utility layer, but it cannot access the resource access layer directly.
The enterprise business entities are used by manager, agent, utility and resource access layer, and so they are never exposed to the outside world.

The layers in detail

The manager layer has the same structure of the agent/utility layer, except that it does not have a resource access layer. So, the manager structure is designed according to the following structure:

Manager layer

And the agent and utility layer is designed according to the following structure:

Agent/Utility layer

Note that for the manager the service interface layer is mandatory: a manager is always exposed as a service to the clients. But for an agent or utility, the service interface layer is optional. This means that:

The service business layer of a manager can use the service interface layer of an agent
The service business layer of a manager can use the service business layer of an agent directly (and later, if the agent is service enabled, talk to the service interface layer instead)

Service interface layer

The service contract contains the interface for the service. It defines a logically and semantically related set of operations grouped on an interface and is about how a service behaves.

The data contract contains all data contracts that the service uses. A data contract is a formal agreement between a service and a client that abstractly describes the data to be exchanged. It precisely defines, for each parameter or return type, what data is serialized (turned into XML) to be exchanged. An important characteristic is that a data contract can be reused within the service. To communicate, the client and the service do not have to share the same types, only the same data contracts.

The message contract contains all message contracts needed by the service. A message contract is a wrapper around the data contracts and is mostly used when you need explicit control over the format of the SOAP (Simple Object Access Protocol) message, but in the architecture we always use them for the following reasons:

clarity and uniformity: use the same approach in all services
explicit implementation of the Request/Response pattern

An important characteristic is that a message contract is designed not to be reused.

The fault contract contains all fault contracts. A fault contract provides a way to describe faults in a contract and mark certain types of exceptions as appropriate for transmission to the client, shielding underlying system exceptions. As a rule we use fault contracts for errors that are not part of the normal program flow, for example:

void SendEmail(SendEmailRequest) throws fault exception when subject or other fields are not filled in
GetCustomersResponse GetCustomers() throws fault exception when underlying data source is unavailable

The service adapter contains the actual implementation of the service interface. It consists of the adapter, which invokes business actions after it uses entity translators to translate between message types or data types and types required by the business actions.

Service business layer

The business layer takes care of enterprise business entity validation and other custom business logic.

Resource access layer

The resource access layer contains the repositories and resource managers. Repositories are abstractions that interact with the resource managers and provide business interfaces to the domain model: so they are coarse-grained and closer to the domain. A repository can work with an underlying resource manager or it can act as a repository to mock data (a convenient way to do unit testing). Using dependency injection techniques, the correct repositories can be invoked at runtime by specifying them in a configuration file. A resource manager is an implementer towards a specific resource, so they are fine-grained and closer to the database. They typically implement the basic CRUD (create, read, update and delete) and other data operations, and use entity translators to do the mapping between data entities and enterprise business entities.

Rules:

An agent can use its repository (only one!) from the resource access layer, and can consume utilities.
A utility can only use its own repository (only one!) from the resource access layer.
A repository will mostly use only one resource manager, but in some cases it can use one or more resource managers as long as they belong to the same business context and business entities (to implement master-data relationships). Example: an OrderRepository can use a resource manager that gets partial order information from one database and another resource manager that gets another part of order information from an xml file, because the same business entity is being constructed out of it. An OrderRepository cannot use a resource manager to get for example customer information; because this does not belong to the OrderRepository’s core tasks (in this case a manager service has to be created to aggregate order and customer information).

Data flow

The following diagram illustrates the request data flow:

Data flow

Continued in part 2.