Not everything works that great (i.e. copying large files via drag&drop doesn’t work, renaming folders, etc., at least in my experience), but it’s pretty darn convenient most of the time. I’m not sure the same thing works for your own personal folders. I don’t use SkyDrive at all, but it certainly does for shared ones (nice when you need a simple way to share docs within a team, privately and without requiring any software to be installed for syncing…).

Enjoy.

But let’s say they encounter some isssue (maybe a bug, maybe a potential improvement) with the library. At this point, going from user to contributor (of a fix, or a good bug repro or even a spike for a new feature) is a very steep and non trivial multi-step process of registering with some open source hosting site (codeplex, github, bitbucket, etc.), learning how to grab the latest sources, build the project, formulate a patch (or fork the code), learn the source control software they use (mercurial, git, svn, tfs), install whatever tools are needed for it, read about the contributors workflow for the project (do you fork & send pull requests? do you just send a patch file? do you just send a snippet? a unit test? etc.), and on, and on, and on. Granted, you may be lucky and already know the source control system the project uses, but in really, I’d say the chances are pretty low. I believe most developers *using* OSS are far from familiar with them, much less with contributing back to various projects. We OSS devs like to be on the cutting edge all the time, ya’ know, always jumping on the new SCC system, the new hosting site, the new agile way of managing work items, bug tracking, code reviews, etc. etc. etc.. But most of our OSS users are largely the “dark matter developers”, they simply don’t have the time to put through all that friction just to contribute back. Even if they want to, it’s just WAY too much. It’s discouraging.

We can do better.

How about this flow?

1. User installs library: install-package Moq
2. He/she uses it happily for years (let’s say ), until one day an issue comes up that’s becoming annoying or doesn’t look like it has a known workaround. So it’s time for a time-boxed investigation to see if it’s truly a library bug or a user bug.
3. User uninstalls library: uninstall-package Moq
4. User installs library source package: install-package Moq.Source
   • At this point, they get the entire *source* for the project, as content (source) files in the SAME project they were previously using the library reference. Everything should still compile just like before. All that changed is that now you’re building against the actual sources, not the library.
   • Any dependencies the library uses for compiling got added automatically by NuGet to the users’ project.
5. In order to understand a bit the library source code and how it’s being tested, the user installs the library unit tests source package: install-package Moq.Tests
   • At this point, they can run the entire test suite for the library, inspect the tests to learn how to isolate various pieces, and learn about the structuring of the code a bit.
   • Note that the tests source would typically be installed in a test project on the user’s solution.
6. Now the user goes and creates a new unit test to try to repro in isolation the issue he/she found.
7. After a successful repro, the time-box may be over. But still, the clean repro he/she got is very useful in its own.
   • If the user has enough time, they may even be able to fix the issue in the code itself, or add the missing behavior.
   • Because of the way NuGet works, when you install a package that brings “content” (code, markup, config files, etc.) into your project, you now have two copies of that content: the original one under the packages folder alongside the solution file, and the potentially modified one in your own project.
8. At this point, a little bit of VS extensibility and automation could detect that you made changes to that code, and offer a context menu to “Send Feedback”, which could pre-package the diff (patch file, .zip, clone/commit/whatever), allow the user to enter briefly an explanation of the issue, and be done.
9. Now, if the issue was really a showstopper, the user now has a way forward, that didn’t even require them to leave their own solution. Granted, checking into a company source control the actual source for an entire OSS project is typically unfeasible. So the alternative is for them to just uninstall-package Moq.Source, go back to install-package Moq and go on by implementing a workaround. But they have actively contributed back to a project they appreciate, they now have a real explanation (for dev leads, upper management) of why something proved harder than expected, and they probably even came out of the experience learning a new trick or two that they found in that codebase while they were investigating. An all around win-win situation.

I believe this is totally worth exploring. I’m willing to give this a try for Moq v5, as we talked about in our first hangout. What do you think? Is this something that looks reasonable and useful?

public class OrderProcessor
{
    public void ProcessPayment(Guid orderId, Payment payment)
    {
        using (var repo = new OrmRepository())
        {
            var order = repo.Find<Order>(orderId);
            order.Pay(payment);

            repo.Save(order);
        }
    }
}

Now that clearly is very hard to test ‘cause it’s directly instantiating the repository. So we know we have to refactor that and pass the repository instead, so that tests can replace the implementation and make assertions about the interaction (if we want to):

public class OrderProcessor
{
    private OrmRepository repository;

    public OrderProcessor(OrmRepository repository)
    {
        this.repository = repository;
    }

    public void ProcessPayment(Guid orderId, Payment payment)
    {
        var order = this.repository.Find<Order>(orderId);

        order.Pay(payment);

        this.repository.Save(order);
    }
}

Now we realize that for unit tests to actually go against the actual real repository (i.e. a database) would be pretty slow and inefficient: we’d have to drop/clean the DB for every test run, etc. Unnecessary complication (not that you don’t need to have *integration* tests that DO run against the real DB, though). So we go ahead and make an interface out of the dependency (the repository in this case), so that we can completely replace its implementation in the tests:

public class OrderProcessor
{
    private IRepository repository;

    public OrderProcessor(IRepository repository)
    {
        this.repository = repository;
    }

    public void ProcessPayment(Guid orderId, Payment payment)
    {
        var order = this.repository.Find<Order>(orderId);

        order.Pay(payment);

        this.repository.Save(order);
    }
}

Let’s not forget WHY we did all this: just so the behavior we’re creating can be easily tested, that’s all. It was never our goal to dynamically replace the repository, make it configurable externally or whatever. That’s NOT the point of the refactoring.

So what do you do when the need comes along to use some runtime framework (i.e. ASP.NET MVC, WCF, etc.) that by default expect your component to have a default parameterless constructor? (say this processor is an MVC controller or a web service). Well, it’s pretty damn easy, you just add a default ctor with the default implementation you know is the only one you have and will use at runtime!

public class OrderProcessor
{
    private IRepository repository;

    public OrderProcessor()
        : this(new OrmRepository())
    {
    }

    public OrderProcessor(IRepository repository)
    {
        this.repository = repository;
    }

