DEV Community: devInstance

Implementing a Mock-Driven Approach in Blazor Applications

InstanceMaster — Thu, 27 Apr 2023 16:19:37 +0000

When starting a project, you typically work with clients on UI sketches. The client provides a list of requirements or pages they want to see. You begin building the client app and backend, designing the database schema, etc. After a few weeks, you present the first demo to the client, only to discover they want to change everything.

Does that sound familiar to you?

Using a "UI first" or "mock-driven approach" can indeed save time for both you and your client, particularly when the client is uncertain about the final product. This approach allows for more efficient development, enabling you to better accommodate changes requested by your client.

This article discusses the "UI first" approach in developing a Blazor application. By building a page and using dependency injection to pass a reference to a service, we will create a mock class for the service. We will then replace the mock with a real service implementation, keeping web API calls abstracted and creating a mock there until the backend is ready. This tutorial will show you how to set up a Visual Studio solution optimally.

A mock driven approach is useful for developing applications with multiple layers of logic. These layers typically include presentation (UI), data transformation and state management (services), and communication with the server (network). By separating and abstracting each layer, we can achieve polymorphism, which allows for more flexibility in implementation.

To implement a solution gradually, we can start with the UI layer and define the interface for the service. Instead of implementing the actual service, we can create a mock class that acts as the real interface for now. This enables us to focus on the UI without worrying about middleware logic. As we refine the service interface, we ensure that our page receives all the necessary information.

The mock driven approach allows for incremental development and testing of individual layers before fully integrating them into the complete solution. This approach can lead to more maintainable and robust applications.

Step 1: Create the Blazor app and divide it into three layers.

Let's start by creating a Blazor WebAssembly App:

The full source of this solution is available on GitHub.

After creating the project, reorganize it into a more structured format by dividing the client project into three parts:

Client/UI: The original Blazor WASM project containing components, pages, etc.
Services: A Class Library containing all the logic related to processing requests and responses from the server, including caching, managing state, and data presentation. The service's library is just a regular Class Library:

Network: Another Class Library responsible for handling REST calls.

The Client Blazor app should depend on the Services library, while the Services library should depend on the Network library. This establishes a clear hierarchy among the components. We will configure dependency injection (DI) for both services and web APIs at a later stage, after creating the mocks.

Step 2: Create and configure the mock project.

Create a "Mocks" Class Library project and add it to the solution. Your Solution Explorer should look like this:

We don't want the Mocks to be built in all project configurations. Ensure that Debug and Release configurations don't build Mocks by unchecking the Mocks project in both configuration options:

To build mocks, create two new configurations: MockService and MockNetApi:

Configure the main project's dependencies by making the Mocks dependency conditional:

<ItemGroup>
  <ProjectReference Include="..\Net\MyBlazorApp.Net.csproj" />
  <ProjectReference Include="..\Services\MyBlazorApp.Services.csproj" />
  <ProjectReference Include="..\..\Shared\MyBlazorApp.Shared.csproj" />
</ItemGroup>
<ItemGroup Condition="'$(Configuration)'=='MockNetApi'">
  <ProjectReference Include="..\Mocks\MyBlazorApp.Mocks.csproj" />
</ItemGroup>
<ItemGroup Condition="'$(Configuration)'=='MockService'">
  <ProjectReference Include="..\Mocks\MyBlazorApp.Mocks.csproj" />
</ItemGroup>

In addition to the solution build configuration, ensure the correct DI behavior. All three projects (Services, Network, and Mocks) should contain service extension methods that are called in Program.cs depending on the selected configuration:

public class Program
{
    public static async Task Main(string[] args)
    {
        var builder = WebAssemblyHostBuilder.CreateDefault(args);
//...
#if MOCKNETAPI
        builder.Services.AddMockNetApi();
#else
        builder.Services.AddNetApi();
#endif

#if MOCKSERVICE
        builder.Services.AddMockAppServices();
#else
        builder.Services.AddAppServices();
#endif
//...
    }
}

Step 3: Create a page and define a service interface.

Instead of creating a new page, we are going to use the FetchData.razor (a part of the project template). Since this page displays a Weather forecast, we are going to modify it to rely on IWeatherForecastService to obtain the data. Additionally, we will add a special feature to this service: it will generate a summary or description of the forecast based on the temperature. To accommodate this field, we will introduce a local model class, WeatherForecastItem, in the Services project:

using MyBlazorApp.Shared;

namespace MyBlazorApp.Services.Model;

