Files are an integrated part of an application. From a social app to an ERP, some form of media exists in the ecosystem. .NET Core APIs provide built-in support for uploading and fetching documents. In today's post, I will show you how to cleanly and efficiently use .NET Core's file system classes to receive file uploads.

Uploading files in ASP.NET Core API

I am creating an API with .NET 10 to accomplish our goal.

Step 1: Create a project

dotnet new webapi -n fileUploadDemo
cd fileUploadDemo

Step 2: Create a controller

using Microsoft.AspNetCore.Mvc;

namespace fileUploadDemo.Controllers;

[ApiController]
[Route("api/[controller]")]
public class FileController: ControllerBase
{
    [HttpPost("upload")]
    public async Task<IActionResult> Upload(IFormFile file)
    {
        if (file == null || file.Length == 0)
            return BadRequest("No file uploaded.");
    
        var uploadsFolder = Path.Combine(Directory.GetCurrentDirectory(), "Uploads");
    
        if (!Directory.Exists(uploadsFolder))
            Directory.CreateDirectory(uploadsFolder);
    
        var filePath = Path.Combine(uploadsFolder, file.FileName);
    
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            await file.CopyToAsync(stream);
        }
    
        return Ok(new { file.FileName, file.Length });
    }
}

The endpoint upload will save the file to the "Uploads" directory and return the filename and length.

Step 3: Configure Program.cs

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

var app = builder.Build();

app.UseStaticFiles();
app.MapControllers();

app.UseHttpsRedirection();

app.Run();

app.UseStaticFiles(); enables the app to serve static files directly over HTTP

Make sure your Uploads folder is accessible.

Step 4: Run and test

dotnet run

Hence, our file is saved:

So far, we have seen a naive, minimal approach to saving a file in an ASP.NET Core API. However, in real applications, you may split it up into layers, services, or however you prefer to structure applications.

Adding OpenApi/Swagger documentation

.NET 10 does not create OpenAPI (formerly Swagger) documentation like previous versions. So we have to add them. First, install the NuGet package:

dotnet add package Swashbuckle.AspNetCore

Next, change Program.cs:

using Microsoft.AspNetCore.Http.Features;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

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

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseStaticFiles();
app.MapControllers();
app.UseHttpsRedirection();

app.Run();

The AddOpenApi() method registers with the OpenAPI document generation services. Then AddEndpointsApiExplorer() adds an API explorer service that discovers endpoints and provides metadata about routes, parameters, and return types. Without this, Swagger would show no APIs. AddSwaggerGen() configures Swashbuckle (Swagger for .NET) and generates a Swagger document. Besides, it adds schema generation for your DTOs. UseSwagger() registers middleware to serve the Swagger JSON document. You must register middleware before using SwaggerUI. The UseSwaggerUI configures the Swagger UI web interface and navigates the UI to the JSON document. It basically adds UI elements, such as the page and Try out buttons.

Result

Restrict the file size limit

It is recommended to set a maximum file size limit for uploaded files:

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<FormOptions>(options =>
{
    options.MultipartBodyLengthLimit = 104857600; 
});

With the property MultipartBodyLengthLimit, I set the maximum size of the multipart body to 100 MBs.

Allowing formats for different file types

Each document type has a set of extensions: images are usually in JPG or PNG, and documents are usually in PDF or docx. For different purposes, we should validate the input. Like for a profile picture, users may not upload a docx or a PDF, while for a report, they should avoid JPG. To enforce it in our API, I will separate the image and document endpoints.

UploadImage specified for uploading image files:

[HttpPost("UploadImage")]
public async Task<IActionResult> UploadImageAsync(IFormFile file)
{
    if (file == null || file.Length == 0)
        return BadRequest("No file uploaded.");

    var allowedExtensions = new[] { ".jpg", ".png" };
    var extension = Path.GetExtension(file.FileName);
    
    if (!allowedExtensions.Contains(extension))
    {
        var extensionsWithoutDots = allowedExtensions.Select(ext => ext.TrimStart('.'));
        return BadRequest($"Invalid file type. Allowed types are: {string.Join(", ", extensionsWithoutDots)}");
    }
    
    var uploadsFolder = Path.Combine(Directory.GetCurrentDirectory(), "Uploads");

    if (!Directory.Exists(uploadsFolder))
        Directory.CreateDirectory(uploadsFolder);

    var filePath = Path.Combine(uploadsFolder, file.FileName);

    using (var stream = new FileStream(filePath, FileMode.Create))
    {
        await file.CopyToAsync(stream);
    }

    return Ok(new { file.FileName, file.Length });
}

UploadDocument method for uploading document files:

    [HttpPost("UploadDocument")]
    public async Task<IActionResult> UploadDocumentAsync(IFormFile file)
    {
        if (file == null || file.Length == 0)
            return BadRequest("No file uploaded.");

        var allowedExtensions = new[] { ".pdf", ".txt" };
        var extension = Path.GetExtension(file.FileName);
        
        if (!allowedExtensions.Contains(extension))
        {
            var extensionsWithoutDots = allowedExtensions.Select(ext => ext.TrimStart('.'));
            return BadRequest($"Invalid file type. Allowed types are: {string.Join(", ", extensionsWithoutDots)}");
        }
        
        var uploadsFolder = Path.Combine(Directory.GetCurrentDirectory(), "Uploads");
    
        if (!Directory.Exists(uploadsFolder))
            Directory.CreateDirectory(uploadsFolder);
    
        var filePath = Path.Combine(uploadsFolder, file.FileName);
    
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            await file.CopyToAsync(stream);
        }
    
        return Ok(new { file.FileName, file.Length });
    }

The prior method only supports JPG and PNG, while the latter supports PDF and TXT. Lets test it from SwaggerUI:

On a correct input:

If we inspect the Uploads folder, we can see the uploaded file:

While the other method:

And for the allowed document:

Renaming the file to standard naming

We have now successfully uploaded files. However, there is a problem: you may notice that file names are arbitrary and random.

For real applications, we often want to control the names of the files to avoid someone uploading a Snapchat image of themselves with a weird-looking filename. Let's fix that.

Step 1: Add model

First, introduce a model to input images. It will contain a type specifying what the file is for.

Add File type enum:

namespace fileUploadDemo.Models.Enums;

public enum FileTypeEnum
{
    ProfilePicture = 1,
    PostImage = 2,
    Resume = 3
}

File input:

using fileUploadDemo.Models.Enums;

namespace fileUploadDemo.Models.Dtos;

public class FileDtoInp
{
    public FileTypeEnum Type { get; set; }
    public IFormFile File { get; set; }
}

To return, we will use a model instead of an anonymous object:

namespace fileUploadDemo.Models.Dtos;

public class FileDto
{
    public string FileName { get; set; } = string.Empty;
    public long Length { get; set; } 
}

Step 2: Add service layer

So far, I have added everything to the controller, which is a bad practice. I'll add a service layer, but this can be implemented in whatever way you prefer.

Add a IFileService interface:

using fileUploadDemo.Models.Dtos;

namespace fileUploadDemo.Services.IServices;

public interface IFileService
{
    Task<FileDto> UploadImageAsync(FileDtoInp input);
    Task<FileDto> UploadDocumentAsync(FileDtoInp input);
}

And a FileService implementation:

using fileUploadDemo.Models.Dtos;
using fileUploadDemo.Models.Enums;
using fileUploadDemo.Services.IServices;

namespace fileUploadDemo.Services;

public class FileService: IFileService
{
    private readonly string _uploadsFolder;

    public FileService(IWebHostEnvironment env)
    {
        _uploadsFolder = Path.Combine(env.ContentRootPath, "Uploads");
    }
    public async Task<FileDto> UploadImageAsync(FileDtoInp input)
    {
        if (input.File == null || input.File.Length == 0)
            throw new Exception("No file uploaded.");
        
        var allowedExtensions = new[] { ".jpg", ".png" };
        var extension = Path.GetExtension(input.File.FileName);
        
        if (!allowedExtensions.Contains(extension))
        {
            var extensionsWithoutDots = allowedExtensions.Select(ext => ext.TrimStart('.'));
            throw new Exception($"Invalid file type. Allowed types are: {string.Join(", ", extensionsWithoutDots)}");
        }
        
        if (!Directory.Exists(_uploadsFolder))
            Directory.CreateDirectory(_uploadsFolder);

        var fileName = $"{ GetFileName(input.Type) }{extension}";
        
        var filePath = Path.Combine(_uploadsFolder, fileName);
    
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            await input.File.CopyToAsync(stream);
        }

        return new 
            FileDto()
            {
                FileName = fileName, 
                Length = input.File.Length
            };
    }

    public async Task<FileDto> UploadDocumentAsync(FileDtoInp input)
    {
        if (input.File == null || input.File.Length == 0)
            throw new Exception("No file uploaded.");

        var allowedExtensions = new[] { ".pdf", ".txt" };
        var extension = Path.GetExtension(input.File.FileName);
        
        if (!allowedExtensions.Contains(extension))
        {
            var extensionsWithoutDots = allowedExtensions.Select(ext => ext.TrimStart('.'));
            throw new Exception($"Invalid file type. Allowed types are: {string.Join(", ", extensionsWithoutDots)}");
        }
        
        if (!Directory.Exists(_uploadsFolder))
            Directory.CreateDirectory(_uploadsFolder);
    
        var fileName = $"{ GetFileName(input.Type) }{extension}";
        var filePath = Path.Combine(_uploadsFolder, fileName);
    
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            await input.File.CopyToAsync(stream);
        }

        return new 
            FileDto()
            {
                FileName = fileName, 
                Length = input.File.Length
            };
    }
    
    private string GetFileName(FileTypeEnum input)
        => input switch
        {
            FileTypeEnum.ProfilePicture => $"PRF-{DateTime.UtcNow:yyMMddHHmmss}",
            FileTypeEnum.PostImage => $"PST-{DateTime.UtcNow:yyMMddHHmmss}",
            FileTypeEnum.Resume => $"RSM-{DateTime.UtcNow:yyMMddHHmmss}",
            _ => throw new ArgumentOutOfRangeException(nameof(input), input, null)
        };
}

Let's understand what is happening here. We have methods for uploading images and documents, which first validate the file types. They actually abstracted the logic from the earlier upgrade of our application from controllers to services, which is always recommended. The main update here is the GetFileName method that returns a standardized name for each type. To make it collision-proof, I concatenated the current datetime into the name. Besides, the upload directory address is initialized in the constructor and used throughout the service. An even better way is to use it in appsettings.json and use the option pattern. Lets keep it simple for now. At last, I returned the FileDto model as output. You may also want to switch to not using exceptions for input validation, but I will leave that part up to you.

Step 3: Register the new service

builder.Services.AddScoped<IFileService, FileService>();

In Program.csI have registered the service dependency.

Step 4: Update controller

Now, the controller will inject and use the IFileService we just created:

using fileUploadDemo.Models.Dtos;
using fileUploadDemo.Services.IServices;
using Microsoft.AspNetCore.Mvc;

namespace fileUploadDemo.Controllers;

[ApiController]
[Route("api/[controller]")]
public class FileController: ControllerBase
{
    private readonly IFileService _fileService;

    public FileController(IFileService fileService)
    {
        _fileService = fileService;
    }
    
    [HttpPost("UploadImage")]
    public async Task<IActionResult> UploadImageAsync([FromForm] FileDtoInp input)
    {
        var result = await _fileService.UploadImageAsync(input);
        return Ok(result);
    }
    
    [HttpPost("UploadDocument")]
    public async Task<IActionResult> UploadDocumentAsync([FromForm] FileDtoInp input)
    {
        var result = await _fileService.UploadDocumentAsync(input);
        return Ok(result);
    }
}

[FromForm] specifies the input as form-data, not a JSON body, ensuring the endpoint receives files.

Step 4: Run and test

dotnet run

Ensure the file is named according to our standard, regardless of its original name.

The same happens with the documents:

Apart from naming files with date and time, using a unique GUID or the username is also a common practice. Consider the following ways:

var fileName = $"{ Guid.NewGuid().ToString() }{extension}";

or:

var fileName = $"{ _userContext.Username }{extension}";

Creating a GET endpoint to fetch a file

We have covered several ways to upload a file in an ASP.NET Core API. Next requirement naturally arises: how to fetch the saved file? Let's design an endpoint for it.

A new model to return the file from the service to the controller could be implemented like this:

namespace fileUploadDemo.Models.Dtos;

public class FileResultDto
{
    public byte[] Content { get; set; } = default!;
    public string ContentType { get; set; } = string.Empty;
    public string FileName { get; set; } = string.Empty;
}

Our service implementation should include a new method for fetching a file:

public async Task<FileResultDto?> GetFileAsync(string key)
{
    if (string.IsNullOrWhiteSpace(key) || key.Contains(".."))
        return null;

    var filePath = Path.Combine(_uploadsFolder, key);

    if (!System.IO.File.Exists(filePath))
        return null;

    var extension = Path.GetExtension(filePath).ToLower();

    var contentType = extension switch
    {
        ".jpg" or ".jpeg" => "image/jpeg",
        ".png" => "image/png",
        ".pdf" => "application/pdf",
        _ => "application/octet-stream"
    };

    var bytes = await System.IO.File.ReadAllBytesAsync(filePath);

    return new FileResultDto
    {
        Content = bytes,
        ContentType = contentType,
        FileName = key
    };
}

After some initial string checks and combining the filename with the directory, we check whether the file exists. In the latter part, we convert the file into a MIME type based on the extension. var bytes = await System.IO.File.ReadAllBytesAsync(filePath); loads the entire file into memory and returns byte[]. If large files are uploaded, consider streaming instead. Finally, it packs the content and metadata into the response model and returns it.

Use it in the controller:

[HttpGet("GetFile")]
public async Task<IActionResult> GetFileAsync([FromQuery] string key)
{
    var result = await _fileService.GetFileAsync(key);

    if (result == null)
        return NotFound("File not found");

    return File(result.Content, result.ContentType, result.FileName);
}

[FromQuery] will prompt for the filename as a key param and pass it to the service. Once the data is received, the endpoint will return the actual file.

Test

Simply, the user can download the file.

Tips for using file uploading in ASP.NET Core

For production environments and scalable systems, consider the following aspects.

• For the production environment, use a cloud service such as Azure Blob or AWS S3 to save files for better reliability and speed.
• Use the path in appsettings for security and good design.
• Organize upload paths into separate directories for document- and module-wise uploads. Even separating directories for users is also a common practice, such as "images/Profile", "images/Posts", "documents/Resumes" or "images/john/".
• Store metadata in a database for referencing and persistence. Creating an image-and-document table with a Type key is a great way to reference files to corresponding entities, such as User and Building, via ImageId and DocumentId. The tables can store other important information, such as file size, creation date, uploader user, file name, etc.
• If your system requires a very large file upload, use chunk uploading.
• Use file streaming for large file instead of buffer that can result in high RAM usage.
• Enable progress tracking via SignalR.

Conclusion

The long story comes to an end, and we learned how to handle files in ASP.NET Core APIs. We started with minimal code and applied best practices when using images and documents. By following these tips, you can design a file structure securely and efficiently in a production-grade system.

For developers who want to taste ORM but don't want to leave SQL either, Dapper is a perfect choice. Dapper runs SQL queries like ADO.NET but returns results as C# objects, like Entity Framework Core. Apart from its abstracting nature, you leverage high-speed data access. The feature set of Dapper is quite large and covers key areas of database work, such as JOINs, aggregate functions, database procedures and functions, transactions, etc. In today's post, I will walk through everything needed to get you started with Dapper.

What is Dapper?

Dapper is a micro-ORM (Object Relational Mapper) for .NET. Developed by Stack Overflow, Dapper offers higher performance database operations faster than full ORMs like Entity Framework Core (EF Core). It suits developers who work with ADO.NET because of its query commands, unlike EF Core, which operates on objects rather than SQL. SQL Queries are directly mapped to strongly typed objects like any ORM.

Why Use Dapper?

As Dapper is a micro-ORM that offers a thin abstraction between the database and applications, it introduces very little overhead. For these reasons, it is an optimal choice for high-performing scenarios. Similar to ADO .NET, you can get full control over SQL queries. You can think of it as the middle ground between ADO.NET and an ORM like EF Core, which uses data as strongly typed C# objects. One can view the SQL generated by EF Core, but can't granularly control it. Dapper uses minimal dependencies, keeping the architecture lightweight. That is one of the reasons Dapper best suits microservices, financial systems, web APIs, and modular APIs.

Commonly used Dapper methods

To summarize the most commonly used Dapper methods, let's go ahead and create a new project.

Step 1: Create a project

dotnet new console -n UserDapperDemo
cd UserDapperDemo

Step 2: Install the required packages

dotnet add package Dapper
dotnet add package Npgsql
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Json

Npgsql provides a NpgsqlConnection class for connecting to PostgreSQL. The Configuration* packages are useful when we create and include appsettings.json in the project.

Step 3: Create models

namespace UserDapperDemo.Models;

public class Movie
{
    public int Id { get; set; }
    public string Title { get; set; } = string.Empty;
    public int DirectorId { get; set; }
    public double Rating { get; set; }
}

namespace UserDapperDemo.Models;

public class Director
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
}

Step 4: Add appsettings.json and its configuration

{
  "ConnectionStrings": {
    "PostgresConnection": "Host=localhost;Port=5432;Database=movieDb;Username=postgres;Password=1234"
  }
}

In the .proj file add the following item group:

    <ItemGroup>
        <None Update="appsettings.json">
            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
    </ItemGroup>

Step 5: Configure connection factory

using System.Data;
using Microsoft.Extensions.Configuration;
using Npgsql;

namespace UserDapperDemo.Data;

public class DbConnectionFactory
{
    
    private readonly string _connectionString;

