<p>Thus far in the series, the Vigil Journey project has been able to <a href="/posts/2016/user-can-create-new-patron/">create a patron</a>, <a href="/posts/2016/user-can-update-a-patron/">update a patron</a>, and have those redefined as "<a href="/posts/2016/patron-can-be-created-and-updated-again/">a patron can be created and updated</a>". However, as acknowledged in those posts, this was all smoke and mirrors. Nothing was being persisted, and once the unit tests were run, there was no lasting effect of the code. All of the tests passed and there were lots of pretty green check marks, but no residual digital substance. Additionally, there was no application that could be left running with which someone could interact.</p>
<p>I began getting antsy about needing to have some semblence of real progress. Something that I could launch and point to and say "see there; it works!" This was my primary motivator for quickly (and sloppily) writing the <a href="/posts/2017/illusions-of-queues-and-buses/"><code>SqlCommandQueue</code> and <code>SqlEventBus</code></a> classes. I wanted to be able to demonstrate <em>something</em>.</p>
<h2>Recent Observations</h2>
<p>While my initial instinct was to spin up a complete user interface for this; what better way to show progress than to open a web browser and display grid views and form fields, thought I. However, I also had grand schemes of building a full API for the UI to utilize. This kept my ambitions in check, and after researching for ways to directly interact with an API, allowing me to reach a more attainable goal. Thus, the next  layer of the project - which is to instantiate the <code>CreatePatron</code> command and pass it to an <code>ICommandQueue</code>. Utilizing my <code>SqlCommandQueue</code>, I could wire that to a database, which would handle persistence of <code>Command</code> objects, passing those to a <code>CommandHandler</code>. These would, in turn, generate events and put them on the <code>SqlEventBus</code>; which would call the appropriate <code>EventHandler</code> classes, and thus persist the changes to the relational database.</p>
<p>An unexpected (though, in hindsight, entirely predictable) revalation I had while adding this additional layer to the application is that each piece seems to have a higher cost to initialize the first proof of concept. When all I was looking for was the ability to <em>create a patron</em>, I could claim that "it works" when the unit test proved that a short piece of code did what it was supposed to do. The <code>PatronCommandHandler</code> class required no external libraries &#x26;emdash; in fact, going up the dependencie chain, <code>System</code> is the only required library because of <code>DateTime</code> and <code>Guid</code>. However, implementing even a cheap Command Queue or Event Bus requires the <code>EntityFrameworkCore</code> and <code>System.Linq</code> NuGet packages. Adding the ability to stand up even a small Rest API requires <code>Microsoft.AspNetCore</code>, <code>Microsoft.AspNetCore.Mvc</code>, <code>Microsoft.AspNetCore.Routing</code>, and if I want to use a webserver to host the code, then it requires bringing one or more of the <code>Microsoft.AspNetCore.Server</code> packages. There is a lot more experimentation, debugging, and unit testing required for each step. This is something that I'm going to have to keep in mind anytime I get the grand ambitions to tack on another layer to the application.</p>
<h2>ASP.NET Core MVC as an API</h2>
<p>Previous versions of ASP.NET MVC separated out the <code>Controller</code> base class from the WebAPI controller base class. With ASP.NET Core MVC, there is no difference between an API controller and a web controller. I see this as being a real advantage when it comes to migrating code that was all crammed together in a web application, when an easier way to manage it would be as two different applications. Since a core goal of this entire <em>Vigil Journey</em> is to separate responsibilities wherever possible, I like having the responsibility of user presentation being entirely separate from the responsibility of the command and query part of the workflow.</p>
<p>The <code>PatronController</code> is going to start as a simple controller that implements the four basic tenents of data: Create, Read, Update, Delete - or CRUD. Each action has a different Verb, Model, and return values.</p>
<p>|        | Http Verb | Model              | Success        | Failure              |
|--------|-----------|--------------------|----------------|----------------------|
| Create | Post      | CreatePatron       | Accepted (202) | BadRequest (400)     |
| Read   | Get       | PatronId           | Ok (200)       | NotFound (404)       |
| Update | Put       | UpdatePatronHeader | Accepted       | BadRequest, NotFound |
| Delete | Delete    | PatronId           | Accepted       | NotFound             |</p>
<pre><code class="language-csharp">using Microsoft.AspNetCore.Mvc;
using System;
using System.Linq;
using Vigil.Domain.Messaging;
using Vigil.Patrons.Commands;

namespace Vigil.WebApi.Controllers
{
    [Route("api/[controller]")]
    public class PatronController : Controller
    {
        private readonly ICommandQueue commandQueue;
        private readonly Func&#x3C;VigilWebContext> contextFactory;

