This is a memo I want to share as I’ve written these thoughts in several messages and calls and pub chats.

People are ruining companies and open source.

This applies to any collaborative environment, I do not care how you use AI on your own personal hobby project. Perhaps it applies if you have users in production.

All my points apply to any work you do. This could be a PR, a config change, a new 3rd party tool, a word document, an email. All work may or may not have AI assistance these days.

Implicit trust

My primary point is that when you do work there is an unspoken agreement that you understand what you did. You also understand why you did it. What you did works, compiles, runs, works when doing basic exploration.

When you use AI to help you work - if you do not understand what it is doing, why, or have not FULLY done your due dilligence you:

• Insult whoever you show the work (PR reviewer, email reader, customer using your app)

  • You expect THEM to do the due dillegence on behalf of you - you break things, they report it, then you vibe another solution without doing the due dillegence. you get the point.

• Will not learn the product or grow as an asset to the company/project.

  • In the age of AI one of the benefits is that you should have more focus on product. Learn and understand the code, architecture AND business. There is no continual improvements, or human ideas that are the next moonshot for the company if you’re not at a baseline understanding what work the AI is doing for you.

  • You also are expected to learn from you mistakes - an outage is okay, but understand the root cause, and fix the culture that allowed it to happen in the first place. A vibe coded solution or feature means you will NEVER learn and are doomed to making the same mistake over and over again. As the complexity increases over time with new features, you have exponentially more outages, issues, loss of quality.

We are all guilty of taking shortcuts.

‘Oh this just changes the text on the page, I don’t need to compile’

Maybe this change was inside a YAML file and you run into the norway problem. What I mean is there are side effects of things you can never account for, no amount of ‘that is probably fine’ will get you by.

In the age before the AI boom, good citizens would do this 1% of the time.

I am now seeing the opposite - this is 99% of the time, and I am really sick of it.

The illusion of expertise

As models get better and better, they write code that looks well structured, seasoned and pragmatic. You see a PR and it looks great - merge it, then the most basic things break.

Before AI coding, you could get a rough guage of skill from looking at submitted code. Now it goes out the window.

We are moving to an engineering culture that favours personal reputation over code. Its really hard to guage if a perfect sounding patch is thought out, tested, had its due dilligence or not.

You might pull a collegue aside and ask them how to define an array in their primary language they get paid well to write - and yet there is no answer.

Do better. Do not submit code you do not fundamentally understand.

If you DO NOT understand code that agents have generated for you, you might see it as magic. You might think the model is therefore smarter than you, and as such its a perfect change. DO NOT DO THIS AT ALL COSTS.

No excuse for being spoon fed

I see it everywhere online, work chats - all of it.

People ask other people questions, without trying ANYTHING yet.

Open Source maintainers, online ‘helpful’ people or experts are NOT your unpaid personal staff engineers.

Did you even TRY to ask an agent your question?

Did you even TRY to play with the technique you’re asking about?

I’m not saying you shouldn’t ask for help, or be active in communitys - again, everything is shifting to reputation rather than code speaking for itself.

My advise is to exhaust ALL options before asking - and demonstrate what you’ve tried.

Are you submitting an LLM generated message to a human? Did you read the message before sending - or are you insulting the receiving party?

Closing loose ends

Finishing things is everything. Do not let AI get you 95% of the way there and move on to the new shiny object.

Please follow through and get it DONE. Not mostly done. Done.

You die by a thousand cuts with unfinished work.

Close the loop!

I don’t know the solution to these things, we’re seeing volume of slop, and work that is plain lazy, and its not good enough. Do better.

On the upside, for good citizens are able to self service and deep dive with no barriers easier than before.

I personally see this when I am able to fix issues inside of the Bun source code, Open Code project, OS diagnostics, remote servers, Azure configs the list goes on.

Please self reflect - its easy to fall into the traps of modern engineering, which also says that its easier than ever to stand out.

My stack focuses on high-speed context dumping and stateless execution loops.

The Stack

• handy.computer: Offline, local Whisper Turbo. I dictate complex architecture, or even loose conflicting thoughts at speech speed. This removes the barrier to providing the "half-useful" details that actually ground the architecture. Agent planning will question this later.

• opencode.ai: The terminal agent runner.

• CLI > MCP: I overwhelmingly prefer standard CLI tools over MCP. LLMs are trained on the internet. They know the CLI as model parameters. Agents can run --help. They don't know your custom MCP schema. Save the context window.

  • The Exception: playwriter. It uses standard Playwright syntax and attaches to your real browser to reuse auth/session state.

1. Ralph Driven Development

Credit to Geoffrey Huntley for the methodology.

The Core Philosophy: Erecting Signs Bad AI results are usually bad prompts, bad context, or bad data access. If the agent fails, do not just fix the code. Fix the prompt. If "Ralph" falls off the slide, you don't just put him back; you put up a sign that says "DON'T JUMP."

• Implementation: I use AGENTS.md (which OpenCode reads by default) to store these "signs." If the agent figures out a tricky build step, I instruct it to write that knowledge to AGENTS.md so the next loop doesn't have to rediscover fire.

