Architecture Update! (Vertical Slices Experiment)

[jonhilt]

Here's a walkthrough of some of the changes I'm testing out in the refit-spike branch.

Here's a video showing one way to implement a new feature with this approach.

There are a few considerations when building a Blazor project, and targeting Blazor WASM brings its own nuances which I thought it might be useful to discuss.

It's useful to start with some guiding principles for what I think we're aiming for.

• Help developers fall into the pit of success
• Make it quick and easy to add new features
• Reduce the amount of boilerplate code needed

Think about what we ship to the client

The first thing that struck me when looking at the initial code for this was that we always have to be careful what we deploy to the client with Blazor.

The first version of the project had a reference to ComponentLibrary which in turn had a reference to the Domain and Services projects.

In practice this means we'd be deploying the following dlls to the client.

• ComponentLibary
• Domain
• Services

This means some server only considerations (like the EF Core Context) are going to end up being shipped to the client. Also, if we push more business logic, rules into the domain, all of this would be shipped to the client too.

However, in practice the client(s) can then only interact with this domain via the web API, so we'd want to try to avoid shipping all of that to the client.

Avoid directly referencing the domain in the client

Moreover, I've learned (the hard way) that using Domain objects directly in the UI for an application can be problematic. Take the TimeEntry entity for example.

We could use that in our Blazor components like so:

protected TimeEntry TimeEntry { get; set; }   

protected async Task SaveAsync()
{
    await TimeEntryService.CreateAsync(TimeEntry);
}

But if we do that we have a couple of potential issues:

1. We have to ship that entity to the client (as discussed)
2. Changes to the entity ripple through to the client

Point 2. makes it much harder to iterate the design for how we interact with and store time. Any changes to the domain, or shape of the entities will ripple all the way through to the client. Effectively, what could be an internal refactoring ends up always changing the shape of the API, requiring both the API and the client(s) to be updated and redeployed.

The easiest way around this is is to use different objects (classes) for interacting with the API, effectively creating a public interface which we try to keep fairly consistent, even when refactoring how the API and data persistence is implemented.

In the refit-spike branch I've therefore renamed ComponentLibrary to Shared. Take a look in there at the Api/Features/TimeEntry folder and you'll find a couple of files which represent this public API.

• CreateTimeEntry.cs
• GetForSelectedDate.cs

If you then take a look at CreateTimeEntry.cs you'll see a class which includes this Command.

  public class CreateTimeEntry
  {
      // validator could also go here (and could be used in both clients + the API
      // for fast feedback on client + reliable validation on the server)
  
      public record Command : IRequest<int>
      {
          public int Category { get; set; }
          public int Client { get; set; }
          public decimal Hours { get; set; }
          public string Notes { get; set; }
          public int UserId { get; set; }
      }
  }

When thinking about what we need to accept in order to create a time entry, we can be very careful to only add properties to this command which are strictly necessary.

For example, note how it defines a UserId but not a CreatedBy property. We may well want to set the CreatedBy field to the id of the User who's logged in, but that feels like an implementation detail which should be handled in the business 'logic' for this feature (behind the API), rather than requiring any consumers of our API to pass the User Id in twice, once for UserId and once for CreatedBy.

If we directly interact with TimeEntry in the client we have little flexibility to intentionally design our API, whereas this way we can be much more specific about the 'shape' of the API.

Commands and Queries

I've found it very useful in recent times to think about these API calls as either Commands (which change data) or Queries (which read data).

In this example:

API/Features/TimeEntry

• CreateTimeEntry.cs
• GetForSelectedDate.cs

We have the CreateTimeEntry command and then a GetForSelectedDate query:

  public class GetForSelectedDate
  {
      public record Query : IRequest<IEnumerable<Model>>
      {
          public int UserId { get; set; }
          public DateTime SelectedDate { get; set; }
      }

      public record Model
      {
          public int Category { get; set; }
          public int Client { get; set; }
          public decimal Hours { get; set; }
          public string Notes { get; set; }
      }
  }

Note how we define both the query (which accepts UserId and SelectedDate) and then the shape of the date to be returned (the model).

Again this is very useful as we build out our API. We can easily add fields to the Model in isolation from changes to our Doman.

