Good luck out there!

Sources

A-Frame Architecture with Wolverine

James Shore A-Frame Architecture

Wolverine Docs

Integration testing in dotnet

TUnit

As far as test setup goes, there is no clear winner for a test framework. xUnit.NET, NUnit and the newcomer TUnit are all dependable frameworks. Personally, I like xUnit for their terminology with Fact and Theory, yet the newcomer TUnit is quickly capturing my interest with some interesting features. I've used it here to encourage everybody (including me) to keep experimenting and learning.

I have similar thoughts on assertion and mocking libraries. There are no bad choices. They’re just tools to get the job done. Pick one and use it as long as it is useful.

Unit tests

The logic code is the easiest to test with standard unit tests. These tests will verify all scenarios that the software needs to support. Since there is no infrastructure setup required, these tests are easy to read and fairly straightforward. Since unit tests are pretty cheap (quick) to run, I’ll write a lot of them to cover all scenarios.

Instantiating the system under test is nothing more than creating a new instance of the class. Here I see the first A-Frame benefit: by limiting the number of services to inject, I can simplify my test setup. When there are no systems to prepare and ensure they return the correct data in the correct circumstances, it takes a gigantic load off my shoulders when preparing my tests.

All injections happen in the Handle function. Keep injected data simple and specific to the case under test. In this case, I create a default _walk that I pass to the function or that can serve as an object mother that I modify to the needs of the test. The _otherWalk is similar to the _walk object, but with another dog that crossed paths with ours. The Func<byte[]> is an easily stubbed method that captures whether the function has been called. Should the need arise, returning different data is now trivial.

While the date is irrelevant for this code, it is a good example to keep mutable calls out of the logic component. Testing with specific dates has been a challenge in the past as there could be a hardcoded DateTimeOffset.Now present. It is possible to replace that with the TimeProvider. I prefer simply passing the date to the test instead of setting up another system.

The result of the logic tells me what it expects to happen. I don't need to start checking multiple mocks and stubs, simple asserts are enough. While there is a mock here, it is only one and not multiple. I find that the result is transparent to interpret.

[Test]
public async Task When_other_dog_encountered_then_do_indicate_dog_encountered()
{
    var getPictureCalled = false;
    var (result, outgoingMessages, entityFrameworkInsert) = new MetFriendsHandler().Handle(
        _walk,
        [_otherWalk],
        () =>
        {
            getPictureCalled = true;
            return [];
        },
        DateTimeOffset.Now);

    await Assert.That(result).IsEquivalentTo(Results.Ok(new FriendsResponse(["Toby"], [])));
    var friends = outgoingMessages.ShouldHaveMessageOfType<MetFriends>().Friends;
    await Assert.That(friends).IsNotEmpty().And.Contains("Toby");
    await Assert.That(entityFrameworkInsert).IsNotNull();
    await Assert.That(getPictureCalled).IsTrue();
}

Integration tests

Now that I've tackled the easy part, let's look at the complex part. Infrastructure code is not easy to test, no matter how I twist or turn it. I've tried mocking it out, I've tried using the Entity Framework in-memory database, I've tried sacrificing managers to the god Maniae. This is where integration tests shine. These tests verify how your system responds to actual external system behaviour. They're slower than unit tests, so focus on the most critical scenarios while using unit tests for edge cases.

Integration tests run (as close to) actual systems. This means starting your application in a web server, talking to a real database and sending requests to external systems over the network. To run the web server in-memory, I use the WebApplicationFactory. This is what I did in my basic (and honestly, quite useless) integration test. In more complex scenarios, I use a library such as Alba or Playwright.

Don't try to simulate the database. I create a local test database in a container or spin up a lightweight database in my CI/CD pipeline. Test containers can be quite convenient, but they take some time to start. I run my migration scripts, then I test against that database. This way, I ensure that my migration scripts work on the database. Another system that works as expected. To reset a database to a known good point, I use Respawn. I prefer resetting the database before each test run. This ensures a clean database before each test, which populates it with just the necessary data and eliminates a previous test from influencing another. After a test fails, I have access to the data to debug efficiently.

Write to the local file system when integration testing. In a CI/CD environment, my tests run in a container that gets disposed of afterwards. This is a good environment to try writes as the data gets discarded after every run. I can even publish the test output as an artefact if I want to inspect it afterwards.

The only time I mock, fake or stub interfaces is when I work with external services. To get realistic responses, I call each system with test data. I prefer doing this with a test system, but I will use the real API if I have no other option. In the last case, I'll never do that unannounced. I'll get in touch with the external services team to coordinate a moment and specify which data I’ll send. In all cases I keep the requests and the responses. I use both good and bad responses in my integration tests, so my system is prepared for all possible scenarios.

Practically, I try to mock, fake or stub the HttpClient to get control of its return values. WireMock.NET can come in quite handy in these scenarios. If I use libraries such as Refit, RestSharp or Flurl, I'll use their built-in test support.

[ClassDataSource<WebAppFactory>(Shared = SharedType.PerTestSession)]
public class MetFriendsIntegrationTests(WebAppFactory webAppFactory)
{
    [Test]
    public async Task Get_response_bad_request()
    {
        var client = webAppFactory.CreateClient();

        using var response = await client.GetAsync("/friends/1");

        await Assert.That(response.StatusCode).IsEqualTo(HttpStatusCode.NotFound);
    }
}

public class WebAppFactory : WebApplicationFactory<Program>, IAsyncInitializer
{
    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        // let Oakton accept --environment variables
        OaktonEnvironment.AutoStartHost = true;

        // disable all external setup so the integration tests don't start sending out messages
        builder.ConfigureTestServices(services => services.DisableAllExternalWolverineTransports());
    }

    public Task InitializeAsync()
    {
        // Grab a reference to the server
        // This forces it to initialise.
        // By doing it within this method, it's thread safe.
        // And avoids multiple initialisations from different tests if parallelisation is switched on
        _ = Server;
        return Task.CompletedTask;
    }
}

Next up, the last post in this series: my closing thoughts on A-Frame architecture.

1. I need multiple pieces of data from different sources

2. I need to perform an infrastructure call in the middle of a logic component

3. I need to do different infrastructure calls based on the decisions taken by my logic code

1. Multiple pieces of infrastructure data

When multiple objects need to be loaded, the Load method can return a tuple. Wolverine injects each object separately in the Validate and Handle methods. The Load function returns the dogs from the database, an image from the web and the current date from the system clock as a Tuple. Wolverine will inject the list of dogs, the picture and the date correctly into the Validate and Handle methods. If different functions require different objects, they only need to specify which data they require. Wolverine will even resolve the services such as the IWatermarkService from the dependency injection framework.

public async Task<(List<Dog> dogs, Image picture, DateTimeOffset now)> LoadAsync(/* dependencies go here */) 
{
    // infrastructure code goes here
    return (dogsFromDatabase, pictureFromTheWeb, DateTimeOffset.Now);
}

public ProblemDetails Validate(List<Dog> dogs, DateTimeOffset now)
{
    // validation code goes here
    return WolverineContinue.NoProblems;
}

public DogDto Handle(List<Dog> dogs, Image picture, DateTimeOffset now, IWatermarkService watermark)
{
    // logic code goes here
}

2. Infrastructure calls in the middle of logic code

The easiest solution is to avoid this scenario. Try to structure the logic code differently so that the infrastructure code can load all data that upfront.

There are situations where I don't want to incur the upfront cost. For example, when there is a chance that the data isn't necessary and the load puts the system under stress. In such cases, I can inject infrastructure code into the logic component. This does not need to mean that I'm back to square one of injecting an interface or DbContext into my Handle method.

Func<> can be returned from the Load method. Thus delegating the execution to a later time. I get the benefits that the infrastructure code prepares the call, and I get an immutable way of testing my logic as I can replace the Func<> with a simple test stub.

