I’ve spent some time recently renewing my old DDDSample.NET project. I understand that it is the projection of my subjective and uninformed view of Domain-Driven Design, but still I see a value in having some implementation compared to having nothing — it provokes discussion. That’s why I will continue to invest my time in it. If you happen to read this and want to take a look at the code, please remember that is is a sample (as the name suggests), not a guidance. The difference is following: a sample shows how I am doing things while a guidance would show how you are supposed to do things.

Journey through the stack trace

Classic version of DDDSample is a web application with simple UI created with ASP.NET MVC. This is where all starts. I would like to take you on a journey through the stack trace to explain various architectural decisions. Let’s register a new handling event.

NHibernateAmbientSessionManager

The very first class that gets a chance to process the request is NHibernateAmbientSessionManager. It is responsible for creating an ambient NHibernate session that will be bound to the request. After processing the request the session is released. It can be accessed anywhere in the code statically through CurrentSessionContext class. This is a built-in feature of NHibernate.

public void CreateAndBind()
{
    CurrentSessionContext.Bind(_sessionFactory.OpenSession());
}
public void UnbindAndDispose()
{
    var session = CurrentSessionContext.Unbind(_sessionFactory);
    if (session != null)
    {
        session.Dispose();
    }
}

HandlingController

Next is the HandlingController and it’s RegisterHandlingEvent method/action

[AcceptVerbs(HttpVerbs.Post)]
public ActionResult RegisterHandlingEvent(string trackingId, DateTime? completionTime, string location, HandlingEventType type)
{
    if (!completionTime.HasValue)
    {
        ViewData.ModelState.AddModelError("completionTime", @"Event completion date is required and must be a valid date.");
    }
    if (!ViewData.ModelState.IsValid)
    {
        AddHandlingLocations();
        AddHandlingEventTypes();
        return View();
    }
    _handlingEventFacade.RegisterHandlingEvent(completionTime.Value, trackingId, location, type);
    return RedirectToAction("Track", "Tracking", new { trackingId });
}

There’s nothing fancy here, but is shows in a nice way that in this design, the responsibility of a controller is data validation and parsing (mostly done by MVC internals). After ensuring that data conforms to the required format, it is passed to another class which is…

HandlingFacade

This class hides the design of internals of the application from the UI. As far as controllers are concerned, business logic is implemented in façade’s methods. The truth is slightly different, however.

public void RegisterHandlingEvent(DateTime completionTime, string trackingId, string location, HandlingEventType type)
{
    var command = new RegisterHandlingEventCommand
                        {
                            CompletionTime = completionTime,
                            TrackingId = trackingId,
                            OccuranceLocation = location,
                            Type = type
                        };
    _pipelineFactory.Process(command);
}

All the façade is doing is packing the arguments into a command object and sending this command to the pipeline where it is processed. Why create a separate class instead of putting this method on the controller? I like my controllers to be concerned only by the UI and have only one reason to change.

NHibernateTransactionCommandFilter

Before the command is actually executed, a number of filters are invoked. I use a very simple command pattern implementation I’ve written a few weeks ago for the sole purpose of using in DDDSample. It allows me to define these filters in a nice (again, subjective view) way

public void OnHandling(object command)
{
    _ambientSession = CurrentSessionContext.Unbind(_sessionFactory);
    _session = _sessionFactory.OpenSession();
    _transaction = _session.BeginTransaction();
    CurrentSessionContext.Bind(_session);
}
public void OnHandled(object command, object result)
{
    CurrentSessionContext.Unbind(_sessionFactory);
    _transaction.Commit();
    _session.Close();
    CurrentSessionContext.Bind(_ambientSession);
}

Before handling a command an aforementioned ambient NHibernate session is unbound from the current context. We are not going to use it while processing the command because we need a clear workplace. We open a new session and a a new transaction. Whatever happens in the command handler, stays in the command handler. After a command succeeds we unbind the session it used and commit the transaction. Then we restore the ambient session so that UI can use it.

Why don’t we just use a transaction on this ambient session? There is a couple of reasons. First, there can be a transaction started before processing the command and we don’t want to take part in it. Second, we want to be absolutely sure we don’t have any entities in the session-level cache. Why? Because we might use some hints to fetch them more efficiently in context of command processing (like for example force eager load on some relations). And last but not least, if command fails we don’t want to break the session UI was using because it may need it for whatever reason after the command processing attempt failed.

The corollary of this is, we don’t want to put any persistent (tracked by NHibernate) into the command. If we allowed this, we could attach it by mistake to this other session and very strange things could happen. The side effect is we can safely serialize commands which allows us, if the need comes, to put our domain model on a separate tier then its client (the web application).

