Sunday, January 29, 2012

Simple Circles–NHibernate Repository (Part 7a)

This post is part of a series on building a simple to use web-based contact and customer relationship management application. The goal is to support various audiences including businesses, teams, clubs, religious organizations, etc.
I’ve got a decent foundation in place with the domain model, persistence interface defining the repository pattern and a concrete implementation with a fake repository for testing purposes. The fake repository also serves to easily and quickly validate the design – if it is difficult to implement with simple in-memory structures then it’ll likely be even harder using an ORM. I have more experience with NHibernate and it’s a more sophisticated and mature ORM so I’ll start with it first.
To begin with, I’ve added two interfaces to the Persistence class library to define a database session and a factory pattern to manage creating sessions.
namespace Circles.Persistence
{
  using System;
  using System.Data;

  public interface IDbSession : IDisposable
  {
    void BeginTransaction(IsolationLevel isolationLevel);

    void Commit();

    void Rollback();

    IPartyRepository CreatePartyRepository();
  }
}
Bob Cravens provided inspiration for the session work with his Truck Management System. that eventually made it into his own GenericRepository project. This database session interface specifies that concrete implementations provide BeginTransaction, Commit, and Rollback methods as well as a concrete implementation for creating a PartyRepository.
The DbSessionFactory defines the factory pattern with a little bit of flexibility – you can create a DbSession with or without transactional support.
namespace Circles.Persistence
{
  public interface IDbSessionFactory
  {
    IDbSession Create(bool withTransaction);
  }
}
Simple Circles - Install NHibernateNext I created an NHibernateRepository class library project and added the NHibernate package via NuGet. While NuGet makes it simple to install packages and their dependencies, it doesn’t relieve you from managing versions. It is usually best to specify an explicit version when installing packages to ensure you don’t get conflicts and other surprises. In my case I used “-version 3.1.0.4000” which also installs the same version of Iesi.Collections.
The implementation of DbSessionFactory is pretty lightweight and trivial:
namespace Circles.NHibernateRepository
{
  using System.Data;
  using Circles.Persistence;

  public class DbSessionFactory : IDbSessionFactory
  {
    public IDbSession Create(bool withTransaction)
    {
      DbSession session = new DbSession(SessionProvider.SessionFactory);

      if (withTransaction)
      {
        session.BeginTransaction(IsolationLevel.ReadCommitted);
      }

      return session;
    }
  }
}

The SessionProvider class used in line #10 above will be discussed below. DbSession is also lightweight because it delegates the heavy lifting to the underlying NHibernate methods:
namespace Circles.NHibernateRepository
{
  using System;
  using System.Data;
  using Circles.Persistence;
  using NHibernate;

  public class DbSession : IDbSession
  {
    private readonly ISession session;
    private ITransaction transaction;

    public DbSession(ISessionFactory sessionFactory)
    {
      if (sessionFactory == null)
      {
        throw new ArgumentNullException("sessionFactory");
      }

      this.session = sessionFactory.OpenSession();
      this.session.FlushMode = FlushMode.Auto;
    }

    ~DbSession()
    {
      this.Dispose();
    }

    public void Dispose()
    {
      if (this.session == null)
      {
        return;
      }

      lock (this.session)
      {
        if (this.session.IsOpen)
        {
          this.session.Close();
        }
      }

      GC.SuppressFinalize(this);
    }

    public IPartyRepository CreatePartyRepository()
    {
      return new PartyRepository(this.session);
    }

    public void BeginTransaction(IsolationLevel isolationLevel)
    {
      this.transaction = this.session.BeginTransaction(isolationLevel);
    }

    public void Commit()
    {
      if (this.transaction == null)
      {
        return;
      }

      if (!this.transaction.IsActive)
      {
        throw new InvalidOperationException("No active transation");
      }

      this.transaction.Commit();
    }

    public void Rollback()
    {
      if (this.transaction == null)
      {
        return;
      }

      if (this.transaction.IsActive)
      {
        this.transaction.Rollback();
      }
    }
  }
}

NHibernate is highly configurable so instantiating the libraries requires processing configuration settings contained in hibernate.cfg.xml as well as reflecting over your assemblies. Doing so is expensive – its best to cache the initialized configuration and session for the lifetime of the application. The SessionProvider class does this:
namespace Circles.NHibernateRepository
{
  using NHibernate;
  using NHibernate.Cfg;

  public class SessionProvider
  {
    private static Configuration configuration;

    private static ISessionFactory sessionFactory;

    private SessionProvider()
    {
    }

    public static Configuration Configuration
    {
      get
      {
        if (configuration == null)
        {
          configuration = new Configuration();
          configuration.Configure();
          configuration.AddAssembly(typeof(PartyRepository).Assembly);
        }

        return configuration;
      }
    }

    public static ISessionFactory SessionFactory
    {
      get { return sessionFactory 
              ?? (sessionFactory = Configuration.BuildSessionFactory()); }
    }

    public static ISession GetSession()
    {
      return SessionFactory.OpenSession();
    }
  }
}