public async
    Task<(WalkWithDogs? Walk, List<WalkWithDogs> OtherWalks, Func<byte[]> GetPictureAsync, DateTimeOffset Now)>
    LoadAsync(int walkId, DogWalkingContext db)
{
    var walk = await db.WalksWithDogs.Include(w => w.Dogs).FirstOrDefaultAsync(w => w.Id == walkId);
    var dogsInWalk = walk?.Dogs.Select(d => d.Id).ToArray() ?? [];
    var otherWalks = await db.WalksWithDogs.Include(w => w.Dogs)
        .Where(w => !w.Dogs.Any(d => dogsInWalk.Contains(d.Id)))
        .ToListAsync();
    var getPicture = () =>
    {
        var stream = Assembly.GetExecutingAssembly().GetManifestResourceStream("MoreThanCode.AFrameExample.Yuna.jpg");
        if (stream == null)
            return [];
        stream.Seek(0, SeekOrigin.Begin);
        byte[] image = new byte[stream.Length];
        stream.ReadExactly(image);
        return image;
    };
    return (walk, otherWalks, getPicture, DateTimeOffset.Now);
}

[WolverineGet("/friends/{walkId}", OperationId = "Friends-On-Walk")]
[Tags("MoreThanCode.AFrameExample")]
public IResult Handle(
    WalkWithDogs walk,
    List<WalkWithDogs> otherWalksAtSameTime,
    Func<byte[]> getPicture,
    DateTimeOffset now,
    Watermark watermarkService)
{
    if (!otherWalksAtSameTime.Any())
        return Results.Empty;

    var friends = otherWalksAtSameTime.SelectMany(w => w.Dogs)
                    .Except(walk.Dogs)
                    .Select(d => d.Name)
                    .ToArray();

    FriendsResponse response = friends.Length == 0 
        ? new([], []) 
        : new(friends, watermarkService.Add(getPicture()));

    return Results.Ok(response);
}

3. Complex return instructions

What if I want to save the walk back to the database, write the picture to disk and publish additional messages? For these purposes, Wolverine has cascading messages and ISideEffects.

Although there are other ways to return cascading messages, I prefer to work with the OutgoingMessages response type. This way I can return none, one or multiple messages based on the decisions of my logic. Wolverine will publish these messages to the bus according to the configured routing information. It's also possible to schedule or delay messages if needed. All these messages will benefit from built-in resiliency mechanisms.

Infrastructure operations that are part of the scope of the handler are best implemented as side effects. Common side effects are saving to the database and writing to disk. For this, there is the ISideEffect marker interface that expects an Execute function to be available. This function is not present on the interface as the input can accept parameters resolved from dependency injection, just like the Handle function discussed earlier. When a side effect is optional, make it nullable and return null if it should not happen.

It isn't possible to return a generic list of ISideEffects. Wolverine needs to know the explicit type of the side effect to resolve the injectable parameters correctly. Side effects are part of the transaction spanning the Load, Verify and Handle functions. This means that if a side effect fails, the message processing fails.

Wolverine publishes the messages after everything in the transaction succeeds. This prevents ghost messages notifying other parts of the system of an operation that may have failed. To prevent messages from disappearing because there is a problem with the bus, I recommend enabling the outbox via durable messaging. Storing the message in the database is part of the transaction which prevents those messages from being lost.

public (IResult, OutgoingMessages, EntityFrameworkInsert<WalkWithDogs>?) Handle(
    WalkWithDogs walk,
    List<WalkWithDogs> otherWalksAtSameTime,
    Func<byte[]> getPicture,
    DateTimeOffset now,
    Watermark watermarkService)
{
    var outgoingMessages = new OutgoingMessages();

    if (!otherWalksAtSameTime.Any())
        return (Results.Empty, outgoingMessages, null);

    var friends = otherWalksAtSameTime.SelectMany(w => w.Dogs).Except(walk.Dogs).Select(d => d.Name).ToArray();
    if (friends.Length != 0)
        outgoingMessages.Add(new MetFriends(friends));

    FriendsResponse response = friends.Length == 0 
        ? new([], []) 
        : new(friends, watermarkService.Add(getPicture()));

    return (Results.Ok(response), outgoingMessages, new EntityFrameworkInsert<WalkWithDogs>(walk));
}

A last remark: when a side effect can fail, publish an event or command and handle it. The most prevalent examples are network calls. A network call can fail for a multitude of reasons. When I trigger the call to an external system in an event, I can leverage built-in retry and error handling mechanisms. This means I have battle-tested ways of handling failures.

Next up, I’ll be looking into different ways of testing logic and infrastructure code.

Wolverine installs alongside other messaging and API frameworks such as MassTransit, NServiceBus, minimal API, ASP.NET and Blazor. This allows gradual integration within existing projects. For this purpose, I will leave the functionality of creating and retrieving a dog in the minimal API.

Let me demonstrate how simple Wolverine can be with another simple example: a walk. To create a walk, I have to map the path I walked and which dogs I had with me. In a real system, I'd look for GPS integration. For this demo system I use a list of coordinates [(0,0), (0,1), (2, 1), ...]. I also want to verify that the dogs are in the system, so I don't have unknown dogs with me.

public class RegisterWalkHandler
{
    public Task<Dog[]> LoadAsync(RegisterWalk request, DogWalkingContext db) =>
        db.Dogs.Where(d => request.DogsOnWalk.Contains(d.Name)).ToArrayAsync();

    public ProblemDetails Validate(RegisterWalk request, Dog[] knownDogs)
    {
        var knownNames = knownDogs.Select(d => d.Name);
        var unknownDogs = request.DogsOnWalk.Except(knownNames).ToArray();
        return unknownDogs.Any()
            ? new ProblemDetails
            {
                Status = (int)HttpStatusCode.BadRequest,
                Title = "Unknown dog or dogs",
                Detail = string.Join(", ", unknownDogs)
            }
            : WolverineContinue.NoProblems;
    }

    [WolverinePost("/walk", Name = "Register Walk", OperationId = "Walk")]
    [Tags("MoreThanCode.AFrameExample")]
    public (LazyCreationResponse<WalkResponse> response, EntityFrameworkInsert<WalkWithDogs> insertWalk) Handle(
        RegisterWalk request,
        Dog[] dogsOnWalk)
    {
        var walk = new WalkWithDogs
        {
            Dogs = dogsOnWalk,
            Path = request.Path.Select((coord, index) => new CoordinateEntity
                {
                    X = coord.X,
                    Y = coord.Y,
                    SequenceOrder = index
                })
                .ToList()
        };

        var response = () => new WalkResponse(walk.Id, dogsOnWalk.Select(d => new DogResponse(d)).ToArray(), request.Path);
        return (LazyCreationResponse.For(() => $"/walk/{walk.Id}", response),
            new EntityFrameworkInsert<WalkWithDogs>(walk));
    }
}

Wolverine works by convention: first it loads data when it sees a Load or LoadAsync function, then it validates the request, and finally it processes the Handle or Consume function. The Load function is equivalent to the infrastructure code, and the Handle function is my logic code. The Validate function is a bonus to even further separate concerns.

Through source generation, it creates the controller for me. This means that the code is fast because there is no reflection during runtime. It also figures out what to inject into each function. It can find injectable services through the configured dependency injection framework, it can inject messages from the bus and HTTP pipeline (including query parameters and form data) and objects returned from the Load function. That is how the Validate and Handle methods get the request and the list of dogs.

What I find most impressive is that Wolverine can handle the output of the Handle function. In an HTTP handler, the first item in the returned tuple is the response to the client. The next items will be either messages to be sent to the configured bus or handled as a side effect. A side effect is anything related to infrastructure that is part of the transaction: saving contents to a file, updating rows in the database,... It makes this distinction by looking for the presence of the ISideEffect marker interface.

For other side effects, especially concerning external systems, I put a command on the bus and have a handler interact with the external system. This has the benefit that it runs asynchronously, it’s possible to distribute processing and it uses built-in resiliency and retry mechanisms. It also promotes reuse as multiple components can trigger the integration with a simple message.

These are the most important features to get started with A-Frame architecture. For more in-depth knowledge I'll refer to the Wolverine docs.

Next up, I’ll dive into a more complex example.

Let’s first get back to the simple scenario in my dog walking application. The initial endpoint will create a dog in the database. I'll start with the infrastructure code as this will be the most recognisable.