        public PatronController(ICommandQueue commandQueue,
            Func&#x3C;VigilWebContext> contextFactory)
        {
            this.commandQueue = commandQueue;
            this.contextFactory = contextFactory;
        }

        [HttpGet]
        public IActionResult Get()
        {
            using (var context = contextFactory())
            {
                var patrons = context.Patrons.Where(p => p.DeletedOn == null);
                return Ok(patrons);
            }
        }

        [HttpGet("{id}")]
        public IActionResult Get(Guid id)
        {
            using (var context = contextFactory())
            {
                var patron = context.Patrons.Find(id);
                if (patron == null)
                {
                    return NotFound();
                }
                else
                {
                    return Ok(patron);
                }
            }
        }

        [HttpPost]
        public IActionResult Create([FromBody]CreatePatron command)
        {
            if (command == null || !ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }
            else
            {
                commandQueue.Publish(command);
                return Accepted(
                    Url.Action(nameof(Get), new { id = command.PatronId })
                );
            }
        }

        [HttpPut("{id}")]
        public IActionResult UpdateHeader(Guid id,
            [Bind(nameof(UpdatePatronHeader.DisplayName),
                  nameof(UpdatePatronHeader.IsAnonymous),
                  nameof(UpdatePatronHeader.PatronType))] UpdatePatronHeader command)
        {
            if (command == null || !ModelState.IsValid)
            {
                return BadRequest(command);
            }
            using (var context = contextFactory())
            {
                if (context.Patrons.Find(id) == null)
                {
                    command.PatronId = id;
                    commandQueue.Publish(command);
                    return Accepted(Url.Action(nameof(Get), new {
                        id = command.PatronId
                    }));
                }
                else
                {
                    return NotFound(id);
                }
            }
        }

        [HttpDelete("{id}")]
        public IActionResult Delete(Guid id)
        {
            using (var context = contextFactory())
            {
                if (context.Patrons.Any(p => p.Id == id))
                {
                    commandQueue.Publish(
                        new DeletePatron(User.Identity.Name, DateTime.Now)
                        {
                            PatronId = id
                        }
                    );
                    return Accepted();
                }
                else
                {
                    return NotFound(id);
                }
            }
        }
    }
}
</code></pre>
<h2>Unit Tests before Functional testing</h2>
<p>Before I attempted to launch Kestrel or IIS Integration, I needed to write a Unit Test. I got a little ahead of myself on this one. I wrote this first unit test, and then went off on a coding tangent, which caused a massive refactoring to occur. The unit tests never got completed for this version of the <code>PatronController</code>, but it does provide a quick overview as to how I handled the constructor requirements of the controller and checks for the return value.</p>
<pre><code class="language-csharp">using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Moq;
using System;
using Vigil.Domain.Messaging;
using Xunit;

namespace Vigil.WebApi.Controllers
{
    public class PatronControllerTest
    {
        public readonly ICommandQueue cmdQueue = Mock.Of&#x3C;ICommandQueue>();
        public readonly Func&#x3C;VigilWebContext> Context;

        public PatronControllerTest()
        {
            var serviceProvider = new ServiceCollection()
                .AddEntityFrameworkInMemoryDatabase()
                .BuildServiceProvider();
            var builder = new DbContextOptionsBuilder&#x3C;VigilWebContext>()
                .UseInMemoryDatabase(databaseName: "TestHelper")
                .UseInternalServiceProvider(serviceProvider);

            Context = () => new VigilWebContext(builder.Options);
        }

        [Fact]
        public void Get_Returns_EmptyCollection_WhenThereAreNoPatrons()
        {
            var controller = new PatronController(cmdQueue, Context);

            var result = controller.Get() as OkObjectResult;

            Assert.NotNull(result);
            Assert.NotNull(result.Value);
        }
    }
}
</code></pre>
<p>If nothing else, this post reinforced that I need to write posts more often, and do a better job of isolating concepts into branches and merging small amounts of code at a time.</p>


Introducing Vigil Web API

<p>There are many solutions on the market (including <a href="https://github.com/zeromq/netmq">free</a> <a href="https://github.com/pardahlman/RawRabbit">open</a> <a href="https://www.rabbitmq.com/dotnet.html">source</a>) for creating both message queues and event buses. However, for example purposes - and as a simple <em>proof of concept</em> - I just wanted a simple way to store the contents of a <code>Command</code>, run the <code>CommandHandler</code>, receive <code>Event</code> objects, call the <code>EventHandler</code> actions, and save all of the results. Everything runs synchronously and there are no retry policies, topics, or request/reply patterns. It is a simple, nearly useless set of code - but it serves its very specific purpose.</p>
<h2>SqlCommandQueue</h2>
<p>Calling this a "queue" is a complete misnomer, since there is no actual queuing of the commands. All this does is persist the command to the database, call the command handler, and then declare the command as handled.</p>
<pre><code class="language-csharp">using Microsoft.Extensions.DependencyInjection;
using Newtonsoft.Json;
using System;
using Vigil.Domain.Messaging;

namespace Vigil.Sql
{
    public class SqlCommandQueue : ICommandQueue
    {
        private readonly IServiceProvider _serviceProvider;
        private readonly Func&#x3C;SqlMessageDbContext> _dbFactory;