    public DbConnectionFactory()
    {
        
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json")
            .Build();

        _connectionString = config.GetConnectionString("PostgresConnection");
    }

    public IDbConnection CreateConnection()
        => new NpgsqlConnection(_connectionString);
}

It makes a centralized database connection point.

Step 6: Prepare the database

Run the following query for the database

CREATE TABLE IF NOT EXISTS public."Director"
(
    "Id" integer NOT NULL DEFAULT nextval('"Director_Id_seq"'::regclass),
    "Name" text COLLATE pg_catalog."default" NOT NULL,
    CONSTRAINT "Director_pkey" PRIMARY KEY ("Id")
)
CREATE TABLE IF NOT EXISTS public."Movie"
(
    "Id" integer NOT NULL DEFAULT nextval('"Movie_Id_seq"'::regclass),
    "Title" text COLLATE pg_catalog."default" NOT NULL,
    "DirectorId" integer,
    "Rating" numeric,
    CONSTRAINT "Movie_pkey" PRIMARY KEY ("Id"),
    CONSTRAINT "Movie_DirectorId_fkey" FOREIGN KEY ("DirectorId")
        REFERENCES public."Director" ("Id") MATCH SIMPLE
        ON UPDATE NO ACTION
        ON DELETE NO ACTION
)

So, our database tables look like:

Step 7: Implement Dapper methods

I will follow a repository pattern to test some of Dapper's most common methods. This is just for the sake of demoing common methods. Whether or not you want to implement repositories in your code is entirely up to you. Some people love repositories while others absolutely hate them.

The movie repository will be:

public class MovieRepo
{
    private readonly DbConnectionFactory _factory;
    public MovieRepo(DbConnectionFactory factory)
    {
        _factory = factory;
    }
    
    //methods
}
    

QueryAsync<T>()