    public void ProcessPayment(Guid orderId, Payment payment)
    {
        var order = this.repository.Find<Order>(orderId);

        order.Pay(payment);

        this.repository.Save(order);
    }
}

And that’s IT. What? You thought at this point you NEEDED to choose an IoC container from the myriad available, hook up a controller/instance factory on the runtime MVC/WCF, etc.?? NO, you DON’T.

An IoC container WILL help if you have complex dependency graphs to instantiate (in your default constructor) or you have truly pluggable components (i.e. you want to allow a component to be picked up automatically at runtime from some binary if it’s in a folder, etc.).

If you don’t, it’s perfectly fine to have a default constructor that is used at runtime and has a hardcoded instantiation of a dependency. It was never a requirement to make that thing configurable or dynamic. So don’t invent business requirements just ‘cause using an IoC container is fancier. As far as I’m concerned, you didn’t violate any sacred principle by having that default constructor in there.

If you were doing TDD (which you should) the process would be slightly different. Instead of refactoring to make it testable, you’d have the constructor receiving the IRepository right from the beginning. But the end result would be the same: just add a default ctor for the runtime framework to use and move on.

That said, an IoC container and a mocking framework are my first two choices when doing File | New Project . I know I’ll need them for anything non-trivial.

In my previous post I showed how you can evolve the way you code your domain objects (or entities) so that they can benefit from the Event Sourcing pattern, and I also showed that it’s pretty simple at its core. That post ended up being a little disconnected from the one where I show how do to cool analysis based on those events. It was on purpose, as I needed to introduce another concept, and the post was getting too big already .

Lets recap briefly what happens on a domain object when we invoke an operation:

So after we invoked Move(), calling GetEvents() on the object would give us the CustomerMoved event data class that was the result of the operation. Pushing this event through the event stream manually is pretty straightforward:

var stream = new EventStream();

// print to the console every time a customer
// changes his address
stream.Of<CustomerMoved>().Subscribe(x => Console.WriteLine("Customer has moved to a new address: {0}", x.NewAddress));

var customer = new Customer(1); // load somehow
customer.Move("999 NE 9TH ST, Redmond, WA");

foreach (var @event in customer.GetEvents())
{
    stream.Push(@event);
}

The next important thing as mentioned by Folwer is that events are persisted somehow, and never change, ever. They are the definite and authoritative source of truth about what happened to your system. And you can perform analysis on that stream at any point in time in the future, even for events that happened long ago. This is very valuable to business: being able to derive new conclusions and trends retroactively, from day one of the system. It’s a very easy sell. So let’s get on to define the simplest possible interface for an event store.

The DomainObject

The domain object base class from my previous post needs to evolve now, so that it’s more flexible. First, we have no way of knowing what type of object identifiers developers will prefer. So we can just make that a generic TObjectId argument. Ditto for the base type for events: maybe you want to enforce they are all EventArgs-derived, or they all implement a certain interface (i.e. ITimestamped?), and so on. So we make that a generic parameter as well:

abstract partial class DomainObject<TObjectId, TBaseEvent>
{
    private Dictionary<Type, Action<TBaseEvent>> handlers = new Dictionary<Type, Action<TBaseEvent>>();
    private List<TBaseEvent> events = new List<TBaseEvent>();

    protected DomainObject()
    {
    }

    public virtual TObjectId Id { get; set; }

    public virtual void AcceptEvents()
    {
        this.events.Clear();
    }

    public virtual IEnumerable<TBaseEvent> GetEvents()
    {
        return this.events.AsReadOnly();
    }

    protected virtual void Handles<TEvent>(Action<TEvent> handler)
        where TEvent : TBaseEvent
    {
        this.handlers.Add(typeof(TEvent), @event => handler((TEvent)@event));
    }

    protected void Load(IEnumerable<TBaseEvent> events)
    {
        foreach (var args in events)
        {
            var handler = default(Action<TBaseEvent>);
            if (this.handlers.TryGetValue(args.GetType(), out handler))
                handler.Invoke(args);
        }
    }

    protected virtual void Apply<TEvent>(TEvent @event)
        where TEvent : TBaseEvent
    {
        var handler = default(Action<TBaseEvent>);
        if (this.handlers.TryGetValue(@event.GetType(), out handler))
            handler.Invoke(@event);

        this.events.Add(@event);
    }
}

The first thing you’d do in a project using that base class, is “fix” the base class type parameters for the ones you’ll use for your entire domain model, like:

abstract class DomainObject : DomainObject<Guid, EventArgs>
{
}

So from your domain you don’t have to repeat those generic parameters all over the place. It would make things easier if you decide to change the type of either the identifier or the event data base class.

The Event Store

An event store has two core responsibilities: save a bunch of events produced by a domain object (maybe in a single "transaction", if we adhere to the DDD principle that a single so-called aggregate root defines the consistency boundary for a domain operation), and allow minimal querying to retrieve the events that apply to a given object, and within a range of time (to allow replaying an object to a previous state) so that we can load it as it was at a certain point in time.

For saving, we could model the API in a few different ways: pass in the list of events, or each event individually, or the entire domain object. I chose the latter because it allows the implementations to decide how they will handle consistency and transactions for the whole set of events raised by the domain object, which may be a DDD aggregate root if you design it that way. But it’s not restrictive in any way, as you can still design things differently.

The store interface will use the TObjectId type for querying the events for a specific object instance.

partial interface IEventStore<TObjectId, TBaseEvent>
{
    void SaveChanges(DomainObject<TObjectId, TBaseEvent> entity);

    IEnumerable<TBaseEvent> Query(EventQueryCriteria<TObjectId> criteria);
}