record CreateDog(string Name, DateOnly Birthday);
app.MapPost(
    "/dog",
    async ([FromBody] CreateDog dog, [FromServices] DogWalkingContext db) =>
    {
        var existingDog = await db.Dogs.FirstOrDefaultAsync(d => d.Name == dog.Name && d.Birthday == dog.Birthday);

        var dogCreation = Dog.CreateDog(dog, existingDog);

        switch (dogCreation)
        {
            case DogCreated created:
                db.Dogs.Add(created.Dog);
                await db.SaveChangesAsync();
                return Results.Created($"/dog/{created.Dog.Id}", created.Dog);
            case DogExists exists:
                return Results.Redirect($"/dog/{exists.Id}");
        }

        return Results.InternalServerError("Could not determine what to do with the dog");
    })
.WithName("CreateDog");

The endpoint retrieves a possibly existing dog and passes it, together with the create command, to the CreateDog handle function. The logic function decides how to handle the creation. Either I create the dog in the database and send a 201 Created response or I send a 301 Redirect response when the dog already exists. Should the logic returns something else, I return a 500 Internal Server Error response.

Now that I have the infrastructure in place, let's look at the logic to create a dog in our system.

abstract record DogCreation;
record DogCreated(Dog Dog) : DogCreation;
record DogExists(int Id) : DogCreation;

public class Dog
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateOnly Birthday { get; set; }

    internal static DogCreation CreateDog(CreateDog dog, Dog? existing)
    {
        if (existing is not null)
            return new DogExists(existing.Id);

        return new DogCreated(
            new Dog
            {
                Name = dog.Name,
                Birthday = dog.Birthday
            });
    }
}

If a dog already exists, I return the identifier of that dog. Otherwise, I'll create a new dog. When I remove infrastructure concerns, the remaining logic is straightforward. The return structure is easy to understand and describes all possible outcomes. I like this little pattern, it reminds me of discriminated unions aka union types. I hope C# gets them soon as I think functional programming paradigms are quite elegant.

Setting up automated tests for logic components is quite easy as there is no infrastructure that gets in the way. Infrastructure benefits more from integration tests that check all the messy side effects, while a (much faster) unit test can verify the output.

The readers who’ve been paying attention will have noticed that the controller and infrastructure code have interwoven in this example. Congratulations to those who spotted it. In this case, I don't mind as this is simple enough as a first example.

In more complex software I would put every infrastructure instruction into its own method or even class, except for Entity Framework queries. Entity Framework is an abstraction of the database, which hides the infrastructure details. I might put more complex queries in their own descriptive function, but I would not use the repository pattern.

Other infrastructure functionality would get their own class. This means that if I want to send an email, I’d create an SendHelloEmail class that would take care of sending out welcome emails. Depending on the needs of the software, I’d determine how abstract, flexible and configurable the setup of these infrastructure components should be.

An even simpler scenario

The processing was easy enough to understand. I returned a reference to an endpoint that loads the details of a dog. How does that look in our A-Frame architecture? I wouldn't use A-Frame Architecture for this. Most queries are so straightforward that I don't want to bother with abstractions or indirection. I would just use a very, and I mean very, simple approach.

app.MapGet(
        "/dog/{dogId}",
        async (int dogId, [FromServices] DogWalkingContext db) => Results.Json(await db.Dogs.FindAsync(dogId)))
    .WithName("GetDog");

Even if queries get more complicated, most don't reach the level of processing code. I'd place these in a separate file with a single function. There is the occasional exception that breaks this rule, but for those cases I'd look for a bespoke approach to the problem at hand instead of a one-size-fits-all approach. A one-size-fits-all approach either has the problem that it’s overly complex for simple scenarios or not flexible enough for the complex cases.

Now that the basics are clear, let's take a look at how I can make my life a lot easier with a framework that already does a lot of the heavy lifting.

This leads to nicely separated code components, have a single responsibility and have no dependencies on other components. This makes each component easy to reason about, which in turn leads to code that is easily tested, changed and replaced. Infrastructure components tend to be more general and promote reuse, while logic is more specific to each use case.

For example, I can have several logic components that need to write an image to the file system. One will deal with profile pictures while another will handle uploaded photographs. Both will delegate the write operation to the same infrastructure component.

Infrastructure

Infrastructure components (aka infrastructure) interact with external systems, read or write state and call functions with an unpredictable outcome. Examples are:

• Database calls

• Sending requests over the network

• Reading or writing to the file system

• Retrieving environment variables

• Determining date and time

• Generating random numbers, ids or uuids

These components can be harder to test without an actual system to talk to. They’re challenging to mock or replace, both in automated tests and test environments. Infrastructure can also behave in unpredictable ways: do I have the right permissions or credentials, is there enough space on a disk, can I make the call through the firewall, etc.

That is why I like to wrap these systems in an abstraction that I can more easily control. Sometimes I create my own interfaces and implementations. For file system access I mostly always create an IFileSystem interface that have Read and Write methods, sometimes with (de)serialisation baked in. When there are good abstractions already available, I reuse those. IOptions is invaluable for accessing settings and TimeProvider is a great way to abstract time management.

When it comes to database access, there is the repository pattern. This is a good option when I access the database directly with ADO.NET or Dapper. I don’t recommend using the repository pattern together with entity framework for the simple reason that a DbContext already is an abstraction over the database. I've seen this lead to a maze of indirection and duplication of logic. A repository with Repository.Get(Expression<Func<Model>> where) that has one implementation which just forwards the where to the DbContext, comes to mind.

When I suggest removing the unnecessary repository pattern, I receive these two arguments against it:

1. What about reusing a query? In my experience, most queries are unique. Extension methods are a great place to store reusable statements. Think filtering by a status enum or by a date range. What I'm trying to avoid is a single function with parameters for each case. Search(StatusEnum? status, DateRange? bornBetween, int? idToFilterOn) with if's throughout the body to filter by each optional parameter. The implementation will get quite complex and confusing. Not to mention the dozens of tests to check that it works with every combination. When there is a search endpoint that needs to perform this kind of complex query, I make a specific endpoint with the complex logic inside. The code for these queries is generally not reused.

2. How do I test against the DbContext? Instead of using mocks/fakes/stubs, use a real database. This is what integration tests are for as there is no substitute for a real database. See the Testing A-Frame architecture article for a detailed explanation.

Keep infrastructure as simple and straightforward as possible. I prefer to have them as standalone components that do one thing and do it well. For example, a FileSystem.Write(Image image) should know how to serialise the image to a byte array. If there are multiple ways of serialising, then either the component can determine what serializer to use or the logic code takes that decision and passes the serializer or the serialised content to the file writer.

In infrastructure code, observability is my best friend. No matter how much I prepare and test, the real system will throw curveballs my way. That is why all infrastructure components should instrument OpenTelemetry so I can track requests throughout systems.

Logic

Now that I've loaded data, it's time to make decisions based on that information. This is where logic components come into play. An alternative term is business logic, but I prefer the more generic term to keep it applicable to more scenarios.

A logic component is, preferably, a pure function. It takes the data it needs as input and returns the decisions it has made. Most logic components are going to be quite easy to read and understand. The most important rule of logic components is that they can’t access external systems. There are a lot of similarities between logic components and the domain model from domain driven design practices.

Infrastructure components handle the decisions that logic components take: save data to a database, write data to a file system, notify external systems and post messages to a bus. The only exception I make is for logging as this is tightly coupled to the logic flow. I could return the log events and write them to a log stream in an infrastructure component. I find that going this far is overkill and complicates the flow. An alternative to logging is writing the in- and output of logic components to OpenTelemetry. This keeps the logic free of logging statements and still gives me all the information necessary to debug later.

When I have need of external libraries in my logic code, I look for ones that don’t produce side effects. For example, an image processing library should take the image as input and return it in the same format as output, I don’t want it saving the image to the file system. If the library is complex, I hide that complexity in its own class. Say I need to add a watermark to an image. I'll wrap the extensive image processing library in a class called Watermark. Injection or instantiation then depends on how expensive it is to create that class. I instantiate a read-only field private readonly Watermark lib = new();, I create it inside the function var lib = new Watermark(); or I inject them after the data Process(Model model, DateTime now, Watermark lib). I don't mind tight coupling if it makes sense. When testing this functionality, I automatically test that the logic component calls the library correctly. Because I don’t allow infrastructure, they’re still easy to set up in my tests.