public async Task<IEnumerable<Movie>> GetAllMoviesAsync()
{
    using var connection = _factory.CreateConnection();

    return await connection.QueryAsync<Movie>(
        "SELECT * FROM \"Movie\""
    );

QueryAsync returns multiple rows of data asynchronously. It is used when we need to fetch multiple rows of data. Its synchronous counterpart is Query<>().

QueryFirstAsync<T>()

public async Task<Movie> GetFirstMovie()
{
    using var connection = _factory.CreateConnection();

    return await connection.QueryFirstAsync<Movie>(
        "SELECT * FROM \"Movie\" ORDER BY \"Id\" LIMIT 1"
    );
}

A single row-returning operation that returns the first row that matches the given condition. It expects the record to exist, otherwise, it throws an exception. QueryFirst<T>() is for synchronous operation.

QueryFirstOrDefaultAsync<T>()

public async Task<Movie?> GetMovieByTitle(string title)
{
    using var connection = _factory.CreateConnection();

    return await connection.QueryFirstOrDefaultAsync<Movie>(
        "SELECT * FROM \"Movie\" WHERE \"Title\" = @Title",
        new { Title = title }
    );
}

As the name suggests, it returns the first row that matches the condition, or otherwise returns the default value. A similar sync method is QueryFirstOrDefault.

QuerySingleAsync<T>()

public  async Task<Movie> GetMovieById(int id)
{
    using var connection = _factory.CreateConnection();

    return await connection.QuerySingleAsync<Movie>(
        "SELECT * FROM \"Movie\" WHERE \"Id\" = @Id",
        new { Id = id }
    );
}

QuerySingleAsync or QuerySingle (sync version) expects exactly one row to match the condition. If fewer or more are found, it throws an exception. QuerySingle is ideal when filtering a record by ID, as ID does not duplicate.

QuerySingleOrDefaultAsync<T>()

public  async Task<Movie?> GetMovieSafe(int id)
{
    using var connection = _factory.CreateConnection();

    return await connection.QuerySingleOrDefaultAsync<Movie>(
        "SELECT * FROM \"Movie\" WHERE \"Id\" = @Id",
        new { Id = id }
    );
}

Returns one record matched or null. Use QuerySingleOrDefault if you want non-async.

ExecuteAsync

public  async Task<int> InsertMovie(Movie movie)
{
    using var connection = _factory.CreateConnection();

    return await connection.ExecuteAsync(
        @"INSERT INTO ""Movie"" (""Title"", ""director_id"", ""rating"")
  VALUES (@Title, @DirectorId, @Rating)",
        movie
    );
}

public async Task<int> UpdateMovieAsync(Movie movie)
{
    using var connection = _factory.CreateConnection();

    return await connection.ExecuteAsync(
        @"UPDATE ""Movie"" 
      SET ""Title"" = @Title, ""Rating"" = @Rating
      WHERE ""Id"" = @Id",
        movie
    );
}

ExecuteAsync runs the command and returns the number of rows affected. Specifically, this and its Execute methods are used for Insert, Update, and Delete operations.

ExecuteScalarAsync

public async Task<int> GetMovieCount()
{
    using var connection = _factory.CreateConnection();

    return await connection.ExecuteScalarAsync<int>(
        "SELECT COUNT(*) FROM \"Movie\""
    );
}

ExecuteScalarAsync or ExecuteScalar returns a single value as a result of SQL aggregation functions such as COUNT(), AVG(), and SUM().

QueryMultipleAsync

public async Task<(IEnumerable<Movie>, IEnumerable<Director>)> GetDashboard()
{
    using var connection = _factory.CreateConnection();

    var sql = @"
        SELECT * FROM ""Movie"";
        SELECT * FROM ""Director"";
    ";

    using var multi = await connection.QueryMultipleAsync(sql);

    var movies = multi.Read<Movie>();
    var directors = multi.Read<Director>();

    return (movies, directors);
}

The method is complex, running multiple commands from a single command. QueryMultiple is the sync version of it. Instead of hitting the database multiple times, QueryMultiple lets you fetch multiple datasets in a single round-trip.

Step 8: Set up Program.cs

using UserDapperDemo.Models;
using UserDapperDemo.Data;
using UserDapperDemo.Data.Repos;

var factory = new DbConnectionFactory();

var repo = new MovieRepo(factory);

// INSERT
repo.InsertMovie(new Movie
{
    Title = "Inception",
    DirectorId = 1,
    Rating = 9.0
});

Console.WriteLine("=== ALL MOVIES ===");
// QUERY
var movies = await repo.GetAllMoviesAsync();

foreach (var m in movies)
{
    Console.WriteLine($"Id: {m.Id}, Title: {m.Title}, Rating: {m.Rating}");
}

Console.WriteLine("\n=== SINGLE MOVIE (QueryFirst) ===");
// SINGLE
var movie1 = await repo.GetFirstMovie();

Console.WriteLine($"Id: {movie1.Id}, Title: {movie1.Title}, Rating: {movie1.Rating}");

Console.WriteLine("\n=== SINGLE MOVIE (QueryFirstOrDefault) ===");
// SINGLE
var movie2 = await repo.GetMovieByTitle("Memento");

Console.WriteLine($"Id: {movie2.Id}, Title: {movie2.Title}, Rating: {movie2.Rating}");

Console.WriteLine("\n=== SINGLE MOVIE (QuerySingle) ===");
// SINGLE
var movie3 = await repo.GetMovieById(1);

Console.WriteLine($"Id: {movie3.Id}, Title: {movie3.Title}, Rating: {movie3.Rating}");

Console.WriteLine("\n=== SINGLE MOVIE (QuerySingleOrDefault) ===");
// SINGLE
var movie4 = await repo.GetMovieSafe(1);

Console.WriteLine($"Id: {movie4.Id}, Title: {movie4.Title}, Rating: {movie4.Rating}");

Console.WriteLine("\n=== MOVIE COUNT (ExecuteScalar) ===");
// COUNT
var count = await repo.GetMovieCount();
Console.WriteLine($"Total Movies: {count}");

Console.WriteLine("\n=== DASHBOARD (QueryMultiple) ===");
// MULTIPLE
var (allMovies, directors) = await repo.GetDashboard();
foreach (var m in allMovies)
{
    Console.WriteLine($"Id: {m.Id}, Title: {m.Title}, Rating: {m.Rating}");
}

foreach (var d in directors)
{
    Console.WriteLine($"Id: {d.Id}, Name: {d.Name}");
}

Here we are using movieRepo to call all of its methods.

Step 9: Run and test

dotnet run

Advanced Dapper Features

We have seen some of the most common dapper methods till now. However, Dapper offers ways to tackle them as well for complex scenarios.

Working with transactions

When inserting or updating data, an exception in between the operation can leave the database inconsistent. Transactions rescue and atomize the data manipulation operations as one, either the whole block executes or fails and rolls back. Let's see how we can do it in Dapper.

public async Task CreateMovieWithDirector(Movie movie, string directorName)
{
    using var connection = _factory.CreateConnection();
    connection.Open();

    using var transaction = connection.BeginTransaction();

    try
    {
        var directorId = await connection.ExecuteScalarAsync<int>(
            @"INSERT INTO ""Director"" (""Name"")
          VALUES (@Name)
          RETURNING ""Id"";",
            new { Name = directorName },
            transaction
        );

        movie.DirectorId = directorId;

        await connection.ExecuteAsync(
            @"INSERT INTO ""Movie"" (""Title"", ""DirectorId"", ""Rating"")
          VALUES (@Title, @DirectorId, @Rating)",
            movie,
            transaction
        );

        transaction.Commit();
    }
    catch
    {
        transaction.Rollback();
        throw;
    }
}

I opened a transaction on the connection, then we first created the director before the movie, as the movie depends on the directorId. At last transaction.Commit() commits the transaction to write everything in the database, while the catch block rolls back the transaction using transaction.Rollback(). Note that I am using a parameterized query to keep the database safe from SQL injection attacks and unwanted data.

In Program.cs:

Console.WriteLine("\n=== Transaction ===");
await repo.CreateMovieWithDirector(
    new Movie()
    {
        Title = null,
        Rating = 9,
    },
    "Martin Scorsese"
);

I intentionally kept the title null, as per the repo method, the director will be added successfully, but during Movie creation, there is an error. The transaction will roll back the director insertion when the second half fails as well.

Upon correct values it will be done:

new Movie()
    {
        Title = "The Departed",
        Rating = 9
    },

Using Stored Procedures/Functions

Stored procedures and functions encapsulate complex logic and provide reusable calls. For such detailed operations, you should not write a raw query spanning dozens of lines in the code that can be difficult to maintain and organize. The best way is to abstract into functions or procedures. Let's consider a function

CREATE FUNCTION public.get_movies_by_director(
	p_director_id integer)
    RETURNS TABLE("Id" integer, "Title" text, "Rating" numeric) 
    LANGUAGE 'plpgsql'
    COST 100
    VOLATILE PARALLEL UNSAFE
    ROWS 1000

AS $BODY$
BEGIN
    RETURN QUERY
    SELECT m."Id", m."Title", m."Rating"
    FROM "Movie" m
    WHERE m."DirectorId" = p_director_id;
END;
$BODY$;

repo method that calls the function

public async Task<IEnumerable<Movie>> GetMoviesByDirector(int directorId)
{
    using var connection = _factory.CreateConnection();

    return await connection.QueryAsync<Movie>(
        @"SELECT * FROM get_movies_by_director(@DirectorId)",
        new { DirectorId = directorId }
    );
}

var moviesByDirector = await repo.GetMoviesByDirector(1);

foreach (var m in moviesByDirector)
{
    Console.WriteLine($"{m.Id} - {m.Title} - {m.Rating}");
}

Result:

Bulk Operations with Dapper

Bulk operations are important features supported by Dapper. When inserting a large amount of data, you do not want to hit the database separately for each record, nor should you. SQL allows bulk insertion or update at once, and you can run the query with ExecuteAsync.

public async Task BulkInsertMovies(IEnumerable<Movie> movies)
{
    using var connection = _factory.CreateConnection();

    await connection.ExecuteAsync(
        @"INSERT INTO ""Movie"" (""Title"", ""DirectorId"", ""Rating"")
          VALUES (@Title, @DirectorId, @Rating)",
        movies
    );
}

Program.cs call

await repo.BulkInsertMovies(new List<Movie>
{
    new Movie { Title = "Batman Begins", DirectorId = 1, Rating = 8.2 },
    new Movie { Title = "The Dark Knight", DirectorId = 1, Rating = 9.0 }
});

Opt between Buffered and Unbuffered Query

By default, Dapper loads everything into the buffer memory. The behavior can be problematic with large datasets, so choose unbuffered queries that stream results rather than storing them in memory.

var movies = await connection.QueryAsync<Movie>(
    sql,
    buffered: false
);

Multi-Mapping (Handling JOIN Queries)

JOINs are a common way to get data from multiple tables in SQL. That common feature is workable using Dapper as well. With the same QueryAsync you can run queries with JOIN commands.

public async Task<IEnumerable<MovieWithDirector>> GetMoviesWithDirectors()
{
    using var connection = _factory.CreateConnection();

    var sql = @"
    SELECT 
        m.""Id"", 
        m.""Title"", 
        m.""Rating"",
        d.""Name"" AS ""DirectorName""
    FROM ""Movie"" m
    JOIN ""Director"" d ON m.""DirectorId"" = d.""Id"";
";

    var result = await connection.QueryAsync<MovieWithDirector>(sql);

    return result;
}

We need a model to get the results

namespace UserDapperDemo.Models;

public class MovieWithDirector
{
    public int Id { get; set; }
    public string Title { get; set; } = string.Empty;
    public double Rating { get; set; }
    public string DirectorName { get; set; } = string.Empty;
}

Simply printing them all after calling the repo method

var moviesWithDirectors = await repo.GetMoviesWithDirectors();

foreach (var m in moviesWithDirectors)
{
    Console.WriteLine($"{m.Id} - {m.Title} - {m.Rating} by {m.DirectorName}");
}

Result

Best Practices When Using Dapper

Following some practices can make Dapper work better than usual. These ways make the application fast, maintainable, and secure.

Use Parameterized Queries

That is general advice to always use parameters to prevent SQL injection attacks. Apart from security, some special characters, such as "," and")", can cause errors when inserting or updating string values.

Prefer Async Methods

To avoid thread block and support asynchronous, go with async versions like QueryAsync and ExecuteAsync. Applications usually run different threads in parallel, preferring async methods in Dapper.

Organize SQL Queries

Good architecture makes a project maintainable. You should handle data access as well when using Dapper. Repository pattern is a preferable choice however choose as per your requirement. Keeping long queries in files will also save mess in the code.

Manage Connections Efficiently

Database connections are like portals to the database. Open and close them the right way with using statements or connection factories to ensure that connections open only once and are properly closed after each query.

Avoid Business logic in the SQL queries

Validate the inputs and other business rules before passing them to SQL queries. This avoids unnecessary checks on SQL and keeps the single responsibility in the data access layer.on SQL and keep the single responsibility on the data access layer.

Avoid checks like

CASE WHEN rating > 5 THEN 'Good' ELSE 'Bad'

It is generally good to keep the repository or other data access separate from business rules.

Cache frequently-accessed data

Database operations are always costly, try to reduce them as much as possible. Caching is one of the best ways to reduce database processing and delays. First, identify which data are most requested or don't change frequently. Set up caching and save them to provide quick access to users, rather than requesting the same data from the dataset every time.

You can follow some generic recommendations for the application apart from Dapper.

Conclusion

We rediscovered Dapper from its basic methods to its advanced features. Later, we reviewed some recommendations for using Dapper. Like any other feature, Dapper has its own world and definitions. I defined its commonly used methods and some of the advanced features. I shared a real example of how those methods and features address most database requirements. By following the tips in the article, you can scale up the use of the high-performance library.

Code: https://github.com/elmahio-blog/MovieDapperDemo.git

Pattern matching is not just condition checking. It reflects how you think as a developer. Matching and validation can be achieved in a naive, descriptive way. However, a cleaner approach stands out in terms of readability and sometimes performance. Pattern matching combines patterns to express complex logic in a single, readable line. In today's post, I will cover some advanced pattern-matching solutions that developers often miss.

Implementation of pattern-matching scenarios

To show pattern matching in code, I will start by creating a console application to test out different examples.

Step 1: Create the project

dotnet new console -n PatternMatchingDemo
cd PatternMatchingDemo

Step 2: Create records

For models, I will use records because we need value types here.

namespace PatternMatchingDemo.Records;
public record Address(string City, string Country);
public record User(string Name, int Age, Address Address, List<string> Roles);
public record Request(string Source, int Priority);
public record Point(int X, int Y);

Step 3: Define collections

To use pattern matching, we need a few collections. Defining an in-memory collection, while it will mimic any real data.

var users = new List<User>
{
    new("Ali", 25, new Address("Karachi", "Pakistan"), new List<string> { "Admin", "User" }),
    new("Sara", 17, new Address("Chicago", "United States"), new List<string> { "User" }),
    new("Kennedy", 65, new Address("London", "UK"), new List<string> { "Guest" })
};

var requests = new List<Request>
{
    new("System", 10),
    new("User", 3),
    new("System", 2)
};

Step 4: Use pattern matching for different requirements

That's it for the setup. In the next sections, I will showcase pattern matching for different requirements and purposes.

Property pattern (nested matching)

foreach (var user in users)
{
    if (user is { Address.City: "Karachi" })
    {
        Console.WriteLine($"{user.Name} is from Karachi");
    }
}

Property pattern provides a clean way to match an object's properties, even when they are nested. It helps in JSON matching and DTO validation without verbosity. A traditional way without a property pattern would be:

if (user != null && user.Address != null && user.Address.City == "Karachi" && user.Age > 18)

Pattern matching with not

foreach (var user in users)
{
    if (user is not { Address.City: "Karachi" })
    {
        Console.WriteLine($"{user.Name} is NOT from Karachi");
    }
}

This one is just the opposite of the previous pattern. It simply excludes the given condition and fetches all other records.

Matching multiple cases in one pattern

foreach (var user in users)
{
    if (user is { Address.City: "Karachi" or "Lahore" })
    {
        Console.WriteLine($"{user.Name} is from a major city");
    }
}

The same property matching can be extended to multiple cases. Well, the pattern is very much descriptive itself, referring to what it actually does.

Pattern matching inside LINQ

var adultsFromPakistan = users
    .Where(u => u is { Age: > 18, Address.Country: "Pakistan" })
    .ToList();

foreach (var user in adultsFromPakistan)
{
    Console.WriteLine($"{user.Name} is adult from Pakistan");
}

One of the most usable scenarios is pattern matching inside LINQ. It filters collections based on object shape and conditions.

Matching partial objects

foreach (var user in users)
{
    if (user is { Name: "Ali" })
    {
        Console.WriteLine("Found Ali");
    }
}

To match a condition, you don't even need to know the structure completely. As the example shows, you can check on a field as well.

Relational + logical patterns

foreach (var user in users)
{
    if (user.Age is > 18 and < 60)
    {
        Console.WriteLine($"{user.Name} is Adult");
    }
    else if (user.Age is < 18 or > 60)
    {
        Console.WriteLine($"{user.Name} is Special Age Group");
    }
}

The relational pattern has made the comparison easier to read. Rather than just mathematical logical operators, you can use readable keywords. Apart from readability, it offers applications like comparing ages, checking a threshold, or checking a range.

Switch expression

foreach (var user in users)
{
    var category = user.Age switch
    {
        < 13 => "Child",
        < 20 => "Teen",
        < 60 => "Adult",
        _ => "Senior"
    };

    Console.WriteLine($"{user.Name} => {category}");
}

A switch case is a well-known way to compare multiple conditions. It is an ideal way of handling multiple cases instead of using a cluster of else-if. If you have some complex code to execute, then the following version is workable:

foreach (var user in users)
{
    string category;
    
    // Traditional switch statement with cases
    switch (user.Age)
    {
        case < 13:
            category = "Child";
            break;
        case < 20:
            category = "Teen";
            break;
        case < 60:
            category = "Adult";
            break;
        default:
            category = "Senior";
            break;
    }
    
    Console.WriteLine($"{user.Name} => {category}");
}

Type + condition pattern

object value = 150;

if (value is int number && number > 100)
{
    Console.WriteLine("Large number (old way)");
}

if (value is int and > 100)
{
    Console.WriteLine("Large number (pattern matching way)");
}

The pattern checks type and condition simultaneously, liberating you from separate casting and checking logic. It is useful for object or dynamic data.

List pattern

int[] nums = { 1, 2, 3 };

if (nums is [1, 2, 3])
{
    Console.WriteLine("Exact match");
}

if (nums is [1, .., 3])
{
    Console.WriteLine("Starts with 1 and ends with 3");
}

List matching is available in C# 11 and later versions. You can match the array/list structure and content and validate without a loop. List patterns can be handy for validating sequences, checking API payload lists, and detecting start/end patterns.

Positional pattern

var point = new Point(10, 20);

if (point is (10, 20))
{
    Console.WriteLine("Point matched (10,20)");
}

Another value comparison pattern matches objects based on their constructor/deconstructed values. Positional patterns are ideal for value types, such as records, because their comparisons are lightweight.

Combined pattern

foreach (var user in users)
{
    if (user is
        {
            Age: > 18,
            Address.City: "Lahore",
            Roles: ["User", ..]
        })
    {
        Console.WriteLine($"{user.Name} is eligible Lahore user");
    }
}

This code combines different patterns. Actually, this is one of the most realistic scenarios in which complex objects and requirements are combined to implement different patterns.

Null pattern

User? maybeUser = null;

if (maybeUser is not null)
{
    Console.WriteLine("User exists");
}
else
{
    Console.WriteLine("User is null");
}

Null pattern is a cleaner and more readable alternative to the traditional != null. Its usage spans large applications, input checks, and condition matching.

Guard clause

number = 7;

var result = number switch
{
    int n when n % 2 == 0 => "Even",
    int n when n % 2 != 0 => "Odd",
    _ => "Unknown"
};

Console.WriteLine(result);

A guard clause allows an additional condition inside a switch case. It tackles complex branching logic and mathematical conditions, giving flexibility when patterns alone aren't enough.

Request handling

foreach (var request in requests)
{
    var response = request switch
    {
        { Source: "System", Priority: > 5 } => "Critical System Request",
        { Source: "User", Priority: <= 5 } => "Normal User Request",
        _ => "Fallback"
    };

    Console.WriteLine($"{request.Source} ({request.Priority}) => {response}");
}

Request handling is a remarkable way to implement business logic while keeping it readable within a switch statement. It has a ton of use cases, like event processing, request routing, and validating business rules.

Step 5: Run and test

dotnet run

The results are expected and correct. However, we did the job more cleanly by combining patterns as needed.

Conclusion

Pattern matching has tons of usage. From validation to condition check, it is prominent. Using the right pattern at the right place can save a lot of code. In today's post, I shared some scenarios and their pattern solutions. In real scenarios, you have to know the patterns and use a combination when needed. This is real art.

Code: https://github.com/elmahio-blog/PatternMatchingDemo.git

A database is the root of most applications. Anything displayed or any operations performed often rely on the database. So, to build a loyal client base, you have to think in terms of a database. In today's post, I will go through some key strategies you can apply to optimize your PostgreSQL database and win the performance war.

Create indexes on frequently queried columns

Index data structures allow a row to be looked up quickly without scanning the entire table.

Without Indexes:

EXPLAIN ANALYZE
SELECT *
FROM orders
WHERE customer_id = 500;

So, the execution time is 240 milliseconds.

After Index:

CREATE INDEX idx_orders_customer_id
ON orders(customer_id);

Normalize the database strategically

Normalization is a crucial step in database design to reduce anomalies and redundancy. Simply break your table into maintainable tables with logically coherent columns.

Instead of keeping role information in the user table, introduce a separate Role table and map it to User to keep data integral and non-redundant.

Keep in mind that over-normalization can also lead to performance penalties. Joining tables is more expensive than querying a single table, so you should analyze which columns should be split into new, normalized tables.

Avoid SELECT *

Fetch only the required columns from the query.

Bad query with SELECT *:

EXPLAIN ANALYZE
SELECT *
FROM orders
WHERE status = 'Completed';

Now, with selective columns, let's say I only need id and amount, so I'm fetching only those columns:

EXPLAIN ANALYZE
SELECT id, amount
FROM orders
WHERE status = 'Completed';

In this example, the execution time is identical, but it reduces I/O and memory usage, especially as the database schema becomes more complex. If the columns you select are all part of an index, PostgreSQL can return the data directly from the index without touching the heap (the actual table file). In that case, this can improve performance as well as I/O.

Order JOINs properly

Ordering JOINs properly can also affect performance. Modern PostgreSQL uses a cost-based optimizer. It analyzes table statistics to determine the most efficient join order and method regardless of the order you write them in the query. But when dealing with older versions or if settings like join_collapse_limit is set manually, this still applies.

Consider this query:

EXPLAIN ANALYZE
SELECT *
FROM orders o
JOIN customers c
ON o.customer_id = c.id
WHERE c.country = 'USA';

Now calling the customers table before:

EXPLAIN ANALYZE
SELECT *
FROM customers c
JOIN orders o
ON c.id = o.customer_id
WHERE c.country = 'USA';

The orders table has 1 million rows, while the clusters have 100k. When we fetch orders before then, we have a larger set to JOIN with customers. If we use customers first, then join with orders, fewer rows are filtered in the first stage. Filtering earlier reduces the rows participating in the join.

Use LIMIT When Exploring Data

In most cases, you will not use thousands of data points at once. Usually, you fetch a chunk of data to display at once, which is practical for UI display. Using that information, only fetch the required amount of data:

EXPLAIN ANALYZE
SELECT *
FROM orders
ORDER BY created_at DESC;

While the efficient way:

EXPLAIN ANALYZE
SELECT *
FROM orders
ORDER BY created_at DESC
LIMIT 50;

Hence, fetching limited rows saves you in all ways.

Use partial indexes

A naive way for the query would be:

EXPLAIN ANALYZE
SELECT *
FROM orders
WHERE status = 'Completed';

Creating a partial index:

CREATE INDEX idx_completed_orders
ON orders(customer_id)
WHERE status = 'Completed';

Now the same query gives:

Hence, indexing reduced the execution time to half that of the prior query. Simply create an index for frequently filtered values to speed up.

Use Proper Data Types

Each data type has its own storage size and comparison time. Columns like primary keys should be handled with care due to these differences. Ints are faster than text, so use int as the primary key column for faster comparisons.

Good advice is to use the smallest sufficient data type. For example, use bigint instead of int if you expect more than 2.1 billion rows, as changing a PK type later is a high-risk operation.

Avoid Functions on Indexed Columns

Functions on indexed columns prevent index usage:

EXPLAIN ANALYZE
SELECT *
FROM customers
WHERE LOWER(name) = 'customer 100';

Creating an index :

CREATE INDEX idx_customers_lower_name
ON customers(LOWER(name));

Now, the same query gives:

We included the function in the index. Index can now support the function.

Partition large tables

Partitioning is another healthy way to handle large data sets. It divides a table into smaller ones:

EXPLAIN ANALYZE
SELECT *
FROM orders
WHERE created_at BETWEEN '2025-01-01' AND '2025-06-30';

Create a copy table where we will use partitioning:

CREATE TABLE public.orders_partitioned(
    id          serial NOT NULL ,
    customer_id integer,
    amount      numeric,
    status      text,
    created_at  timestamp without time zone NOT NULL,
    CONSTRAINT orders_partitioned_pkey PRIMARY KEY (id, created_at)
) PARTITION BY RANGE (created_at);

Create yearly partitions:

CREATE TABLE public.orders_2024
    PARTITION OF public.orders_partitioned
    FOR VALUES FROM ('2024-01-01') TO ('2025-01-01');

CREATE TABLE public.orders_2025
    PARTITION OF public.orders_partitioned
    FOR VALUES FROM ('2025-01-01') TO ('2026-01-01');

CREATE TABLE public.orders_2026
    PARTITION OF public.orders_partitioned
    FOR VALUES FROM ('2026-01-01') TO ('2027-01-01');
    
-- Default partition — catches ANY row that doesn't fit the ranges above
CREATE TABLE public.orders_default
    PARTITION OF public.orders_partitioned
    DEFAULT;

Copy the data into our partitioned table:

INSERT INTO public.orders_partitioned SELECT * FROM public.orders;

Just to check if everything is well:

SELECT
    inhrelid::regclass AS partition
FROM pg_inherits
WHERE inhparent = 'orders_partitioned'::regclass;

We can see 4 partitions created. Now the same query after partition:

EXPLAIN ANALYZE
SELECT *
FROM orders_partitioned
WHERE created_at BETWEEN '2025-01-01' AND '2025-06-30';

Use a transaction for bulk operations.

Operations like inserting or updating multiple rows at once use transactions. Transaction groups multiple SQL operations into a single unit of work. Instead of committing after every statement, PostgreSQL commits only once at the end of the transaction:

INSERT INTO orders(customer_id, amount, status)
VALUES (1,100,'Completed');

INSERT INTO orders(customer_id, amount, status)
VALUES (2,200,'Completed');

INSERT INTO orders(customer_id, amount, status)
VALUES (3,300,'Completed');

The above one writes each row one by one. Each insertion triggers a WAL write, a disk sync, and a commit operation:

BEGIN;

INSERT INTO orders(customer_id, amount, status)
VALUES (1,100,'Completed');

INSERT INTO orders(customer_id, amount, status)
VALUES (2,200,'Completed');

INSERT INTO orders(customer_id, amount, status)
VALUES (3,300,'Completed');

COMMIT;

The transaction was completed in less than half the time. That is the only difference, with only 3 inserts. Once you scale up to more rows, this difference becomes more pronounced. transaction commits only once, awakening the expensive operations once for all the rows.

Avoid Long-Running Transactions

Long-running transactions keep old row versions alive underp PostgreSQL's MVCC. This prevents VACUUM from cleaning dead rows, causing table bloat:

BEGIN;

SELECT *
FROM orders;

COMMIT;

BEGIN;

UPDATE orders
SET status = 'Completed'
WHERE id = 100;

COMMIT;

Short, focused transactions don't last as long as the first one in our example did. Besides, VACUUM can reclaim space and shorter transactions lower lock contention.

Clean the table and index bloats

Postgres table bloat occurs when a table contains dead rows that are no longer visible to any transaction but still occupy disk space. Postgres DELETE or UPDATE Operations create dead rows in the tables they modify. For example, if we run the following on an order row with a 400 amount:

UPDATE orders
SET amount = 1000
WHERE id = 55;

Postgres keeps the older row but marks it as dead, and adds a new one. That means the deleted row will be there along with the new one. Such dead rows pile up, overwhelming the storage. PostgreSQL provides VACUUM to reclaim or reuse the storage.

Index bloat occurs when indexes contain references to dead rows that still occupy space. Every update also updates indexes, so PostgreSQL keeps dead row indexes.

Bloated tables and indexes can significantly slow down queries and unnecessarily consume additional disk space, pressuring I/O.

We can simply fix table bloat manually:

VACUUM orders;

This reclaims storage occupied by dead rows and ensures that the space can be reused:

VACUUM FULL orders;

The above is an intensive counterpart that reclaims all storage occupied by dead rows, including the space at the end of the table. Be aware that a full vacuum will block all reads and writes to that table until it finishes. For large datasets, this can cause hours of downtime.

Usually, an AUTOVACUUM is by default enabled, which we can check

SHOW autovacuum;

You can configure the auto vacuum. Make sure it remains on, otherwise, leaving dead rows can eat up space, which is dangerous for the production database. You can simply do it by running:

ALTER SYSTEM SET autovacuum = 'on';
SELECT pg_reload_conf();

How often should it run:

-- Set the naptime to 30 seconds for more aggressive cleanup
ALTER SYSTEM SET autovacuum_naptime = '30s';
-- Reload the configuration to apply changes without restarting the service
SELECT pg_reload_conf();

When vacuum triggers:

autovacuum_vacuum_threshold = 50
autovacuum_vacuum_scale_factor = 0.2

The above configuration means running the vacuum when the number of dead rows exceeds 50 and when 20% of the table size is reached.

Apply changes by running:

SELECT pg_reload_conf();

For a table level:

ALTER TABLE orders
SET (
    autovacuum_vacuum_threshold = 50
    autovacuum_vacuum_scale_factor = 0.2
);

To view how much storage your tables are taking, run:

SELECT
    relname,
    pg_size_pretty(pg_total_relation_size(relid)) AS total_size
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

Conclusion

As a popular database choice for scalable applications, PostgreSQL requires several performance optimization techniques to keep the system fast. In this post, I presented the 12 most insightful ways to speed up your database. From indexing and partitioning to projection and handling bloat. I shared them in detail and explained how to implement them.

We know that every Entity Framework Core (EF Core) LINQ query has a corresponding SQL query. That equivalent SQL is actually executed under the hood. Some LINQ expressions involve. NET-specific code, such as calling a method, using a reflection filter, or accessing files. You may have found several code blocks of your query that could not be translated. Why does it happen? In today's post, I will cover the reasons along with on-ground examples.

LINQ Queries Translation

We will write different LINQ queries in a real project and examine what results they yield. I will use a Console application with a PostgreSQL database as an example.

Step 1: Create a project

dotnet new console -n EfTranslationDemo
cd EfTranslationDemo

Step 2: Install NuGet packages

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

Step 3: Model for the table

This will be a single-table application consisting of the Perfume model.

public class Perfume
{
    public int Id { get; set; }

    public string Name { get; set; } = string.Empty;

    public string Brand { get; set; } = string.Empty;

    public decimal Price { get; set; }

    public int Rating { get; set; }

    public DateTime ReleaseDate { get; set; }
}

Step 4: Create a database

To speed up the process, I have already created the database and the Perfumes table.

CREATE DATABASE perfumedb;

CREATE TABLE public."Perfumes" (
    "Id" serial PRIMARY KEY,
    "Name" varchar(255) NOT NULL DEFAULT '',
    "Brand" varchar(255) NOT NULL DEFAULT '',
    "Price" decimal(10,2) NOT NULL,
    "Rating" integer NOT NULL,
    "ReleaseDate" timestamp NOT NULL DEFAULT (NOW() AT TIME ZONE 'UTC')
);

Step 5: Set up the DB context

using EfTranslationDemo.Models;
using Microsoft.EntityFrameworkCore;

namespace EfTranslationDemo.Data;

public class ApplicationDbContext: DbContext
{
    public DbSet<Perfume> Perfumes => Set<Perfume>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        options
            .UseNpgsql("Your Connection string with db name perfumedb")
            .LogTo(Console.WriteLine);
    }
}

Step 6: Seed data

To begin with, I will seed some data programmatically.

using EfTranslationDemo.Data;
using EfTranslationDemo.Models;
using Microsoft.EntityFrameworkCore;

using var context = new ApplicationDbContext();

context.Database.EnsureCreated();

SeedData(context);

static void SeedData(ApplicationDbContext context)
{
    if (context.Perfumes.Any())
        return;

    context.Perfumes.AddRange(
        new Perfume { Name="Sauvage", Brand="Dior", Price=120, Rating=9, ReleaseDate=new DateTime(2018,1,1,0,0,0, DateTimeKind.Utc)},
        new Perfume { Name="Bleu De Chanel", Brand="Chanel", Price=150, Rating=10, ReleaseDate=new DateTime(2017,1,1,0,0,0, DateTimeKind.Utc)},
        new Perfume { Name="Aventus", Brand="Creed", Price=300, Rating=10, ReleaseDate=new DateTime(2015,1,1,0,0,0, DateTimeKind.Utc)},
        new Perfume { Name="F Black", Brand="Ferragamo", Price=60, Rating=7, ReleaseDate=new DateTime(2019,1,1,0,0,0, DateTimeKind.Utc)}
    );

    context.SaveChanges();
}

