IExtendable while (this.IsAlive) self => self.UpdateAll()

19Aug/130

Don’t Unit Test NHibernate: Use Generic Repository

I was reading this stack overflow question: How can I solve this: Nhibernate Querying in an n-tier architecture?

The author is trying to abstract away NHibernate and is being counseled rather heavily not to do so. In the comments there are a couple of blog entries by Ayende on this topic:

The false myth of encapsulating data access in the DAL

Architecting in the pit of doom the evils of the repository abstraction layer

Ayende is pretty down on abstracting away NHIbernate. The answers on StackOverflow push the questioner toward just standing up an in-memory Sqlite instance and executing the tests against that.

The Sqlite solution is pretty painful with complex databases. It requires that you set up an enormous amount of data that isn’t really germane to your test in order to satisfy FK and other constraints. The ceremony of creating this extra data clutters the test and obscures the intent. To test a query for employees who are managers, I’d have to create Departments and Job Titles and Salary Types etc., etc., etc.. Dis-like.

What problem am I trying to solve?

In the .NET space developers tend to want to use LINQ to access, filter, and project data. NHibernate (partially) supports LINQ via an extension method off of ISession. Because ISession.Query<T> is an extension method, it is not stubbable with free mocking tools such as RhinoMocks, Moq, or my favorite: NSubstitute. This is why people push you to use the Sqlite solution—because the piece of the underlying interface that you want to use most of the time is not built for stubbing.

I think that a fundamental problem with NHibernate is that it is trying to serve 2 masters. On the one hand it wants to be a faithful port of Hibernate. On the other, it wants to be a good citizen for .NET. Since .NET has LINQ and Java doesn’t, the support for LINQ is shoddy and doesn’t really fit in well the rest of the API design. LINQ support is an “add-on” to the Java api, and not a first-class citizen. I think this is why it was implemented as an extension method instead of as part of the ISession interface.

I firmly disagree with Ayende on Generic Repository. However, I do agree with some of the criticisms he offers against specific implementations. I think his arguments are a little bit of straw man, however. It is possible to do Generic Repository well.

I prefer to keep my IRepository interface simple:

    public interface IRepository : IDisposable
    {
        IQueryable<T> Find<T>() where T: class;

        T Get<T>(object key) where T : class;

        void Save<T>(T value) where T: class;

        void Delete<T>(T value) where T: class;

        ITransaction BeginTransaction();

        IDbConnection GetUnderlyingConnection();
    }

 

Here are some of my guidelines when using a Generic Repository abstraction:

  • My purpose in using Generic Repository is not to “hide” the ORM, but
    • to ease testability.
    • to provide a common interface for accessing multiple types of databases (e.g., I have implemented IRepository against relational and non-relational databases) Most of my storage operations follow the Retrieve-Modify-Persist pattern, so Find<T>, Get<T>, and Save<T> support almost everything I need.
  • I don’t expose my data models outside of self-contained operations, so Attach/Detach are not useful to me.
  • If I need any of the other advanced ORM features, I’ll use the ORM directly and write an appropriate integration test for that functionality.
    • I don’t use Attach/Detach, bulk operations, Flush, Futures, or any other advanced features of the ORM in my IRepository interface. I prefer an interface that is clean, simple, and useful in 95% of my scenarios.
  • I implemented Find<T> as an IQueryable<T>. This makes it easy to use the Specification pattern to perform arbitrary queries. I wrote a specification package that targets LINQ for this purpose.
    • In production code it is usually easy enough to append where-clauses to the exposed IQueryable<T>
    • For dynamic user-driven queries I will write a class that will convert a flat request contract into the where-clause needed by the operation.
  • I expose the underlying connection so that if someone needs to execute a sproc or raw sql there is a convenient way of doing that.
6Aug/137

Isg.EntityFramework 0.8.0 Released

InterceptionContext is now passed to TypeInterceptor methods and ChangeInterceptor methods. This may result in breaking changes depending on if and how you have inherited those classes, but I’ve done my best to preserve existing behavior. I marked the obsolete methods as such.

The purpose of this change is enable the scenario where you want to write a log-record back to the database when a record is saved or deleted.

Update:

