Posts in "Vigil Journey"

Inspired by the CQRS Journey that a team at Microsoft made in 2012, I felt that posting a series of pieces about the steps that I was taking while creating this large project would provide three key benefits. First, it would give me something to write about. I have tried keeping blogs before, but I fail after a few months to generate content. Second, by having to describe everything, it forces me to have to rationalize all design and development decisions. Sure, I'm just having to rationalize them to myself, but frequently, I am my own worst critic. Finally, it give me motivation to keep working on the progress instead of getting bored with it and not trying to find some way to reinvigorate my enthusiasm. I have no idea where this is going to take me, but I am excited to see what happens.

Vigil's Azure Command Queue

Command Query Responsibility Segregation (CQRS) was not something that I easily understood. Martin Fowler did a thorough job of explaining it in often-linked post from 2011. However, I still did not quite grasp it at the time. I also wasn’t working on any project large enough or complex enough that it made sense to use a pattern with that level of depth. When I came back to the concept many years later while working on a significantly more complex project, I could put together all of the puzzle pieces but I still couldn’t quite see the whole picture. While researching the topic, I stumbled on a blog post by Cesar de la Torre from Microsoft - CQRS BUS and Windows Azure technologies. His picture was well worth the thousands of words that I had already read.

Using an Explicit Model Constructor with a JsonInputFormatter

I may have gone down a long and twisted rabbit hole trying to figure out this problem, but I learned a lot about how model binding along the way, so I consider the whole experiment a productive use of my time, even if I end up ripping it all out in a few weeks. However, since I thought this would be a good idea, I figure others might find a good use for this knowledge. Thus, this is how I am using an explicity constructor when the input is in a JSON format and parameter is bound using the request body.

Discovering the ASP.NET Core MVC Stack

Now that the Vigil Project has breached into the API layer, I started to learn all kinds of new information about what takes place before the Controller’s Action method is called and what happens after that method returns. The MVC framework, especially while using Visual Studio, make it incredibly easy to forget about all of the heavy lifting that the framework does – long before my code is ever executed. It is only when I wanted to start changing how pieces worked that I really start to see the true depth and breadth of what Microsoft has created. As I begin to discover new pieces of the framework, I felt that the best way to retain this information is to repeat it; and since no one around me wants to hear about all of this, I’ll just type it into a blog post.

22 Month Status Report

As I was writing the previous post, it came as a shock how far behind my posts on the progress of the Vigil Donor Relationship Management System had gotten. I was going too deep into the code and making too many changes that I didn’t pause to write a post about my progress. My posts are 22 commits behind, and there are quite a few changes I’ve made to the workflow and to the application. As a way to catch up on all the missed posts that I should have written, I am putting this one together as a status report of the project/journey/solution.

In terms of workflow, I have embraced the GitHub Flow workflow (both for Vigil and for this blog). For my little project, since there is no discussion and no deployments (as of yet), the workflow is as simple as Branch, Commit(s), Pull, Merge, Delete. I like the way that a merge can squash all of the commits made on a branch, so that I have one summarized collection of everything that I did. This way, I can easily differentiate the content of a post by doing one per Pull Request / Merge. Hopefully, this process will now keep the posts coming regularly, help me be more concise about what should be in a post, and better contain runaway developing.

Introducing Vigil Web API

Thus far in the series, the Vigil Journey project has been able to create a patron, update a patron, and have those redefined as “a patron can be created and updated”. 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.

Illusions of Queues and Buses

There are many solutions on the market (including free open source) for creating both message queues and event buses. However, for example purposes - and as a simple proof of concept - I just wanted a simple way to store the contents of a Command, run the CommandHandler, receive Event objects, call the EventHandler 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.

Hydrating A Patron

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 Patron, 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 Patron from only a list of events.

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

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 Controller that primarily entails the ControllerContext, which would also wire the Controller.User, Controller.Url, and Controller.HttpContext properties. So how do I do that?

Patron Can Be Created and Updated (Again)

Now that I have revised my approach for what constitutes creating and updating entities, I am going back to my Patron entity to rework the create and update commands. I have already scrapped the Factory class and its associated unit tests, and gone forward with code creation.

Revisiting Creating and Updating Entities

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 CQRS Journey 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 Factory 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 call 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 assume the command was already on the bus.

User Can Update a Patron

A simple update of an object is as complex as adding a new instance of the object, which means it is both straight forward and laden with all kinds of caveats and unlying processes. As with creating a new Patron, it is trivial for me to put together a contrived example of code that will technically satisfy the requirements for “User Can Update a Patron”. A unit Test will create a new Command that will be validated by the Factory and then passed to the MessageQueue for persistance by some other process.

A Word On Validation

For a while, I have been battling with where validation should occur, and who is responsible for ensuring that the information in a command is good data. For the first layer of data validation, I am turning to the Command to validate itself — the mere application of data types is a rudimentary form of data validation, so including addition simple validation extends that basic logic.

User Cannot* Create Patron That Fails Validation**

Creating a patron (by which I mean, issuing a command such that some process somewhere will instantiate an actual Patron entity, and perhaps persist it in some useful manor) is all well and good, until someone tries to stuff in data that isn’t valid. Users like to do things like this all the time, so I am going to attempt to protect against it from the beginning. Additionally, by setting up the mechanisms to test validation and perform validation, I should be able to keep a culture of enforcing these conventions throughout development.

A Word On Factory Results and Contracts

For simplicity, the PatronFactory’s CreatePatron method just returned an IKeyIdentity. This was a simple interface that requires an Id of type Guid. When the creation method was always assumed to work correctly, this was fine - I don’t have to worry about validation checking, data errors, or anything that might cause a failure. However, in the real world, I need to be aware of these things. As such, the first refactor that I’m going to perform is to change the return type to a multi-purpose class.

User* Can Create** New Patron***

The first thing that I learned with Dependency Injection is that it encourages a mindset of “I’ll figure that out that later.” This allows me to put in the bare minimum for what might pass a test, even though I know it will have all kinds of complex integration somewhere down the line. To start this little experiment, I am going to put together a tiny amount of arguably functional code. I will start with the very simple definition of what a User is, what it means to Create an entity, and how a Patron is represented.

Everything Gets an Id

There can be a lot of issues with figuring out how to identify an object, especially as I try to track it across various services, platforms, persistance strategies, and even entire systems. For a while, I played around with just having every object contain its own identification field. However, it was painful having to remember to put the same and correct field(s) on every entity. I stumbled upon a blog post (which I cannot find anymore), which talked about pulling the key out into its own class, and have everything inherit from there. I’m not entirely sure I like the idea of a super-base-class, but I think it at least gives me a good place to isolate the key into a globally consistent way.