Plans vs. Specs Huntley advocates for separating requirements into specs/*.md files.

• My take: Currently, I find a massive, well-structured plan.md sufficient for most tasks, though splitting specs is a valid optimization I am exploring.

While I use OpenCode - of course this works with Claude Code or any other harness.

2. The Planning Phase

I spend an hour purely on the plan. I do not touch code. I dictate high-level constraints and nitpick API surfaces until I have a plan.md that often reaches 1,000+ lines. I read every line, if I am not happy I keep planning.

The Pivot: Once the plan is solid, change to the build agent and send this prompt to crystallize the state:

"I love the plan. Please write it to plan.md in chronological order as a backlog with checkboxes. Each task should be small and isolated. Feel free to create a large backlog so it is specific enough for a new engineer to take over implementation immediately."

Most engineers would change to Build agent and send ‘go’.

3. The Execution Loop

Once plan.md is frozen, I run a headless loop. This forces the agent to re-read the full context every iteration, eliminating context drift. This ensures the agent has a vague understanding of the past AND the end state.

Bash (macOS/Linux):

while :; do opencode run -m "opencode/claude-opus-4-5" "READ all of plan.md. Pick ONE task. Verify via web/code search. Complete task, verify via CLI/Test output. Commit change. ONLY do one task. Update plan.md. If you learn a critical operational detail (e.g. how to build), update AGENTS.md. If all tasks done, sleep 5s and exit. NEVER GIT PUSH. ONLY COMMIT."; done

PowerShell (Windows):

while ($true) { opencode run -m "opencode/claude-opus-4-5" "READ all of plan.md. Pick ONE task. Verify via web/code search. Complete task, verify via CLI/Test output. Commit change. ONLY do one task. Update plan.md. If you learn a critical operational detail (e.g. how to build), update AGENTS.md. If all tasks done, sleep 5s and exit. NEVER GIT PUSH. ONLY COMMIT." }

4. Verification & Backpressure

The compiler is not just a runner; it is a filter. You need strict backpressure to reject hallucinations before they are committed.

• CLI Verification: Design codebases to be verifiable via args (e.g., dotnet run -- analyze).

• Strictness: In .NET, I enforce <TreatWarningsAsErrors>true</TreatWarningsAsErrors> and use the latest Roslyn analyzers in a root Directory.Build.props. If it warns, the loop fails, and Ralph tries again.

5. Brownfield vs. Greenfield

Huntley argues this is for Greenfield only. I disagree.

Because I spend significant time planning and never allow the agent to git push (only commit), I maintain a "Human in the Loop" review process. I manually review, apply taste, and test the final state before raising a PR. This makes the technique viable for Brownfield/Legacy codebases, provided you trust your review process more than the agent.

Future Roadmap

I am looking into community plugins for OpenCode to integrate a native "Ralph Agent."

• Parallelism: Currently, the loop is serial. Future harnesses should identify which tasks in plan.md can be parallelized (fan-out) and when they must converge for a blocking build step (fan-in).

Architecture is a certainty in software development. There have been many architectures over the years, and you can find a plethora of information on Google.

The history of just Vertical Slice Architecture is a bit more recent. The term was coined by Jimmy Bogard in 2018. However, the ideas behind it have been around for a while.

2015

In fact, as early as 2015, Jimmy was talking about SOLID Architecture which is essentially the same thing. It had a few key points (from his slides):

• SRP - One class per feature/concept
• OCP - Extend through cross-cutting concerns
• LSP - Just don't do inheritance
• ISP - Separating queries from commands
• DIP - Save for true external dependencies.

The key points of the SOLID architecture were really applying the principals to achieve a highly cohesive codebase in regard to the Domain specific code (SRP, ISP). The Domain specific code was then extended (OCP) via cross-cutting concerns - like authentication, authorization & generic logging.

A lot of the outcomes from this talk to me, was allowing a simpler architecture for what matters most - the Domain. The most important thing in software, is that it works. The architecture that allows you to deliver features quickly, is the best architecture for you.

2018

Moving along a few years, in 2018, Jimmy wrote a blog post called Vertical Slice Architecture. This was the first time the term was used. It was then shortly followed up with a presentation at NDC Sydney later that year.

The key points of this evolution of the architecture were (from the presentation):

• CQRS - e.g. HTTP GET is safe & idempotent, POST is Unsafe & not idempotent. Represent this two different concerns in different models/classes where this was just one.
• Vertical Slicing makes it easy to modify code
• Do not skip the refactor step in Red-Green-Refactor. (Common complaints about 'simple' architectures is due to this)
• Push behaviour down (i.e. Focus on a rich domain & allow handlers to do the 'ugly' work, like data access)
• Integration test handlers & unit test Domain

Where it was left

At that point, Jimmy has set the world up with some pretty nice foundations.

1. Logically split application reads & writes using CQRS.
2. CQRS models are use cases. Application use cases should be sliced & tightly coupled within
3. Refactor repeated logic into a rich Domain
4. Refactor repeated domain-agnostic code into services, repositories
5. Integration test use cases
6. Unit test the Domain

AutoMapper is one of the most popular mapping libraries in the .NET ecosystem. It is currently sitting at around ~10k stars on GitHub. The library was written by Jimmy Bogard (the VSA guy, the MediatR guy, etc) and has been around for a long time.

The library is meant to reduce the amount of manual, convention/pattern based mapping code you write in your application. Straight from the README:

AutoMapper is a simple little library built to solve a deceptively complex problem - getting rid of code that mapped one object to another. This type of code is rather dreary and boring to write, so why not invent a tool to do it for us

A lot of the pain does come from people using the library in an unintented way - for complex mappings that are not following a convention.

Jimmy writes about this in his blog post: Dissecting AutoMapper Programming Horror

The main takeaway for using AutoMapper is that it should be used for really simple mappings, e.g. for this example:

public record WeatherForecast(DateTime Date, int TemperatureC, string Summary);
public record WeatherForecastDto(DateTime Date, int TemperatureC, string Summary);

The convention is clear, and the mapping is simple - less code to write. Its a big win to use the library!

The source of hate

I've personally used AutoMapper for a long time now. Its included in many popular templates, like many of the Clean Architecture templates that long dominate the .NET Enterprise space.

A lot of the hate is chalked up to the misuse of the library, which Jimmy breaks down greatly in the linked blog post. I won't comment further on that, as he does a great job.

The second main reason that goes around is performance. Yes - it uses reflection, and that is slower than manual/source generated code. That is a valid reason.

The final reason, which is the main one for me, is that it reduces the ability for static analysis between code. This is a big one in the Vertical Slice Architecture space, and that is what I spend a lot of time working within. Optimising for developer confidence, and refactor-ability.

Now what do I mean by that?

Context on a Sample application

For the rest of the blog post, I will use a very simple sample application, using the following Domain entity that will be mapped into DTOs using different methods.

public class WeatherForecast
{
    public DateOnly Date { get; set; }
    public int TemperatureC { get; set; }
    public string? Summary { get; set; }
}

Note: All the code from this article is available on my GitHub here 🧑‍💻

Each mapping sample has its own copy of the following DTO, to look into the static analysis that an IDE can see.

public class WeatherForecastDto
{
    public DateOnly Date { get; set; }
    public int TemperatureC { get; set; }
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    public string? Summary { get; set; }
}

We could even make it so that the TemperatureF is a calculated property from mapping configuration, but I want to keep it really simple.

Reduced static analysis

To put it very quickly, because the library is implemented using reflection, the links between objects and properties is not clear.

To configure AutoMapper, we simply add this line to a mapping configuration (probably through a Profile)

CreateMap<WeatherForecast, WeatherForecastDto>();

In this example, we can see that none of the fields are show have any Usages. This means it can't find where it is set from. When I refactor in an area I don't know well, potentially remove fields from the Domain entity, or even rename them - I have no confidence that the mapping will still work.

This is a big problem for me, and I know it is for others too.

What can I do otherwise?

Yes, you can manually map each property with AutoMapper, but that is directly counter to the point of the library.

Manual Mapping

Okay, we want a more safe codebase with static analysis, how about we just manually map the properties?

public static class Mapping
{
    public static WeatherForecastDto ToDto(this WeatherForecast entity)
    {
        return new WeatherForecastDto
        {
            Date = entity.Date,
            TemperatureC = entity.TemperatureC,
            Summary = entity.Summary
        };
    }
}

Now with this, we get the following static analysis in the IDE:

That's pretty good! I can see where the properties are being used, and I can refactor with confidence.

However, we feel the same pain that caused Jimmy to write AutoMapper. For a lot of mapping, this is a lot of code!

Mapperly

This is where I want to introduce Mapperly. Similar to my AutoMapper introduction, here is a quote from the public site:

A .NET source generator for generating object mappings. No runtime reflection.

That sounds pretty awesome. A source generator, if you don't know generates code at compile time. The mapper wil basically create the mapping we did in the Manual section, but without us having to write it.

Let's set it up!

There are several ways to do it, however I like the static extension method syntax.

[Mapper]
public static partial class Mapper
{
    public static partial WeatherForecastDto ToDto(WeatherForecast entity);
}

That's it - inspecting the source generated output, we can see the generated code is very similar:

// <auto-generated />

...

[global::System.CodeDom.Compiler.GeneratedCode("Riok.Mapperly", "3.6.0.0")]
public static partial global::App.Mapperly.WeatherForecastDto ToDto(global::Domain.WeatherForecast entity)
{
    var target = new global::App.Mapperly.WeatherForecastDto();
    target.Date = entity.Date;
    target.TemperatureC = entity.TemperatureC;
    target.Summary = entity.Summary;
    return target;
}

In this sample comparison I didn't use extension method syntax, because of many conflicting namespaces. So for this case I called the map method like so: var mapperlyDto = App.Mapperly.Mapper.ToDto(weatherForecast);

I would suggest using the extension method syntax, as it is much cleaner...

Anyway, as you would expect the static analysis is the same as the manual mapping.

Although it has the same great static analysis, we have the added benefit that we don't have to write the mapping code! This is the best of both worlds, convention based mapping, but manual mapping's static analysis!

What about performance?

Of course, we know AutoMapper is slow, but how slow? How does Mapperly compare to manual mapping?

I wrote a simple benchmark to compare. The whole snippet is this:

Program.cs

BenchmarkRunner.Run<Benchmarks>();

public class Benchmarks
{
    private static readonly WeatherForecast DomainEntity = new WeatherForecast
    {
        Date = new DateOnly(2021, 1, 1),
        TemperatureC = 25,
        Summary = "Mild"
    };

    [Benchmark(Baseline = true)]
    public int Manual()
    {
        var dto = DomainEntity.ToDto();

        return dto.TemperatureF;
    }

    private static readonly IMapper Mapper = new MapperConfiguration(cfg => cfg.AddProfile<App.AutoMapper.Mapping>()).CreateMapper();

    [Benchmark]
    public int AutoMapper()
    {
        var dto = Mapper.Map<App.AutoMapper.WeatherForecastDto>(DomainEntity);

        return dto.TemperatureF;
    }

    [Benchmark]
    public int Mapperly()
    {
        var dto = App.Mapperly.Mapper.ToDto(DomainEntity);

        return dto.TemperatureF;
    }
}

The results come back very clear.

Note - I marked the manual mapping as the baseline. That means both Mapperly and AutoMapper get compared to the manual mapping.

BenchmarkDotNet v0.14.0, Windows 11 (10.0.22631.3880/23H2/2023Update/SunValley3)
Intel Core i7-14700K, 1 CPU, 28 logical and 20 physical cores
.NET SDK 8.0.303
  [Host]     : .NET 8.0.7 (8.0.724.31311), X64 RyuJIT AVX2
  DefaultJob : .NET 8.0.7 (8.0.724.31311), X64 RyuJIT AVX2


| Method     | Mean      | Error     | StdDev    | Ratio | RatioSD |
|----------- |----------:|----------:|----------:|------:|--------:|
| Manual     |  4.094 ns | 0.0565 ns | 0.0501 ns |  1.00 |    0.02 |
| AutoMapper | 35.244 ns | 0.1533 ns | 0.1280 ns |  8.61 |    0.11 |
| Mapperly   |  4.077 ns | 0.0278 ns | 0.0371 ns |  1.00 |    0.01 |

Awesome - Mapperly is as fast as manual mapping, and AutoMapper is 8.61 times slower!

Note: The performance here is within nanoseconds, so for most applications that will be negligible. I don't see it as a key factor in this case to pick Mapperly over AutoMapper.

This really proves that modern mapping libraries that use source generators are the way to go.

EF Core projections

Once you start building real world apps inside of an AutoMapper codebase, a great feature is automatically projecting SQL queries into DTOs. It reduces the amount of fields coming back over the wire, and can be a big performance win.

How does this work in AutoMapper?

Take the following example DbContext:

public class WeatherForecastContext : DbContext
{
    public DbSet<WeatherForecast> WeatherForecasts { get; set; }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseInMemoryDatabase("WeatherForecast");
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<WeatherForecast>().HasKey(e => e.Date);
    }
}

Let's say we want to query a slim version of WeatherForecast data.

The DTO would look like so:

public record WeatherProjection(DateOnly Date, int TemperatureC);

Using aggressive inlining (again, in a real app you would be using Profiles)

private readonly IConfigurationProvider _automapperConfig = new MapperConfiguration(cfg => cfg.CreateMap<WeatherForecast, WeatherProjection>());

Using the AutoMapper configuration we setup, we can project any query into the DTO.

Lets grab the first record.

public string AutoMapperProjection()
{
    var output = _context.WeatherForecasts
        .AsQueryable()
        .ProjectTo<WeatherProjection>(_automapperConfig)
        .First();

    return output.ToString();
}

Okay that's pretty awesome!

We really like this feature, and we want to use it with Mapperly.

Well the good news is you can do this!

First, lets create the mapper.

[Mapper]
public static partial class WeatherProjectionMapper
{
    public static partial IQueryable<EfCoreSample.WeatherProjection> Project(this IQueryable<WeatherForecast> q);
}

Now we can use the following code to project the query very similarly to AutoMapper:

public string MapperlyProjection()
{
    var output = _context.WeatherForecasts
        .AsQueryable()
        .Project()
        .First();

    return output.ToString();
}

Conclusion

• AutoMapper is great to reduce code to write, but people misuse it, its slow (comparatively), and reduces static analysis (big deal)

• Manual mapping is great for static analysis, but can be a lot of code to write.

• Mapperly is the best of both worlds, and is as fast as manual mapping. ⭐

I hope you enjoyed this blog post, and I hope you give Mapperly a try in your next project!

If you like the sound of Mapperly, then good news because its part of my Vertical Slice Architecture template!

Finally, find the complete sample code here: https://github.com/Hona/ReferenceCode/tree/main/AutoMapperBlog

A little while ago I was wanting to find a way to allow my PostCSS Tailwind styles to be close to my Razor components.

Without any additional work, you might end up building styles & components in the following structure:

📁 BlazorApp/
│
│── 📁 Shared/ 
│   │
│   │── MyButton.razor
|
│── 📁 Styles/ 
    │── 📄 MyButton.css

MyButton.razor

<button class="bg-amber-800" @onclick="IncrementCount">Click me</button>

MyButton.css

button {
    @apply rounded-xl p-8;
    width: calc(100% - 2rem);
}

This omits the other files like tailwind.config.js that come from a project setup.

Checkout Chris Sainty's awesome tutorial for setting up Tailwind in a Blazor project. You can imagine this blog post as an extension to that tutorial.

Note that inline styles already work if you followed Chris's setup, however when we need to get a bit more power, like writing styles once & using it many times, or mixing tailwind with typical css (e.g. the width calculation above), this approach falls short.

So, back to the structure. There are two problems:

• When I want to change MyButton I've got the files all scattered about. This violates the proximity principle and makes it harder to maintain - especially as your app grows.

• Writing styles that get built using PostCSS into a published CSS file means that you don't gain the benefits of scoped CSS. You have to manually make sure there are no selectors that clash with other components.

• You can't use @apply or write mixed CSS & Tailwind styles.

The Solution

Let's do better now.

First, lets create a SCSS file next to the component.

📁 Shared/ 
│── MyButton.razor
│── MyButton.razor.scss

This is not going to work out of the box, yet.

The first step is to extend the tailwind.config.js file to find classes in any razor file or SCSS file.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./**/*.{razor,css,scss,cs,html,js}"], // 👈 Add SCSS & Razor files
  theme: {
    extend: {},
  },
  plugins: [],
}

