In this post I show how you can replace the Razor views for the default UI, without taking ownership of the business logic stored in the Razor Page PageModel code-behind files. I show how you can use the ASP.NET Core Identity scaffolder to generate the replacement Razor Pages initially, but customise these to use the existing, default, PageModels.

ASP.NET Core Identity

ASP.NET Core Identity is a series of services that provide functionality for managing and signing in users. You can use the Identity services to (among other things):

ASP.NET Core Identity is a series of services that provide functionality for managing and signing in users. You can use the Identity services to (among other things):

• Create users, and provide sign-in functionality
• Secure passwords using best practice, strong, hashing algorithms
• Generate short-lived tokens for email confirmation or multi-factor authentication,
• Enable auto-lockout of users to prevent brute-force attacks.
• Allow logging in with third-party providers like Google and Facebook.

The Identity services provide APIs for achieving all these things, but you still have to arrange them all in the right order. You also have to write the UI that users use to interact with the services. Obviously, that’s a huge investment, and is working with sensitive data, so you have to be very careful not to introduce any security holes.

Prior to ASP.NET Core 2.1, your best bet for implementing this was to use the UI generated from the Visual Studio templates. Unfortunately, using templates means that your UI is fine initially, but you then have a lot of code to maintain. If a bug is found in the templates, you have to go and update it yourself.

Luckily, ASP.NET Core 2.1 introduced a default UI Razor Class Library that meant you could benefit from the same UI, without having dozens of Razor Pages in your application to maintain. If a bug is found in the UI, the NuGet package can be updated, and you seamlessly get the bug fix, and all is great.

Customising the default UI

Of course, using the default UI means: you have to use the default UI. I think it’s generally unlikely that users will want to use the default UI in its entirety, unless you’re building internal apps only, or creating a “throwaway” app. For a start, the login and register pages include references to developer documentation that most people will want to remove:

Even though the UI is contained in a Razor Class Library, you can “overwrite” individual pages, by placing your own Razor Pages in a “magic” location in your project. For example, to override the register page, you can create a Razor Page at Areas/Identity/Pages/Register.cshtml:

A valid concern would be “how do I know which pages I can override?”. Luckily there’s a .NET Core tool you can use to scaffold pages from Identity in the correct locations, along with supporting files.

Scaffolding Identity files with the .NET CLI

The documentation for scaffolding Identity pages is excellent, so I’ll just run through the basics with the .NET CLI here. You can also use Visual Studio, but be sure to follow steps 1-3 below, otherwise you get weird random errors when running the scaffolder.

1. Add all the required packages to your application. If you’re already using EF Core in your app, then you may already have some of these, but make sure they’re all there, as missing packages can cause frustrating errors locally

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore
dotnet add package Microsoft.AspNetCore.Identity.UI
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools

Also make sure that the installed package versions match your project version, for example .NET Core 3.1 projects should use packages starting 3.1.x.

2. Confirm your project builds without errors. If it doesn’t you’ll get errors when scaffolding files.

3. Install the code generator tool globally using dotnet tool install -g dotnet-aspnet-codegenerator.

4. Run dotnet aspnet-codegenerator identity -lf from the project folder (not the solution folder), to see the list of files you can scaffold:

>  dotnet aspnet-codegenerator identity -lf
Building project ...
Finding the generator 'identity'...
Running the generator 'identity'...
File List:
Account._StatusMessage
Account.AccessDenied
Account.ConfirmEmail
Account.ConfirmEmailChange
Account.ExternalLogin
Account.ForgotPassword
Account.ForgotPasswordConfirmation
Account.Lockout
... 25 more not shown!

In this case, I’m going to scaffold the Account.Register page, and remove the external login provider section completely.

You can create a Razor Pages app using the default UI by running dotnet new webapp -au Individual -uld

If you’re scaffolding into a project that’s configured to use the default UI, you will already have an EF Core IdentityDbContext in your application. Pass the fully namespaced name of the context in the following command, using the -dc switch, when scaffolding your files:

dotnet aspnet-codegenerator identity -dc TestApp.Data.ApplicationDbContext --files "Account.Register"

After running this command, you’ll find a bunch more files in the Areas/Identity folder:

The generated pages override the equivalents in the default UI package, so any changes you make to Register.cshtml will be reflected in your app. For example, I can delete the external login provider section entirely:

Remove your liabilities – deleting the scaffolded PageModel

I don’t want that code, so I’m just going to delete it! As I’m only going to make changes to the Razor views, I can delete the following files:

• Areas/Identity/Pages/Account/Register.cshtml.cs — this is the PageModel implementation I don’t want to have to maintain
• Areas/Identity/Pages/Account/ViewImports.cshtml — No longer necessary, as there’s nothing in the namespace it specifies now
• Areas/Identity/Pages/_ValidationScriptsPartial.cshtml — A duplicate of the version included in the default UI. No need to override it
• Areas/Identity/Pages/IdentityHostingStartup.cs — Doesn’t actually configure anything, so can be deleted

Additionally, you can update Areas/Identity/Pages/ViewImports.cshtml to remove the project-specific namespaces, to leave just the following:

@using Microsoft.AspNetCore.Identity
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

At this point, your app won’t compile. The Register.cshtml page will complain that you’ve specified a now non-existent RegisterModel as the PageModel for the Razor Page:

The final step is to update the @page directive to point to the original RegisterModel that’s included with the default Identity UI, referenced in full in the example below:

@page
@model Microsoft.AspNetCore.Identity.UI.V4.Pages.Account.Internal.RegisterModel
@{
    ViewData["Title"] = "Register";
}

This is the magic step. Your application will now compile, use your custom Razor views, but use the original Razor Pages PageModels that are part of the default UI! That’s much less code to maintain, and less chance to screw something up in your Identity pages

What are the downsides?

So what are the downsides of this approach? The only one I can really think of is that you’re very tightly tied to the PageModels in the original Identity UI, so you have to be sure that any updates that are made to the Identity UI are reflected in your Razor Page templates as appropriate. The big advantage is that if the default UI package is updated and it doesn’t make any breaking changes to the Razor templates, then you get the updates with no friction at all.

Another danger is that the inability to customise the PageModel may encourage you to do slightly janky things like @inject-ing services into the Razor views that shouldn’t be there, and adding additional logic into the Razor views. I’m not suggesting you should do this. If you _do_ need to change the behaviour of the page handlers, then you should just go ahead and take ownership of that code. The point is that this technique is useful when you don’t need to change the page handler logic.

Summary

In this post I gave some background on ASP.NET Core Identity and the default UI Razor Class Library that provides over 30 Razor Pages “for free”. I then showed how you could use the scaffolder tool to override one of these pages when you want to change the Razor template.

The downside of this default approach is that you now have to maintain the page handlers for the scaffolded pages. That’s 100s of lines of code per page that you must keep up to date when a new package version is released.

I showed how you can avoid that burden by deleting the scaffolded PageModel file, and point your Razor template to the original PageModel that comes as part of the default UI. This lets you update your Razor templates without having to take ownership of the page handler logic, potentially giving you the best of both worlds.

The mediator pattern is meant to split responsibilities between a caller and the callee. So instead of having an instance of a class and calling a method directly on it, you ask the mediator to do this for you. While this might sound a lot like doing dependency injection, it actually goes a step further. You don’t even know the interface of the callee. This makes it even more decoupled than you’d have with dependency injection.

The result is that the objects are loosely coupled. They only know about the mediator object, not about each other. Besides the mediator object they’ll likely also have some kind of data transfer object to send parameters for the callee.

For a comparison in the real world, imagine only being able to communicatie with someone or a department through their secretary. You give them a message (the data transfer object) and they pass it on to who you want to reach. Once there’s an answer, the secretary will give it back to you. This way you have no knowledge of who actually answered it.

Advantages and Disadvantages of the Mediator Pattern

The mediator pattern brings a couple of advantages:

• Less coupling: Since the classes don’t have dependencies on each other, they are less coupled.
• Easier reuse: Fewer dependencies also helps to reuse classes.
• Single Responsibility Principle: The services don’t have any logic to call other services, therefore they only do one thing.
• Open/closed principle: Adding new mediators can be done without changing the existing code.

There is also one big disadvantage of the mediator pattern:

• The mediator can become such a crucial factor in your application that it is called a “god class”

How to Implement Mediator Pattern ASP.NET Core 3.1

Start by opening Visual Studio and creating an ASP.NET Core 3.1 Web Application with a name and at any location.

Choose an empty project since this is just a demo.

Install the Nuget Swashbuckle.AspNetCore so we can use Swagger to test the API:

Open the file Startup.cs and configure both MVC and Swagger, making it easier to test our web API.

    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();

            services.AddSwaggerGen();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            app.UseDeveloperExceptionPage();

            app.UseSwagger();

            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "Mediator ExampleApi V1");
            });

            app.UseRouting();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }.

The web API

Since the objective of this article is to show the mediator pattern, a simple endpoint to manage products should be enough:

• GET /products — search for products using some filters;
• GET /products/{id} — get a product by its unique identifier;
• POST /products — create a product;
• PUT /products/{id} — update a product by its unique identifier;
• DELETE /products/{id} — delete a product by its unique identifier;

Create a Controllers folder with another Products folder inside, a ProductsController and the following models:

    [Route("products")]
    public class ProductsController : ControllerBase
    {
        [HttpGet]
        public async Task<IEnumerable<ProductModel>> SearchAsync([FromQuery] string filterQ, [FromQuery] int? skip, [FromQuery] int? take, CancellationToken ct)
        {
            throw new NotImplementedException();
        }

        [HttpGet("{id:guid}")]
        public async Task<ProductModel> GetByIdAsync([FromRoute] Guid id, CancellationToken ct)
        {
            throw new NotImplementedException();
        }

        [HttpPost]
        public async Task<CreateProductResultModel> CreateAsync([FromBody] CreateProductModel model, CancellationToken ct)
        {
            throw new NotImplementedException();
        }

        [HttpPut("{id:guid}")]
        public async Task UpdateAsync([FromRoute] Guid id, [FromBody] UpdateProductModel model, CancellationToken ct)
        {
            throw new NotImplementedException();
        }

        [HttpDelete("{id:guid}")]
        public async Task DeleteAsync([FromRoute] Guid id, CancellationToken ct)
        {
            throw new NotImplementedException();
        }
    }

    public class CreateProductModel
    {
        public string Code { get; set; }

        public string Name { get; set; }

        public decimal Price { get; set; }
    }

    public class CreateProductResultModel
    {
        public Guid Id { get; set; }
    }

    public class ProductModel
    {
        public Guid Id { get; set; }

        public string Code { get; set; }

        public string Name { get; set; }

        public decimal Price { get; set; }
    }

    public class UpdateProductModel
    {
        public string Code { get; set; }

        public string Name { get; set; }

        public decimal Price { get; set; }
    }

The project should look as follows:

Open the Swagger endpoint (ex: https://localhost:44380/swagger/index.html) and you should see your products endpoint with all the actions:

The database model

For demo purposes we are going to use Entity Framework Core with data stored in-memory.

Install the Nuget Microsoft.EntityFrameworkCore.InMemory:

Create a Database folder, the following database context and a product entity:

    public class ApiDbContext : DbContext
    {
        public ApiDbContext(DbContextOptions<ApiDbContext> options) : base(options)
        {

        }

        protected override void OnModelCreating(ModelBuilder builder)
        {
            base.OnModelCreating(builder);

            builder.Entity<ProductEntity>(cfg =>
            {
                cfg.HasKey(e => e.Id);
                cfg.HasAlternateKey(e => e.ExternalId);

                cfg.HasIndex(e => e.Code).IsUnique();

                cfg.Property(e => e.ExternalId)
                    .IsRequired();
                cfg.Property(e => e.Code)
                    .IsRequired()
                    .HasMaxLength(8);
                cfg.Property(e => e.Name)
                    .IsRequired()
                    .HasMaxLength(128);
                cfg.Property(e => e.Price)
                    .IsRequired();
            });
        }
    }

    public class ProductEntity
    {
        public long Id { get; set; }

        public Guid ExternalId { get; set; }

        public string Code { get; set; }

        public string Name { get; set; }

        public decimal Price { get; set; }
    }

Open the Startup.cs file and add the context into the container as an in-memory database:

services.AddDbContext<ApiDbContext>(o =>
{
    o.UseInMemoryDatabase("ApiDbContext");
});

The project should look as follows:

The mediator

Now that we have created the demo endpoint, models and database, its time to configure the mediator.

Install the Nuget SimpleSoft.Mediator.Microsoft.Extensions which is a specialized package for projects using Microsoft.Extensions.*:

Open the Startup.cs file and add the mediator into the container, scanning the current assembly for all classes implementing ICommandHandler, IQueryHandler and IEventHandler:

services.AddMediator(o =>
{
    o.AddHandlersFromAssemblyOf<Startup>();
});

Open the ProductsController.cs file and inject into the constructor the IMediator instance:

private readonly IMediator _mediator;
public ProductsController(IMediator mediator)
{
    _mediator = mediator;
}

The handlers

We now have everything we need to start implementing the business logic.

To keep it simple, we are not going to use the mediator pipelines, only focusing on commands, queries, events and their handlers. I’ll demonstrate more complex scenarios in future articles.

Start by creating a folder named Handlers with another inside Products in which we are going to put our POCOs and their handlers.

As a note, remember this is a demo article and this project structure should not be seen as a valid way to organize your solution in your private projects. Commands, queries, events and their handlers should be, at minimum, in different folders.

CreateProductComand

We need data so lets create a command that allows that and will be sent when a request for POST /products is received.

Create a class CreateProductResult that will be returned by the handler with the product unique identifier and a CreateProductCommand, implementing the class Command<CreateProductResult>:

    public class CreateProductCommand : Command<CreateProductResult>
    {
        public string Code { get; set; }

        public string Name { get; set; }

        public decimal Price { get; set; }
    }

    public class CreateProductResult
    {
        public Guid Id { get; set; }
    }

Open the ProductsController.cs file and inside the method CreateAsync send the command into the mediator and map its result:

[HttpPost]
public async Task<CreateProductResultModel> CreateAsync([FromBody] CreateProductModel model, CancellationToken ct)
{
    var result = await _mediator.SendAsync(new CreateProductCommand
    {
        Code = model.Code,
        Name = model.Name,
        Price = model.Price
    }, ct);
    return new CreateProductResultModel
    {
        Id = result.Id
    };
}

If we now invoked the endpoint, we would receive an exception saying that no ICommandHandler<CreateProductCommand, CreateProductResult> was found by the container.

We will fix that by creating the class CreateProductCommandHandler with the business logic for this action. For this demo, an InvalidOperationException with a custom message will be thrown when a duplicated code is received:

    public class CreateProductCommandHandler : ICommandHandler<CreateProductCommand, CreateProductResult>
    {
        private readonly ApiDbContext _context;

        public CreateProductCommandHandler(ApiDbContext context)
        {
            _context = context;
        }

        public async Task<CreateProductResult> HandleAsync(CreateProductCommand cmd, CancellationToken ct)
        {
            var products = _context.Set<ProductEntity>();

            if (await products.AnyAsync(p => p.Code == cmd.Code, ct))
            {
                throw new InvalidOperationException($"Product code '{cmd.Code}' already exists");
            }

            var externalId = Guid.NewGuid();
            await products.AddAsync(new ProductEntity
            {
                ExternalId = externalId,
                Code = cmd.Code,
                Name = cmd.Name,
                Price = cmd.Price
            }, ct);

            await _context.SaveChangesAsync(ct);

            return new CreateProductResult
            {
                Id = externalId
            };
        }
    }

If you now try to create a product using the Swagger endpoint, you will receive the response with the unique identifier or an internal server error indicating a duplicated code.

The project should look as follows:

GetProductByIdQuery

Time to return a product when a GET /products/:id is received by the web API.

Inside the Handlers/Products folder, create a Product, the GetProductByIdQuery and its corresponding handler, GetProductByIdQueryHandler. Like in the previous handler, for this demo, we are going to throw an InvalidOperationException if the id is unknown:

    public class GetProductByIdQuery : Query<Product>
    {
        public Guid ProductId { get; set; }
    }

    public class Product
    {
        public Guid Id { get; set; }

        public string Code { get; set; }

        public string Name { get; set; }

        public decimal Price { get; set; }
    }

    public class GetProductByIdQueryHandler : IQueryHandler<GetProductByIdQuery, Product>
    {
        private readonly IQueryable<ProductEntity> _products;

        public GetProductByIdQueryHandler(ApiDbContext context)
        {
            _products = context.Set<ProductEntity>();
        }

        public async Task<Product> HandleAsync(GetProductByIdQuery query, CancellationToken ct)
        {
            var product = await _products.SingleOrDefaultAsync(p => p.ExternalId == query.ProductId, ct);

            if (product == null)
            {
                throw new InvalidOperationException($"Product '{query.ProductId}' not found");
            }

            return new Product
            {
                Id = product.ExternalId,
                Code = product.Code,
                Name = product.Name,
                Price = product.Price
            };
        }
    }

Open the ProductsController.cs file and inside the method GetByIdAsync fetch the query from the mediator and map its result:.

[HttpGet("{id:guid}")]
public async Task<ProductModel> GetByIdAsync([FromRoute] Guid id, CancellationToken ct)
{
    var result = await _mediator.FetchAsync(new GetProductByIdQuery
    {
        ProductId = id
    }, ct);
    return new ProductModel
    {
        Id = result.Id,
        Code = result.Code,
        Name = result.Name,
        Price = result.Price
    };
}

If you now try to get a product using the Swagger endpoint, you will receive the product or an internal server error indicating an unknown identifier.

CreatedProductEvent

Finally, we are going to create an event that will be broadcast when a product is successfully created.

Just like the previous ones, create a CreateProductEvent and the handler CreateProductEventHandler. This time we are just going to log that a product was created:

    public class CreatedProductEvent : Event
    {
        public Guid ExternalId { get; set; }

        public string Code { get; set; }

        public string Name { get; set; }

        public decimal Price { get; set; }
    }

    public class CreatedProductEventHandler : IEventHandler<CreatedProductEvent>
    {
        private readonly ILogger<CreatedProductEventHandler> _logger;

        public CreatedProductEventHandler(ILogger<CreatedProductEventHandler> logger)
        {
            _logger = logger;
        }

        public Task HandleAsync(CreatedProductEvent evt, CancellationToken ct)
        {
            _logger.LogInformation("The product '{externalId}' has been created", evt.ExternalId);

            return Task.CompletedTask;
        }
    }

Open the CreateProductCommandHandler file, inject the IMediator instance and after saving the changes just broadcast the event:

    public class CreateProductCommandHandler : ICommandHandler<CreateProductCommand, CreateProductResult>
    {
        private readonly ApiDbContext _context;
        private readonly IMediator _mediator;

        public CreateProductCommandHandler(ApiDbContext context, IMediator mediator)
        {
            _context = context;
            _mediator = mediator;
        }

        public async Task<CreateProductResult> HandleAsync(CreateProductCommand cmd, CancellationToken ct)
        {
            var products = _context.Set<ProductEntity>();

            if (await products.AnyAsync(p => p.Code == cmd.Code, ct))
            {
                throw new InvalidOperationException($"Product code '{cmd.Code}' already exists");
            }

            var externalId = Guid.NewGuid();
            await products.AddAsync(new ProductEntity
            {
                ExternalId = externalId,
                Code = cmd.Code,
                Name = cmd.Name,
                Price = cmd.Price
            }, ct);

            await _context.SaveChangesAsync(ct);

            await _mediator.BroadcastAsync(new CreatedProductEvent
            {
                ExternalId = externalId,
                Code = cmd.Code,
                Name = cmd.Name,
                Price = cmd.Price
            }, ct);

            return new CreateProductResult
            {
                Id = externalId
            };
        }
    }

The project should look as follows:

Conclusion

I hope this article gave you a good idea on how to use the mediator to implement the CQRS and ES patterns even if you are implementing an MVP and can’t spend much time thinking about the architecture but you still want something that can be maintained and extended for some time.

Soon I’ll be explaining more advanced scenarios, like using the mediator pipeline to validate commands before reaching the handler, managing database transactions or even implementing transversal auditing into you application.