public class WeatherForecastItem : WeatherForecast
{
    public string? Summary { get; set; }
}

IWeatherForecastService itself will be part of the Services project in the Api folder:

namespace MyBlazorApp.Services.Api;

public interface IWeatherForecastService
{
    Task<WeatherForecastItem[]> GetForecastAsync();
}

Now, we will remove the reference to HttpClient and add IWeatherForecastService to the page:

@page "/fetchdata"
@using MyBlazorApp.Services.Api;
@using MyBlazorApp.Shared
@inject IWeatherForecastService Service

//...

@code {
    private WeatherForecastItem[]? forecasts;

    protected override async Task OnInitializedAsync()
    {
        forecasts = await Service.GetForecastAsync();
    }
}

Step 4: Implement a mock for this service.

If you start the application now and click on the "Fetch data" link in the menu on the left side, you will see an error in the browser's console: Unhandled exception rendering component: Cannot provide a value for property 'Service' on type 'MyBlazorApp.Client.Pages.FetchData'. There is no registered service of type 'MyBlazorApp.Services.Api.IWeatherForecastService'.

This is the time to introduce the mock class:

using MyBlazorApp.Services.Api;
using MyBlazorApp.Services.Model;

namespace MyBlazorApp.Mocks.ServicesMocks;

internal class WeatherForecastServiceMock : IWeatherForecastService
{
    private static readonly string[] Summaries = new[]
    {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    public async Task<WeatherForecastItem[]> GetForecastAsync()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecastItem
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        }).ToArray();
    }
}

Next, register WeatherForecastServiceMock in the DI services. Add the following line in ServiceExtensions.cs:

public static IServiceCollection AddMockAppServices(this IServiceCollection services)
{
     services.AddScoped<IWeatherForecastService, WeatherForecastServiceMock>();

    return services;
}

Now, switch to the "MockService" configuration, build, and run.

Step 5: Repeat steps 3 and 4 until the application's UI is ready.

Add more pages, service interfaces, or methods to the existing services. Iterate and refine until you have something you can demo to your client.

Step 6: Demo it to the client.

During the demonstration, it is important to let the client know that it is only a prototype and most of the work still needs to be done.

Good luck with your demo!

Final Step (a big one): Implement the service itself, web API interfaces, and unit tests.

Once the UI part and service interfaces are defined, you can proceed with the service implementation.

using MyBlazorApp.Net.Api;
using MyBlazorApp.Services.Api;
using MyBlazorApp.Services.Model;

namespace MyBlazorApp.Services;

internal class WeatherForecastService : IWeatherForecastService
{
    IWeatherForecastApi Api { get; set; }
    public WeatherForecastService(IWeatherForecastApi api)
    {
        Api = api;
    }

    private static string FindSummary(int temperatureC)
    {
    //...
    }

    public async Task<WeatherForecastItem[]> GetForecastAsync()
    {
        var result = await Api.GetForecastAsync();
        return result.Select(x => new WeatherForecastItem
        {
            Date = x.Date,
            TemperatureC = x.TemperatureC,
            Summary = FindSummary(x.TemperatureC)
        }).ToArray();
    }
}

and add it to the DI in ServiceExtensions.cs:

public static class ServiceExtensions
{
    public static IServiceCollection AddAppServices(this IServiceCollection services)
    {
        services.AddScoped<IWeatherForecastService, WeatherForecastService>();

        return services;
    }
}

This article could end here since it covers the most important part with UI mocks. However, I want to give a complete picture of this project structure, which is why I introduced the Network layer earlier. First, it allows you to build and test the service's logic without having an actual back-end ready. It also provides the ability to cover the service with unit tests by mocking the network layer.

Mocking web API follows the same principle as with services. We are going to create IWeatherForecastApi in the Network project in the Api folder:

using MyBlazorApp.Shared;

namespace MyBlazorApp.Net.Api;

public interface IWeatherForecastApi
{
    Task<WeatherForecast[]> GetForecastAsync();
}

and we are going to create a mock for it in the Mock project:

using MyBlazorApp.Net.Api;
using MyBlazorApp.Shared;

namespace MyBlazorApp.Mocks.NetApiMocks;

internal class WeatherForecastApiMock : IWeatherForecastApi
{
    public async Task<WeatherForecast[]> GetForecastAsync()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
        }).ToArray();
    }
}

and register it in ServiceExtensions.cs:

public static IServiceCollection AddMockNetApi(this IServiceCollection services)
{
    services.AddScoped<IWeatherForecastApi, WeatherForecastApiMock>();

    return services;
}