This is a nice glob of all things that could include a Tailwind class.

We have to make sure that SCSS compilation works for all users no matter the IDE or extensions. Previously for SCSS a lot of users would have to install an extension to get it to work. e.g. this one for Visual Studio.

We actually can make this work in the MSBuild process meaning any IDE or even the command line will work.

In your csproj file, e.g. BlazorApp.csproj add the following:

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

    <PropertyGroup>
        <TargetFramework>net7.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="BlazorComponentUtilities" Version="1.8.0" />
        ...
    </ItemGroup>

    <!-- 👇 New Code -->
    <Target Name="StylesCompile" BeforeTargets="BeforeBuild">
        <!-- On Error, write the stderr as a build error -->
        <Exec ConsoleToMSBuild="true" Command="npm run build:scoped-css" />
        <Exec Command="npm run build:css" />
    </Target>
    <!-- 👆 New Code -->

</Project>

This allows us to run an NPM script BEFORE any files are added to the build process. You might be able to figure out where this is headed.

Now we need to add the package.json that contains the scripts build:scoped-css and build:css

{
  "devDependencies": {
    // ⚠️ Versions may vary
    "autoprefixer": "^10.4.13",
    "postcss": "^8.4.19",
    "postcss-cli": "^10.0.0",
    "tailwindcss": "^3.2.4",
    "glob": "^8.0.3"
  },
  "scripts": {
    "build:scoped-css": "node build-scoped-css.js",
    "build:css": "postcss wwwroot/css/app.scss -o wwwroot/css/app.min.css"
  }
}

Note the differences between the scripts.

• build:scoped-css runs a custom script build-scoped-css.js that we will create in a moment.

• build:css processes the single 'global' SCSS file into a single CSS file. This is nothing special - however, if we're adding SCSS we might as well make it consistent.

It's magic time! Create a file called build-scoped-css.js in the root of your project.

const glob = require('glob');
const {exec} = require('child_process');

// 👇 Find every scoped SCSS file
glob("**/*.razor.scss", function (er, files) {
    files.forEach(function (file) {
        // 👇 Output the processed file as *.razor.css, which is a normal scoped CSS file
        const command = `npx postcss "${file}" -o "${file.replace('.razor.scss', '.razor.css')}"`;
        console.log(command)
        exec(command, (error, stdout, stderr) => {
            if (error) {
                console.error(`exec error: ${error}`);
                return;
            }
            console.log(`stdout: ${stdout}`);
            console.error(`stderr: ${stderr}`);
        });
    });
})

Make sure your index.html file includes both the Scoped CSS file and the global CSS file.

<head>
    <link href="css/app.min.css" rel="stylesheet" />
    <link href="BlazorApp.styles.css" rel="stylesheet" />
