Building a Robust .NET Core Web API: A Beginner's Guide

dotnet new webapi -o MyWebApi
cd MyWebApi

MyWebApi/
├── Controllers/
├── Services/
├── Models/
├── DTOs/
├── Middleware/
├── appsettings.json
├── Program.cs
└── MyWebApi.csproj

builder.Services.AddTransient<IMyService, MyService>();

global using System;
global using System.Collections.Generic;
global using System.Linq;

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public decimal Price { get; set; }
}

public class ProductDTO
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

public class MappingProfile : Profile
{
    public MappingProfile()
    {
        CreateMap<Product, ProductDTO>();
        CreateMap<ProductDTO, Product>();
    }
}

builder.Services.AddAutoMapper(typeof(MappingProfile));

## Data Access Layer

The data access layer is responsible for interacting with the database. We'll use the Generic Repository and Unit of Work patterns to create a flexible and testable data access layer.

### Generic Repository Pattern

The Generic Repository pattern provides an abstraction over the data access logic, allowing you to easily switch between different data sources without modifying the rest of the application.

First, let's define a generic repository interface:

Next, let's create a generic repository implementation:

public GenericRepository(AppDbContext context)
{
    _context = context;
}

public async Task GetByIdAsync(int id)
{
    return await _context.Set().FindAsync(id);
}

public async Task> GetAllAsync()
{
    return await _context.Set().ToListAsync();
}

public async Task AddAsync(T entity)
{
    await _context.Set().AddAsync(entity);
    await _context.SaveChangesAsync();
    return entity;
}

public async Task UpdateAsync(T entity)
{
    _context.Set().Update(entity);
    await _context.SaveChangesAsync();
}

public async Task DeleteAsync(T entity)
{
    _context.Set().Remove(entity);
    await _context.SaveChangesAsync();
}

### Unit of Work Pattern

The Unit of Work pattern provides a way to group multiple database operations into a single transaction. This ensures that all operations are either committed or rolled back together, maintaining data consistency.

First, let's define a unit of work interface:

Then, let's create a unit of work implementation:

public UnitOfWork(AppDbContext context)
{
    _context = context;
    Products = new GenericRepository(_context);
}

public IGenericRepository Products { get; private set; }

public async Task CompleteAsync()
{
    return await _context.SaveChangesAsync();
}

public void Dispose()
{
    _context.Dispose();
}

### Base Service

Now, let's create a base service that uses the generic repository and unit of work:

public BaseService(IUnitOfWork unitOfWork, IMapper mapper)
{
    _unitOfWork = unitOfWork;
    _mapper = mapper;
}

public async Task> GetAllAsync()
{
    var entities = await _unitOfWork.Products.GetAllAsync();
    return _mapper.Map>(entities);
}

public async Task GetByIdAsync(int id)
{
    var entity = await _unitOfWork.Products.GetByIdAsync(id);
    return _mapper.Map(entity);
}

public async Task AddAsync(TDTO entity)
{
    var model = _mapper.Map(entity);
    await _unitOfWork.Products.AddAsync(model);
    await _unitOfWork.CompleteAsync();
    return entity;
}

public async Task UpdateAsync(int id, TDTO entity)
{
    var model = await _unitOfWork.Products.GetByIdAsync(id);
    _mapper.Map(entity, model);
    await _unitOfWork.CompleteAsync();
}

public async Task DeleteAsync(int id)
{
    var entity = await _unitOfWork.Products.GetByIdAsync(id);
    _unitOfWork.Products.DeleteAsync(entity);
    await _unitOfWork.CompleteAsync();
}

Install-Package Azure.Messaging.ServiceBus

Install-Package MassTransit
Install-Package MassTransit.Azure.ServiceBus.Core
Install-Package MassTransit.Newtonsoft

builder.Services.AddMassTransit(x =>
{
    x.UsingAzureServiceBus((context, cfg) =>
    {
        cfg.Host("your_service_bus_connection_string");

        cfg.ReceiveEndpoint("my_queue", e =>
        {
            e.Consumer<MyConsumer>();
        });
    });
});

public class MyMessage
{
    public string Text { get; set; }
}

public class MyConsumer : IConsumer<MyMessage>
{
    public async Task Consume(ConsumeContext<MyMessage> context)
    {
        Console.WriteLine($"Received message: {context.Message.Text}");
    }
}

public class MyService
{
    private readonly IPublishEndpoint _publishEndpoint;

    public MyService(IPublishEndpoint publishEndpoint)
    {
        _publishEndpoint = publishEndpoint;
    }

    public async Task SendMessage(string text)
    {
        await _publishEndpoint.Publish(new MyMessage { Text = text });
    }
}

## Filtering and Sorting

Filtering and sorting are essential features for any API that returns a list of data. They allow clients to easily find and order the data they need.

We'll use Sieve to implement filtering and sorting in our project.

### Sieve

Sieve is a library that provides a simple and flexible way to implement filtering, sorting, and pagination in ASP.NET Core APIs.