That’s a lot of implementation and setup plumbing! The source code for this article can be downloaded from here. The next installment will map the domain model to the relational database model.

Sunday, January 22, 2012

Simple Circles–Enabling jQuery UI (Part 6)

This post is part of a series on building a simple to use web-based contact and customer relationship management application. The goal is to support various audiences including businesses, teams, clubs, religious organizations, etc.
I think of the default blue MVC 3 UI as something of a developer’s test version – not really what you’ll go to production with but sufficient to work with while developing. It’s possible to use the ASP.NET MVC themes from their gallery but I think jQuery and its companion jQuery UI provide a much richer and cross-browser solution with far less effort.

Themes

Steve Hobbs wrote a great step-by-step post on enabling jQuery UI last June. Like him, I used the Redmond theme to start with so it more closely resembled the default.
Simple Circles - Enable jQuery UISimple Circles - jQuery UI themeAfter downloading the Redmond theme, copy the css\redmond folder to the Content\themes folder under the Circles website. Remember to choose “Include in Project” from the Solution Explorer (see image to the left). As Steve Hobbs indicates, jQuery UI support is already included in the ASP.NET MVC 3 templates – it just needs to be enabled by adding two lines to the _Layout.cshtml in the Shared folder as shown on the right. To start taking advantage of the jQuery UI theme, simply add the appropriate styles to HTML elements. Here I’ve commented out the standard Submit button on the Create.cshtml page and replaced it with one decorated with jQuery UI CSS classes:
<!--<input type="submit" value="Create" />-->
<input type="submit" value="Create" 
       class="ui-button ui-widget ui-state-default ui-corner-all" 
       role="button" aria-disabled="false">

Simple Circles - jQuery buttonThis screen shot shows the before and after using the Redmond theme just set up. These CSS classes are designed such that switching themes is as easy as deploying a different theme to the Content\themes folder and changing the single <link> line in the _Layout.cshtml page. The “eye candy” is nice – it looks fresher and more modern…well, months ahead of the default hard images the browser displays!

Next I’m going to add some feedback for the user when an action completes. The default behavior when adding, updating or deleting an entity is to perform the action then return the user to the Index page. Breaking this down, it means the controller performs the action then uses RedirectToAction to redirect the browser to the default HTTP GET action. Doing so ensures that the user can’t accidently use refresh to repeat the same action, e.g. adding the same entity twice or, classically, buying the same thing again.

Because redirect is used the current HTTP request ends and another one initiates. This means the feedback message has to be passed across HTTP requests so the usual suspect – ViewData – won’t work. The MVC engineers planned for this with another dictionary object that’s briefly stored in the user’s session – TempData. The MSDN article Passing Data in an ASP.NET MVC Application provides the necessary details. Here I tuck the confirmation message into TempData (line #4) before issuing the redirect:
  ...
  this.repository.Add(entity);

  TempData["message"] = string.Format("{0} was added", entity.PartyName);

  return RedirectToAction("Index");
}

Back in the Index.cshtml the message just passed to it is retrieved and rendered with jQuery UI classes decorating the output:
<h2>People</h2>

@if (TempData["message"] != null) {
  <div style="margin-top: 20px; padding: 0 .7em;" class="ui-state-highlight ui-corner-all"> 
    <p><span style="float: left; margin-right: .3em;" class="ui-icon ui-icon-info"></span>
      @TempData["message"]
    </p>
  </div>
}

Simple Circles - ConfirmationThe result is shown to the right. Another simple feature to take advantage of jQuery’s client-side power is to enable “unobtrusive client-side validation”. There’s plenty of examples already, including the ASP.NET Teams’s own tutorial. Two web.config settings and two more <link> elements to include necessary JavaScript files in _Layout.cshtml and field/form validation moves from server-side down to client-side to provide feedback without having to HTTP POST the form to the server then getting the validation messages sent back to the client browser.

Menu Tabs and Lists

Simple Circles - Tabbed MenuOnce again I’m turning to the ASP.NET team’s tutorials to improve the user experience even more. Their Iteration #2 – Make the application look nice article contains two enhancements; one improves the menu tabs by rounding the corners and providing highlighting to indicate the selected tab the user is on and the other replaces the textual hyperlinks on each row with graphics for edit and delete. Simple Circles - Nicer ListsAgain, rather than duplicating details here, please refer to the article for more information. The result of these efforts is shown on the right.

The source code for this article can be downloaded from here. The next several installments will flesh out concrete implementations of the repository using Entity Framework and NHibernate.

Thursday, January 19, 2012

Simple Circles–MVC Controller Unit Tests (Part 5)

This post is part of a series on building a simple to use web-based contact and customer relationship management application. The goal is to support various audiences including businesses, teams, clubs, religious organizations, etc.

Simple Circles - ControllerTestsIn the last post I left off with the PeopleController refactored to use an IPartyRepository via dependency injection. Now I’ll create unit tests for the controller so that we’ll know if something breaks as the solution evolves. Since I’m planning on several views and controllers, I added a ControllerTests folder to the UnitTests project to organize and group them together. With xUnit, as with many unit testing frameworks, simply add a new class called PeopleControllerTest and begin writing the tests.