        public SqlCommandQueue(IServiceProvider serviceProvider,
            Func&#x3C;SqlMessageDbContext> dbFactory)
        {
            _serviceProvider = serviceProvider;
            _dbFactory = dbFactory;
        }

        public void Publish&#x3C;TCommand>(TCommand command) where TCommand : ICommand
        {
            using (SqlMessageDbContext context = _dbFactory())
            {
                var newCmd = new Command()
                {
                    GeneratedBy = command.GeneratedBy,
                    GeneratedOn = command.GeneratedOn,
                    Id = command.Id,
                    SerializedCommand = JsonConvert.SerializeObject(command),
                    CommandType = typeof(TCommand).AssemblyQualifiedName,
                    DispatchedOn = DateTime.UtcNow
                };
                context.Commands.Add(newCmd);
                context.SaveChanges();
            }

            var handler = _serviceProvider
                .GetRequiredService&#x3C;ICommandHandler&#x3C;TCommand>>();
            handler.Handle(command);

            using (SqlMessageDbContext context = _dbFactory())
            {
                var cmd = context.Commands.Find(command.Id);
                cmd.HandledOn = DateTime.UtcNow;
                context.SaveChanges();
            }
        }
    }
}
</code></pre>
<p>A bit of magic happens on lines 28 and 29 — in order to retrieve an arbitrary object for later consumption, the command needs to be serialized. Additionally, to allow it to be deserialized later, the full AQN of the class should be kept handy. The actual work is done in lines 36 and 37, which get the command handler that has already been globally registered, and then calls the <code>Handle</code> method. Since nothing happens asynchronously, the queue is fully able to assume that returning control back to it means the command has been handled. Updating the <code>HandleOn</code> property closes that loop.</p>
<h2>SqlEventBus</h2>
<p>Just as the "Command Queue" isn't a queue, the <code>SqlEventBus</code> isn't a bus, or a topic, or any kind of fancy messaging. What does it do? It persists the event to storage (a database), gets and calls all of the event handlers, then marks the persisted event as handled. The code looks quite similar to the <code>SqlCommandQueue</code>.</p>
<pre><code class="language-csharp">using Microsoft.Extensions.DependencyInjection;
using Newtonsoft.Json;
using System;
using Vigil.Domain.Messaging;

namespace Vigil.Sql
{
    public class SqlEventBus : IEventBus
    {
        private readonly IServiceProvider _serviceProvider;
        private readonly Func&#x3C;SqlMessageDbContext> _dbFactory;


        public SqlEventBus(IServiceProvider serviceProvider,
            Func&#x3C;SqlMessageDbContext> dbFactory)
        {
            _serviceProvider = serviceProvider;
            _dbFactory = dbFactory;
        }

        public void Publish&#x3C;TEvent>(TEvent evnt) where TEvent : IEvent
        {
            using (SqlMessageDbContext context = _dbFactory())
            {
                var newEvnt = new Event()
                {
                    GeneratedBy = evnt.GeneratedBy,
                    GeneratedOn = evnt.GeneratedOn,
                    Id = evnt.Id,
                    SourceId = evnt.SourceId,
                    EventType = typeof(TEvent).AssemblyQualifiedName,
                    SerializedEvent = JsonConvert.SerializeObject(evnt),
                    DispatchedOn = DateTime.UtcNow
                };
                context.Events.Add(newEvnt);
                context.SaveChanges();
            }

            var handlers = _serviceProvider.GetServices&#x3C;IEventHandler&#x3C;TEvent>>();
            foreach(IEventHandler&#x3C;TEvent> handler in handlers)
            {
                handler.Handle(evnt);
            }

            using (SqlMessageDbContext context = _dbFactory())
            {
                var handled = context.Events.Find(evnt.Id);
                handled.HandledOn = DateTime.UtcNow;
                context.SaveChanges();
            }
        }
    }
}
</code></pre>
<p>The unit tests are very simple (so simple that I haven't even created them - and probably won't). It would just be a set of tests that verify it is doing exactly what I've told it to do. Since this code is only a demostration, and not meant for any kind of actual use, I'm not bother to fully unit test it. I doubt that this code will survive past the point where I have a real queue and bus living up in Azure.</p>
<p>Two other pieces that I did add, that may be something that carries into an Azure implementation. I created new <code>Command</code> and <code>Event</code> objects that are just POCO wrappers for the <code>Vigil.Domain.Command</code> and <code>Vigil.Domain.Event</code> entities that are being persisted. One little handy thing that I did create, solely for debugging, is a <code>SqlViewerController</code> that sets up a <em>/sql/</em> route with a way to view all persisted commands, all persisted events, and the ability to test rehydrating a <code>Patron</code>. It has been useful to have when I was testing out the <code>Vigil.WebApi</code> project — more on that in another post.</p>


Illusions of Queues and Buses

<p>There are two ways to retrieve the current values associated with an entity. The canonical source is the collection of events that describe how an entity came into existance and then was affected over time. The standard term for this seems to be "hydrating" the entity. Once the current state of the entity is found, it can then be persisted to a different medium for easier access. In the example of a <code>Patron</code>, there are few circumstances where the entire history of the entity is needed. Instead, most requests for the information will only be looking for the most current iteration - which is found in a snapshot database. One of the first challenges that I faced when building this initial prototype was proving that my code could rehydrate a <code>Patron</code> from only a list of events.</p>
<p>Looking into the details of what the process is when hydrating a <code>Patron</code>, the best place to start is with the constructor. The prelude to calling the constructor, of course, is that something has gone and fetched a collection of <code>IVersionedEvent</code> entities with a given <code>PatronId</code>.</p>
<pre><code class="language-csharp">using System;
using System.Collections.Generic;
using Vigil.Domain.EventSourcing;
using Vigil.Patrons.Events;

public class Patron : EventSourced
{
    public Patron(Guid patronId, IEnumerable&#x3C;IVersionedEvent> history) : this(patronId)
    {
        LoadFrom(history);
    }

    protected Patron(Guid patronId) : base(patronId)
    {
        Handles&#x3C;PatronCreated>(OnPatronCreated);
        Handles&#x3C;PatronHeaderChanged>(OnPatronHeaderChanged);
        Handles&#x3C;PatronDeleted>(OnPatronDeleted);
    }
}

public abstract class EventSourced : IEventSourced
{
    private readonly Dictionary&#x3C;Type, Action&#x3C;IVersionedEvent>> handlers
        = new Dictionary&#x3C;Type, Action&#x3C;IVersionedEvent>>();