0.8.0 did not contain the updated assemblies.

0.8.1 does.

What happened?

My build server is configured so that it only creates and publishes packages from the last pinned build. I forgot to pin the build that has the changes. I've pinned the build and republished 0.8.1. I've created a workitem for myself to separate package creation from package publication so that I can inspect the package before it's sent to Nuget.

30Jun/138

Review of “Guitar Practiced Perfectly” Software

Overall

Guitar Practiced Perfectly is a piece of software that helps a guitarist manage and plan practice routines. It includes 300 or so practice routines out of the box. Routines can be organized into sessions. Sessions can be organized arbitrarily, but the software supports daily sessions. It’s written in Adobe Air so it will run on Mac and PC. I’m running on Windows 8 64-bit.

I’ve only used the software for one practice session so far. The overall effort is very good. As far as I know, it’s the only software of its kind. At $50 US, it’s a little pricey to buy without a trial.

image

 

Missing Features

  • I should be able to create my own routines. This is a huge gap in the software. For example, I'd like a version of the C major pentatonic that includes the minor 3rd and the diminished 7th. Or I’d like a routine in which I play a scale through ascending keys.
  • When I drag/drop an element between tree elements, I should be able to choose "Copy" or "Move."
  • In addition to being able to create a new routine, I’d like to be able to clone an existing routine and modify it.

Bugs

  • I've noticed that if I'm playing an exercise and change the tempo then it stops playing sound. I have to close/reopen the software to get it to play sound again.
  • Drag/Drop a routine within a session doesn’t work. This makes changing the order of the routines hard.

Usability Problems

  • The use of accordion style controls for the session menus makes it hard to understand that you can drag/drop exercises between accordion tabs. In general, accordions should not be used when data is shared across panels.
  • The fact that the screen elements are static is irritating. It would be nicer if I could move things around. The best UI I've seen for this sort of thing is in Microsoft Visual Studio. Each panel is draggable and dockable on its own. I don't know if Adobe Air gives you this kind of flexibility, but it would be nice, and it would make the drag/drop operations easier to manage as "Session by Weekday" could be docked to a different screen area than "Session by Skill Level."
  • The user should be able to drag/drop more than one exercise at a time. I found this annoying when I was trying to drag all of a certain category of exercise to my Sunday routine. I had to do them one at a time.
  • The labels that control Tempo, Lead In, Repeat, etc react to the mouse as if they were buttons. Clicking them doesn't do anything. This is confusing. They should either just be labels, or open some kind of advanced editing screen.
  • Having to choose between Music and Metronome is painful. They should have independent volume controls.The existing either-or functionality forces me to into a tricky volume balancing act with my amp.
  • Help->About menu should include the software version. The fact that the software version is missing from the UI makes it hard to tell if you are running the latest.
  • The main window should include a standard control box for changing screen size, minimize, and maximize functionality.
  • I think it should be impossible to delete system-defined routines and sessions. This is scary functionality as I could get rid of something very useful.

Overall

I like Guitar Practiced Perfectly very much and I’ll get a lot of use out of it. However, it’s not the software I was hoping it was. The lack of routine-creation and editing functionality means it misses the mark by quite a large margin. Some of the UI constraints make working with sessions very hard. For an intermediate player such as myself, it will definitely help me take my playing to the next level. However, I’ll not be able to use it to integrate my teacher’s lessons into my daily practice.

Final Score

70%

21Apr/136

Isg.EntityFramework 0.7.0 Released–Bug Fix

Issues Fixed

  1. ChangeInterceptor.OnAfter not working correctly.

The cause of the bug is that EntityFramework resets the EntityState to UnChanged after writing the object to the database. This means that I cannot tell which operation was performed on the entity unless I memoize the state before the operation. The effect of this change is that I can no longer get the EntityState of the item before the operation from the DbEntityEntry.

Breaking Changes

If you are inheriting from TypeInterceptor or ChangeInterceptor the signature of OnBefore and OnAfter has changed.

The new signatures are

 protected override void OnBefore(DbEntityEntry item, EntityState state)
 protected override void OnAfter(DbEntityEntry item, EntityState state)

16Apr/130

Testing Ninject Bindings