Fast forward, the data is seeded to the database

Step 7: LINQ queries testing

1. Query with price filter

A simple query to fetch perfumes with a price of more than 100.

Console.WriteLine("Full translable");
var query1 = context
    .Perfumes
    .Where(p => p.Price > 100)
    .Select(p => new { p.Name, p.Price });

Console.WriteLine(query1.ToQueryString());

2. Filter with Name

We will filter the data with the name starting with 'B'.

var query2 = context
    .Perfumes
    .Where(p => p.Name.StartsWith("B"));

Console.WriteLine(query2.ToQueryString());

StartsWith() translates to SQL's LIKE . Similarly, EndsWith and Contains are also translated.

3. Client Side Execution

Another translatable but performance-heavy solution is

var perfumes = context
    .Perfumes
    .ToList()
    .Where(p => p.Price > 100);

Console.WriteLine(perfumes.Count());

It loads all the data in memory first, then applies a filter on the stored data. Such a solution can cause significant problems, especially when the data is large.

4. External list filter

We can write a translatable filter with an external list

var brands = new List<string> { "Dior", "Creed" };

var query = context
    .Perfumes
    .Where(p => brands.Contains(p.Brand));

Console.WriteLine(query.ToQueryString());

EF Core converts the C# in-memory list into SQL constants.

5. DateTime filter

Any filter with parsing datetime will work the same as any other.

var query = context
    .Perfumes
    .Where(p => p.ReleaseDate.Year > 2016);

Console.WriteLine(query.ToQueryString());

Common DateTime properties are supported.

6. Custom method filter

What you cannot do in a LINQ query is to filter by a method. LINQ can't find an SQL equivalent of it.

static bool IsLuxury(Perfume perfume)
{
    return perfume.Price > 200;
}

var query = context
    .Perfumes
    .Where(p => IsLuxury(p));

Console.WriteLine(query.ToQueryString());

EF Core cannot inspect the body of arbitrary C# methods.

7. Regex matching

We can simply put a regex pattern in the filter as well.

var query = context
    .Perfumes
    .Where(p => Regex.IsMatch(p.Name, "^A"));

Console.WriteLine(query.ToQueryString());

var result = query.ToList();
Console.WriteLine(result.Count());

8. Non-Translatable Projection

string GetCategory(decimal price)
{
    return price > 150 ? "Luxury" : "Regular";
}

var query = context
    .Perfumes
    .Select(p => new
    {
        p.Name,
        Category = GetCategory(p.Price)
    });

Console.WriteLine(query.ToQueryString());

The right way

var query = context
    .Perfumes
    .Select(p => new
    {
        p.Name,
        Category = p.Price > 150 ? "Luxury" : "Regular"
    });

Console.WriteLine(query.ToQueryString());

9. Reflection

.NET does not have an equivalent in SQL.

var query = context
    .Perfumes
    .Where(p => p.GetType().GetProperty("Price") != null);

Console.WriteLine(query.ToQueryString());

10. File System Access

var query = context
    .Perfumes
    .Where(p => File.Exists($"brands/{p.Brand}.txt"));

Console.WriteLine(query.ToQueryString());

11. Random number generation

var query = context
    .Perfumes
    .Where(p => Random.Shared.Next(0, 10) > 5);

Console.WriteLine(query.ToQueryString());

A filter using random number generation did not translate.

12. string.Compare method

One of the cool methods that we often use for string comparison is string.Comparison. Unfortunately, you cannot use it in a LINQ query.

var query = context
    .Perfumes
    .Where(p => 
        string.Compare(p.Name, "Sauvage", 
            StringComparison.OrdinalIgnoreCase) == 0
        );
var result  = await query.ToListAsync();
Console.WriteLine(query.ToQueryString());

Why does EF Core have limitations in translating LINQ queries?

One question arises that even after years of improvement and enhancement, EF Core does not translate some common C# expressions in LINQ. Actually, LINQ does not merely read and execute any query. It first creates an expression tree of the query. Next, these trees are converted to SQL. SQL queries are a declarative language that describes what data you want, not how to compute it step by step. So, methods' bodies are not parsed, as in our case with the IsLuxury method, where expressions do not analyze arbitrary method bodies for translation. Also, C# is a full programming language, whereas SQL lacks many of the features of a programming language. Neither can it read its logic, as SQL servers cannot execute .NET runtime code.

EF Core is responsible for translating an expression tree to database-specific SQL. We know that every database has its own SQL dialect. For example, DATE_PART('year', column) in a PostgreSQL expression, while the SQL Server equivalent is YEAR(column). So EF must maintain different translators for each database. It does not rely on a single translator, so there are limitations in translating each and every query across diverse database providers. Finally, some .NET runtime features are specific to the program, such as random number generation, ordinal string comparison, and reflection, which are impossible to translate.

Conclusion

EF Core is a popular ORM and the default choice for many developers for database operations. EF Core uses LINQ for querying and enables you to use databases as if they were in C#. However, the underlying database cannot fully replicate a complete programming language like C#. Many programming expressions and filtering logic cannot be translated into a database query. Calling a method in a LINQ query, using reflection, and ordinal string comparison are examples of limitations in EF Core. SQL is specifically designed to fetch data and is not a programming language. It does not have the .NET runtime, so it cannot execute .NET features. In this post, I have gone through many examples that can be translated into SQL and some common queries that cannot.

Code: https://github.com/elmahio-blog/EfTranslationDemo.git

Entity Framework Core (EF Core) is working fine in your project. But the moment you use views, the migration gets messy. As a developer, I know any problem in the migration is haunting. You have to update and take care of other migrations so they don't get disturbed. If not done well, database views can throw you into a pitfall. In today's post, I will walk through how to map views in EF Core without breaking migrations.

What is a database view?

A view is a named query that acts as a virtual table. It is defined using base tables or previously defined views and provides an abstraction of a complex query. Views do not store any data, but they execute the enclosed query. Views reduce client-side code by encapsulating logic and adding reusability. Although it supports data modifications like create and update in some cases, it is primarily used for read-only operations.

Mapping database views with EF Core

Let's see, with the glasses from the actual project, how we can utilize views. I will use a console project with a PostgreSQL database.

Step 1: Create the project

dotnet new console -n EfCoreViewDemo
cd EfCoreViewDemo

Step 2: Install necessary NuGet packages

dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Json

Configuration packages will be used to load appsettings.

Step 3: Create appsettings.json

Adding appsettings.json with a database connection string.

{
  "ConnectionStrings": {
    "PostgresConnection": "Host=localhost;Port=5432;Database=productVDb;Username=postgres;Password=1234"
  }
}

Step 4: Define Models

Add the Product class:

namespace EfCoreViewDemo.Models;
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

The ProductSummary class will catch the results of the view:

namespace EfCoreViewDemo.Models;

public class ProductSummary
{
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

Step 5: Configure DbContext

using EfCoreViewDemo.Models;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace EfCoreViewDemo.Data;

public class ApplicationDbContext: DbContext
{
    public DbSet<Product> Products => Set<Product>();
    public DbSet<ProductSummary> ProductSummaries => Set<ProductSummary>();

    private readonly string _connectionString;

    public ApplicationDbContext()
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json")
            .Build();

        _connectionString = config.GetConnectionString("PostgresConnection");
    }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseNpgsql(_connectionString);
    }
    
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<ProductSummary>()
            .ToView("vw_product_summary")   
            .HasNoKey();                  
    }
}

One important configuration is ToView(...) that specifies the DbSet map as a database view. Calling ProductSummaries will fetch data from the view named vw_product_summary. HasNoKey() specifies that views are read-only structures in the database and do not contain any primary key. If not specified, EF Core expects a primary key on the entity and throws an exception.

Step 6:  Set up appsettings.json in the project

By default, a console app will expect the file in the bin directory. To read newly added appsettings from the root directory, add the following inside the <Project> tag of the application's project file:

<ItemGroup>
  <None Update="appsettings.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

Step 7: Run migrations

dotnet ef migrations add InitialCreate

So the migration will look like

using Microsoft.EntityFrameworkCore.Migrations;
using Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;

#nullable disable

namespace EfCoreViewDemo.Migrations
{
    /// <inheritdoc />
    public partial class InitialCreate : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.CreateTable(
                name: "Products",
                columns: table => new
                {
                    Id = table.Column<int>(type: "integer", nullable: false)
                        .Annotation("Npgsql:ValueGenerationStrategy", NpgsqlValueGenerationStrategy.IdentityByDefaultColumn),
                    Name = table.Column<string>(type: "text", nullable: false),
                    Price = table.Column<decimal>(type: "numeric", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_Products", x => x.Id);
                });            
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropTable(
                name: "Products");
        }
    }
}

But we skipped views from EF Core's tracking, so we need to add it manually in the Up method.

migrationBuilder.Sql(@"
  CREATE VIEW vw_product_summary AS
  SELECT ""Name"", ""Price""
  FROM ""Products"";
");

While in the Down method:

migrationBuilder
    .Sql(@"DROP VIEW IF EXISTS vw_product_summary;");

To reflect the migration

dotnet ef database update

Now, the database looks like

Step 8: Define program

using EfCoreViewDemo.Data;
using EfCoreViewDemo.Models;

using var context = new ApplicationDbContext();

context.Products.Add(new Product { Name = "Laptop", Price = 1000 });
context.Products.Add(new Product { Name = "Keyboard", Price = 100 });
context.Products.Add(new Product { Name = "Headphone", Price = 150 });
context.Products.Add(new Product { Name = "Web cam", Price = 200 });
context.Products.Add(new Product { Name = "Mouse", Price = 50 });

context.SaveChanges();

var summaries = context.ProductSummaries.ToList();

foreach (var item in summaries)
{
    Console.WriteLine($"{item.Name} - {item.Price}");
}

To summarize, I added 5 records manually. Later, I am calling ProductSummaries, which is a view.

Step 9: Run the project

Manual migration allows you to automate view definition without breaking migration functionality. A naive approach is to write views directly in the database.

Step 10: Update the view

Let's say a requirement came, and we need to update the view.

Create an empty migration:

dotnet ef migrations add UpdateProductSummaryView

Manual query in migration will look like this:

using Microsoft.EntityFrameworkCore.Migrations;

#nullable disable

namespace EfCoreViewDemo.Migrations
{
    /// <inheritdoc />
    public partial class UpdateProductSummaryView : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.Sql(@"
                DROP VIEW IF EXISTS vw_product_summary;

                CREATE VIEW vw_product_summary AS
                SELECT ""Name"", ""Price"", ""Price"" * 0.9 AS ""DiscountedPrice""
                FROM ""Products"";
            ");
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.Sql(@"
                DROP VIEW IF EXISTS vw_product_summary;

                CREATE VIEW vw_product_summary AS
                SELECT ""Name"", ""Price""
                FROM ""Products"";
            ");
        }
    }
}

Updating the model accordingly:

namespace EfCoreViewDemo.Models;

public class ProductSummary
{
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public decimal DiscountedPrice { get; set; }
}

In Program.cs, the view call will become:

var summaries = context.ProductSummaries.ToList();

foreach (var item in summaries)
{
    Console.WriteLine($"{item.Name} - {item.Price} - {item.DiscountedPrice}");
}

Hence, the result

Conclusion

Database Views are great for enclosing complex logic as virtual tables. Developers often use it extensively in the application. However, views can make EF Core migration tracking tedious if not managed properly. I provided a solution in today's blog on how you can design views without harming migration.

Code: https://github.com/elmahio-blog/EfCoreViewDemo.git

What really happens when you write throw new Exception() in .NET? Microsoft guidelines state that

When a member throws an exception, its performance can be orders of magnitude slower. 

It's not just a simple jump to a catch block, but a lot goes in CLR (Common Language Runtime). Expensive operations such as stack trace capture, heap allocations, and method unwinding occur each time. You will not want to use them in any hot paths. Today, In today's post, I will help you decide when exceptions are appropriate and when a simple alternative type might be better.

What is an Exception?

An exception is an error condition or unexpected behaviour during the execution of a program. Exceptions can occur at runtime for various reasons, such as accessing a null object, dividing by zero, or requesting a file that is not found. A C# exception contains several properties, including a Message describing the cause of the exception. StackTrace contains the sequence of method calls that led to the exception in reverse call order to trace the exception source.

How does an exception work?

The try block encloses the code prone to exceptions. try/catch protects the application from blowing up. Use the throw keyword to signal the error and throw an Exception object containing detailed information, such as a message and a stack trace. The caught exception allows the program to continue gracefully and notify the user where and what error occurred. When an error occurs, the CLR searches for a compatible catch block in the current method. If not found, it moves up the call stack to the calling method, and so on. Once a matching catch is found based on the exception type, control jumps to that block. In an unhandled exception situation where no compatible catch block is found, the application can terminate. Exception handling uses a heap to store the message. To look for a catch body, the CLR unwinds the stack by removing intermediate stack frames. The JIT must generate EH tables and add hidden control-flow metadata.

What is OneOf<T> in .NET?

OneOf<T> or OneOf<T1, T2, T...> represents a discriminated union containing all possible returns of an operation or a method. It contains an array of types, allowing a method to return one of several defined possibilities. The OneOf pattern provides you with fine-grained control and type safety.

Examine Exceptions with the benchmark.

To truly understand it, let's create an application. I will use a console application.

Step 1: Create the project

dotnet new console -n ExceptionBenchmark
cd ExceptionBenchmark

Step 2: Add necessary packages

I am adding the Benchmark library along with OneOf, which is used for the OneOf return type.

dotnet add package BenchmarkDotNet
dotnet add package OneOf

Step 3: Set up the program.cs

All the code is in the Program.cs

using System;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
using OneOf;

BenchmarkRunner.Run<ExceptionBenchmarks>();

[MemoryDiagnoser] 
public class ExceptionBenchmarks
{
    private const int Iterations = 100_000;
    private const int FailureEvery = 10;

    [Benchmark]
    public int NoException()
    {
        int failures = 0;

        for (int i = 1; i <= Iterations; i++)
        {
            if (!DoWork_NoException(i))
                failures++;
        }

        return failures;
    }

    private bool DoWork_NoException(int i)
    {
        return i % FailureEvery != 0;
    }

    [Benchmark]
    public int WithException()
    {
        int failures = 0;

        for (int i = 1; i <= Iterations; i++)
        {
            try
            {
                DoWork_WithException(i);
            }
            catch
            {
                failures++;
            }
        }

        return failures;
    }

    private void DoWork_WithException(int i)
    {
        if (i % FailureEvery == 0)
            throw new InvalidOperationException();
    }

    [Benchmark]
    public int WithOneOf()
    {
        int failures = 0;

        for (int i = 1; i <= Iterations; i++)
        {
            var result = DoWork_WithOneOf(i);

            if (result.IsT1)
                failures++;
        }

        return failures;
    }

    private OneOf<Success, Error> DoWork_WithOneOf(int i)
    {
        if (i % FailureEvery == 0)
            return new Error("Error");

        return new Success("Passed");
    }

    private readonly struct Success
    {
        public string Message { get; }

        public Success(string message)
        {
            Message = message;
        }
    }

    private readonly struct Error
    {
        public string Message { get; }

        public Error(string message)
        {
            Message = message;
        }
    }
}

The first method is simple with no exception. Then it throws an exception, and in subsequent methods, it finally returns an error object from OneOf. To make it realistic, each method will observe with 10% error and 90% success rate, as FailureEvery is set to 10. Success and Error are value types to avoid allocations, since they only return the value from the method.

Step 4: Run and test

dotnet run -c Release

The best performer is the NoException. But that is not practical, you have to identify unexpected behaviour and report it in the code flow. Firstly, a naive approach is to use an exception. Using it adds a time cost and increases the Garbage collector's Gen 0 pressure. So, our alternative to exception is OneOf, which significantly saved time and memory. We can further add Objects to the OneOf, considering the possible return values of the method.

In exceptions, Stack tracing is very expensive, as it propagates stacks, captures method names, stores IL offsets, and inspects frames. Also, the JIT inlining is limited during exceptions. With OneOfI used a struct value type, so Gen 0 utilization is minimized. Neither does it fall for stack trace nor unwind it. Hence, the execution remains linear.

When can I use an exception alternative?

In the following cases, exceptions can be replaced with Result or OneOf in normal application flows.

• Business rule rejection, such as the customers cannot order out-of-stock items. You can return an error in response.
• API validation, where you can simply return 400 with a custom message after figuring out all possible error cases.
• High-throughput paths where you cannot afford an exception mechanism.
• Validation failure, such as invalid email or mobile number input.
• Data not found scenarios where you know either the request data will be available or will not be found. Simply, you can deal with both cases.

When is an exception the optimal choice?

You don't remove fire alarms from a building because they're loud. You just don't pull them every time someone burns toast. We have some situations where exceptions stand out even if they are expensive.

• Exceptions occur when the program falls into an impossible state, such as when a null database connection is used. You cannot proceed anywhere because the connection is not even initialized for some reason.
• For environmental failures, you will opt for exceptions such as timeout failures, disk I/O failures, or database connection losses.
• Programming bugs where your code falls into a dead end, and it cannot handle further. Conditions where your input case exhaust, such as you have order statuses of pending, cancelled, and confirmed, are enumerated with 1,2 and 3, respectively. There is no case apart from that, so you can simply throw an ArgumentOutOfRangeException or a custom exception in the default case.
• If developing a library, use an exception to signal to the user what went wrong and halt normal execution. Here, you cannot force consumers to handle result types.

Conclusion

In high-performance systems, every allocation matters. Exceptions aim to provide a safeguard against anomalous conditions, but they can sometimes be a burden on memory and CPU. I put light on the exception of how much resource they can use for simple operations compared to their counterparts. We explored where it is suitable and where it can be replaced. In short, use exceptions for Unexpected, impossible, and environmental failures. While you can simply use Result/OneOf As an alternative, when conditions are expected, it is useful for business validation, user-driven errors, and high-frequency failures.

Code: https://github.com/elmahio-blog/ExceptionBenchmarks.git

APIs are the engine of modern applications. Your product belongs to any domain, either medical, banking, or IoT, APIs are most probable bricks in it. Good, maintainable, and reusable code promises a functional system. While a bad one makes maintenance and testing tedious. There is so much to care about in your application. In today's post, I will dig into writing a clean controller that fulfils the Single Responsibility Principle. We will see why exposing any business logic can harm the application and what exactly a controller should include.

Example with Fat Controller (bad design)

Consider the following ASP.NET Core controller implementation:

using System;
using Microsoft.AspNetCore.Mvc;

namespace EcCommerce.Controllers;

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly ApplicationDbContext _context;

    public OrdersController(ApplicationDbContext context)
    {
        _context = context;
    }
        
    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        var user = await _context.Users
            .Include(u => u.Orders)
            .FirstOrDefaultAsync(u => u.Id == request.UserId);
    
        if (user == null)
            return NotFound("User not found");
    
        if (!user.IsActive)
            return BadRequest("User is not active");
    
        if (request.TotalAmount <= 0)
            return BadRequest("Invalid order amount");
    
        var todayOrdersCount = user.Orders
            .Count(o => o.CreatedAt.Date == DateTime.UtcNow.Date);
    
        if (todayOrdersCount >= 5)
            return BadRequest("Daily order limit exceeded");
    
        var order = new Order
        {
            UserId = user.Id,
            TotalAmount = request.TotalAmount,
            CreatedAt = DateTime.UtcNow
        };
    
        _context.Orders.Add(order);
        await _context.SaveChangesAsync();
    
        return Ok(order);
    }
}