</head>

To summarise what we just added, a few steps occur.

1. Before running any Blazor build steps we run 2 scripts

2. The first script outputs *.razor.css files for every *.razor.scss file

3. The second script processes the global SCSS file into a single CSS file

4. The Blazor build process then runs as normal, with the working CSS files included

🥳 That is all it takes!

If you want a complete example to follow rather than a step by step, here is my repository that setup an example project with these steps completed:

⭐ https://github.com/Hona/Blazor.Tailwind

It features a demo website on GitHub pages that you can explore also.

Vertical Slice Architecture (VSA) is a great way to structure your code. Getting started with a new or familiar architecture can be daunting, so I've created a quick start guide to get you up and running by using a dotnet new template.

What is Vertical Slice Architecture?

VSA is primarily about separating use cases or features entirely, in such a way that they do not rely or communicate on each other. This is reflected via the 'vertical' nature of the architecture, where each feature is a vertical slice of the application.

Compared to traditional structures like N-tier or even Clean Architecture, where they are organised in ways of grouping by technical concern (Web API, Data Access), VSA groups by the feature or use case.

To get a quick briefing on a few of the key players in Software Architecture watch my User Group here:

Vertical Slice Architecture: How Does it Compare to Clean Architecture

This theory is all well and good, but how do I represent this in a .NET Application?

The Template

https://github.com/Hona/VerticalSliceArchitecture

The template is a simple .NET 8 template that creates a solution with 1 source project (ASP.NET Core) & 1 test project (xUnit).

The source project is setup with a few important folders to get you started:

📁 [ProjectName]/
│
│── 📁 Features/ 
│   │
│   │── 📁 Todo/
│       │── 🤔
|
│── 📁 Common/ 
    │── 📄 AppDbContext.cs
    │── 📄 *

What is inside each feature folder however?

This is where a little magic happens.

📁 Todo/
│
│── 📁 CreateTodo/
│   │── 📄 CreateTodoEndpoint.cs
│   │── 📄 CreateTodoRequest.cs
|
|── 📁 GetTodo/
|   │── 📄 *
|
|── 📁 [...]
|
|── 📄 TodoEntity.cs
|── 📄 TodoRepository.cs
|── 📄 DependencyInjection.cs

From here, as you can see - each feature contains an entity & repository for each use case to consume. As well as a Dependency Injection class to wire up services to the IoC container.

This is a great way to get started with VSA, and I hope you find it useful!

Bigger enterprise apps will need more features & different things to consider, like a Modular Monolith. But, that is for another time.

How to use the template

To use the template, you need to install it first. This is done via the dotnet new command.

dotnet new install Hona.VerticalSliceArchitecture.Template

Then, create a project (e.g. called 'Sprout')

mkdir Sprout
cd Sprout

dotnet new hona-vsa

Let me know your thoughts below, or if I should add anything else to the template!

Building a personal project can be exciting, but it can also be a lot of work. In this post, I will go over how to use Marten DB to quickly build a backend for your project.

The Problem

When building a project, you will often need to build a backend for it. This can be a lot of work, and it's easy to get distracted by the infrastructure and forget about the project. In this post, I will go over how to use Marten DB to quickly build a backend for your project.

The Solution

Marten DB is a fantastic document store that uses PostgreSQL as the database engine. It is easy to use, and allows you to quickly build your backend.

Marten's Background

Before Marten came around, the de facto Document DB to use was Raven DB. Raven DB was a fantastic Document DB, but it was not free.

The developers behind Marten were working on a 'very large web application' that was suffering with performance and stability issues - that was using RavenDB as the document store. They decided to build their own document store, and Marten was born.

But why the name?

Straight from the Marten DB website:

The project name Marten came from a quick Google search one day for "what are the natural predators of ravens?" -- which led to us to use the marten as our project codename and avatar.

A bit of a superhero origin story, but it's a great name!

Setting up Marten DB

First things first lets create a new ASP.NET Core Web API, and add MediatR to it. While we are at it, let's also add Marten.

dotnet new webapi -o MartenTest
cd MartenTest
dotnet add package Marten
dotnet add package MediatR

Now we need to add a connection string to our appsettings.json file. I am using a local PostgreSQL database, but you can use any version Marten supports, which as of right now is: PostgreSQL 9.6 or above database with PLV8

appsettings.Development.json

{
  "ConnectionStrings": {
    "MartenTest": "Host=localhost;Database=MartenTest;Username=postgres;Password=postgres"
  }
}

Next lets setup the pipeline in Program.cs

builder.Services.AddMarten(options =>
{
    options.Connection(builder.Configuration.GetConnectionString("Marten"));

    options.AutoCreateSchemaObjects = builder.Environment.IsDevelopment()
        ? AutoCreate.All
        : AutoCreate.CreateOrUpdate;
});

// For the sake of this article we'll just put everything into one project
builder.Services.AddMediatR(typeof(Program).Assembly);

As a homage to the Blazor template using WeatherForecasts as the model of choice, lets build a few commands and queries to perform CRUD operations on.

MartenTest/Domain/WeatherForecast.cs

public record WeatherForecast(DateTime Date, int TemperatureC, string Summary);

Now, if you've used Document Stores to any degree before - we need to have a field that acts as the identity or primary key. Marten DB by default looks for the Id property, so we need to manually configure it to use Date instead.

MartenTest/Program.cs

builder.Services.AddMarten(options =>
{
    ...

    options.Schema.For<WeatherForecast>()
        .Identity(x => x.Date);
});

CREATE

MartenTest/Application/CreateWeatherForecastCommand.cs

public record CreateWeatherForecastCommand(WeatherForecast WeatherForecast) : IRequest<WeatherForecast>;

public class CreateWeatherForecastCommandHandler : IRequestHandler<CreateWeatherForecastCommand, WeatherForecast>
{
    private readonly IDocumentSession _documentSession;

    public CreateWeatherForecastCommandHandler(IDocumentSession documentSession)
    {
        _documentSession = documentSession;
    }

    public async Task<WeatherForecast> Handle(CreateWeatherForecastCommand request, CancellationToken cancellationToken)
    {
        await _documentSession.Insert(request.WeatherForecast);
        await _documentSession.SaveChangesAsync(cancellationToken);

        return request.WeatherForecast;
    }
}

UPDATE

MartenTest/Application/UpdateWeatherForecastCommand.cs

public record UpdateWeatherForecastCommand(WeatherForecast WeatherForecast) : IRequest<WeatherForecast>;

public class UpdateWeatherForecastCommandHandler : IRequestHandler<UpdateWeatherForecastCommand, WeatherForecast>
{
    private readonly IDocumentSession _documentSession;

    public UpdateWeatherForecastCommandHandler(IDocumentSession documentSession)
    {
        _documentSession = documentSession;
    }

    public async Task<WeatherForecast> Handle(UpdateWeatherForecastCommand request, CancellationToken cancellationToken)
    {
        _documentSession.Store(request.WeatherForecast);
        await _documentSession.SaveChangesAsync(cancellationToken);

        return request.WeatherForecast;
    }
}

An important thing to note is the nomenclature. You would use Insert to create a new document, and Store to update or create an existing document.

DELETE

MartenTest/Application/DeleteWeatherForecastCommand.cs

public record DeleteWeatherForecastCommand(DateTime Date) : IRequest;

public class DeleteWeatherForecastCommandHandler : IRequestHandler<DeleteWeatherForecastCommand>
{
    private readonly IDocumentSession _documentSession;

    public DeleteWeatherForecastCommandHandler(IDocumentSession documentSession)
    {
        _documentSession = documentSession;
    }

    public async Task<Unit> Handle(DeleteWeatherForecastCommand request, CancellationToken cancellationToken)
    {
        _documentSession.Delete<WeatherForecast>(new WeatherForecast(request.Date, 0, ""));
        await _documentSession.SaveChangesAsync(cancellationToken);

        return Unit.Value;
    }
}

READ

MartenTest/Application/GetWeatherForecastQuery.cs

public record GetWeatherForecastQuery(DateTime Date) : IRequest<WeatherForecast>;