    protected void LoadFrom(IEnumerable&#x3C;IVersionedEvent> pastEvents)
    {
        var orderedPastEvents = pastEvents.OrderBy(pe => pe.GeneratedOn);
        foreach (var e in orderedPastEvents)
        {
            handlers[e.GetType()].Invoke(e);
            Version = e.Version;
            events.Add(e);
        }
    }
}

</code></pre>
<p>I saw two options for where to put the actions that receive an event and cause an entity to be in the proper state. Either I could create an <code>EventHandler</code> that receives an entity and then conjures up a new instance of it with the resultant changes (thus making entities immutable), or I could have an entity know how to handle events that affect it (entities are thus mutable objects).</p>
<p>I liked the idea of keeping the logic of how an <code>EventSourced</code> object is affect consolidated to just the entity itself. This allows for an ORM (like <a href="https://docs.microsoft.com/en-us/ef/">Entity Framework</a>) to directly assign data to the entity's properties, or for something else that has the collection of events to tell an entity to just <em>create itself</em>. Thus, the <code>Patron</code> constructor defines all of the events that it knows how to handle. When constructed with a collection of <code>IVersionEvent</code> objects, it calls the inherited <code>LoadFrom</code> method from <code>EventSourced</code>. My assumption is that the unit tests will be written to ensure that the <code>Patron</code> registers only events that are useful and that it handles all of the events that it should.</p>
<p>My initial goal was to create some sort of reflection assembly scanning that would find all methods that match the signature needed for an event and allow them to self-register. I might be able to create a custom attribute for that - perhaps a <code>HandlesEventAttribute</code>.</p>
<p>Anyway, each of the events, in creation order, get their appropriate method within the <code>Patron</code> object invoked, which updates the properties as appropriate. Unit testing is fairly straightforward.</p>
<pre><code class="language-csharp">using System;
using Vigil.Domain.EventSourcing;
using Vigil.Patrons.Events;
using Xunit;

namespace Vigil.Patrons
{
    public class PatronTest
    {
        [Fact]
        public void Patron_Can_Be_Hydrated_From_Patron_Created()
        {
            var patronId = Guid.NewGuid();

            PatronCreated created = new PatronCreated("Create User", TestHelper.Now, Guid.NewGuid())
            {
                DisplayName = "Test Creation",
                IsAnonymous = false,
                PatronType = "Test Account",
                PatronId = patronId,
                Version = 0
            };
            Patron result = new Patron(patronId, new[] { created });

            Assert.Equal("Test Creation", result.DisplayName);
            Assert.False(result.IsAnonymous);
            Assert.Equal("Test Account", result.PatronType);
            Assert.Equal(patronId, result.Id);
            Assert.Equal(0, result.Version);
            Assert.Equal("Create User", result.CreatedBy);
            Assert.Equal(TestHelper.Now, result.CreatedOn);
            Assert.Null(result.ModifiedBy);
            Assert.Null(result.ModifiedOn);
            Assert.Null(result.DeletedBy);
            Assert.Null(result.DeletedOn);
        }

        [Fact]
        public void Patron_Can_Be_Hydrated_From_Patron_Created_And_Updated()
        {
            var patronId = Guid.NewGuid();
            var evnts = new VersionedEvent[] {
                new PatronCreated("Create User", TestHelper.Now, Guid.NewGuid())
                {
                    DisplayName = "Test Creation",
                    IsAnonymous = false,
                    PatronType = "Test Account",
                    PatronId = patronId,
                    Version = 0
                },
                new PatronHeaderChanged("Change User", TestHelper.Later, Guid.NewGuid())
                {
                    DisplayName = "Test Update",
                    IsAnonymous = true,
                    PatronType = "Test Updated",
                    PatronId = patronId,
                    Version = 1
                }
            };
            Patron result = new Patron(patronId, evnts);

            Assert.Equal("Test Update", result.DisplayName);
            Assert.True(result.IsAnonymous);
            Assert.Equal("Test Updated", result.PatronType);
            Assert.Equal(patronId, result.Id);
            Assert.Equal(1, result.Version);
            Assert.Equal("Create User", result.CreatedBy);
            Assert.Equal(TestHelper.Now, result.CreatedOn);
            Assert.Equal("Change User", result.ModifiedBy);
            Assert.Equal(TestHelper.Later, result.ModifiedOn);
            Assert.Null(result.DeletedBy);
            Assert.Null(result.DeletedOn);
        }

        [Fact]
        public void Patron_Can_Be_Hydrated_From_Patron_Created_And_Empty_Updated()
        {
            var patronId = Guid.NewGuid();
            var evnts = new VersionedEvent[] {
                new PatronCreated("Create User", TestHelper.Now, Guid.NewGuid())
                {
                    DisplayName = "Test Creation",
                    IsAnonymous = false,
                    PatronType = "Test Account",
                    PatronId = patronId,
                    Version = 0
                },
                new PatronHeaderChanged("Change User", TestHelper.Later, Guid.NewGuid())
                {
                    PatronId = patronId,
                    Version = 1
                }
            };
            Patron result = new Patron(patronId, evnts);

            Assert.Equal("Test Creation", result.DisplayName);
            Assert.False(result.IsAnonymous);
            Assert.Equal("Test Account", result.PatronType);
            Assert.Equal(patronId, result.Id);
            Assert.Equal(1, result.Version);
            Assert.Equal("Create User", result.CreatedBy);
            Assert.Equal(TestHelper.Now, result.CreatedOn);
            Assert.Equal("Change User", result.ModifiedBy);
            Assert.Equal(TestHelper.Later, result.ModifiedOn);
            Assert.Null(result.DeletedBy);
            Assert.Null(result.DeletedOn);
        }