RegisterHandlingEventCommandHandler

When we have the new session and transaction in place it’s time to do the actual work. Here’s how a typical command handler look like

public object Handle(RegisterHandlingEventCommand command)
{
    var trackingId = new TrackingId(command.TrackingId);
    var cargo = _cargoRepository.Find(trackingId);
    var occuranceLocationUnLocode = new UnLocode(command.OccuranceLocation);
    var occuranceLocation = _locationRepository.Find(occuranceLocationUnLocode);
    var evnt = new HandlingEvent(command.Type, occuranceLocation, DateTime.Now, command.CompletionTime, cargo);
    _handlingEventRepository.Store(evnt);
    return null;
}

The idea here is to have only one method or constructor invocation on an Aggregate Root in one command. As you can see, command handler’s responsibility is to convert the raw data from the command to the proper Value Objects. The validation of data is performed when constructing VOs. In this case we create a new AR so we first instantiate a new object and then call repository to store it.

HandlingEventRepository

What happens in the repository?

public void Store(HandlingEvent handlingEvent)
{
    Session.Save(handlingEvent);
    _eventPublisher.Raise(handlingEvent);
}

Two things. First, we save the newly created AR to the command’s session. Then we use an Event Aggregator to publish this AR as an event. I based this approach on Eric Evans’ What I’ve learned about DDD since the book presentation where he explains that in many domains you encounter Aggregate Roots that are immutable. He calls them Events.

CargoWasHandlerEventHandler

The Event Aggregator publishes the event to all interested parties. In our case there is only one

public void Handle(HandlingEvent handlingEvent)
{
    handlingEvent.Cargo.DeriveDeliveryProgress(handlingEvent);
}

It calls a method on a Cargo Aggregate Root to notify it about the event. One thing worth notice here is we are doing it synchronously in the sample but our contract does not guarantee synchronicity. We write our event handlers in such a way that they can be executed asynchronously to the transaction that published the event. It is good to have such possibilities open in case we need to scale.

Cargo

This is how we reach the Cargo AR

public virtual void DeriveDeliveryProgress(HandlingEvent lastHandlingEvent)
{
    Delivery = Delivery.DerivedFrom(RouteSpecification, Itinerary, lastHandlingEvent);
}

The method looks very simple and it is not a coincidence. In classic DDD we have limited testing options since we can’t set our Entities to proper state easily (as easy in if we use Event Sourcing). That’s why we don’t want to test Entities. We want to test Value Objects because they are immutable and truly persistence ignorant. All we do in an Entity is pass the arguments to a VO and replace the current value with a new one. The probability that we make a bug in this one-liner is small, at least I hope so.

Delivery

Finally we arrived at our destination, the Value Object. Here I won’t include any code as it is quite complex and lengthy. I’ve already said probably the most important thing about VOs in this approach: they are immutable. This property allows us to test them easily. The compromise we are willing to accept in regards to Value Objects is, we expose their state via properties. Because we don’t have Command and Query Responsibility Separation, we use same objects (but remember, fetched via different session) to read and to write.

Summary

I hope you enjoyed this journey through the layers of the onion. Remember that this is just a sample. Most of its features were tested in the field but some combinations of them were not. I am eager to hear what you think about this approach and also to hear about your approach to DDD when size and/or complexity does not justify CQRS.

As I promised in one of the previous posts, I am now in process of renewing the DDDSample.Net source code. It’s been quite a while since I published the first version of it. Many technologies have changed and my take on Domain-Driven Design and software architecture also has changed slightly.

First of all, the repo was moved to github. Hurray! In the process of transforming TFS repository into a git one I lost the branch structure. Originally all versions were branched one from another which made updating all samples a little bit easier since (ideally) I had to change only one and then merge this change. With git I am thinking of a slightly different structure. I am pretty sure I can freeze some portions of the solution (like routing engine and most of the UI) and move them to separate repos. Then I can import them as submodules to each of the samples.

At first I just wanted to add new features to the existing samples but when I opened the vanilla version (a port of Java DDDSample) I found out that it is so outdated that it urgently needs to be renewed. The changes I made so far include:

• Upgrading solution to VS2010 format
• Removing the web setup project (I guess nobody used it, ever)
• Switching to NuGet for resolving most of the packages (using don’t commit packages workflow described here by David Ebbo)
• Upgrading some dependencies (like NHibernate) to the newest versions
• Switching from using façade-like classes in application layer to commands and command handlers implemented using brand new tiny LeanCommandUnframework (a separate micro project hosted here on github)
• Switching from Unity 1.2 to Autofac
• Removing dependency on NServiceBus
• Cleaning up the global.asax file