For the query, I provided a simple query object style pattern that store implementations can use to issue the actual underlying query. We basically want to be able to load events for a specific object instance, for objects of a given type (maybe, like "give me all Published events of all products", for specific event types (i.e. LoginFailure) and all of that within certain time ranges:

partial class EventQueryCriteria<TObjectId>
{
    public EventQueryCriteria()
    {
        this.ObjectInstances = new List<ObjectFilter>();
        this.ObjectTypes = new List<Type>();
        this.EventTypes = new List<Type>();
    }

    public List<ObjectFilter> ObjectInstances { get; private set; }
    public List<Type> ObjectTypes { get; private set; }
    public List<Type> EventTypes { get; private set; }

    public DateTime? Since { get; set; }
    public DateTime? Until { get; set; }
    public bool IsExclusiveRange { get; set; }

    public class ObjectFilter
    {
        public ObjectFilter(Type objectType, TObjectId objectId)
        {
            this.ObjectType = objectType;
            this.ObjectId = objectId;
        }

        public Type ObjectType { get; private set; }
        public TObjectId ObjectId { get; private set; }
    }
}

Just a plain DTO of the query information. The nice thing about this is that I can provide a fluent API over the store interface, like so:

var store = new EventStore(...);

var query = store
    .Query()
    .For<Product>()
    .Since(new DateTime(2010, 1, 1))
    .OfType<Published>();

var results = query.Execute();

The query.Execute method simply calls Query(criteria) on the underlying store . Needless to say, not all stores need to implement all the query behavior. You’ll use what you need. I just put in the criteria I thought would be useful against an event store (things like being able to query by event type regardless of object instance, or all events for all objects of a given type, are useful in some scenarios we’ll see later, but aren’t common in other event store implementations).

To make things even simpler, I’ve created a separate nuget package that provides the necessary LINQ expression building so that implementing a store over an underlying IQueryable storage is trivial. But again, being a separate package means you don’t have to use it or that your underlying storage has to be an IQueryable of some sort. And that’s about it for the store API itself.

I currently have an Entity Framework-based store, an in-memory store (useful for tests, for example) and a sample file system based one. Being NETFx packages, they are all provided as source code (few lines each), so building a new store based on that source should be pretty straightforward against almost any store. I may include more store implementations in the future.

Some might say that I’ve gone too far with the event store querying capabilities. I believe that the basic querying I’ve put in makes it much more useful in its own right, rather than having to resort to full CQRS to perform simple ad-hoc querying like “how many new customers have registered last month?” (store .Query().OfType<CustomerRegistered>().Since(DateTime.Now.Substract(TimeSpan.FromDays(30))) and the like. Once you have the domain raising all sort of interesting events, business owners will surely want to be able to perform various querying over that data, and there’s no reason why we wouldn’t want to leverage existing technology that solves that easily (i.e. Linq to data in .NET).

Of course, loading a given domain object state up to a certain date is pretty simple too:

var events = store.Query()
    .For<Customer>(customerId)
    .Until(DateTime.Now.Substract(TimeSpan.FromDays(30)))
    .Execute();

var customerAsOfLastMonth = new Customer(events);

This type of querying capability on top of the basic event stream that your “empowered” domain model starts populating is extremely easy to sell to stakeholders. And I believe it’s entirely additive on top of whatever modeling and persistence strategy you’re currently using. This is not the prevalent criteria among CQRS/ES practitioners, but I think it’s a pragmatic approach that can quickly bring real benefits in terms of business value and intelligence without having to do anything significantly different than what you’re already doing.

I’ll explore more of this smooth evolution path in my next post. Stay tunned.

public class SystemClock : IClock
{
    private SystemClock() { }

    static SystemClock()
    {
        Instance = new SystemClock();
    }

    public static IClock Instance { get; private set; }
}

Fairly easy. Problem is, of course that there’s no way you can test a class that uses this singleton now. The easy thing that you might be tempted to do is to just make the setter internal and starting replacing the singleton clock with mocks of it. Problem is, as you may have guessed, that now the tests cannot be run in multiple threads simultaneously. You have made no provisions for shielding changes across threads, so if one test setups up the singleton with a mock with certain values, and another goes and changes it before the asserts get through, you’ll be seeing intermittent failures on random tests when run together, but no single failure when run individually.

Being such a common problem, the .NET framework provides a few ways to work around that, via a mechanism called Thread Local Storage (or TLS). Joe Albahari provides a great summary of the available options, so make sure you read that link. In summary, they are:

• Mark a static backing variable with [ThreadStatic] attribute:
  

  public class SystemClock : IClock
  {
      [ThreadStatic]
      private static IClock instance = new SystemClock();
  
      private SystemClock() { }
  
      public static IClock Instance
      {
          get { return instance; }
          internal set { instance = value; }
      }
  }
  

• Use ThreadLocal<T> instead for the private field:
  

  public class SystemClock : IClock
  {
      private static ThreadLocal<IClock> instance = new ThreadLocal<T>(() => new SystemClock());
  
      private SystemClock() { }
  
      public static IClock Instance
      {
          get { return instance.Value; }
          internal set { instance.Value = value; }
      }
  }
  

• Use Thread.SetData/GetData to hold the state:
  

  public class SystemClock : IClock
  {
      private static readonly LocalDataStoreSlot slot = Thread.AllocateDataSlot();
  
      private SystemClock() { }
  
      public static IClock Instance
      {
          get
          {
              var value = (IClock)Thread.GetData(slot);
              // Lazy init first time for this thread.
              if (value == null)
              {
                  value = new SystemClock();
                  Thread.SetData(slot, value);
              }
  
              return value;
          }
          internal set { Thread.SetData(slot, value); }
      }
  }

These options have slightly different performance characteristics (in my tests, ThreadStatic is fastest and the other two about 5x slower than that). However, they all share a very serious limitation, that was highlighted by Scott ages ago, back in 2003. They simply don’t work if what you need is per-context state, such as per web request, per test, essentially, per Call Context. Some call this the Ambient Context pattern, but its essence in .NET is the Logical Call Context, thoroughly dissected by Jeffrey Richter in a blog post.

Given its misleading MSDN summary, and its location with the namespace System.Runtime.Remoting.Messaging, it’s not surprising that developers quickly dismiss it as a valid (and much better as we’ll see!) alternative. A logical call context flows as a thread-like state bag, but it’s not limited to a single thread. In fact, even the new threading Tasks library honors this capability, and the most prominent use of this in .NET is in WCF E2E Tracing, which uses the CorrelationManager.ActivityId, which is persisted in the logical call context and flows even across AppDomains.

You basically use CallContext.LogicalGetData and LogicalSetData instead of the Thread.SetData/GetData from the example above. It is, however, a bit cumbersome, and I just wish we had something like ThreadLocal<T> to leverage for this “smart singleton” (or “ambient singleton”) capability.

Enter the NETFx AmbientSingleton class, which gives you just that :

public class SystemClock : IClock
{
    private static readonly AmbientSingleton<IClock> instance = new AmbientSingleton<IClock>(() => new SystemClock());

    private SystemClock() { }

    public static IClock Instance
    {
        get { return instance.Value; }
        internal set { instance.Value = value; }
    }
}

It is safe to set the value of the singleton in multiple threads simultaneously, and the value you set will be preserved in the entire call chain, even if the test or code under test spawns new threads via the thread pool or the task pool (which ultimately also uses the thread pool by default).

There is also a static AmbientSingleton.Create factory method with a couple overloads, to cut on the generic parameters noise.

The entire source for the class is very straightforward, as you’d expect:

static partial class AmbientSingleton
{
    public static AmbientSingleton<T> Create<T>(T defaultValue)
    {
        return new AmbientSingleton<T>(defaultValue);
    }

    public static AmbientSingleton<T> Create<T>(Func<T> defaultValueFactory)
    {
        return new AmbientSingleton<T>(defaultValueFactory);
    }
}

partial class AmbientSingleton<T>
{
    private string slotName = Guid.NewGuid().ToString();
    private Lazy<T> defaultValue;

    /// </summary>
    public AmbientSingleton()
        : this(() => default(T))
    {
    }

    public AmbientSingleton(T defaultValue)
        : this(() => defaultValue)
    {
    }

    public AmbientSingleton(Func<T> defaultValueFactory)
    {
        Guard.NotNull(() => defaultValueFactory, defaultValueFactory);

        this.defaultValue = new Lazy<T>(defaultValueFactory);
    }

    public T Value
    {
        get
        {
            var contextValue = CallContext.LogicalGetData(this.slotName);
            if (contextValue != null)
                return (T)contextValue;

            return this.defaultValue.Value;
        }
        set
        {
            CallContext.LogicalSetData(this.slotName, value);
        }
    }
}

As you can see, the Ambient Singleton behaves like a regular singleton, without the overhead of per-thread initialization, when it’s not needed. This is another drawback of the TLS approaches: if the object initialization is expensive, you’ll be paying for that once per thread. In the ambient singleton, however, only when a particular call context requires a different value for the singleton, the added behavior kicks in. In my tests this approach is the closest to the speed of [ThreadStatic], measuring only about 1.8x the ThreadStatic approach (compared with 5x for the ThreadLocal<T> and Thread data). All in all, a very compelling way of implementing singletons, when they are unavoidable (although you could say there’s always another way of doing it , but that’s another post).

You can install the nuget package to get the source AmbientSingleton<T> class, which is partial and defaults to internal, as you’d typically not expose it as a public type in your libraries, and is rather an internal implementation detail of your singletons. You can of course create another partial of it and make it public if you wish. It’s fully documented, and lives in the System namespace.

In order to keep your code coverage goals, you can also install the xUnit tests which provide 100% coverage for this source.

I realized that there seems to be quite some interest in the event  (or message) bus pattern as an application architecture pattern and not necessarily in the usual enterprise integration style. This means that you leverage the concept of an event bus for internal application decoupling (along the lines of an Event Collaboration), and not for integration with external systems. The difference is that everything happens in-memory, there is no intermediate persistent message queue, there are not message/event routers, partition, scalability requirements or anything like that. It’s a very simple way to make your components more loosely coupled.

In this post I’ll introduce a minor tweak to the original implementation of an event stream (I wanted to remove the Bus word from it as it confuses people that think it’s an enterprise style message bus) to make it more useful and general purpose.

To recap: the event stream is consumed by subscribers by simply subscribing to the desired event type:

var subscription = eventStream.Of<ProductPurchased>().Subscribe(….)

Or by performing a more complicated reactive query over the events:

var query =
    from discharged in events.Of<PatientLeftHospital>()
    from admitted in events.Of<PatientEnteredHospital>()
    where
        admitted.PatientId == discharged.PatientId &&
        (admitted.When - discharged.When).Days < 5
    select admitted;

var subscription = query.Subscribe(...)

My initial implementation would only invoke subscribers that register for the specific event being pushed through the stream:

partial class EventStream : IEventStream
{
    private ConcurrentDictionary<Type, object> subjects = new ConcurrentDictionary<Type, object>();

    public void Push<TEvent>(TEvent @event)
    {
        Guard.NotNull(() => @event, @event);

        var subject = this.subjects.Find(@event.GetType()) as Subject<TEvent>;
        if (subject != null)
            subject.OnNext(@event);
    }

    public IObservable<TEvent> Of<TEvent>()
    {
        return (IObservable<TEvent>)subjects.GetOrAdd(typeof(TEvent), type => new Subject<TEvent>());
    }
}

The Find extension method on ConcurrentDictionary simply does a TryGetValue on it and returns null if not found. We need to be smarter there to make this event stream more useful.

It’s probably that we’ll want to subscribe to more generic events (say for tracing purposes, for some global statistics, etc.), so you should be able to subscribe to (say) EventArgs and get all events that derive from it. Or do it based on interfaces, etc.

The change to generalize it is pretty simple too: we just make the Push method look for all subjects that have compatible event types:

public void Push<TEvent>(TEvent @event)
{
    Guard.NotNull(() => @event, @event);

    var eventType = @event.GetType();

    var compatible = subjects.Keys
        .Where(subjectEventType => subjectEventType.IsAssignableFrom(eventType))
        .Select(subjectEventType => subjects[subjectEventType]);

    foreach (dynamic subject in compatible)
    {
        subject.OnNext((dynamic)@event);
    }
}

We cast the subjects from object to dynamic so that we can do a dynamic invocation, because we don’t have a common interface for all. They all implement ISubject<T>. We also need to make the event itself dynamic, so that the runtime will pick the right method signature given both the subject type and the event type (might involve covariant cast, etc.).

In my opinion, the coolest part of having this type of event bus is that you can now layer on top the concept of schedulers (i.e. introduce async event listeners, or even create your own custom scheduler and perform crazy things like out of process queue-based events if you wanted) with no effort and keeping the same simple public interface.

Both the IEventStream and EventStream implementation are very straightforward and simple. I have put them together as source code NETFx nugets so you can get any updates to this post or future posts concerning these classes in the future. They are separate because in your application you may have a separate assembly for all your interfaces and separate ones for the implementations. In that case, you’ll install the interface nuget in the former, and the other in one of the implementation ones. For convenience, I also made an aggregated package that installs both interface and implementation on the same project. To make either the interface or the implementation public (they are both partial internal by default, to avoid increasing your API surface unnecessarily), you just add a partial declaration marking them public. The interface nuget even comes with a Visibility.cs file which you can just uncomment to get make the interface public:

// In order to make types introduced by this package public
// uncomment the following:

//namespace System.Reactive
//{
//    public partial interface IEventStream { }
//}

Enjoy!

public class Patient
{
    public DateTimeOffset? AdmittedDate { get; private set; }
    public bool IsInHospital { get; private set; }

    public void Admit(DateTimeOffset when)
    {
        if (this.IsInHospital)
            throw new InvalidOperationException("Already in hospital!");

        this.IsInHospital = true;
        this.AdmittedDate = when;
    }
}

The domain object method typically does some precondition validation (like the one above, the patient can’t be admitted twice), then mutates the state as needed. At some point the resulting object state will be persisted somehow, but it’s a good goal to have persistence ignorant entities, as you probably know by now .

If we now want to let other components know whenever a patient is admitted, we can just add a .NET event, like so:

public class Patient
{
    public event EventHandler<PatientAdmitted> Admitted = (sender, args) => { };

    //...

    public void Admit(DateTimeOffset when)
    {
        //...
        this.OnAdmitted();
    }

    private void OnAdmitted()
    {
        this.Admitted(this, new PatientAdmitted(this.AdmittedDate.Value));
    }
}

public class PatientAdmitted : EventArgs
{
    public PatientAdmitted(DateTimeOffset when)
    {
      this.When = when;
    }

    public DateTimeOffset When { get; set; }
}

From the domain public method, we just raise the event when we’re done mutating state, and this is typical practice in .NET.

Note: I have initialized the event with a non-null initializer lambda, (sender, args) => { }, and that means the event will never be null, so I can avoid the null check in the OnAdmitted method. The overhead is negligible compared to the increased readability and simplicity. I’ve been using this trick forever, and I always find it weird that developers don’t use it everywhere since we have lambdas…

Now, in order to achieve the kind of analysis that I showed in my previous post, we need a way to grab ALL events that have been raised by any domain object, so as to publish them for analysis. Someone could still hook to our .NET event, but it would be cumbersome to have to do that in a generic fashion, using reflection, for all events of all domain objects we instantiate (not to mention it would be slow). If we think about the events, the actual interesting data about it is the event args class itself. The sender is always the same, the current object. So we could refactor a bit the code like so:

public void Admit(DateTimeOffset when)
{
    // ...
    this.OnAdmitted(new PatientAdmitted(this.AdmittedDate.Value));
}

private void OnAdmitted(PatientAdmitted args)
{
    this.Admitted(this, args);
}

So that now the OnAdmitted receives the actual event data instead. We still need a central way to track all raised event data for this object, so that we can do something like:

var patient = new Patient(); // load somehow
patient.Admit(DateTimeOffset.Now);

var events = patient.GetEvents();
// Publish events somehow somewhere

Let’s add a way to track the raised event data in a list that we can return later. We can do this by introducing a private Raise method that receives the event data, and the method to call to handle the actual event raising (our OnAdmitted method), which we can pass as an Action<T> delegate. When we introduce this method, the code above will change to:

public void Admit(DateTimeOffset when)
{
    // ...
    this.Raise(new PatientAdmitted(when), this.OnAdmitted);
}

private void OnAdmitted(PatientAdmitted args)
{
    this.Admitted(this, args);
}

The Raise implementation just adds the raised event data to a list:

private List<EventArgs> events = new List<EventArgs>();

private void Raise<TEvent>(TEvent args, Action<TEvent> handler)
    where TEvent : EventArgs
{
    this.events.Add(args);
    handler(args);
}

public IEnumerable GetEvents()
{
    return this.events.AsReadOnly();
}

We could probably say we’re done, but we’ll go a bit further. How do you know up-front which events are interesting to raise and which aren’t? How can you possibly foresee the business needs in the future? What if you also want to do analysis of how many new patients you’re receiving vs admission of existing patients? What if you now need to report on the frequency patients get certain symptoms? Or how frequent they move, and to which neighbors, and so on? In the end, it might be that some day, you need to do analysis on ANY state changes in the system. What if we “forced” ourselves to ensure that ALL state changes have a corresponding event associated with them?

One easy way to do that would be to refactor a little bit the code above, and perform the state changes always in the private event handler, instead of the public domain method:

public void Admit(DateTimeOffset when)
{
    if (this.IsInHospital)
        throw new InvalidOperationException("Already in hospital!");

    this.Raise(new PatientAdmitted(when), this.OnAdmitted);
}

private void OnAdmitted(PatientAdmitted args)
{
    this.IsInHospital = true;
    this.AdmittedDate = args.When;

    this.Admitted(this, args);
}

The change seems minor, but it has profound implications as we’ll see shortly. First and foremost, if you force yourself to do every state change like this, you can be sure you’ll have a very rich set of domain events to perform analysis from in the future. Not only that, but you’re forcing yourself to put ALL the data you need to perform the state changes IN the event data class itself. Seems like an obvious thing to do. Let’s add one more domain method, which is to assign a bed to the patient:

public event EventHandler<BedAssigned> BedAssigned = (sender, args) => { };

public int Bed { get; private set; }

public void AssignBed(int bed)
{    if (!this.IsInHospital)        throw new InvalidOperationException("Patient must be in the hospital to assign a bed");
    if (bed < 0)
        throw new ArgumentException("Invalid bed number");

    this.Raise(new BedAssigned(bed), this.OnBedAssigned);
}

private void OnBedAssigned(BedAssigned args)
{
    this.Bed = args.Bed;

    this.BedAssigned(this, args);
}

Another minor thing we changed here: the concept of When things happen is key in any domain event. Events clearly have a When property pretty much always. In our first event, we passed the date as an argument to the Admit method, but assigning a bed would be no different, right? You’d soon realize that you’d be passing a date time to pretty much every method. But if you think about it, the actual domain state doesn’t necessarily need that piece of data. In the assign bed example, the domain class may just need to keep the current bed, but not necessarily when it was assigned. That might be something that analysis from the events needs. Ditto for other events. Forcing our domain to keep two properties (one for the actual data, another for the when it changed) seems unnatural and it’s something we don’t typically do, essentially because our domain objects have state that is current as of now. So in this case, I just moved the responsibility of knowing when an event happened to the event arguments class itself, and we free our domain from having to worry or pass that data over and over:

public class BedAssigned : EventArgs
{
    public BedAssigned() { }
    public BedAssigned(int bed)
    {
        this.Bed = bed;
        this.When = DateTimeOffset.Now;
    }

    public int Bed { get; set; }
    public DateTimeOffset When { get; set; }
}

The passing of time

We mentioned above that the domain objects represent state that is current as of now. If you think about the Patient.Bed property, its current value will change over time as the OnBedAssigned handler is called repeatedly over time. What if in addition to the GetEvents() method we also provided a Load(events) method that received events that we just want to apply to the object?

public void Load(IEnumerable<EventArgs> events)
{
    foreach (var args in events)
    {
        // OnAdmitted(args)
        // OnBedAssigned(args)
        // etc.
    }
}

Notice how moving the state changes from the public domain method into the event handler allows us to cause the state of the object to change by just loading (or applying) events to it. We can essentially change the concept of now for our domain objects! We can grab a set of events (say, until yesterday), load them into the object, and see what the state of the patient was as of yesterday. And if we were strictly following our pattern of making ALL state transitions in the private event handlers, we can be sure the object state will be exactly the same as it was yesterday. This is the manifestation of the apparently minor but profound change we did above when we moved the state change from the public method to the private event handler. We have replay capabilities now in our domain objects!

This is very useful capability that we gained with very little effort. So now we not only have business analytics capabilities built-in, but also historical replay for every entity we code this way. This is huge. But there’s even more, as we’ll see later.

Let’s first finish our implementation of the Load method: we need a way to know which handlers to call for which events, and we can do that by registering the mapping between event types and handler methods in the constructor:

public Patient()
{
    this.Handles<PatientAdmitted>(this.OnAdmitted);
    this.Handles<BedAssigned>(this.OnBedAssigned);
}

private Dictionary<Type, Action<EventArgs>> handlers = new Dictionary<Type, Action<EventArgs>>();

private void Handles<TEvent>(Action<TEvent> handler)
    where TEvent : EventArgs
{
    this.handlers.Add(typeof(TEvent), @event => handler((TEvent)@event));
}

public void Load(IEnumerable<EventArgs> events)
{
    foreach (var @event in events)
    {
        var handler = default(Action<EventArgs>);
        if (this.handlers.TryGetValue(@event.GetType(), out handler))
            handler(@event);
    }
}

The Handles method simply stores a delegate that knows how to call our handler. Our dictionary contains the event type –>Action map. The action has to be generic (can’t have a separate list for Action<PatientAdmitted>, another for Action<BedAssigned> and so on), so we just make the action receive the generic EventArgs type, which we just cast to the type we know it will have for our event handler:

this.handlers.Add(typeof(TEvent), @event => handler((TEvent)@event));

When the Load method finds an Action handler for a given event type, it will just call our lambda with no reflection involved. We’ll then cast from the generic base event data type the Load event passes us, down to the one the specific handler expects:

handler(@event) –>(calls our lambda in Handles)-> @event => handler((TEvent)@event))

With that in place, the following works perfectly:

var patient = new Patient(); // load somehow
patient.Admit();
patient.AssignBed(1);

// grab events as of now.
var yesterdayEvents = patient.GetEvents().ToList();

// Do something more with the patient.
patient.AssignBed(2);
patient.AssignBed(3);

// Later on, we want to see
// patient as it was yesterday.
var yesterdayPatient = new Patient();
yesterdayPatient.Load(yesterdayEvents);

Debug.Assert(yesterdayPatient.Bed == 1);

Note how depending on what events we load on the patient, we get the state currently reflecting as of that time. One thing you might have noticed at this point, is that as we’re loading events and calling the various OnXXX handlers, we’re also causing the corresponding .NET events to fire! That shouldn’t be the case, as the .NET events are the external notification that happens when the event was originally created. So it seems appropriate to move the raising of the .NET event to the domain method instead:

public void Admit()
{
    if (this.IsInHospital)
        throw new InvalidOperationException("Already in hospital!");

    var args = new PatientAdmitted();
    this.Raise(args, this.OnAdmitted);
    this.Admitted(this, args);
}

private void OnAdmitted(PatientAdmitted args)
{
    this.IsInHospital = true;
}

And it’s now pretty obvious that the Raise method is not actually raising anything, but actually applying the event data to the object. So we can rename that method now and call it Apply instead.

Now that we have the event type and handler map in place from the constructor we added, we can even simplify the way we raise events too. We had:

public void Admit()
{
    if (this.IsInHospital)
        throw new InvalidOperationException("Already in hospital!");

    this.Apply(new PatientAdmitted(), this.OnAdmitted);    this.Admitted(this, args);
}

But now we already know what handler to call for events of type PatientAdmitted (as demostrated when we loaded events), so the call should instead just be: Raise(new PatientAdmitted()):

private void Raise<TEvent>(TEvent args)
    where TEvent : EventArgs
{
    this.events.Add(args);

    var handler = default(Action<EventArgs>);
    if (this.handlers.TryGetValue(args.GetType(), out handler))
        handler(args);
}

And if we move all that generic code to a base class, we end up with a pretty straightforward way of implementing our domain classes:

public class Patient : DomainObject
{
    public event EventHandler<PatientAdmitted> Admitted = (sender, args) => { };
    public event EventHandler<BedAssigned> BedAssigned = (sender, args) => { };

    public Patient()
    {
        this.Handles<PatientAdmitted>(this.OnAdmitted);
        this.Handles<BedAssigned>(this.OnBedAssigned);
    }

    public int Bed { get; private set; }
    public bool IsInHospital { get; private set; }

    public void Admit()
    {
        if (this.IsInHospital)
            throw new InvalidOperationException("Already in hospital!");

        var args = new PatientAdmitted()
        this.Apply(args);
        this.Admitted(this, args);
    }

    public void AssignBed(int bed)
    {
        if (!this.IsInHospital)
            throw new InvalidOperationException("Patient must be in the hospital to assign a bed");
        if (bed < 0)
            throw new ArgumentException("Invalid bed number");

        var args = new BedAssigned(bed);
        this.Apply(args);
        this.BedAssigned(this, args);
    }

    private void OnBedAssigned(BedAssigned args)
    {
        this.Bed = args.Bed;
    }

    private void OnAdmitted(PatientAdmitted args)
    {
        this.IsInHospital = true;
    }
}

Note also that we wouldn’t typically want to allow our objects to be mutated by applying arbitrary events at arbitrary times (i.e. after performing operations on it), so we’d typically make the Load method protected on the base class, and expose two constructors for our objects instead:

private Patient()
{
    this.Handles<PatientCreated>(this.OnCreated);
    this.Handles<PatientAdmitted>(this.OnAdmitted);
    this.Handles<BedAssigned>(this.OnBedAssigned);
}

public Patient(int id)
    : this()
{
    if (id < 0)
      throw new ArgumentException("Invalid patient identifier");

    this.Apply(new PatientCreated(id));
}

public Patient(IEnumerable<EventArgs> events)
    : this()
{
    this.Load(events);
}

As true OO design mandates, our object cannot be constructed in an invalid state: you can either create a new patient (first time he comes in), with a valid identifier, or you create a patient by loading a set of events. Notice how both public constructors call the private parameterless constructor which hooks up the event-handler map. Also key is that even for the new patient creation constructor, we also follow the pattern we’ve explained: we don’t just blindly set the Id property. Instead, we validate the argument, apply a proper event data class, which in turn sets the Id:

private void OnCreated(PatientCreated args)
{
    this.Id = args.Id;
}

Another subtlety to notice, is that in this case we don’t expose a corresponding .NET event for the object creation event. The reason is quite obvious: nobody would be able to attach to the event before the object is constructed, at which point it would be too late to catch the event using plain .NET event handlers. Our mechanism to retrieve object events and push them to an event stream would still work, however. This highlights another important thing:

Raising a .NET event for a domain event is optional.

Given that you’re performing the analysis and storage of events (as we’ll see in my next post) using a different API than plain .NET event handlers (our current GetEvents() method), there’s no requirement that you expose your event data as .NET events at all. And if you’re not doing so, there’s not even a requirement that the event data classes derive from EventArgs either! It’s really up to you. 

And that, dear reader, is the essence of the Event Sourcing pattern. Nothing more, nothing less. As Folwer says:

The fundamental idea of Event Sourcing is that of ensuring every change to the state of an application is captured in an event object, and that these event objects are themselves stored in the sequence they were applied for the same lifetime as the application state itself.

And I’ll talk about the storage in my next post. To peek at what’s coming, you can install the Event Sourcing NETFx package, which includes the DomainObject base class we’ve been discussing in this post (and a bit more).

Stay tunned.

There is, however, one mainstream application of reactive extensions that seems to have been missed by most: business intelligence. Here’s one concrete example: pretty soon, hospitals will face penalties for patient readmission, so you need a way to get an alert whenever patients are readmitted before a certain elapsed time (say 5 days or whatever). Another one: you want to preventively block a user’s account after 5 consecutive login failures within a minute (looks like an automated attack), or shoot an sms to the support team when failure rates for your app go above 5 crashes a day, or keep a report of top trending products in a store, and so on.

The common theme across all those kinds of business queries is that they involve the concept of time passing and events happening (patients admitted and discharged from hospitals, users trying to log-in, an app crashing, a product being downloaded), things that the Reactive Extensions models as first class citizens. These events are not .NET events, but domain events, the representation of something meaningful that happened to your system.

And how would the query for readmitted patients look like? Pretty much like a SQL query would, actually:

var events = new EventStream();
var query =
    from discharged in events.Of<PatientLeftHospital>()
    from admitted in events.Of<PatientEnteredHospital>()
    where
        admitted.PatientId == discharged.PatientId &&
        (admitted.When - discharged.When).Days < 5
    select admitted;

Note how we’re joining the patient discharge events with the admission ones based on the patient id, and filtering those where the difference between a readmission event (that is, it’s When is greater than a previous discharge’s When) and a previous discharge is less than 5 days. Looks pretty darn easy to author and grasp.

The login failures one:

var query = events.Of<LoginFailure>()
    // Sliding windows 1' long, every 10''
    .Buffer(TimeSpan.FromMinutes(1), TimeSpan.FromSeconds(10), scheduler)
    // From all failure values
    .SelectMany(failures => failures
        // Group the failures by user
        .GroupBy(failure => failure.UserId)
        // Only grab those failures with more than 5 in the 1' window
        .Where(group => group.Count() >= 5)
        // Return the user id that failed to log in
        .Select(group => group.Key));

And the app crash one would be very similar to the one above. The most interesting ones are of course those that combine data from multiple events, like the hospital example.

The EventStream class is simply a pass-through of events that turns things that are pushed through it into observable streams of specific events. This allows the queries to receive just one dependency, the event stream, and grab the events they are interested in by using the Of<TEvent> method:

partial interface IEventStream
{
    void Push<TEvent>(TEvent @event);
    IObservable<TEvent> Of<TEvent>();
}

The implementation is surprisingly simple with Reactive Extensions:

partial class EventStream : IEventStream
{
    private ConcurrentDictionary<Type, object> subjects = new ConcurrentDictionary<Type, object>();

    public void Push<TEvent>(TEvent @event)
    {
        Guard.NotNull(() => @event, @event);

        var subject = this.subjects.Find(@event.GetType()) as Subject<TEvent>;
        if (subject != null)
            subject.OnNext(@event);
    }

    public IObservable<TEvent> Of<TEvent>()
    {
        return (IObservable<TEvent>)subjects.GetOrAdd(typeof(TEvent), type => new Subject<TEvent>());
    }
}

I’ve put this together as a NuGet for your convenience. I’ve also published a unit tests package for it, so you get the above examples to play.

This seems like a rather simple thing, and even one that isn’t so revolutionary by itself. Might seem like just an improved way to query a log, but in real-time. Like many things, the true power comes when it’s combined with other patterns, specifically Event Sourcing (ES), as I’ll explain in my next blog post. And that’s the reason behind the title’s prefix, a hint to Greg’s upcoming Event Centric book, which talks about the ES pattern (although I doubt it will mention how combining it with Rx makes for the killer business argument for adopting it).

Stay tunned!

[Update] The “surprisingly simple” implementation explained above is surprisingly limiting too . Namely: the subscriber has to use the exact same type as the publisher in order for a subscription to be called. In other words: no support for covariant subscriptions, subscriptions to interfaces implemented by the concrete events, etc. (i.e. the EventPattern<TEventArgs> from Rx wouldn’t work for subscriptions to the base EventPattern<EventArgs>). So I had to make it a bit more complicated to support everything the CLR supports in terms of assignable types. The updated nuget package contains the full implementation.

There’s a built-in mechanism for this that is being used in WinForms and WPF: the ISupportInitialize interface. The initialization code generated by both toolkits checks to determine if the object implements the interface. If it does, it will call BeginInit() before invoking all property setters, and EndInit() at the end. This provides a nice hook for validating all properties and maybe interrelated ones.

Adding this to the IL generated by the compiler for object initializers would make them immensely more useful. I’d be willing to replace many ctor overloads with properties if I had that hook, given the much more readable code that results from using object initializers.

Microsoft Connect site used to be the place where you suggested things. I did for this one, and Mads Torgersen, C# Language PM, liked the idea. But alas, they closed the bug as Won’t Fix back in 2008 (as it was way too late for C# 4.0/VS2008) and never reopened it. I cannot reopen it either now for consideration for C# 5.0. And it seems in the meantime, they changed their mind and now suggestions should go to a UserVoice site. Sigh.

So I basically cloned the suggestion in the new site. Please go vote to get support for ISupportInitialize on object initializers in C# 5.0!

To help you tell whether my evaluation is worth reading, these are the (music capable/usable) devices I own/owned and use/used actively:

1. iPod Touch (first gen)
2. iPad 1
3. Zune Player
4. T-Mobile G1
5. Google Nexus One
6. Galaxy Tab 7’’
7. Galaxy Tab 10.1
8. Windows 7 HTPC

And these are online music services I’ve used (either currently -soon to be dropped- or very recently). Note that they offer varying services and capabilities, so they cannot be compared easily, but they are all related to music, and I’m just noting the plus/minus I found for each:

1. Grooveshark Anywhere: $9 per month
   + Offline caching (per playlist or per song)
   + Playlists that can be made offline entirely
   + Android support
   - iPhone/iPod not supported (blame Steve)
   - Sound quality very disparate
   - Duplicate songs, albums, kinda messy
2. Zune Pass: $15 per month for unlimited downloads
   + 10 free songs to keep (plain mp3, no DRM)
   + Up to 5 devices simultaneously
   + Pretty extensive music catalog (far from everything, though)
   + Sleekest mobile and desktop app
   + Awesome music quality, even while streaming
   + Found good new bands from “Smart-DJ” mode (radio with a “seed” artist)
   - Microsoft-only
3. iTunes – No streaming
   - Sync with a freakin’ cable, etc.
   - Pay per song/album
   - Epic #fail.
   (The first two alone discouraged me enough that I never bought a single song through it. Yeah, there’s a beta 10.4 of “iTunes in the Cloud” now, which still doesn’t do streaming. Too little, way too late)
4. Amazon Cloud Player
   + Upload my existing songs
   + Nice Android app
   + Multiple (Android platform only currently ) devices supported
   + Amazon recommendation system behind your purchases
   - No radio mode
   - No subscription mode for unlimited streaming (have to buy songs/albums)
   - To sync my songs across devices, I have to upload to cloud and pay for storage
5. Google Music: haven’t used it yet, but looks to be more or less like Amazon’s (-recommendations)
6. Last.fm subscription: $3 per month
   + Multiple devices supported (even XBox!)
   - No offline support
   - No custom playlists that I could find

So I set out to try out for a month Spotify. Got a Premium account, and downloaded the desktop, Android and iPod clients. I hate iTunes with a passion, so I would have preferred a more creative desktop client than essentially a cleaned-up version of iTunes. I wish they copied Zune software instead which is truly gorgeous and (r?)evolutionary as a media player.

Now, here’s how you do sync in this age, Apple:

At no point, ever, you need to connect a cable between your computer and your device. Ever. Here I’m sync’ing for offline play on the laptop the most excelent Nightwish End of an Era CDs right off the cloud (I don’t own this album).

Here’s another view but now sync’ing to my Nexus One phone:

And now with ALL my current devices (except for the Zune) connected (couldn’t rename the Galaxy Tab 10.1 device, option appears greyed out ):

Truly amazing. Totally sold.

Needless to say, you can of course do everything you can do from the desktop client (except manage sync on other devices, AFAICS) from each mobile client (search, create playlists, cache for offline, etc.).

One thing I didn’t like is that you can only play on one device at a time. Starting on another pauses whichever other device is using the same username. I prefer the Zune’s approach of letting up to 5 simultaneous devices to be used. Imagine my wife is playing something on the HTPC for my kids and at the same time I’m working on my office. Can’t use my account on both. Means I have to pay more unnecessarily. Resorting to caching the music ahead of time and offlining one client or the other to avoid notifying Spotify and pause the other, is not going to work .

As a general purpose music player for my local files, it also looks pretty decent, so although I’m sure I’ll miss the desktop Zune software, I think I’m ready to let it go.