The first thing in the code is that it is piercing to the eyes. Also, the controller knows too much of business logic and is really fat. If any business logic changes are required, we need to update the controller. Let's say we have to increase the daily order limit from 5 to 50, then we will need to update it here. Testing is difficult too, any test, even for business logic, will be done on the controller. All of that violates the DRY (Don't Repeat Yourself) and Single Responsibility Principles, as the controller is not inherently dedicated to these tasks. The example may look like I have added too much logic here, which people usually avoid, but you still need to be clear about exactly what the controllers should have. Many developers get confused and write a few lines of business logic where they shouldn't. The controllers should handle HTTP requests, validate the mapping, and return responses.

Business Rules Don't Leak Into Controllers

So, correcting the faulty controller here.

Step 1: Create a Domain Service

public interface IOrderService
{
    Task<Order> CreateOrderAsync(int userId, decimal totalAmount);
}

A very good way to encapsulate business logic is to introduce a service layer with an interface and its implementation, and inject them into the controller.

Step 2: Implementation of the domain service

public class OrderService : IOrderService
{
    private readonly ApplicationDbContext _context;

    public OrderService(ApplicationDbContext context)
    {
        _context = context;
    }

    public async Task<Order> CreateOrderAsync(int userId, decimal totalAmount)
    {
        var user = await _context.Users
            .Include(u => u.Orders)
            .FirstOrDefaultAsync(u => u.Id == userId);

        if (user == null)
            throw new Exception("User not found");

        if (!user.IsActive)
            throw new Exception("User is not active");

        if (totalAmount <= 0)
            throw new Exception("Invalid order amount");

        var todayOrdersCount = user.Orders
            .Count(o => o.CreatedAt.Date == DateTime.UtcNow.Date);

        if (todayOrdersCount >= 5)
            throw new Exception("Daily order limit exceeded");

        var order = new Order
        {
            UserId = user.Id,
            TotalAmount = totalAmount,
            CreatedAt = DateTime.UtcNow
        };

        _context.Orders.Add(order);
        await _context.SaveChangesAsync();

        return order;
    }
}

Sometimes, you can add a repository layer below the services and inject it instead of using ApplicationDbContext directly.

Step 3: Thin Controller

using System;
using Microsoft.AspNetCore.Mvc;

namespace EcCommerce.Controllers;

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IOrderService _orderService;

    public OrdersController(IOrderService orderService)
    {
        _orderService = orderService;
    }
        
    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
      
        var order = await _orderService
            .CreateOrderAsync(request.UserId, request.TotalAmount);
    
        return Ok(order);
    }
}

Now, we have a soothing code. Not to forget dependency injection in your Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Other injections

builder.Services.AddScoped<IOrderService, OrderService>();

Clean Architecture Style (Domain-Driven)

One more way you can deal is to define the logic in the domain itself.

User Model

public class User
{
    public bool IsActive { get; private set; }
    public List<Order> Orders { get; private set; } = new();

    public void CanPlaceOrder(decimal totalAmount)
    {
        if (!IsActive)
            throw new Exception("User is not active");

        if (totalAmount <= 0)
            throw new Exception("Invalid order amount");

        var todayOrders = Orders
            .Count(o => o.CreatedAt.Date == DateTime.UtcNow.Date);

        if (todayOrders >= 5)
            throw new Exception("Daily limit exceeded");
    }
}

Service

public class OrderService : IOrderService
{
    private readonly ApplicationDbContext _context;

    public OrderService(ApplicationDbContext context)
    {
        _context = context;
    }
    
    public async Task<Order> CreateOrderAsync(int userId, decimal totalAmount)
    {
        var user = await _context.Users
            .Include(u => u.Orders)
            .FirstOrDefaultAsync(u => u.Id == userId);
    
        if (user == null)
            throw new Exception("User not found");
    
        user.CanPlaceOrder(totalAmount);
    
        var order = new Order(userId, totalAmount);
    
        _context.Orders.Add(order);
        await _context.SaveChangesAsync();
    
        return order;
    }
}

Dependency injection

var builder = WebApplication.CreateBuilder(args);

// Other injections

builder.Services.AddScoped<IOrderService, OrderService>();

Now the service becomes cleaner. In our corrected versions, we addressed all issues seen in the first code. If a new requirement asks to change the daily limit, we will go to the service or the domain model in a later example, and the controller will remain unaffected in both cases. Testing units are also made easy with the exposed method in the service. If any endpoint requires similar CreateOrder operations, then we can simply use it from OrderService, complying with the DRY principle. Our controller is now clean, and it adheres to the Single Responsibility Principle. The controller can only focus on validating requests and generating responses, while other tasks are handled in the underlying layers.

Conclusion

API controllers are responsible for exposing endpoints that your clients extensively rely on. They should validate the request, call the underlying layer like the service layer, and return the data. Keeping things in their place can help a lot with testing and maintenance, especially if your code is considerably large. One overlooked aspect is understanding exactly what a controller should contain. People often mistakenly add logic inside the controller method and fail to identify where to draw the line. I made it easy with this article and showed what potential problems can arise if business logic leaks inside the controller.

If you design an application with a data source, the repository pattern often comes to mind as a prominent choice. In fact, many developers see it as the default choice. However, the pattern is not helping every time. In this post, I will pinpoint some cases where the repository pattern is not the best choice.

What is a repository pattern?

The repository pattern is a design pattern that acts as an intermediate layer between data access and business logic. It abstracts the data source and implements the details, providing a clean representation of data manipulation as objects and lists.

Let us start by looking at how a repository pattern can be implemented with EF Core.

Start by adding a new model named Movie:

public class Movie
{
    public Guid Id { get; set; }
    public string Title { get; set; } = string.Empty;
    public string Director { get; set; } = string.Empty;
    public int ReleaseYear { get; set; }
    public double ImdbRating { get; set; }
    public DateTime CreatedAtUtc { get; set; } = DateTime.UtcNow;
}

Next, add a IMovieRepository interface with the basic methods for adding, getting, and saving movies:

public interface IMovieRepository
{
    Task AddAsync(Movie movie);
    Task<Movie?> GetByIdAsync(Guid id);
    Task<List<Movie>> GetTopRatedAsync(double minRating);
    Task SaveChangesAsync();
}

Add an implementation of that interface using EF Core:

public class MovieRepository : IMovieRepository
{
    private readonly AppDbContext _context;

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

    public async Task AddAsync(Movie movie)
    {
        await _context.Movies.AddAsync(movie);
    }

    public async Task<Movie?> GetByIdAsync(Guid id)
    {
        return await _context.Movies.FindAsync(id);
    }

    public async Task<List<Movie>> GetTopRatedAsync(double minRating)
    {
        return await _context.Movies
            .Where(m => m.ImdbRating >= minRating)
            .OrderByDescending(m => m.ImdbRating)
            .ToListAsync();
    }

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

Finally, I'll add a service class that shows how to use the movie repository:

public class MovieService
{
    private readonly IMovieRepository _repository;

    public MovieService(IMovieRepository repository)
    {
        _repository = repository;
    }

    public async Task<Guid> CreateMovieAsync(
        string title,
        string director,
        int releaseYear,
        double rating)
    {
        var movie = new Movie
        {
            Id = Guid.NewGuid(),
            Title = title,
            Director = director,
            ReleaseYear = releaseYear,
            ImdbRating = rating
        };

        await _repository.AddAsync(movie);
        await _repository.SaveChangesAsync();

        return movie.Id;
    }

    public async Task<List<Movie>> GetHighlyRatedMoviesAsync()
    {
        return await _repository.GetTopRatedAsync(8.0);
    }
}

If you are writing CRUD applications, implementing a data layer like this probably looks very familiar.

What are the advantages of the Repository pattern?

The repository pattern promises several key advantages.

• A clean separation of concerns where data access logic is centralized.
• Reusability, where the same repo methods can be used without copying the same logic again.

When to use the Repository pattern

Like any tool, it offers leverage only when in the right place. If you smell any scent in your code, go for the repository pattern.

• When your application does not rely on simple data storage or fetching but requires enquiring logic such as validation, projection, object preparation, or calculations. Domains such as insurance, banking, healthcare, and IoT require calculations, so the repository pattern can be helpful.
• The repository pattern can win for you if you are aggregating multiple data sources but presenting them as a single source to the upper layers. Usage of different data sources, such as MSSQL, Postgres, and external APIs, is kept hidden from the business logic layer.
• The repository layer can be handy if an application demands sophisticated caching strategies and you don't want to pollute the business layers. Hence, the service layer can be unaware of how the cache is configured, or even of whether the data comes from the cache or another source.
• For unit testing, you can employ the repository pattern, especially in error-critical systems such as financial systems, medical devices, and safety systems. Repositories enable you to test business logic in isolation by swapping real data access with test doubles. You can verify complex business rules, edge cases, and error handling without the overhead, unpredictability, and slowness of database tests.

When to avoid the Repository pattern

Well, we have seen the usefulness of the repository pattern. Now, rejoining our original question, "In what conditions can you avoid the repository pattern?"

• If your app is just basic Create, Read, Update, Delete operations without complex business logic, you simply go without it. A simple creation or fetch will not require verbose code, and adding a new layer will overengineer it.

For example, in the code, a repository pattern has simple operations:

public class UserRepository : IUserRepository 
{
    public User GetById(int id) => _context.Users.Find(id);
    public void Add(User user) => _context.Users.Add(user);
}

• With an ORM, you can avoid the abstraction layer. Most ORMs, such as Entity Framework Core, NHibernate, and Doctrine, already implement the repository pattern using DbSet and AppDbContext. You can simply deal with entities like collections and objects. If you don't have to add conditions, validation, and projections in the operations, you can choose simplicity. When wrapping an ORM in repositories, you are often hiding powerful features (like IQueryable for deferred execution or Include for eager loading) behind a more restrictive interface.
• Smaller projects also don't need to be tedious. If your project requires simple queries and consists of 10-15 tables, you are good to go without bombarding a small project with more code.
• Any abstraction comes with overhead. In a performance-critical system, a repository may not be the best choice for the same reason. Repository layers can require memory allocation, additional method calls, or complex query translation, which may slow down the software. Repositories often lead to the N+1 query problem or over-fetching data because the repository method returns a generic object rather than a specific projection (Select) tailored to the view.
• One more scenario where you can skip the repository pattern is in a microservice architecture. If a service is simple enough to have a small database and minimal operations, you don't need to trade off the repository pattern for maintenance and performance.
• While preparing reporting and analytics data, the repository pattern can be unnecessary. Mostly, the stored procedures, raw SQL queries, and database-specific optimizations do the whole job for us. The code only calls those underlying queries and returns. To keep things maintainable and, of course, speedy, you can avoid one layer.

Conclusion

The repository pattern is something you have probably used on your development journey. Why not? It is one of the popular choices for abstracting data access. However, abstractions have a hidden cost that I highlighted in the blog. I identified a few scenarios where you can escape it and barely lose anything. If you still want to use the repository pattern without losing its limitation, the specification pattern is another player that can work. It allows for reusable query logic without the bloat of a traditional repository.

For F1 racing, choosing the right car is as important as your expertise. No matter how skilled you are, if you race in an ordinary car, you can't stand out. You need to understand the race and use the F1 racing car. The same goes for programming. Going with the wrong option can hurt your application. If your application contains high-throughput junctions prone to bottlenecks, you are left with choices for different collections. Today, I will explore popular data collection options, including IEnumerable and List, and examine how IEnumerable can hinder hot paths.

IEnumerable in C#

IEnumerable is an interface that represents a forward-only sequence of elements. It represents a behaviour that can be deferred or materialized based on implementation. It exposes a single method, GetEnumerator() that returns an IEnumerator<T> object you can iterate sequentially. However, it does not support indexing.

List in C#

A list is a dynamic collection that resizes automatically and allows access to elements by index. The List class provides methods such as Add, Remove, and AddRange. A List is materialized, loading all data into memory. In fact, List implements IEnumerable.

IEnumerable analysis with benchmark

To observe actual ground effects, let's create a console application where we can benchmark IEnumerable with a concrete List.

Step 1: Create the project

dotnet new console -n IEnumerableBenchmark
cd IEnumerableBenchmark

Step 2: Install the BenchmarkDotNet library

dotnet add package BenchmarkDotNet

Step 3: Prepare the benchmarking code

Here, we will define everything in the Program.cs file:

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Runtime.InteropServices;

BenchmarkRunner.Run<EnumerationBenchmarks>();

[MemoryDiagnoser]
public class EnumerationBenchmarks
{
    private List<int> _list = null!;
    private IEnumerable<int> _interfaceEnumerable = null!;
    private IEnumerable<int> _linqEnumerable = null!;
    private IEnumerable<int> _yieldEnumerable = null!;
    private int[] _array = null!;

    [Params(1000, 100_000)]
    public int N;

    [GlobalSetup]
    public void Setup()
    {
        // Independent data sources
        _list = Enumerable.Range(1, N).ToList();

        _array = Enumerable.Range(1, N).ToArray();

        _interfaceEnumerable = Enumerable.Range(1, N);

        _linqEnumerable = Enumerable.Range(1, N)
                                    .Where(x => x % 2 == 0)
                                    .Select(x => x * 2);

        _yieldEnumerable = CreateYieldSequence(N);
    }

    private IEnumerable<int> CreateYieldSequence(int count)
    {
        for (int i = 1; i <= count; i++)
        {
            if (i % 2 == 0)
                yield return i * 2;
        }
    }

    // -------------------------------
    // List - for (optimized)
    // -------------------------------
    [Benchmark(Baseline = true)]
    public int List_For()
    {
        int sum = 0;
        var list = _list;
        int count = list.Count;

        for (int i = 0; i < count; i++)
        {
            var x = list[i];
            if (x % 2 == 0)
                sum += x * 2;
        }

        return sum;
    }

    // -------------------------------
    // List - foreach
    // -------------------------------
    [Benchmark]
    public int List_Foreach()
    {
        int sum = 0;

        foreach (var x in _list)
        {
            if (x % 2 == 0)
                sum += x * 2;
        }

        return sum;
    }

    // -------------------------------
    // IEnumerable - foreach
    // -------------------------------
    [Benchmark]
    public int IEnumerable_Foreach()
    {
        int sum = 0;

        foreach (var x in _interfaceEnumerable)
        {
            if (x % 2 == 0)
                sum += x * 2;
        }

        return sum;
    }

    // -------------------------------
    // Array - foreach
    // -------------------------------
    [Benchmark]
    public int Array_Foreach()
    {
        int sum = 0;

        foreach (var x in _array)
        {
            if (x % 2 == 0)
                sum += x * 2;
        }

        return sum;
    }

    // -------------------------------
    // LINQ Deferred Execution
    // -------------------------------
    [Benchmark]
    public int Linq_Deferred()
    {
        return _linqEnumerable.Sum();
    }

    // -------------------------------
    // Yield State Machine
    // -------------------------------
    [Benchmark]
    public int Yield_Enumeration()
    {
        int sum = 0;

        foreach (var x in _yieldEnumerable)
        {
            sum += x;
        }

        return sum;
    }

    // -------------------------------
    // Multiple Enumeration
    // -------------------------------
    [Benchmark]
    public int Multiple_Enumeration()
    {
        int sum = 0;

        if (_linqEnumerable.Any())
        {
            foreach (var x in _linqEnumerable)
            {
                sum += x;
            }
        }

        return sum;
    }