Unit testing MVC controllers generally falls into two categories:
  1. Ensuring that an action result being returned from a controller’s action is correct. On HTTP GET requests, this means the correct view result is returned.
  2. Ensuring that HTTP POSTs are behaving properly:
    1. A POST with purposely invalid model data causes it to route the request back to the originating view.
    2. A POST with correct model data causes it to route back to the Index view.
Because of the dependency injection work just done, setting up the unit test is straightforward:
[Fact]
public void DefaultGetReturnsIndexView()
{
// arrange
const string ExpectedViewName = "Index";
var peopleController =
new PeopleController(new FakeRepository.FakePartyRepository());

// act
var viewResult = peopleController.Index();

// assert
Assert.NotNull(viewResult);
Assert.Equal(ExpectedViewName, viewResult.ViewName);
var model = viewResult.ViewData.Model as IEnumerable;
Assert.NotNull(model);
}

Notice on Line #6 above that it’s easy to pass a new instance of the FakeRepository from the test method. The assertions section checks that a view result was returned, that it was the expected named view result and that the view’s model is present.


Testing the HTTP POST actions is a bit more involved. The basic test is the same however since the testing class is calling the controller directly a little more work is needed. Model validation is a part of the MVC runtime which is not present during testing so it is necessary to “prime the pump” so to speak by placing the error into the controller’s ModelState to see if it’s being handled correctly – this is essentially the same behavior the MVC runtime exhibits:

[Fact]
public void CreatePostReturnsViewIfModelStateIsInvalid()
{
// arrange
const string ExpectedViewName = "Create";
var peopleController
= new PeopleController(new FakeRepository.FakePartyRepository());
peopleController.ModelState.AddModelError("LastName", "LastName is required.");
var person = new Person
{
FirstName = "Henry",
MiddleName = "Lewis",
//LastName = "Stimson ",
Gender = Enum.GetName(typeof(GenderEnum), GenderEnum.Male),
Birthday = new DateTime(1867, 9, 21)
};

// act
var viewResult = peopleController.Create(person) as ViewResult;

// assert
Assert.NotNull(viewResult);
Assert.Equal(ExpectedViewName, viewResult.ViewName);
}

Line #8 above is where the error is set up. Lines #9 through #16 create a Person instance to pass to the controller method to mimic what the MVC runtime will do. Notice that I commented out the line for setting the LastName property for authenticity purposes. Personally, I would hate to come across some else’s code that sets up an error yet passes in perfectly valid data. Finally, the assert statements check that the same Create view is returned indicating that the error(s) were detected and handled properly.

Testing for a valid model is nearly the same – just don’t set the ModelState, pass a valid Person instance and check that we’re returned to the Index page. Edit, update and delete actions are nearly identical as well.


The final bit of code worthy of mention is around the use of AutoMapper – remember that the last post introduced AutoMapper as an implementation of the DataMapper pattern. I wired up the mapping initialization inside Global.asax.cs then. Of course the test harness doesn’t have a website since it’s job is exercising the logic and behavior of the controller classes. Therefore I have to use the xUnit way of introducing a “fixture” necessary for the test class to operate.

public class PeopleControllerTest : IUseFixture<DataMapperFixture>
{
public void SetFixture(DataMapperFixture data)
{
data.CreateMaps();
}
...
}
...
public class DataMapperFixture : IDisposable
{
public void CreateMaps()
{
Mapper.AssertConfigurationIsValid();
PersonMap.CreateMaps();
}
}

The test class implements the xUnit IUseFixture<T> interface which tells the xUnit runtime that it needs to call SetFixture with an instance of that type – in my case I created a trivial DataMapperFixture class that simply verifies the mapping is valid and calls the PersonMap.CreateMaps() method to initialize AutoMapper.


The source code for this article can be downloaded from here. The next installment will explore some simple jQuery enhancements to make the UI a little nicer and more informative.

Sunday, January 15, 2012

Simple Circles–Add an ASP.NET MVC 3 UI (Part 4b)

This post is part of a series on building a simple to use web-based contact and customer relationship management application. The goal is to support various audiences including businesses, teams, clubs, religious organizations, etc.
Simple Circles - Ninject packageIn the last post I left off with a scaffolded People MVC implementation that was hard-wired to use the Entity Framework 4 data access technology. In this post I’m going to replace that with the Ninject dependency-injection framework and use the previously built FakePartyRepository implementation to begin testing the UI quickly.
With NuGet, adding Ninject support is easy – just two simple commands: ‘Install-Package Ninject -Version 2.2.1.4’ and ‘Install-Package Ninject.MVC3 -Version 2.2.2.0’. I chose to include specific versions since they were specified on the corresponding NuGet Gallery pages. Once again there is a lot going on behind the scene as shown to the right.
Simple Circles - Ninject.MVC3The Ninject.MVC3 extension was created to add support to MVC 3 applications including DI for Controllers, filters, validators and the Unit of Work pattern for NHibernate (more on this later!). The NuGet version adds a class to the \App_Start folder called NinjectMVC3 wired and ready to go. It does so by hooking in with the WebActivator project – one of the dependencies automatically installed when the Ninject.MVC3 package was installed.