I recently had a subtle production bug introduced by creating more than one Ninject binding for a given interface to the same instance.

I wanted to be able to see what bindings existed for a given interface, but Ninject does not provide an easy way to do that.

This gist contains an extension method I wrote (with the help of a StackOverflow article) to acquire this information.

As this code relies on using reflection to get a private member variable, this code is brittle in the face of a change in the implementation of KernelBase. In the meantime, it works on my machine.

16Apr/130

Onion Architecture: An Opinionated Approach Part 2, Anemic Data Models

Anemic Data Model is my term for a domain model indicating entities and their relationships to other entities, but having little or no business behavior. It basically serves as a contract for a data store. It’s purpose is structural, and often to provide ease of queryability.

In ShowPlanner, the domain is about planning and selling tickets to musical events called “shows.” Venues contain one or more Stages, and a Show can consist of one or more Performances on one or more Stages at a Venue. Tickets are sold to a Show.

DataModel

This data model represents the universe of entities, attributes, and relationships that the ShowPlanner application will interact with at this time. These models have no methods or functions, no behavior of any kind.

The Problem of Behavior

Why no behavior? Putting behavior in domain models raises some difficult design questions. How do the domain objects get their dependencies? Which domain object should the method or methods that control behavior go in?

Let’s take a simple case. Suppose you want to model what happens when a Ticket is purchased by a Customer. When a show is created, a number of tickets are created as well. When a Customer buys a Ticket, the ticket will be marked as sold.

Ownership

Generally speaking it’s very seldom that we write basic CRUD applications in an enterprise environment. Application behavior tends to live in the relationships and what happens when certain kinds of relationships are created and destroyed. This means that application operations often involve the state of multiple domain objects directly and indirectly involved in the relationship that is changing.

There are several possible ways to model this operation.

    public class Customer
    {
        public int? CustomerId { get; set; }

        public IList<Ticket> Tickets { get; set; }

        [Required]
        public string Name { get; set; }

        public void Purchase(Ticket ticket)
        {
            ticket.SoldTo = this;
            ticket.Sold = true; 
        }
    }

 

Or

    public class Ticket
    {
        public int? TicketId { get; set; }

        public int? ShowId { get; set; }
        [Required]
        public Show Show { get; set; }

        public int? CustomerId { get; set; }
        public Customer SoldTo { get; set; }

        public bool? Sold { get; set; }

        [Required]
        public decimal Price { get; set; }

        public void SellTo(Customer customer)
        {
            this.Sold = true;
            this.SoldTo = customer;
        }
    }

Or

    public class Show
    {
        public int? ShowId { get; set; }

        public IList<Ticket> Tickets { get; set; }

        [Required]
        public string Title { get; set; }

        public void SellTicket(Customer customer, Ticket ticket)
        {
            ticket.Sold = true;
            ticket.SoldTo = customer;
        }
    }

 

Which domain object should own the method for selling the ticket? It will depend on who you ask. When a given operation affects multiple entities in the Domain, there is no objective way to decide which entity gets the behavior. The method performing the operation has no natural home.

Dependencies

Let’s assume you secure agreement that Customer should own this operation. You’re happily coding along on something else when a few weeks later your customer tells you that when the ticket is sold a message needs to be sent to a billing system. The messaging system is represented by an interface called IMessageSender. What happens in the domain model now? How does the Customer class get a reference to the MessageSender implementation?

You could do this I guess:

        public void Purchase(Ticket ticket, IMessageSender messageSender)
        {
            ticket.SoldTo = this;
            ticket.Sold = true;

            messageSender.Enqueue(new BillForTicketMessage(this, ticket));
        }

But that’s an ugly road to walk down. You’ll start expanding dependencies when you need to add logging, authorization, validation, and a host of other concerns. Suddenly what started out as a very simple method on domain model full of complexity.

Constructor injection is not viable if I’m expecting to use an ORM to retrieve my Customer instance. Assuming you could make that work, you have to consider that with the addition of each new operation involving Customer, you’ll be adding still more dependencies which will turn Customer into more of a GOD class than will be supportable.

Wouldn’t’ design-by-composition work better?

Designing the Domain Models