public class GetWeatherForecastQueryHandler : IRequestHandler<GetWeatherForecastQuery, WeatherForecast>
{
    private readonly IDocumentSession _documentSession;

    public GetWeatherForecastQueryHandler(IDocumentSession documentSession)
    {
        _documentSession = documentSession;
    }

    public Task<WeatherForecast> Handle(GetWeatherForecastQuery request, CancellationToken cancellationToken)
    {
        return _documentSession.Query<WeatherForecast>()
            .FirstOrDefaultAsync(x => x.Date == request.Date, cancellationToken);
    }
}

Just like that we have a fully functional infrastructure. As a bonus - lets use minimal APIs to expose our CRUD operations.

Minimal APIs are a new feature in .NET 6 that allows you to build web APIs without having to use controllers. You can read more about them here.

MediatR is discussing adding support for minimal APIs here.

MartenTest/WebApi/Endpoints.cs

public static class Endpoints
{
    public static void MapEndpoints(this WebApplication app)
    {
        app.MapGet("/weatherforecast/{date}", (DateTime date, IMediator mediator, CancellationToken ct) =>
            mediator.Send(new GetWeatherForecastQuery(date), ct)
        );
        app.MapPost("/weatherforecast", ([FromBody] model, IMediator mediator, CancellationToken ct) =>
            mediator.Send(new CreateWeatherForecastCommand(model), ct)
        );
        app.MapPut("/weatherforecast", ([FromBody] model, IMediator mediator, CancellationToken ct) =>
            mediator.Send(new UpdateWeatherForecastCommand(model), ct)
        );
        app.MapDelete("/weatherforecast/{date}", (DateTime date, IMediator mediator, CancellationToken ct) =>
            mediator.Send(new DeleteWeatherForecastCommand(date), ct)
        );
    }
}

MartenTest/Program.cs

var app = builder.Build();

...

app.MapEndpoints();

app.Run();

And that's it! We have a fully functional CRUD API that uses Marten DB as the data store.

Conclusion

Marten DB is a great tool for building Document Stores in .NET. It's easy to use, and has a lot of great features. I hope this article has helped you get started with Marten DB. If you have any questions or comments, feel free to reach out to me on Twitter @LukeParkerDev.

Please let me know what you think of Marten DB, or this article. I'd love to hear your feedback in the comments below!

Blazor WebAssembly is a great framework for building web applications. It's fast, easy to use, and has a great community. However, there is one thing that is often overlooked when building a Blazor WebAssembly application, and that is SEO. In this post, I will go over the problem and how to fix it.

The Problem

As we know Blazor WASM is a static site, however it requires JavaScript to run on the client and load the .NET Framework using WebAssembly. This means when a crawler like GoogleBot visits the site to index it & load information the default index.html is served.

Basically the only text that is 'human readable' by default in this file is:

<div id="blazor-error-ui">
    An unhandled error has occurred.
    <a href="" class="reload">Reload</a>
    <a class="dismiss">🗙</a>
</div>

So what does that mean for your SEO?

Well, what google thinks your site is, is a broken website.

The Quick Solution

If you are just looking for general accuracy for your site, you can just add <meta> tags to the head of your index.html file. This will tell Google what your site is about, and will help with the accuracy of your search results.

An example of this is:

<meta Name="keywords" Content="Keywords" />
<meta Property="og:title" Content="Title" />
<meta Name="twitter:title" Content="Title" />
<meta Name="description" Content="SubTitle" />
<meta Property="og:description" Content="SubTitle" />
<meta Name="twitter:description" Content="SubTitle" />

Much better than the error message you get by default!

However, this is not a great solution.

1. It still won't load any of the page which helps with keywords and ranking metrics.

2. What if you have a blog?

3. What if you have subpages that should have descriptions?

The Better Solution - Prerendering for Crawlers

The better solution is to prerender the pages for crawlers. This means that when a crawler visits the site, it will get a fully loaded and cached version of your site. This won't impact your users at all, and allows you to use a free hosting service like GitHub Pages, or Azure Static Web Apps.

The Benefits

• Custom <meta> tags and SEO data for each page. Completely customizable in your Razor components!

• No impact on your users, as the prerendering is only for crawlers.

Prerendering with Blazor

A prerequisite to this way of prerending is that you use Cloudflare for your DNS.

In my case lukeparker.dev is hosted on GitHub Pages & CloudFlare pages, with CloudFlare as the DNS provider.

Prerender.io - A SPA Prerendering Service for Crawlers

I am not sponsored or affiliated with prerender.io in any way. I use the free service and it works well.

prerender.io is a service that allows you to prerender your site for crawlers. It's free for up to 1000 prerenders per month, which is more than enough for most sites (roughly 250 unique pages).

It utilizes an industry standard for this problem which is Dynamic Rendering. Which, like I outlined is basically prerendering the site for crawlers, while serving the normal site for users.

Setting it Up

Thankfully instead of me maintaining a third party manual, they have a CloudFlare integration guide here.

Basically you copy a little JavaScript code into a new Worker on CloudFlare & setup your API key & domain.

At that point you're good to go & can start using prerender.io!

Blazor SEO - Page-based Dynamic Metadata

Note: My implementation is heavily based on MudBlazor's which is what prompted me to go down the SEO route with Blazor WASM.

Firstly we need to create a component that will be used to set the metadata for each page. This is a simple component that will take in a title, description, and keywords.

Create a file called SeoHeader.razor.

Then lets fill it with the following:

<PageTitle>@(GetTitle())</PageTitle>
<HeadContent>
    <meta Name="keywords" Content="@GetKeywords()" />
    <meta Property="og:title" Content="@GetTitle()" />
    <meta Name="twitter:title" Content="@GetTitle()" />
    @if (!string.IsNullOrEmpty(Overview))
    {
        <meta Name="description" Content="@GetSubTitle()" />
        <meta Property="og:description" Content="@GetSubTitle()" />
        <meta Name="twitter:description" Content="@GetSubTitle()" />
    }
</HeadContent>

Note the usage of <PageTitle> to set the tab title & the <HeadContent> to set part of the <head> of the page using the new HeadOutlet.

Now we just need to fill out the code that takes these variables and returns the nice strings.

Add this code at the bottom of the component:

@code {
    [Parameter]
    public string? Title { get; set; }

    [Parameter]
    public string? Overview { get; set; }

    [Parameter]
    public IEnumerable<string> Keywords { get; set; } = new List<string>();

    string GetTitle() => Title is null ? "LukeParkerDev" : $"{Title} | [YOUR BRAND NAME/SUFFIX]";

    string GetSubTitle()
    {
        if (string.IsNullOrEmpty(Overview))
            return "";
        return Overview.TrimEnd('.') + ".";
    }

    string GetKeywords()
    {
        var keywords = new List<string>();

        keywords.AddRange(Keywords);

        keywords.Add("[YOUR NAME or BRAND]");

        return string.Join(", ", keywords);
    }
}

At this point the component is ready to be consumed in every Razor Page.

Using the SEO Header Component

Starting simple, lets add it to the Index page.

<SeoHeader
    Overview="My personal website acting as a personal portfolio as well as a blog to share my knowledge." 
    Keywords="@(new []{"blog", "portfolio"})"/>

This one just sets a description & keywords. Remember it always adds the one keyword of your brand name.

Now lets add it to something more dynamic, like a blog post, dynamically loaded

@if (_loading)
{
    <MudProgressLinear Color="Color.Secondary" Indeterminate/>
}
else if (_blog is not null)
{
    <SeoHeader 
            Title="@_blog.Frontmatter.title" 
            Overview="@_blog.Frontmatter.hook" 
            Keywords="_blog.Frontmatter.categories
                .Concat(_blog.Frontmatter.series)
                .Concat(_blog.Frontmatter.tags)" />
    ...
}

Thats all! Now your site will slowly get crawled by Google & others, in a few days you'll see the updated version of your site!

The Result

This exact site uses that approach, and here is an example of the result in Discord:

Even better is MudBlazor's, which has a lot more pages & content:

Conclusion

I hope this post has helped you understand how to do SEO with Blazor WASM. If you have any questions, feel free to ask in the comments!

Next Steps