Closing Thoughts

Thank you for taking the time to read this article! I hope it proves useful for your ongoing projects. Your feedback and shared experiences are invaluable, so please feel free to leave comments below. Don't forget to follow me on Twitter for more updates and insights.

A Practical Guide to ASP.NET Applications: Designing Robust CRUD WebAPIs (Part2)

InstanceMaster — Tue, 18 Apr 2023 16:02:35 +0000

This article offers an approach to designing, implementing, and unit-testing CRUD APIs (Create, Read, Update, Delete). We will explore best practices for designing web APIs, discuss how to implement pagination, searching, and outline methods for organizing models effectively.

Introduction

In a previous article, we reviewed the general structure of the template project DevCoreApp, which is available on GitHub. In this article, we demonstrate how to add a new entity type as well as CRUD functionality using rules and features available in this project.

Everyone who has recently created an ASP.NET project from a Visual Studio template has likely encountered the Weather Forecast page example. The purpose of this example is to demonstrate how to retrieve data from the server. We will extend this use case by adding a weather forecast table to the database, creating a model, shared model, and implementing the necessary data retrieval logic, service, and controller. Additionally, we will incorporate pagination and searching capabilities.

We are going to work backward from the API itself. We will define the requirements and implement them, starting from the top (API/Controller), then moving to the Service, and finally, to the data provider.

As a starting point, we will use the DevCoreApp project, available on GitHub.

Crafting Web API Requirements

Let's specify the requirements:

As a client application, I need an API to retrieve a list of weather forecasts. This API should accept parameters for the maximum number of forecasts to return, the page number, and a search parameter.
As a client application, I need an API to fetch a forecast record by its id, and to insert, update, and delete the forecast record.

Sculpting the API and Shared Model

For the model object shared between the server and client, we'll take the existing WeatherForecast as a base. There are several modifications we have to make to it though:

Relocate it to the Shared.Model assembly.
In accordance with the shared model naming convention, append the Item suffix to the name.
To include the id field, inherit it from the EntityItem class.

Here's the refined structure of the shared model item:

public class WeatherForecastItem : EntityItem
{
    public DateTime Date { get; set; }
    public int TemperatureC { get; set; }
    public string Summary { get; set; }
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

public class EntityItem
{
    public string Id { get; set; }
}

Now, let's define the CRUD APIs. We are going to modify the WeatherForecastController with the route "api/forecast". In this controller, we will add the following APIs:

GetById : Retrieves a WeatherForecastItem by public id or returns HTTP 404 (Not Found) if there is no record with the specified id.
Add : Accepts a WeatherForecastItem object and returns it with the public id and other automatic attributes. This API requires authorization and returns HTTP 401 (Unauthorized) if the criteria have not been met.
Update : Accepts an id and a WeatherForecastItem object. Returns the updated version of the object. This API also requires authorization and returns HTTP 401 (Unauthorized) or HTTP 404 (Not Found) if the object with the specified id doesn't exist in the database.
Remove : Accepts an id and returns the deleted WeatherForecastItem object (allowing the client to reinsert it later, if needed). Follows the same rules as the Update API (HTTP 401 & 404).
GetItems : Returns a list of items wrapped in a ModelList object. Accepts parameters for paging, filters, fields, and search. This API is more complex and requires further explanation:

Here is what the controller is going to look like:

[ApiController]
[Route("api/forecast")]
public class WeatherForecastController : BaseController
{
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public ActionResult<ModelList<WeatherForecastItem>> GetItems(int? top, int? page, string search = null)
    {
        return HandleWebRequest<ModelList<WeatherForecastItem>>(() =>
        {
            throw new NotImplementedException();
        });
    }