I said earlier that “domain models as merely a means of persisting the state of the application.” To my way of thinking, this is their core purpose. To that end, they should effectively act as a contract to the underlying data store used by your application. They should support both queryability and data modification and be well-organized.

Queryability

To support queryability, data models should be fully connected. This just means that any relationships between entities should be referentially  expressed. Prefer Performance.Show over Performance.ShowId. Some ORM’s such as Entity Framework support using both the Id and the reference. For others, such as NHibernate, having both properties is an issue. When faced with a choice, prefer a reference over an Id.

Data Modification

To support data modification, your data models should contain all the fields used in the database. I was writing an integration test recently and I needed to create some test data in Sql Server. As I tried to insert one of my entities, I discovered that field required by the database was not actually on the model. The original developer had only populated the fields he needed for the specific operation he was writing which resulted in additional work and testing for me. It also exposed a lack of integration test coverage for any operation involving this entity as it was impossible to create new records using existing code.

Organization

Data models are the center of the onion. They should be in their own assembly or package both to make them easier to find and modify, and to prevent other developers from violating the Dependency Depth principle by referencing higher layers.

Do’s
  • Put your data models in their own project or assembly. This makes them easy to find. They are the innermost circle in your application, so this project should have next to no dependencies on anything else.
  • If you’re tools set supports it, maintain a class diagram of the models and their relationships. The diagram above was generated by Visual Studio.
  • Prefer referential relationships over using Id’s to identify related data.  Use both if your ORM supports it.
  • This should go without saying, but use an ORM.
  • In the anal-retentive list of things to consider
    • List the primary key first.
    • List single-entity references second.
    • List collection references third.
    • List the entity’s fields last.
    • List audit data (create date, create user, etc) dead last.
    • Alphabetize fields. Why? Because with larger data models it gets really hard to find the field you’re looking for in an unsorted list. This is an easy thing to habitualize and saves a good bit of headache down the road.
  • In .NET, use System.ComponentModel.DataAnnotations to attribute your models metadata when it is known.
    • Especially use StringLength because it produces a nicer error message than “String or binary data would be truncated” when using SQL Server as the database.
Don’ts
  • Don’t put behavior on the models.
  • Don’t accept dependencies in the models.
  • Don’t put ORM-specific attributes on the models unless you have no other choice.
  • Don’t put anything on the models that isn’t actually in your data store.
    • This is another way of saying “don’t put behavior on the models.” But I’ve seen developers put properties on models that they calculate and set in the course of one operation and that isn’t used in other operations. This breaks down when another operation wants to use the calculated value.
  • Don’t use data models in your UI. In web applications, this means don’t use data models in your pages and controllers. Use View Models and some sort of Request-Response api instead.

This is Part 2 of a series

Disclaimer: This series of articles is intentionally opinionated. From an architectural perspective I am much more interested in clearly defining each layer than I am in the choice of specific implementation pattern. However, an architecture doesn’t exist without the details that make it up, so I must choose some implementation pattern so that the architecture can be revealed. Since I’m the one writing the series, I’ll choose implementation patterns I like. Smile If you have a better idea, take a fork of ShowPlanner and share it!

10Apr/130

Isg.EntityFramework 0.6.0 Released

Breaking Changes

New Features

 

Isg.EntityFramework.Interceptors.Auditable

If you have a class that implements IAuditable the AuditableChangeInterceptor will use IPrincipal and IClock to assign audit fields. If you are inserting a new record, CreateUser and UpdateUser will be set to IPrincipal.Identity.Name, and CreateDate and UpdateDate will be set to IClock.Now. If you are updating an existing record, only the Update fields will be modified.

    public interface IAuditable
    {
        DateTime CreateDate { get; set; }
        string CreateUser { get; set; }

        DateTime UpdateDate { get; set; }
        string UpdateUser { get; set; }
    }
16Mar/130

Onion Architecture: An Opinionated Approach, Part 1

The Purpose of Architecture

I believe that the value of explicitly identifying and conforming to an architectural pattern in your applications is two-fold.

  1. It defines the number of boundaries between layers and how they communicate.
  2. Future maintainers can leverage what they’ve learned about one vertical slice to understand the rest of the application.