You might want to generate a SiteMap dynamically, or have one statically, which helps Google & other crawlers find your pages much more easily! You can see how I do it here on my blog's Build Job.

Before we can get started using the many great components provided by AntBlazor, we have to first install it and follow the setup steps.

NuGet

Using your package manager, add a reference to the latest version of AntDesign in the project OKR.Web

Blazor Boilerplate

Now with the package installed, we have to reference the assets and add a few modules to the dependency injection.

Add to OKR.Web/Pages/_Host.cshtml, just before the <head> tag closes:

<link href="_content/AntDesign/css/ant-design-blazor.css" rel="stylesheet" />
<script src="_content/AntDesign/js/ant-design-blazor.js"></script>

This references the default CSS file - you can replace it to easily get dark mode, or a custom theme. There is also some JS interop required hence the import.

OKR.Web/Startup.cs

services.AddAntDesign();

This is an extension method provided in the library, which adds the services all in one clean call. Some of the services added here is the message service, modal service, etc.

OKR.Web/App.razor

<AntContainer />

At the bottom of the file add this line, this allows the popups to run globally and persist on page changes, as well as other uses.

Finally, we need to add the AntBlazor namespace to the Blazor component imports:

OKR.Web/_Imports.razor

@using AntDesign

That's it! We are now ready to build with these enterprise grade components.

Removing Bootstrap

A small caveat of the Blazor template provided by .NET is that all projects begin with Bootstrap and Open Iconic. The CSS file conflicts with AntBlazor and causes some centring issues.

As we aren't using Bootstrap or Open Iconic in this project at all, we can just delete both of them completely:

• OKR.Web/wwwroot/css/bootstrap

• OKR.Web/wwwroot/css/open-iconic

Removing Unused CSS

Now that there is no bootstrap, there was some custom CSS that we don't use, so lets clean it up.

OKR.Web/wwwroot/css/site.css

  #blazor-error-ui {
      background: lightyellow;
      bottom: 0;
      box-shadow: 0 -1px 2px rgba(0, 0, 0, 0.2);
      display: none;
      left: 0;
      padding: 0.6rem 1.25rem 0.7rem 1.25rem;
      position: fixed;
      width: 100%;
      z-index: 1000;
  }

      #blazor-error-ui .dismiss {
          cursor: pointer;
          position: absolute;
          right: 0.75rem;
          top: 0.5rem;
      }

Delete everything from the file leaving just the Blazor error UI - which is the bar on the bottom.

Using Forwarded Headers

As we are proxying from HTTPS/domain to the project using NGINX, the application needs to change the pipeline so that redirects are correct, and HTTPS is correctly detected. We also don't need to force redirects to HTTPS as it is already forced using NGINX.

Just before app.UseStaticFiles(); add the following:

OKR.Web/Startup.cs

app.UseForwardedHeaders(new ForwardedHeadersOptions
{
    ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});

Then, delete the redirection: app.UseHttpsRedirection();

Verify AntBlazor is Working

Inside of Index.razor, there is currently a simple 'Hello World', lets test everything is working correctly by displaying a simple button:

OKR.Web/Pages/Index.razor

<Button Type="primary">Primary</Button>

You should see the following:

If you got this far, you are doing great!

Designing the Main Layout

The AntBlazor documentation is great, it provides many examples of how to setup a typical layout.

For this project, at least initially we don't need a complex setup, but for future proofing we can include a menu bar, with navigation, as well as a simple content area for our page (anything with a route) components.

Lets replace the OKR.Web/Shared/MainLayout.razor with the following (using AntBlazor components)

@inherits LayoutComponentBase

<Layout Style="min-height: 100vh; width: 100vw">
    <Header Style="display: flex; align-items: center;">
        <Title Level="2" Class="ant-menu-dark ant-menu-submenu-open" Style="padding: 0; margin: 0 12px 0 0; color: #ffffff">OKR</Title>
        <Menu Theme="MenuTheme.Dark" Mode="MenuMode.Horizontal" DefaultSelectedKeys=@(new[]{"2"})>
            <AntDesign.MenuItem Key="1">nav 1</AntDesign.MenuItem>
            <AntDesign.MenuItem Key="2">nav 2</AntDesign.MenuItem>
            <AntDesign.MenuItem Key="3">nav 3</AntDesign.MenuItem>
        </Menu>
    </Header>
    <AntDesign.Content Style="padding: 0 50px;">
        <Breadcrumb Style="margin: 16px 0;">
            <BreadcrumbItem>Home</BreadcrumbItem>
            <BreadcrumbItem>List</BreadcrumbItem>
            <BreadcrumbItem>App</BreadcrumbItem>
        </Breadcrumb>
        <div>@Body</div>
    </AntDesign.Content>
    <Footer Style="text-align: center;">©2021 Created by Luke Parker</Footer>
</Layout>

Your layout should look similar to this:

At this point we have a consistent visual story without thinking and we can begin designing the OKR cards. For the dashboard, we should have an overview of each OKR. The perfect component for this is the Card.

Before we get started however, we need to build a view model to act as an aggregate object of the object and all the key results.

Create a file: OKR.Web/ViewModels/OKRViewModel

public class OKRViewModel
{
    public Objective Objective { get; set; }
    public IReadOnlyList<KeyResult> KeyResults { get; set; }
}

At this point we can assume that the OKR Card component will take a single OKRViewModel - where this data comes from right now doesn't matter.

Lets create OKR.Web/Shared/OKRCard.razor

@using OKR.Web.ViewModels
<Card Bordered="true" Hoverable="true" Class="okr-card"
      Title="@(OKR?.Objective.Title ?? "Loading...")">
    <Extra>
        <AntDesign.Progress Type=ProgressType.Circle 
                  Percent="@((int)_completion)" 
                  Size=ProgressSize.Small />
    </Extra>
    <Body>
        <AntList DataSource="@OKR.KeyResults">
            <ListItem>
                <ListItemMeta Description="@context.Description">
                    <TitleTemplate>
                        @context.Title
                    </TitleTemplate>
                </ListItemMeta>
                <div style="width: 35%">
                    <AntDesign.Progress Percent="@((int)(context.Completion * 100))" Size="@ProgressSize.Small" />
                </div>
            </ListItem>
        </AntList>
    </Body>
</Card>

@code {
    [Parameter]
    public OKRViewModel OKR
    {
        get => _okr;
        set
        {
            _okr = value;
            _completion = value.KeyResults.Average(keyResult => keyResult.Completion * 100);
        }
    }

    private decimal _completion;
    private OKRViewModel _okr;
}

Note that there is the Class property, instead of class. This is a custom AntBlazor property that passes the parameter to the real HTML element, which is very useful for custom styling.

Try running it, and you should get something that looks like this:

In this post we got started with building a component using the AntBlazor library. In the next post, I continue the UI layout with AntBlazor.

← Part 2

There is one objective with many key results. I added some properties that I think will be useful. These may change as we figure out the UI/UX a bit more.

Some feature ideas:

• Objectives should be toggleable if they are active or not
• Objectives should have a start and end date
• Objectives should have a brief title, and a longer description
• Key Results should have a brief title, and a longer description
• Key Results should be toggleable if they are active or not
• Key Results should have a completion percent 0%-100%
• Key Results should have a priority (higher the number the more important)

public class Objective
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public DateTime DueDate { get; set; }
    public DateTime StartDate { get; set; }
    public bool Active { get; set; }
}

public class KeyResult
{
    public Guid Id { get; set; }
    public Guid ObjectiveId { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public bool Active { get; set; }
    public decimal Completion { get; set; }
    public int Priority { get; set; }
}

That's it for the core models! Lets add it to the project...

Coding it

In the OKR.Core project, create a folder called Models - you guessed it, for our domain models. Now add the two models from above in files: Objective.cs and KeyResult.cs

Repositories

Now we have the core models, we need to build an interface that abstracts data access. Lets build two repositories for the Objectives and Key Results.

Create another folder in OKR.Core called Repositories.

Data access code, especially in repositories can get pretty repetitive, so lets abstract it to a generic repository:

IGenericRepository.cs

using System.Collections.Generic;
using System.Threading.Tasks;

namespace OKR.Core.Repositories
{
    public interface IGenericRepository<T>
    {
        public Task AddAsync(T model);
        public Task UpdateAsync(T model);
        public Task DeleteAsync(T model);