    [HttpGet]
    [Route("{id}")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public ActionResult<WeatherForecastItem> GetById(string id)
    {
        return HandleWebRequest((WebHandler<WeatherForecastItem>)(() =>
        {
            throw new NotImplementedException();
        }));
    }

    [Authorize]
    [HttpPost]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    public ActionResult<WeatherForecastItem> Add(WeatherForecastItem item)
    {
        return HandleWebRequest<WeatherForecastItem>(() =>
        {
            throw new NotImplementedException();
        });
    }

    [Authorize]
    [HttpPut]
    [Route("{id}")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public ActionResult<WeatherForecastItem> Update(string id, [FromBody] WeatherForecastItem item)
    {
        return HandleWebRequest<WeatherForecastItem>(() =>
        {
            throw new NotImplementedException();
        });
    }

    [Authorize]
    [HttpDelete]
    [Route("{id}")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public ActionResult<WeatherForecastItem> Remove(string id)
    {                   
        return HandleWebRequest<WeatherForecastItem>(() =>
        {
            throw new NotImplementedException();
        });
    }
}

This controller is derived from the BaseController, which implements the HandleWebRequest method. This method encapsulates exception-handling logic and returns an ActionResult based on the outcome of the call. The text is well-written and presents a straightforward description of the controller.

The Weather Forecast Service

As you can see, the controller above defines APIs but returns a 500 error for every API because the implementation is missing. As explained in the previous article, the controller should remain "slim" and call the service to perform the required tasks. Therefore, we need to define a WeatherForecastService that presents similar methods. There are several points to consider:

Service class should have the [AppService] attribute.
Service cannot reference controllers in any case.
Service cannot expose any internal types besides types declared as part of the shared model or simple types.

Here is what the service looks like:

[AppService]
public class WeatherForecastService : BaseService
{
    public WeatherForecastItem Add(WeatherForecastItem item)
    {
        throw new NotImplementedException();
    }
    // ...
}

In turn, we can add a reference to the controller and implement its methods:

public class WeatherForecastController : BaseController
{
    public WeatherForecastService Service { get; }

    public WeatherForecastController(WeatherForecastService service)
    {
        Service = service;
    }
    // ...
    [Authorize]
    [HttpPost]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    public ActionResult<WeatherForecastItem> Add(WeatherForecastItem item)
    {
        return HandleWebRequest<WeatherForecastItem>(() =>
        {
            return Ok(Service.Add(item));
        });
    }
    // ...
}

Now let's implement the service. The first step is to "inject" the data provider. We will use the Repository pattern for this purpose. The following concept of using a repository is prevalent. However, it would be confusing to define all the interfaces working with data at this point. So, we are going to examine the existing implementation of the "Add" method line by line, assuming all data provider interfaces are defined already. Later, we will dive deep into the data provider itself and its interfaces.

I'm going to present the next snippet with the implementation of the method "Add" and explain every line:

public WeatherForecastItem Add(WeatherForecastItem item)
{
    Validate(item);
    var q = Repository.GetWeatherForecastQuery();

    var record = q.CreateNew().ToRecord(item);
    q.Add(record);

    return GetById(record.PublicId);
}

We call Validate() to validate the incoming object. This method defines validation rules, and if this model object is not valid for some reason, it will throw a BadRequestException, which will be caught by the controller and converted into HTTP 400 (Bad Request).
Every service has a reference to the IQueryRepository interface. This is an abstraction that hides the actual database access logic from the service. This interface will be mocked in unit tests of the service.
We get a specific query interface, IWeatherForecastQuery.
Once we get a reference to the query interface, we call IModelQuery.CreateNew() which creates a database model object for the forecast record. This object will have all the pre-generated attributes ready, such as Id, PublicID (which will be shared with the client), etc.
The extension method ToRecord() merges all the data from the shared model into this newly created record object.
The Add() method inserts a record into the database.
GetById() returns a shared model object from the database.

As you probably guessed, the Repository and all interfaces it provides are defined in the Data Provider. We will talk about it more later in this article.

Why do we need so much "glue code" and service? There are a couple of reasons to support this approach:

Separation of concerns: the controller only cares about handling HTTP requests, which makes it simple. The service implements "business logic" but doesn't care about the actual DB. You can start with an in-memory DB, a flat file, mock it, and delay decisions about which DBMS to use or how the schema should look like. You have to define model and query interfaces, though.
It is easy to unit test. As mentioned earlier, mocking the data provider interface will help in unit testing the service. Additionally, you don't have to refer to any data types used in the controller (such as ActionResult). The following example shows how to set up a unit test for the "Add" method:

[TestMethod()]
public void AddTest()
{
    var id = Guid.NewGuid();
    var publicId = IdGenerator.New();
    var date = DateTime.Now;
    var mockSelect = new Mock<IWeatherForecastQuery>();
    var service =
    SetupServiceMock((mockRepository) =>
    {    
        WeatherForecast[] data = { 
            new WeatherForecast { Id = id, PublicId = publicId, CreateDate = date, UpdateDate = date }, };
        mockSelect.Setup(x => x.CreateNew()).Returns(data[0]);
        mockSelect.Setup(x => x.Select()).Returns(data.AsQueryable());
        mockSelect.Setup(x => x.ByPublicId(It.IsAny<string> ())).Returns(mockSelect.Object);
        mockSelect.Setup(x => x.Clone()).Returns(mockSelect.Object);
        mockRepository.Setup(x => x.GetWeatherForecastQuery(It.IsAny<UserProfile>())).Returns(mockSelect.Object);
    });

    var item = new WeatherForecastItem
    {
        Date = date,
        Summary = "Test",
        TemperatureC = 32,
    };

    var result = service.Add(item);

    Assert.IsNotNull(result);
    Assert.AreEqual("Test", result.Summary);
    Assert.AreEqual(date, result.Date);
    Assert.AreEqual(32, result.TemperatureC);

    mockSelect.Verify(x => x.Add(It.IsAny<WeatherForecast>()), Times.Once);
}

Please refer to the test class WeatherForecastServiceTests for more details.

Data Provider

Data providers play a crucial role in supplying the necessary tools and resources to a service. Their primary objective is to separate high-level business logic from the specifics of database implementations or data query methods. This separation grants flexibility when it comes to selecting a database engine, replacing it when necessary, or even opting not to use a database at all.

The "Database" folder contains data providers divided into two main sections: "Database.Core" and "Database.(e.g. Database.SqlServer or Database.Postgres)". The "Database.Core" section encompasses all the interfaces, shared logic, and remains agnostic to any particular database engine. On the other hand, the "Database." section is responsible for implementing the interfaces, incorporating database-specific code, and, if using Entity Framework (EF), handling migrations. See more about providers and migrations in Database ReadMe.

Database Model

Database model classes define the structure and schema of your database. They typically share a majority of fields with their corresponding shared models. However, there are some key differences:

Database models include primary and, in some cases, secondary keys. Shared models should never contain internal keys from the database. Instead, they should use a PublicID, which can be changed if necessary without affecting database integrity.
Database model types must not be shared with controllers; they should be used exclusively by services. Services are responsible for converting data between shared models and database models. To facilitate this, the Core library provides extension methods known as "decorators." You can refer to an example of decorators here.

Here's an example of a model class definition for weather forecast records:

public class WeatherForecast
{
    [Key]
    public Guid Id { get; set; }

    [Required]
    public string PublicId { get; set; }

    public DateTime Date { get; set; }

    public int Temperature { get; set; }

    public string Summary { get; set; }
}

This model class illustrates the structure of weather forecast records in the database, including primary keys, required fields, and other relevant attributes.

Implementing the Repository Pattern

The Repository Pattern is a design pattern that establishes a clear separation between data access and business logic in an application. By centralizing data access and decoupling it from the underlying data storage, this pattern allows for more flexible and maintainable code. In our example, the pattern is represented by the IQueryRepository interface.

IQueryRepository

IQueryRepository is part of the Database.Core library and its purpose is to define the methods required to interact with different data sources:

public interface IQueryRepository
{
    ...
    IWeatherForecastQuery GetWeatherForecastQuery();
}

Provider Implementation

The actual implementation of the IQueryRepository interface is located in the Provider library. In this example, we use the SQLServer provider:

public class SqlServerQueryRepository : IQueryRepository
{
    public SqlServerQueryRepository(ApplicationDbContext dB)
    {
        return new SqlServerForecastQuery(DB);
    }
}

By adhering to the Repository Pattern, you create a clean separation between data access and business logic, making it easier to switch the underlying data storage technology, implement unit testing, and maintain the codebase. The IQueryRepository interface serves as a contract that can be implemented by different database providers, offering flexibility and adaptability to your application.

Implementing the Query Interface

The query interface is a part of the Core project as well. For each specific table or set of tables, every query interface implements operations that can be performed on them. The repository will return a reference to a specific query implementation, in our case, IWeatherForecastQuery:

public interface IWeatherForecastQuery : IModelQuery<WeatherForecast, IWeatherForecastQuery>, 
                                        IQSearchable<IWeatherForecastQuery>,
                                        IQPageable<IWeatherForecastQuery>
{
    IQueryable<WeatherForecast> Select();
}

As you can see, IWeatherForecastQuery inherits from several other interfaces. These interfaces are common building blocks for queries:

public interface IModelQuery<T, D>
{
    T CreateNew();
    void Add(T record);
    void Update(T record);
    void Remove(T record);
    D Clone();
}

public interface IQPageable<T>
{
    T Skip(int value);
    T Take(int value);
}

public interface IQSearchable<T>
{
    T ByPublicId(string id);
    T Search(string search);
}

The IModelQuery<T, D> interface provides methods for creating, adding, updating, and removing records of type T, as well as cloning the implementing instance. The CreateNew() method creates a new instance of the model type T, while the Add(), Update(), and Remove() methods are used to add, update, and remove records in the data store, respectively. The Clone() method creates a deep copy of the implementing instance and returns a new instance of type D.

The IQPageable<T> interface provides two methods, Skip() and Take(), which allows pagination for a given sequence. The Skip() method is used to skip a specified number of items before starting to take elements, while the Take() method specifies the maximum number of items to include in the resulting sequence. Both methods return an updated instance of the implementing class. The IQSearchable interface is self-explanatory. Most of the queries working with entities associated with public ids should implement this interface.

Finally, the query implementation will look like this:

public class SqlServerWeatherForecastQuery : IWeatherForecastQuery
{
    private IQueryable<WeatherForecast> currentQuery;
    protected ApplicationDbContext DB { get; }

    private CoreWeatherForecastQuery(IQueryable<WeatherForecast> q, ApplicationDbContext dB)
    {
        currentQuery = q;
        DB = dB;
    }

    public CoreWeatherForecastQuery(ApplicationDbContext dB) 
        : this(from ts in dB.WeatherForecasts
               orderby ts.Date descending
               select ts, dB)
    {

    }

    public void Add(WeatherForecast record)
    {
        DB.WeatherForecasts.Add(record);
        DB.SaveChanges();
    }

    public IWeatherForecastQuery ByPublicId(string id)
    {
        currentQuery = from pr in currentQuery
                       where pr.PublicId == id
                       select pr;

        return this;
    }

    public IWeatherForecastQuery Clone()
    {
        return new CoreWeatherForecastQuery(currentQuery, LogManager, TimeProvider, DB, CurrentProfile);
    }

    public WeatherForecast CreateNew()
    {
        return new WeatherForecast
        {
            Id = Guid.NewGuid(),
            PublicId = IdGenerator.New(),
        };
    }

    public void Remove(WeatherForecast record)
    {
        DB.WeatherForecasts.Remove(record);
        DB.SaveChanges();
    }

    public IQueryable<WeatherForecast> Select()
    {
        return (from pr in currentQuery select pr);
    }

    public void Update(WeatherForecast record)
    {
        DB.WeatherForecasts.Update(record);
        DB.SaveChanges();
    }

    public IWeatherForecastQuery Search(string search)
    {
        throw new NotImplementedException();
    }

    public IWeatherForecastQuery Skip(int value)
    {
        currentQuery = currentQuery.Skip(value);
        return this;
    }

    public IWeatherForecastQuery Take(int value)
    {
        currentQuery = currentQuery.Take(value);
        return this;
    }
}

By implementing these interfaces, you can create a clean and modular structure for your queries, making it easier to maintain and extend your data access layer.

The Final Solution

Here is a final solution for the service:

[AppService]
public class WeatherForecastService : BaseService
{
    public WeatherForecastService(IQueryRepository rep) : base(rep)
    {
    }

    public ModelList<WeatherForecastItem> GetItems(int? top, int? page, string search)
    {
        using (log.TraceScope())
        {
            var coreQuery = Repository.GetWeatherForecastQuery(AuthorizationContext.CurrentProfile);

            coreQuery = ApplyFilters(coreQuery, search);

            var pagedQuery = coreQuery.Clone();
            pagedQuery = ApplyPages(pagedQuery, top, page);

            var list = pagedQuery.Select().ToView();

            return CreateListPage(coreQuery.Select().Count(), list.ToArray(), top, page);
        }
    }

    private static void Validate(WeatherForecastItem item)
    {
        if (item.TemperatureC < -273 || String.IsNullOrWhiteSpace(item.Summary))
        {
            throw new BadRequestException();
        }
    }

    public WeatherForecastItem Add(WeatherForecastItem item)
    {
        Validate(item);

        var q = Repository.GetWeatherForecastQuery(AuthorizationContext.CurrentProfile);

        var record = q.CreateNew().ToRecord(item);

        q.Add(record);

        return GetById(record.PublicId);
    }

    public WeatherForecastItem GetById(string id)
    {
        var record = GetRecordByPublicId(id);
        return record.ToView();
    }

    private WeatherForecast GetRecordByPublicId(string id)
    {
        var q = Repository.GetWeatherForecastQuery(AuthorizationContext.CurrentProfile).ByPublicId(id);
        var record = q.Select().FirstOrDefault();
        if (record == null)
        {
            throw new RecordNotFoundException();
        }

        return record;
    }

    public WeatherForecastItem Remove(string id)
    {
        var q = Repository.GetWeatherForecastQuery(AuthorizationContext.CurrentProfile);
        var record = GetRecordByPublicId(id);

        q.Remove(record);

        return record.ToView();
    }

    public WeatherForecastItem Update(string id, WeatherForecastItem item)
    {
        Validate(item);

        var q = Repository.GetWeatherForecastQuery(AuthorizationContext.CurrentProfile);
        var record = GetRecordByPublicId(id);

        q.Update(record.ToRecord(item));

        return GetById(record.PublicId);
    }
}

and the BaseService for reference:

public abstract class BaseService
{
    public IQueryRepository Repository { get; }

    public BaseService(IQueryRepository query)
    {
        Repository = query;
    }

    protected static ModelList<T> CreateListPage<T>(int totalItemsCount, T[] items, int? top, int? page)
    {
        var pageIndex = 0;
        var totalPageCount = 1;

        if (top.HasValue && top.Value > 0)
        {
            totalPageCount = (int)Math.Ceiling((double)totalItemsCount / (double)top.Value);
        }

        if (page.HasValue && page.Value >= 0)
        {
            pageIndex = page.Value;
            if (pageIndex >= totalPageCount)
            {
                pageIndex = totalPageCount - 1;
            }
        }

        return new ModelList<T>()
        {
            TotalCount = totalItemsCount,
            Count = items.Length,
            PagesCount = totalPageCount,
            Page = pageIndex,
            Items = items
        };
    }

    protected static T ApplyPages<T>(T q, int? top, int? page) where T : IQPageable<T>
    {
        if (top.HasValue && top.Value > 0)
        {
            if (page.HasValue && page.Value > 0)
            {
                q = q.Skip(page.Value * top.Value);
            }
            q = q.Take(top.Value);
        }

        return q;
    }

    protected static T ApplyFilters<T>(T coreQuery, string search) where T : IQSearchable<T>
    {
        if (!String.IsNullOrEmpty(search))
        {
            coreQuery = coreQuery.Search(search);
        }

        return coreQuery;
    }

}

Additional Thoughts

This separation of concerns ensures a clean, maintainable codebase that makes it easier to manage and test your application.

The solution is a simplified version of the one implemented in DevCoreApp. But I hope it demonstrates how to use and extend this app. Also, I intentionally skipped database migration and changes in the database context to keep this article concise. Please see Database Readme for more details.

However, it's worth noting that this solution is just one approach among many possible solutions, and different situations may require different design patterns or architectures. It's important to choose the appropriate solution for your specific use case and requirements.

A Practical Guide to ASP.NET Applications: The Structure (Part 1)

InstanceMaster — Tue, 11 Apr 2023 19:20:37 +0000

In this article, we will discuss structuring an ASP.NET Core project to prepare it for large-scale commercial software solutions. Topics covered include project structure as well as service boundaries and responsibilities. To see a practical example of the concepts discussed, please check out the DevCoreApp repository.

Introduction

Every time I began a new project, I relied on the standard Visual Studio project template. Updated regularly by the Visual Studio team, it is a great way to explore new features. However, due to its simplicity, the project template lacks the necessary structure and organization required for robust, feature-rich applications.

As my projects expanded, I repeatedly found myself refactoring the code, implementing loose coupling, and incorporating layers, interfaces, and unit tests. Drawing inspiration from Angular architecture and SOLID design principles, I developed a three-layer architecture for my app, consisting of Controllers , Services , and Providers. This three-layer pattern can be applied to a wide range of applications.

To streamline the process for future projects, I created my own base app, or starting point, called DevCoreApp. By sharing it as an open-source project, I hope it can benefit others as well.

The general structure

The typical .NET Core Web API project in Visual Studio contains a Controllers folder, Startup.cs, and Program.cs. If authentication is chosen, it creates a database model and a "Migration" folder in the same project. This is a perfect project structure to start with.

As development progresses, controllers can grow to an enormous size. They might directly call EF code, execute queries, send emails, etc. Moving reusable code to a "BaseController" that every controller can inherit from may help, but this approach could complicate providing sufficient unit testing coverage (if any). This is when the following structure comes to the rescue:

/src/Server/Database: Includes database providers. Please refer to the Database ReadMe.
/src/Server/Email: Contains email provider(s).
/src/Server/WebService: Houses the Web App project.
/src/Server/WebService/Controller: Contains controllers implementing the APIs.
/src/Server/WebService/Services: Contains services (see more about the purpose of services below).
/src/Server/WebService/Authentication: Contains authentication and authorization logic.
/src/Server/WebService/Tools: Includes a set of classes to support the framework.

Here is the high-level diagram of the server’s architecture:

Controllers

Controllers live on the frontier of the web service. Their primary function is handling web requests. Controllers are responsible for accepting HTTP requests, reading inputs (query or request body), calling the service, returning results from the service back to the caller, and handling exceptions by converting them to HTTP codes. They "consume" a service. Any logic not directly related to HTTP should be handled by a dedicated service. Typically, controllers do not need to be unit tested.

Controllers should only work with shared model types (see more about Shared Models below). They should not reference any database models or any other internal types.

The following example demonstrates the typical Web API implementation:

[HttpGet]
[Route("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status401Unauthorized)]
public ActionResult<WeatherForecastItem> GetById(string id)
{
    return HandleWebRequest((WebHandler<WeatherForecastItem>)(() =>
    {
        return Ok(Service.GetById(id));
    }));
}

The HandleWebRequest method encapsulates the error handling.

Services

A Service is a middleware component and contains all high-level logic, also known as business logic. It is the heart of the whole application and binds the controller, data access components, and other providers together. It is designed to abstract the controller from implementation details and keep the controller's code simple. In turn, the Service is protected by abstraction from details of database or other framework features implementations. The idea is that you can take a service, place it in a unit test, mock all the interfaces needed for it to operate, and it will just work without any changes.

As mentioned earlier, the Service layer should isolate controllers from exposure to database types. One of the tasks for a service is to translate between database model types and shared types.

A Service should follow the single responsibility pattern. It should not fall into the trap of satisfying the needs of a specific controller. It should have a single purpose. For instance, a "StudentService" should include functions needed to list, create, update, and delete students but have nothing to do with teachers.

Use the AppServiceAttribute to declare a service class. This attribute adds all the classes with this attribute to the dependency injection.

[AppService]
public class WeatherForecastService : BaseService
{
    ...
}

Make sure to call the AddAppServices method in Startup.cs.

...
using DevInstance.DevCoreApp.Server.WebService.Tools;

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

The following example demonstrates the typical service method implementation:

public WeatherForecastItem GetById(string id)
{
    var record = GetRecordByPublicId(id);
    return record.ToView();
}

private WeatherForecast GetRecordByPublicId(string id)
{
    var q = Repository.GetWeatherForecastQuery(AuthorizationContext.CurrentProfile).ByPublicId(id);
    var record = q.Select().FirstOrDefault();
    if (record == null)
    {
        throw new RecordNotFoundException();
    }

    return record;
}

As you can see, the example above refers to the mysterious Repository and IWeatherForecastQuery. These types come from the database provider (see more about providers below) and will be subjects of future articles.

A typical service is located in the "Services" folder of the project. It refers to the "Tools" namespace for some basic tools for service configuration. Potentially, tools and all or some of the services can be moved into a separate assembly.

Providers

A provider is responsible for low-level data handling operations, such as SQL or LINQ queries, working with files, network requests, or sending emails. Providers offer an abstraction (a set of interfaces) and should only be accessed by services via these interfaces, rather than directly. The dependency hierarchy flows from top to bottom, with the controller dependent on the service and the service dependent on the provider. As a result, providers should be the most stable components, and any changes to them should be made with extra consideration. Conversely, controllers can be updated as frequently as needed.

The sample app currently has several providers:

Identity and Authentication : A set of interfaces implementing user and password validation and management. Interface declarations and implementations reside in the "Authentication" folder of the project. Potentially, it can be moved to a separate assembly if the authentication process gets more complicated.
Email provider : A set of interfaces for composing and sending emails wrapped into a separate assembly called "EmailProcessor." There is an implementation based on MailKit.
Database providers : As mentioned above, the database provider will be the subject of a future article. For now, please see more in the Database ReadMe.

Shared Model

The shared model is a set of entities shared between the client and server. These reside in the Shared.Model assembly. In the case of a Blazor project, this assembly is used by both the Server and Client. Shared model objects are not database objects and should not be treated as such.

There is a naming convention to distinguish between different types of objects. For instance, objects like Employee that can be returned as a list, inserted, updated, or deleted should end with "Item." Objects like login parameters or registration should end with "Parameters."

In the following articles, I will dive deep into how to apply this architecture to specific use cases.