This approach lends itself to reuse very easily: inject or instantiate the Watermark class and use it. It's even easy to extend to add a timestamp in another feature... Wait, hold that thought. I get why this seems like a good idea, both are adding something to an image. Unfortunately, this is a case where the functionality looks alike but is quite different in practice. Adding a watermark is something else than adding a timestamp. They’re only accidentally alike. The moment I'd start implementing this, I'd notice they’re quite different. I would take the lessons learned from the Watermark implementation and just create another class Timestamp. This is easier to maintain, evolve, replace or compose.

It's only when I notice that similar code appears in the codebase that I'll reflect and refactor into a shared class or component. The difference is that I'll react to what is actually there instead of prematurely optimising. This way it's more challenging to create accidental complexity.

Controller

This is a good point in the development process to think about the last step. I can load the necessary data and act upon it; all that I need to do is to connect the dots. This is where the controller comes into play. It will pass information from one to the other and make sure the two never meet. The controller will determine what data to load and pass it on to the logic component. Finally, it will instruct other infrastructure components based on the output of the logic component. This code is fairly straightforward and can even be automated away.

In practice, controllers are endpoint declarations, message handlers, WPF binding methods, cronjob entry points or equivalent. This is the place that will know where to get the data from and which logic component to pass it to.

Let’s put this theory into practice with a simple example.

I will be using a demo project to illustrate these concepts. The app will help dog walkers record their routes, which dogs they took on each walk and which friends they met along the way.

Seeing as this is a demo app, I will use a basic coordinate system instead of GPS data. This will simplify the code and keep the focus on the techniques instead of going into unnecessary details of the non-existent business domain. For brevity, I'll assume you’re familiar with popular concepts such as setting up Entity Framework or how to correctly use HttpClient. There are numerous articles explaining those topics in more depth. I want to keep A-Frame architecture front and centre.

If you want to skip ahead, my GitHub repository with the same name contains all the source code used in the following posts. I’ve also found a blog book (too long to be called a post) from James Shore that expands immensely on my idea. I’ve also drawn inspiration from that work to enhance my learning process, so I encourage you to check it out.

Let’s get started with explaining what A-Frame architecture is.

Since I've been enjoying F# immensely the last few months (I'll probably blog some more about that in the future), I figured I'd write an F# script to create these DNS records automatically. And good news, I kept all secret bits out of it so I can share it with you, my dearest reader!

The script can be found in a public Github Gist. I won't go over every detail of the script, but you can see that I create a list of DNS records, serialise them and then post them to Cloudflare.

How do you use the script? Copy the script to a file ending with .fsx. Make sure you have at least dotnet 5 installed. Then execute the following line

dotnet fsi [path-to-script] [domain] [cloudflare-auth-key]

Example: dotnet fsi .\set-fastmail-dns-in-cloudflare.fsx kenbonny.net 00000000000-ABCdef

The cloudflare-auth-key can be found in your Cloudflare Dashboard. They have a nice guide on how to create a token.

Fastmail provided an easy list of all the DNS records that should be set to make everything work.

Keep one thing in mind: the Cloudflare API documentation is not up to date when it comes to creating SRV DNS records. Other DNS records require a general JSON structure:

{
  "type": "CNAME",
  "name": "fm1._domainkey.domain.com",
  "content": "fm1.domain.com.dkim.fmhosted.com",
  "ttl": 1,
  "priority": null,
  "proxied": false
}

An SRV DNS record needs a specific JSON structure:

{
  "type": "SRV",
  "data": {
    "service": "_caldavs",
    "proto": "_tcp",
    "name": "domain.com",
    "priority": 0,
    "weight": 1,
    "port": 443,
    "target": "caldav.fastmail.com"
  }
}

Hopefully this saves somebody some setup headache when configuring Fastmail on Cloudflare. Including me, when I add more domains to my account. 😁

When I was thinking about ways to make Kotlins type aliases available in C#, I was too focussed on the perceived ease of representing one thing as something else. A string as a Uri for example. I did not investigate deeply enough to see that Kotlins type aliases are syntactic sugar to make concepts more explicit and not a real conversion.

This brings me to the first comment and I even put it right into my blog post. 🤦‍♂️

An implicit cast should always succeed and return a result.

This is stated originally in the Microsoft guidelines:

Predefined C# implicit conversions always succeed and never throw an exception.

Why is it important that there is no exception? Because of the implicit connection between the two types. One type should always be the other type. With an explicit cast, this can be said to be the case sometimes. I'm forcing the cast from one type to another, but it can go wrong. When I'm using an implicit cast, this should be a given.

For example: I can say that a Uri can always be represented as a string. I cannot say that every string should always be a valid Uri. Especially not if I say that every string should also be a valid FileInfo and a valid DirectoryInfo and a valid Telephone number. A string cannot be all at the same time. Yet that is what this implicit cast would indicate.

Therefore, my notion that all their classes should be able to transparently cast from string to their type is wrong.

A better way to do this would be to write convenience overloads for methods that take a Uri so it accepts a string.

class DownloadSomething
{
    Task<T> Data<T>(string location)
    {
        // parse string to uri
        Data(new Uri(location));
    }
    Task<T> Data<T>(Uri location)
    {
        // download data
    }
}

This makes it easy to pass in a string instead of a Uri, yet gives me the option to parse the string to make sure this is a valid Uri.

This brings me to the second point: code should not be magic. If I read the code, I should understand what it is doing, unambiguously. Suddenly going from a string to a Uri, without checking, verifying or parsing is not always intuitively. In some cases, it might be, but in a lot more, it won't be.

For as long as I've programmed, I've disliked clever tricks or techniques that look like magic. This should have looked like magic as well, but I was staring too blindly at the Kotlin type alias functionality. This clicked when I read this really good explanation about Visual Basics Nothing keyword.

To end on a positive note, I think I have found a good place for an implicit cast: inside the builder pattern. A builder should always have a valid instance of the type it has been building. So, casting a builder to the type it's creating is safe, can always be done and does not feel like magic. It works very nicely in my tests where I need to prepare several input objects. For example, an order with several items:

database.Add(OrderBuilder.Create(orderDate, personOrdering)
                         .AddItem("Item 1", price:200, quantity:10)
                         .AddItem("Item 2", price:500, quantity:2))

class OrderBuilder
{
    public OrderBuilder Create(DateTime orderDate, Person client)
    {
        // create order
        return this;
    }

    public OrderBuilder AddItem(string description, int price, int quantity)
    {
        // add item to order
        return this;
    }

    public Order Build()
    {
        // return order with lines
    }

    public static implicit operator Order(OrderBuilder builder) => builder.Build();
}

Making mistakes is never fun, but I did learn a great deal from it. I learned a lot about casting, I got a history lesson about Visual Basic and I got a lesson in humility. Now I hope others can learn from my mistake as well.

Here is a first for my blog: Rwing offered to translate it to Chinese. So I took him up on it and you can read his translation on his blog cnblogs.com. I hope it says nice things about me. 😁

C# 10

Earlier this week, I followed a talk by Mads Torgersen at DotNet SouthWest, he's the lead designer for the C# language at Microsoft. He outlined the cool new things C# 10 will contain. Let's take a quick look at some of the good things coming our way!

Small disclaimer, most of these changes are pretty much done as he was clearly showing off. Since it's still in active development, I can't guarantee that everything will be exactly as is when C# 10 releases.

The first thing he talked about, is how the current implementation of record uses a class (read: reference type) as the base object. There will also be a record struct variant available so the underlying type can be a value type. The difference is that a regular record will pass from function to function by reference and a record struct will be copied by its values. The record struct will include with support.

At the same time, it will be possible to add operators to records. It will be available for both record types.

record Person(string Name, string Email)
{
  public static Person operator +(Person first, Person second)
  {
    // logic goes here
  }
}

One of the goals the C#-team is focussing on, is making initialisation of objects easier. That is why it will be possible to flag properties of a class, struct, record or record struct as required. It makes those properties mandatory to fill in. This can be done via a constructor, or this can be done with object initialisation. The two class definitions below are equivalent. If you write it with the required keyword, you cannot instantiate the Person without setting the Name property. The compiler will throw errors and fail to compile.

class Person
{
  public required string Name { get; set; }
  public DateTime DateOfBirth { get; set; }
}

class Person
{
  public Person(string name) => Name = name;

  public string Name { get; set; }
  public DateTime DateOfBirth { get; set; }
}

To further improve properties, it will be possible to get rid of backing fields alltogether. The new keyword field will provide access to said backing field. This will be available for both setters as init only properties.