        public Task<IReadOnlyList<T>> GetAllAsync();
        public Task<IReadOnlyList<T>> GetPagedAsync(int page = 0);
    }
}

This code provides the simple CRUD operations on any model T

Now lets build the specific repositories for OKRs:

IObjectiveRepository.cs

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using OKR.Core.Models;

namespace OKR.Core.Repositories
{
    public interface IObjectiveRepository : IGenericRepository<Objective>
    {
        Task<IReadOnlyList<Objective>> GetAllActiveAsync(bool active = true);
        Task<IReadOnlyList<Objective>> GetAllWithinDueDateAsync();
        Task<Objective> GetByIdAsync(Guid id);
    }
}

Note the added functions that are specific to Objective properties

IKeyResultRepository.cs

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using OKR.Core.Models;

namespace OKR.Core.Repositories
{
    public interface IKeyResultRepository : IGenericRepository<KeyResult>
    {
        Task<IReadOnlyList<KeyResult>> GetAllByObjectiveAsync(Guid objectiveId);
    }
}

Pretty simple here, I don't think we need to provide any filtering on the data access level here, since there won't be any ridiculous number of key results inside an objective

Mocking the Repositories

Before we get started with the frontend we have to mock the repositories to get some 'real' data.

Lets create a new class library project to hold the mock repositories called OKR.Core.Mock. Add a project reference to OKR.Core. Create a folder called Repositories and create the files: MockObjectiveRepository.cs and MockKeyResultRepository.cs - implementing the underlying interface. You should be able to autogenerate the functions like so:

public class MockObjectiveRepository : IObjectiveRepository
    {
        public async Task AddAsync(Objective model)
        {
            throw new NotImplementedException();
        }

        public async Task UpdateAsync(Objective model)
        {
            throw new NotImplementedException();
        }