Controller

First I’ll add references to the Domain and Persistence projects to bring in their type definitions then I’ll replace the EF context reference in PeopleController with the IPartyRepository instead. Refer to the last screenshot in the previous post to see the boilerplate code generated by the scaffolding.
public class PeopleController : Controller
{
  private readonly IPartyRepository repository;

  public PeopleController(IPartyRepository repository)
  {
    this.repository = repository;
  }

  public ViewResult Index()
  {
    IEnumerable<Domain.Person> persons = this.repository.FindAllPersons();
    return View(persons);
  }
  ...

The problem with the above code is that it will not compile because of line 13 – ‘return View(persons)’. The MVC convention is to use separate model classes in the presentation layer to decouple it from the business/domain layer. I did exactly this when creating a Person class in the \Models folder - essentially flattening the EntityBase->Entity->Party->Person inheritance hierarchy to just Person. The scaffolding constructed the views (Index, Details, Edit, etc.) to work with the Models.Person class – not the Domain.Person. Line 12 is returning an enumeration of Domain.Person instances whereas the view expects Models.Person instances.

Data Mapper


The solution to this mismatch lies in another tool called AutoMapper which makes using the Data Mapper pattern a cinch. Jeremy Miller’s MSDN article Persistence Patterns gives a good overview of how these various proven patterns fit and work together. Also, Jimmy Bogard wrote a series of articles on his tool at Los Techies. Back to the NuGet Package Manager console to ‘Install-Package AutoMapper’.

I created a \Maps folder and added a new class called PersonMap to define the mapping back and forth between the two models…
internal class PersonMap
{
  internal static void CreateMaps()
  {
    Mapper.CreateMap<Domain.Person, Models.Person>()
        .ForMember(dest => dest.Birthday, opt => opt.MapFrom(src => src.Birthday))
        .ForMember(dest => dest.FirstName, opt => opt.MapFrom(src => src.FirstName))
      ...
        .ForMember(dest => dest.PersonId, opt => opt.MapFrom(src => src.PartyId))
        .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.PartyName))
        .ForMember(dest => dest.Salutation, opt => opt.MapFrom(src => src.Salutation ?? null))
        .ForMember(dest => dest.Suffix, opt => opt.MapFrom(src => src.Suffix ?? null));

    Mapper.CreateMap<Models.Person, Domain.Person>()
        .ForMember(dest => dest.ChannelAddresses, opt => opt.Ignore())
        .ForMember(dest => dest.Birthday, opt => opt.MapFrom(src => src.Birthday))
        .ForMember(dest => dest.FirstName, opt => opt.MapFrom(src => src.FirstName))
      ...
        .ForMember(dest => dest.PartyId, opt => opt.MapFrom(src => src.PersonId))
        .ForMember(dest => dest.PartyName, opt => opt.Ignore())
        .ForMember(dest => dest.PartyType, opt => opt.Ignore())
        .ForMember(dest => dest.PostalAddresses, opt => opt.Ignore())
        .ForMember(dest => dest.Salutation, opt => opt.MapFrom(src => src.Salutation ?? null))
        .ForMember(dest => dest.Suffix, opt => opt.MapFrom(src => src.Suffix ?? null));
  }
}
A few things are worth pointing out in the above listing:

  1. Line #9 shows how I map the generic, internal PartyId from the domain model to the more friendly and meaningful PersonId in the MVC layer.
  2. Line #10 does the same for the PartyName - mapping it to a FullName property.
  3. Line #15 tells the mapper to ignore the ChannelAddress property in the domain model – it will not be mapped to the MVC layer. The same goes for PostalAddresses  –  these will be dealt with later and in a manner appropriate for the user interface.
  4. Lines #11, #12, #23, #24 show how optional fields are handled.

A call to PersonMap.CreateMaps() in Global.asax.cs will initialize the maps when the website starts up. To use the maps, add a line to invoke the data mapping like this:
[HttpPost]
public ActionResult Create(Person person)
{
  if (!ModelState.IsValid)
  {
    return View(person);
  }

  var entity = Mapper.Map<Person, Domain.Person>(person);

  this.repository.Add(entity);

  return RedirectToAction("Index");
}

Line #9 is the magic – transferring the contents of the MVC Models.Person to the Domain.Person before passing to the repository to store.

Dependency Injection


The PeopleController at the top of this article used constructor injection on Line #5 to receive an IPartyRepository instance. Following the Ninject samples and documentation, I’ve added a \Services\ServicesModule which inherits from NinjectModule to handle the injection of services:
/// <summary>
/// A Ninject module to bind services.
/// </summary>
public class ServicesModule : NinjectModule
{
  /// <summary>
  /// Called when the module loads into the kernel.
  /// </summary>
  public override void Load()
  {
    this.Bind<IPartyRepository>()
        .To<FakePartyRepository>()
        .InRequestScope();
  }
}