To configure Sieve, add the following NuGet package to your project:

Then, register Sieve in your `Program.cs` file:

To use Sieve in your API endpoints, inject the `ISieveProcessor` interface and use the `Apply` method to apply filtering and sorting to your data:

public ProductsController(ISieveProcessor sieveProcessor, IProductService productService)
{
    _sieveProcessor = sieveProcessor;
    _productService = productService;
}

[HttpGet]
public async Task Get([FromQuery] SieveModel sieveModel)
{
    var products = await _productService.GetAllAsync();
    var filteredProducts = _sieveProcessor.Apply(sieveModel, products.AsQueryable()).ToList();
    return Ok(filteredProducts);
}

This code applies filtering and sorting to the `products` collection based on the values in the `sieveModel` object.

To enable filtering and sorting for specific properties, you can use the `[Sieve]` attribute in your model classes:

Install-Package Microsoft.AspNetCore.Authentication.JwtBearer

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://your-auth-provider.com";
        options.Audience = "your-api-audience";
    });

[Authorize]
[HttpGet]
public async Task<IActionResult> Get()
{
    // Only authenticated users can access this endpoint
    return Ok();
}

## Middleware

Middleware components are executed in the request pipeline and can be used to perform various tasks, such as logging, exception handling, and authentication.

To create custom middleware, you need to create a class that implements the `IMiddleware` interface or follows a specific convention.

### Exception Handling Middleware

Exception handling middleware can be used to catch unhandled exceptions and return appropriate error responses.

Here's an example of exception handling middleware:

public ExceptionMiddleware(ILogger logger)
{
    _logger = logger;
}

public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
    try
    {
        await next(context);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "An unhandled exception occurred.");

        context.Response.StatusCode = 500;
        context.Response.ContentType = "application/json";

        var errorResponse = new
        {
            message = "An unhandled exception occurred.",
            traceId = Guid.NewGuid()
        };

        await context.Response.WriteAsync(JsonConvert.SerializeObject(errorResponse));
    }
}

To register the middleware, add the following code to your `Program.cs` file:

### Logging Middleware

Logging middleware can be used to log request and response information for debugging and monitoring.

Here's an example of logging middleware:

public LoggingMiddleware(ILogger logger)
{
    _logger = logger;
}

public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
    _logger.LogInformation($"Request: {context.Request.Method} {context.Request.Path}");

    await next(context);

    _logger.LogInformation($"Response: {context.Response.StatusCode}");
}

To register the middleware, add the following code to your `Program.cs` file:

Install-Package Microsoft.AspNetCore.Diagnostics.HealthChecks

builder.Services.AddHealthChecks();
app.UseHealthChecks("/health");

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["MyWebApi.csproj", "."]
RUN dotnet restore "./MyWebApi.csproj"
COPY . .
WORKDIR "/src/."
RUN dotnet build "MyWebApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "MyWebApi.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyWebApi.dll"]

docker build -t mywebapi .

docker run -d -p 8080:80 mywebapi

name: CI/CD

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: '6.0'
    - name: Install dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --configuration Release
    - name: Test
      run: dotnet test --configuration Release
    - name: Publish
      run: dotnet publish -c Release -o /tmp/publish
    - name: Deploy to Azure App Service
      uses: azure/webapps-deploy@v2
      with:
        app-name: your-app-name
        slot-name: production
        publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
        package: /tmp/publish

[Route("api/[controller]")]
[ApiController]
public class ProductsController : ControllerBase
{
    private readonly IProductService _productService;
    private readonly ISieveProcessor _sieveProcessor;

    public ProductsController(IProductService productService, ISieveProcessor sieveProcessor)
    {
        _productService = productService;
        _sieveProcessor = sieveProcessor;
    }

    [HttpGet]
    public async Task<IActionResult> Get([FromQuery] SieveModel sieveModel)
    {
        var products = await _productService.GetAllAsync();
        var filteredProducts = _sieveProcessor.Apply(sieveModel, products.AsQueryable()).ToList();
        return Ok(filteredProducts);
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> Get(int id)
    {
        var product = await _productService.GetByIdAsync(id);
        if (product == null)
        {
            return NotFound();
        }
        return Ok(product);
    }

    [HttpPost]
    public async Task<IActionResult> Post([FromBody] ProductDTO productDto)
    {
        var product = await _productService.AddAsync(productDto);
        return CreatedAtAction(nameof(Get), new { id = product.Id }, product);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> Put(int id, [FromBody] ProductDTO productDto)
    {
        await _productService.UpdateAsync(id, productDto);
        return NoContent();
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> Delete(int id)
    {
        await _productService.DeleteAsync(id);
        return NoContent();
    }
}

public interface IProductService : IBaseService<Product, ProductDTO>
{
}

public class ProductService : BaseService<Product, ProductDTO>, IProductService
{
    public ProductService(IUnitOfWork unitOfWork, IMapper mapper) : base(unitOfWork, mapper)
    {
    }
}