        ...

At this point, lets just make a couple functions return mock data, the rest can throw exceptions:

MockKeyResultRepository.cs

public async Task<IReadOnlyList<KeyResult>> GetAllByObjectiveAsync(Guid objectiveId) => new[]
{
    new KeyResult
    {
        Id = Guid.NewGuid(),
        Active = true,
        Completion = 0,
        Description = "Do something...",
        Title = "Something",
        Priority = 1,
        ObjectiveId = objectiveId
    },
    new KeyResult
    {
        Id = Guid.NewGuid(),
        Active = true,
        Completion = (decimal) 0.35,
        Description = "Do this...",
        Title = "This",
        Priority = 4,
        ObjectiveId = objectiveId
    }
    ,
    new KeyResult
    {
        Id = Guid.NewGuid(),
        Active = true,
        Completion = (decimal) 0.80,
        Description = "Do that...",
        Title = "This",
        Priority = 10,
        ObjectiveId = objectiveId
    }
};

MockObjectiveRepository.cs

public async Task<IReadOnlyList<Objective>> GetAllAsync() => new[]
{
    new Objective
    {
        Active = true,
        Title = "Q1 Growth",
        Description = "Grow in Q1 by doing some productive things.",
        Id = Guid.NewGuid(),
        StartDate = DateTime.Now.Subtract(TimeSpan.FromDays(4)),
        DueDate = DateTime.Now.AddDays(5)
    },
    new Objective
    {
        Active = true,
        Title = "Lorem Ipsum",
        Description = "A sentence describing what this is",
        Id = Guid.NewGuid(),
        StartDate = DateTime.Now.Subtract(TimeSpan.FromDays(4)),
        DueDate = DateTime.Now.AddDays(5)
    },
    new Objective
    {
        Active = true,
        Title = "Q2 Growth",
        Description = "Grow in Q2 by doing some productive things.",
        Id = Guid.NewGuid(),
        StartDate = DateTime.Now.Subtract(TimeSpan.FromDays(20)),
        DueDate = DateTime.Now.AddDays(5)
    },
    new Objective
    {
        Active = true,
        Title = "Q3 Growth",
        Description = "Grow in Q3 by doing some productive things.",
        Id = Guid.NewGuid(),
        StartDate = DateTime.Now.Subtract(TimeSpan.FromDays(50)),
        DueDate = DateTime.Now.AddDays(100)
    },
    new Objective
    {
        Active = false,
        Title = "Q4 Growth",
        Description = "Grow in Q4 by doing some productive things.",
        Id = Guid.NewGuid(),
        StartDate = DateTime.Now.AddDays(100),
        DueDate = DateTime.Now.AddDays(200)
    },
};

Now we have some mock repositories return some data.

In the next post, I begin the UI with AntBlazor, using the mock data.

← Part 1 | Part 3 →

GitHub

1. Create a repository called OKR, and initialize it with only a README.md file
2. Open GitHub Desktop, and clone the repository to your machine

Folder Structure

The physical folder structure will be:

OKR
│   README.md
│   Docker Related files
|   .sln    
│   ...
|
└───src
    │   
    └─── ... (Projects e.g. 'OKR.Web')
        │   .csproj
        │   Dockerfile
        │   ...

Setup Solution + Projects

1. Open the folder in the file explorer, and Shift + Right Click -> Open PowerShell window here. Type dotnet new gitignore to generate a .gitignore file. Feel free to make this file the first git commit
2. Create a new empty solution (Blank Solution in VS, Empty Solution in Rider) and call it OKR
3. Create a solution folder src/ - this is not a physical folder, its part of the solution
4. Create a solution folder Solution Items, and add the existing items, README.md and .gitignore. In the future the docker files will be added here too
5. Add 4 projects to the src/ solution folder, and the src/ physical folder path - these are following the DDD principals
   • OKR.Web Blazor Server - here is where the Blazor frontend code will be, separate from business logic + data access layers
   • OKR.Application Class Library - here is the business logic layer with references to repository interfaces from the OKR.Core layer to abstract data access away from business logic
   • OKR.Core Class Library - here is the core domain models, and repository interfaces
   • OKR.Infrastructure Class Library - here are the implementations of repository interfaces using Marten

DevOps

Its always nice to have DevOps from day 0 of your project, so lets add it!

GitHub CI

To setup the dotnet build + test action, go to the GitHub Repository -> Actions -> .NET -> Set up this workflow. The template file works without any changes, because our .sln is in the root directory - so click Start commit -> Commit directly to the main branch, add a commit message like Add dotnet CI, and finally Commit new file

Docker

First we need a Dockerfile to create an image for the Blazor site. Visual Studio automatically generates Dockerfiles - right click the OKR.Web project, Add -> Docker Support -> Linux -> Ok. That's all it takes! When projects get dependencies make sure to run this again (like when you reference projects)

Docker Compose

Now we need to orchestrate the config for the Blazor site, and include the postgres database all in one.

Create a blank file called docker-compose.yml and add it to the Solution Items/ folder in the .sln.

Fill it out with the following:

version: "3.8"
services:
  frontend:
    build:
      dockerfile: src/OKR.Web/Dockerfile
      context: .
    image: okr-frontend
    container_name: OkrFrontend
    restart: unless-stopped
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_ConnectionStrings__Marten=User ID = okr;Password=o32342134k4r%Y#%Y345yRasdf;Server=postgres;Port=5432;Database=okr_db;Integrated Security=true;Pooling=true
    volumes:
      - ./config/appsettings.json:/app/appsettings.json
    ports:
    - "9595:80"
  postgres:
    image: postgres
    container_name: OkrPostgres
    environment:
      - POSTGRES_USER=okr
      - POSTGRES_PASSWORD=o32342134k4r%Y#%Y345yRasdf
      - POSTGRES_DB=okr_db
    volumes:
      - ./data:/var/lib/postgresql/data

Note the two services, the frontend and database. The secrets for the database are hardcoded - this is fine since the database is not exposed to the internet, but for added security feel free to make this in a config file.

The frontend is exposed to the VPS's port 9595, proxying the request to the containers port 80.

To start the whole system you can run docker-compose up -d --build (-d detached mode, --build builds the Dockerfile)

Ensure on your VPS you have installed Git, Docker and Docker Compose.

Domain + Reverse Proxy

Cloudflare

This site will run on a subdomain okr.lukeparker.dev, so I will walk through that. (If you want to point it to a root domain, like lukeparker.dev use an A record pointing to your VPS IP address instead)

Since I have a record for lukeparker.dev to point to my VPS, I just need to add a CNAME record to proxy okr.lukeparker.dev to the same IP as lukeparker.dev.

Open up the Cloudflare dashboard and goto the site (in my case lukeparker.dev), the click the DNS page. Click Add record:

• Change Type to: CNAME
• Change Name to: okr
• Change Content to: @ (@ will resolve to the base domain - lukeparker.dev)

Then click save.

This may take a minute or two to update in Cloudflare's network, but it is pretty fast.

NGINX on VPS

Ok so now we have requests incoming, we need to proxy okr.lukeparker.dev -> localhost:9595

I have a global NGINX docker-compose repository you can reference that I use for my VPS and sites: azetio-nginx

Before we begin you need to install the Cloudflare Origin Certificate on your server, so follow this guide - make sure to note where and what the certificates are called. If you are running your global NGINX server in Docker, make sure to mount the certificate files. Read more here

If you used my azetio-nginx, then add a new file in nginx/sites-enabled/ called lukeparker.dev.okr.conf and fill it out with the following (renamed to match your domain):

server {
    listen 80;
    server_name okr.lukeparker.dev www.okr.lukeparker.dev;

    return 301 https://okr.lukeparker.dev$request_uri;
}

server {
    listen 443 ssl;
    server_name okr.lukeparker.dev www.okr.lukeparker.dev;

    ssl_certificate /etc/ssl/certs/lukeparker.pem;
    ssl_certificate_key /etc/ssl/private/lukeparker.pem;
    ssl_client_certificate /etc/ssl/certs/origin-pull-ca.pem;
    ssl_verify_client on;

    ssl_session_cache builtin:1000 shared:SSL:10m;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://localhost:9595;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600;
    }
}

This configuration will automatically redirect http -> https, and proxy requests to the 9595 port, passing forwarded headers.

Note that if you aren't using my nginx config: add this to the http { ... } clause:

map $http_upgrade $connection_upgrade {
        default Upgrade;
        '' close;
    }

Make sure to read Host ASP.NET Core on Linux with Nginx to understand the config.

With all this setup, make sure to restart the azetio-nginx config with docker-compose up -d --force-recreate

On the VPS, we need to first clone the git repository, so run git clone git@github.com:Hona/OKR (Replace with your username + repository)

Navigate to the repo: cd OKR

Make sure to create the config directory and an empty appsettings.json file:

mkdir config
echo "{ }" > "config/appsettings.json"

Then start the OKR project with docker-compose up -d --build

If all goes well, navigate to the domain you setup, and you should see the default Blazor page, if you do, everything is setup perfectly!

In the next post, I will plan and setup the core models, repository interfaces and mock repositories.

← Part 0 | Part 2 →

Why?

There are many boilerplate Blazor examples everywhere online, showing the basics, and some more intricate parts. However, I am yet to find a full blog series showing end-to-end, how to make a beautiful UI and clean coded backend 'real world' website with Blazor

The Idea

For this series I decided that a reasonably simple but more complex than the typical TODO app, is an OKR website. If you aren't familiar with what an OKR tracker is, it stands for objectives and key results. What this means is there are larger objectives, that can be tracked by specific key results.

An example might be:

O: Become the top retailer in your state

KR:

• Increase sales by 45%
• Decrease monthly costs by $2000

From a developer perspective this is a simple enough app, you have one objective to many key results. This means the focus of this series will be to dive into UI and hooking it up with Blazor.

Series Roadmap

1. Scaffold the project boilerplate using DDD (domain driven design), and full DevOps (GitHub CI, Docker + docker-compose, NGINX domain->docker setup)
2. Plan the backend, and setup the core models and repository interfaces
3. Build mock repositories with test data, to be able to build the UI properly, once. Build the main UI sections
4. Build the backend repositories and database setup using Marten DB as a document store
5. Build an analytics dashboard using data from all OKRs

Potential Extensions

• Add authentication, authorization, users/groups
• Add an API to expose data for 3rd party use

The Tech Stack

Domain Registrar: Cloudflare

DDoS Protection, Nameservers, DNS: Cloudflare

Server Hosting: Vultr VPS

Reverse Proxy (differentiate between domains): NGINX

Containers: Docker and docker-compose

Website: ASP.NET Core Blazor + C#

Database: Postgres

UI

There are many UI frameworks for Blazor, but many are hard to use, require knowledge from React and more. The only UI framework I've found for Blazor that makes sense, and is easy to use - is AntBlazor. AntBlazor is a Blazor component library for Ant Design.

This library supports many components, and its component overview can be found on the linked site. I've personally used AntBlazor for many of my personal projects, and for paid projects - in production. It is still a somewhat young library compared to React or Angular UI libraries, but Blazor is the new tech on the block.

In this blog series I am going to show you how easy it is to build a beautiful frontend; this is especially useful if you are primarily a backend developer and don't have/want to put in the time for the frontend.

In the next post, I will setup the project boilerplate and full DevOps.

Part 1 →

I have personally been using Visual Studio since I started learning to code, all the way back in 2010 using VB.NET. Over that time I have grown more comfortable with using the IDE. Made by Microsoft, and considered the flagship way to develop for C#, why would I want to switch away from it?

Visual Studio's Shortcomings

• Very laggy - Visual Studio as a piece of software is an age-old behemoth, an unavoidable recipe for lag, and severe slow downs. This becomes evident once you start loading projects larger than a simple proof of concept. More recently, I've noticed these issues becoming more extreme.
• Many, many slight issues and bugs. Little annoying issues that aren't code destroying, but enough to slow down your productivity, or break you out of your flow state. An example of one of the bugs is an unlimited loading time when adding a reference to another project through a 'quick' action.
• The almost necessity for ReSharper, and other VS Extensions.

Although my list isn't that large, they all contribute to being less productive, and in ReSharper's case, already reliant on JetBrain's products.

Making the Switch

It should be mentioned that Rider is a paid product, however you can get a free for personal use license as a student, or even as an open source maintainer.

Downloading Rider was a simple process through their website, and the install process was seamless.

A nice feature that comes with Rider (and ReSharper for VS), was the keymap options, which allows you to instantly get a familiar experience, no matter what IDE you come from.

Initial Impressions

I immediately loaded up a reasonably large sized project (10+ projects), to see how Rider holds up. Wow! I was blown away... I've never seen such a smooth experience; loading a solution, indexing files/symbols, code inspection + analysis were all amazingly smooth! The background tasks that usually run in the 'background' of Visual Studio - often causing the syntax highlighting to break, IntelliSense to freeze, and sometimes the window itself to stop responding - went by unnoticed in Rider. You can start coding right away as these tasks fire off in the background, so if you boot up Rider with that bug fix that suddenly came to you in the shower, no need to wait upwards of several minutes to open the IDE.

Rider's Downfalls

Even though Rider is a great product, and I will not be going back to Visual Studio anytime soon, it still comes with its downsides.

• No way to auto-generate a Dockerfile - in VS you can Right Click -> Add -> Docker Support to instantly dockerize your project, however this option does not exist in Rider. This is the only reason that I open Visual Studio anymore, to simply generate Dockerfiles.
• Some code formatting issues, upon saving rider keeps pointless whitespace, so if you have accidental spaces after a ; or }, it will be there, luckily git diffs show this so I can manually delete them before commiting, but this is a missed feature from VS. Autoformatting does fix this, but really, it should be done on save.
• You cannot edit a .csproj file without unloading the project first, making the change, and reloading it. Coming from VS, you know that you can simply click the project and edit the file without issue.

Final Thoughts

Rider is a great product, and the simple fact that it is significantly more performant, and less bug-filled than Visual Studio is enough for me to make the permanent switch. As I mentioned above, some small issues and missing features annoy me from time to time, but is nothing compared to freezes, lag and bugs from Visual Studio.

I'd recommend that everyone gives Rider a go for at least a week (there's a 30 day free trial), because trust me, once you switch, you cannot go back!