    // -------------------------------
    // Span<T>
    // -------------------------------
    [Benchmark]
    public int Span_For()
    {
        int sum = 0;
        var span = CollectionsMarshal.AsSpan(_list);

        for (int i = 0; i < span.Length; i++)
        {
            var x = span[i];
            if (x % 2 == 0)
                sum += x * 2;
        }

        return sum;
    }
}

I defined a list and an IEnumerable. In the Setup, we will initialize each one with 1000 and 100000 elements. There are several other testers to get how IEnumerable performs as deferred and as materialized collections, as shown in the methods.

Step 4: Run the project

Let's run our project in release mode

dotnet run -c Release

So, the results show the cost of IEnumerable.

As per the results, List outperformed IEnumerable by up to 7x. Thanks to contiguous memory allocation and JITs array optimization, arrays outclass the list, too. But flexibility and numerous handy methods make the list more usable in most scenarios. The single test does not prove that IEnumerable should be abandoned. In fact, you will not want to overload memory by loading the entire dataset if it is extremely large. Then theIEnumerable's behaviour took effect. The List is a help for small to medium-sized collections and requires frequent manipulation, such as adding and removing items. As immediate execution loads data immediately, lists are ideal when you need data to be readily available and need frequent manipulation.

Using IEnumerable in hot paths slows performance and does not support data manipulation. Usually, applications do not load all data at once; instead, they use filtering or pagination when fetching data. In such cases, lists leverage immediate execution.

Conclusion

We may not need to emphasize the importance of performance in any application. We already know the importance of keeping the operations as fast as possible. Identifying and mitigating the hot path is one link in this chain. I shared one underrated point about using the right collection in such bottleneck areas. Being cautious about IEnumerable in hot paths, can be good for the application and your peace of mind.

Code: https://github.com/elmahio-blog/IEnumerableBenchmark

Database schema and entity design are the pavement of most applications. If the entities are paved well, the application can provide great performance. Otherwise, it can lead to pitfalls. One key aspect of entity design is dealing with polymorphic relationships. EF Core supports several ways to implement inheritance, so in this post, I will explore the best ways to handle these relationships.

To see these concepts in action, we need to look at the specific implementation strategies EF Core offers. We will start with the most common approach, which maps an entire class hierarchy to a single database table.

Table-per-Hierarchy (TPH) Inheritance (EF Core-native) polymorphic relationship implementation

One polymorphic relationship EF Core provides is Table-per-Hierarchy (TPH). A single table stores data for all inherited types, differentiated by a discriminator column. I will use an enum for the discriminator. In fact, TPH is the default mapping of EF Core. Let us create a project to showcase TPH.

Step 1: Create a project

dotnet new console -o EfCoreTph

Step 2: Install the required packages

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools

Step 3: Define models

Add the discriminator enum:

public enum EmployeeTypeEnum: byte
{
    FullTimeEmployee = 1,
    PartTimeEmployee = 2,
    Contractor = 3
}

Add the model Employee:

public abstract class Employee
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public DateTime HireDate { get; set; } = DateTime.UtcNow.Date;
    public decimal BaseSalary { get; set; }
}

I've made it abstract to function as a base class. Next, add the Contractor sub-class:

public class Contractor: Employee
{
    public DateTime ContractEndDate { get; set; }
    public string AgencyName { get; set; } = string.Empty;
}

And add another subclass named FullTimeEmployee:

public class FullTimeEmployee: Employee
{
    public decimal AnnualBonus { get; set; }
    public int VacationDays { get; set; }
}

And finally, add the PartTimeEmployee subclass:

public class PartTimeEmployee: Employee
{
    public decimal HourlyRate { get; set; }
    public int WeeklyHours { get; set; }
}

Step 4: Set up DbContext

As a decisive step, I will specify how I want to handle relationships.

using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext: DbContext
{
    public DbSet<Employee> Employees => Set<Employee>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        options.UseNpgsql(
            "Connection string with db name tphDb");
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Employee>()
            .HasDiscriminator<EmployeeTypeEnum>("EmployeeType")
            .HasValue<FullTimeEmployee>(EmployeeTypeEnum.FullTimeEmployee)
            .HasValue<PartTimeEmployee>(EmployeeTypeEnum.PartTimeEmployee)
            .HasValue<Contractor>(EmployeeTypeEnum.Contractor);
    }
}

Inside the OnModelCreating method, I configure EF Core to store all derived types in a single table and use a column to indicate which CLR type each row represents, following TPH. That discriminator is EmployeeType, which in this case is an enum.

Step 5: Configure Program.cs

using Microsoft.EntityFrameworkCore;

using var db = new ApplicationDbContext();

var fullTime = new FullTimeEmployee
{
    Name = "Ali Hamza",
    Email = "ali@company.com",
    HireDate = DateTime.UtcNow.AddYears(-2),
    BaseSalary = 150000,
    AnnualBonus = 30000,
    VacationDays = 25
};

var partTime = new PartTimeEmployee
{
    Name = "James Anderson",
    Email = "james@anderson.com",
    HireDate = DateTime.UtcNow.AddMonths(-6),
    BaseSalary = 0,
    HourlyRate = 1200,
    WeeklyHours = 20
};

var contractor = new Contractor
{
    Name = "Frank Doe",
    Email = "Frank@agency.com",
    HireDate = DateTime.UtcNow.AddMonths(-3),
    BaseSalary = 0,
    ContractEndDate = DateTime.UtcNow.AddMonths(9),
    AgencyName = "TechStaff Ltd"
};

db.Employees.AddRange(fullTime, partTime, contractor);
db.SaveChanges();

Console.WriteLine("Employees inserted.");

var partTimers = 
    await db.Employees.OfType<PartTimeEmployee>().ToListAsync();

foreach (var item in partTimers)
{
    Console.WriteLine(item.Name);
    Console.WriteLine(item.Email);
    Console.WriteLine(item.HireDate);
    Console.WriteLine(item.BaseSalary);
    Console.WriteLine(item.WeeklyHours);
    Console.WriteLine(item.HourlyRate);
}

var employees = await db.Employees.ToListAsync();

foreach (var emp in employees)
{
    Console.WriteLine($"[{emp.GetType().Name}] {emp.Name}");

    if (emp is FullTimeEmployee fte)
    {
        Console.WriteLine($"  Bonus: {fte.AnnualBonus}");
    }
    else if (emp is PartTimeEmployee pte)
    {
        Console.WriteLine($"  Hourly Rate: {pte.HourlyRate}");
    }
    else if (emp is Contractor c)
    {
        Console.WriteLine($"  Agency: {c.AgencyName}");
    }
}

We can fetch records either by a specific type, like PartTimeEmployee or with Employees using the polymorphic nature.

Step 6: Run migration

Migrate the database with all of the changes:

dotnet ef migrations add InitialDb

dotnet ef database update

Let us look inside the InitialDb migration to see the generated code:

using System;
using Microsoft.EntityFrameworkCore.Migrations;
using Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;

#nullable disable

namespace EfCoreTph.Migrations
{
    /// <inheritdoc />
    public partial class InitialDb : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.CreateTable(
                name: "Employees",
                columns: table => new
                {
                    Id = table.Column<int>(type: "integer", nullable: false)
                        .Annotation("Npgsql:ValueGenerationStrategy", NpgsqlValueGenerationStrategy.IdentityByDefaultColumn),
                    Name = table.Column<string>(type: "text", nullable: false),
                    Email = table.Column<string>(type: "text", nullable: false),
                    HireDate = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
                    BaseSalary = table.Column<decimal>(type: "numeric", nullable: false),
                    EmployeeType = table.Column<byte>(type: "smallint", nullable: false),
                    ContractEndDate = table.Column<DateTime>(type: "timestamp with time zone", nullable: true),
                    AgencyName = table.Column<string>(type: "text", nullable: true),
                    AnnualBonus = table.Column<decimal>(type: "numeric", nullable: true),
                    VacationDays = table.Column<int>(type: "integer", nullable: true),
                    HourlyRate = table.Column<decimal>(type: "numeric", nullable: true),
                    WeeklyHours = table.Column<int>(type: "integer", nullable: true)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_Employees", x => x.Id);
                });
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropTable(
                name: "Employees");
        }
    }
}

A single table is created, with all common properties non-nullable and type-specific properties nullable.

The table and seed data in the database look like this:

We observe that type-specific columns are null for records of other types.

Step 7: Run and test the application

Let's run the project:

dotnet run

When is TPH best

• For domain-driven design, TPH is best suited to lower complexity and is fully supported by EF Core.
• It offers the least complexity, and LINQ works naturally.
• Optimal when types are closely related, and there are fewer chances of null values.

When to avoid TPH

• Sometimes strength becomes a liability. So is the case with TPH. If your entities are unrelated, then a single table can be overwhelmed by null values.
• Due to null columns, TPH can be inefficient if you have too many derived entities.

Table-Per-Type (TPT) EF core polymorphic relationship implementation

Another type of relationship EF offers is Table-Per-Type (TPT). As the name suggests, parent and child entities contain their own table joined via foreign keys. Let's check how we can do it with a new sample project.

Step 1: Create a project

dotnet new console -o EfCoreTpt

Step 2: Install the required packages

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools

Step 3: Define models

We will create the same models as in the sample above.

Step 4: Set up DbContext

using Microsoft.EntityFrameworkCore;

namespace EfCoreTpt.Data;

public class ApplicationDbContext: DbContext
{
    public DbSet<Employee> Employees => Set<Employee>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        options.UseNpgsql(
            "connection string with db name tptDb");
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Employee>().UseTptMappingStrategy();

        modelBuilder.Entity<FullTimeEmployee>().ToTable("FullTimeEmployees");
        modelBuilder.Entity<PartTimeEmployee>().ToTable("PartTimeEmployees");
        modelBuilder.Entity<Contractor>().ToTable("Contractors");
    }
}

Here, with UseTptMappingStrategy I have to specify the base type of Employee with TPT mapping. You can see that other types are also mapped to their table.

Step 5: Configure Program.cs

using var db = new ApplicationDbContext();

var fullTime = new FullTimeEmployee
{
    Name = "Ali Hamza",
    Email = "ali@company.com",
    HireDate = DateTime.UtcNow.AddYears(-2),
    BaseSalary = 150000,
    AnnualBonus = 30000,
    VacationDays = 25
};

var partTime = new PartTimeEmployee
{
    Name = "James Anderson",
    Email = "james@anderson.com",
    HireDate = DateTime.UtcNow.AddMonths(-6),
    BaseSalary = 0,
    HourlyRate = 1200,
    WeeklyHours = 20
};

var contractor = new Contractor
{
    Name = "Frank Doe",
    Email = "Frank@agency.com",
    HireDate = DateTime.UtcNow.AddMonths(-3),
    BaseSalary = 0,
    ContractEndDate = DateTime.UtcNow.AddMonths(9),
    AgencyName = "TechStaff Ltd"
};

db.Employees.AddRange(fullTime, partTime, contractor);
db.SaveChanges();

Console.WriteLine("Employees inserted.");

var employees = db.Employees.ToList();

foreach (var emp in employees)
{
    Console.WriteLine($"[{emp.GetType().Name}] {emp.Name}");

    switch (emp)
    {
        case FullTimeEmployee f:
            Console.WriteLine($"  Bonus: {f.AnnualBonus}");
            break;

        case PartTimeEmployee p:
            Console.WriteLine($"  Hourly: {p.HourlyRate}");
            break;

        case Contractor c:
            Console.WriteLine($"  Agency: {c.AgencyName}");
            break;
    }
}

Step 6: Run migration

Again, let us update the database:

dotnet ef migrations add InitialDb

dotnet ef database update

And look at the generated migration class:

using System;
using Microsoft.EntityFrameworkCore.Migrations;
using Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;

#nullable disable

namespace EfCoreTpt.Migrations
{
    /// <inheritdoc />
    public partial class InitialDb : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.CreateTable(
                name: "Employees",
                columns: table => new
                {
                    Id = table.Column<int>(type: "integer", nullable: false)
                        .Annotation("Npgsql:ValueGenerationStrategy", NpgsqlValueGenerationStrategy.IdentityByDefaultColumn),
                    Name = table.Column<string>(type: "text", nullable: false),
                    Email = table.Column<string>(type: "text", nullable: false),
                    HireDate = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
                    BaseSalary = table.Column<decimal>(type: "numeric", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_Employees", x => x.Id);
                });

            migrationBuilder.CreateTable(
                name: "Contractors",
                columns: table => new
                {
                    Id = table.Column<int>(type: "integer", nullable: false),
                    ContractEndDate = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
                    AgencyName = table.Column<string>(type: "text", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_Contractors", x => x.Id);
                    table.ForeignKey(
                        name: "FK_Contractors_Employees_Id",
                        column: x => x.Id,
                        principalTable: "Employees",
                        principalColumn: "Id",
                        onDelete: ReferentialAction.Cascade);
                });

            migrationBuilder.CreateTable(
                name: "FullTimeEmployees",
                columns: table => new
                {
                    Id = table.Column<int>(type: "integer", nullable: false),
                    AnnualBonus = table.Column<decimal>(type: "numeric", nullable: false),
                    VacationDays = table.Column<int>(type: "integer", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_FullTimeEmployees", x => x.Id);
                    table.ForeignKey(
                        name: "FK_FullTimeEmployees_Employees_Id",
                        column: x => x.Id,
                        principalTable: "Employees",
                        principalColumn: "Id",
                        onDelete: ReferentialAction.Cascade);
                });

            migrationBuilder.CreateTable(
                name: "PartTimeEmployees",
                columns: table => new
                {
                    Id = table.Column<int>(type: "integer", nullable: false),
                    HourlyRate = table.Column<decimal>(type: "numeric", nullable: false),
                    WeeklyHours = table.Column<int>(type: "integer", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_PartTimeEmployees", x => x.Id);
                    table.ForeignKey(
                        name: "FK_PartTimeEmployees_Employees_Id",
                        column: x => x.Id,
                        principalTable: "Employees",
                        principalColumn: "Id",
                        onDelete: ReferentialAction.Cascade);
                });
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropTable(
                name: "Contractors");

            migrationBuilder.DropTable(
                name: "FullTimeEmployees");

            migrationBuilder.DropTable(
                name: "PartTimeEmployees");

            migrationBuilder.DropTable(
                name: "Employees");
        }
    }
}

One notable aspect here is the use of foreign keys to link tables. TPT is the only one that uses foreign keys to represent the inheritance itself. Other strategies can still use FKs for normal relationships (like Employee has a Laptop).

The database and data now look like this:

Although I added records using the base class, they are written into their respective tables.

Step 7: Run and test the application

dotnet run

EF Core generates joins in every query, such as:

SELECT ...
FROM Employees e
LEFT JOIN FullTimeEmployees f ON e.Id = f.Id
LEFT JOIN PartTimeEmployees p ON e.Id = p.Id
LEFT JOIN Contractors c ON e.Id = c.Id

When is TPT best

• With each type having its own table, the database schema remained clean.
• The database is inherently well normalized.
• Records contain minimal nulls. TPT is optimal when your application has big inheritance trees.

When to avoid TPT

• TPT can be problematic in performance-critical systems, potentially slowing data reading.
• Queries heavily rely on joins.

Table-Per-Concrete (TPC) EF Core polymorphic relationship implementation

The last approach in EF Core polymorphic relationships is Table-Per-Concrete-Class (TPC). The parent class has no table, while each concrete class contains its own table. Each table repeats inherited fields as its columns. Like with the previous types, let us create a sample project to show how it works.

Step 1: Create a project

dotnet new console -o EfCoreTpc

Step 2: Install the required packages

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools

Step 3: Define models

We will use the same models as in the sample above.

Step 4: Set up DbContext

This is the most crucial step, as with the others. Here, I will specify how I want to deal with relationships:

using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext: DbContext
{
    public DbSet<Employee> Employees => Set<Employee>();
    public DbSet<FullTimeEmployee> FullTimeEmployees => Set<FullTimeEmployee>();
    public DbSet<PartTimeEmployee> PartTimeEmployees => Set<PartTimeEmployee>();
    public DbSet<Contractor> Contractors => Set<Contractor>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        options.UseNpgsql(
            "Connectionstring with db name tpcDb");
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Employee>()
            .UseTpcMappingStrategy();
    }
}

The code modelBuilder.Entity().UseTpcMappingStrategy() instructs EF Core to use TPC mappings.

Step 5: Configure Program.cs

using var db = new ApplicationDbContext();

var fullTime = new FullTimeEmployee
{
    Name = "Ali Hamza",
    Email = "ali@company.com",
    HireDate = DateTime.UtcNow.AddYears(-2),
    BaseSalary = 150000,
    AnnualBonus = 30000,
    VacationDays = 25
};

var partTime = new PartTimeEmployee
{
    Name = "James Anderson",
    Email = "james@anderson.com",
    HireDate = DateTime.UtcNow.AddMonths(-6),
    BaseSalary = 0,
    HourlyRate = 1200,
    WeeklyHours = 20
};

var contractor = new Contractor
{
    Name = "Frank Doe",
    Email = "Frank@agency.com",
    HireDate = DateTime.UtcNow.AddMonths(-3),
    BaseSalary = 0,
    ContractEndDate = DateTime.UtcNow.AddMonths(9),
    AgencyName = "TechStaff Ltd"
};

db.Employees.AddRange(fullTime, partTime, contractor);
db.SaveChanges();

Console.WriteLine("Employees inserted.");

var employees = db.Employees.ToList();

foreach (var emp in employees)
{
    Console.WriteLine($"[{emp.GetType().Name}] {emp.Name}");
}

Here, I am leveraging polymorphic behaviour by inserting records into the Employees data set.

Step 6: Run migration

Create a migration and update the database:

dotnet ef migrations add InitialDb

dotnet ef database update

The new migration class looks like this:

using System;
using Microsoft.EntityFrameworkCore.Migrations;

#nullable disable

namespace EfCoreTpc.Migrations
{
    /// <inheritdoc />
    public partial class InitialDb : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.CreateSequence(
                name: "EmployeeSequence");