I am now quite happy with the solution. Everything seems to have its place in the architecture. There are some things yet to be clean up such as changing the way command handlers are created but these should be minor fixes. If you have some spare time, please clone the repo and check if you like what I did. And please note that only Vanilla version was updated.

A Domain-Driven Design sample I created some time ago, DDDSample.Net, is now a little bit rusty. I though it is a good idea to spend some time and make it up to date. It will involve, for sure, moving the project to github because you all know what I thing about TFS version control.

Currently there are 4 major versions of DDDSample solution

• Vanilla (‘by the book’)
• CQRS with two relational databases
• CQRS with event sourcing
• Layered model

I am thinking about dropping the second one as it was more like an experiment, not a final solution. The layered model is an advanced version of vanilla solution witch demonstrates how to structure larger domain models. Another thing I might do is migrate the event sourcing sample to NCQRS. Or maybe I should use EventStore directly? What do you think?

Now the important part. I have some ideas what to implement next and I need your feedback. Help me rate them

• Event driven SOA a’la Udi Dahan. This would be probably an extended version of layered model sample but with slightly different structuring approach (autonomous services instead of layers).
• Vanilla with RavenDB as a data store
• Native CQRS with event sourcing on RavenDB according to this description by Ayende.

If you have some other ideas, post them in the comments. I am also thinking about getting rid of the installer projects. It does not make sense to just install the application in IIS and don’t look at the code. And if you open it, you can run it by hitting F5.

Quite a lot have happened since last DDDSample.Net information was published here. Version 0.8 was released on April 18. This is the most recent binary release of the project. It focuses on the concept of model layers which were introduced in a separate code branch.

On April 30 another branch — AutoPersistence – was added. AutoPersistence is a concept-proof exploring the possibilities of inferring persistence mapping from the model. AP uses slightly modified version of FluentNHibernate to achieve this goal. This version is currently available only in trunk.

The most recent change is a redesign of Handling aggregate in Vanilla version of DDDSample. The new design is now more aligned with book and original Java-based project.

Stay tuned!

Just a quick note. There was no new post yesterday because I was busy implementing automatic persistence for domain model concept-proof. In the previous post I was writing about private field automapping. Since then I managed to implement a bunch of other concepts, including composite elements.

My fork of FluentNHibernate (automapping-fields branch) on github was updated with the most current code version.

DDDSample.NET ‘AutoPersistence’ branch uses the modified FNH to persists its domain model and it works! Without a single mapping file!

So, if everything works fine, why ‘halfway through’? That is because the code is very, very dirty and needs much work before it can be used in production.

0.7 release of DDDSample is there. Go, download it, and say if you like it. There are now really five different versions in the package:

• Classic with synchronous communication
• Classic with asynchronous communication via NServiceBus (these two can be switched using compilation target)
• CQRS using two NHibernate relational sores
• CQRS using with relational store based on LINQ 2 SQL (not available as binary installation package, only in trunk)
• Event Sourcing with CQRS

I really would like to hear you opinions on where the project should go now? Do you think it is finished and contains all the things it should contains? What needs to be done? What should be done first?

Installation is dead-simple when using default SQLite database, so don’t be afraid. If you have any problems, feel free to contact me via e-mail or twitter.

Zdaję sobie sprawę, że tytuł jest ogromnym skrótem myślowym. Tak naprawdę chodzi mi o możliwość generowania raportów z rozwiązań wykorzystujących model domeny z CQRS. Oczywiście, posłużę się przykładem DDDSample. Na wstępnie jednak muszę się przyznać, że nie jestem ekspertem od business intelligence, więc jeśli popełniłem jakieś karygodne wykroczenia, proszę o wyrozumiałość i zgłoszenie poprawek w komentarzach — będę wdzięczny za wszelkie uwagi.

Problem wygląda następująco: nasz system transakcyjny działa świetnie, jest wydajny, bezpieczny itp. Nadszedł jednak czas, aby wygenerować z niego jakiś raport potwierdzający, że system się sprawdza biznesowo. Jak to zrobić, mając po stronie komend silnie znormalizowaną bazę zoptymalizowaną dla operacji update/insert, a po stronie zapytań — tabele odzwierciedlające formatki UI? Są dwie możliwości:

1. Zmodyfikować bazę strony zapytań, aby stała się prawdziwą “bazą raportową”. Dzięki temu będzie mogła służyć i do generowania raportów i do wyświetlania danych na formatki. Niestety konsekwencją tego jest znaczne zwiększenie skomplikowania kodu dostępu do danych dla formularzy i list. Dlaczego? Zaraz zobaczymy.
2. Dodać kolejną (3!) bazę danych zoptymalizowaną pod kątem raportów. Minusem jest, jak zwykle, zwiększony wysiłek ze strony administratorów. Plus (również jak zwykle): lepszy podział odpowiedzialności i możliwość optymalizacji.

Spróbujmy więc zrealizować to drugie rozwiązanie. Na początek potrzebujemy struktury bazodanowej, która nadawałaby się do generowania raportów. Oczywiście, w rzeczywistej sytuacji zapytalibyśmy naszego klienta, jakich raportów potrzebuje. Niestety nie mam takiej możliwości pisząc te notkę. Przygotowałem więc schemat, który wydaje mi się użyteczny:

Pozwala on na analizę towarów pod kątem zmian rzeczywistej trasy w stosunku do tej zarejestrowanej i ich wpływu na dostarczenie towaru. Z drugiej strony umożliwia także analizę samych tras: którędy prowadziła, czy wynikiem było złe skierowanie towaru, czy została porzucona (zmieniona), czy też w wyniku jej realizacji towar został dostarczony.

Na pierwszy rzut oka widać, że transformacja tak przechowywanych danych do formatu niezbędnego do wyświetlenie na formatkach byłoby bardzo trudna. Utwierdza mnie to w przekonaniu, że (tym razem) słusznie wybrałem wariant drugi (osobne bazy).

Mając już strukturę danych, zastanówmy się, czego potrzebujemy, aby ją zasilić? Z pomocą przychodzi nam naturalna właściwość tego rodzaj systemów CQRS. Są one naturalnie przystosowane do scenariuszy real-time business intelligence, ponieważ posiadają wbudowany mechanizm wypychania danych z bazy transakcyjnej w czasie rzeczywistym (służący do zasilania bazy dla zapytań). Możemy się więc w niego bezwstydnie wpiąć. Potrzebujemy jedynie czterech obiektów obsługi komunikatów dla zdarzeń:

• zarejestrowano towar (utworzenie obiektu w CargoFacts i RouteFacts)
• przypisano trasę (aktualizacja RouteFacts)
• zmieniono lokalizację docelową (utworzenie obiektu w RouteFacts, modyfikacja reprezentującego poprzednią trasę)
• zarejestrowano zdarzenie obsługi (aktualizacja rzeczywistego miejsca załadunku towaru i miejsca dostarczenia towaru, aktualizacja pola “misdirected” itp.)

Implementacje możemy wykonać (znów) na dwa sposoby: albo bezpośrednio przygotowując odpowiednie komendy SQL, albo mapując przedstawiony model na obiekty. Co kto woli.

PS. Zamierzam spróbować zaimplementować przedstawione rozwiązanie. Jak tylko mi się uda, podzielę się z Wami wynikami eksperymentu.

I have just published some new documentation pages on DDDSample.Net CodePlex site. You can now read about Domain-Driven Design elements in context of class diagrams, compare CQRS approach to the classic one and read on how Event Sourcing influences the model.

Zostałem niedawno zapytany, dlaczego w projekcie DDDSample.NET projekt “Application” nazywa się właśnie tak, a nie “Domain Services”. Zwróciło to moją uwagę na całkiem spory problem nazewnictwa związanego z DDD oraz ogólnie z architekturami. Jednym ze źródeł problemu zdaje się być niesamowicie przeładowane znaczeniowo słowo “usługa”. Ale po kolei…

Wspomniany projekt “Application” zawiera fasadę Modelu Domeny udostępniającą operacje biznesowe realizowane za pomocą tegoż modelu. Te operacje to coś w rodzaju transaction script-ów operujących na obiektach domeny. Nazwę zaczerpnąłem oczywiście wprost z Java-owego oryginału, którego dokumentacja tak opisuje ten element architektury:

The application layer is responsible for driving the workflow of the application, matching the use cases at hand. These operatios are interface-independent and can be both synchronous or message-driven. This layer is well suited for spanning transactions, high-level logging and security.

The application layer is thin in terms of domain logic – it merely coordinates the domain layer objects to perform the actual work.

Przyznam szczerze, że nazwa “Application” nie jest najszczęśliwsza na świecie, bo tak na dobrą sprawę, nie mówi nic o przeznaczeniu tej warstwy. Można ją znaleźć także w innych przykładach, np. w architekturze cebulowej Jeffreya Palermo. Różnica polega jednak na tym, że u Palermo nazwa brzmi “Application Services”, co niesie już ze sobą jakieś znaczenie — mamy do czynienia z usługami.