In most cases I don’t think developers bother to identify their application architecture, and consequently their application doesn’t have one. Or rather, it has many. Each new operation is put together in a slightly different way from all the others. Nothing learned about one area of the system can be used to understand other areas of the system. Nothing in the existing implementations direct you on how to add or modify new or existing features.

What a mess!

Onion Architecture

Full disclosure: I don’t know many architectural patterns. However, I’ve spent the last 5 years of my career groping toward an architecture that was hazy in my mind. The first explicit description I encountered of this pattern that I encountered was in a lecture I attended by Uncle Bob at SCNA 2011. Later I found some other resources.

In The Onion Architecture Jefferey Palermo describes a method of structuring an application such that the work of the application is separated from the infrastructure and loose coupling provides flexibility.

There are two important rules about this architecture. I personally thinking of them as the Dependency Direction Principle and the Dependency Depth Principle.

Palermo writes:

The fundamental rule is that all code can depend on layers more central, but code cannot depend on layers further out from the core.  In other words, all coupling is toward the center.

This principle is about the direction of dependencies. A given application may have a greater or fewer number of layers in its “onion,” but the outer layers should depend on the layers underneath, and the inner layers should have no dependencies on the outer layers.

In Clean Architecture, Uncle Bob calls this The Dependency Rule

The overriding rule that makes this architecture work is The Dependency Rule. This rule says that source code dependencies can only point inwards. Nothing in an inner circle can know anything at all about something in an outer circle. In particular, the name of something declared in an outer circle must not be mentioned by the code in the an inner circle. That includes, functions, classes. variables, or any other named software entity.

By the same token, data formats used in an outer circle should not be used by an inner circle, especially if those formats are generate by a framework in an outer circle. We don’t want anything in an outer circle to impact the inner circles.

Neither of the above-linked posts calls out what I think is another important rule about dependencies. Here, I’m speaking for myself.

The Dependency Depth Principle: Application layers must depend only on the contracts exposed by the layer immediately beneath them.

By controlling dependency depth, the seams between your application layers become well-defined and easily testable. More importantly, changes to the mechanics or api of one layer do not necessitate changes to the surrounding layers.

An Example

Let’s say I have a domain service that performs searching for musical performances. This service accepts a request like this:

   1:      public class QueryPerformanceRequest
   2:      {
   3:          public int[] PerformanceIds { get; set; }
   4:          public string[] Artists { get; set; }
   5:          public string[] Venues { get; set; }
   6:          public bool? Upcoming { get; set; }
   7:   
   8:          public int? Page { get; set; }
   9:          public int? PageSize { get; set; }
  10:      }

 

and returns this:

   1:      public class QueryResponse<T>
   2:      {
   3:          public T[] Results { get; set; }
   4:   
   5:          public int Page { get; set; }
   6:   
   7:          public int PageSize { get; set; }
   8:   
   9:          public int TotalRecords { get; set; }
  10:      }

QueryPerformanceRequest is a parameter object with which the client can indicate which data is being searched for by filling out properties. Some underlying layer is responsible for executing the query against the data store.

My web application application has this controller action:

   1:          public ActionResult Search(string term)
   2:          {
   3:              using (var command = _performanceCommands.Query())
   4:              {
   5:                  var request = _builder
   6:                      .Create<QueryPerformanceRequest>()
   7:                      .From(term)
   8:                      ;
   9:                  var results = command.Execute(request);
  10:   
  11:                  var model = _builder
  12:                      .Create<PerformanceSearchResultsViewModel>()
  13:                      .From(results);
  14:   
  15:                  return View(model);
  16:              }       
  17:          }

What’s happening?

Line 3: Constructs the domain service used to perform the search.

Line 5: I like to use a fluent api for object conversion. I’ll speak more about this later. In this case, we’re just converting the incoming string into the QueryPerformanceRequest object. The converter manages the seam between the Application Services layer (MVC Controller) and the Domain Services layer (the command).

Line 9: This is the line that performs the query.

Line 11: Now that we have results from the query, let’s get them ready for presentation by converting them into a ViewModel.

Line 15: Returns the page with the required data.

Things to notice:

The domain services layer provides a contract in the form of a command to execute the query, a parameter object to describe the query, and the query results. It’s probably that somewhere inside the command database connections are being created, domain models are being searched for, and the results are being transformed back into the response. The controller layer does not directly depend on any of that logic.

Further, the controller has it’s own api independent from that of the domain services layer. Pass me a string and I’ll hand you a ViewModel. None of the details of the domain services layer leak into the View.

Each layer depends only on the layers underneath, and only on the layer directly underneath. No abstraction from an underlying layer crosses more than one seam.

If I change my controller api, the query contracts do not have to change. If I add behavior to my query contracts, the controller gets that behavior without modifications to the existing code. If I change the implementation of the query command, the controller does not have to change. Each layer is protected from changes in the other layers by layer-specific contracts and explicit management of the seams between layers.

About this series

I’m going to be writing a series of posts in which I build a simple application from the ground up. I want to express the Onion Architecture as well as my favorite implementation patterns. I think it will be a good exercise for me to explicitly identify the reasons for many of the things I do in my daily work.

I will host the application on github so you’ll be able to review the full source code as I work.

In my next post in this series, I’ll explain the demo project and start describing the innermost layer of the onion: The domain model.

11Mar/131

Adherence to Architecture vs. YAGNI

I had an interesting discussion with my co-workers this morning about architecture.

Some background

We’re putting together a sample web application to demo the default architecture we expect from applications. The idea is that applications should either be written to use the default architecture, or they should be migrating in that direction. As we have new ideas about how things should be done, we can fork the demo application and try our new idea out. Then we can brownbag our new work to the team and share idea. If the team likes it, the pull request will be accepted into the demo project.

Onion Architecture

I was asked to start the demo application work. I am a proponent of the Onion Architecture which clearly discriminates responsibilities among layers and enforces the rule that dependencies only point inward, and only at the layer inside the current layer. In other words, dependency depth for any class should be 0 or 1.

The Problem

In Draw Abstractions From Concretes I wrote:

Waiting until you have an actual need for the abstraction proves that the additional complexity you’re adding is actually necessary and that the abstraction you’re creating is the correct one.

I’m basically just invoking YAGNI with a special focus on how you know “when you need it.” The problem is that in the demo application I’m creating contracts and services for each layer of the application even though the application itself doesn’t have enough functionality (yet) to demonstrate the need for those layers.

Our team is split.

One side believes that YAGNI precludes us from creating an Application Services layer when the Domain Services are sufficient to solve the immediate problem. The specific issue is that Application Services have their own contracts for inputs and outputs that look much like the contracts used by the Domain Services layer. Why not just expose the Domain Services directly? This just creates more complexity than is necessary to solve the problem and makes the code harder to understand.

The other side (me included) believes that choosing an architecture and sticking to it overrides YAGNI. It’s better to have an defined architecture applied consistently even in cases where it’s not strictly necessary from a purely functional perspective. The purpose of having an Application Services layer apart from the Domain Services layer is that it allows them to change independently over time. It’s immaterial that in the beginning much of the behavior is basically pass-through. Anyone who is going to work on the code base will have to learn what Onion architecture is (or whatever architectural pattern is chosen for the application) and the additional complexity will make sense.

What are your thoughts?

Filed under: Design, Practices 1 Comment
11Mar/130

Draw Abstractions from Concretes

It’s often tempting to draw a more abstract solution to the problem you’re currently facing. It seems wrong to handled the the local concrete case when you know you’re going to be doing something very similar soon. Why not build a more abstract solution now and reuse it later?

There’s a principle in software called YAGNI. “You Aren’t Going to Need It.” The ideas behind YAGNI are that you shouldn’t introduce complexity into code until you’ve proven you need it. Waiting until you have an actual need for the abstraction proves that the additional complexity you’re adding is actually necessary and that the abstraction you’re creating is the correct one.

That last point bears repeating.

Wait until you have at least 2 or even 3 similar code paths before creating the abstract solution. Otherwise, you may mistake which code needs to be abstracted and end up with an abstraction that is ill-suited to the actual problems you’re trying to solve.

Filed under: Design, Practices, TDD No Comments