To wire up the module, add a line to the RegisterServices method found in NinjectMVC3:
private static void RegisterServices(IKernel kernel)
{
  kernel.Load<Services.ServicesModule>();
}

The end result of this effort is that I can now browse and display the list of persons as shown here:

Simple Circles - MVC with Fake Repo

Next time I’ll set up a unit test to exercise the functionality of the controller through injection so that I won’t have to always manually hit every view/page to see if it still works as changes are made.

The source code for this article can be downloaded from here.

Wednesday, January 11, 2012

Simple Circles–Add an ASP.NET MVC 3 UI (Part 4a)

This post is part of a series on building a simple to use web-based contact and customer relationship management application. The goal is to support various audiences including businesses, teams, clubs, religious organizations, etc.
Last time I left off with a working fake implementation of the IPartyRepository called FakePartyRepository. We know that it is “working” because of the unit tests project that exercised the various methods of the contract. Since I have a working repository I’m going to start building out an ASP.NET MVC 3 website that will use the repository. My experience is that doing so earlier in the development cycle rather than later will flush out any problems or misaligned requirements. Remember, to this point I’ve been operating in something of a vacuum – building interfaces and implementations according to a vague vision of consuming them. Now I will make that vision concrete by constructing a user interface to work with.

Setup

Using the New Project wizard, I added an ASP.NET MVC 3 website and chose “Internet Application” for the template with Razor as the view engine. I did not elect to create unit tests as I’m using xUnit and the template support is not worth setting up according to this discussion post. At this point pressing <F5> will bring up the default empty website.
Simple Circles - MVC ScaffoldingI’m a big fan of Steve Sanderson’s Pro ASP.NET MVC Framework books as well as his work on the MVC Scaffolding project which I started using last January as soon as he began publishing it. Therefore, I’m going to draw on his work to move things along quickly. First, I installed the scaffolding project using ‘install-package mvcscaffolding’ which in turn brought in several dependencies as shown on the right.
I’ll also start off simple by using SQL Server Compact 4.0 along with the new ASP.NET Universal Providers 1.01. You can follow Scott Hanselman’s or Scott Guthrie’s posts on setting it up.

Person

MVC Scaffolding works off a model so first I added a Person class to the Models folder…
namespace Circles.Models
{
  using System;
  using System.ComponentModel.DataAnnotations;

  /// <summary>
  /// Represents a view model of a Person
  /// </summary>
  public class Person
  {
    /// <summary>
    /// Default constructor
    /// </summary>
    /// <remarks>Ensure Gender has a default value.</remarks>
    public Person()
    {
      this.Gender = "Unknown";
    }

    [Display(Name = "Person Id")]
    [Key]
    public Guid PersonId { get; set; }

    [Display(Name = "Full name")]
    public string FullName { get; set; }

    // [Required]
    [Display(Name = "Salutation")]
    [StringLength(20)]
    public string Salutation { get; set; }