No właśnie. Dlaczego pisałem na wstępie, że winne jest słowo “usługa”? Ponieważ tak naprawdę ja najchętniej z “Application Services” zostawiłbym “Services” jako nazwę mojej warstwy. Zauważcie, że pasuje ona o wiele lepiej pasuje do przytoczonego opisu. Niestety usługi występują już w tylu kontekstach w naszej terminologii, że wprowadzenie kolejnych “usług” byłoby niewskazane.

Być może lepiej byłoby w ogóle zrezygnować z terminologii wywodzącej się z “Application Services”? Można się odwołać np. do tego, że warstwa ta implementuje przypadki użycia i nazwać ją “Use Cases”. Albo, podchodząc do problemu od strony technicznej, zauważyć że jest to implementacja wzorca fasady — “Model Facade”. A jak Wy nazywacie projekty takiego rodzaju w swoich architekturach?

Druga część pytania dotyczy domain services — usług modelu domeny. Wydaje się, że jest jeszcze wiele wątpliwości związanych z usługami w Domain Driven Design. Moje rozumienie tego termin jest następujące.

Usługi modelu domeny pozwalają wyrazić operacje, które nie mają naturalnie przypisanego obiektu wykonującego je lub są realizowane przez obiekty zewnętrzne w stosunku do modelu. Na przykład IPricingService to usługa zwracająca ceny produktów na podstawie danych uzyskanych z innego systemu za pośrednictwem webserwisu. Na poziomie modelu reprezentowana jest przez interfejs, aby nie uzależniać go od szczegółów implementacyjnych.

Osoba, która zadała mi pytanie rozumiała usługi domenowe jako sposób na wykonanie pewnych bardziej skomplikowanych operacji biznesowych poprzez orkiestrację wywołań na obiektach modelu, czyli… dokładnie to, co u mnie kryje znajduje się w warstwie “Application”. Podobne opinie znalazłem też na kilku znanych blogach, np. tu. Cóż, nie zgadzam się z takim podejściem. Nie widzę sensu, aby definiować takie byty. Co więcej, usługi domenowe w takim znaczeniu miałyby bardzo niebezpieczną tendencję to wysysania logiki biznesowej z obiektów modelu.

Podsumowując, w dużym skrócie i uproszczeniu:

• Następnym razem napewno nazwę swoją warstwę “Application” inaczej. Skłaniam się ku “Use Cases”.
• Usługi domenowe mogą reprezentować albo operacje nie posiadające wykonawcy (algorytmy), albo być abstrakcją dla synchronicznych usług implementowanych na zewnątrz. Oba przypadki powinny być bardzo rzadkie.

As CQRS version of DDDSample is getting mature, I am switching my development efforts to event sourcing support. For those of you who don’t know that yet, event sourcing is a pattern which encourages persisting not snapshots of data in particular moments in time, but rather events which describe how these data changes. Then, data snapshots (not only the latest, but also historic ones) can be reconstructed by applying these events starting from the ‘beginning of time’. More about defining event sourcing and CQRS can be found here.

I’ve started by looking at Marc Nijhof’s excellent series of posts (starting here) describing event sourcing. Mark has built a sample application based on what he had learnt about CQRS during Greg Young’s course.

Mark’s solution is fairly simple. In the core there is a domain assembly containing classes that model domain concepts like Account and Client. These inherit and use additional infrastructure assemblies which provide event sourcing features.

One thing that looks odd to me is usage of memento pattern to store snapshots of aggregates. I don’t understand why can’t they (the aggregates) be simply serialized as they are. Maybe there is a reason behind this, but I don’t see it, at least for now. I marked this area for further investigation.

Moving away from the core, there are several supporting assemblies which contain commands, command handlers, events and so on. Personally, I don’t see a point in separating some of them. There is an obvious reason why commands and command handlers are in separate assemblies, but the events? They are part of the domain model, at least for me.

After more careful analysis I noticed that there is no notion of messages in Marks sample solution. The events themselves are passed from command side to query side. That is probably the reason why the events are defined in separate assembly — if they are to be used in reporting, it would be nice not to have to reference whole domain model assembly, only the events.

Going further, Mark is using a custom O/RMish solution to implement query/reporting side. I am not a big fan of custom solutions and I probably would use an off-the-shelve one, even if it is slightly more complex then necessary. I am planing to use NHibernate, as in the non-event-sourcing CQRS version.

Anyway, Mark did great job of describing event sourcing concepts to the public. I probably wouldn’t be able to start writing my own implementation in DDDSample without first reading his code. Thanks a lot!