            migrationBuilder.CreateTable(
                name: "Contractors",
                columns: table => new
                {
                    Id = table.Column<int>(type: "integer", nullable: false, defaultValueSql: "nextval('\"EmployeeSequence\"')"),
                    Name = table.Column<string>(type: "text", nullable: false),
                    Email = table.Column<string>(type: "text", nullable: false),
                    HireDate = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
                    BaseSalary = table.Column<decimal>(type: "numeric", nullable: false),
                    ContractEndDate = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
                    AgencyName = table.Column<string>(type: "text", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_Contractors", x => x.Id);
                });

            migrationBuilder.CreateTable(
                name: "FullTimeEmployees",
                columns: table => new
                {
                    Id = table.Column<int>(type: "integer", nullable: false, defaultValueSql: "nextval('\"EmployeeSequence\"')"),
                    Name = table.Column<string>(type: "text", nullable: false),
                    Email = table.Column<string>(type: "text", nullable: false),
                    HireDate = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
                    BaseSalary = table.Column<decimal>(type: "numeric", nullable: false),
                    AnnualBonus = table.Column<decimal>(type: "numeric", nullable: false),
                    VacationDays = table.Column<int>(type: "integer", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_FullTimeEmployees", x => x.Id);
                });

            migrationBuilder.CreateTable(
                name: "PartTimeEmployees",
                columns: table => new
                {
                    Id = table.Column<int>(type: "integer", nullable: false, defaultValueSql: "nextval('\"EmployeeSequence\"')"),
                    Name = table.Column<string>(type: "text", nullable: false),
                    Email = table.Column<string>(type: "text", nullable: false),
                    HireDate = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
                    BaseSalary = table.Column<decimal>(type: "numeric", nullable: false),
                    HourlyRate = table.Column<decimal>(type: "numeric", nullable: false),
                    WeeklyHours = table.Column<int>(type: "integer", nullable: false)
                },
                constraints: table =>
                {
                    table.PrimaryKey("PK_PartTimeEmployees", x => x.Id);
                });
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropTable(
                name: "Contractors");

            migrationBuilder.DropTable(
                name: "FullTimeEmployees");

            migrationBuilder.DropTable(
                name: "PartTimeEmployees");

            migrationBuilder.DropSequence(
                name: "EmployeeSequence");
        }
    }
}

The code migrationBuilder.CreateSequence(name: "EmployeeSequence") specifies global ID generation across the hierarchy. Instead of independent identity generators, EF Core uses one shared sequence.

The database now looks like this:

Step 7: Run and test the application

dotnet run

A high-level view of the generated query is:

SELECT ... FROM FullTimeEmployees
UNION ALL
SELECT ... FROM PartTimeEmployees
UNION ALL
SELECT ... FROM Contractors

And the rows returned look like in the following screenshots:

When is TPC best

• TPC applies when the application requires performing extensive queries on concrete types.
• When you are designing a fast read-heavy system.
• When you want to keep clean tables with no nulls.

When to avoid TPC

• TPC can slow down when the application has many polymorphic queries.
• Do not use with large inheritance trees.
• Not optimal, frequent schema changes.
• Duplicated columns can be problematic for some users.

Conclusion

Entity Framework provides different ways to design entities. They are not fixed for any use, but we tried to see by example how each one creates tables and how its internal relationships work. A quick summary of the types and features can be seen here:

In this blog post, I delved deeper into TPH, TPT, and TPC. I hope it helps you decide on which strategy to use for your database design.

Code: https://github.com/elmahio-blog/PolymorphicRelEfCore

As developers, we know that user requests can be unpredictable. When they request data, it is either successfully returned or not found. However, a "not found" result usually happens in two ways. First, the user might request a record, such as a basketball player, by passing an ID that doesn't exist. Second, they might pass the wrong type of ID, like a Team ID, while trying to fetch a Player. The first situation is common, but the second should be handled to avoid logic pitfalls. Enforcing this validation for every entity can be a humongous task when your application contains hundreds of entities. In this post, I will provide a way out of this situation so you can restrict your application from passing IDs interchangeably among entities.

Primitive obsession

Primitive obsession refers to a situation where we use primitive data types, such as int, string, or bool, to represent complex data. Usually, values like URLs, Addresses, or identities are saved as strings. This creates a hidden breach of encapsulation because it forces you to add an extra layer of validation somewhere else in the code.

For domain-specific entities like URLs or addresses, you can use owned entities. However, to define domain-specific identities, we need strongly-typed IDs.

Primitive Id implementation for EF Core model entity

Let's first understand the problem with the traditional way. I will create a console application with a PostgreSQL database to catch the issue at hand.

Step 1: Create the project

dotnet new console -n IntIdsDemo
cd IntIdsDemo

Step 2: Install necessary packages

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

Step 3: Define models

I'll create models to represent a player, a team, and the relationship between them.

Player

namespace IntIdsDemo.Domain.Entities;

public class Player
{
    public int Id { get; private set; }
    public string Name { get; private set; } = string.Empty;

    private Player() { } // Required by EF Core

    public Player(string name)
    {
        Name = name;
    }
}

Team

namespace IntIdsDemo.Domain.Entities;

public class Team
{
    public int Id { get; private set; }
    public string Name { get; private set; } = string.Empty;

    private Team() { } 

    public Team(string name)
    {
        Name = name;
    }
}

PlayerTeam to join them

namespace IntIdsDemo.Domain.Entities;

public class PlayerTeam
{
    public int Id { get; private set; }
    public int PlayerId { get; set; }
    public int TeamId { get; set; }

    private PlayerTeam() { }

    public PlayerTeam(int playerId, int teamId)
    {
        PlayerId = playerId;
        TeamId = teamId;
    }
}

Step 4: Configure ApplicationDbContext

using IntIdsDemo.Domain.Entities;
using Microsoft.EntityFrameworkCore;

namespace IntIdsDemo.Data;

public class ApplicationDbContext: DbContext
{
    public DbSet<Player> Players => Set<Player>();
    public DbSet<Team> Teams => Set<Team>();
    public DbSet<PlayerTeam> PlayerTeams => Set<PlayerTeam>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        options.UseNpgsql(
            "Connection string with database simpleIdsDb");
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {        
    }
}

Step 5: Define Program.cs

using IntIdsDemo.Data;
using IntIdsDemo.Domain.Entities;

using var db = new ApplicationDbContext();

// Seed data
var player1 = new Player("Ali");
var player2 = new Player("Hamza");
var team = new Team("Warriors");

db.Players.Add(player1);
db.Players.Add(player2);
db.Teams.Add(team);
db.SaveChanges();

Console.WriteLine("Player & Team saved");

// Simple assignment method
void AssignPlayerToTeam(int playerId, int teamId)
{
    var playerTeam = new PlayerTeam(playerId, teamId);
    db.PlayerTeams.Add(playerTeam);
    db.SaveChanges();
}

AssignPlayerToTeam(player2.Id, team.Id);
AssignPlayerToTeam(team.Id, player2.Id);

Player player = db.Players.Find(team.Id);

if (player != null)
{
    Console.WriteLine($"Player Id (int): {player.Id}");
    Console.WriteLine($"Player Name: {player.Name}");
}

player = db.Players.Find(player2.Id);

if (player != null)
{
    Console.WriteLine($"Player Id (int): {player.Id}");
    Console.WriteLine($"Player Name: {player.Name}");
}

I am initializing 2 players and 1 team here. Later, I assign player 2 to the team. First, I did it correctly as per the method's requirement, with AssignPlayerToTeam(player2.Id, team.Id); While in the second part, which is logically wrong, the compiler will give a green signal to AssignPlayerToTeam(team.Id, player2.Id). Next, I am observing an issue with fetching data. I can easily pass teamId as the parameter for the Find method, where playerId (db.Players.Find(team.Id)) is expected. But since we are using the primitive type of int, it will compile without any errors.

Step 6: Run the migration

We need to create an empty database

CREATE DATABASE simpleIdsDb;

And create a migration and update the database

dotnet ef migrations add InitialCreate
dotnet ef database update

Step 7: run the project

dotnet run

Let's check the database. The Players table contains the following rows:

The Teams table contains a single row:

And finally, the PlayerTeams table contains two relationship rows:

As you can see, the assignment is done, and PlayerId and TeamId were assigned interchangeably. To prevent this at the database level, we would have to add specific constraints. However, at the coding level, this remains a significant issue. While the console output shows that the player was not found with team.Id, this behavior can still lead to data inconsistency or unexpected runtime errors.

Strongly-Typed ID implementation for safer domain model

To keep focus on strongly-typed ID implementations, I will continue a similar project.

Step 1: Create the project

dotnet new console -n StronglyTypedIdsDemo
cd StronglyTypedIdsDemo

Step 2: Install necessary packages

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

Step 3: Create the Strongly-Typed IDs

Traversing to the directory Domain/Ids/ and add the following code for creating a player ID

namespace StronglyTypedIdsDemo.Domain.Ids;

public readonly record struct PlayerId(int Value)
{
    public override string ToString() => Value.ToString();
}

And the following for creating a team ID

namespace StronglyTypedIdsDemo.Domain.Ids;

public readonly record struct TeamId(int Value)
{
    public override string ToString() => Value.ToString();
}

And finally, the player/team relational ID

namespace StronglyTypedIdsDemo.Domain.Ids;

public readonly record struct PlayerTeamId(int Value)
{
    public override string ToString() => Value.ToString();
}

struct are the best fit for strongly-typed IDs. A struct cannot contain null, while a class would allow it null, heap allocation, and reference semantics. readonly ensures immutability and cannot be modified after creation. As we know record is a value object, record struct will give you value-based equality automatically.

Step 4: Create the Entity

Go to the directory StronglyTypedIdsDemo.Domain.Entities and add the following model classes

using StronglyTypedIdsDemo.Domain.Ids;

namespace StronglyTypedIdsDemo.Domain.Entities;

public class Player
{
    public PlayerId Id { get; private set; }
    public string Name { get; private set; } = string.Empty;

    private Player() { } 

    public Player(string name)
    {
        Name = name;
    }
}

using StronglyTypedIdsDemo.Domain.Ids;

namespace StronglyTypedIdsDemo.Domain.Entities;

public class Team
{
    public TeamId Id { get; private set; }
    public string Name { get; private set; } = string.Empty;

    private Team() { } 

    public Team(string name)
    {
        Name = name;
    }
}

using StronglyTypedIdsDemo.Domain.Ids;

namespace StronglyTypedIdsDemo.Domain.Entities;

public class PlayerTeam
{
    public PlayerTeamId Id { get; private set; }
    public PlayerId PlayerId { get; private set; }
    public TeamId TeamId { get; private set; }

    private PlayerTeam() { }

    public PlayerTeam(PlayerId playerId, TeamId teamId)
    {
        PlayerId = playerId;
        TeamId = teamId;
    }
}

These classes look similar to the first application but all ID types have been switched out for the strongly typed versions.

Step 5: Configure the DbContext

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
using StronglyTypedIdsDemo.Domain.Entities;
using StronglyTypedIdsDemo.Domain.Ids;

namespace StronglyTypedIdsDemo.Data;

public class ApplicationDbContext: DbContext
{
    public DbSet<Player> Players => Set<Player>();
    public DbSet<Team> Teams => Set<Team>();
    public DbSet<PlayerTeam> PlayerTeams => Set<PlayerTeam>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        options.UseNpgsql(
            "Connection string with db name strongIdsDb");
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        var playerIdConverter = new ValueConverter<PlayerId, int>(
            id => id.Value,
            value => new PlayerId(value));

        modelBuilder.Entity<Player>(entity =>
        {
            entity.HasKey(x => x.Id);

            entity.Property(x => x.Id)
                .HasConversion(playerIdConverter)
                .ValueGeneratedOnAdd();

            entity.Property(x => x.Name)
                .IsRequired();
        });
        
        var teamIdConverter = new ValueConverter<TeamId, int>(
            id => id.Value,
            value => new TeamId(value));

        modelBuilder.Entity<Team>(entity =>
        {
            entity.HasKey(x => x.Id);

            entity.Property(x => x.Id)
                .HasConversion(teamIdConverter)
                .ValueGeneratedOnAdd();

            entity.Property(x => x.Name)
                .IsRequired();
        });
        
        var playerTeamIdConverter = new ValueConverter<PlayerTeamId, int>(
            id => id.Value,
            value => new PlayerTeamId(value));

        modelBuilder.Entity<PlayerTeam>(entity =>
        {
            entity.HasKey(x => x.Id);

            entity.Property(x => x.Id)
                .HasConversion(playerTeamIdConverter)
                .ValueGeneratedOnAdd();

            entity.Property(pt => pt.PlayerId)
                .HasConversion(playerIdConverter)
                .IsRequired();

            entity.Property(pt => pt.TeamId)
                .HasConversion(teamIdConverter)
                .IsRequired();
        });
    }
}

I used ValueConverter<PlayerId, int> that tells EF Core to use PlayerId but save the value as int. similarly TeamId and PlayerTeamId are configured. Notice that adding a connection string through code is not recommended and only done for simplicity. Always use external configuration for this.

Step 6: Configure Program.cs

using StronglyTypedIdsDemo.Data;
using StronglyTypedIdsDemo.Domain.Entities;
using StronglyTypedIdsDemo.Domain.Ids;

using var db = new ApplicationDbContext();

// Seed data
var player1 = new Player("Ali");
var player2 = new Player("Hamza");
var team = new Team("Warriors");

db.Players.Add(player1);
db.Players.Add(player2);
db.Teams.Add(team);
db.SaveChanges();

Console.WriteLine("Player & Team saved");

// Simple assignment method
void AssignPlayerToTeam(PlayerId playerId, TeamId teamId)
{
    var playerTeam = new PlayerTeam(playerId, teamId);
    db.PlayerTeams.Add(playerTeam);
    db.SaveChanges();
}

AssignPlayerToTeam(player2.Id, team.Id);

// ⚠️ Wrong order of parameter
AssignPlayerToTeam(team.Id, player2.Id);

// ⚠️ Wrong ID type for Find
Player player = db.Players.Find(team.Id);

if (player != null)
{
    Console.WriteLine($"Player Id (int): {player.Id}");
    Console.WriteLine($"Player Name: {player.Name}");
}

player = db.Players.Find(player2.Id);

if (player != null)
{
    Console.WriteLine($"Player Id (int): {player.Id}");
    Console.WriteLine($"Player Name: {player.Name}");
}

In the code, I'm adding a record manually . In the line AssignPlayerToTeam(team.Id, player2.Id), a compiler error is shown.

The compiler now detects when we try to use the incorrect IDs when adding a user to a team.

Sep 7: run migrations

We need to create an empty database

CREATE DATABASE strongIdsDb;

And add the migration and run it

dotnet ef migrations add InitialCreate
dotnet ef database update

Step 8: Run and test

dotnet run

The second error is now revealed, since we are trying to use a team ID as the parameter for the Find method on the Players table

This means we are on the right track. Remove erroneous code and everything looks great

What strongly-typed IDs have improved?

• Primitive IDs can lead to id-mixup at compile time. Defining identity structure. Each entity eliminates this shortcoming.
• The traditional approach lacks domain meaning, whereas a strongly typed ID contains explicit intent.
• Strongly-typed IDs removed the ambiguity of method signatures that happens when int, Guid, or other primitive types are used.
• Traditionally, bugs are skipped at compile time, leading to runtime errors, while strongly-typed IDs catch ID mismatches at compile time.

Conclusion

Robustness is a big win for any application. Your code should handle issues right at the gateway. One common problem most people overlook is primitive obsession. Using types like ints for IDs allows you to pass IDs of different entities interchangeably. You can validate them manually, but that requires extra verbose code elsewhere, which breaks encapsulation. In this post, I have provided a solution using strongly-typed IDs to resolve that problem. We first looked at the traditional approach and observed the real-world issues caused by primitive obsession. Using separate value-object IDs makes your domain model much safer.

Code: https://github.com/elmahio-blog/StronglyTypedIdsDemo

.NET 10 is officially out, along with C# 14. Microsoft has released .NET 10 as Long-Term Support (LTS) as a successor to .NET 8. Like every version, it is not just an update but brings something new to the table. In this series, we will explore which aspects of software can be upgraded with the latest release. Today, we will explore a multi-tenant rate limiter with .NET 10.

APIs power your business. The statement is mostly true for all of your applications. The user accesses the information via mobile or web, and you provide it to them via an API. For SaaS, the access and information have more to manage from client to client. A premium client pays more and needs more throughput. Similarly, others will use the system according to their plan and user base. One factor of fair use among clients or tenants is rate limiting, that is, how many requests users of a client can hit the server. .NET 10 offers improvements in rate-limiting with its throttling middleware.

Designing a multi-tenant rate limiter

To understand the multi-tenant rate limiter, we will create a simple web API. I will provide step-by-step instructions to break this down with .NET 10.

Step 1: Create a .NET API project

dotnet new webapi -n Net10RateLimiter -f net10.0
cd Net10RateLimiter

Step 2: Create Models

I organized models in the Models folder and created the following class:

namespace Net10RateLimiter.Models;

public class TenantRateLimit
{
    public string TenantId { get; set; } = string.Empty;
    public int RequestsPerMinute { get; set; }
}

The class TenantRateLimit will define a tenant-specific rate using OOP. For a database-based application, we can save it as well.

Step 3: Create a Limit resolver service

For that logic, I created a folder named Services, and the resolver class look like this:

namespace Net10RateLimiter.Services;

public sealed class TenantResolver
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public TenantResolver(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public string ResolveTenant()
    {
        var context = _httpContextAccessor.HttpContext;

        if (context is null)
            return "default";

        if (context.Request.Headers.TryGetValue("X-Tenant-ID", out var tenantId))
            return tenantId.ToString();

        return "default";
    }
}

The resolver works as request-scoped logic to invalidate limits on each request. It extracts the tenant identity from the incoming request and returns.