    [Required]
    [Display(Name = "First name")]
    [StringLength(50, MinimumLength = 3)]
    public string FirstName { get; set; }
  ...

Simple Circles - Scaffold PersonNow with a single NuGet instruction I scaffold a full CRUD interface for the model class using ‘scaffold controller PeopleController -ModelType Circles.Models.Person’ as shown to the right. This one command generated an MVC controller class complete with all behaviors as well as a set of six Razor pages (Index to list, Details, Edit, Create, Delete, and a shared _CreateorEdit) to support CRUD behavior for a Person instance. As the second image shows, quite a bit of code was generated.Simple Circles - Scaffolded Code

I can’t say enough about how exceedingly cool Steve’s scaffolding work is and how much effort it saves. Unfortunately, the current implementation is built to support Entity Framework as the underlying data technology. Notice the CirclesContext class added to the Models folder and the reference to that context embedded in the PeopleController class. While the hooks are there to plug in other scaffolding templates (e.g. NHibernate) as of yet nobody has stepped forward to provide implementations.

You could also, as Steve suggests, add the Entity Framework 4.1 Code First capability via ‘install-package EFCodeFirst.SqlServerCompact’ then regenerate the controller with the additional flags ‘-Repository –Force’. You’d then have a working repository-based implementation built with all Microsoft products.

In the second part of this installment I’ll take a different approach and wire in Ninject as the dependency injection framework then use it to inject the FakePartyRepository previously built.

The source code for this article can be downloaded from here.

Monday, January 9, 2012

Simple Circles–Fake Repository (Part 3)

This post is part of a series on building a simple to use web-based contact and customer relationship management application. The goal is to support various audiences including businesses, teams, clubs, religious organizations, etc. With a basic structure for the domain objects taking shape it’s time to move on to the notion of persistence.

In the last post I set up the interfaces to support the Repository pattern and left off with the following signature:

namespace Circles.Persistence
{
using System;
using System.Linq;

public interface IPartyRepository : IRepository<Party, Guid>, ISupportSave<Party, Guid>, ISupportDelete<Party, Guid>
{
IQueryable<Household> FindAllHouseholds();
IQueryable<Organization> FindAllOrganizations();
IQueryable<Person> FindAllPersons();
}

Now I’m going to put together a simple fake repository implementation to exercise the interfaces as well as quickly provide sample data to work with. I’ve added a new project called FakeRepository containing a single class called FakePartyRepository partly shown here:

namespace Circles.FakeRepository
{
using System;
using System.Collections.Generic;
using System.Linq;

public class FakePartyRepository : IPartyRepository
{
private readonly List<Household> fakeHouseholdList = new List<Household>
{
new Household { PartyName = "Churchill", FormalGreeting = "Sir Winston and Lady Clementine" },
new Household { PartyName = "Roosevelt", FormalGreeting = "President Franklin and Mrs. Eleanor" },
};

private readonly List<Organization> fakeOrganizationList = new List<Organization>
{
new Organization { PartyName = "Great Lakes Food Market" },
new Organization { PartyName = "Hungry Coyote Import Store" },
new Organization { PartyName = "Lazy K Kountry Store" },
};

private readonly List<Person> fakePersonList = new List<Person>
{
new Person { FirstName = "Nancy", LastName = "Davolio", Gender = GenderEnum.Female, Birthday = new DateTime(1948, 12, 8) },
new Person { FirstName = "Andrew", LastName = "Fuller", Gender = GenderEnum.Male, Birthday = new DateTime(1992, 8, 14) },
};

private readonly IQueryable<Household> fakeHouseholdRepository;
private readonly IQueryable<Organization> fakeOrganizationRepository;
private readonly IQueryable<Person> fakePersonRepository;
private readonly IQueryable<Party> fakePartyRepository;

public FakePartyRepository()
{
this.fakeHouseholdRepository = this.fakeHouseholdList.AsQueryable();
this.fakeOrganizationRepository = this.fakeOrganizationList.AsQueryable();
this.fakePersonRepository = this.fakePersonList.AsQueryable();
this.fakePartyRepository = this.fakeOrganizationList.Union(this.fakePersonList).Union(this.fakeHouseholdList).AsQueryable();
}

public IQueryable<Party> FindAll()
{
return this.fakePartyRepository;
}

public Party FindById(Guid id)
{
return this.fakePartyRepository.FirstOrDefault(x => x.PartyId == id);
}
}

As you can see, the underlying data is contained in simple in-memory generic Lists that are wrapped into LINQ IQueryable objects. Note the last line of the constructor where the fakePartyRepository is a .Union of the three underlying lists.


Simple Circles - xunitTo test the FakeRepository let’s add another class library project called UnitTests. We’ll use NuGet to add the xUnit package with the command ‘install-package xunit’ as shown to the right. xUnit was created by James Newkirk (creator of the venerable NUnit) and Brad Wilson to better reflect the purpose of driving and iterating the design of an implementation at the unit level. Brad discusses this philosophy in his article Its not TDD, It’s Design by Example. After adding the xUnit reference, add a class called PartyRepositoryTest:

  public class PartyRepositoryTest
{
[Fact]
public void CanAddHousehold()
{
// arrange
IPartyRepository repository = new FakePartyRepository();

// act
var id = repository.Add(new Household
{
PartyName = "Eisenhower",
FormalGreeting = "President Dwight D. and Mrs. Mamie",
InformalGreeting = "Ike and Mamie"
});

// assert
Assert.NotNull(id);
Assert.NotNull(repository.FindById(id));
}
}

The first thing you may notice is that xUnit uses the attribute [Fact] rather than [Test] as other TDD frameworks do. As Brad puts it “a [Fact] is an expression of some condition which is invariant”. Essentially we’re saying that the condition “CanAddHousehold” is an invariant condition of the PartyRepository which must always be true. In addition to expressing facts, xUnit lets you express theories which are “an expression of a condition which is only necessarily true for the given set of data.”:

  [Theory,
InlineData("D28AA45E-C650-4121-8070-3D12BE31F91A")]
public void CanFindSinglePerson(string id)
{
// arrange
IPartyRepository repository = new FakePartyRepository();
var partyId = new Guid(id);

// act
var person = repository.FindById(partyId) as Person;

// assert
Assert.NotNull(person);
Assert.True(person.Id == partyId);
}

Simple Circles - Unit TestsSince we built the FakeRepository with our known data, we can construct tests with known values to prove the repository is working as designed without defects. In the above example, we know the PartyId of one of the person instances that we put into the fake repository so we can attempt to retrieve that person to exercise that logic. ReSharper’s test runner shows all the tests we currently have. Before the tests can be compiled and run, you must add a reference to the Extensions subproject of xUnit which holds the [Theory] attribute definition and behavior. Once again, use the NuGet Package Manager Console to execute the command “install-package xunit.extensions”.


Finally, you’ll notice in the above samples as well as the source code accompanying this post that I’ve followed the “3A” or “Arrange-Act-Assert” principle for writing the tests.


The source code for this article can be downloaded from here.


Next we’ll look at starting an ASP.NET MVC 3 website to consume and present the domain model.

Wednesday, January 4, 2012

Simple Circles–Persistence (Part 2)

This post is part of a series on building a simple to use web-based contact and customer relationship management application. The goal is to support various audiences including businesses, teams, clubs, religious organizations, etc. With a basic structure for the domain objects taking shape it’s time to move on to the notion of persistence.
One of the tenets of DDD is known as “aggregate root” – a top-level, course grained collection of responsibilities. In plain object-oriented systems, objects tend to expose granular methods to operate on their data. Unfortunately, this approach allows business knowledge and intimate design details to creep outside of the model. That is, accomplishing a business operation usually entails making several method calls across several objects – this sequencing of calls becomes embedded externally in calling applications making the whole thing tightly coupled and brittle. The aggregate root principle groups related objects closely and provides consistent and coordinated access to these related objects.Vaughn Vernon wrote an in depth three-part article on the topic of Effective Aggregate Design.
In this model the Party is an obvious root object – we don’t access addresses or notes without first going through the Party instance they belong to. This approach leads to methods like Party.AddAddress() or Party.AddNote() rather than creating addresses and notes separately.
Once the aggregate root(s) have been identified it’s time to move on to persisting the data they contain. The Repository pattern is a proven way to implement persistence in a storage-neutral manner. There are many references to consult for more information but in the context of DDD, Jak Charlton’s post, DDD: The Repository Pattern, is particularly concise and a good starting point for why it is useful. Gabriel Schenker provides another good write up with code examples on the NHibernate FAQ. Given that we have a Party aggregate root, we should also have a PartyRepository since each aggregate should be responsible for its own “domain” or “scope” if you will.
Since repositories manage aggregate roots and their associated entities/ values, the basic semantics for the repository follow that of a generic collection. For us this means something like:
namespace Circles.Persistence
{
  using System;
  using System.Collections.Generic;

  public interface IPartyRepository
  {
    IList<Party> FindAllParties();
    Party FindPartyById(Guid Id);
    Guid Add(Party party);
    void Delete(Guid Id);
    void Update(Party party);
  }
}

Some might balk at the Delete and Update methods, arguing that pure collections have “Remove” instead. However, I am of the opinion that we’re working with domain (a.k.a. business) entities that are persisted somewhere so the semantics of persisting data are more natural with delete and update.

Of course the above approach is very "party-specific” so it could be refactored using generics like this:
namespace Circles.Persistence
{
  using System;
  using System.Collections.Generic;

  public interface IRepository<T> where T : Entity
  {
    IList<T> FindAll();
    T FindById(Guid Id);
    Guid Add(T entity);
    void Delete(Guid Id);
    void Update(T entity);
  }
}

Now we’ve got an interface that supports any type of domain entity – note the removal of the term “Party” from the method names.

The above refactored interface implies that every repository created supports all four “CRUD” operations.  A better approach would be to split out the operations and then have a specific repository implement the ones it needs like this:
namespace Circles.Persistence
{
  using System;
  using System.Linq;

  public interface IRepository<T, in TId> where T : Entity
  {
    T this[TId id] { get; set; }
    IQueryable<T> FindAll();
    T FindById(TId Id);
  }

  public interface ISupportSave<in T, out TId> where T : Entity
  {
    TId Add(T entity);
    void Update(T entity);
  }

  public interface ISupportDelete<T, in TId> where T : Entity
  {
    void Delete(TId Id);
  }

  public interface IPartyRepository : IRepository<Party, Guid>, ISupportSave<Party, Guid>, ISupportDelete<Party, Guid>
  {
    IQueryable<Household> FindAllHouseholds();
    IQueryable<Organization> FindAllOrganizations();
    IQueryable<Person> FindAllPersons();
  }

Now we’re explicit about what the PartyRepository does. By implementing IRepository, ISupportSave and ISupportDelete we’re clear that the IPartyRepository supports full CRUD behavior using Guids for the Id types. Additionally, we provide FindAllxxx methods for retrieving specific types from the repository. Notice that having the repository return IQueryable gives flexibility on both sides – concrete implementations can translate the LINQ query passing it to the underlying data store for execution and callers can query the repository in various ways rather than being forced to go through a rigid, narrowly defined API we provide.

One more thing to cover – I slipped in a new Type called Entity that is a base class for all domain entities. Rather than rehashing all the details here I’d suggest checking out Jason Dentler’s blog or his book NHibernate 3.0 Cookbook. Equally important is Billy McCafferty’s work on Sharp Architecture. Standing on the shoulder’s of giants…

The source code for this article can be downloaded from here.

Next we’ll look at testing what we have xUnit.

Tuesday, January 3, 2012

Simple Circles–Domain Model (Part 1)

This post is part of a series on building a simple to use web-based contact and customer relationship management application. The goal is to support various audiences including businesses, teams, clubs, religious organizations, etc. Thus, it is important that the domain model be flexible enough to allow various combinations of entities to be used to support these use cases. For example, in a B2B scenario the notion of a person or a household will not likely be center stage whereas businesses will be. However, a club or sports team will likely interact with individuals and possibly households but not likely with businesses.

Models

Simple Circles - Party ConceptModeling entities such as Person, Household, and Organization come to mind immediately. However, the “Party” model has existed for many years as a way to generically model the relationships between various parties. The figure to the right illustrates graphically this concept. Person, Household, and Organization are all types of parties. This approach also allows reuse of relationships such as notes, postal addresses, and communication channels across all types of parties. Rather that duplicating logic, storage mechanisms and business rules for each entity this approach follows the Don’t Repeat Yourself (DRY) principle.

Simple Circles - Party Class DiagramTransferring the conceptual model to a physical one is accomplished using inheritance as shown in the class diagram to the right. The Party class is an abstract base class containing a PartyId unique identifier and a PartyName. Person, Household, and Organization all inherit these base properties supplementing them with specific properties they contain. Notice that the base class contains relationships to Party Note, Postal Address and Channel Address as well as to Party Type. Through inheritance all child subtypes also inherit these relationships without having to explicitly code them three different times (DRY!). Using a separate Party Type allows classifying individual party instances which supports filtering the parties in lists, views, etc.

Classes

Here is the code for the Party class which realizes the class diagram shown above:
namespace Circles.DomainModel
{
  using System;
  using System.Collections.Generic;