Shared Models

Because these models (commands and queries) live in the Shared project we can happily reference them from the Blazor WASM and Server clients.

This could also be a good place to define FluentValidation rules. That's one thing I'd like to explore next!

Refit to reduce boilerplate

Just before we move on from the Shared project there's one more thing I stumbled upon which could be really useful.

In the first version we had a TimeEntryService which acted as an HTTP Client for our API.

public async Task<IEnumerable<TimeEntry>> GetForSelectedDateAsync(int userId, DateTime selectedDate)
{
    string url = $"api/timeentry/GetForSelectedDate?userId={userId}" +
        $"&selectedDate={selectedDate.ToString("s", System.Globalization.CultureInfo.InvariantCulture)}";

    return await JsonSerializer.DeserializeAsync<IEnumerable<TimeEntry>>
        (await _httpClient.GetStreamAsync(url), new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
}

These clients are a pain to create because they're pretty much all boilerplate (with just the URIs and Types changing between methods).

That's where Refit comes in, and it looks pretty nice.

Instead of writing all that code manually, you can just define an interface to match the API.

For example, knowing that our API has two methods, one for creating a TimeEntry and one for getting all entries for a selected user/date, we can define that in the Shared project like so:

ITimeEntryApi.cs

public interface ITimeEntryApi
{
    [Get("/api/TimeEntry/GetForSelectedDate")]
    Task<IEnumerable<GetForSelectedDate.Model>> GetForSelectedDate(GetForSelectedDate.Query query);

    [Post("/api/TimeEntry")]
    Task<int> Create(CreateTimeEntry.Command command);
}

Note how we define the URL (to the API) plus re-use the shared types we defined (for our command and query).

Now we can use this in our components (in place of the TimeEntryService) like so:

  public partial class AddTimeEntry
  {
      [Inject] protected ITimeEntryApi TimeEntryApi { get; set; }

      protected CreateTimeEntry.Command Command { get; set; }

      protected override void OnParametersSet()
      {
          Command = new CreateTimeEntry.Command
          {
              UserId = 1
          };
      }

      protected async Task SaveAsync()
      {
          await TimeEntryApi.Create(Command);
      }
  }

Refit is configured simply enough Program.cs or Startup.cs in the client projects.

  public class Program
  {
      public static async Task Main(string[] args)
      {
         // other code omitted
     
          builder.Services.AddRefitClient<ITimeEntryApi>()
              .ConfigureHttpClient(c => { c.BaseAddress = new Uri("https://localhost:5001/"); });
      }
  }

API Implementation

For the actual API implementation itself, I've collapsed some of the layers and used MediatR to create handlers for our command and query.

In the TimeKeeper/Api/Features folder you'll see a TimeEntry folder.

In there you'll see these two files:

• CreateTimeEntry.cs
• GetForSelectedDate.cs

CreateTimeEntry

 public class CreateTimeEntryHandler : IRequestHandler<CreateTimeEntry.Command, int>
  {
      private readonly TimeKeeperContext _context;

      public CreateTimeEntryHandler(TimeKeeperContext context)
      {
          _context = context;
      }

      public async Task<int> Handle(CreateTimeEntry.Command command, CancellationToken cancellationToken)
      {
          var timeEntry = new Domain.TimeEntry
          {
              Hours = command.Hours,
              Category = command.Category,
              Client = command.Client,
              Notes = command.Notes,
              DateCreated = DateTime.Now,
              IsSubmitted = false,
              IsAuthorised = false,
              CreatedBy = command.UserId,
              User = command.UserId
          };

          _context.TimeEntries.Add(timeEntry);

          await _context.SaveChangesAsync(cancellationToken);

          return timeEntry.Id;
      }
  }

If you're not familiar with MedaitR this may look a bit strange at first.

Effectively we create a class and implement IRequestHandler<> for our command (or query).

In this case the handler is for our CreateTimeEntry.Command.

The Handle method then contains the logic for this feature.

In a case like this, that's likely to be fairly simple, spinning up a new TimeEntry object and setting its properties from the incoming command.

Note how we set CreatedBy to command.UserId. This is an easy way to ensure the correct user is recorded against the record in the DB, but (as discussed earlier) without having to expose that property via the API.

You might have heard people talk about vertical slices. These handlers are one way to implement those slices.

Jimmy Bogard has a couple of very useful primers about vertical slices (and how they compare to other approaches:

Why Vertical Slice Architecture is better
How Vertical Slice architecture fulfils clean architecture's broken promises

From my own experience I can only report that this has been the single biggest mindset shift which has positively impacted the projects I've worked on in the last 5-6 years. In every case where we switched to this approach we saw a massive increase in how quickly we could add features, but also a massive reduction in bugs and the ability to make changes without those changes rippling out to other parts of the application.

Summary

Reading this back I realise there's a lot of detail in here which might be hard to decipher/take in!

Although there's quite a few changes, we can break them down as follows (and for thinking about what to adopt going forward).

• Refit to auto-generate the API client
• API-specific models to represent API operations (rather than using the Domain directly in the Blazor clients)
• Adoption of Commands, and Query separation
• Using MediatR to implement the commands/queries as vertical slices

In terms of moving forwards, I'm thinking I might just knock up a quick screencast showing how I'd add a simple feature with this architecture. Sometimes it's just easier to see it in action than try to understand it from a description 😃

[DotNetDublin]

Great stuff @jonhilt!

Will review in detail this evening and come back with some thoughts.

[harperjohn]

WOW @jonhilt ! My head is spinning! Spinning in a good way!!!

Yes - a screen cast of your changes and how you would add a simple feature sounds like great thing...

wow...

Thanks so much to @DotNetDublin and @jonhilt for all this!!!

[adamfoneil]

A screencast would be good, @jonhilt
I know you've written about vertical slices before, and I'm interested in the possibilities this brings.
I too have run into trouble with server-side concerns leaking into the client when referencing domain/entity models directly. But I'm not super enthused about maintaining two different domain "views" -- one for the client and one for the server. You will need some kind of middle man to mediate them. In my mind that middle layer is the dreaded Another Mouth to Feed.

One crazy solution I've had is to implement domain models as partial classes. For each domain class, one partial is shipped to the client, and the other is kept server-private -- biz logic things that have a direct database connection, etc. This gives you dependency-free domain classes in the client, and heavy domain models on the server -- with seamless compatibility between them. The downside is that on the client side, you must link every domain class individually to the project rather than use a project reference. This is a little clumsy from a solution management perspective, and is a bit tough to conceptualize what's happening if you're new to it. (Frankly true of many things.)

I'm still interested to see your suggestion in action via screencast or PowerPoint

[adamfoneil]

btw @jonhilt I'm a big fan of Refit -- glad to see that in play here

[jonhilt]

Thanks @adamfoneil.

I think the distinction is I don't tend to see the command/query classes as separate to the domain, but rather the public face of the domain.

Saying that, there are always trade-offs for sure, and I guess it varies a lot depending on the scope/complexity of the application.

Blazor is also fairly unique (compared to other web frameworks) in sharing those types between the backend API and frontend code. I think this sharing is a net benefit but it can also muddy the waters somewhat given the API is ultimately accepting and returning JSON, not objects!

[jonhilt]

btw @jonhilt I'm a big fan of Refit -- glad to see that in play here

Yeah I only just found it this week but it looks like a huge timesaver!

[jonhilt]

OK here's the promised video showing one way to implement a new feature with this approach.

It's a little rough and ready but hopefully helps show the key moving parts :-)

https://practicaldotnet.vids.io/videos/709ddbb01f1ee7c2f9/architecture-mp4

[adamfoneil]

wow! this is a great walkthrough.

I'm sort of struggling to see merits of the command abstraction (IRequest, ICommandHandler). I think it's because it lets you implement a "handler" anywhere in your application -- to decouple controller logic from controllers. But I confess I don't know why such logic needs to be "anywhere." (Why not just in the controller?) I think the whole MediatR discussion is a bigger one, and there are reasons for it, but they aren't on the tip of my tongue.

I also feel like the Id property mapping needing a special LINQ statement was a little boilerplate-ish. (around 7:30) This is the whole discussion about domain models being available in the client or not, I think.

Seeing your debug process, testing in the browser, using F12 along with the IDE, is all really great to see. I also wasn't aware how good the app looks already with the MudBlazor stuff also.

[jonhilt]

Hey @adamfoneil

Appreciate the feedback and questions.

I wonder if the continued discussion (see replies below) has helped clarify the role/purpose of using MediatR to facilitate vertical slices?

I've also been thinking about it some more (that's one of the great things about being able to discuss these ideas here, it makes you think!).

Ultimately I see MVC controllers as a bit of a relic (for spinning up an API).

Steve Smith makes this point in the Readme for his Api Endpoints project...

MVC Controllers are essentially an antipattern. They're dinosaurs. They are collections of methods that never call one another and rarely operate on the same state. They're not cohesive. They tend to become bloated and to grow out of control. Their private methods, if any, are usually only called by a single public method. Most developers recognize that controllers should be as small as possible (unscientific poll), but they're the only solution offered out of the box, so that's the tool 99% of ASP.NET Core developers use.

Now his Api Endpoints library is actually another way to address this problem, but I find the MediatR abstraction useful because it decouples the application commands/queries from ASP.NET Core completely.

This makes a few things possible/easier:

• You can invoke MediatR directly from tests (without having to go via MVC/API to get there)
• You can invoke MediatR directly if you want to execute the logic in your app but avoid HTTP (I'm thinking this might be useful for the Blazor Server implementation)

On a kind of semi-related note, I don't know if you remember (or have ever used) NancyFX?

It was a bit ahead of its time but it let you ditch controllers and handle routing this way:

public class SampleModule : Nancy.NancyModule
{
    public SampleModule()
    {
        Get["/"] = _ => "Hello World!";
    }
}

Now I'd imagine people's reactions to that syntax may vary! But it proved pretty popular and showed that there was a way, without controllers, to handle things like routing and HTTP request/responses in your .NET applications.

It also did some funky stuff like making it easy to define pipelines, so you could handle cross-cutting concerns like error handling:

pipelines.OnError += (ctx, ex) => {
    return null;
};

Interestingly, most 'modern' web frameworks have something vaguely similar to this approach. Here, for example, is Express (node).

app.get('/', (req, res) => {
  res.send('Hello World!')
})

Fast forward a decade and there are signs that MS are poised to offer a non-controller alternative (for building APIs) in .NET 6.

dotnet/aspnetcore#27724

So with all that background/context, I like that little bit of separation between the web layer and the application, whether it's MediatR or any other approach. Then I find MediatR puts just enough guardrails up to prevent accidental re-use (which often couples unrelated features together) by giving you a handler to work with which isn't even in the same place as some other random features (which may or may not be related).

I then find the handlers provide a handy place to start 'thinking' about and iterating on a feature by fleshing out its inputs, outputs and business logic.

[adamfoneil]

Thank you @jonhilt . I totally agree that "fat" controllers are problematic -- for testing reasons if nothing else, but also for coupling concerns more generally. So when I said above why can't logic be "in the controller?", I should've added "injected via some service." I had not heard of Nancy. I kind of like the look of it or at least the intent. I see a bit better now how MediatR fits in. You've expanded my mind a bit!

[DotNetDublin]

Just finished watching the video which was really informative.

Prior to that I had started watching Tim Corey's video Intro to MediatR - Implementing CQRS and Mediator Patterns so I'll need to finish that over the coming days as well as taking a look at Refit which I hadn't come across before.

I can appreciate how the structure shown in the refit-spike branch addresses some of the issues I had thought of while putting the initial code together such as the amount of repeated code in the controllers and services and not exposing the entire TimeEntry model for create requests etc.

One question to begin with is that I see that the API project now contains Data and Domain folders which removes the need for the Domain and Repository projects and then in the Shared project there is the Api directory which removes the need for the Services project. I'm wondering if someone could argue that the Api project is doing too much if it is handling database access and controlling the domain? Does that come down to project size or is having that within the Api not an issue?

In relation to the Services project in my mind there would be service class such as EmailService.cs as well as a service per object such as TimeEntryService,cs. In the new architecture would the email sending functionality be contained within the Api project and would this be called from within Features/Email or similar within the Api directory of the Shared project?

One advantage I thought the Services project held was that it added a layer of abstraction between the ComponentLibrary project (now Shared) and the API in that the component library wouldn't need to be updated if in future you pivoted and had everything server side with direct data access etc. As I type that I realise that's probably similar to when I hear that the repository pattern is great as it covers you when you might switch from SQL Server to CoolKidsDB and I think "well that's never going to happen".

There will be more questions but I'm thinking that it will take two to three dog walks before they have formed coherently in my mind.

Overall I'm happy to continue going down the road of vertical slices unless anyone else has other thoughts so thanks for taking the time to put this together.

[DotNetDublin]

Thanks @jonhilt

I think for now we should adopt whatever approach is the most accessible for developers that are new to mediator (looking in the mirror) and would match what they might commonly find in real world applications.

In the real world applications need to be adapted as they grow and it's not always possible to foresee the pain points ahead of time so it would probably be good experience to see how we need to adapt TimeKeeper as it organically grows rather than holding things up by aiming for the perfect architecture which some might find hard to get their head around.

That said and being totally selfish I would be interested to get your thoughts on the below.

One question to begin with is that I see that the API project now contains Data and Domain folders which removes the need for the Domain and Repository projects and then in the Shared project there is the Api directory which removes the need for the Services project. I'm wondering if someone could argue that the Api project is doing too much if it is handling database access and controlling the domain? Does that come down to project size or is having that within the Api not an issue?

In relation to the Services project in my mind there would be service class such as EmailService.cs as well as a service per object such as TimeEntryService,cs. In the new architecture would the email sending functionality be contained within the Api project and would this be called from within Features/Email or similar within the Api directory of the Shared project?

One advantage I thought the Services project held was that it added a layer of abstraction between the ComponentLibrary project (now Shared) and the API in that the component library wouldn't need to be updated if in future you pivoted and had everything server side with direct data access etc. As I type that I realise that's probably similar to when I hear that the repository pattern is great as it covers you when you might switch from SQL Server to CoolKidsDB and I think "well that's never going to happen".

[jonhilt]

In the real world applications need to be adapted as they grow and it's not always possible to foresee the pain points ahead of time so it would probably be good experience to see how we need to adapt TimeKeeper as it organically grows rather than holding things up by aiming for the perfect architecture which some might find hard to get their head around.

This ^ of course, is wisdom!

There's a considerable difference between solving an interesting technical problem because it's fun vs holding up an entire project to try and solve an interesting technical problem (before it's really a problem!)

That said and being totally selfish I would be interested to get your thoughts on the below.

One question to begin with is that I see that the API project now contains Data and Domain folders which removes the need for the Domain and Repository projects and then in the Shared project there is the Api directory which removes the need for the Services project. I'm wondering if someone could argue that the Api project is doing too much if it is handling database access and controlling the domain? Does that come down to project size or is having that within the Api not an issue?

It's interesting to turn this question around and challenge what separate projects actually gives us, and is it worth the trade-offs that come along for the ride (references between projects, figuring out which code goes where, breaking a feature up into lots of tiny pieces and scattering them around the project so it's harder to find them again later).

One really important test. If you want to work on a feature, how many different places do you have to visit in the code. This comes down to cohesion, things that change together really ought to live together.

Lots of separation along technical grounds can severely hinder refactoring too. It's hard, once a feature is split up into multiple pieces and separated into separate projects, to really pull the code around and refactor a feature on its own merits.

I found this article and I think James does a much better job of explaining this approach than I can probably manage here just now, so let me know if this helps :-)

https://www.jamesmichaelhickey.com/clean-architecture/

In relation to the Services project in my mind there would be service class such as EmailService.cs as well as a service per object such as TimeEntryService,cs. In the new architecture would the email sending functionality be contained within the Api project and would this be called from within Features/Email or similar within the Api directory of the Shared project?

It depends whether sending email is a feature, or a side effect. If we created a view in the frontend which was explicitly to send an email, with fields for subject, message etc. then we'd want to build an Email feature.

On the other hand, if we had a scenario such as emailing a report when someone requests it, then the feature is probably to request the report (with specific parameters etc) and the emailing of it would be part of that feature (I'd probably start by writing the code in the MediatR handler, then refactor it out of there as needed).

This leads into a whole new conversation about whether you want the user hanging around waiting for an email to be sent, but that's fine, we could always move the email sending part out of the command handler and put it behind a queue, or use Hangfire to handle it or whatever. The important thing is we'd focus on making the feature work first!

One advantage I thought the Services project held was that it added a layer of abstraction between the ComponentLibrary project (now Shared) and the API in that the component library wouldn't need to be updated if in future you pivoted and had everything server side with direct data access etc. As I type that I realise that's probably similar to when I hear that the repository pattern is great as it covers you when you might switch from SQL Server to CoolKidsDB and I think "well that's never going to happen".

For me (and James Hickey mentions this in his article) I see the MediatR commands/queries as our application layer. If we forget frontend UIs for a moment, those handlers are our application (in terms of behaviour).

They are responsible for interacting with the DB (to hydrate and persist domain objects) and orchestrating other parts of the system, before returning a response.

There are arguments for keeping the Shared project detached from this part of the application. In fact, because everything's done over HTTP there's no need for the Shared/ComponentLibrary project to reference any of the 'backend' projects.

The trade-off is we'd have to create duplicate types in the Shared project to represent the API (if you've ever built a Typescript front end you might have effectively done the same, building TS types to represent an API).

So my hunch is, from a pragmatic perspective, the shared library referencing the application layer so it can share types is convenient and probably provides enough benefits that we can live with the slightly increased coupling.

Incidentally, on the repository point, I've actually found the Repository pattern makes it much, much harder to switch DB. This is because, to perform the switch, you have to do a big-bang switch of the entire repository, and these repositories often grow very big over time,

I've found it's actually easier to take one or two feature which exist as vertical slices, and which rely on the same part of the database and migrate them, leaving the rest of the features unaffected. You can gradually migrate the data (and features) across this way.

The repository works against this philosophy because you have to write an entirely new repository, pointing to the new database, before you can migrate anything at all.

[DotNetDublin]

Thanks for taking the time to respond @jonhilt.

I'll read over https://www.jamesmichaelhickey.com/clean-architecture/ later this evening.

I now think with my lack of MediatR experience I'm asking questions from a place of ignorance and it's akin to being told that we now have a 4K Blu-ray player and I'm saying that's great but where do I put in my VHS tapes? Younger readers click here

Furthermore and again I'm being selfish I know how to build a Blazor application with multiple projects including service and repository layers however I don't know how to build a Blazor application using vertical slices and MediatR so if we go down this road it presents an exciting learning opportunity.

Once we are further down the road I can hopefully ask more informed questions but in legal terms the state drops all charges against vertical slices.

I'm sure the other contributors will still have questions however I'm wondering whether there is any further changes you would like to make to the refit-spike branch before we merge it into the main branch and start building on it?

I know you are busy so it's fine if you want to say yes but give me a week etc.

[harperjohn]

2. Carl Franklin has two videos on gRPC as part of his Blazor Train series which I've watched and one in particular compares performance against a standard API. Spoiler alert it's faster. See https://youtu.be/0fAjA6BVVFI and https://youtu.be/djsYXiun1vE

@DotNetDublin gotta love Carl Franlin!

Both videos were great, and I especially liked his second approach in the second video. I liked he started with (and kept) the "traditional" API, and then easily (with very little code or effort) added the gRPC layer/capability. And I noticed (and I liked) that he created his own (open source) code generation tool. This seems to show some additional interest/endorsement for this technology/path. 7x speed gain is significant!

I have used google protocol buffers in the past... not strictly a "web app", but it was a network app. There were three components, Java, C/C+ (desktop) and C (embedded IOT device) It was so nice to have a clear way to represent the data structures between the systems, and to not have to write "parsers"/"translators"/"serializers"/etc.

[jonhilt]

I'm sure the other contributors will still have questions however I'm wondering whether there is any further changes you would like to make to the refit-spike branch before we merge it into the main branch and start building on it?

I've merged that into main now (hoping that's OK with everyone).

Worth saying I'm very happy to see this evolve over time, and am not at all precious about this architecture! Hopefully (and I believe this to be the case) it doesn't box us in too much, nor stop us experimenting with some/all of the great ideas that are being thrown around here.

The acid test is how it evolves as we add features, so I guess that's the next experiment :-)