class Person
{
  public string Name { get; init => field = value.Trim(); }
  public DateTime DateOfBirth { get; set => field = value.Date; }
}

There will be a few nifty little enhancements in the next version as well. One is that the with operator will support anonymous types as well.

var foo = new
{
  Name = "Foo",
  Email = "foo@mail.com"
};
var bar = foo with {Name = "Bar"};

It will now be possible to create a single file with namespace imports that are used everywhere. For example, if there is a popular namespace that is used in virtually every file, say Microsoft.Extensions.Logging.ILogger, then it will be possible to add a global using Microsoft.Extensions.Logging.ILogger to any .cs file (I suggest the Program.cs or a dedicated Imports.cs) and the logger interface will be available in the entire project. Not the solution! Nobody can predict which imports are needed anywhere, so they are grouped per project.

Subsequently, there will also be an optimisation to namespaces. Now a namespace requires curly braces {} to group code which entails that all code will at least be indented once. To save that tab (or four spaces, whatever, you choose) and the screen real estate, adding a namespace anywhere in a file, will make all code belong to that namespace. Research has shown that nearly all code in one file belongs to the same namespace. The subsequent reduction in file size because all those tabs (or spaces) are saved might not be significant for one solution (even if it contains thousands of files), but on the scale of GitHub/GitLab/BitBucket/..., I think it will save them some space. Should anybody still want to include multiple namespaces in one file, the option to use the curly braces is still available.

// LegacyNamespace.cs
namespace LegacyNamespace
{
  class Foo
  {
    // legacy code goes here
  }
}

// SimplifiedNamespace.cs
namespace SimplifiedNamespace;
class Bar
{
  // awesome code goes here
}

There are some cool updates to lambda statements coming too. The compiler will have better support for inferring lambda signatures and it will be possible to add attributes as well. It will be possible to specify explicit return types to help the compiler understand the lambda.

var f = Console.WriteLine;
var f = x => x; // inferring the return type
var f = (string x) => x; // inferring the signature
var f = [NotNull] x => x; // adding attributes on parameters
var f = [NotNull] (int x) => x;
var f = [return: NotNull] static x => x; // adding attribute for a return type
var f = T () => default; // explicit return type
var f = ref int (ref int x) => ref x; // using ref on structs
var f = int (x) => x; // explicitly specifying the return type of an implicit input
var f = static void (_) => Console.Write("Help");

Thanks at Schooley for suggesting a less confusing example attribute!

Lastly, it will be possible to specify static methods and properties on interfaces. I know this will be a controversial topic, just like adding default implementations to interface. I'm not a fan of that last one. This however, could be very interesting. Imagine that you could specify the default value of an interface or specify creation methods.

interface IFoo
{
  static IFoo Empty { get; }
  static operator +(IFoo first, IFoo second);
}
class Foo : IFoo
{
  public static IFoo Empty => new Foo();
  public static operator +(IFoo first, IFoo second) => /* do calculation here */;
}

Personally, I like these changes. My favourite ones are the changes to namespace and the improvements to the interfaces. Anyway, the future is seeing sharp. Eh Eh...

I'll see myself out now.

Preparing the blog content

The first step was to get access to all my blog posts as I'm not about to manually copy ~130 posts from WP to HN. The number of things I had to fix was time consuming, if I had to do it all by hand it would have taken forever. Fortunately, there is an export functionality in WordPress to export my posts via Tools > Export. The downside is that this generates one huge XML file and I need markdown files to upload to HN.

After a bit of googling, I stumbled upon a wordpress-export-to-markdown tool. With a bit of experimenting, I found the right adjustments to get the output ready for HN. I just had to replace the frontmatter variable in parser.js to the following code.

frontmatter: {
    title: getPostTitle(post),
    date: getPostDate(post),
    slug: getPostSlug(post),
    image: `https://images.kenbonny.net/${getPostSlug(post)}/cover.jpg`,
    categories: getCategories(post),
    tags: getTags(post)
}

With the following command, I transformed the XML file into separate markdown files that represent each blog post.

> node index.js
Starting wizard...
? Path to WordPress export file? export.xml
? Path to output folder? output
? Create year folders? No
? Create month folders? No
? Create a folder for each post? No
? Prefix post folders/files with date? No
? Save images attached to posts? No
? Save images scraped from post body content? No
? Include custom post types and pages? No

Preparing the images

This took care of the posts and their content, but unfortunately did nothing for the cover images. That's why I ran the transformation again, but this time I told it to download all the blog images.

> node index.js
Starting wizard...
? Path to WordPress export file? export.xml
? Path to output folder? output-with-images
? Create year folders? No
? Create month folders? No
? Create a folder for each post? Yes
? Prefix post folders/files with date? No
? Save images attached to posts? Yes
? Save images scraped from post body content? Yes
? Include custom post types and pages? No

For safety, I copied the content of the output-with-images folder to another folder, so I could experiment with it. The first thing I did was remove all the markdown files as I'm interested in the images at this time. So I ran ls *.md -Recurse -File | rm in powershell to remove the unwanted files. All the images are saved to an images subfolder, I wanted them in the base folder. So I had to find a way to move the images from \\images to \. After a little poking around, I found this stack overflow answer which told me to run ls . -Recurse -Include *.jpg, *.jpeg, *.png | mv -Destination { $_.Directory.Parent.FullName }.

With all the images in the slug folder, it's time to remove the emtpy images folders with the powershell ls images -Directory -Recurse | rm command. I like clean folders. If there is something that I don't need, I like to get rid of it.

A few git commands later and my images are in a repository on which I enabled GitHub Pages. Since GitHub Pages supports custom domains, I can assign it a subdomain of kenbonny.net: images.kenbonny.net. I configured this subdomain via Cloudflare and called it a day.

I now have my own CDN with an upper limit of 5GB. After 5 years of blogging, the images folder takes up 105MB of disk space. So I think I'll get a decent amount of mileage out of this.

The last hurdle is to make sure there is a cover.jpg file available. I wrote a custom dotnet console app that loops over the folders, checks if there is one image present and renames that to cover.. It printed the folders with multiple images that did not contain one with the name cover. That way I knew which folders to manually check.

Uploading the content

Now that I have my content as markdown files and the cover images are available on my own CDN, it's time to upload the content to HN. I was tempted for a while to write my own upload process using the graphql api so I could add tags on the fly as the import process does not have support for this. There are two drawbacks to this approach:

1. No backdate functionality: the frontmatter contains the actual publish date of the post, this backdate cannot be set through the api. This is available through the standard upload process.
2. Correlating tags is not easy: in WP I could set any tag I wanted, in HN, there is a curated list of tags (which I've grown to like). There is no 1-to-1 mapping for each tag that I've used over the years. Putting too much effort in this felt like a waste of time.

So I zipped up all the markdown posts (after trying it with some example posts) and uploaded the zip file to HN import tool. After that ran for about an hour all my posts were present in HN. Now all I needed to do was go through each and every post and set the tags right and I was done... right?

Unfortunately, it wasn't that straightforward. Apparently I had forgotten that not every post had a cover image, so there were a number of posts with an empty cover image. There were also a few empty ones that did have a cover image, but the cover image was not in the jpg format that I set as default.

While checking the posts for missing cover images and tags, I noticed something else. During my 5 years of blogging, some WP formats have changed. How code is represented changed quite a bit over the years. In the early posts, I noticed that there were [code language="csharp"][/code] tags throughout my posts. In the later posts, the wp-to-markdown nicely used the ``` format. In some posts, I noticed some additional information such as html comments with WP paragraph specific info. So it was a good thing that I went through each post and fixed the broken parts myself. The automation did a lot out of the box, but keeping track of all the things WP can is an impossible task.

Unfortunately, only after I edited all my posts, I found out that in order to back a post up to my own GitHub repository, I need to save the post. I will not be doing that again to get them into my backup repository, I'll just wait for the tool that can back up the existing posts.

Finishing touch

Now there is one last problem to worry about: legacy URLs. WP uses the format //// while HN only supports /. That would mean that the link https://kenbonny.net/2021/02/01/moving-to-trunk-based-development would not work after the move to HN. This would mean that I had a serious problem as I did not know how many links would break. There are people who send a link to a friend, there are browser autocomplete suggestions, linked articles would not arrive correctly, etc.

While I was checking all the content of the blog, the solution presented itself: Cloudflare transform rules. It's a new feature from Cloudflare that would allow rewriting of urls on the fly. After some experimenting, I found out that regex matches are not allowed for the free plan. I'd love to get a professional Cloudflare plan, but it would be just for this. That is a bit of a steep price for my simple blog.

Fortunately, I can solve the same thing with a Cloudflare Worker. I created a Worker and added the below script. This will strip out the date format and redirct the user to the correct page. If the url does not contain the date format, it does nothing.

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

const movedPermanently = 301;
async function handleRequest(request) {
  const dateFormat = /\/\d{4}(\/\d{1,2}){2}/i
  if (request.url.match(dateFormat)) {
    const urlWithoutDate = request.url.replace(dateFormat, '');
    console.log(`redirect ${request.url} to ${urlWithoutDate}`);
    return Response.redirect(urlWithoutDate, movedPermanently);
  }

  return fetch(request);
}

It is now finally time to switch de domain from WP to HN. All that took was to set the domain in a HN setting and pointing the CNAME DNS record from WP to HN.

Conclusion

Starting from now, my blog is hosted on Hashnode. If I did everything correctly, nobody should really know that this happened except for the visual changes. All links should continue to work and all content should be converted into the right format. If anybody finds any issues, let me know and I'll look into it.

So I set out to find an alternative. At first, I thought about creating my own platform. Something like Gatsby or Hugo. After looking into that for a bit, I found it too much work for a blog with my own personal thoughts. I don't want to get bogged down into maintaining a blog platform, making sure the certificates are up to date, improving speed and efficiency, getting the RSS feed right, adding support for twitter and code snippets, etc. I just want to log in, write an article with some content and publish it. I admire the guys who have the time and dedication to maintain their own platform, but I know I have too much going on in my life to find or make time for that commitment.

After some googling and looking around, I stumbled upon Hashnode . It is simple but not limiting, I can write in markdown (which I personally like) and it has just the right kind of configurability for me. It supports RSS feeds, has a build in night mode (I don't need it personally, but I know a lot of people like it) and it's a hosted solution (meaning, I log in, write content and publish). It even offers custom domains for free!

While I was moving my ~130 articles from WordPress to Hashnode, which will get a more thorough technical post in the future, I noticed a number of nice little benefits. My number one: Hashnode does not track the readers.

A curated list of tags is another one I got used to quite quickly. This forces me to choose from the available tags, but it ensures everybody uses the same tags to make posts with relevant topics easy to find. In WordPress, I could add any tag I wanted, but it also meant the community is pretty scattered.

The last benefit, is that I can take backups to a GitHub repository. Right now, I would need to edit and save each post individually for it to be backed up, but there is a feature coming to back up the legacy posts. It quite literally backs the markdown up to a repository that I control. If I ever need or want to switch blogging platform, I've got my content in an easy to access format under my control. As I mentioned earlier, getting my content out of WordPress and into Hashnode was not a simple task and I like that Hashnode makes this a lot simpler. It says to me: you are free to leave if you do not like our platform. This implicitly means that they have to step up and provide a great platform. This really resonates with the way I like to work.

It's not all sunshine and happiness. The main thing I'm going to miss is the feature to post blog (or stories as they are called in Hashnode) at a later date. This means that I cannot finish writing a blog post and schedule it to release on Monday at 10 o'clock. I hope they add this quite fast as I'm fond of this feature.

The second and more problematic thing, is that Hashnode does not support the url format that WordPress uses: [domain]/[year]/[month]/[day]/[slug]. the [year]/[month]/[day] part is not added by Hashnode and I've had a bit of trouble to work around that. A big thanks to Cloudflare for supplying such an awesome platform that made this quite easy to work around. The details of this will come in the follow up post with more details.

The last thing that kept me on the fence for a little while, is the speed. Although the DOM draw happens quite fast, the Hashnode blog is heavier and takes overall longer to load. Because I like the writing experience a lot better and they don't track users, I am going through with the switch. Also, ignore my awesome editing skills. The speeds are taken by loading my lastest blog post Jimmy Bogards crossing the generics divide from both the WordPress and the Hashnode site.

Overall, I'm quite happy with how my Hashnode blog looks, shows code and handles Twitter and other references. That is why I'll be moving my blog over to the new platform next weekend. If you want to keep receiving updates whenever I post them, make sure to check that that still works after next week. I've made sure the impact is as small as possible, but I'm sure some issues are bound to pop up. Let me know when they happen and I'll fix them as soon as I can.

So I created a GitHub repository named Crossing The Generics Divide. I did put it in a namespace KenBonny, not (only) because I did the copy pasting from Jimmy’s blog, but to show that this is not made by Jimmy. It’s just a tribute. I did do one thing different: Jimmy uses “validators”, I replaced that by “processor” as I wanted to return a result (which is just a bit of text to differentiate between the processors).

The most important lesson that I learned is that the composition has my preference, but that I cannot inject the general IPolicyProcessor (Jimmy’s IPolicyValidator) directly. I need to ask for the specific PolicyProcessor<> as I cannot pass the type of Policy to the factory method with basic dependency injection.

There is an example with the IPolicyProcessor that comes from a factory, but this required a bit of extra work in a console application. The IServiceProvider does not automatically get registered if I did it manually. To get this working, I had to set up a hosting environment (as described by the Microsoft docs). So if the normal execution is an asp.net project, this should work out of the box.

Because the project is small, my first instinct was to consolidate on one branch. This looks a lot like trunk based development and that's because it is. I now only have a master branch from which I deploy to every test environment. With only me as developer and a few business people who test on it, it felt overkill to keep the development and quality assurance environment.

A problem arises when I talk with the business people about release management. They want to test the version in the test environment and when everything looks ok, I can deploy outside of business hours to production. At the moment, I do not have a way to enable new features in the test environment and disable them for the production environment. So I would not be able to continue development without also pushing those changes to production. The same issue arises with hotfixes, I'd need a way to push changes to production, without pushing every experimental feature on the master branch. The best approach would be to use feature toggles, but this is not a change I can do overnight.

Queue the only other long lived branch besides the master branch: the production branch. I use feature branches taken from the master branch. When the business gives the green light that everything looks good, I can create a release branch from the master branch. When I have the release branch in place, I can wait until outside working hours before merging the release to production. Basically I create a snapshot from a well tested environment and push it to production. Should bugs in production appear, I can create a hotfix branch from the production branch and merge that back to the test environment for verification.

With this in structure in place, I have only 2 branches: production for the production environment and master for everything else. I can work trunk based in the testing environment and have a dedicated branch for production releases and issues. There is a temporary (and optional) release branch so I have a snapshot of a production release, but that is only for practical reasons.

In the next part, I describe the changes and important remarks I noticed while working towards the end result. This will start from the old implementation with different branches and releases and work towards the solution described above.

So now I just have to change the release pipeline. The first thing I noticed, was that there are a lot of branches that can kick off the single pipeline that is in control of the continuous integration (CI) build, the release build and the deploys to the various environments.

trigger:
  - master
  - develop
  - feature/*
  - bugfix/*
  - hotfix/*
  - release/*

Before a pull request (PR) can be merged into the branches master or develop (both kick off a deploy to a specific environment), it needs to pass a build pipeline. I think the person who set this up, thought that there should be triggers for the CI pipeline to kick in. In Azure DevOps, I can specify a policy on a branch that needs to run before the PR can complete. This kicks off a separate build process for the policy.

What this in practice does, is when I push to a feature branch (or any other described above), it kicks off a build (described in the release pipeline). Then I start a PR, which also kicks off a build (for the branch policy). I see one build too many here. This does not only cost time as it basically doubles the time for a PR build, it also costs money as the build process is a paid service (after the first 1800 free minutes). It becomes even more wasteful if I need to add changes to the PR. Remember that each push to a branch starts a build and each PR change kicks off a policy build.

Seeing as I do not want multiple branches for each environment (right now, the develop branch goes to the develop environment and the master branch goes to the test and production environments), I can simplify the trigger.

trigger:
  - master
  - production

With the simplified triggers, I'm now left with a whole section that is only used for a CI build. As this is not needed for a deployment, I moved this to it's own pipeline. Azure DevOps supports multiple pipelines. I simply create one in the DevOps portal (or maybe through the Azure CLI, I'm not familiar with that) and point it at a yaml file.

trigger:
  - none

variables:
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
  DOTNET_CLI_TELEMETRY_OPTOUT: true
  solution: src/SolutionFile.sln
  buildPlatform: Any CPU
  buildConfiguration: Release

stages:
  - stage: CI_Build
    displayName: CI build on PR
    jobs:
      - job:
        displayName: CI Build
        pool:
          vmImage: windows-latest
        steps:
          - task: NuGetToolInstaller@1
            displayName: Install NuGet Tooling
          - task: NuGetCommand@2
            displayName: Restore NuGet Packages
            inputs:
              restoreSolution: $(solution)
              feedsToUse: select
              vstsFeed: feed-identifier
          - task: VSBuild@1
            displayName: Build Solution
            inputs:
              solution: $(solution)
              platform: $(buildPlatform)
              configuration: $(buildConfiguration)
          - task: VSTest@2
            displayName: Run Test Suite
            inputs:
              platform: $(buildPlatform)
              configuration: $(buildConfiguration)

The content of the ci-pipeline.yml contains a simplified build process. I have added two variables to opt out of providing Microsoft with telemetry data about my builds. The DOTNET_CLI_TELEMETRY_OPTOUT and DOTNET_SKIP_FIRST_TIME_EXPERIENCE work together to not send information to Microsoft and speed the build up a little bit. More information can be found in the Microsoft documentation.

Now that I placed my CI build in a separate pipeline, my original pipeline is already looking cleaner. I'll save you all the refactoring steps, cursing and head scratching (of which there was a lot) and present the finished product. I redacted some parts as they are client specific details, it should not be difficult to figure out what goes where. Let's start with the general release-pipeline.yml file.

trigger:
  - master
  - production

variables:
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
  DOTNET_CLI_TELEMETRY_OPTOUT: true
  solution: src/SolutionFile.sln
  prodBranch: refs/heads/production

stages:
  - template: pipeline/release-build.yml

  - template: pipeline/deploy.yml
    parameters:
      environment: TEST
      condition: and(succeeded(), not(eq(variables.build.sourceBranch, variables.prodBranch)))

  - template: pipeline/deploy.yml
      parameters:
        environment: PROD
        condition: and(succeeded(), eq(variables.build.sourceBranch, variables.prodBranch))

The trigger and variables sections are pretty self explanatory, so lets look at the different stages. I won't display the release-build.yml, but safe to say it looks a lot like the CI pipeline yaml from earlier. I've added a few different steps as I want to build the website and processing services separately. This is necessary to deploy them separately later.

There are two deploys, one to the test environment and one for production. The test deployment runs after a successful build when it's not the production branch and the production deploy only runs after a successful build when it is the production branch. This is the only difference between the deploys.

The deploy.yml in the pipeline folder, contains a stage that calls two job templates: one to deploy the website and one for the processing services. The rest of this template should be pretty straightforward.

parameters:
  environment: ""
  condition: ""

stages:
 - stage: ${{ parameters.environment }}\_Deploy
    displayName: Deploy To ${{ parameters.environment }}
    dependsOn: Release_Build
    condition: ${{ parameters.condition }}
    pool:
      vmImage: windows-latest
    jobs:
      - template: deploy-website.yml
        parameters:
          environment: ${{ parameters.environment }}
      - template: deploy-processing-services.yml
        parameters:
          environment: ${{ parameters.environment }}

The website template is just a deployment job that first cleans the target folder, then extracts the new build and finally transforms the web.config.

parameters:
  environment: ""
  serviceName: "Client.Website"
  artifactPrefix: "Client.Website.Build"

jobs:
  - deployment: Public_Website
    displayName: Install public website
    environment:
      name: ${{ parameters.environment }}
      resourceType: VirtualMachine
      tags: website
    strategy:
      runOnce:
        deploy:
          steps:
            - task: DeleteFiles@1
              displayName: "Delete ${{ parameters.serviceName }}"
              inputs:
                SourceFolder: "C:\\WebSites\\${{ parameters.serviceName }}"
                Contents: "**/*"
            - task: ExtractFiles@1
              displayName: "Extract ${{ parameters.serviceName }}"
              inputs:
                archiveFilePatterns: "$(Pipeline.Workspace)/Mooose/${{ parameters.artifactPrefix }}.$(Build.BuildId).zip"
                cleanDestinationFolder: true
                destinationFolder: "C:\\WebSites\\${{ parameters.serviceName }}"
            - task: FileTransform@2
              displayName: "Transforming $(Environment.Name) web.config"
              inputs:
                folderPath: 'C:\\WebSites\\${{ parameters.serviceName }}'
                xmlTransformationRules: "-transform web.$(Environment.Name).config -xml web.config"

The deploy-processing-services.yml is quite easy. It installs two agents that process service bus messages. One is for general processing, the other is for pdf generation. This gets its own service as this needs to go fast and can't wait for other general messages. There is an install-service.yml script that contains the powershell to stop, install and start the service. So that is easily reusable as well.

parameters:
  environment: ""

jobs:
  - deployment: Processing_Services
    displayName: Install processing agents
    environment:
      name: ${{ parameters.environment }}
      resourceType: VirtualMachine
      tags: processing
    strategy:
      runOnce:
        deploy:
          steps:
            - template: install-service.yml
              parameters:
                serviceName: Backend.Agent
                artifactPrefix: client.backend.agent
            - template: install-service.yml
              parameters:
                serviceName: Pdf.Agent
                artifactPrefix: client.pdf.agent

I don't do a lot of special deployment things, but there is one area where I want to focus on: the environment.tags. I set the deployment to a specific environment name (QA or PROD, from the release-pipeline.yml) on a virtual machine (because they use machines in a local server park) and I use tags to specify which servers I deploy to.

The use of tags allow me to tag one server in the Azure DevOps Environments with the "website" and "processing" tags and everything gets deployed on one server. In the production environment on the other hand, those are several different servers (multiple for the website and one for the services). Yet I can use the same pipeline to deploy to different combinations. Should I ever need more processing servers, I can just add the servers to the Azure Environment, apply the correct tags and the deployment process would know what to do.

With a simplified pipeline, I can spend less time worrying about getting code into the right environment and focus more on getting the features right.

At the end of the year, I'd like to look back at what I did this past year. It's not as much as the past few years. My blogging was not that much, I wrote a few articles at the start of this year. Then I had a bit of a down period. Not just because of lil' old Corona, but also because I sold my last house and moved into another one. That took up a considerable amount of my time. I have also switched projects, which was a bit sudden (and stressful). I did come out in a better environment, if I say so myself. I have tried to keep sporting, but it's been a challenge to motivate myself. Going to a sports club really does wonders for my motivation, but they had to shut down for the time being.

From the bottom of my heart, I hope next year will be gentler, calmer and filled with joyous reunions of friends and loved ones. Because right now, they are in my thoughts (and Zoom calls), but unfortunately not close enough to share a laugh over a drink. Except for my loving and supporting wife, who's now constantly by my side as we both work from home.

I hope that everybody who reads this has their family, whomever they are, close by. So enjoy the holidays as best as you can and I'll see you next year. Fit and fresh to get vaccinated and pick life back up where we left it a year ago.

Happy new year, everybody!

Disclaimer: I've bought all my gear myself with my own, hard earned, money. So no sponsorship here! Which is why I can give you the good and the bad.

Because I like gaming and I love Logitech gear, I've got myself the G502 Hero gaming mouse. It's a great mouse and I can't decide if I like it more than my MX Master 2S. The G502 is attached to my desk and I use the MX when I take my laptop with me. The MX has a very long battery life and it can easily switch between multiple PC's, but the G502 is a lot more sensitive and it's a lot more customisable. For gaming, I love the G502, for coding and day to day use, I prefer the MX.

My keyboard is the Microsoft Comfort Curve 3000, there is already an upgrade: the Wireless Comfort Desktop 5050. I love the ergonomic design, it really is a lot more friendly on my wrists. I don't think I want to go back to a normal keyboard. The keys type very smoothly. I just wish I could disable the CAPS LOCK KEY BECAUSE... damnit it happened again. That is a complaint irrespective of the type of keyboard; normal keyboards, ergonomic ones, they all still have a CAPS LOCK KEY... damnit. I think the Logitech Ergo K860 has the option to turn it off or remap it. That and it can switch between multiple PC's like the MX Master 2S mouse.

To improve the video recording during teleconferences, I bought myself a Logitech BRIO webcam. This is a good upgrade from my laptop camera. The image looks more crisp and it recognises me in a flash. From friends I've heard that the image over Skype is not great, but I think that might be Skype as Teams, Zoom and Discuss do produce nice video. The audio is good, but I've heard that it's a bit hollow compared to the mic on my headset.

My headset is a Logitech G933 surround sound one. I must say, that surround sound really is awesome. When I play video games, this really comes to life as I can clearly hear which direction the enemies are coming from. It's comfortable, even when I game for a few hours (too few and far in between). The microphone is really superb as well. It captures a nice, warm sound and filters out background noise effortlessly.

The reason I focused so much on connecting to multiple PC's earlier is because my laptop and PC share a desk. So I had to find a way to share my keyboard, mouse, headset and webcam between these two devices. Cue in the UGreen 2 In 4 Out USB Sharing Box. This little device allows me to plug in 4 USB devices: headset receiver, keyboard, mouse and webcam. With a single press of the button on top, I can switch to which device they are attached to. My PC streams to my screen on the Display Port input and my laptop connects via HDMI. Now I press the button on top of the UGreen box and I switch the input of the screen and I'm good to go. Unfortunately, I should have taken a bigger UGreen box, because if I want to share additional devices (say a USB microphone) I'll have to start choosing.

The only thing that is directly plugged into my PC is my Logitech G13 gaming keyboard. I received this as a birthday gift from my wife. I was looking for something like this and I kept doubting. When my birthday rolled around, she presented it to me. I've used it for every game I've played since. I hope it doesn't break as I don't think they still make these. I can't find a link to it on the Logitech site nor on local PC stores. The only reference I find is on Amazon for way too high a price. After a little fiddle with the key mappings, either to make a special profile for the game or to remap the keyboard config, I play way smoother with this device than any keyboard or gamepad. Best gift ever!

The last thing on my desk is the Roost laptop stand. It's a bit pricey, but it's the best laptop stand I've ever had. I've given my wife one a few years ago and it's a very easy to set up stand. Much better control over the stands than the ones I've previously used in corporate settings. It also keeps a much better grip on my laptop.

Hopefully this series helps somebody make a decision while they are looking for a new keyboard or mouse, (standing) desk or ergonomic chair.

Disclaimer: I've bought all my gear myself with my own, hard earned, money. So no sponsorship here! Which is why I can give you the good and the bad.

The last package to arrive is the monitor arm. I took a single one, as I only have one screen, my laptop screen functions as my secondary screen. I have used 2 dedicated screens in the past and this is something I want to go back to. Multiple big screens (27" and up) are a lot more practical than my small laptop screen.

The monitor arm can be attached as a clamp or drilled through the table. The foot of the support column can be changed so the stand can be attached how you like. The part on the underside is a metal clamp and I could easily see how that would damage my brand new table. I have placed the second foot, which has a rubber sole, between the metal clamp and the underside of the table.

With the column installed, I can attach the arm at the right height. This part feels a little unstable as I need to clamp it on the column. This did have me worried as I installed the arm, but it has not moved since I set it up.

Finding the right height can be a challenge though as the arm can't easily be moved up or down once it's been installed. If I loosen it up, I'll need to adjust the height with the screen attached to it. Which I can assume is tricky and has the risk of the screen falling. That's why I put it at the same height as my screen was when it was standing on it's base. That way, I knew it was at a comfortable height.

When I prepared the screen to be attached to the arm, I was slightly worried that the arm would not be able to carry the weight of the screen. This fear proved to be unfounded as the Asus ROG PG279Q is really light and most of the weight is in the foot. The arm can easily hold the screen up and after I tightened the bolt that controls the tilt, it hasn't budged from the angle I placed it in.

The Asus ROG is a great screen: it has nice colours and a good refresh rate, but I do wish I had taken the 4K version instead of the 2K version. 4K just looks a lot more smooth and is easier on the eyes. Especially when looking a whole day at code, mails and stack overflow. Maybe also a bit for gaming. But mostly for the code.

Attaching the screen to the arm did provide a problem. The mechanism would be super easy to use if the part that holds up the screen would stick out of the back of the screen. If you take a good look, the attachment is sunken into the case of the screen. This part slides over the end of the arm, so it's really easy to install... normally. With the cool triangular design (that you never see), the sliding mechanism is blocked by the triangular part of the back. I attached the sliding mechanism to the arm and asked my wife to hold up the screen, while I screwed it to the attachment. Luckily, the screen itself is very light, but it was a tense moment anyway.

The arm can't easily be adjusted in the height. Tilting and turning the screen side to side is very easy and I notice I use it to show my wife something if she's standing next to me so she can more easily see what's on the screen. The screen has a nice viewing angle, but staring directly at a screen instead of at an angle is always more fun.

Cable management is pretty easy although the plastic holders are a bit of squeeze for my HDMI cable. I made sure there is a bit of room on the end so I can turn my screen left and right without pulling on the cables. There is one cable that is not in the cable management, but that's because my display port cable is not long enough to fit into the cable management holders.

There is one detail that annoys me. When I put the table in the standing position, I notice the screen wobbles if I type or touch the table (put a glass down, for example). When I type more slowly, it doesn't happen, when I type harder or faster, it wobbles more noticeably. It's subtle, but I notice it when I write while standing up. I know it's the vibrations through the table and I can't do anything about it. Unfortunately, that doesn't make it any less annoying.

Now that my screen floats above my desk, I noticed that I have a lot more table space. The place that the foot of the screen took up is quite large and now it's available for documents, my phone and keys. Maybe a microphone if I want to upgrade my audio setup. It's a decent arm and I love the additional space on my desk, but next time I would look for an arm with a more sturdy base so it won't wobble.

Disclaimer: I've bought all my gear myself with my own, hard earned, money. So no sponsorship here! Which is why I can give you the good and the bad.

The two ErgoChair 2 chairs were next to arrive, about one and a half month after ordering them. Before, I had a very comfortable Markus chair from Ikea (not the exact model as I bought mine about 8 years ago). It was a very comfortable chair, but I have to say that the ErgoChair 2 is an upgrade all around.

It started when I assembled the ErgoChair. The instructions are very clear and a lot of thought has gone into the assembly process. In a little over half an hour, I was done with one chair. The star of the show is the superb tool that is supplied. It makes tightening the bolts a breeze. No need to awkwardly grip the little metal tool that is normally supplied, with this tool the bolts are tightened in a flash.

During assembly, I did make a silly mistake: I put the arm rests on backwards on the first chair. Luckily I saw my mistake as I put the cushion (with the armrests) down. Besides my little derp moment, assembly went as smooth as it could have.

Now that I've used the chair for the past 2 months, I can say it's very pleasant to sit on. Almost everything can be adjusted. From the height of the chair, the headrest and the incline of the back, to the tilt of the cushion and back tilt tension. I'm not sure what that last one does, but it's impressive. They even have a very good instruction video on what you can adjust and how to do it, because I didn't even mention all the settings you can tinker with.

There is one minor point: the armrests. Like the rest of the chair, it's very customisable. I can adjust the height and move the armrest itself horizontally in all directions. Here is my biggest annoyance so far: the armrests just slide around. Most adjustments such as moving the armrest or the headrest up and own, happen in stages. I can feel the clicks and stands as I move them. Not so when horizontally positioning the armrests. This is most distracting when I move my arm from my keyboard to my mouse or the other way. Then the armrest can change positions without intending to do it.

The top of the armrest is made of a soft kind of plastic which is nice to the touch, but some fabric or fake leather with a cushion would have been more comfortable. Especially when sitting in the chair for hours during a workday. I think it's strange they did not use the same material of the cushion to make the armrest more comfortable.

Don't get me wrong, the armrest is still comfortable and I love the chair. There's a lot of thought put into this to make it as comfortable as possible. If the good folks at Autonomous add some cushion to the armrest, they'll have the perfect chair.

Up next week: the monitor arm, again from the good folks over at Autonomous.