  /// <summary>
  /// An abstract class representing any 'Party' that can be interacted with.
  /// </summary>
  public abstract class Party
  {
    private ISet<ChannelAddress> channelAddresses = new HashSet<ChannelAddress>();
    private ISet<PartyNote> notes = new HashSet<PartyNote>();
    private ISet<PostalAddress> postalAddresses = new HashSet<PostalAddress>();

    /// <summary>
    /// Gets or sets the unique identifier of the Party instance.
    /// </summary>
    public Guid PartyId { get; set; }

    /// <summary>
    /// Gets or sets the name of the Party instance.
    /// </summary>
    public virtual string PartyName { get; set; }

    /// <summary>
    /// Gets or sets the PartyType of the Party instance.
    /// </summary>
    public virtual PartyType PartyType { get; set; }

    /// <summary>
    /// Gets or sets the Notes associated with the Party instance.
    /// </summary>
    public ISet<ChannelAddress> ChannelAddresses
    {
      get { return this.channelAddresses; }
      set { this.channelAddresses = value; }
    }

    /// <summary>
    /// Gets or sets the Notes associated with the Party instance.
    /// </summary>
    public ISet<PartyNote> Notes
    {
      get { return this.notes; }
      set { this.notes = value; }
    }

    /// <summary>
    /// Gets or sets the Notes associated with the Party instance.
    /// </summary>
    public ISet<PostalAddress> PostalAddresses
    {
      get { return this.postalAddresses; }
      set { this.postalAddresses = value; }
    }
  }
}

Note that this is not the “finished product” but rather an early version along the way. Future articles will refine this further.

The source code for this article can be downloaded from here.

Next we’ll look at persistence of this model.

Sunday, January 1, 2012

Simple Circles–Introduction

This series will be a step-by-step approach on building a simple to use web-based contact and customer relationship management application. The goals are to employ current best practices including domain-driven design (DDD), object-relational mapping (ORM), unit testing – a component of Test-Driven Development (TDD), and the model-view-controller paradigm of ASP.NET MVC3. Additionally, as the name suggests – the finished product must be simple to use. While patterns, practices and techniques employed to build the application might be advanced the end user mustn't be overwhelmed. Keeping track of a circle of friends, acquaintances and associates should be simple!
There are numerous examples of using these practices and technologies around the Internet. However many are overly simplified – designed to show a particular technique – rather than a complete “real world” example. Technical books tend to stick to the Microsoft mantra of always using their latest offering or their shiny new version of some proven OSS product. For example, Steve Sanderson’s Sports Store in Pro ASP.NET MVC 3 Framework and Tim McCarthy’s SmartCA in .NET Domain-Drive Design with C# both deliver complete examples yet neither tackle NHibernate. That is, true persistence ignorance beyond the theory that its possible. Don’t misunderstand, I’m not saying they’re bad books – I’ve bought both, used them to learn, and do refer back to them. However, if I see another contrived example of using Entity Framework with a few wizards to whip out a solution I’ll scream. Smile
This application will be built with NET 4.0 using the following tools and technologies:
  1. Visual Studio 2010 with NuGet package support
  2. ASP.NET MVC 3 and Razor view engine
  3. Persistence layer will be:
    1. NHibernate 3.1 with SQLite
    2. Entity Framework 4.1 with SQL Server CE 4.0
  4. Ninject 2.2 for dependency injection
  5. xUnit for unit testing
  6. jQuery UI for user experience.
Here are links to the posts for this project:
  1. Domain Model
  2. Persistence
  3. Fake Repository
  4. ASP.NET MVC 3 UI
    1. Scaffold People CRUD
    2. Replace EF hard wiring with Repository pattern
  5. MVC Controller Unit Tests
  6. Enabling jQuery UI
  7. NHibernate Repository
    1. IDbSession and implementation
    2. Fluent NHibernate mapping
    3. NHibernate Unit Testing
As this series is developed, I’ll keep updating this post with new links.