Introducing Jasper as an In Process Command Bus for .Net

A couple weeks ago I wrote a blog post called If you want your OSS project to be successful… about trying to succeed with open source development efforts. One of the things I said was “don’t go dark” when you’re working on an OSS project. Not only did I go “dark” on Jasper for quite awhile, I finally rolled out its 1.0 release during the worst global pandemic in a century. So all told, Jasper is by no means an exemplary project model for anyone to follow who’s trying to succeed with an OSS project.

This sample application is also explained and demonstrated in the documentation page Jasper as a Mediator.

Jasper is a new open source tool that can be used as an in process “command bus” inside of .Net Core 3 applications. Used locally, Jasper can provide a superset of the “mediator” functionality popularized by MediatR that many folks like using within ASP.Net MVC Core applications to simplify controller code by offloading most of the processing to separate command handlers. Jasper certainly supports that functionality, but also adds rich options for asynchronous processing commands with built in resiliency mechanisms.

Part of the reason why Jasper went cold was waiting for .Net Core 3.0 to be released. With the advent of .Net Core 3.0, Jasper was somewhat re-wired to support the new generic HostBuilder for bootstrapping and configuration. With this model of bootstrapping, Jasper can easily be integrated into any kind of .Net Core application (MVC Core application, web api, windows service, console app, “worker” app) that uses the HostBuilder.

Let’s jump into seeing how Jasper could be integrated into a .Net Core Web API system. All the sample code I’m showing here is on GitHub in the “InMemoryMediator” project. InMemoryMediator uses EF Core with Sql Server as its backing persistence. Additionally, this sample shows off Jasper’s support for the “Outbox” pattern for reliable messaging without having to resort to distributed transactions.

To get started, generated a project with the dotnet new webapi template. From there, I added some extra Nuget dependencies:

  1. Microsoft.EntityFrameworkCore.SqlServer — because we’re going to use EF Core with Sql Server as the backing persistence for this service
  2. Jasper — this is the core library, and all that you would need to use Jasper as an in process command bus
  3. Jasper.Persistence.EntityFrameworkCore — extension library to add Jasper’s “Outbox” and transactional support to EF Core
  4. Jasper.Persistence.SqlServer — extension library to add persistence for the “Outbox” support
  5. Swashbuckle.AspNetCore — just to add Swagger support

Your First Jasper Handler

Before we get into bootstrapping, let’s just start with how to build a Jasper command handler and how that would integrate with an MVC Core Controller. Keeping to a very simple problem domain, let’s say that we’re capturing, creating, and tracking new Item entities like this:

public class Item
    public string Name { get; set; }
    public Guid Id { get; set; }

So let’s build a simple Jasper command handler that would process a CreateItemCommand message, persist a new Item entity, and then raise an ItemCreated event message that would be handled by Jasper as well, but asynchronously somewhere off to the side in a different through. Lastly, we want things to be reliable, so we’re going to introduce Jasper’s integration of Entity Framework Core for “Outbox” support for the event messages being raised at the same time we create new Item entities.

First though, to put things in context, we’re trying to get to the point where our controller classes mostly just delegate to Jasper through its ICommandBus interface and look like this:

public class UseJasperAsMediatorController : ControllerBase
    private readonly ICommandBus _bus;

    public UseJasperAsMediatorController(ICommandBus bus)
        _bus = bus;

    public Task Create([FromBody] CreateItemCommand command)
        // Using Jasper as a Mediator
        return _bus.Invoke(command);

You can find a lot more information about what Jasper can do as a local command bus in the project documentation.

When using Jasper as a mediator, the controller methods become strictly about the mechanics of reading and writing data to and from the HTTP protocol. The real functionality is now in the Jasper command handler for the CreateItemCommand message, as coded with this Jasper Handler class:

public class ItemHandler
    // This attribute applies Jasper's transactional
    // middleware
    public static ItemCreated Handle(
        // This would be the message
        CreateItemCommand command,

        // Any other arguments are assumed
        // to be service dependencies
        ItemsDbContext db)
        // Create a new Item entity
        var item = new Item
            Name = command.Name

        // Add the item to the current
        // DbContext unit of work

        // This event being returned
        // by the handler will be automatically sent
        // out as a "cascading" message
        return new ItemCreated
            Id = item.Id

You’ll probably notice that there’s no interface and mandatory base class usage in the code up above. Similar to MVC Core, Jasper will auto-discover the handler classes and message handling methods from your code through type scanning. Unlike MVC Core and every other service bus kind of tool .Net I’m aware of, Jasper only depends on naming conventions rather than base classes or interfaces.

The only bit of framework “stuff” at all in the code above is the [Transactional] attribute that decorates the handler class. That adds Jasper’s own middleware for transaction and outbox support around the message handling to just that message. At runtime, when Jasper handles the CreateItemCommand in that handler code up above, it:

  • Sets up an “outbox” transaction with the EF Core ItemsDbContextservice being passed into the Handle() method as a parameter
  • Take the ItemCreated message that “cascades” from the handler method and persists that message with ItemsDbContext so that both the outgoing message and the new Item entity are persisted in the same Sql Server transaction
  • Commits the EF Core unit of work by calling ItemsDbContext.SaveChangesAsync()
  • Assuming that the transaction succeeds, Jasper kicks the new ItemCreated message into its internal sending loop to speed it on its way. That outgoing event message could be handled locally in in-memory queues or sent out via external transports like Rabbit MQ or Azure Service Bus

If you’re interested in what the code above would look like without any of Jasper’s middleware or cascading message conventions, see the section near the bottom of this post called “Do it All Explicitly Controller”.

So that’s the MVC Controller and Jasper command handler, now let’s move on to integrating Jasper into the application.

Bootstrapping and Configuration

This is just an ASP.Net Core application, so you’ll probably be familiar with the generated Program.Main() entry point. To completely utilize Jasper’s extended command line support (really Oakton.AspNetCore), I’ll make some small edits to the out of the box generated file:

public class Program
    // Change the return type to Task to communicate
    // success/failure codes
    public static Task Main(string[] args)
        return CreateHostBuilder(args)

            // This replaces Build().Start() from the default
            // dotnet new templates

    public static IHostBuilder CreateHostBuilder(string[] args) =>

            // You can do the Jasper configuration inline with a 
            // Lambda, but here I've centralized the Jasper
            // configuration into a separate class

            .ConfigureWebHostDefaults(webBuilder =>

This isn’t mandatory, but there’s just enough Jasper configuration for this project with the outbox support that I opted to put the Jasper configuration in a new file called JasperConfig that inherits from JasperOptions:

public class JasperConfig : JasperOptions
    public override void Configure(IHostEnvironment hosting, IConfiguration config)
        if (hosting.IsDevelopment())
            // In development mode, we're just going to have the message persistence
            // schema objects dropped and rebuilt on app startup so you're
            // always starting from a clean slate
            Advanced.StorageProvisioning = StorageProvisioning.Rebuild;

        // Just the normal work to get the connection string out of
        // application configuration
        var connectionString = config.GetConnectionString("sqlserver");

        // Setting up Sql Server-backed message persistence
        // This requires a reference to Jasper.Persistence.SqlServer

        // Set up Entity Framework Core as the support
        // for Jasper's transactional middleware

        // Register the EF Core DbContext
        // You can register IoC services in this file in addition
        // to any kind of Startup.ConfigureServices() method,
        // but you probably only want to do it in one place or the 
        // other and not both.
            x => x.UseSqlServer(connectionString),

            // This is important! Using Singleton scoping
            // of the options allows Jasper + Lamar to significantly
            // optimize the runtime pipeline of the handlers that
            // use this DbContext type

Returning a Response to the HTTP Request

In the UseJasperAsMediatorController controller, we just passed the command into Jasper and let MVC return an HTTP status code 200 with no other context. If instead, we wanted to send down the ItemCreated message as a response to the HTTP caller, we could change the controller code to this:

public class WithResponseController : ControllerBase
    private readonly ICommandBus _bus;

    public WithResponseController(ICommandBus bus)
        _bus = bus;

    public Task<ItemCreated> Create([FromBody] CreateItemCommand command)
        // Using Jasper as a Mediator, and receive the
        // expected response from Jasper
        return _bus.Invoke<ItemCreated>(command);

“Do it All Explicitly Controller”

Just for a comparison, here’s the CreateItemCommand workflow implemented inline in a controller action with explicit code to handle the Jasper “Outbox” support:

// This controller does all the transactional work and business
// logic all by itself
public class DoItAllMyselfItemController : ControllerBase
    private readonly IMessageContext _messaging;
    private readonly ItemsDbContext _db;

    public DoItAllMyselfItemController(IMessageContext messaging, ItemsDbContext db)
        _messaging = messaging;
        _db = db;

    public async Task Create([FromBody] CreateItemCommand command)
        // Start the "Outbox" transaction
        await _messaging.EnlistInTransaction(_db);

        // Create a new Item entity
        var item = new Item
            Name = command.Name

        // Add the item to the current
        // DbContext unit of work

        // Publish an event to anyone
        // who cares that a new Item has
        // been created
        var @event = new ItemCreated
            Id = item.Id

        // Because the message context is enlisted in an
        // "outbox" transaction, these outgoing messages are
        // held until the ongoing transaction completes
        await _messaging.Send(@event);

        // Commit the unit of work. This will persist
        // both the Item entity we created above, and
        // also a Jasper Envelope for the outgoing
        // ItemCreated message
        await _db.SaveChangesAsync();

        // After the DbContext transaction succeeds, kick out
        // the persisted messages in the context "outbox"
        await _messaging.SendAllQueuedOutgoingMessages();

As a huge lesson learned from Jasper’s predecessor project, it’s always possible to easily bypass any kind of Jasper conventional “magic” and write explicit code as necessary.

There’s a lot more to say about Jasper and you can find a *lot* more information on its documentation website. I’ll be back sometime soon with more examples of Jasper, with probably some focus on functionality that goes beyond other mediator tools.

In the next post, I’ll talk about Jasper’s runtime execution pipeline and how it’s very different than other .Net tools with similar functionality (hint, it involves a boatload less generics magic than anything else).


Using Alba for Integration Testing ASP.Net Core Web Services

There’s a video of David Giard and I talking about Alba at CodeMash a couple years ago on YouTube if you’re interested.

Alba is a helper library for doing automated testing against ASP.Net Core web services. Alba started out as a subsystem of the defunct FubuMVC project for HTTP contract testing, but was later extracted into its own project distributed via Nuget, ported to ASP.Net Core, and finally re-wired to incorporate TestServer internally.

There are certainly other advantages, but I think the biggest selling point of adopting ASP.Net Core is the ability to run HTTP requests through your system completely in memory without any other kind of external web server setup. In my experience, this has made automated integration testing of ASP.Net Core applications far simpler compared to older versions of ASP.Net.

We could use FubuMVC’s OWIN support with or without Katana to perform the same kind of automated testing that I’m demonstrating here years ago, but hardly anyone ever used that and what I’m showing here is significantly easier to use.

Why not just use TestServer you ask? You certainly can, but Alba provides a lot of helper functionality around exercising HTTP web services that will make your tests much more readable and remove a lot of the repetitive coding you’d have to do with just using TestServer.

To demonstrate Alba, I published a small solution called AlbaIntegrationTesting to GitHub this morning.

Starting with a small web services application generated with the dotnet new webapi template, I added a small endpoint that we’ll later write specifications against:

public class Answers
    public int Product { get; set; }
    public int Sum { get; set; }

public class AdditionController : ControllerBase
    public Answers DoMath(int one, int two)
        return new Answers
            Product = one * two,
            Sum = one + two

Next, I added a new test project using xUnit.Net with the dotnet new xunit template. With the new skeleton testing project I:

  • Added a reference to the latest Alba Nuget
  • My preference for testing assertions in .Net is Shouldly, so I added a Nuget reference for that as well

Since bootstrapping an ASP.Net Core system is non-trivial in terms of performance, I utilized xUnit.Net’s support for sharing context between tests so that the application only has to be spun up once in the test suite. The first step of that is to create a new “fixture” class that holds the ASP.Net Core system in memory like so:

public class AppFixture : IDisposable
    public AppFixture()
        // Use the application configuration the way that it is in the real application
        // project
        var builder = Program.CreateHostBuilder(new string[0])
            // You may need to do this for any static 
            // content or files in the main application including
            // appsettings.json files
            // DirectoryFinder is an Alba helper
            // Override the hosting environment to "Testing"

        // This is the Alba scenario wrapper around
        // TestServer and an active .Net Core IHost
        System = new SystemUnderTest(builder);

        // There's also a BeforeEachAsync() signature
        System.BeforeEach(httpContext =>
            // Take any kind of setup action before
            // each simulated HTTP request
            // In this case, I'm setting a fake JWT token on each request
            // as a demonstration
            httpContext.Request.Headers["Authorization"] = $"Bearer {generateToken()}";

        System.AfterEach(httpContext =>
            // Take any kind of teardown action after
            // each simulated HTTP request


    private string generateToken()
        // In a current project, we implement this method
        // to create a valid JWT token with the claims that
        // the web services require
        return "Fake";

    public SystemUnderTest System { get; }

    public void Dispose()

This new AppFixture class will only be built once by xUnit.Net and shared between test unit classes using the IClassFixture<AppFixture> interface.

Do note that you can express some actions in Alba to take immediately before or after executing an HTTP request through your system for typical setup or teardown operations. In one of my current projects, we exploit this capability to add a pre-canned JWT to the request headers that’s required by our system. In our case, that’s allowing us to test the security integration and the multi-tenancy support that depends on the JWT claims at the same time we’re exercising controller actions and the associated database access underneath it. If you’re familiar with the test pyramid idea, these tests are the middle layers of our testing pyramid.

To simplify the xUnit.Net usage throughout the testing suite, I like to introduce a base class that inevitable accumulates utility methods for running Alba or common database setup and teardown functions. I tend to call this class IntegrationContext and here’s a sample:

public abstract class IntegrationContext : IClassFixture<AppFixture>
    protected IntegrationContext(AppFixture fixture)
        Fixture = fixture;

    public AppFixture Fixture { get; }

    /// <summary>
    /// Runs Alba HTTP scenarios through your ASP.Net Core system
    /// </summary>
    /// <param name="configure"></param>
    /// <returns></returns>
    protected Task<IScenarioResult> Scenario(Action<Scenario> configure)
        return Fixture.System.Scenario(configure);

    // The Alba system
    protected SystemUnderTest System => Fixture.System;

    // Just a convenience because you use it pretty often
    // in tests to get at application services
    protected IServiceProvider Services => Fixture.System.Services;


Now with the AppFixture and IntegrationContext in place, let’s write some specifications against the AdditionController endpoint shown earlier in this post:

public class DoMathSpecs : IntegrationContext
    public DoMathSpecs(AppFixture fixture) : base(fixture)

    // This specification uses the shorthand helpers in Alba
    // that's useful when you really only care about the data
    // going in or out of the HTTP endpoint
    public async Task do_some_math_adds_and_multiples_shorthand()
        var answers = await System.GetAsJson<Answers>("/math/3/4");
    // This specification shows the longhand way of executing an
    // Alba scenario and using some of its declarative assertions
    // about the expected HTTP response
    public async Task do_some_math_adds_and_multiples_longhand()
        var result = await Scenario(x =>
            x.ContentTypeShouldBe("application/json; charset=utf-8");

        var answers = result.ResponseBody.ReadAsJson<Answers>();

Alba can do a lot more to work with the HTTP requests and responses, but I hope this gives you a quick introduction to using Alba for integration testing.

Using Oakton for Development-Time Commands in .Net Core Applications

All of the sample code in this blog post is on GitHub in the OaktonDevelopmentCommands project.

Last year I released the Oakton.AspNetCore library that provides an expanded command line experience for ASP.Net Core applications (and environment tests too!) that adds additional command line flags for the basic dotnet run behavior. Oakton.AspNetCore also gives you the ability to embed completely different named command directly into your application — either from your own application or Oakton.AspNetCore can pull in commands from Nuget libraries.

To make this concrete, I started a new sample project on GitHub with the dotnet new webapi template. To add the new command line experience, I added a Nuget reference to Oakton.AspNetCore and modified the Program.Main() method to this:

// I changed the return type to Task
public static Task Main(string[] args)
    return CreateHostBuilder(args)
        // This extension method makes Oakton the active
        // command line parser and executor

To show the ability to add commands from an external library, I also swapped out the built in DI container with Lamar, and added a reference to the Lamar.Diagnostics Nuget to expose Lamar’s diagnostics reports via the command line.

Just to show the Lamar integration, I added just the one line of code to the host builder configuration you can see below:

public static IHostBuilder CreateHostBuilder(string[] args) =>
        .UseLamar() // Overriding the IoC container to use Lamar
        .ConfigureWebHostDefaults(webBuilder =>

Now, to switch the actual command line to see the results of all of that, you can see Oakton’s built in command line help by typing the command dotnet run --?, which gives this output:

    Available commands:
         check-env -> Execute all environment checks against the application
          describe -> Writes out a description of your running application to either the console or a file
    lamar-scanning -> Runs Lamar's type scanning diagnostics
    lamar-services -> List all the registered Lamar services
    lamar-validate -> Runs all the Lamar container validations
               run -> Runs the configured AspNetCore application
          sayhello -> I'm a simple command that just starts up the app and says hello

A couple notes about the output above:

  • With the dotnet cli mechanics, the basic usage is dotnet [command] [optional flags to dotnet itself] -- [arguments to your application]. The double dashes marks the boundaries between arguments and flags meant for dotnet itself and arguments or flags for your application. So as an example, to run your application compiled as “Release” and using the “Testing” environment name for your .Net Core application, the command would be dotnet run --configuration Release -- --environment Testing.
  • The check-env, describe, and run commands come in from the base Oakton.AspNetCore library. The run command is the default, so dotnet run actually delegates to the run command.
  • All the lamar-******* commands come from Lamar.Diagnostics because Oakton.AspNetCore can happily find and apply commands from other assemblies in the project.
  • We’ll build out sayhello later in this post

Assuming that you are a Lamar (or a StructureMap) user, the first step to unravel most IoC configuration problems is the old WhatDoIHave() method to see what the service registrations are. To get at that data faster, you can use the dotnet run -- lamar-services command just to dump out the WhatDoIHave() output to the console or a text file.

However, adding Lamar.Diagnostics to your application adds some dependencies you may not want to be deployed. With a little help from the .Net Core SDK project system, we can just tell .Net to only use Lamar.Diagnostics at development time by using the <PrivateAssets> tag in the csproj file like this:

<PackageReference Include="Lamar.Diagnostics" Version="1.1.5">


I don’t know how to do that without breaking into the csproj file, but once you do, the Lamar.Diagnostics assembly will not be deployed if you’re using dotnet publish to bundle up your application for deployment.

The “AspNetCore” naming is unfortunately a misnomer, because as of .Net Core 3.* the Oakton extension works for any project configured and bootstrapped with the new generic HostBuilder (purely console applications, worker applications, or any kind of web application).

Now, to add a custom command to the application directly into the application without polluting the deployed application, we’re just using some conditional compilation as shown in this super simple example:

// This is necessary to tell Oakton
// to search this assembly for Oakton commands

namespace OaktonDevelopmentCommands
    // The conditional compilation here just keeps this command from
    // being present in the Release build of the application
    // This is also an OaktonAsyncCommand if you need to 
    // call async APIs
    [Description("I'm a simple command that just starts up the app and says hello")]
    public class SayHelloCommand : OaktonCommand<NetCoreInput>
        public override bool Execute(NetCoreInput input)
            // Super cheesy, just starting up the application
            // and shutting it right down
            using (var host = input.BuildHost())
                // You do have access to the host's underlying
                // IoC provider, and hence to any application service
                // including the compiled IConfiguration as well
                Console.WriteLine("Hey, I can start up the application!");

            // Gotta return true to let Oakton know that the command succeeded
            // This is important if you're using commands that need to report
            // success or failure to the command line.
            return true;

It’s hoke-y, but the command up above will only be compiled into your application if you are compiling as “Debug” — as you generally do when you’re working locally or running tests. When you deploy as a “Release” build, this command won’t be part of the compiled executable. As silly as it looks, this is being very useful in one of my client projects right now.

If you want your OSS project to be successful…

Don’t take any of this too seriously because I wrote this really fast as I was procrastinating instead of working with some ugly legacy code today.

First off, I don’t know why the hell you’d pay attention to me because I’m only middling successful at OSS in terms of the effort I’ve put in over the years to whatever the benefits are. That being said, I do know quite a bit about what not to do, and that’s valuable.

First off, have the right idea and build something that solves some kind of common problem. It helps tremendously if you’re going into some kind of problem area without a lot of existing solutions. My aging StructureMap project was the very first production ready IoC tool for .Net. I seriously doubt it would have been terribly successful if it hadn’t been for that fact. Likewise, Marten has been successful because the idea of Postgresql as a Document Database just makes sense because of Postgresql’s unusually strong JSON support. I can say with some authority that the project concept was appealing because there were 3-4 other nascent OSS projects to do exactly what Marten became a couple years ago.

If you’re trying to go build a better mousetrap and walk into a problem domain with existing solutions, you just need to have some kind of compelling reason for folks to switch over to your tool. My example there would be Serilog. NLog or Log4Net are fine for what they are, but Serilog’s structured logging approach is different and provided some value beyond what the older logging alternatives did.

Try not to compete against some kind of tool from Microsoft itself. That’s just a losing proposition 95% of the time. And maybe realize upfront that the price of a significant success in .Net OSS means that Microsoft will eventually write their own version of whatever it is you’ve done.

Oh, and don’t do OSS at least in the .Net world if you’re trying to increase your professional visibility. I think it’s the other way around, you increase your visibility through talks, blog posts, and articles first. Then your OSS work will likely be more successful with more community visibility and credibility. Other folks might disagree with that, but that’s how I see it and what I’ve experienced myself both in good and bad ways.

If at all possible, dog-food your OSS project on a real work project. I can’t overstate how valuable that is to see how your tool really functions and to ensure it actually solves problems. The feedback cycle between finding a problem and getting it fixed is substantially faster when you’re dog-fooding your OSS project in a codebase where you have control versus getting GitHub issues from other people in code you’re not privy to. Moreover, it’s incredibly useful to see your colleagues using your OSS tool to find out how other folks reason about your tool’s API, try to apply it, and find out where you have usability issues. Lastly, you’re much more likely to have a good understanding of how to solve a technical problem that you actually have in your own projects.

All that being said about dog-fooding however, I’ve frequently used OSS work to teach myself new techniques, design ideas, and technologies.

Be as openly transparent about the project as you can early on and try to attract other contributors. Don’t go dark on a project or strive for perfection before releasing your project or starting to talk about it in public. I partially blame “going dark” prior to the v1.0 release for FubuMVC being such a colossal OSS failure for me. In 2011 I had a pretty packed room at CodeMash for a half day workshop on the very early FubuMVC, but I quit blogging or talking about it much for a couple years after that. When the FubuMVC team got a chance to do present again at CodeMash 2013 for the big v1.0 rollout, there were about a dozen people in the room and I was absolutely crushed.

Or just as valuable, try to get yourself some early adopters to get feedback and more ideas about the direction of the project. Not in terms of downloads and usage per se, but absolutely in terms of the technical achievement and community, Marten is by far and away the most successful OSS project I’ve had anything to do with over the years. A lot of this I would attribute to just having the right concept for a project, but much of that I believe is in how much effort I put into Marten very early on in publicizing it and blogging the project progress early. You know that saying that “with enough eyeballs, all bugs are shallow?” I have no idea if that’s actually true, but I can absolutely state that plenty of early user feedback and involvement has a magical ability to improve the usability of your OSS project.

Contributors come in all different types, and you want as many as you can attract. An eventual core team of contributors and project leaders is invaluable. Pull requests to implement functionality or fix bugs is certainly valuable. Someone who merely watches your project and occasionally points out usability problems or unclear documentation is absolutely helpful. People who take enough time to write useful GitHub issues contribute to projects getting better. Heck, folks who make itty bitty pull requests to improve the wording of the documentation help quite a bit, especially when there’s a bunch of those.

This deserves its own full fledged conversation, but make sure there’s enough README documentation and build automation to get new contributors up and running fast in the codebase. If you’re living in the .Net space, you make sure that folks can just open up Visual Studio.Net (or better IDE tools like JetBrains Rider;) and go. If there is any other kind of environment setup, get that scripted out where a simple “build” or “./” command of some sort or another build out whatever they need to run your code and especially the tests. Docker and docker-compose is turning out to be hugely helpful for this. This might force you to give up your favorite build automation tooling in favor of something mainstream (sorry Rake, I still love you). And don’t be like MS teams used to be and always use all kinds of weird Visual Studio.Net project extensions that aren’t on most folks’s box.

Documentation is unfortunately a big deal. It’s not just a matter of having documentation though, it’s also vital to make that documentation easy to edit and keep up to date because your project will change over time. Years ago I was frequently criticized online for StructureMap having essentially no documentation. As part of the huge (at the time) StructureMap 2.5 release I went and wrote up a ton of documentation with code samples in a big static HTML website. The 2.5 release had some annoying fluent interface APIs that nobody liked (including me), so I started introducing some streamlined API usage in 2.6 that still exists in the latest StructureMap (and Lamar) — which was great, except now the documentation was all out of date and people really laid into me online about that for years.

That horrendous experience with the StructureMap documentation led to me now having some personal rules for how I approach the technical documentation on ongoing OSS projects:

  1. Make the project documentation website quick to re-publish because it’s going to change over time. Your best hope to keeping documentation up to date is to make it as painless as possible to update and publish documentation updates
  2. Just give up and author your documentation in markdown one way or another because most developers at this point understand it
  3. Embed code samples in the documentation in some sort of way where they can be kept up to date
  4. As silly as it may sound, use some kind of “Edit me on GitHub” link in each page in your documentation website that let’s random people quickly whip up little pull requests to improve the documentation. You have no idea how helpful that’s been to me over the past 3-4 years.
  5. Make it easy to update and preview the documentation website locally. That helps tremendously for other folks making little contributions.

There are other solutions for the living documentation idea, but all of the projects I’m involved with use the Storyteller “stdocs” tooling (which I of course wrote over years of dog-fooding:)) to manage “living documentation” websites.

Try to be responsive to user problems and questions. This is a “do as I say, not as I do” kind of thing because I can frequently be slow to acknowledge GitHub issues or questions at times. Just letting them know that “I saw this” can buy you some good will. Try to be cool in the face of folks being assholes to you online. Remember that interactions and folks generally come off worse online than they would in real life with body language cues, and also remember that you’re generally dealing with people when they’re already frustrated.

Assuming that your project is on GitHub, I highly recommend Gitter as a way to communicate with users. I find the two way communication a lot faster to help unwind user problems compared to working asynchronously in GitHub issues.



Fast Build, Slow Build, and the Testing Pyramid

At Calavista we’ve been helping a couple of our clients use Selenium for automated testing of web applications. For one client we’re slowly introducing a slightly different, but still .Net-focused technical stack that allows for much more effective test automation without having to resort to quite so many Selenium tests. For another client we’re trying to help them optimize the execution time of their large Selenium test suite.

At this point, they’re only running the Selenium test suite in a scheduled run overnight, with their testers and developers needing to deal with any test failures the next day. Ideally, they want to get to the point where developers could optionally execute either the whole suite or a targeted subset of the Selenium tests on their own development branches whenever they want.

I think it’s unlikely that we’ll get the full Selenium test suite to where it executes fast enough that a developer would be willing to run those tests as part of their normal “check in dance” routine. To thread the needle a bit between letting a developer get quick feedback from their own local builds or the main continuous integration builds and the desire to run the Selenium suite much more often for faster feedback, we’re suggesting they split the build activity up with what I’ve frequently seen called the “fast build, slow build” pattern (I couldn’t find anybody to attribute this to tonight as I wrote this, but I can’t take credit for it).

First off, let’s assume your project is following the idea of the “testing pyramid” one way or another such that your automated tests probably fall into one of three broad categories:

  1. Unit tests that don’t touch the database or other external services so they generally run pretty quickly. This would probably include things like business logic rules or validation rules.
  2. Integration tests that test a subset of the system and frequently use databases or other external services. HTTP contract tests are another example.
  3. End to end tests that almost inevitably run slowly compared to other types of tests. Selenium tests are notoriously slow and are the obvious example here.

The general idea is to segment the automated build something like this:

  1. Local developer’s build — You might only choose to compile the code and run fast unit tests as a check before you try to push commits to a GitHub/BitBucket/Azure DevOps/whatever you happen to be using branch. If the integration tests in item #2 are fast enough, you might include them in this step. At times, I’ve divided a local build script into “full” and “fast” modes so I can easily choose how much to run at one time for local commits versus any kind of push (I’m obviously assuming that everybody uses Git by this point, so I apologize if the Git-centric terminology isn’t helpful here).
  2. The CI “fast build” — You’d run a superset of the local developer’s build, but add the integration tests that run reasonably quickly and maybe a small smattering of the end to end tests. This is the “fast build” to give the developer reasonable assurance that their push built successfully and didn’t break anything
  3. The CI “slow build” of the rest of the end to end tests. This build would be triggered as a cascading build by the success of the “fast build” on the build server. The “slow build” wouldn’t necessarily be executed for every single push to source control, but there would at least be much more granularity in the tracking from build results to the commits picked up by the “slow build” execution. The feedback from these tests would also be much more timely than running overnight. The segregation into the “fast build / slow build” split allows developers not to be stuck waiting for long test runs before they can check in or continue working, but still get some reasonable feedback cycle from those bigger, slower, end to end tests.



Standing up a local Sql Server development DB w/ Bullseye, Docker, and Roundhouse

EDIT 3/26: I added the code that delegates to the Sql Server CLI tools in Docker

For one of our Calavista engagements we’re working with a client who has a deep technical investment in Sql Server with their database migrations authored in RoundHousE. The existing project automation depended on Sql Express for standing up local development and testing databases, with some manual set up steps in a Wiki page before you could successfully clone and run the application locally.

As we’ve started to introduce some newer technologies to this client’s web development ecosystem, there was an opportunity to improve what my former colleague Chad Myers used to call the “time to login screen” metric — how long does it take a new developer from making their first initial clone of a codebase to being able to run the system locally on their development box? Being somewhat selfish because I prefer to develop on OS X these days, I opted for running the local development database in Docker instead of Sql Express.

Fortunately, you can quickly stand up Sql Server quickly in a Linux container now. Here’s a sample docker-compose.yaml file we’re using:

version: '3'
    image: "microsoft/mssql-server-linux:2017-latest"
    container_name: "Descriptive Container Name"
     - "1433:1433"
     - "ACCEPT_EULA=Y"
     - "SA_PASSWORD=P@55w0rd"
     - "MSSQL_PID=Developer"

That’s step 1, but there’s a little bit more we needed to do to stand up a local database (actually two databases):

  1. Provision a new database server
  2. Create two named databases
  3. Run the RoundHousE database migrations to bring the database up to the current version

So now let’s step into the realm of project automation scripting. I unilaterally chose to use Bullseye for build scripting because of the positive experience the Marten team had when we migrated the Marten build from Rake to Bullseye. Using Bullseye where you’re just writing C#, we have this task:

Target("init-db", () =>
    // This verifies that the docker instance
    // defined in docker-compose.yaml is up
    // and running
    Run("docker-compose", "up -d");

    // The command above is asynchronous, so wait
    // until Sql Server is responsive

    // Create the two databases
    CreateDatabase("Database Name #1");
    CreateDatabase("Database Name #2");

    // Run RoundHousE to apply the latest database migrations
    Run("dotnet", "tool update -g dotnet-roundhouse");

To flesh this out a little more, the Sql Server Docker image embeds some of the Sql Server command line tools in the image, so we were able to create the new named databases like this:

        // No points for style!!!
        private static void WaitForSqlServerToBeReady()
            var attempt = 0;
            while (attempt < 10)
                    using (var conn = new SqlConnection(DockerConnectionString))
                        Console.WriteLine("Sql Server is up and ready!");
                catch (Exception)

The CreateDatabase() method just delegates to the sqlcmd tool within the Docker container like this (the Run() method comes from SimpleExec):

        private static void CreateDatabase(string databaseName)
                    $"exec -it SurveySqlServer /opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P \"{SqlServerPassword}\" -Q \"CREATE DATABASE {databaseName}\"");
            catch (Exception e)
                Console.WriteLine($"Could not create database '{databaseName}': {e.Message}");

It was a lot of Googling for very few lines of code, but once it was done, voilà, you’ve got a completely functional Sql Server database for local development and testing. Even better yet, it’s super easy to turn development database on and off when I switch between different projects by just stopping and starting Docker images.

It’s an OSS Nuget Release Party! (Jasper v1.0, Lamar, Alba, Oakton)

My bandwidth for OSS work has been about zero for the past couple months. With the COVID-19 measures drastically reducing my commute and driving kids to school time, getting to actually use some of my projects at work, and a threat from an early adopter to give up on Jasper if I didn’t get something out soon, I suddenly went active again and got quite a bit of backlog things, pull requests, and bug fixes out.

My main focus in terms of OSS development for the past 3-4 years has been a big project called “Jasper” that was originally going to be a modernized .Net Core successor to FubuMVC. Just by way of explanation, Jasper, MO is my ancestral hometown and all the other projects I’m mentioning here are named after either other small towns or landmarks around the titular “Jasper.”


Alba is a library for HTTP contract testing with ASP.Net Core endpoints. It does quite a bit to reduce the repetitive code from using TestServer by itself in tests and makes your tests be much more declarative and intention revealing. Alba v3.1.1 was released a couple weeks ago to address a problem exposing the application’s IServiceProvider from the Alba SystemUnderTest. Fortunately for once, I caught this one myself while dogfooding Alba on a project at work.

Alba originated with the code we used to test FubuMVC HTTP behavior back in the day, but was modernized to work with ASP.Net Core instead of OWIN, and later retrofitted to just use TestServer under the covers.


Baseline is a grab bag of utility code and extension methods on common .Net types that you can’t believe is missing from the BCL, most of which is originally descended from FubuCore.

As an ancillary project, I ripped out the type scanning and assembly finding code from Lamar into a separate BaselineTypeDiscovery Nuget that’s used by most of the other libraries in this post. There was a pretty significant pull request in the latest BaselineTypeDiscovery v1.1.0 release that should improve the application start up time for folks that use Lamar to discover assemblies in their application.


Oakton is a command parsing library for .Net that was lifted originally from FubuCore that is used by Jasper. Oakton v2.0.4 and Oakton.AspNetCore v2.1.3 just upgrade the assembly discovery features to use the newer BaselineTypeDiscovery release above.


Lamar is a modern, fast, ASP.Net Core compliant IoC container and the successor to StructureMap. I let a pretty good backlog of issues and pull requests amass, so I took some time yesterday to burn that down and the result is Lamar v4.2. This release upgrades the type scanning, fixes some bugs, and added quite a few fixes to the documentation website.


Jasper at this point is a command executor ala MediatR (but much more ambitious) and a lightweight messaging framework — but the external messaging will mature much more in subsequent releases.

This feels remarkably anti-climactic seeing as how it’s been my main focus for years, but I pushed Jasper v1.0 today, specifically for some early adopters. The documentation is updated here. There’s also an up to date repository of samples that should grow. I’ll make a much bigger deal out of Jasper when I make the v1.1 or v2.0 release sometime after the Coronavirus has receded and my bandwidth slash ambition level is higher. For right now I’m just wanting to get some feedback from early users and let them beat it up.


There’s nothing new to say from me about Marten here except that my focus on Jasper has kept me from contributing too much to Marten. With Jasper v1.0 out, I’ll shortly (and finally) turn my attention to helping with the long planned Marten v4 release. For a little bit of synergy, part of my plans there is to use Jasper for some of the advanced Marten event store functionality we’re planning.







.Net Core Backend + React.js Frontend — Optimizing the development time experience

I’ve seen some chatter on Twitter this week that the enforced home time due to the Coronavirus will lead to much more blogging and OSS activity. Hopefully all the social distance measures work out and we’ll have time and energy to be concerned about relatively unimportant things like software development in the weeks to come. Or maybe this kind of thing is just a nice distraction.

As a follow up to my last post a while back titled Choosing a “Modern” React.js + .Net Core Stack, I want to talk about how our team is trying to create a productive development time experience for working with both the React.js frontend and the .Net Core backend. In this case we’re really building out a replacement for a large feature in an existing ASP.Net MVC application, so even though we’ve opted for a brand new ASP.Net Core backend for the new feature, we’ve got to play nice with the existing application. To that end, out new React.js bundle is going to be hosted in production by the existing MVC5 application in a minimalistic Razor page (really just the inevitable <div id="main" /> tag and a <script /> tag that serves up the Javascript bundle. I should also point out that the React.js bundle is created at build time in the CI/CD pipelines by Parcel.js.

All that being said, the production time architecture simply looks like this, with the production database, the existing MVC5 web application, and our new ASP.Net Core service all being hosted on Azure:


So that’s in production, but at development time we need to have a little different configuration. After a couple iterations, our development time model for running the application locally looks like this:


I feel strongly that most development tasks can and should be done with a test driven development approach (but I’m not demanding any kind of test-first purity as long as the tests are actually written concurrently with new code) — especially on the .Net backend side. Even quite a bit of the React.js components and any other Javascript code can be written inside of unit testing cycles using the Jest watch mode.

However, there’s still a lot of times when you want to run the application to see the user interface itself and work on the interactions between the full stack. To that end we did want a configuration that allowed developers to run everything locally on their own development box.

Since I’m a big believer in “per developer development databases,” I set up a little bit of project automation with Bullseye to spin up Sql Server in a Docker container, provision the application databases with the existing RoundHousE migrations, and add some sample data as necessary. I’ll write a separate blog post someday (maybe) about this because I thought it came together pretty smoothly, but you still had to piece things together across a lot of disjointed blog posts and online documentation.

Running the .Net Core backend locally is easy with ASP.Net Core. Using the Oakton.AspNetCore command line extensions, we can spin up the application at the command line or an IDE run configuration with dotnet run -- -e Development to run the application in “development” mode with configuration pointing at local resources (i.e., appsettings.Development.json).

Running the front end React.js code was a little trickier in our case because of its reliance on so much server side state. We very initially used hard-coded JSON data in the React.js code itself to get started, but we quickly outgrew that. We later kicked the tires on stand in API tools like json-server. In the end, we opted to run the real backing API web service when working with the React.js application to avoid having any incompatibilities between a fake web service and the real thing. I don’t know that I’d opt to make that same decision in every case, but I think it’s going to work out in this one.

For UI development, I’m a huge fan of using React.js’s hot module replacement mode for quick change loop / feedback cycles at development time. Using Parcel.js’s development server, you can serve up your React.js bundle in a minimal HTML page where the React.js components are automatically rebuilt and refreshed on the page while maintaining the existing state of the application whenever the backing code files are changed.

As a hot tip though, if you’re going to try to use the hot replacement mode while also talking to a local ASP.Net Core, disable the HTTPS support in development mode on the .Net side of things. I found that it knocks out the websockets communication that Parcel.js uses to reload the React.js components.

Using Dotenv for Javascript Environment Variables

One of the first issues we faced was that the API’s URL location is different locally versus in production mode, and the code that made HTTP calls in the React.js bundle needed to be aware of that. Fortunately, we’re using Parcel.js and it has out of the box support for the dotenv library to support the idea of environment variables within the Javascript bundled code for configuration items like the base url of our backing web service.

The environment variables are defined in text files with the naming convention `.env.[profile]`. For the “development” mode, we added a file parallel to the package.json file called .env.developmentthat consists for now of just this line:


When you run the Parcel.js development server with the hot module replacement, it uses the “development” profile and the value of “BASE_URL” in the file above will be embedded into the bundled Javascript accessible from the global process.env object.

In the Javascript file in our React.js bundle that makes HTTP calls to the backend service, we lookup the base url for the backend service like this:

var baseUrl = '';

// dotenv places the values from the file above
// into the "process.env" object at build time
if (process.env.BASE_URL){
    baseUrl = process.env.BASE_URL;


There’s still some ongoing work around security via JWT tokens, but right now we’re able to run the React.js bundle in the hot replacement mode, but still connect to the locally running ASP.Net Core web service and I’m happy with the development experience so far.

Choosing a “Modern” React.js + .Net Core Stack

This is really just preparation for a meeting tomorrow and I haven’t blogged much lately. Also, I had to write this way, way too late at night and the grammar probably shows that:/ I’m happy to take any kind of feedback, mockery, or questions.

One of our Calavista development teams and I are having a kind of kickoff meeting tomorrow morning to discuss our new technical stack that we plan to use for some big new customer-facing features in a large web application this year. The current application we’re building onto was originally designed about a decade ago and uses a lot of the .Net tools and approaches that I myself would have espoused at that time and even a few OSS things that I helped build — but some of which are clearly aluminum wiring today (RIP K. Scott Allen) or at least have been surpassed by later tools.

First off, we’ve got a couple constraints:

  1. .Net for the backend
  2. Sql Server as the database (but with perfect control on a greenfield project I’d obviously opt for Marten + Postgresql 😉
  3. We can’t rewrite or update the very large application all at one time because of course we can’t
  4. The “new” stack still has to cooperate with the “old” stack
  5. Azure hosting
  6. Bootstrap styling

And, what we need and/or want in a new technical stack:

  • The ability to craft very good user experiences in the new features
  • Better testability all the way through the technical architecture. We have to depend much more on Selenium testing than I prefer, and I’d like to see much more of a balanced test pyramid / test funnel distribution of tests. At the bottom of this post is a brief explanation of why I’m leery of too much Selenium usage.
  • Good feedback cycles for the developers doing the front end work
  • Fairly mainstream tools as much as possible so our client can more easily deal with the system after we’re gone
  • A way to incorporate the new technology into the existing system with minimal disruption to the current state and without the users being aware of the technical sausage making (other than hopefully some better usability and richer features).

The Proposed “New” Stack

For a variety of reasons, we’re moving to using React.js for the client side backed by an ASP.Net Core “backend for frontend” service that will mostly be zapping JSON back and forth as an API.

On the server side, we’re going with:

  • ASP.Net Core 3.*. Probably with MVC Core for API endpoints, but I’m voting to use it in the lightest possible way. Our client wants to do this anyway, but I’ve been pushing it for awhile because of the easier build automation, testability, faster builds and throughput, and honestly because I want to code on OS X and not have to use my Windows VM;-)
  • I’m probably not willing to use any kind of “Mediator tool” because I think it’s unnecessary complexity, but we might pull in Jasper for any kind of asynchronous messaging or just plain asynchronous work through it’s local command bus
  • Entity Framework Core. Using Sql Server is a constraint, I’m not particularly a fan of Dapper, I don’t mind EF Core, it’s very commonly used now, and it’s what the development team wants to use. If we can get away with it, I want to use EF Core’s migrations support to create development databases on the fly for rapid prototyping and development throughput. If you’re old enough to remember that I was one of the authors of the EF Vote of No Confidence, I’d say that EF Core is a perfectly fine heavy ORM if that’s what you need and EF has left behind all the design decisions from EF v1 that we so strenuously disagreed with way back when.
  • We will also not be using any Azure tool that cannot be executed on a local developer box. So, using Azure Service Bus that you can connect to locally is fine, but weird serverless tools that can only be run on Azure are absolutely off the table as long as I have a say in anything.

The one place where we’ll deviate from what I guess is mainstream MVC Core is to absolutely ditch any kind of leftover Ruby on Rails Models/Views/Controllers folder and/or namespace layout. I’m very much in favor of using a “feature folder” organization where closely related classes/services/DTOs for a use case live in the same namespace instead of being scattered all over God’s green earth. Moreover, I’m dead set against any kind of “Onion Architecture” code organization, but that’s a rant for another day.

More interestingly, on the client side we’ve rewritten an existing feature in the application with a new “React Stack” that we plan to start with:

  • React.js vLatest. I’ve been mostly out of React.js for a few years, and I’ve been pretty happy with the improvements since I built Storyteller 3.0 with React v11. I really like React Hooks even though I didn’t really understand them well when they were brewing a couple years ago.
  • Parcel.js. ZOMG, Parcel.js is so much easier to get up and going that Webpack.js was a couple years ago. I’m absolutely sold. I think the hot module replacement ability in React.js is a killer feature and a huge advantage over trying to do complex user interfaces in MVC + Razor because of the vastly better feedback cycle, but it used to be a nightmare to get up and going with Webpack.js (IMO). It basically comes out of the box with Parcel.js.
  • React-Bootstrap. The existing application is based around Bootstrap anyway, and using this library instantly gives us a consistently styled application with the rest of the application. Plus it’s a pretty rich out of the box component library.
  • Redux and React-Redux for state management. I had good results with these tools before, and I don’t see any compelling reason to move to something else or to do without.
  • I don’t think we’ll use TypeScript, but I’m not opposed if the team wants to do that. I don’t see much advantage for React components, but maybe for Redux reducer code
  • I played some with Redux middleware and I’m at least intrigued by react-api-middleware, but we might just stick with simple axios usage.

More on the testing tools in a later section because that’s a crucial part of all of this.


Integrating the New with the Old

I’m going to stop using the word “microservice” with our client because that apparently conjures up visions of hopeless complexity. Instead, we’re starting a new stack off to the side for new features that may also become a strangler application that eventually takes over the existing functionality.

All the same though, there’s much less literature about microservices in an conglomerate user interface application than there is on backend services. We’re initially going down a path of running our new React.js feature bundles inside the existing application’s Razor layout in an architecture something like this:



For new features, we’ll keep to the existing navigation structure and application look and feel by just adding new Razor pages that do nothing but embed a small Razor application like so:

@model Application.Feature1.ViewModel
    ViewBag.Title = "Feature Title";

<link rel="stylesheet" type="text/css" href="~/assets/feature_bundle.css">

<div id="main"></div>

There’s some details to work out around security, API gateways, and the like — but the hope is to have the React.js mini-applications completely communicating with a new ASP.Net Core “BFF” API.

I’m hoping there’s not a lot of overlap in the necessary database data between the old and the new worlds, but I’m prepared to be wrong. Our current thinking is that we’ll *gasp* keep using the old database, but keep a new schema to isolate the new tables. Right now my working theory is that we’ll have a background queue to synchronize any “writes” to the new database schema to the old database if that proves to be necessary.


Testing Approach

Alright, the part of this that I’m most passionate about. I’ve written before about my personal philosophy for automated testing in Jeremy’s Only Law of Testing (Test with the finest grained mechanism that tells you something important) and Succeeding with Automated Integration Tests. I think that both React.js + Redux and ASP.Net Core have good testability stories, especially compared to the MVC5 + Razor stack we’re using today. React.js + Redux because there are great tools for fast running unit tests against the client side code that isn’t really feasible with Razor — and especially now that there are effective ways to test React components without needing to use real browsers with Karma (shudder). ASP.Net Core because you can run your application in process, there’s some decent testing support for HTTP contract testing, and it’s far more modular than ASP.Net MVC pre-Core was.

Looking at another low fidelity view of the proposed architecture just to demonstrate how the new testing pyramid should go:


We’ll probably use xUnit.Net instead of NUnit, but at the time I drew this diagram I thought we’d have less control over things.

With this stack, our testing pyramid approach would be:

  • Unit tests as appropriate and useful for the .Net code in the backend, with a focus on isolating business logic from infrastructure using techniques described in Jim Shore’s Testing Without Mocks article — which is a fantastic paper about designing for testability in my opinion.
  • Use Alba (wraps TestServer) to execute integrated HTTP tests against the entire MVC Core stack
  • We’ll probably use Storyteller for acceptance tests when we hit some very data intensive business logic that I know is coming up this year
  • Possibly use Docker to run little isolated Sql Server databases for testing something like this approach
  • At least smoke tests against the React.js components with Jest and react-testing-library (I think I came down on preferring its approach to Enzyme). I’m going to prefer some real unit tests on the behavior of the components using react-testing-library.
  • Jest unit tests against the state tracking logic in the Redux store and reducers.
  • Use moxios for testing the interaction with the backend from the JS code?
  • I had some success in the past writing tests that combined the Redux store, the react-redux bindings, and the React components in more coarse grained integration tests that flush out problems that little unit tests can’t
  • And just a modicum of new Selenium tests just to feel safe about the end to end integration between the React client and the ASP.Net Core server



Why Not….?

  • Angular.js? Ick, no.
  • Vue.js? I think Vue.js sounds perfectly viable, but the team and I have prior experience with React.js and the existing ecosystem of components matters
  • GraphQL? I don’t see it as applicable to this application
  • Alternative web frameworks in .Net Core? Not unless it’s my own;)
  • Dapper? Meh from me.
  • Blazor? This one is a little more serious conversation because the client asked us about it. My feeling is that it’s not quite ready for prime time, doesn’t have much of an ecosystem yet, nobody is familiar with it yet, and we’d lose that awesome hot module replacement feedback cycle in React.js


Why am I down on Selenium?

I spent all my summers in High School and College working on my Dad’s house framing crew. And as any framer knows, the “Sawzall” is the one tool that will always be able to get you out of a jam when you can’t possibly utilize any other kind of saw — but it’s never your first choice of tool and it generally only came out when something was put together wrongly.



Selenium is the Sawzall of automated software testing (at least in web applications). It’s almost never the first choice of testing tool, but if you didn’t architect for testability, it’s your last resort because it can always work by driving the entire stack through the browser.

It’s also:

  • Slow to execute
  • Laborious to do well in more complex applications — especially when there’s asynchronous behavior in the user interface
  • Frequently flake-y because of the asynchronous behavior
  • Brittle when the user interface is evolving
  • Hard to debug failures because you’re testing the whole damn system

In summary, Selenium is what you use when nothing else can work but never your first choice of approach.

Lamar 4.1: Multithreading improvements, diagnostics, documentation updates, and some thoughts on troubleshooting

As promised in my previous post My (Big) OSS Plans for 2020, the very first thing out the gate for me this year is a bug fix release for Lamar.

Lamar 4.1 and its related libraries was released on Nuget late last week with a variety of bug fixes, a couple new features, and a documentation refresh at — including some new guidance here and there as a direct reaction to GitHub issues. Continuing my personal theme of OSS interactions being more positive than not over the past couple years, I received a lot of help from Lamar users. This release was largely the result of users submitting pull requests with fixes or failing unit tests that reproduced issues — and I cannot stress enough how helpful those reproduction tests are for an OSS maintainer. Another user took the time to investigate how an error message could be greatly improved. Thank you to all the users who helped on this release with pull requests, suggestions, and feedback on GitHub.

All told, the libraries updated are:

  • Lamar 4.1.0 — Multi-threading issues were finally addressed, fixes for Lamar + ASP.Net Core logging, some finer grained control over type scanning registrations
  • Lamar.Microsoft.DependencyInjection v4.1.0 — Adds support back for IWebHostBuilder for .Net Core 3.0 applications
  • Lamar.Diagnostics v1.1.3 — More on this one below
  • LamarCompiler 2.1.1 — Just updated the Roslyn dependencies. Lamar itself doesn’t use this, so you’re very unlikely to be impacted
  • LamarCodeGeneration v1.4.0 — Some small additions to support a couple Jasper use cases
  • LamarCodeGeneration.Commands v1.0.2 — This isn’t documented yet, and is really just to support some diagnostics and pre-generation of code for Jasper


A Note on Troubleshooting

I have a partially written blog post slash treatise on troubleshooting and debugging. One of the things I try to suggest when troubleshooting a technical issue is to come up with a series of theories about why something isn’t working and figuring out the quickest way to prove or disprove that theory.

In the case of Lamar’s multi-threading issues addressed in this release and a very similar issue fixed previously, the “obvious” theory was that somewhere there was some issue with data structures or locking. Myself and several others tried to investigate Lamar’s internals down this path, but came up empty handed.

The actual root cause turned out to be related to the Expression construction and compilation inside of Lamar that allowed variables to bleed through threads in heavily multi-threaded usage.

So, I still think that my idea of “build a theory about why something is failing, then try to knock it down” is a good approach, but not 100% effective. I’m adding a section to that blog post entitled “don’t get tunnel vision” and talk about fixating on one theory and not considering other explanations;-)

Then again, some things are just hard some time.


Back in October I blogged about the new Oakton.AspNetCore package that extends the command line capabilities of standard .Net Core / ASP.Net Core applications with additional diagnostics. As a drop in extension to Oakton.AspNetCore, the new Lamar.Diagnostics package can be installed into a .Net Core application to give you ready access to all of Lamar’s built in diagnostics through the command line.

Your newly available commands from the root of your project with Lamar.Diagnostics are:

  1. dotnet run -- lamar-services — prints out the Container.WhatDoIHave() output to the console or a designated file
  2. dotnet run -- lamar-scanning — prints out the Container.WhatDidIScan() output to the console or a designated file
  3. dotnet run -- lamar-validate — runs the Container.AssertConfigurationIsValid() command

You can also opt into Lamar’s built in environment tests being used through Oakton.AspNetCore’s environment check capability.

In all cases, these commands work by calling IHostBuilder.Build() to build up your application — but doesn’t call Start() so none of your IHostedService objects will run — and calls the underlying Container methods. By doing this, you get ready access to the Lamar diagnostics against your application exacstly the way that your applicaiton is configured, without you having to add any additional code to your system to get at this diagnostic information.