        [Fact]
        public void Patron_Can_Be_Hydrated_From_Patron_Created_And_Deleted()
        {
            var patronId = Guid.NewGuid();
            var evnts = new VersionedEvent[] {
                new PatronCreated("Create User", TestHelper.Now, Guid.NewGuid())
                {
                    DisplayName = "Test Creation",
                    IsAnonymous = false,
                    PatronType = "Test Account",
                    PatronId = patronId,
                    Version = 0
                },
                new PatronDeleted("Delete User", TestHelper.Later, Guid.NewGuid())
                {
                    PatronId = patronId,
                    Version = 1
                }
            };
            Patron result = new Patron(patronId, evnts);

            Assert.Equal("Test Creation", result.DisplayName);
            Assert.False(result.IsAnonymous);
            Assert.Equal(patronId, result.Id);
            Assert.Equal(1, result.Version);
            Assert.Equal("Create User", result.CreatedBy);
            Assert.Equal(TestHelper.Now, result.CreatedOn);
            Assert.Equal("Delete User", result.ModifiedBy);
            Assert.Equal("Delete User", result.DeletedBy);
            Assert.Equal(TestHelper.Later, result.ModifiedOn);
            Assert.Equal(TestHelper.Later, result.DeletedOn);
        }
    }
}
</code></pre>


Hydrating A Patron

<p>2016 was a busy year - in total, I ran eight races. While four of them were all in one weekend for <a href="/posts/2016/disney-s-dopey-challenge/">Disney's Dopey Challenge</a>, it was still a lot of early mornings for me. For 2017, I am going to scale things back a bit - which really just means removing the one racing weekend.</p>
<h2>F3 Half Marathon</h2>
<p>My favorite half marathon in Chicago is the <a href="http://www.f3running.com/">F^3 Lake Half Marathon</a>. My current personal record for a half marathon is 1:36:44, coming from last year's race. I enjoy the race because it is small enough that I feel competative, but it is large enough that the course does not feel empty. My first goal is to clear 1:35:00, with a rocket goal of finishing under 1:30:00 (6:51/mile). Ninty minutes to run 31.1 miles. Just thinking about it makes me think I might be approaching an acceptable pace to be called fast. This race is heavily weather dependent; if winds are calm and the course is dry, then I expect good things.</p>
<h2>Kalamazoo Marathon</h2>
<p>I have been doing a different spring marathon each year for the past two years - <a href="/posts/2015/3-56-58-2015-wisconsin-marathon/">Wisconsin</a> and <a href="https://results.chronotrack.com/event/results/event/event-13270?entryID=16657247">New Jersey</a>. In the spirit of trying something new, I'll be heading to Michigan for this year's spring marathon, running the <a href="https://thekalamazoomarathon.com/">Kalamazoo Marathon at the Borgess Run</a>. My goal is to finish under 3:15:00 (7:26/mile); which, conveniently, is also the fastest pace group that the race offers. My goal is to hold tight with them for as long as I can. If I am feeling really good after 18 miles, then I might try to go ahead of them. Otherwise, I will be thoroughly thrilled with crossing with the group. As with all of my races, the minimum goal for me is to beat my PR of 3:21:43.</p>
<h2>Some Unnamed 5k</h2>
<p>For the past four years, I have run the <a href="http://www.universalsole.com/burgers--beer-5k.html">Burgers &#x26; Beer 5k</a>. I am undecided if I want to run that race again, or find some other 5k. Last year, I was doing a #Whole30, so I couldn't eat the burger or the beer. It lost a lot of the luster. I would be willing to do it again, if I knew that I would not be on a restricted diet on race day. Otherwise, I will run one of the many other 5k races the city has during the summer. My options are not slim. My goal would be to beat my PR - 19:21 (6:13/mile).</p>
<h2>Chicago Marathon 2017</h2>
<p>This will be my fifth Chicago Marathon in a row, and if all goes well, will be the race that I finally qualify for the Boston Marathon - thus running that race in April 2019. Since I would be 37 on race day, my qualifying standard is 3:10:00; but with the way they do actual selection, I am aiming for 3:05:00 (7:03/mile). Five full minutes under the standard should be plenty to clear selection cutoffs.</p>


My 2017 Running Calendar

<p>I have come to the point where I am building out the initial proof-of-concept for the WebAPI portion of this project. This gives me a place to continue testing out features, and see if how I envisioned things would work can actually work. One of the first parts of unit testing the controller was to mock any of the properties that I need to use that the web server would ordinarily wire up. In a <code>Controller</code> that primarily entails the <code>ControllerContext</code>, which would also wire the <code>Controller.User</code>, <code>Controller.Url</code>, and <code>Controller.HttpContext</code> properties. So how do I do that?</p>
<h3>Mocking Controller.Url</h3>
<p>I use Moq as my mocking framework, though this could be done with any library. The <code>Url</code> property returns an <code>IUrlHelper</code>, which makes it easy to mock.</p>
<pre><code class="language-csharp">namespace Microsoft.AspNetCore.Mvc
{
    public interface IUrlHelper
    {
        ActionContext ActionContext { get; }

        string Action(UrlActionContext actionContext);
        string Content(string contentPath);
        bool IsLocalUrl(string url);
        string Link(string routeName, object values);
        string RouteUrl(UrlRouteContext routeContext);
    }
}
</code></pre>
<p>The <code>Content(string)</code>, <code>IsLocalUrl(string)</code>, and <code>Link(string, object)</code> are all trivial to overload. The piece that I stumbled across was when I wanted to mock <code>Url.Action(string, object)</code>, which is an extension method in the <code>UrlHelperExtensions</code> class. Moq is unable to mock extension methods. However, because <code>AspNetCore</code> is open source, I could happily go <a href="https://github.com/aspnet/Mvc/blob/master/src/Microsoft.AspNetCore.Mvc.Core/UrlHelperExtensions.cs">look at the source</a> and see what the extension method was doing behind the scenes. All of the various extension methods just pass controll to the last (and longest) extension method, which calls <code>Url.Action(UrlActionContext)</code>. They all pass a <code>null</code> for values not collected.</p>
<pre><code class="language-csharp">public static string Action(
    this IUrlHelper helper,
    string action,
    string controller,
    object values,
    string protocol,
    string host,
    string fragment)
{
    if (helper == null)
    {
        throw new ArgumentNullException(nameof(helper));
    }

    return helper.Action(new UrlActionContext()
    {
        Action = action,
        Controller = controller,
        Host = host,
        Values = values,
        Protocol = protocol,
        Fragment = fragment
    });
}

</code></pre>
<p>This all means that in order to "mock" the extension methods, I just need to provide a mock for the <code>IUrlHelper.Action(UrlActionContext)</code> method.</p>
<pre><code class="language-csharp">[Fact]
public void Create_With_ValidCommand_IsPublished_AndReturnsAcceptedResult_WithLocation()
{
    CreatePatron cmd = new CreatePatron("Patron Web Test", TestHelper.Now)
    {
        DisplayName = "Patron Display Name",
        IsAnonymous = false,
        PatronType = "Test Patron"
    };

    var mockUrlHelper = new Mock&#x3C;IUrlHelper>(MockBehavior.Strict);
    Expression&#x3C;Func&#x3C;IUrlHelper, string>> urlSetup
        = url => url.Action(It.Is&#x3C;UrlActionContext>(uac => uac.Action == "Get" &#x26;&#x26; GetId(uac.Values) != cmd.Id));
    mockUrlHelper.Setup(urlSetup).Returns("a/mock/url/for/testing").Verifiable();

    var controller = new PatronController()
    {
        Url = mockUrlHelper.Object
    };

    AcceptedResult result = controller.Create(cmd) as AcceptedResult;

    Assert.NotNull(result);
    mockUrlHelper.Verify(urlSetup, Times.Once());
    Assert.Equal("a/mock/url/for/testing", result.Location);
}

private Guid? GetId(object values)
{
    return values?.GetType().GetProperty("id")?.GetValue(values, null) as Guid?;
}
</code></pre>
<p>On my initial attempt, I was having the Url mock return an actual Url. However, I realized that since the string that returns from this shouldn't have any effect other than being a string, it <em>should</em> be some meaningless value. This code is not attempting to mock the routing or url creation based on the values sent to the <code>IUrlHelper</code>. All this unit test is doing, and all it <em>should be doning</em>, is validating that the controller is asking for a string that comes from passing in the "Get" action and an object with a property of "id" that is a <code>Guid</code>.</p>
<p>Mocking the <code>UrlHelperExtensions.RouteUrl(this IUrlHelper, ...)</code> extension methods is done the same way, but by mocking the <code>IUrlHelper.RouteUrl(UrlRouteContext)</code> method. The <code>RouteUrl</code> extension methods also just pass along their values to a new instance of <code>UrlRouteContext</code> and then call the interface's method.</p>
<h2>Mocking Controller.User.Identity.Name</h2>
<p>Mocking the User property on a Controller can be a little more difficult to figure out, because the <code>ControllerBase.User</code> property is read-only; <code>User</code> gets its value from the <code>HttpContext.User</code> property. The <code>Request</code> and <code>Response</code> properties on the <code>ControllerBase</code> also come from the <code>HttpContext</code>. Fortuitously, <code>ControllerBase.HttpContext</code> is settable and <code>HttpContext</code> is an abstract class. Therefore, a simple stub of the <code>User</code> property on a mock of the <code>HttpContext</code> takes care of whatever needs there are for accessing the claims information.</p>
<p>Since the most common usage for this is that I am trying to access the user's name, I created a quick private method that goes inside of my test class. Moq takes care of walking the expression tree and creating the necessary mocks of the <code>ClaimsPrincipal</code> and the <code>IIdentity</code> properties.</p>
<pre><code class="language-csharp">private void SetupUser(Controller controller, string username)
{
    var mockContext = new Mock&#x3C;HttpContext>(MockBehavior.Strict);
    mockContext.SetupGet(hc => hc.User.Identity.Name).Returns(username);
    controller.ControllerContext = new ControllerContext()
    {
        HttpContext = mockContext.Object
    };
}
</code></pre>


Mock Controller's User and Url Properties in ASP.NET Core MVC

<p>Now that I have revised my approach for what constitutes <a href="/posts/2016/revisiting-creating-and-updating-entities/">creating and updating entities</a>, I am going back to my <code>Patron</code> entity to rework the create and update commands. I have already scrapped the <code>Factory</code> class and its associated unit tests, and gone forward with code creation.</p>
<h2>Commands for Create and Update Patron</h2>
<p>The first major change is that I have moved the Patron Commands into the <code>Vigil.Patrons</code> project; at this moment, I am keeping projects confined by domain. Later, I may find this to be in error, but for now it seems to make sense. I am keeping validation on the Command class and the unit tests for the validation scenarios does not need to change at all. The only change that I made was adding the <code>Id</code> property implementation for <code>ICommand</code>. Since I would like to track every part of the system, it makes sense to have unique identifiers for everything.</p>
<pre><code class="language-csharp">using System;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using Vigil.Domain.Messaging;

namespace Vigil.Patrons.Commands
{
    public class CreatePatronCommand : ICommand
    {
        public Guid Id { get; set; } = Guid.NewGuid();

        [Required, StringLength(250)]
        public string DisplayName { get; set; }
        [DefaultValue(false)]
        public bool IsAnonymous { get; set; } = false;
        [Required, StringLength(250)]
        public string PatronType { get; set; }
    }
}
</code></pre>
<p>Along with some other shuffling around, I have dropped the notion of passing around <code>IKeyIdentity</code> and just using the <code>Guid</code>. I am never going to change the type of the key; but if I did, it would need to be a momumental undertaking anyway, since I would be changing <em>everything</em>. <code>Guid</code> is universally understood and unique, so I am just making life easier that way.</p>
<pre><code class="language-csharp">using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using Vigil.Domain.Messaging;

namespace Vigil.Patrons.Commands
{
    public class UpdatePatronCommand : ICommand, IValidatableObject
    {
        public Guid Id { get; set; } = Guid.NewGuid();

        public Guid PatronId { get; set; }

        [StringLength(250)]
        public string DisplayName { get; set; }
        public bool? IsAnonymous { get; set; }
        [StringLength(250)]
        public string PatronType { get; set; }

        public IEnumerable&#x3C;ValidationResult> Validate(ValidationContext validationContext)
        {
            if (PatronId == Guid.Empty)
            {
                yield return new ValidationResult("PatronId is a required field.", new string[] { nameof(PatronId) });
            }
        }
    }
}
</code></pre>
<h2>Patron Command Handler</h2>
<p>Someone else will put a command in a message queue, and some other process will handle pulling that command off of the queue and instantiating the <code>PatronCommandHandler</code>. However, once all that work is taken care of (it's all part of the unit test's arrange step), it is time to turn the command into a series of events. While the current examples only show one event fired from the command, there could be many more. However, there are two (probably hard and fast) rules: #1 - there must be exactly one command handler per command (though one handler can handle many different commands), and #2 - every command must fire at least one event (if a command doesn't create an event, what's the point?).</p>
<pre><code class="language-csharp">using System;
using Vigil.Domain.Messaging;
using Vigil.Patrons.Commands;
using Vigil.Patrons.Events;

namespace Vigil.Patrons
{
    public class PatronCommandHandler : ICommandHandler&#x3C;CreatePatronCommand>
    {
        private readonly IEventBus eventBus;
        private readonly ICommandRepository repo;

        public PatronCommandHandler(IEventBus eventBus, ICommandRepository repo)
        {
            this.eventBus = eventBus;
            this.repo = repo;
        }

        public void Handle(CreatePatronCommand command)
        {
            var patronCreated = new PatronCreated
            {
                SourceId = command.Id,
                PatronId = Guid.NewGuid(),
                DisplayName = command.DisplayName,
                IsAnonymous = command.IsAnonymous,
                PatronType = command.PatronType
            };
            eventBus.Publish(patronCreated);
            repo.Save(command);
        }

        public void Handle(UpdatePatronCommand command)
        {
            var patronUpdated = new PatronUpdated
            {
                SourceId = command.Id,
                PatronId = command.PatronId,
                DisplayName = command.DisplayName,
                IsAnonymous = command.IsAnonymous,
                PatronType = command.PatronType
            };
            eventBus.Publish(patronUpdated);
            repo.Save(command);
        }
    }
}
</code></pre>
<h2>Command Handler Unit Tests</h2>
<p>The purpose of a unit test for an <code>ICommandHandler</code> is to ensure the correct event(s) is/are put on the event bus, and that the command will be persisted through the repository. Later unit tests on the repository itself will determine if the entity was actually persisted, and later tests on the actual implementation of the event bus will determine if anything happens when an event is put on the bus. But for this unit test, the code is just checking to make sure the handler does what is expected.</p>
<pre><code class="language-csharp">using Moq;
using System;
using Vigil.Domain.Messaging;
using Vigil.Patrons.Commands;
using Vigil.Patrons.Events;
using Xunit;

namespace Vigil.Patrons
{
    public class PatronCommandHandlerTest
    {
        [Fact]
        public void User_Can_Create_New_Patron()
        {
            CreatePatronCommand command = new CreatePatronCommand()
            {
                DisplayName = "Test Patron",
                IsAnonymous = false,
                PatronType = "Test Account"
            };

            var eventBus = new Mock&#x3C;IEventBus>();
            eventBus.Setup(bus => bus.Publish(It.IsAny&#x3C;PatronCreated>()))
                .Callback&#x3C;PatronCreated>((@event) =>
                {
                    Assert.Equal(command.DisplayName, @event.DisplayName);
                    Assert.Equal(command.IsAnonymous, @event.IsAnonymous);
                    Assert.Equal(command.PatronType, @event.PatronType);
                    Assert.Equal(command.Id, @event.SourceId);
                    Assert.NotEqual(command.Id, @event.Id);
                    Assert.NotEqual(command.Id, @event.PatronId);
                    Assert.NotEqual(Guid.Empty, @event.PatronId);
                    Assert.NotEqual(Guid.Empty, @event.Id);
                }).Verifiable();
            var repo = new Mock&#x3C;ICommandRepository>();
            repo.Setup(re => re.Save(It.Is&#x3C;CreatePatronCommand>(cpc => cpc.Id == command.Id))).Verifiable();

            ICommandHandler&#x3C;CreatePatronCommand> handler = new PatronCommandHandler(eventBus.Object, repo.Object);
            handler.Handle(command);

            Assert.NotEqual(Guid.Empty, command.Id);
            Mock.Verify(eventBus, repo);
        }

        [Fact]
        public void User_Can_Update_a_Patron()
        {
            UpdatePatronCommand command = new UpdatePatronCommand()
            {
                PatronId = Guid.NewGuid(),
                DisplayName = "Updated Test Patron"
            };

            var eventBus = new Mock&#x3C;IEventBus>();
            eventBus.Setup(bus => bus.Publish(It.IsAny&#x3C;PatronUpdated>()))
                .Callback&#x3C;PatronUpdated>((@event) =>
                {
                    Assert.Equal(command.DisplayName, @event.DisplayName);
                    Assert.Equal(command.IsAnonymous, @event.IsAnonymous);
                    Assert.Equal(command.PatronType, @event.PatronType);
                    Assert.Equal(command.Id, @event.SourceId);
                    Assert.Equal(command.PatronId, @event.PatronId);
                    Assert.NotEqual(command.Id, @event.Id);
                    Assert.NotEqual(Guid.Empty, @event.Id);
                }).Verifiable();
            var repo = new Mock&#x3C;ICommandRepository>();
            repo.Setup(re => re.Save(It.Is&#x3C;UpdatePatronCommand>(cpc => cpc.Id == command.Id))).Verifiable();

            ICommandHandler&#x3C;UpdatePatronCommand> handler = new PatronCommandHandler(eventBus.Object, repo.Object);
            handler.Handle(command);

            Assert.NotEqual(Guid.Empty, command.Id);
            Mock.Verify(eventBus, repo);
        }
    }
}
</code></pre>


Patron Can Be Created and Updated (Again)

<p>Just when I thought I was in a good place to carry forward with retrieving a persisted entity and then modifying its values, I started looking intently into the <a href="https://msdn.microsoft.com/en-us/library/jj554200.aspx">CQRS Journey</a> on MSDN. While reading through their narative, I thought I was really getting to understand how the code was structured. However, once I dug into the source code - well, I was naively mistaken. The notion of having <a href="/posts/2016/user-can-create-new-patron/">a Factory</a> was entirely flawed, as that role of validating and placing Commands on the Event Bus was better suited in the user interface layer (be it a Web Controller, a console library, or some other set of code). I supposed that the Factory could fall under "some other set of code"; however, for the purposes of demonstrating the bare minimum needed to declare an action completed, the Factory was adding one too many steps. I realized that the unit test need not create a Factory to then pass a Command to the Bus. Instead, the Unit Test should <em>assume the command was already on the bus</em>.</p>
<p>If I go back to the notion of "User Can Create New Patron", I have realized that I did it entirely wrong. Since what I wanted to demonstrate was the power and ability of using <code>interface</code> design to better focus on what I want to accomplish, the statement I should have been "User Can Command A Patron To Be Created". This provides a better starting place for me to carry that command forward. The <code>CreatePatronCommand</code> has now already been created (<em>ipso facto</em>, it is in the message queue) and now needs an <code>ICommandHandler</code> to turn it into one or more events and to persist the command for historical referencing.</p>
<h3>The New Command Interfaces</h3>
<p>With this refocus, I now have an <code>ICommand</code> that is handled by an <code>ICommandHandler</code> with access to a <code>ICommandRepository</code> for persistence needs. The narative now becomes:</p>
<p>A <code>Command</code> describes the action that needs to take place. The name of the command (<code>CreatePatronCommand</code>) indicates what should be peformed and the data in the command provides the necessary information to fully execute the command.</p>
<pre><code class="language-csharp">using System;

namespace Vigil.Domain.Messaging
{
    public interface ICommand
    {
        /// &#x3C;summary>Gets the command identifier.
        /// &#x3C;/summary>
        Guid Id { get; }
    }
}
</code></pre>
<p>The command, having been put on the bus, is then passed to a <code>CommandHandler</code> which creates one or more events, placing them on the event bus, and persists the command to some storage for archival purposes. Otherwise, the command is of no further use and could be discarded.</p>
<pre><code class="language-csharp">namespace Vigil.Domain.Messaging
{
    public interface ICommandHandler
    {
    }

    public interface ICommandHandler&#x3C;TCommand> : ICommandHandler
        where TCommand : ICommand
    {
        void Handle(TCommand command);
    }
}
</code></pre>
<p>In order to persist the command, a <code>CommandRepository</code> is passed to the command handler to presist the command. When needed, this could also fetch data if it is required to do some kind of look-up when creating events.</p>
<pre><code class="language-csharp">namespace Vigil.Domain.Messaging
{
    public interface ICommandRepository
    {
        void Save&#x3C;TCommand>(TCommand command) where TCommand : ICommand;
    }
}
</code></pre>


Rovani's Sandbox

Blog Posts - Page 9