Step 4: Register Required Services

Inject the required dependencies in Program.cs

builder.Services.AddControllers();

// Required for HttpContext access
builder.Services.AddHttpContextAccessor();

// Tenant resolver must be scoped
builder.Services.AddScoped<TenantResolver>();

Step 5: Add rate limiting logic

Just after the dependency injections, add the following code:

builder.Services.AddRateLimiter(options =>
{
    options.OnRejected = async (context, token) =>
    {
        context.HttpContext.Response.StatusCode = 429;
        await context.HttpContext.Response.WriteAsync("Too Many Requests");
    };

    options.AddPolicy("TenantPolicy", context =>
    {
        var tenantResolver =
            context.RequestServices.GetRequiredService<TenantResolver>();

        var tenantId = tenantResolver.ResolveTenant();
        var limit = GetTenantLimit(tenantId);

        return RateLimitPartition.GetTokenBucketLimiter(
            tenantId,
            _ => new TokenBucketRateLimiterOptions
            {
                TokenLimit = limit,
                TokensPerPeriod = limit,
                ReplenishmentPeriod = TimeSpan.FromMinutes(1),
                AutoReplenishment = true
            });
    });
});

RateLimitPartition.GetTokenBucketLimiter(...) is the throttling engine using fully native ASP.NET Core 10.

While at the top, add the GetTenantLimit method:

static int GetTenantLimit(string tenantId)
{
    return tenantId switch
    {
        "tenantA" => 10, // Premium tenant
        "tenantB" => 5,  // Standard tenant
        _ => 2           // Default / anonymous
    };
}

We are defining the maximum request per minute for each client by extracting tenantId from the header of a request. GetTenantLimit is kept hard-coded to simplify our implementation. In real scenarios, you will use a Redis cache or database for that.

Step 6: Add controller

Our controller is as follows:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.RateLimiting;

namespace Net10RateLimiter.Controllers;

[EnableRateLimiting("TenantPolicy")]
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<string> Get()
        => ["Sunny", "Windy", "Breezy"];
}

The attribute [EnableRateLimiting("TenantPolicy")] associates our tenant policy with the controller.

Step 7: Enable the Middleware

Insert rate limiter middleware:

var app = builder.Build();

app.UseRateLimiter();

app.MapControllers();

app.Run();

Make sure to add this just before controllers, so it blocks the request before hitting the controller if the rate limit exceeds.

Our final Program.cs looks like this:

using System.Threading.RateLimiting;
using Net10RateLimiter.Services;

static int GetTenantLimit(string tenantId)
{
    return tenantId switch
    {
        "tenantA" => 10, // Premium tenant
        "tenantB" => 5,  // Standard tenant
        _ => 2           // Default / anonymous
    };
}

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();
builder.Services.AddControllers();
// Required for HttpContext access
builder.Services.AddHttpContextAccessor();

// Tenant resolver must be scoped
builder.Services.AddScoped<TenantResolver>();
builder.Services.AddRateLimiter(options =>
{
    options.OnRejected = async (context, token) =>
    {
        context.HttpContext.Response.StatusCode = 429;
        await context.HttpContext.Response.WriteAsync("Too Many Requests");
    };

    options.AddPolicy("TenantPolicy", context =>
    {
        var tenantResolver =
            context.RequestServices.GetRequiredService<TenantResolver>();

        var tenantId = tenantResolver.ResolveTenant();
        var limit = GetTenantLimit(tenantId);

        return RateLimitPartition.GetTokenBucketLimiter(
            tenantId,
            _ => new TokenBucketRateLimiterOptions
            {
                TokenLimit = limit,
                TokensPerPeriod = limit,
                ReplenishmentPeriod = TimeSpan.FromMinutes(1),
                AutoReplenishment = true
            });
    });
});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.UseRateLimiter();

app.MapControllers();
app.Run();

And the file structure looks like this:

Step 8: Run and test

dotnet run

Let us test this in Postman. Tenant A can call the endpoint:

So can Tenant B:

Once Tenant A reached the limit

Once tenant B reached the limit, you will see the endpoint returning a status code of 429, meaning too many requests:

What has .NET 10 improved in the rate limiter?

.NET 10 has changed the game of rate limiter in many ways, such as:

• While .NET 8 introduced native rate-limiting, .NET 10 improved throttling middleware, eliminating verbose and third-party reliance. You can simply use AddRateLimiter and add UseRateLimiter to the pipeline now.
• Earlier, developers had to implement counter expiration, sliding windows, and token buckets for handling race conditions and concurrency-safe code. The practice was tiring and risky to maintain. .NET 10 flattens these jobs.
• Rate limiting was mostly IP-based with no native concept of tenants. If you had to design it for a SaaS multitenant application, you would have to do it manually. In .NET 10, partitioned rate limiters allow each tenant to have an isolated limiter, preventing noisy-neighbor issues by design.
• Scalability of rate limiting demands Redis, distributed locks, and careful atomic operations with prior .NET versions. .NET 10 relieved the pain with its optimized high concurrency ability.
• Custom logic and third-party usage in rate limiting caused extra overhead and performance penalty. .NET 10, with its allocation-efficient and optimized middleware, runs efficiently and fast.

Conclusion

.NET 10 was released in November 2025 and is supported for three years as a long-term support (LTS) release. It brings the latest version of C# with many refinements. In this blog post for our .NET 10 and C# 14 series, we discovered refinements in the rate limiter and throttling middleware. Built-in support and middleware native implementation have improved the maintainability and performance of rate limiters.

Code: https://github.com/elmahio-blog/Net10RateLimiter.git

.NET 10 is officially out, along with C# 14. Microsoft has released .NET 10 as Long-Term Support (LTS) as a successor to .NET 8. Like every version, it is not just an update but brings something new to the table. In this series, we will explore which aspects of software can be upgraded with the latest release.

Model validation is a constant performance "tax" on every request, yet it remains non-negotiable for ensuring data integrity and a good user experience. While developers once faced a trade-off between strict validation and high throughput, .NET 10 eliminates this friction. In this post, I'll examine the benchmarks to see how these shifts dramatically reduce latency in .NET 10.

APIs Model Validation Benchmarking with .NET 8 and .NET 10

To start testing the improvements, I have created a solution named ValidationBenchmarks where three projects will reside. The structure looks like this:

.NET 8 API project

The project will contain an API with a single endpoint. Let's create it.

Step 1: Create a .NET 8 project

mkdir ApiNet8
cd ApiNet8

dotnet new webapi -n ApiNet8 --framework net8.0

Step 2: Create DTO (validation target)

using System.ComponentModel.DataAnnotations;

namespace ApiNet8.Models;

public sealed class CreateDeviceRequest
{
    [Required]
    public string DeviceId { get; set; } = default!;

    [Range(-40, 85)]
    public double Temperature { get; set; }

    [Range(0, 100)]
    public int BatteryLevel { get; set; }

    [Required]
    public DateTime Timestamp { get; set; }
}

The model is a minimal representation of telemetry data where DeviceId and Timestamp are mandatory while Temperature and BatteryLevel are restricted to be in a valid range.

Step 3: Create controller

using ApiNet8.Models;
using Microsoft.AspNetCore.Mvc;

namespace ApiNet8.Controllers;

[ApiController]
[Route("devices")]
public class DevicesController : ControllerBase
{
    [HttpPost]
    public IActionResult Create(CreateDeviceRequest request)
    {
        return Ok(new { Message = "Device accepted (.NET 8)" });
    }
}

The controller contains a single POST endpoint to create a device. The method takes our model as input.

Step 4: Configure Progam.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.MapControllers();
app.Run();

If you have create a MVC API before, you will see nothing different from the default template here.

.NET 10 API project

Let's create a similar project for .NET 10.

Step 1: Create a .NET 10 project

mkdir ApiNet10
cd ApiNet10

dotnet new webapi -n ApiNet10 --framework net10.0

Steps 2, 3, and 4 are exactly the same as from the .NET 8 steps.

Benchmark project

Once we have set up both target projects, we will set up a benchmark to evaluate them.

Step 1: Create the project

Our benchmark project will be a console application using the BenchmarkDotNet package.

dotnet new console -n ApiBenchmarks
cd ApiBenchmarks

Step 2: Install the BenchmarkDotNet package

dotnet add package BenchmarkDotNet

For more information about benchmarking, check out How to Monitor Your App's Performance with .NET Benchmarking.

Step 3: Add Benchmarking code

using System.Text;
using BenchmarkDotNet.Attributes;

namespace ApiBenchmarks;
[MemoryDiagnoser]
public class ValidationBenchmarks
{
    private HttpClient _client8 = default!;
    private HttpClient _client10 = default!;
    private StringContent _invalidPayload = default!;

    [GlobalSetup]
    public void Setup()
    {
        _client8 = new HttpClient
        {
            BaseAddress = new Uri("http://localhost:5008")
        };

        _client10 = new HttpClient
        {
            BaseAddress = new Uri("http://localhost:5010")
        };

        var json = """
                   {
                       "deviceId": "",
                       "temperature": 120,
                       "batteryLevel": 150,
                       "timestamp": null
                   }
                   """;

        _invalidPayload = new StringContent(
            json,
            Encoding.UTF8,
            "application/json"
        );
    }

    [Benchmark]
    public async Task Net8_Invalid_Model()
        => await _client8.PostAsync("/devices", _invalidPayload);

    [Benchmark]
    public async Task Net10_Invalid_Model()
        => await _client10.PostAsync("/devices", _invalidPayload);
}

Here, I initialized two clients, _client8 for calling the API of the .NET 8 project and _client10 to call the endpoint of the .NET 10 project. To represent an invalid payload, I created an _invalidPayload field. To test the worst case, I violated all the validations.

Step 4: Call the benchmark in Program.cs

using ApiBenchmarks;
using BenchmarkDotNet.Running;

BenchmarkRunner.Run<ValidationBenchmarks>();

Step 5: Run the projects

Open 3 terminals, on the first one run

cd ApiNet8
dotnet run --urls "http://localhost:5100"

Run the following on the Second one

cd ApiNet10
dotnet run --urls "http://localhost:5200"

While on the third one

cd ApiBenchmarks
dotnet run -c Release

So each of the API will be running on the designated port.

Result

Let's break down how .NET performed about 3x faster in several ways.

• Earlier model validation relied heavily on reflection, such as discovering attributes like [Required], [Range], and [StringLength]. Applying reflection on properties adds to the time. .NET 10 generates validation metadata at build time and replaces reflection with precomputed accessors. This actually saves a runtime check that happened earlier due to reflection.
• .NET 10 uses Span<T> where possible, and avoids LINQ in hot paths.
• Attributes executed as object-oriented (OO) components, relying on virtual method calls and object-based values in prior versions. Classes provide a flexible solution, but they were expensive to the CPU. .NET 10 precomputes validation metadata and replaces virtual, object-based execution with direct, typed method calls. That means the .NET 10 keeps validation attributes as an OO API but replaces their runtime execution with precomputed, direct calls that are cheaper for the CPU.
• During attribute invocation, expensive boxed values were used along with context objects. .NET 10 eliminated boxing for value types and introduced a shared validation context where safe.
• .NET 10 replaced repeated metadata traversal of evaluating each attribute and building ModelState entries with fewer temporary strings, lazy creation of error messages, and smarter reuse of ModelError objects. This ensured low GC pressure and better stability of latency. The provision helps in APIs where validation errors often occur, such as auth endpoints, ingestion APIs, and public APIs.
• .NET 10 has better p95 / p99 latency, less jitter, more predictable execution, fewer unpredictable branches, and less runtime metadata walking. The results are visible in StdDev, which is 3x less than its counterpart.

Conclusion

.NET 10 is released in November 2025 and is supported for three years as a long-term support (LTS) release. It brings the latest version of C# with many refinements. In the blog post for our .NET 10 and C# 14 series, I highlighted improvements to the model validations. .NET 10 has changed the nature of the validation process from reflection to precomputed, faster calls. We saw a dramatic cut down of 3x in parameters like StdDev and Error due to better p99 latency and less jittering in the latest version.

Code: https://github.com/elmahio-blog/ValidationBenchmarks

.NET 10 is officially out, along with C# 14. Microsoft has released .NET 10 as Long-Term Support (LTS) as a successor to .NET 8. Like every version, it is not just an update but brings something new to the table. In this series, we will explore which aspects of software can be upgraded with the latest release. Today, in the series of What is new in .NET 10 and C#14, we will evaluate on-ground changes in the APIs using minimal examples.

APIs don't need any introduction. From loading the cart to your mobile to showing this blog on your computer, everything is fetched by APIs. In today's dynamic websites, a simple action requires multiple API calls. So, a simple lag can hurt users' experience, no matter what application you build. .NET 10 brings some thoughtful changes for APIs. Some major improvements, like JIT inlining and lower GC burden, made things faster across operations. However, there are enhancements in API pipelining as well. Let's observe how API operations are improved in .NET 10.

Benchmarking Minimal APIs with .NET 8 and .NET 10

I have created a directory MinimalApiComparison where three projects will reside. Consider the structure:

One folder per API version and another for the benchmarks.

.NET 8 minimal API project

Let's start by creating a minimal API on .NET 8.

Step 1: Create a .NET 8 project

mkdir ApiNet8
cd ApiNet8

dotnet new webapi -n ApiNet8 --framework net8.0

Step 2: Set up the code

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/weather", () =>
{
    return new WeatherForecast(DateTime.Now, 25, "Sunny");
});

app.Run();

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

Just a single endpoint named /weather.

.NET 10 Minimal API project

Now, let's set up a similar project for .NET 10.

Step 1: Create a .NET 10 project

mkdir ApiNet10
cd ApiNet10

dotnet new webapi -n ApiNet10 --framework net10.0

Step 2: Set up the code

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureHttpJsonOptions(o =>
{
    o.SerializerOptions.AllowOutOfOrderMetadataProperties = true;
});

var app = builder.Build();

app.MapGet("/weather", static () =>
    {
        return new WeatherForecast(DateTime.Now, 25, "Sunny");
    })
    .WithName("GetWeather")
    .WithSummary("Faster pipeline in .NET 10");

app.Run();

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

The property AllowOutOfOrderMetadataProperties allows skipping strict ordering checks in JSON deserialization. It is an optimisation step that reduces parsing branches in compilation and speeds up model binding. static () => Prevents closure allocation by restricting the lambda from capturing variables. In preceding versions, lambda saves the inner variable in Gen 0 memory. While in the latest updates, static lambda results in 0 allocation and a faster, memory-efficient API.

Benchmark project

Once we set up both target projects, let us move to the benchmark to evaluate them.

Step 1: Create the project

Our benchmark project will be a console application.

dotnet new console -n ApiBenchmarks
cd ApiBenchmarks

Step 2: Install the BenchmarkDotNet package

We are using `BenchmarkDotNet to observe the results. For more information about this package, check out How to Monitor Your App's Performance with .NET Benchmarking.

dotnet add package BenchmarkDotNet

Step 3: Set up the URLs benchmarking code

using System.Net.Http.Json;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Order;

[MemoryDiagnoser]
[SimpleJob(warmupCount: 3, iterationCount: 10)]
[Orderer(SummaryOrderPolicy.FastestToSlowest)]
public class ApiComparisonBenchmarks
{
    private readonly HttpClient _client8;
    private readonly HttpClient _client10;

    public ApiComparisonBenchmarks()
    {
        _client8 = new HttpClient { BaseAddress = new Uri("http://localhost:5100") };
        _client10 = new HttpClient { BaseAddress = new Uri("http://localhost:5200") };
    }

    [Benchmark]
    public async Task WeatherNet8()
    {
        var result = await _client8.GetFromJsonAsync<WeatherForecast>("/weather");
    }

    [Benchmark]
    public async Task WeatherNet10()
    {
        var result = await _client10.GetFromJsonAsync<WeatherForecast>("/weather");
    }
}

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

I created two methods WeatherNet8 to hit the .NET 8 minimal API and WeatherNet10 for the .NET 10 version. I have specified server URLs with each client explicitly. The [Benchmark] decorator will do the rest of the job.

Step 4: Run the projects

Open 3 terminals, on the first one run:

cd ApiNet8
dotnet run --urls "http://localhost:5100"

Run the following on the second one:

cd ApiNet10
dotnet run --urls "http://localhost:5200"

While on the third one:

cd ApiBenchmarks
dotnet run -c Release

So each of the API will be running on the designated port. ApiBenchmark hits its endpoint at /weather and performs benchmarking.

Output

We can observe a difference in the same api of both projects. .NET 10 did the job quite fast, and other parameters are also lower, indicating the performance improvements in the latest version. .NET 10 has 3x smaller Standard deviation and error due to less jitter in execution times by the grace of JIT improvements and JSON parsing novelty. Pipeline configurations like AllowOutOfOrderMetadataProperties and static () => reduced the per-request overhead. AllowOutOfOrderMetadataProperties lowers CPU burden and reduces System.Text.Json paths in compilation. And static lambda not only eliminated closure allocation but made the delegate work faster with lower Garbage Collector pressure.

Our big win was not only in the pipeline configuration but also in faster request-response improvements in ASP.NET Core. .NET 10 has optimized middleware dispatch overhead, added static pipeline analysis and faster endpoint selection, resulting in lower mean and tail latency. Our observation was just on a minimal API with small objects. These enhancements will bring noticeable results when you work on real projects with larger API operations.

Conclusion

.NET 10 is released in November 2025 and is supported for three years as a long-term support (LTS) release. For the APIs pipeline, .NET 10 brought key enhancements. In this post, I showed these enhancements with on-ground benchmark analysis. Better JIT inlining, lower CPU and GC pressure, and numerous other factors have contributed to better APIs.

Source code: https://github.com/elmahio-blog/MinimalApiComparison-.git