Forem: Anton Martyniuk

How to Build a Production-Ready Invoice Builder in .NET Using IronPDF

Anton Martyniuk — Sat, 06 Dec 2025 19:09:17 +0000

Today, I want to show you how to build a production-ready invoice builder application.

We will build an app that helps clients create, manage, and download invoices from business data.
It turns orders and customer records into branded documents with accurate taxes, totals, and payment terms, and provides users with clear actions, such as previews and PDF downloads.

In production, it must be reliable and consistent, and produce PDFs that are easy to store and easy to read on any device.

Invoice Builder requirements

Business requirements:

Create Invoice Customers and Senders
Create Invoices: Invoice & Date details, existing Customer and Sender data, line items
Generate and download Invoice PDF files

PDF requirements:

Consistent layout at any length: a single item or hundreds of rows should paginate cleanly.
Accurate rendering and stable formatting on any device.
High-quality rendering with crisp text, logos, and tables suitable for printing or archiving.
PDF/UA compliance for long-term storage and audit needs.
Digital signatures to prove integrity and origin, with an optional visible signature appearance.
Fully managed, cross-platform runtime with fast generation and small operational overhead.

UI Features:

Home Screen:
- Tabs: Invoices, Customers, Senders
Invoices:
- List paged invoices in a table view
- Create new invoices
- Table actions: View, Edit, Delete (with confirmation), Download PDF
Customers:
- List paged customers in a table view
- Create new customers
- Table actions: View, Edit, Delete (with confirmation)
Senders:
- List paged senders in a table view
- Create new senders
- Table actions: View, Edit, Delete (with confirmation)

Implementation Tech Stack:

Backend:

ASP .NET Core 10, EF Core, IronPDF for generating PDFs

Frontend:

React, TypeScript, TailwindCSS

Architecture:

Modular Monolith
Vertical Slice Architecture + Clean Architecture

Database:

PostgreSQL

Deployment:

Docker Compose

Let's dive into the implementation details.

Invoice Builder UI Overview

To better understand how the Invoice Builder app works, let's take a look at the UI screens.

Here is the Home Screen with Invoices, Customers, and Senders tabs:

The Invoices tab shows a list of invoices with actions such as View, Edit, Delete, and Download PDF.

To create a new invoice, we need to create a Customer and a Sender first.

Now we can create an invoice. We need to fill the following fields:

Invoice Details (Number, Dates, Tax Rate, Notes, etc.)
Sender Info
Customer Info
Line Items

We need to select a Customer and Sender from the dropdowns.

After we click "Create Invoice", the invoice is created and stored in the database.

You can download the PDF file by clicking the "Download PDF" button on the invoice details page or the Invoices list page.

Now, let's explore the options we have for generating the PDF file.

Selecting C# PDF Library for Invoice Generation

There are multiple options for generating PDFs in C# and ASP.NET Core:

IronPDF
QuestPDF
Aspose.PDF
PuppeteerSharp

Let's briefly explore each of them and compare their pros and cons.

IronPDF

IronPDF is a powerful .NET library for creating, editing, signing, and rendering PDFs.
It is designed to be developer-friendly: many complex tasks in raw PDF APIs or lower-level tools are easier with IronPDF via a more fluent, higher-level API.

IronPDF pros:

HTML, DOCX, RTF, XML, MD, Image to PDF Conversion
PDF FROM URL, PDF to HTML
Compliant to PDF/A, PDF/UA, and PDF/X standards
Fully managed and cross-platform
High-performance rendering
Digital Signatures & Security
Rich PDF Manipulation (edit, merge, split PDFs)
Good documentation

IronPDF cons:

Requires a paid license for commercial use.

QuestPDF

QuestPDF is a popular open-source PDF generation library for .NET developers.
Its primary goal is to simplify PDF creation through a C# fluent API.

QuestPDF pros:

Fluent C# API — build documents directly in code using a layout-based approach.
Consistent layouts — predictable, repeatable output for structured documents.
Good documentation with many examples and patterns for reports.
Free for commercial use for small companies.

QuestPDF cons:

Missing HTML-to-PDF conversion — unable to convert HTML content directly into PDFs, limiting versatility in web applications.
Missing Compliance standards — no built-in support for PDF/A (archival) or PDF/UA (accessibility).
Missing Digital signatures or security — no native features for signing, password protection, or permissions.
Missing Interactive forms or JavaScript rendering — limited scope to static layouts only.
Requires a paid license for commercial use for larger companies.

Aspose.PDF

Aspose.PDF provides advanced capabilities for programmatic PDF creation.
It gives developers extensive control over document elements, including paragraphs, tables, images, forms, and annotations.

Aspose.PDF pros:

Extensive programmatic control over PDF elements (paragraphs, tables, images, forms, annotations).
Advanced PDF manipulation features for complex document workflows.
Support for PDF/A standards and digital signatures.
Mature library with a long track record in enterprise environments.

Aspose.PDF cons:

Verbose API requiring detailed coding even for simple tasks, leading to a steeper learning curve.
Limited HTML-to-PDF conversion — lacks native Chromium engine, resulting in rendering limitations.
No JavaScript execution support for dynamic content rendering.
Slower performance and higher memory usage compared to Chromium-based alternatives (like IronPDF).
Expensive licensing with higher pricing tiers compared to competitors.

PuppeteerSharp

Puppeteer Sharp is a .NET port of the official Node.js Puppeteer API.

It lets you drive Chromium/Chrome from C# over the DevTools Protocol:
open pages, run JavaScript, wait for selectors, take screenshots, and print pages to PDF.

It runs headless by default and can also connect to a remote browser.

PuppeteerSharp pros:

Easy API to create PDFs using Chrome Engine
Open-source and free for commercial use

PuppeteerSharp cons:

Puppeteer-Sharp is a browser automation library, and not a .NET-native PDF SDK. While it excels at rendering HTML into PDFs, it is not a full-featured .NET PDF SDK.
Missing Compliance standards — no built-in support for PDF/A (archival) or PDF/UA (accessibility).
Missing Digital signatures or security — no native features for signing, password protection, or permissions.
Missing PDF editing — no tools for merging, splitting, or modifying existing PDFs.

Why IronPDF is the Best Choice for Invoice Builder Application

I have personally tested all the libraries, and my preferred choice for commercial projects is IronPDF.

For an invoice builder application, it's a perfect choice because it meets all our requirements:

Consistent layout at any length: a single item or hundreds of rows should paginate cleanly.
Accurate rendering and stable formatting on any device.
High-quality rendering with crisp text, logos, and tables suitable for printing or archiving.
PDF/A-3b compliance for long-term storage and audit needs.
Digital signatures to prove integrity and origin, with an optional visible signature appearance.
Fully managed, cross-platform runtime with fast generation and small operational overhead.

QuestPDF and PuppeteerSharp don't meet these requirements.

Aspose can be an alternative, but IronPDF is better in HTML-to-PDF conversion, is faster and uses less memory.
Also, IronPDF offers a license at a much more affordable price.

Now let's explore how we can generate the invoice PDF file on the backend, using IronPDF.

Generating Invoice PDFs with IronPDF

IronPDF has a quick learning curve, just 5 minutes from getting started to generating the first PDF.

First, you need to install the following NuGet package:

dotnet add package IronPdf

With IronPDF, you can create a PDF document from HTML content in just three lines of code:

using IronPdf;

var htmlContent = @"
<html>
<head>
    <style>
        h1 { color: blue; }
        p { font-size: 16px; }
    </style>
</head>
<body>
    <h1>Invoice 1000471</h1>
    <p>Test invoice</p>
</body>
</html>";

// Create a PDF from HTML content
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("Invoice.pdf");

Creating PDF documents from HTML content is pretty easy.
But how can we quickly generate a rich, professional-looking HTML invoice document in ASP.NET Core?

For this purpose, we can use Razor views.
They are used in ASP.NET Core MVC, Razor Pages and Blazor applications.

Razor views have a .cshtml extension and allow you to use C# inside the HTML markup.

Let's build the Invoice PDF document using Razor views.

You need to install the additional NuGet package:

dotnet add package Razor.Templating.Core

Razor.Templating.Core package allows you to use Razor views in any assembly, even in a class library, so you don't need to create an ASP.NET Core MVC application.

Here is our set of Invoice models:

public sealed record InvoiceResponse(
    Guid Id,
    string InvoiceNumber,
    DateTime InvoiceDate,
    DateTime DueDate,
    string Currency,
    string Notes,
    CustomerResponse Customer,
    SenderResponse Sender,
    List<InvoiceLineItemResponse> LineItems,
    decimal Subtotal,
    decimal TaxRate,
    decimal TotalAmount
);

public sealed record CustomerResponse(
    Guid Id,
    string CompanyName,
    string CustomerName,
    string CustomerAddress,
    string PostalCode,
    string CustomerEmail,
    string CustomerTaxVatId
);

public sealed record SenderResponse(
    Guid Id,
    string SenderCompanyName,
    string SenderFullName,
    string SenderAddress,
    string SenderTaxVatId,
    string BankDetails
);

public sealed record InvoiceLineItemResponse(
    Guid Id,
    string ItemName,
    decimal Quantity,
    decimal UnitPrice,
    decimal Total
);

For styling, we can use Tailwind CSS, which simplifies CSS and makes it easier to create responsive layouts.

Let's create an InvoiceTemplate.cshtml file in the Views folder:

@model Modules.Invoices.Features.Features.Shared.Responses.InvoiceResponse

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Invoice @Model.InvoiceNumber</title>
    <script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="bg-white">
    <div class="max-w-4xl mx-auto p-8">
        <!-- Header -->
        <div class="flex justify-between items-start mb-8">
            <div>
                <h1 class="text-4xl font-bold text-gray-900 mb-2">INVOICE</h1>
                <p class="text-lg text-gray-600">@Model.InvoiceNumber</p>
            </div>
            <div class="text-right">
                <p class="text-sm text-gray-600">Invoice Date</p>
                <p class="text-lg font-semibold text-gray-900">@Model.InvoiceDate.ToString("MMM dd, yyyy", System.Globalization.CultureInfo.InvariantCulture)</p>
                <p class="text-sm text-gray-600 mt-2">Due Date</p>
                <p class="text-lg font-semibold text-red-600">@Model.DueDate.ToString("MMM dd, yyyy", System.Globalization.CultureInfo.InvariantCulture)</p>
            </div>
        </div>

        <!-- Sender and Customer Information -->
        <div class="grid grid-cols-2 gap-8 mb-8">
            <!-- From (Sender) -->
            <div class="bg-gray-50 p-6 rounded-lg">
                <h2 class="text-sm font-semibold text-gray-500 uppercase mb-3">From</h2>
                <div class="space-y-1">
                    <p class="text-lg font-bold text-gray-900">@Model.Sender.SenderCompanyName</p>
                    <p class="text-gray-700">@Model.Sender.SenderFullName</p>
                    <p class="text-gray-600 text-sm">@Model.Sender.SenderAddress</p>
                    <p class="text-gray-600 text-sm mt-2">
                        <span class="font-semibold">VAT/Tax ID:</span> @Model.Sender.SenderTaxVatId
                    </p>
                    <div class="mt-3 pt-3 border-t border-gray-300">
                        <p class="text-xs text-gray-500 uppercase font-semibold mb-1">Bank Details</p>
                        <p class="text-sm text-gray-700">@Model.Sender.BankDetails</p>
                    </div>
                </div>
            </div>

            <!-- To (Customer) -->
            <div class="bg-blue-50 p-6 rounded-lg">
                <h2 class="text-sm font-semibold text-blue-700 uppercase mb-3">Bill To</h2>
                <div class="space-y-1">
                    <p class="text-lg font-bold text-gray-900">@Model.Customer.CompanyName</p>
                    <p class="text-gray-700">@Model.Customer.CustomerName</p>
                    <p class="text-gray-600 text-sm">@Model.Customer.CustomerAddress</p>
                    <p class="text-gray-600 text-sm">@Model.Customer.PostalCode</p>
                    <p class="text-gray-600 text-sm mt-2">
                        <span class="font-semibold">Email:</span> @Model.Customer.CustomerEmail
                    </p>
                    <p class="text-gray-600 text-sm">
                        <span class="font-semibold">VAT/Tax ID:</span> @Model.Customer.CustomerTaxVatId
                    </p>
                </div>
            </div>
        </div>

        <!-- Line Items Table -->
        <div class="mb-8">
            <table class="w-full border-collapse">
                <thead>
                    <tr class="bg-gray-800 text-white">
                        <th class="text-left py-3 px-4 font-semibold text-sm">Item Description</th>
                        <th class="text-right py-3 px-4 font-semibold text-sm">Quantity</th>
                        <th class="text-right py-3 px-4 font-semibold text-sm">Unit Price</th>
                        <th class="text-right py-3 px-4 font-semibold text-sm">Total</th>
                    </tr>
                </thead>
                <tbody>
                    @foreach (var item in Model.LineItems)
                    {
                        <tr class="border-b border-gray-200 hover:bg-gray-50">
                            <td class="py-3 px-4 text-gray-900">@item.ItemName</td>
                            <td class="text-right py-3 px-4 text-gray-700">@item.Quantity.ToString("N2")</td>
                            <td class="text-right py-3 px-4 text-gray-700">@item.UnitPrice.ToString("N2") @Model.Currency</td>
                            <td class="text-right py-3 px-4 font-semibold text-gray-900">@item.Total.ToString("N2") @Model.Currency</td>
                        </tr>
                    }
                </tbody>
            </table>
        </div>

        <!-- Totals Section -->
        <div class="flex justify-end mb-8">
            <div class="w-80">
                <div class="bg-gray-50 p-6 rounded-lg space-y-3">
                    <div class="flex justify-between items-center">
                        <span class="text-gray-700">Subtotal</span>
                        <span class="text-lg font-semibold text-gray-900">@Model.Subtotal.ToString("N2") @Model.Currency</span>
                    </div>
                    <div class="flex justify-between items-center">
                        <span class="text-gray-700">Tax (@(Model.TaxRate.ToString("N2"))%)</span>
                        <span class="text-lg font-semibold text-gray-900">@((Model.TotalAmount - Model.Subtotal).ToString("N2")) @Model.Currency</span>
                    </div>
                    <div class="border-t-2 border-gray-300 pt-3">
                        <div class="flex justify-between items-center">
                            <span class="text-xl font-bold text-gray-900">Total Amount</span>
                            <span class="text-2xl font-bold text-blue-600">@Model.TotalAmount.ToString("N2") @Model.Currency</span>
                        </div>
                    </div>
                </div>
            </div>
        </div>

        <!-- Notes Section -->
        @if (!string.IsNullOrWhiteSpace(Model.Notes))
        {
            <div class="bg-yellow-50 border-l-4 border-yellow-400 p-4 mb-8">
                <h3 class="text-sm font-semibold text-gray-700 uppercase mb-2">Notes</h3>
                <p class="text-gray-700 text-sm">@Model.Notes</p>
            </div>
        }

        <!-- Footer -->
        <div class="border-t-2 border-gray-300 pt-6 text-center">
            <p class="text-sm text-gray-600">Thank you for your business!</p>
            <p class="text-xs text-gray-500 mt-2">This is a computer-generated invoice and does not require a signature.</p>
        </div>
    </div>
</body>
</html>

Then we call RazorTemplateEngine.RenderAsync to dynamically render the HTML content from a Razor view:

public sealed class InvoicePdfGenerator : IInvoicePdfGenerator
{
    private const string InvoiceTemplatePath = "~/Views/Invoice/InvoiceTemplate.cshtml";
    private const int DefaultMargin = 10;

    public async Task<byte[]> GeneratePdfAsync(InvoiceResponse invoice)
    {
        var html = await RazorTemplateEngine.RenderAsync(InvoiceTemplatePath, invoice);

        var renderer = CreatePdfRenderer();
        var pdf = await renderer.RenderHtmlAsPdfAsync(html);

        return pdf.BinaryData;
    }
}

Here we use the ChromePdfRenderer class from IronPDF to generate a PDF document:

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);

The InvoicePdfGenerator is used in the DownloadInvoiceHandler, which reads the invoice from the database and generates the PDF document:

internal sealed class DownloadInvoiceHandler(
    InvoicesDbContext context,
    IInvoicePdfGenerator pdfGenerator)
    : IDownloadInvoiceHandler
{
    public async Task<Result<InvoicePdfResponse>> HandleAsync(
        Guid id,
        CancellationToken cancellationToken)
    {
        var invoice = await context.Invoices
            .Include(x => x.Customer)
            .Include(x => x.Sender)
            .Include(x => x.Items)
            .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);

        if (invoice is null)
        {
            return InvoiceErrors.NotFound(id);
        }

        var invoiceResponse = invoice.MapToResponse();

        var pdfBytes = await pdfGenerator.GeneratePdfAsync(invoiceResponse);

        var fileName = $"Invoice_{invoice.InvoiceNumber}_{DateTime.UtcNow:yyyyMMdd}.pdf";

        return new InvoicePdfResponse(pdfBytes, fileName);
    }
}

We can use the Results.File with contentType: "application/pdf" to download the file from the ASP .NET Core Minimal API endpoint:

public class DownloadInvoiceApiEndpoint : IApiEndpoint
{
    public void MapEndpoint(WebApplication app)
    {
        app.MapGet(RouteConsts.Download, Handle);
    }

    private static async Task<IResult> Handle(
        Guid id,
        IDownloadInvoiceHandler handler,
        CancellationToken cancellationToken)
    {
        var response = await handler.HandleAsync(id, cancellationToken);
        if (response.IsError)
        {
            return response.Errors.ToProblem();
        }

        var pdfData = response.Value!;

        return Results.File(
            fileContents: pdfData.FileBytes,
            contentType: "application/pdf",
            fileDownloadName: pdfData.FileName);
    }
}

Here is what the downloaded report looks like:

This invoice looks good and professional.

Now let's explore how we can add PDF/UA Compliance to the generated PDF.

Generating Compliant PDFs with IronPDF

For invoices, regulations and accessibility standards often require that documents follow strict formats.
Two of the most important standards are PDF/A and PDF/UA.

PDF/A (PDF for Archiving) ensures that a document can be stored long-term without losing fonts, colors, or layout.
It is often required for contracts, invoices, and government filings.

PDF/UA (Universal Accessibility) ensures that a document is accessible to everyone, including individuals who rely on screen readers or other assistive technologies.
This is important for accessibility compliance.

With IronPDF, you can create both PDF/A and PDF/UA documents in just a few lines of code.
It uses the Chromium engine to render HTML and CSS, then exports the result into the required compliant format.

You can convert the rendered HTML into PDF/A or PDF/UA using the ConvertToPdfA or ConvertToPdfUA methods:

using IronPdf;

var renderer = CreatePdfRenderer();

var pdf = await renderer.RenderHtmlAsPdfAsync(html);
pdf = pdf.ConvertToPdfUA();

And let the user download the compliant PDF file.

Now let's explore the final piece of the puzzle: adding a digital signature to the generated PDF.

Adding a Digital Signature to PDF with IronPDF

Invoices often need a signature to prove integrity and origin.

There are two parts you can combine:

A visual mark inside the PDF (a stamp or signature block) so the human reader sees a signed area.
A cryptographic digital signature that a PDF reader can verify.

Let's explore how we can add a visual signature with a sender name to the generated PDF:

using IronPdf;

var renderer = CreatePdfRenderer();
var pdf = await renderer.RenderHtmlAsPdfAsync(html);

AddSignatureToPdf(pdf, invoice.Sender.SenderFullName);

private void AddSignatureToPdf(PdfDocument pdf, string senderFullName)
{
    var signatureText = $"Digitally signed by: {senderFullName}";

    var stamp = new IronPdf.Editing.TextStamper
    {
        Text = signatureText,
        FontFamily = "Arial",
        FontSize = 20,
        IsBold = false,
        IsItalic = true,
        VerticalAlignment = IronPdf.Editing.VerticalAlignment.Bottom,
        HorizontalAlignment = IronPdf.Editing.HorizontalAlignment.Right,
        Opacity = 100,
        Rotation = 0
    };

    pdf.ApplyStamp(stamp);

    logger.LogDebug("Added signature to PDF: {SignatureText}", signatureText);
}

This code adds a stamp with the sender's name to the bottom right corner of the PDF:

To add a real cryptographic signature, sign the document with a certificate (PFX).

This feature ensures your PDFs are secure for business, legal, and compliance purposes.

Digital signatures prove the authenticity of a document.

With IronPDF, you can sign using a certificate (.pfx or .p12) and add details like the signer's name, location, or even an image:

var renderer = CreatePdfRenderer();

var pdf = await renderer.RenderHtmlAsPdfAsync(html);
pdf = pdf.ConvertToPdfUA();

var signature = new PdfSignature("IronSoftware.pfx", "123456")
{
    SignatureDate = DateTime.Now,
    SigningContact = "cert@company.com",
    SigningLocation = "Chicago, USA",
    SigningReason = "Contractual Agreement",
    TimeStampUrl = "[http://timestamp.digicert.com](http://timestamp.digicert.com)",
    TimestampHashAlgorithm = TimestampHashAlgorithms.SHA256,
    SignatureImage = new PdfSignatureImage("assets/visual-signature.png", 0,
        new Rectangle(350, 750, 200, 100))
};

pdf.Sign(signature);

This ensures that the PDF cannot be changed without invalidating the signature.

For more information, refer to the official documentation.

Licensing

IronPDF follows a commercial licensing model.

Free trial available: You can start with a trial license to explore features.
Commercial licenses required for production: Businesses and organizations must obtain a license before deploying IronPDF in production.
Support and updates included: A license comes with access to updates, bug fixes, and professional technical support.

IronPDF provides enterprise-grade features, including PDF/A and PDF/UA compliance, digital signatures, and document security, which are often required in professional and regulated environments.

IronPDF offers a license at a much more affordable price and offers more benefits than Aspose, which is honestly very overpriced.

IronPDF offers the best support, helping developers quickly resolve issues — a feature that other PDF libraries often lack.

New Features in .NET 10 and C# 14

Anton Martyniuk — Tue, 11 Nov 2025 12:13:20 +0000

.NET 10 and C# 14 is out today (November 11, 2025).

As a Long-Term Support (LTS) release, .NET 10 will receive three years of support until November 14, 2028.
This makes it a solid choice for production applications that need long-term stability.

In this post, we will explore:

What's New in .NET 10
What's New in C# 14
What's New in ASP.NET Core in .NET 10
What's New in EF Core 10
Other Changes in .NET 10

Let's dive in!

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.

What's New in .NET 10

File-Based Apps

The biggest addition in .NET 10 is support for file-based apps.
This feature changes how you can write C# code for scripts and small utilities.

Traditionally, even the simplest C# application required three things: a solution file (sln), a project file (csproj), and your source code file (*.cs).
You would then use your IDE or the dotnet run command to build and run the app.

Starting with .NET 10, you can create a single *.cs file and run it directly:

dotnet run main.cs

This puts C# on equal with Python, JavaScript, TypeScript and other scripting languages.
This makes C# a good option for CLI utilities, automation scripts, and tooling, without a project setup.

File-based apps can reference NuGet packages and SDKs using special # directives at the top of your file.
This lets you include any library you need without a project file.

You can even create a single-file app that uses EF Core and runs a Minimal API:

#:sdk Microsoft.NET.Sdk.Web
#:package Microsoft.EntityFrameworkCore.Sqlite@9.0.0

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddDbContext<OrderDbContext>(options =>
{
    options.UseSqlite("Data Source=orders.db");
});

var app = builder.Build();

app.MapGet("/orders", async (OrderDbContext db) =>
{
    return await db.Orders.ToListAsync();
});

app.Run();
return;

public record Order(string OrderNumber, decimal Amount);

public class OrderDbContext : DbContext
{
    public OrderDbContext(DbContextOptions<OrderDbContext> options) : base(options) { }
    public DbSet<Order> Orders { get; set; }
}

You can also reference existing project files from your script:

#:project ../ClassLib/ClassLib.csproj

Cross-Platform Shell Scripts

You can write cross-platform C# shell scripts that are executed directly on Unix-like systems.
Use the #! directive to specify the command to run the script:

#!/usr/bin/env dotnet

Then make the file executable and run it:

chmod +x app.cs
./app.cs

Converting to a Full Project

When your script grows and needs more structure, you can convert it to a regular project using the dotnet project convert command:

dotnet project convert app.cs

Note: Support for file-based apps with multiple files will likely come in future .NET releases.

You can see the complete list of new features in .NET 10 here.

What's New in C# 14

C# 14 is one of the most significant releases in recent years.

Let's explore the key features:

Extension Members

Extension members are my favorite feature in C# 14. They represent a modern evolution of extension methods that have been part of C# since version 3.0.

Traditional Extension Method Syntax

Before C# 14, you created extensions by writing static methods with a this parameter:

public static class StringExtensions
{
    public static bool IsNullOrEmpty(this string value)
    {
        return string.IsNullOrEmpty(value);
    }

    public static string Truncate(this string value, int maxLength)
    {
        if (string.IsNullOrEmpty(value) || value.Length <= maxLength)
        {
            return value;
        }

        return value.Substring(0, maxLength);
    }
}

New Extension Keyword Syntax

The new syntax separates the receiver (the type you're extending) from the members you're adding. Instead of putting this on each method parameter, you declare an extension block that specifies the receiver once:

public static class StringExtensions
{
    extension(string value)
    {
        public bool IsNullOrEmpty()
        {
            return string.IsNullOrEmpty(value);
        }

        public string Truncate(int maxLength)
        {
            if (string.IsNullOrEmpty(value) || value.Length <= maxLength)
                return value;

            return value.Substring(0, maxLength);
        }
    }
}

The extension block takes the receiver as a parameter.
Inside the block, you write your methods and properties just like they were actual members of the type.
The value parameter is available to all members within the block.

Both old and a new syntax compile to identical code, so they work the same way. You can even use both styles in the same static class.

The new extension syntax supports:

Instance methods
Instance properties
Static methods
Static properties

Extension Properties

Extension properties make your code more readable and expressive. Instead of calling methods, you can use properties that feel more natural.

For example, when working with collections, you frequently check if they're empty.
Instead of writing !items.Any() everywhere, you can create an IsEmpty property:

public static class CollectionExtensions
{
    extension<T>(IEnumerable<T> source)
    {
        public bool IsEmpty => !source.Any();

        public bool HasItems => source.Any();

        public int Count => source.Count();
    }
}

public void ProcessOrders(IEnumerable<Order> orders)
{
    if (orders.IsEmpty)
    {
        Console.WriteLine("No orders to process");
        return;
    }

    foreach (var order in orders)
    {
        // Process order
    }
}

Private Fields and Caching

Inside an extension block, you can define private fields and methods, just like in a regular class.
This is useful when you need to cache expensive calculations:

public static class CollectionExtensions
{
    extension<T>(IEnumerable<T> source)
    {
        private List<T>? _materializedList;

        public List<T> MaterializedList => _materializedList ??= source.ToList();

        public bool IsEmpty => MaterializedList.Count == 0;

        public T FirstItem => MaterializedList[0];
    }
}

The backing field _materializedList ensures that ToList() is only called once, no matter how many times you access the properties.

Static Extension Members

Static extensions let you add factory methods or utility functions to a type, not the instance.
To create static extensions, use extension without naming the receiver parameter:

public static class ProductExtensions
{
    extension(Product)
    {
        public static Product CreateDefault() =>
            new Product
            {
                Name = "Unnamed Product",
                Price = 0,
                StockQuantity = 0,
                Category = "Uncategorized",
                CreatedDate = DateTime.UtcNow
            };

        public static bool IsValidPrice(decimal price) =>
            price >= 0 && price <= 1000000;

        public static string DefaultCategory => "General";
    }
}

You can call these static members directly on the type:

var product = Product.CreateDefault();
if (Product.IsValidPrice(999.99m))
{
    product.Price = 999.99m;
}

Null-Conditional Assignment

The null-conditional operators (?. and ?[]) can now be used for assignment, not just for accessing members.

Before C# 14, you needed an explicit null check before assigning to a property:

if (user is not null)
{
    user.Profile = LoadProfile();
}

Now you can simplify this using the ?. operator:

user?.Profile = LoadProfile();

This is cleaner and more consistent with how null-conditional operators work for reading values.

The Field Keyword

The field keyword eliminates the need for explicit backing fields in many common property scenarios.

Previously, you needed to declare a private backing field:

public class Record
{
    private string _msg;

    public string Message
    {
        get => _msg;
        set => _msg = value ?? throw new ArgumentNullException(nameof(value));
    }
}

With the field keyword, you can reference the compiler-generated backing field directly:

public class Record
{
    public string Message
    {
        get;
        set => field = value ?? throw new ArgumentNullException(nameof(value));
    }
}

You can use field in any accessor: get, set, or init.

If you already use "field" as a variable name in your code, you can avoid conflicts by using @field or this.field, or by renaming your existing variable.

The field keyword is particularly useful for lazy initialization and default values:

public class ConfigReader
{
    public string FilePath
    {
        get => field ??= "data/config.json";
        set => field = value;
    }

    public Dictionary<string, string> ConfigValues
    {
        get => field ??= new Dictionary<string, string>();
        set => field = value;
    }
}

This avoids declaring separate backing fields for FilePath and ConfigValues.

Lambda Parameters with Modifiers

C# 14 allows you to use parameter modifiers like out, ref, in, scoped, and ref readonly in lambda expressions without specifying parameter types.

Previously, you had to include complete type declarations when using modifiers:

delegate bool TryParse<T>(string text, out T result);

TryParse<int> parse = (string text, out int result) => Int32.TryParse(text, out result);

Now you can omit the types and let the compiler infer them:

delegate bool TryParse<T>(string text, out T result);

TryParse<int> parse = (text, out result) => Int32.TryParse(text, out result);

This makes lambda expressions more concise while maintaining type safety.

Partial Constructors and Events

C# 14 extends partial member support to include constructors and events. This is particularly useful for source generators.

Partial constructors must have one defining declaration and one implementing declaration:

public partial class User
{
    // This is the defining part
    public partial User(string name);
}

public partial class User
{
    // This is the implementing part
    public partial User(string name)
        : this() // Calls another constructor in the same class
    {
        Name = name;
    }

    public User() { }

    public string Name { get; set; }
}

Rules for partial constructors:

Only the implementing part can use this() or base() to call another constructor
Only one part of the class can use a primary constructor

Partial events also require one defining and one implementing declaration:

public partial class Downloader
{
    public partial event Action<string> DownloadCompleted;
}

public partial class Downloader
{
    public partial event Action<string> DownloadCompleted
    {
        add { }
        remove { }
    }
}

The implementing part must include both add and remove accessors.

You can see the complete list of new features in C# 14 here.

What's New in ASP.NET Core in .NET 10

Validation Support in Minimal APIs

ASP.NET Core 10 adds built-in validation support for Minimal APIs.
This feature automatically validates data sent to your endpoints, including query parameters, headers, and request bodies.

builder.Services.AddValidation();

The validation system automatically discovers types used in your Minimal API handlers and validates them using attributes from the System.ComponentModel.DataAnnotations namespace.

You can apply validation attributes directly to endpoint parameters:

app.MapPost("/products",
    ([Range(1, int.MaxValue)] int productId, [Required] string name) =>
    {
        return TypedResults.Ok(new { productId, name });
    });

Record types work with validation too:

public record Product(
    [Required] string Name,
    [Range(1, 1000)] int Quantity);

app.MapPost("/products", (Product product) =>
{
    return TypedResults.Ok(product);
});

When validation fails, the runtime automatically returns a 400 Bad Request response with details about the validation errors.

You can disable validation for specific endpoints:

app.MapPost("/products", (int productId, string name) =>
    TypedResults.Ok(productId))
    .DisableValidation();

You can customize error responses by implementing IProblemDetailsService and registering it in the dependency injection container.
This lets you create consistent, user-friendly error messages across your application.

JSON Patch Support in Minimal APIs

To enable JSON Patch support with System.Text.Json, install the package:

dotnet add package Microsoft.AspNetCore.JsonPatch.SystemTextJson --prerelease

Server-Sent Events (SSE)

Server-Sent Events (SSE) provide a lightweight, reliable way for ASP.NET Core apps to push continuous streams of data without the complexity of bidirectional protocols.

Server-Sent Events (SSE) is a web standard that enables a server to push real-time data to web clients over a single HTTP connection.
Unlike traditional request-response patterns where clients must repeatedly poll the server for updates, SSE allows the server to initiate communication and send data whenever new information becomes available.

For sending Server-Sent Events, you need to provide a data stream via IAsyncEnumerable<T>.

Here's a service that generates stock price updates:

public record StockPriceEvent(string Id, string Symbol, decimal Price, DateTime Timestamp);

public class StockService
{
    public async IAsyncEnumerable<StockPriceEvent> GenerateStockPrices(
       [EnumeratorCancellation] CancellationToken cancellationToken)
    {
       var symbols = new[] { "MSFT", "AAPL", "GOOG", "AMZN" };

       while (!cancellationToken.IsCancellationRequested)
       {
          var symbol = symbols[Random.Shared.Next(symbols.Length)];
          var price = Math.Round((decimal)(100 + Random.Shared.NextDouble() * 50), 2);
          var id = DateTime.UtcNow.ToString("o");

          yield return new StockPriceEvent(id, symbol, price, DateTime.UtcNow);

          await Task.Delay(TimeSpan.FromSeconds(2), cancellationToken);
       }
    }
}

Use TypedResults.ServerSentEvents to create an endpoint that streams data:

builder.Services.AddSingleton<StockService>();

app.MapGet("/stocks", (StockService stockService, CancellationToken ct) =>
{
    return TypedResults.ServerSentEvents(
       stockService.GenerateStockPrices(ct),
       eventType: "stockUpdate"
    );
});

Clients can connect to this endpoint and receive real-time updates as they're generated.

You can read an in-depth guide on Server-Sent Events with ASP.NET Core here.

OpenAPI 3.1 Support

ASP.NET Core 10 adds support for generating OpenAPI 3.1 documents.
While the version number suggests a minor update, OpenAPI 3.1 is significant because it includes full support for JSON Schema draft 2020-12.

Key Changes in OpenAPI 3.1:

Nullable types use a type array that includes null instead of a nullable: true property
Integer types (int and long) may appear without the type: integer field and use a pattern field instead, depending on your JSON serialization settings
The default OpenAPI version is now 3.1

You can explicitly set the OpenAPI version when adding OpenAPI support:

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_1;
});

YAML Format Support

ASP.NET Core now supports serving OpenAPI documents in YAML format.
YAML is more concise than JSON and supports multi-line strings, making it easier to read long descriptions.

To serve YAML documents, specify a .yaml or .yml extension:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi("/openapi/{documentName}.yaml");
}

What's New in Blazor

Blazor receives several improvements in .NET 10:

Hot Reload for Blazor WebAssembly and .NET on WebAssembly
Environment configuration in standalone Blazor WebAssembly apps
Performance profiling and diagnostic counters for Blazor WebAssembly
NotFoundPage parameter for the Blazor router
Static asset preloading in Blazor Web Apps
Improved form validation

You can see the complete list of ASP.NET Core 10 features here.

What's New in EF Core 10

Complex Types

Complex types let you model data that belongs to an entity but doesn't have its own identity.
While entity types map to database tables, complex types can map to columns in the same table (table splitting) or to a JSON column.

Complex types enable document modeling patterns that can improve performance by avoiding JOINs and simplifying your database schema.

Table Splitting

Map a customer's addresses as complex types:

modelBuilder.Entity<Customer>(b =>
{
    b.ComplexProperty(c => c.ShippingAddress);
    b.ComplexProperty(c => c.BillingAddress);
});

Optional Complex Types

EF 10 adds support for optional complex types:

public class Customer
{
    public int Id { get; set; }
    public Address ShippingAddress { get; set; }
    public Address? BillingAddress { get; set; }
}

JSON Mapping

Map complex types to JSON columns:

modelBuilder.Entity<Customer>(b =>
{
    b.ComplexProperty(c => c.ShippingAddress, c => c.ToJson());
    b.ComplexProperty(c => c.BillingAddress, c => c.ToJson());
});

Struct Support

Complex types support .NET structs:

public struct Address
{
    public required string Street { get; set; }
    public required string City { get; set; }
    public required string ZipCode { get; set; }
}

LeftJoin and RightJoin Operators

LEFT JOIN is common in database queries, but previous versions of EF Core made it complicated to write.
You needed to combine SelectMany, GroupJoin, and DefaultIfEmpty in a specific way.

.NET 10 adds first-class LINQ support for LeftJoin, making these queries much simpler:

var query = context.Students
    .LeftJoin(
        context.Departments,
        student => student.DepartmentID,
        department => department.ID,
        (student, department) => new
        {
            student.FirstName,
            student.LastName,
            Department = department.Name ?? "[NONE]"
        });

EF 10 also supports RightJoin, which keeps all data from the second collection and only matching data from the first.

Both methods translate to the appropriate SQL JOIN operations.

Note that C# query syntax (from x select x.Id) doesn't yet support these operators.

ExecuteUpdate for JSON Columns

While EF Core has supported JSON columns for several versions, ExecuteUpdate couldn't modify them.
EF 10 changes this by allowing you to update JSON properties in bulk operations.

Given this model with a JSON column:

public class Blog
{
    public int Id { get; set; }
    public BlogDetails Details { get; set; }
}

public class BlogDetails
{
    public string Title { get; set; }
    public int Views { get; set; }
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>().ComplexProperty(b => b.Details, bd => bd.ToJson());
}

You can now update properties within the JSON column:

await context.Blogs.ExecuteUpdateAsync(s =>
    s.SetProperty(b => b.Details.Views, b => b.Details.Views + 1));

This generates efficient SQL that updates the JSON data directly in the database.

Named Query Filters

Global query filters let you define conditions that apply to all queries for an entity type. This simplifies implementing patterns like soft deletion and multi-tenancy.

Previously, EF Core supported only one query filter per entity type.

EF 10 introduces named query filters, letting you define multiple filters and control them independently:

modelBuilder.Entity<Blog>()
    .HasQueryFilter("SoftDeletionFilter", b => !b.IsDeleted)
    .HasQueryFilter("TenantFilter", b => b.TenantId == tenantId);

You can selectively disable specific filters in individual queries:

var allBlogs = await context.Blogs
    .IgnoreQueryFilters(["SoftDeletionFilter"])
    .ToListAsync();

This gives you fine-grained control over which filters apply to each query.

Regular Lambdas in ExecuteUpdateAsync

ExecuteUpdateAsync lets you perform bulk updates directly in the database without loading entities into memory.

In previous versions, you had to provide changes as expression trees, making it challenging to build dynamic updates.

EF 10 allows regular lambdas with conditional logic:

await context.Blogs.ExecuteUpdateAsync(s =>
{
    s.SetProperty(b => b.Views, 8);

    if (nameChanged)
    {
        s.SetProperty(b => b.Name, "foo");
    }
});

This is much simpler than manually building expression trees and makes conditional updates straightforward.

You can see the complete list of EF Core 10 features here.

Other Changes in .NET 10

Additional resources for .NET 10:

Summary

.NET 10 and C# 14 represent a significant step forward for the .NET ecosystem.

The file-based apps feature makes C# viable for scripting scenarios that were previously dominated by Python, Node.js and JavaScript.

Extension members give you flexibility by letting you add properties to types, not just methods.

The improvements to Minimal APIs, EF Core, and ASP.NET Core make building modern web applications faster and more intuitive.

As an LTS release, .NET 10 provides a stable foundation for both new and existing applications.

Whether you're building Web APIs, desktop applications, or CLI tools, this release offers features that improve productivity and code quality.

I've been testing .NET 10 in personal projects and will begin migrating commercial projects this month.

Are you excited about .NET 10? Hit reply and let me know.

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.

The 3 C# PDF Libraries Every Developer Must Know

Anton Martyniuk — Tue, 07 Oct 2025 11:09:02 +0000

Creating and managing PDF documents is a common and crucial requirement for many applications built with C# and .NET.
You may need to generate invoices, reports, agreements, or transform content from web pages and other formats.

There are several C# PDF libraries available, but not all of them are equal.

To ensure you deliver professional documents without lags, you need a reliable PDF library that excels in compliance and professional document rendering.

In this post, we will explore three essential C# PDF libraries every developer must know.
We will explore the unique strengths and best use cases for each library.
This way, you can confidently choose the right one for your next project.

We will cover:

IronPDF
QuestPDF
PuppeteerSharp

Let's dive in.

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

IronPDF

IronPDF is a powerful .NET library for creating, editing, signing, and rendering PDFs.
It is designed to be developer-friendly: many tasks that are complex in raw PDF APIs or lower-level tools are easier in IronPDF via a more fluent, higher-level API.

Here are the features that make IronPDF unique:

HTML, DOCX, RTF, XML, MD, Image to PDF Conversion
PDF FROM URL, PDF to HTML
Compliant to PDF/A, PDF/UA, and PDF/X standards
Fully managed and cross-platform
High-performance rendering
Digital Signatures & Security
Rich PDF Manipulation (edit, merge, split PDFs)

Converting HTML to PDF with IronPDF

IronPDF allows converting HTML and CSS into pixel-perfect PDFs quickly and easily.

IronPDF is built on top of a real Chromium rendering engine (the same engine used by Google Chrome), which ensures high accuracy and fast rendering of web content into PDFs.
It efficiently handles complex HTML, CSS, and even JavaScript-rendered content.

IronPDF is extremely easy to get started with — install the following NuGet package:

dotnet add package IronPdf

With IronPDF, you can create a PDF document from HTML content in just three lines of code:

using IronPdf;

var htmlContent = @"
<html>
<head>
    <style>
        h1 { color: blue; }
        p { font-size: 16px; }
    </style>
</head>
<body>
    <h1>Invoice 1000471</h1>
    <p>Test invoice</p>
</body>
</html>";

// Create a PDF from HTML content
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("Invoice.pdf");

For more professional and complex documents, you can use Razor views or another templating engine.
And then convert the HTML to PDF.
I explained how to do this - in this article.

You can see a few examples of complex PDF documents created from HTML:

Creating Compliant PDFs with IronPDF: PDF/A and PDF/UA

In some industries, regulations and accessibility standards often require that documents follow strict formats.
Two of the most important standards are PDF/A and PDF/UA.

PDF/A (PDF for Archiving) ensures that a document can be stored long-term without losing fonts, colors, or layout.
It is often required for contracts, invoices, and government filings.

IronPDF supports export of PDFs to the PDF/A-3b standard.
PDF/A-3b is a strict subset of the ISO PDF specification used to create archival versions of documents that guarantee rendering exactly the same as when they were saved.

PDF/A-3b allows for the embedding of additional files, such as XML or CSV, within the document.

You can use the SaveAsPdfA method and specify the PDF/A version:

using IronPdf;

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

pdf.SaveAsPdfA("Invoice.pdf", PdfAVersions.PdfA3b);

The "b" level ensures that the visual appearance is preserved, which is usually required for archiving.

You can use the SaveAsPdfUA method to create a PDF that follows the PDF/UA standard:

using IronPdf;

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

pdf.SaveAsPdfUA("Invoice.pdf");

This ensures that the document is appropriately tagged so that assistive technologies can read it.

Editing PDF Documents with IronPDF

In real-world applications, you often need to manipulate existing documents: add new pages, remove old ones, or combine multiple PDFs into a single file.

IronPDF makes these operations simple with an easy-to-use API.

You can load an existing PDF and insert it as a new page:

using IronPdf;

var pdf = PdfDocument.FromFile("Original.pdf");

var coverPage = PdfDocument.FromFile("CoverPage.pdf");

// Insert PDF
contentPage.InsertPdf(coverPage, 0);

pdf.SaveAs("WithNewPage.pdf");

Removing unwanted pages is just as easy:

using IronPdf;

var pdf = PdfDocument.FromFile("Original.pdf");

// Delete the first page
pdf.RemovePage(0);

// Delete multiple pages
pdf.RemovePages(new int[] { 1, 2 });

pdf.SaveAs("WithoutPages.pdf");

Need to reuse content from one PDF in another? You can copy pages:

using IronPdf;

var source = PdfDocument.FromFile("Source.pdf");

var copyOfPageOne = source.CopyPage(0);

// Copy multiple pages into a new PDF object
var copyOfFirstThreePages = source.CopyPages(new List<int> { 0, 1, 2 });

copyOfFirstThreePages.SaveAs("WithCopiedPages.pdf");

You can combine several PDF files into one document:

using IronPdf;

var merged = PdfDocument.Merge(
    [
        PdfDocument.FromFile("Part1.pdf"),
        PdfDocument.FromFile("Part2.pdf"),
        PdfDocument.FromFile("Part3.pdf")
    ]
);

merged.SaveAs("Merged.pdf");

If you need to split a large PDF into smaller parts, IronPDF makes it straightforward:

using IronPdf;

var pdf = PdfDocument.FromFile("BigFile.pdf");

// Extract the first page into a new file
var part1 = pdf.CopyPage(0);
part1.SaveAs("SplitPage1.pdf");

// Extract a range of pages
var part2 = pdf.CopyPages(1, 3);
part2.SaveAs("SplitPages2to4.pdf");

For more information, refer to the official documentation.

Signing PDF Documents with IronPDF

When working with sensitive documents, security is just as important as generating the PDF itself.
IronPDF provides everything you need to sign documents, protect them with passwords, manage permissions, and sanitize files to remove hidden risks.

These features ensure your PDFs are secure for business, legal, and compliance purposes.

Digital signatures prove the authenticity of a document.
With IronPDF, you can sign using a certificate (.pfx or .p12) and add details like the signer's name, location, or even an image:

using IronPdf;

var pdf = PdfDocument.FromFile("Contract.pdf");

// Create a PdfSignature object directly from the certificate file and password.
var signature = new PdfSignature("IronSoftware.pfx", "123456");
signature.SignatureDate = DateTime.Now;
signature.SigningContact = "legal@ironsoftware.com";
signature.SigningLocation = "Chicago, USA";
signature.SigningReason = "Contractual Agreement";
signature.TimeStampUrl = "[http://timestamp.digicert.com](http://timestamp.digicert.com)";
signature.TimestampHashAlgorithm = TimestampHashAlgorithms.SHA256;

signature.SignatureImage = new PdfSignatureImage("assets/visual-signature.png", 0,
    new Rectangle(350, 750, 200, 100));

pdf.Sign(signature);

// Save the signed PDF
pdf.SaveAs("SignedContract.pdf");

This ensures that the PDF cannot be changed without invalidating the signature.

For more information, refer to the official documentation.

Securing PDF Documents with IronPDF

Sometimes PDFs contain hidden metadata, scripts, or sensitive information. IronPDF can sanitize a document to remove these elements, ensuring a clean and safe file.

using IronPdf;

var pdf = PdfDocument.FromFile("Original.pdf");

// Sanitize the PDF to remove hidden or unsafe data
var sanitizeWithBitmap = Cleaner.SanitizeWithBitmap(pdf);

sanitizeWithBitmap.SaveAs("Sanitized.pdf");

The trick behind sanitizing a PDF is to convert the PDF document into an image format, which removes JavaScript code, embedded objects, and buttons, and then convert it back to a PDF document.
IronPDF provides Bitmap and SVG image types.

SVG sanitizing is faster than Bitmap sanitizing, but the layout might be inconsistent.

Sanitizing is especially useful before sharing documents outside your organization.

IronPDF lets you encrypt PDFs so that they can only be opened with a password:

using IronPdf;

var pdf = PdfDocument.FromFile("Report.pdf");

// Add a password
pdf.Password = "StrongPassword123";

// Save the protected file
pdf.SaveAs("ProtectedReport.pdf");

And you can easily open a password-protected file:

using IronPdf;

var pdf = PdfDocument.FromFile("ProtectedReport.pdf", "StrongPassword123");

Beyond passwords, you can control what users are allowed to do with the PDF — for example, blocking printing or copying.

using IronPdf;

var pdf = PdfDocument.FromFile("Confidential.pdf");

// Set permissions and owner password
pdf.SecuritySettings.OwnerPassword = "OwnerSecret";
pdf.SecuritySettings.AllowUserAnnotations = false;
pdf.SecuritySettings.AllowUserCopyPasteContent = false;
pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.NoPrint;

pdf.SaveAs("Restricted.pdf");

For more information, refer to the official documentation.

Creating PDF Documents with QuestPDF

QuestPDF is a popular open-source PDF generation library for .NET developers.
Its primary goal is to simplify PDF creation through a fluent API.

To get started, install the following NuGet package:

dotnet add package QuestPDF

Here is how you can create a PDF document with QuestPDF:

using QuestPDF.Fluent;
using QuestPDF.Helpers;
using QuestPDF.Infrastructure;

var pdf = Document.Create(container =>
{
    container.Page(page =>
    {
        page.Size(PageSizes.A4);
        page.Margin(2, Unit.Centimetre);
        page.PageColor(Colors.White);
        page.DefaultTextStyle(x => x.FontSize(14));

        page.Header()
            .Text("Monthly Sales Report")
            .SemiBold()
            .FontSize(20)
            .FontColor(Colors.Blue.Medium);

        page.Content()
            .Column(x =>
            {
                x.Spacing(10);
                x.Item().Text("Generated on: " + DateTime.Now.ToShortDateString());
                x.Item().Text("Total Sales: $15,450");
                x.Item().Text("Best-selling product: Wireless Headphones");
            });

        page.Footer()
            .AlignCenter()
            .Text(x =>
            {
                x.Span("Page ");
                x.CurrentPageNumber();
            });
    });
});

pdf.GeneratePdf("MonthlySalesReport.pdf");

Why Developers Use QuestPDF:

Fluent C# API — build documents directly in code using a layout-based approach.
Consistent layouts — predictable, repeatable output for structured documents.
Good documentation — with many examples and patterns for reports.

What QuestPDF Lacks:

QuestPDF is not a complete replacement for a Chromium rendering engine, such as IronPDF.
It does not support:

HTML-to-PDF conversion — unable to convert HTML content directly into PDFs, limiting versatility in web applications.
Compliance standards — no built-in support for PDF/A (archival) or PDF/UA (accessibility).
Digital signatures or security — no native features for signing, password protection, or permissions.
Interactive forms or JavaScript rendering — limited scope to static layouts only.

QuestPDF is a solid choice for simple use cases but may fall short in enterprise-grade scenarios.
More complex documents require more code and more time to develop than creating it from HTML-to-PDF conversion.

In such cases, developers often turn to more powerful libraries, such as IronPDF.

Puppeteer Sharp

Puppeteer Sharp is a .NET port of the official Node.js Puppeteer API.

It lets you drive Chromium/Chrome from C# over the DevTools Protocol:
open pages, run JavaScript, wait for selectors, take screenshots, and print pages to PDF.

It runs headless by default and can also connect to a remote browser.

To get started with Puppeteer Sharp, install the following NuGet package:

dotnet add package PuppeteerSharp

Here is how you can create a PDF from HTML using Puppeteer Sharp:

using System.Threading.Tasks;
using PuppeteerSharp;

// 1) Ensure a Chromium binary is available (downloads if missing)
var browserFetcher = new BrowserFetcher();
await browserFetcher.DownloadAsync();

// 2) Launch headless Chromium
await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
{
    Headless = true
});

// 3) Create a new page and inject your HTML
await using var page = await browser.NewPageAsync();

await page.SetContentAsync(htmlContent);

// 4) Print to PDF with options
await page.PdfAsync("Report.pdf", new PdfOptions
{
    Format = PaperFormat.A4,
    PrintBackground = true,
    MarginOptions = new MarginOptions { Top = "20mm", Right = "15mm", Bottom = "20mm", Left = "15mm" }
});

Puppeteer-Sharp will download a compatible Chrome build into an output folder when you run your application for the first time.

Puppeteer Sharp is good at printing real web pages (including dynamic, JS-rendered content) to PDF using the Chromium engine with various options.

What Puppeteer-Sharp Lacks:

Puppeteer-Sharp is a browser automation library, and not a .NET-native PDF SDK.

While it excels at rendering HTML into PDFs, it is not a full-featured .NET PDF SDK.
It does not support:

Compliance standards — no built-in features for creating PDF/A (archival) or PDF/UA (accessible) documents.
PDF editing — no tools for merging, splitting, or modifying existing PDFs.
Digital signatures & security — lacks password protection, encryption, or signing capabilities.

Puppeteer-Sharp is free and open-source, making it a good option for developers who want to experiment with PDF generation without licensing costs.

Licensing

IronPDF:

IronPDF follows a commercial licensing model.

Free trial available: You can start with a trial license to explore features.
Commercial licenses required for production: Businesses and organizations must obtain a license before deploying IronPDF in production.
Support and updates included: A license comes with access to updates, bug fixes, and professional technical support.

IronPDF does not have a free open-source tier.
However, it provides enterprise-grade features such as PDF/A and PDF/UA compliance, digital signatures, and document security, which are often required in professional and regulated environments.

IronPDF offers the best support, helping developers quickly resolve issues — a feature that other PDF libraries often lack.

QuestPDF:

QuestPDF is open-source but requires a license:

Free for personal and non-commercial use: Anyone can use QuestPDF at no cost for personal projects, learning, or non-commercial purposes.
Commercial use requires a license: If you're building software for a company, clients, or profit, you need to purchase a commercial license (based on company size).

Note: QuestPDF now requires a commercial license even for small companies.

What about Aspose.PDF?

Aspose.PDF was the most popular PDF library until the release of IronPDF.

Aspose.PDF, while powerful, takes a more traditional approach.
It constructs PDFs programmatically or parses and manipulates existing ones, but doesn't use Chromium (or another web engine) for rendering.
As a result, while it offers manual control over each aspect, it's often slower and more resource-intensive when working with rich layouts or conversions.

IronPDF can provide a 2-4x performance boost over Aspose.PDF, with reduced memory usage.

IronPDF offers a license at a much more affordable price and provides more benefits than Aspose, which is honestly very overpriced.

You read the detailed comparison here.

Summary

Choosing the right PDF library in .NET depends on your project's needs.

IronPDF stands out for professional use cases where compliance, security, and pixel-perfect rendering are essential. It offers PDF/A and PDF/UA support, digital signatures, sanitization, and strong customer support — making it ideal for any company.
QuestPDF is a good choice for developers who want to design structured, layout-driven reports with a fluent C# API. It is free for personal and non-commercial use, but commercial use requires a paid license, even for small companies. It's simple to learn, but it lacks compliance, security, and HTML-to-PDF conversion.
Puppeteer-Sharp is excellent when you need to render dynamic HTML, CSS, and JavaScript into PDFs with Chromium. It's completely free, but it's not a .NET-native SDK and does not cover compliance, editing, or security.
Aspose.PDF deserves a short mention as well — it's a heavyweight commercial tool, but for most scenarios IronPDF provides more value and developer experience.

For most professional .NET projects that require trust, compliance, and long-term support, IronPDF is the clear winner.

Although it requires a commercial license, it provides enterprise-grade features, dedicated support, and compliance standards that make it a worthwhile investment.

QuestPDF, on the other hand, is free for personal or non-commercial use only and offers lower-cost licensing options for businesses. Still, it lacks the advanced capabilities and reliability that IronPDF delivers.

Many thanks to IronPDF for sponsoring this blog post.

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Load Testing Microservices With C# and NBomber

Anton Martyniuk — Tue, 09 Sep 2025 10:42:35 +0000

I have been working with microservices for 7+ years.

You can't build a quality microservices system without these 3 things:

Observability
Integration tests
Load tests

Many teams skip load tests.
They think it takes too much time, or they are not important.

This is a mistake. Without load tests, problems often show up in production when it is too late and too costly to fix them.

In microservices, your system connects to many parts:

Databases
Distributed caches
Message queues
External APIs
Other services

How do you decide if your service should use MS SQL Server, PostgreSQL, or MongoDB?
Should services talk through a REST API (synchronous communication) or use a message queue (asynchronous)?

Load tests will give you clear answers.

They show how much traffic your system can handle before it slows down or fails.
They reveal slow parts of your system and help compare different design choices.

They show real latency numbers, help you check timeouts, retries, and error handling under stress.

They also give you data for capacity planning so you know when to scale.
And when you run them regularly, you can spot performance regressions early.

They also help you compare different setups under the same conditions, such as MS SQL Server vs PostgreSQL vs MongoDB.
You can test REST API calls against message queue events to see which communication method works better for your case.

One of the best solutions I have found for load tests in .NET is NBomber.

Today I want to show you how easily you can create load tests for microservices with NBomber.

In this post, we will explore:

Getting Started With NBomber
Creating Load Tests with NBomber
Running Load Tests in Parallel
Configuring NBomber with JSON Files
Creating Reports with NBomber

Let's dive in.

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Getting Started With NBomber

NBomber is a modern and flexible load-testing framework designed to test any system regardless of a protocol or a semantic model (Pull/Push).

NBomber lets you define load test scenarios in plain C# or F# code.
One of its key advantages over other tools is the ability to use your favorite language and IDE (with a debugger) to model realistic load tests.
As your load test codebase grows, the benefits of using a type-safe programming language become increasingly important for maintaining and evolving your tests.

NBomber is protocol-agnostic by design. Unlike many tools, it doesn't depend on external packages for specific protocols, which makes it flexible enough to test anything from HTTP and WebSockets to gRPC, Kafka, NoSQL databases, or custom protocols.

In addition, NBomber provides a rich ecosystem of open-source plugins and extensions - covering protocols, real-time reporting, monitoring, and more.
This makes it well-suited for adoption across teams and organization-wide testing initiatives.

NBomber offers the following features:

Protocol-agnostic – you can test HTTP, gRPC, WebSockets, databases, message brokers, or anything else you can call from .NET.
Cloud-agnostic – you can run and replicate your test on any cloud. No need to depend on a specific cloud UI, just build your app, deploy, and get results.
Developer-friendly – you write tests in C#/F# using your IDE, with type safety and full debugging support.
HTML Reports – built-in HTML reports with custom metrics
Real-time reporting - Stores load test metrics in many different observability systems (DataDog, InfluxDB, TimeScaleDB, Grafana, NBomber Studio)
Plugins support - you can add your own plugins (Converter, WebSockets, AMQP, MQTT) and data sinks
Integration with xUnit/NUnit – you can run load tests as part of your CI/CD pipeline (xUnit Example).
Kubernetes/Cluster mode – run distributed tests across multiple nodes.

You can find system requirements for using NBomber - here.

Creating Scenarios

To create load tests, you need to define a scenario.

Scenario represents some user behaviour you need to test, for example:

User logs in
User loads profile page
User creates an order

You can create a scenario with the Scenario.Create method:

var scenario = Scenario.Create("order scenario", async context =>
{
    await Login();
    await LoadProfile();     
    await CreateOrder();

    return Response.Ok();        
})
.WithLoadSimulations(
    Simulation.Inject(rate: 10,
        interval: TimeSpan.FromSeconds(1),
        during: TimeSpan.FromSeconds(30))
);

When you run this scenario, NBomber will measure the whole scenario execution.
At the end of execution, NBomber will print the scenario's statistics result.

Each load test consists of the following phases:

Init
Warm-up
Bombing (testing)
Clean

Scenario Init

This method should be used to initialize the Scenario and all its dependencies.
You can use it to prepare your target system, populate the database, or read and apply the JSON configuration for your scenario.

var scenario = Scenario.Create("order scenario", async context =>
{
    await Login();
    await LoadProfile();     
    await CreateOrder();

    return Response.Ok();
})
.WithInit(async context =>
{
    await SeedDatabase();
})
.WithLoadSimulations(
    Simulation.Inject(rate: 10,
        interval: TimeSpan.FromSeconds(1),
        during: TimeSpan.FromSeconds(30))
);

Scenario Clean

This method should be used to clean the scenario's resources after the test finishes.

var scenario = Scenario.Create("order scenario", async context =>
{
    await Login();
    await LoadProfile();     
    await CreateOrder();

    return Response.Ok();
})
.WithClean(async context =>
{
    await CleanDatabase();
});

Let's explore how we can write load tests for a real-world microservices system.

Creating Load Tests with NBomber

I have built a microservices application with three services:

UserService — responsible for user authentication and JWT issuing
ShipmentService — for creating shipments
StockService — for checking and updating inventory

All services are placed behind an API Gateway (YARP) and store data in PostgreSQL.

Here is how the services interact with each other when creating a shipment:

"Create Shipment" use case has the following flow:

ShipmentService sends a REST HTTP request to StockService and checks whether there are enough products to create a shipment
If enough stocks — creates a shipment in the database
Sends a "ShipmentCreatedEvent" to a message queue
StockService — subscribes to the event and updates the inventory

Creating First Load Scenario

Let's create our first scenario with NBomber that consists of 2 steps:

User logs in
User loads his profile

With NBomber, we can test how UserService performs when many users log into their profiles at the same time.

Follow these simple steps to create your load tests:

Step 1:

Create a .NET Console project.

Step 2:

Add the following NuGet packages:

dotnet add package NBomber
dotnet add package NBomber.Http

To work with HTTP, NBomber provides NBomber.Http plugin for the native .NET HttpClient.
This plugin offers useful extensions that simplify creating and sending requests, receiving responses, and tracking data transfer and status codes.

Step 3:

Create a test scenario with NBomber.

You can choose 2 options:

You can run all the needed steps as a whole and NBomber will measure the performance of the complete flow:

var httpClient = Http.CreateDefaultClient();

var scenario = Scenario.Create("user_login_and_get_profile_scenario", async context =>
{
    await Login();
    await GetProfile();
})
.WithoutWarmUp()
.WithLoadSimulations(
    Simulation.Inject(rate: 10,
        interval: TimeSpan.FromSeconds(1),
        during: TimeSpan.FromSeconds(30))
);

Or you can move each method into separate steps and NBomber will measure them separately:

var httpClient = Http.CreateDefaultClient();

var scenario = Scenario.Create("user_login_and_get_profile_scenario",
    async context =>
{
    var step1 = await Step.Run("login", context, () => LoginStep(httpClient));

    var token = step1.Payload.Value;

    var step2 = await Step.Run("get_profile", context, () => GetProfileStep(httpClient, token));

    return step2;
})
.WithoutWarmUp()
.WithLoadSimulations(
    Simulation.Inject(rate: 10,
        interval: TimeSpan.FromSeconds(1),
        during: TimeSpan.FromSeconds(30))
);

Here is how you can send an HTTP request with NBomber:

var loginRequest = Http.CreateRequest("POST", "http://localhost:5000/api/users/login")
    .WithJsonBody(new { Email = "admin@test.com", Password = "Test1234!"});

    // Send HTTP request with NBomber
    var loginResponse = await Http.Send(httpClient, loginRequest);

Here is the complete implementation of each step:

private async Task<Response<string>> LoginStep(
    HttpClient httpClient,
    IScenarioContext context)
{
    // Create HTTP request
    var loginRequest = Http.CreateRequest("POST", "http://localhost:5000/api/users/login")
        .WithJsonBody(new { Email = "admin@test.com", Password = "Test1234!"});

    var loginResponse = await Http.Send(httpClient, loginRequest);

    var responseBody = await loginResponse.Payload.Value.Content.ReadFromJsonAsync<LoginUserResponse>();

    return responseBody is null
        ? Response.Fail<string>(message: "No JWT token available")
        : Response.Ok(payload: responseBody.Token);
}

private async Task<Response<string>> GetProfileStep(
    HttpClient httpClient,
    IScenarioContext context)
{
    var profileRequest = Http.CreateRequest("GET", "http://localhost:5000/api/users/profile")
        .WithHeader("Accept", "application/json")
        .WithHeader("Authorization", $"Bearer {token}");

    var profileResponse = await Http.Send(httpClient, profileRequest);

    var responseBody = await profileResponse.Payload.Value.Content.ReadFromJsonAsync<UserResponse>();

    return responseBody is null
        ? Response.Fail<string>(message: "User profile not found")
        : Response.Ok<string>();
}

Each step and scenario should return either Response.Ok or Response.Fail.

Note that LoginStep step returns the JWT token that is used in the GetProfileStep.

You can also share data between steps with ScenarioContext, that represents the execution context of the currently running Scenario.
You can use ScenarioContext to share data between steps.

It provides functionality to log particular events, get information about the test, thread ID, scenario copy/instance number, etc.
Also, it provides the option to stop all or particular scenarios manually.

Step 4:

Run the scenario in the Release mode:

NBomberRunner
    .RegisterScenarios(scenario)
    .Run(args);

We are running a load test for 30 seconds, and after it finishes, we will get the following results in the Console:

This 30-second test ran the user_login_and_get_profile_scenario at 20 requests per second, completing 600 requests with zero failures.

You can see one login request that took over 1 second - it's the first request as we have specified WithoutWarmUp when creating a scenario.

Configuring Load Simulation

NBomber gives you several ways to control how virtual users are added during a test.
This is called Load Simulation.

You can configure:

Open Model: new virtual users arrive at a fixed rate, no matter how many are already running. This is good for testing systems that face a steady stream of incoming requests.
Closed Model: the number of active virtual users stays constant. New users only start once others have finished. This is useful for testing complete user journeys with predictable concurrency.

You can also combine both models in the same test to simulate different traffic patterns.

For most end-to-end user flows, the Closed Model is a good starting point.
If you are unsure, start here and adjust based on results.

Whatever model you choose, ramp up the load gradually.
This avoids overwhelming your system instantly and helps you see when performance starts to degrade.

Best Practices When Using HttpClient in Load Tests

When testing HTTP-based services, follow these best practices:

Reuse your HttpClient – create one HttpClient per scenario, not per request. This avoids unnecessary TCP connections and reduces overhead.
Per-user HttpClient (if needed) – if each virtual user needs its own cookies or session state, attach a dedicated HttpClient to the scenario instance using context.ScenarioInstanceData.
Do not dispose too often – frequent disposal can cause socket exhaustion and skew results. It's better not to dispose HttpClient during the load test.

These practices will keep your load tests reliable and ensure you are testing the service's limits and not hitting issues in your test code.

Creating Second Load Scenario

Let's create our 2nd scenario that consists of 2 steps:

User logs in
User creates a shipment

var httpClient = Http.CreateDefaultClient();

var scenario = Scenario.Create("user_login_and_create_shipment_scenario",
    async context =>
{
    var step1 = await Step.Run("login", context, () => LoginStep(httpClient));

    var token = step1.Payload.Value;

    var step2 = await Step.Run("create_shipment", context, () => CreateShipmentStep(httpClient, token));

    return step2;
})
.WithLoadSimulations(
    // ramp up the injection rate from 0 to 50 copies
    // injection interval: 5 seconds
    // duration: 30 seconds (it executes from [00:00:00] to [00:00:30])
    Simulation.RampingInject(rate: 50,
        interval: TimeSpan.FromSeconds(5),
        during: TimeSpan.FromSeconds(30)),

    // keeps injecting 50 copies per 1 second
    // injection interval: 5 seconds
    // duration: 30 seconds (it executes from [00:00:30] to [00:01:00])
    Simulation.Inject(rate: 50,
        interval: TimeSpan.FromSeconds(5),
        during: TimeSpan.FromSeconds(30)),

    // ramp down the injection rate from 50 to 0 copies
    // injection interval: 5 seconds
    // duration: 30 seconds (it executes from [00:01:00] to [00:01:30])
    Simulation.RampingInject(rate: 0,
        interval: TimeSpan.FromSeconds(5),
        during: TimeSpan.FromSeconds(30))
);

The CreateShipmentStep implementation is as follows:

private async Task<Response<string>> CreateShipmentStep(
    HttpClient httpClient,
    IScenarioContext context)
{
    var request = GetCreateShipmentRequest();

    // Send HTTP request with NBomber
    var createShipmentRequest = Http.CreateRequest("POST", "http://localhost:5000/api/shipments")
        .WithHeader("Content-Type", "application/json")
        .WithHeader("Authorization", $"Bearer {token}")
        .WithJsonBody(request);

    await Http.Send(httpClient, createShipmentRequest);

    return Response.Ok(payload: orderId);
}

Let's run the test:

This test verifies that our complete flow works under load:

User logs in
User initiates shipment creation
ShipmentService sends a REST HTTP request to StockService and checks whether there are enough products to create a shipment
If enough stocks — creates a shipment in the database
Sends a "ShipmentCreatedEvent" to a message queue
StockService — subscribes to the event and updates the inventory

Running Load Tests in Parallel

In real systems, traffic is rarely a single type of request.
Some users might be browsing profiles, others might be creating orders, and both happen at the same time.

NBomber lets you model this by running multiple scenarios in parallel.
For example, if your site usually has 100 concurrent users, you might simulate:

70 users visiting the home page
30 users creating orders

You do this by creating two scenarios, each with its own throughput or virtual user count, and then registering them to run together.
This way, your load test reflects realistic traffic patterns instead of a single workload.

We can combine our two previous scenarios and run them side-by-side in parallel:


var scenario1 = new UserLoginAndProfileScenario().CreateScenario();
var scenario2 = new UserLoginAndCreateShipmentScenario().CreateScenario();

NBomberRunner
    .RegisterScenarios(scenario1, scenario2)
    .Run(args);

public class UserLoginAndProfileScenario
{
    public ScenarioProps CreateScenario()
    {
        var httpClient = Http.CreateDefaultClient();

        var scenario = Scenario.Create("user_login_and_get_profile_scenario",
            async context =>
        {
            // Step 1: LoginStep
            // Step 2: GetProfileStep
            // Code remains the same from the previous examples
        })
        .WithoutWarmUp()
        .WithLoadSimulations(
            Simulation.Inject(rate: 20,
                interval: TimeSpan.FromSeconds(1),
                during: TimeSpan.FromSeconds(30))
        );

        return scenario;
    }
}

public class UserLoginAndCreateShipmentScenario
{
    public ScenarioProps CreateScenario()
    {
        var httpClient = Http.CreateDefaultClient();

        var scenario = Scenario.Create("user_login_and_create_shipment_scenario",
            async context =>
        {
            // Step 1: LoginStep
            // Step 2: CreateShipmentStep
            // Code remains the same from the previous examples
        })
        .WithLoadSimulations(
            Simulation.RampingInject(rate: 50,
                interval: TimeSpan.FromSeconds(5),
                during: TimeSpan.FromSeconds(30)),

            Simulation.Inject(rate: 50,
                interval: TimeSpan.FromSeconds(5),
                during: TimeSpan.FromSeconds(30)),

            Simulation.RampingInject(rate: 0,
                interval: TimeSpan.FromSeconds(5),
                during: TimeSpan.FromSeconds(30))
        );

        return scenario;
    }
}

For more advanced setup, see the documentation.

Configuring NBomber with JSON Files

NBomber supports configuration through JSON files, making it easy to:

Run the same test under different environments
Adjust load patterns without changing code
Keep versioned test profiles in source control

NBomber supports two JSON config types:

JSON Config - overrides scenario execution settings like LoadSimulations, WarmUpDuration, and TargetScenarios.
JSON Infrastructure Config - overrides infrastructure settings like loggers, reporting sinks, and worker plugins.

Note: If a value is set in both code and JSON, the JSON value takes priority.

You can load JSON in three ways:

// From JSON file
NBomberRunner
    .RegisterScenarios(scenario)    
    .LoadConfig("config.json")
    .Run(args);

// Providing JSON directly
NBomberRunner
    .RegisterScenarios(scenario)    
    .LoadConfig("{ PLAIN JSON }")
    .Run(args);

// Providing from an URL
NBomberRunner
    .RegisterScenarios(scenario)    
    .LoadConfig("https://my-test-host.com/config.json")
    .Run(args);

NBomber also supports CLI arguments for loading JSON Config.

dotnet MyLoadTest.dll --config=config.json

Configuring Load Simulation

You can fully define Load Simulation in JSON, including multiple stages:

{
    "LoadSimulationsSettings": [              
        { "RampingInject": [50, "00:00:01", "00:00:30"] },
        { "Inject": [50, "00:00:01", "00:01:00"] },
        { "RampingInject": [0, "00:00:01", "00:00:30"] }
    ]
}

This example ramps up to 50 RPS, holds steady, then ramps down.

Configuring Thresholds

You can set Thresholds settings in JSON, so tests fail automatically if performance drops below your limits:

{
    "ThresholdSettings": [
        { "OkRequest": "RPS >= 30" },
        { "OkRequest": "Percent > 90" }
    ]
}

Thresholds can also be checked in code after the tests finish:

var scenario = new UserLoginAndCreateShipmentScenario().CreateScenario();

var result = NBomberRunner
    .RegisterScenarios(scenario)
    .Run(args);

// Get the final stats to check against our thresholds.
var stats = result.ScenarioStats.Get("user_login_and_create_shipment_scenario");

Assert.True(stats.Fail.Request.Percent <= 5);

Custom Metrics

NBomber tracks built-in metrics (CPU, RAM, data transfer), but you can also create custom metrics for business or technical KPIs.

Two common types are:

Counter – tracks a running total (e.g., total successful logins).
Gauge – tracks the latest value (e.g., current memory usage).

Here is how you can define custom metrics in your code:

// define custom metrics
var counter = Metric.CreateCounter("my-counter", unitOfMeasure: "MB");
var gauge = Metric.CreateGauge("my-gauge", unitOfMeasure: "KB");

var scenario = Scenario.Create("scenario", async context =>
{
    await Task.Delay(500);

    counter.Add(1); // tracks a value that may increase or decrease over time
    gauge.Set(6.5); // set the current value of the metric

    return Response.Ok();
})
.WithInit(ctx =>
{
    // register custom metrics
    ctx.RegisterMetric(counter);
    ctx.RegisterMetric(gauge);

    return Task.CompletedTask;
});

var stats = NBomberRunner
    .RegisterScenarios(scenario)
    .Run(args);

// We can retrieve the final metric values for further assertions
var counterValue = stats.Metrics.Counters.Find("my-counter").Value;
var gaugeValue = stats.Metrics.Gauges.Find("my-gauge").Value;

You can also set thresholds on custom metrics:

// define custom metrics
var counter = Metric.CreateCounter("my-counter", unitOfMeasure: "MB");
var gauge = Metric.CreateGauge("my-gauge", unitOfMeasure: "KB");

var scenario = Scenario.Create("scenario", async context =>
{
    ...
})
.WithInit(ctx =>
{
    // register custom metrics
    ctx.RegisterMetric(counter);
    ctx.RegisterMetric(gauge);

    return Task.CompletedTask;
})
.WithThresholds(
    Threshold.Create(metric => metric.Counters.Get("my-counter").Value < 1000),
    Threshold.Create(metric => metric.Gauges.Get("my-gauge").Value >= 6.5)
);

Creating Reports with NBomber

You can generate reports with NBomber.
They are crucial for understanding how your application performs under load.

This is an example of an HTML report that you can interact with.

Reports provide detailed insights into various performance metrics, helping you identify bottlenecks, optimize performance, and ensure a smooth user experience.

NBomber can generate reports in the following formats:

HTML report
MD report
CSV report
TXT report

You can configure report formats using the WithReportFormats method:

NBomberRunner
    .RegisterScenarios(scenario)
    .WithReportFormats(
        ReportFormat.Csv, ReportFormat.Html, 
        ReportFormat.Md, ReportFormat.Txt
    )
    .Run(args);

You can also configure the report folder and a file name:

NBomberRunner
    .RegisterScenarios(scenario)
    .WithReportFolder("reports")
    .WithReportFileName("shipment-reports")
    .Run(args);

NBomber also allows you to retrieve the contents of the generated reports.
It's useful when you need to upload them to a custom destination (remote storage):

var result = NBomberRunner
    .RegisterScenarios(scenario)
    .Run(args);

var htmlReport = result.ReportFiles.First(x => x.ReportFormat == ReportFormat.Html);

var filePath = htmlReport.FilePath;  // file path
var html = htmlReport.ReportContent; // string HTML content

// You can upload the content to a remote storage

Here is what the HTML report looks like when we run two scenarios in parallel:

In the "Scenarios" tab, you can view all the scenarios you ran during a testing session.

Summary

NBomber is a powerful and flexible load-testing tool for .NET.
It lets you create realistic user scenarios, run them in parallel, and measure performance at every step.

You can simulate HTTP, gRPC, WebSockets, databases, and message queues like RabbitMQ in the same test.

Its JSON configuration, runtime thresholds, and custom metrics make it easy to adapt tests.
The built-in reports show latency percentiles, error rates, and system metrics so you can spot problems fast.

With NBomber, you can validate system limits, compare technology choices, and find bottlenecks before they reach production.

The biggest advantage of NBomber is that you can write load tests directly in C# or F#.
This means you can reuse your existing application code, helpers, and libraries inside your tests.
You don't need to learn JavaScript or custom scripts for creating tests.

NBomber is free for personal use.
Using NBomber in an organization requires a paid license, learn more here.

NBomber's pricing is very affordable because the license covers the entire organization.
A single license can be shared across all teams, so there's no need to manage individual developer seats — one license works for the whole company.

You can check the Pricing info here.

Start building your load tests today with NBomber and find issues before they reach production:

I highly recommend starting with the Hello World tutorial.
Then please read this article about Load Testing Microservices. It will provide a basic foundation on how to cover your system with isolated and end-to-end (E2E) Load testing.
After that, you're ready to explore their collection of demo examples

Many thanks to NBomber for sponsoring this blog post.

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Boost Your EF Core Productivity in PostgreSQL With Entity Developer

Anton Martyniuk — Wed, 20 Aug 2025 05:05:39 +0000

EF Core has been my go-to ORM for many years because it significantly improves developer productivity.
However, managing data models using traditional approaches like Database-First or Code-First can become boring and time-consuming, especially as your projects grow.

While Database-First allows rapid model generation from existing databases, and Code-First provides flexible schema migrations, both approaches can slow down development when manually configuring complex entities and relationships.

Luckily, there is a more efficient and modern way: the Model-First approach.
Instead of hand-writing your models and configurations, you design them visually.
These visual models are then automatically transformed into EF Core entities and database schemas.

One of the best tools for implementing the Model-First approach is Entity Developer by Devart.

It features an intuitive drag-and-drop interface that lets you easily visualize and manage your data models, significantly reducing manual coding and errors.

Today, I will show you how to rapidly design, generate, and synchronize your EF Core models for PostgreSQL databases using Entity Developer.
You'll discover how this powerful tool can simplify your workflow, improve code quality, and boost your overall development efficiency.

In this post, we will explore:

Getting Started: Creating Your EF Core Model for PostgreSQL
Designing Your Data Model Visually
Generating PostgreSQL Database Scripts
Automating EF Core Code Generation
Core Benefits for EF Core and PostgreSQL Development

Let's dive in!

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Getting Started: Creating Your EF Core Model for PostgreSQL

Entity Developer is an easy-to-use visual tool designed to simplify working with EF Core.
It allows developers to quickly create and visualize data models using a simple drag-and-drop interface.

You don't need to write much code, making it perfect for those who prefer visual tools over manual coding.
This tool is useful for developers of all levels: from juniors to seniors.

Entity Developer supports two main approaches: Model-First and Database-First.

Entity Developer supports the following databases:

PostgreSQL
MySQL
Oracle
MariaDB
SQLite

Today, we'll focus on using Entity Developer with EF Core and PostgreSQL, specifically with the Model-First approach.

Let's set up our first EF Core model with Entity Developer.

Follow these simple steps:

Step 1: Install Entity Developer

First, download and install Entity Developer from its official website.

Once installed, you can run Entity Developer as a standalone tool or use it inside Visual Studio.
For this guide, we'll use the standalone version.

Step 2: Start the Create Model Wizard

Open Entity Developer, click "File → New Model," and the Create Model Wizard will open.
Select "EF Core Model," then give your Model a clear, descriptive name:

Step 3: Configure Entity Model

Choose the Model-First approach.
This lets you visually design your database model first, then automatically generate the necessary code and database schema.

You will need to install dotConnect for PostgreSQL to connect EF Core with a PostgreSQL database.
It comes with Visual Studio integration and installs the required DLLs for a database communication provider.

Next, configure the following settings:

Check "Use the connection string from appsettings.json"
Enter the connection string name as "Postgres."
Set the DbContext name to "ShipmentDbContext."
Select your EF Core version (EF 9 is supported).

Your initial setup is complete! Now, let's start designing our entity models.

Designing Your Data Model Visually

Let's design a real-world application with three entities: Order, Shipment, and Product.
Each Order has one Shipment and multiple Products.

Follow these simple steps:

Step 1: Create an Entity Class

Right-click anywhere on the diagram and select "Add → New Class".

Create 3 entities: Order, Shipment and Product.

Step 2: Add Properties to the Entities

To add properties, right-click the entity and select "Edit" or press "Enter".
In the opened dialog, add all the properties.

Add the following properties to the entities:

Order:

Id (Primary key, UUID)
Number (string)
Date (DateTime)
CustomerName (String)
CustomerEmail (String)
Status (String)

Shipment:

Id (Primary key, UUID)
TrackingNumber (string)
Carrier (string)
Address (string)
ShippedDate (DateTime, nullable)
DeliveredDate (DateTime, nullable)
Price (decimal)
ShipmentId (UUID)

Product:

Id (Primary key, UUID)
Name (string)
Description (DateTime)
Price (Int32)
Quantity (Int32)
OrderId (UUID)

The visual schema should look like this:

Step 3: Add Relations between Entities

Next, define the relationships between entities:

Shipment has a one-to-one relationship with Order.
Order has a one-to-many relationship with Product.

To create a relationship, right-click on the Shipment entity and select "Add → New Association" from the context menu.

In the dialog, select the following:

Order Entity (Shipment has OrderId)
Set Cardinality to OneToOne.
Choose None for On Delete Action.
Map Shipment (OrderId) to Order (Id).

Repeat this process to create a OneToMany relationship between Order and Product.

Your completed schema will look like this:

Entity Developer also supports inheritance hierarchies using the "New Inheritance" context action.
This is useful for EF Core patterns like Table-Per-Hierarchy (TPH) and Table-Per-Type (TPT).

Using Entity Developer makes entity modeling simple and enjoyable.
With its intuitive drag-and-drop interface, you won't need to write classes or handle relationships manually.

Next, we'll explore how Entity Developer automates PostgreSQL database script creation.

Generating PostgreSQL Database Scripts

Entity Developer makes generating PostgreSQL database scripts simple.
It automatically creates SQL scripts based on your visual EF Core model, helping you quickly set up or update your database.

To generate a script, follow these simple steps:

In Entity Developer, click "Model → Generate Database Script From Model" from the main menu:

In the dialog that opens, configure the following settings:

Target Server: PostgreSQL
Server Version: 17
Target schema: shipments (our database schema)
Data Provider: Devart.Data.PostgreSql

Entity Developer will display a preview of the script before making any changes.
This lets you check the database updates carefully.

As a result, Entity Developer will create the following database schema:

CREATE TABLE shipments."Orders" (
   "Id" UUID NOT NULL,
   "Number" VARCHAR NOT NULL,
   "Date" TIMESTAMP NOT NULL,
   "CustomerName" VARCHAR NOT NULL,
   "CustomerEmail" VARCHAR NOT NULL,
   "Status" VARCHAR NOT NULL,
   CONSTRAINT "PK_Orders" PRIMARY KEY ("Id")
);

CREATE TABLE shipments."Products" (
   "Id" UUID NOT NULL,
   "Name" VARCHAR NOT NULL,
   "Description" VARCHAR NOT NULL,
   "Price" DECIMAL NOT NULL,
   "Quantity" INT4 NOT NULL,
   "OrderId" UUID NOT NULL,
   CONSTRAINT "PK_Products" PRIMARY KEY ("Id"),
   CONSTRAINT "FK_Products_Orders_0" FOREIGN KEY ("OrderId") REFERENCES shipments."Orders" ("Id") ON DELETE NO ACTION
);

CREATE TABLE shipments."Shipments" (
   "Id" UUID NOT NULL,
   "TrackingNumber" VARCHAR NOT NULL,
   "Carrier" VARCHAR NOT NULL,
   "Address" VARCHAR NOT NULL,
   "ShippedDate" TIMESTAMP,
   "DeliveredDate" TIMESTAMP NOT NULL,
   "Price" DECIMAL NOT NULL,
   "OrderId" UUID NOT NULL,
   CONSTRAINT "PK_Shipments" PRIMARY KEY ("Id"),
   CONSTRAINT "FK_Shipments_Orders_0" FOREIGN KEY ("OrderId") REFERENCES shipments."Orders" ("Id") ON DELETE NO ACTION
);

You can use this SQL script to create all the needed database tables in your PostgreSQL.

Alternatively, you have two options for applying your database updates:

Update database directly from the Entity Developer (from the context menu in the Designer).
Use EF Core to generate migrations.

Now let's explore how to generate code with Entity Developer for EF Core.

Automating EF Core Code Generation

With Entity Developer, turning your visual database model into code is easy.
Let's quickly set up an EF Core Web API project using Visual Studio.

First, install these necessary NuGet packages:

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet add package Devart.Data.PostgreSql.EFCore

We'll use Devart.Data.PostgreSql.EFCore as our PostgreSQL provider for EF Core.

Next, convert your Entity Developer model to code:

Ensure your Entity Developer project is saved.
Click "Model → Generate code" from the main menu

Entity Developer uses T4 templates to generate C# entity classes, DbContext, and mapping configurations automatically.
Copy these files into your Visual Studio solution.

Entity Developer has created Order, Product and Shipment entities.
Here is what they look like in the code:

public partial class Order
{
    public Order()
    {
        this.Products = new List<Product>();
        OnCreated();
    }

    public Guid Id { get; set; }
    public string Number { get; set; }
    public DateTime Date { get; set; }
    public string CustomerName { get; set; }
    public string CustomerEmail { get; set; }
    public string Status { get; set; }
    public Guid ShipmentId { get; set; }

    public virtual Shipment Shipment { get; set; }
    public virtual IList<Product> Products { get; set; }

    partial void OnCreated();
}

public partial class Product
{
    public Product()
    {
        OnCreated();
    }

    public Guid Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public decimal Price { get; set; }
    public int Quantity { get; set; }
    public Guid OrderId { get; set; }

    public virtual Order Order { get; set; }

    partial void OnCreated();
}

public partial class Shipment
{
    public Shipment()
    {
        OnCreated();
    }

    public Guid Id { get; set; }
    public string TrackingNumber { get; set; }
    public string Carrier { get; set; }
    public string Address { get; set; }
    public DateTime? ShippedDate { get; set; }
    public DateTime DeliveredDate { get; set; }
    public decimal Price { get; set; }

    public virtual Order Order { get; set; }

    partial void OnCreated();
}

And here is what our ShipmentDbContext looks like:

public partial class ShipmentDbContext : DbContext
{
    public ShipmentDbContext(DbContextOptions<ShipmentDbContext> options) :
        base(options)
    {
        OnCreated();
    }

    public virtual DbSet<Order> Orders { get; set; }
    public virtual DbSet<Shipment> Shipments { get; set; }
    public virtual DbSet<Product> Products { get; set; }

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

        this.OrderMapping(modelBuilder);
        this.CustomizeOrderMapping(modelBuilder);

        this.ShipmentMapping(modelBuilder);
        this.CustomizeShipmentMapping(modelBuilder);

        this.ProductMapping(modelBuilder);
        this.CustomizeProductMapping(modelBuilder);

        RelationshipsMapping(modelBuilder);
        CustomizeMapping(ref modelBuilder);
    }

    private void OrderMapping(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>().ToTable(@"Orders");
       modelBuilder.Entity<Order>().Property(x => x.Id).HasColumnName(@"Id").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Order>().Property(x => x.Number).HasColumnName(@"Number").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Order>().Property(x => x.Date).HasColumnName(@"Date").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Order>().Property(x => x.CustomerName).HasColumnName(@"CustomerName").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Order>().Property(x => x.CustomerEmail).HasColumnName(@"CustomerEmail").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Order>().Property(x => x.Status).HasColumnName(@"Status").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Order>().HasKey(@"Id");
    }

    private void ShipmentMapping(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Shipment>().ToTable(@"Shipments");
       modelBuilder.Entity<Shipment>().Property(x => x.Id).HasColumnName(@"Id").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Shipment>().Property(x => x.TrackingNumber).HasColumnName(@"TrackingNumber").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Shipment>().Property(x => x.Carrier).HasColumnName(@"Carrier").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Shipment>().Property(x => x.Address).HasColumnName(@"Address").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Shipment>().Property(x => x.ShippedDate).HasColumnName(@"ShippedDate").ValueGeneratedNever();
       modelBuilder.Entity<Shipment>().Property(x => x.DeliveredDate).HasColumnName(@"DeliveredDate").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Shipment>().Property(x => x.Price).HasColumnName(@"Price").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Shipment>().Property(x => x.OrderId).HasColumnName(@"OrderId").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Shipment>().HasKey(@"Id");
    }

    private void ProductMapping(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Product>().ToTable(@"Products");
       modelBuilder.Entity<Product>().Property(x => x.Id).HasColumnName(@"Id").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Product>().Property(x => x.Name).HasColumnName(@"Name").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Product>().Property(x => x.Description).HasColumnName(@"Description").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Product>().Property(x => x.Price).HasColumnName(@"Price").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Product>().Property(x => x.Quantity).HasColumnName(@"Quantity").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Product>().Property(x => x.OrderId).HasColumnName(@"OrderId").IsRequired().ValueGeneratedNever();
       modelBuilder.Entity<Product>().HasKey(@"Id");
    }

    private void RelationshipsMapping(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>()
          .HasOne(x => x.Shipment)
          .WithOne(op => op.Order)
          .HasForeignKey(typeof(Shipment), @"OrderId")
          .IsRequired(false);

       modelBuilder.Entity<Order>()
          .HasMany(x => x.Products)
          .WithOne(op => op.Order)
          .HasForeignKey(@"OrderId")
          .IsRequired(true);

       modelBuilder.Entity<Product>()
          .HasOne(x => x.Order)
          .WithMany(op => op.Products)
          .HasForeignKey(@"OrderId")
          .IsRequired(true);
    }
}

As you can see, in a few minutes with the Entity Developer, we were able to create our Model visually, and all the boilerplate code for Entity classes, DbContext and Mapping was generated for us automatically.

Now you can start implementing the actual business logic.

Here is how to register our DbContext in the DI:

var connectionString = builder.Configuration.GetConnectionString("Postgres");

builder.Services.AddDbContext<ShipmentDbContext>(options =>
{
    options.EnableSensitiveDataLogging()
       .UsePostgreSql(connectionString);
});

Note that we configure the connection to the database with UsePostgreSql from the Devart.Data.PostgreSql.
This package uses dotConnect for PostgreSQL to connect to the database.

This is what the Web API endpoint for creating an Order will look like:

public static class OrderEndpoints
{
    public static WebApplication MapOrderEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/api/orders");
        group.MapPost("/", CreateOrder);
        return app;
    }

    private static async Task<IResult> CreateOrder(
        [FromBody] CreateOrderRequest request,
        ShipmentDbContext dbContext)
    {
        var shipmentId = Guid.NewGuid();
        var shipment = MapToShipment(request.Shipment, shipmentId);

        var order = MapToOrder(request, shipment);

        foreach (var productRequest in request.Products)
        {
            var product = MapToProduct(productRequest, order.Id, order);
            order.Products.Add(product);
        }

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

        var response = MapToOrderResponse(order, shipment);

        return TypedResults.Created($"/api/orders/{order.Id}", response);
    }
}

With Entity Developer, you can focus on writing the code, and all the boilerplate code for the setup is generated automatically.

Core Benefits for EF Core and PostgreSQL Development

Entity Developer doesn't just simplify your daily tasks — it transforms the way you manage EF Core and PostgreSQL databases.

Using a Model-First approach, you visually design your database schema, and Entity Developer generates your EF Core models automatically.
This simplifies model management and synchronization between code and the database.

Entity Developer is more than just a visual modeling tool — it's designed to solve real problems that .NET developers face when working with EF Core and PostgreSQL.

Here is how Entity Developer improves your development workflow and boosts development productivity:

Accelerated Development: Spend less time on boilerplate and repetitive configuration. Design, generate, and update models much faster than manual coding allows.
Better Collaboration: The visual Model makes it easier to share ideas and discuss changes with teammates, regardless of their EF Core experience.
Error Prevention: Reduce the risk of runtime errors caused by hand-written mappings or misconfigured relationships. Entity Developer generates accurate code and schema scripts for you.
Maintainable Codebase: Consistent, auto-generated entity and context code means easier maintenance, fewer bugs, and quicker onboarding for new team members.
Flexible Database Support: Switch between PostgreSQL and other supported databases as your project grows, without changing your workflow.
Easy Integration: Use it directly in Visual Studio or as a standalone tool.
PostgreSQL Optimization: Get full advantage of PostgreSQL's unique features — like native UUIDs, JSONB, arrays, and advanced indexing — directly within your EF Core model.

By simplifying every step of the model-design-to-database workflow, Entity Developer helps you deliver projects on time and with greater confidence.

Note: Entity Developer supports the following databases: PostgreSQL, SQL Server, Oracle, MySQL, MariaDB, and SQLite.

Summary

Entity Developer by Devart, managing EF Core models and PostgreSQL databases has never been easier or faster.

Whether you're building a new application or maintaining an existing one, its visual Model-First approach lets you focus on what matters most — solving business problems and delivering value to users.

With automatic code and SQL script generation, robust Visual Studio integration, and support for advanced PostgreSQL features, Entity Developer is a must-have tool for any .NET developer who wants to simplify their workflow and boost productivity.

Ready to transform your EF Core development process?

Download the free trial for Entity Developer, connect it to your PostgreSQL database, and see how much more productive your next project can be!

Many thanks to Devart for sponsoring this blog post.

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Refactoring A Modular Monolith Without MediatR in .NET

Anton Martyniuk — Tue, 12 Aug 2025 10:41:15 +0000

MediatR is one of my favourite libraries in .NET, I have been using it for 5+ years in production.

I used MediatR to separate my read and write commands and queries, encapsulating them in separate classes.
It made my Presentation (API layer) very simple and elegant, and it reduces coupling between the handlers.

Eventually, I moved to a Vertical Slice Architecture, and MediatR remained the core of it.

But recently, in the new project, I decided to remove MediatR.

Over the last couple of months, I've thought that there's a better way to organize my use cases.
This was a feeling I had after I finished working on the project in late 2024.

This project had complex use cases, and my team ended up calling one MediatR Handler from another.
As you know, MediatR decouples the Command/Query from their Handlers, and this made code navigation and debugging much more difficult in our project.

After talking to my friend who had a similar problem with his projects, and after recent news that MediatR is going commercial, this was a turning point.
I will not be using MediatR in my next project.

Yes, there is a fairly generous Community license for MediatR that you can use for free, and I will continue to use MediatR in my existing projects.
But in the new projects, I will go without MediatR.

What about MediatR alternatives? One of the most popular is Wolverine.
Also, many developers have already created their custom MediatR libraries, and some of them are much faster than MediatR, such as MitMediator.

But I won't be using either of them.

Today, I want to show you how to refactor a Modular Monolith application from MediatR to manual handlers.
They are the best replacement for MediatR: easy code navigation and debugging, no reflection and decorators.

In this post, we will explore:

Initial implementation of a Modular Monolith with MediatR
Replacing MediatR with manual handlers
How to implement auto-registration of manual handlers
How to replace MediatR notifications
Managing cross-cutting concerns without MediatR

Let's dive in!

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Initial implementation of a Modular Monolith with MediatR

I have built a Modular Monolith with three modules: Shipments, Carriers, and Stocks.

Each module is built using a combination of Vertical Slice Architecture and Clean Architecture, which structures an application by features.
Each slice encapsulates all aspects of a specific feature, including the API, business logic, and data access.

Here is a project's structure:

Let's explore the CreateShipment use case of the Shipments module:

public class CreateShipmentEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/shipments", Handle);
    }

    private static async Task<IResult> Handle(
        [FromBody] CreateShipmentRequest request,
        IValidator<CreateShipmentRequest> validator,
        IMediator mediator,
        CancellationToken cancellationToken)
    {
        var validationResult = await validator.ValidateAsync(request, cancellationToken);
        if (!validationResult.IsValid)
        {
            return Results.ValidationProblem(validationResult.ToDictionary());
        }

        var command = request.MapToCommand();

        var response = await mediator.Send(command, cancellationToken);
        if (response.IsError)
        {
            return response.Errors.ToProblem();
        }

        return Results.Ok(response.Value);
    }
}

I use Carter library for structuring Minimal APIs and MediatR for encapsulating application logic in command handlers:

public async Task<ErrorOr<ShipmentResponse>> Handle(
    CreateShipmentCommand request,
    CancellationToken cancellationToken)
{
    // 1. Check if the shipment already exists
    var shipmentExists = await context.Shipments.AnyAsync(x => x.OrderId == request.OrderId, cancellationToken);
    if (shipmentExists)
    {
        logger.LogInformation("Shipment for order '{OrderId}' already exists", request.OrderId);
        return Error.Conflict($"Shipment for order '{request.OrderId}' already exists");
    }

    // 2. Check stock levels
    var stockRequest = CreateStockRequest(request);
    var stockResponse = await stockApi.CheckStockAsync(stockRequest, cancellationToken);

    if (!stockResponse.IsSuccess)
    {
        logger.LogInformation("Stock check failed: {ErrorMessage}", stockResponse.ErrorMessage);
        return Error.Validation("ProductsNotAvailableInStock", stockResponse.ErrorMessage ?? "Products not available in stock");
    }

    // 3. Save the shipment in the database
    var shipment = request.MapToShipment();

    await context.Shipments.AddAsync(shipment, cancellationToken);
    await context.SaveChangesAsync(cancellationToken);

    logger.LogInformation("Created shipment: {@Shipment}", shipment);

    // 4. Call the Carrier Module to create a shipment
    var carrierRequest = CreateCarrierRequest(request);
    await carrierApi.CreateShipmentAsync(carrierRequest, cancellationToken);

    // 5. Update stock levels
    var updateRequest = CreateUpdateStockRequest(shipment);
    var response = await stockApi.UpdateStockAsync(updateRequest, cancellationToken);

    if (!response.IsSuccess)
    {
        return Error.Failure("StockUpdateFailed", "Failed to update stock");
    }

    return shipment.MapToResponse();
}

MediatR is a great fit for Vertical Slice Architecture. It has the following advantages:

Code decoupling
Easy implementation of Command/Query Handler-per-Class
Built-in notifications with zero or many handlers
Built-in pipelines (middlewares) for implementing cross-cutting concerns

But it comes with the following drawbacks:

Harder code navigation
Harder to debug: you can't directly step inside a handler, you need to put breakpoints in each Handler
Slower performance because of reflection
Paid license for companies with revenue > 5M $ per year. Learn more here.

Honestly, these drawbacks are subjective:

You can put Command and Handler in the same file (and you should)
Performance penalty is not a thing for most projects

MediatR has never been a bad thing in the codebases of my team.
However, I have seen many terrible codebases where developers made a mess with MediatR.

And how can I take the best from MediatR and build something on my own to make my projects even better?

And here is where I got a brilliant idea: what if I build all the handlers manually?

Let's see how we can do this.

Replacing MediatR with Manual Handlers

I have created the following handlers for the Shipments module:

ICreateShipmentHandler, CreateShipmentHandler
IUpdateShipmentStatusHandler, UpdateShipmentStatusHandler
IGetShipmentByNumberHandler, GetShipmentByNumberHandler

Here is the ICreateShipmentHandler:

internal interface ICreateShipmentHandler
{
    Task<ErrorOr<ShipmentResponse>> HandleAsync(
        CreateShipmentRequest request,
        CancellationToken cancellationToken);
}

And the implementation:

internal sealed class CreateShipmentHandler(
    ShipmentsDbContext context,
    IStockModuleApi stockApi,
    IEventPublisher eventPublisher,
    ILogger<CreateShipmentHandler> logger)
    : ICreateShipmentHandler
{
    public async Task<ErrorOr<ShipmentResponse>> HandleAsync(
        CreateShipmentRequest request,
        CancellationToken cancellationToken)
    {
        // All the code remains the same
    }
}

In the API endpoint, I replaced IMediator with ICreateShipmentHandler:

public class CreateShipmentEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/shipments", Handle);
    }

    private static async Task<IResult> Handle(
        [FromBody] CreateShipmentRequest request,
        IValidator<CreateShipmentRequest> validator,
        ICreateShipmentHandler handler,
        CancellationToken cancellationToken)
    {
        var validationResult = await validator.ValidateAsync(request, cancellationToken);
        if (!validationResult.IsValid)
        {
            return Results.ValidationProblem(validationResult.ToDictionary());
        }

        var response = await handler.HandleAsync(request, cancellationToken);
        if (response.IsError)
        {
            return response.Errors.ToProblem();
        }

        return Results.Ok(response.Value);
    }
}

And that's it.

This approach has the following benefits:

We are injecting an exact interface, no guesses about the handlers
Easier navigation and debugging: you can step into the handler implementation
No reflection and other magic

Of course, you can register every handler manually in the DI container:

builder.Services.AddScoped<ICreateShipmentHandler, CreateShipmentHandler>();

But it's tiresome.
Let's explore a better option.

Implementing Handler Auto-Registration in DI

It's better to implement a simple auto-registration of our Handlers and their implementations, just like in MediatR.

First, we need a market interface that handlers will inherit:

/// <summary>
/// Marker interface for all handlers in the application
/// </summary>
public interface IHandler;

// Inheriting from the marker inteface
internal interface ICreateShipmentHandler : IHandler
{
    Task<ErrorOr<ShipmentResponse>> HandleAsync(
        CreateShipmentRequest request,
        CancellationToken cancellationToken);
}

Note: we don't need to make any changes in the CreateShipmentHandler implementation.

Next, we need to make the assembly scanning and some reflection (but we only do this once on the application startup) to find and register our handlers:

public static class HandlerRegistrationExtensions
{
    /// <summary>
    /// Registers all handlers from the assembly containing the specified type
    /// </summary>
    /// <param name="services">The service collection</param>
    /// <param name="marker">A type from the assembly where handlers are located</param>
    /// <returns>The service collection for chaining</returns>
    public static IServiceCollection RegisterHandlersFromAssemblyContaining(
        this IServiceCollection services, Type marker)
    {
        RegisterCommandHandlers(services, marker.Assembly);
    }

    private static void RegisterCommandHandlers(IServiceCollection services, Assembly assembly)
    {
        var handlerTypes = assembly.GetTypes()
            .Where(t => t is { IsClass: true, IsAbstract: false }
                && t.IsAssignableTo(typeof(IHandler))
            .ToList();

        foreach (var implementationType in handlerTypes)
        {
            var interfaceType = implementationType.GetInterfaces()
                .FirstOrDefault(i => i != typeof(IHandler) && i.IsAssignableTo(typeof(IHandler)));

            if (interfaceType is not null)
            {
                services.AddScoped(interfaceType, implementationType);
            }
        }
    }

Now we can call the RegisterHandlersFromAssemblyContaining method and pass the type in the assembly:

builder.Services.RegisterHandlersFromAssemblyContaining(typeof(CreateShipmentHandler));

Replacing MediatR Notification Handlers

One of the best features in MediatR is the ability to have zero or many handlers for notifications.

Let's see how we can build this ourselves.

First, we need a couple of marker interfaces for the Event and EventHandler:

/// <summary>
/// Marker interface for all events in the application
/// </summary>
public interface IEvent;

/// <summary>
/// Marker interface for all event handlers in the application
/// </summary>
public interface IEventHandler;

/// <summary>
/// Base interface for typed event handlers
/// </summary>
/// <typeparam name="TEvent">Type of event handled by this handler</typeparam>
public interface IEventHandler<in TEvent> : IEventHandler where TEvent : IEvent
{
    Task HandleAsync(TEvent @event, CancellationToken cancellationToken);
}

And here is our event publisher:

/// <summary>
/// Interface for publishing events
/// </summary>
public interface IEventPublisher
{
    /// <summary>
    /// Publishes an event to all registered handlers
    /// </summary>
    /// <typeparam name="TEvent">The type of event to publish</typeparam>
    /// <param name="event">The event instance</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>A task representing the asynchronous operation</returns>
    Task PublishAsync<TEvent>(TEvent @event, CancellationToken cancellationToken)
        where TEvent : IEvent;
}

/// <summary>
/// Implementation of IEventPublisher that resolves all handlers for an event
/// and executes them in parallel
/// </summary>
public class EventPublisher(
    IServiceProvider serviceProvider)
    : IEventPublisher
{
    /// <inheritdoc />
    public async Task PublishAsync<TEvent>(
        TEvent @event,
        CancellationToken cancellationToken)
        where TEvent : IEvent
    {
        var eventType = @event.GetType();

        try
        {
            // Resolve all handlers for this event type
            var handlers = serviceProvider.GetServices<IEventHandler<TEvent>>().ToArray();
            if (handlers.Length == 0)
            {
                return;
            }

            // Execute all handlers and collect results
            var handlerTasks = handlers.Select(handler =>
                    ExecuteHandlerAsync(handler, @event, cancellationToken)
                ).ToList();

            await Task.WhenAll(handlerTasks);
        }
        catch (Exception ex)
        {
            throw;
        }
    }

    private async Task<Exception?> ExecuteHandlerAsync<TEvent>(
        IEventHandler<TEvent> handler, 
        TEvent @event, 
        CancellationToken cancellationToken) where TEvent : IEvent
    {
        await handler.HandleAsync(@event, cancellationToken);
    }
}

The benefit of our implementation is that we have complete freedom to make any changes.
We can call all the handlers in parallel, make a commit of the database transaction, throw an aggregate exception, use a result pattern, and so on.

await Task.WhenAll(handlerTasks);

Now we can use events to call the Carrier and Stock module that react to ShipmentCreatedEvent:

/// <summary>
/// Event that is raised when a shipment is created
/// </summary>
public sealed record ShipmentCreatedEvent(Shipment Shipment) : IEvent;

internal sealed class CreateShipmentHandler(
    ShipmentsDbContext context,
    IStockModuleApi stockApi,
    IEventPublisher eventPublisher,
    ILogger<CreateShipmentHandler> logger)
    : ICreateShipmentHandler
{
    public async Task<ErrorOr<ShipmentResponse>> HandleAsync(
        CreateShipmentRequest request,
        CancellationToken cancellationToken)
    {
        // Code remains the same as in the previous example

        try
        {
            var shipmentCreatedEvent = new ShipmentCreatedEvent(shipment);
            await eventPublisher.PublishAsync(shipmentCreatedEvent, cancellationToken);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Failed to process shipment events for order {OrderId}", request.OrderId);
            return Error.Failure("ShipmentProcessingFailed", "Failed to process shipment");
        }

        return shipment.MapToResponse();
    }
}

Here is what our event handlers look like:

/// <summary>
/// Event handler that creates a carrier shipment when a shipment is created
/// </summary>
public sealed class CreateCarrierEventHandler(
    ICarrierModuleApi carrierApi,
    ILogger<CreateCarrierEventHandler> logger)
    : IEventHandler<ShipmentCreatedEvent>
{
}

/// <summary>
/// Event handler that updates stock when a shipment is created
/// </summary>
public sealed class UpdateStockEventHandler(
    IStockModuleApi stockApi,
    ILogger<UpdateStockEventHandler> logger)
    : IEventHandler<ShipmentCreatedEvent>
{
}

We can implement event handler auto-registration the way we did for our Handlers.

Managing cross-cutting concerns without MediatR

Now it's time to address the final part of MediatR - pipeline behaviours (middlewares).
Developers used them to implement:

Validation
Mapping
Logging
Caching
Exception handling

Honestly, I won't reimplement this logic myself. Cross-cutting concerns can be addressed in the Presentation (API/transport level).

Here is how we can address cross-cutting concerns in the API layer in ASP .NET Core:

Validation: manually calling validators inside Controllers or Minimal API endpoints.
Alternatives: create a middleware or use the FastEndpoints library, which has FluentValidation built in.
Mapping: inject an API request directly into the Handler without creating an additional layer of models (Request and Entity, no Command here).
I recommend using manual mapping.
Logging: use built-in HttpLogging for API requests.
Caching: use Output caching or IMemory/IDistributed/HybridCache/FusionCache
Exception handling: use the built-in Global Exception Handler in .NET 8+

Here is our Minimal API endpoint for creating a shipment:

public class CreateShipmentEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/shipments", Handle);
    }

    private static async Task<IResult> Handle(
        [FromBody] CreateShipmentRequest request,
        IValidator<CreateShipmentRequest> validator,
        ICreateShipmentHandler handler,
        CancellationToken cancellationToken)
    {
        var validationResult = await validator.ValidateAsync(request, cancellationToken);
        if (!validationResult.IsValid)
        {
            return Results.ValidationProblem(validationResult.ToDictionary());
        }

        var response = await handler.HandleAsync(request, cancellationToken);
        if (response.IsError)
        {
            return response.Errors.ToProblem();
        }

        return Results.Ok(response.Value);
    }
}

Here we manually call the validator and pass the API request model into the Handler.
I am not creating another layer of models, like I passed a Command in the MediatR implementation.

Summary

In this post, I've shown you what I consider the best alternative to MediatR.
From now on, I will be using manual handlers in the new projects.

They provide the following benefits when compared to MediatR:

Easier code navigation and debugging
Easier to understand code
No reflection and better performance
You have complete control over the implementation
Easier unit testing of the code that calls the Handlers
No licensing concerns

I believe that implementing cross-cutting concerns can be achieved with built-in ASP.NET Core features.

Don't get me wrong, MediatR is still an excellent library.
So, only you can decide what works best for your project.

P.S.: I publish all these blogs on my own website: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Building High-Performance .NET Apps With C# Channels

Anton Martyniuk — Tue, 05 Aug 2025 10:35:48 +0000

Building reliable, scalable, and high-performance .NET applications often comes down to how you handle concurrency and data processing.
C# Channels bring a new, modern approach for building safe, asynchronous, and high-throughput pipelines in .NET.

Channels allow you to create in-memory producer-consumer queues that scale naturally across async workflows and background services.
However, a crucial architectural decision is choosing between bounded and unbounded channels.

In today's post, we will explore:

What are C# Channels?
Bounded vs. Unbounded Channels
Background Processing with Channels
Using channels in an ASP.NET Core real-world application
Best practices and tips for working with Channels

Let's dive in!

P.S.: I publish all these blogs on my own website.: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

What are C# Channels?

When building .NET apps, you often need to send data from one part of your code to another.

In the past, developers used constructs such as Queue, ConcurrentQueue, or BlockingCollection for this purpose.
They encapsulated these queues into classes and used them to manage their data flows.

However, such implementations have a significant drawback: tight code coupling.

C# Channels solve this problem. They implement a producer-consumer pattern.
One class produces data and the other consumes it, without knowing about each other.

C# Channels come from the System.Threading.Channels namespace.
Channels make it simple to send data between producers and consumers, helping you avoid common threading problems.

A channel has two parts:

Writer: pushes data into the Channel.
Reader: pulls data out of the Channel.

Both reading and writing can occur on different threads, and Channels ensure thread safety.
They let you use async code everywhere, so your app can handle lots of data without blocking threads or locking.

Here's a basic example of using channels in C#.
Here we asynchronously produce numbers and consume them from the Channel:

using System;
using System.Threading.Channels;
using System.Threading.Tasks;

var channel = Channel.CreateUnbounded<int>();

// Producer
_ = Task.Run(async () =>
{
    for (var i = 0; i < 10; i++)
    {
        await channel.Writer.WriteAsync(i);
        Console.WriteLine($"Produced: {i}");
        await Task.Delay(100); // simulate work
    }
    channel.Writer.Complete();
});

// Consumer
await foreach (var item in channel.Reader.ReadAllAsync())
{
    Console.WriteLine($"Consumed: {item}");
    await Task.Delay(150); // simulate processing
}

Console.WriteLine("Processing complete.");

Here is how it works:

The producer runs on a separate Thread (Task), writing data to the Channel.
The consumer reads data from the Channel and processes it.
The Channel handles all communication and thread safety.

Channels are a great fit when:

You need to connect producers and consumers using async/await.
You want to decouple the producing and consuming logic
You want to control the flow of data (for example, slow down producers if consumers can't keep up).
You want to avoid low-level threading, locking, or manual synchronization.

Channels are ideal for streaming events and processing background tasks.
They are a simple in-memory alternative to message queues within a single application.

Bounded vs. Unbounded Channels

C# channels can be of 2 types: bounded and unbounded.
Both let you pass data from a producer to a consumer, but they handle flow control and memory differently.

What is a Bounded Channel?

A bounded channel has a fixed maximum capacity.
When you create it, you set the limit for the number of items it can hold at once.

If the producer tries to add more items after the Channel is full, it has to wait until there is space.

When should you use a bounded channel?

When you want to limit memory usage and prevent overload.
When the consumer is sometimes slower than the producer.
When you need backpressure to avoid flooding your system.

var channel = Channel.CreateBounded<int>(5);

// Producer
await channel.Writer.WriteAsync(1); // Adds item if there's space, waits if full

// Consumer
var item = await channel.Reader.ReadAsync(); // Takes an item

Bounded channels are a good choice for background processing, job queues, and any application where you need to control resource usage.
They help protect your app from sudden spikes and runaway producers.

What is an Unbounded Channel?

An unbounded channel has no fixed limit.
The producer can keep adding items as fast as they want.

The Channel will grow to handle as many items as you put in it, limited only by available system memory.

When should you use an unbounded channel?

When you are sure the producer will never outpace the consumer for long.
For simple cases where flow control is not a problem.
When you expect only a small or steady stream of items.

Here is how to create an unbounded channel:

var channel = Channel.CreateUnbounded<int>();

// Producer
await channel.Writer.WriteAsync(42); // Always accepts new items

// Consumer
var item = await channel.Reader.ReadAsync(); // Takes an item

Unbounded channels are simple to use, but they can be risky in high-load situations.
If the producer writes items faster than the consumer reads them, you can run out of memory.

Which one should you use?

If you want safety and stability in your system, start with bounded channels.
They protect your app if the consumer falls behind.

If you know your producer is always in control and the data rate is low, you can use unbounded channels.

In most real-world .NET services, bounded channels are the safer default.

Background Processor with a Bounded Channel

In production, channels are often used in ASP.NET Core background services.

A common pattern is to set up a background service that reads messages or tasks from a channel and processes them one by one.
This makes your code easy to scale and keeps the main thread free for other work.

Let's explore an example of a BackgroundService that processes items from a Channel:

builder.Services.AddSingleton(_ => Channel.CreateBounded<string>(new BoundedChannelOptions(100)
{
    FullMode = BoundedChannelFullMode.Wait
}));

public class MessageProcessor : BackgroundService
{
    private readonly Channel<string> _channel;
    private readonly ILogger<MessageProcessor> _logger;

    public MessageProcessor(Channel<string> channel, ILogger<MessageProcessor> logger)
    {
       _channel = channel;
       _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
       _logger.LogInformation("Message processor starting");

       await foreach (var message in _channel.Reader.ReadAllAsync(stoppingToken))
       {
          _logger.LogInformation("Processing message: {Message}", message);

          await Task.Delay(100, stoppingToken);

          _logger.LogInformation("Message processed successfully: {Message}", message);
       }
    }
}

To publish items into the Channel, you need to call the WriteAsync method:

private Task AddSampleMessagesAsync(CancellationToken stoppingToken)
{
    _ = Task.Run(async () =>
    {
        // Add 150 messages (more than channel capacity of 100)
        for (var i = 1; i <= 150 && !stoppingToken.IsCancellationRequested; i++)
        {
            var message = $"Sample message #{i}";

            // Wait until there's space in the Channel (this will block when the Channel is full)
            await _channel.Writer.WriteAsync(message, stoppingToken);

            _logger.LogInformation("Added message to channel: {Message}", message);

            await Task.Delay(50, stoppingToken);
        }

        // Complete the Channel when done adding messages
        _channel.Writer.Complete();
    }, stoppingToken);
    return Task.CompletedTask;
}

Notice that we run the foreach loop over AsyncEnumerable:

await foreach (var message in _channel.Reader.ReadAllAsync(stoppingToken))
{
    // Process message
}

The _channel.Reader.ReadAllAsync waits for a new message to appear in the Channel.
When done publishing messages, you can call _channel.Writer.Complete() and the loop will end.

The Channel is bounded with a capacity of 100, so if 100 messages are already waiting, the producer will pause until a free slot becomes available.
The background service reads messages as fast as it can process them.

If you try to add messages too quickly, the producer will slow down, which keeps your memory usage under control.

When creating a bounded channel, you can set BoundedChannelFullMode to control what happens when the Channel is full:

Wait: The writer waits until space is available (most common, safest).
DropWrite: New items are dropped if the Channel is full.
DropOldest: The oldest item is removed to make space for the new one.
DropNewest: The newest item is dropped instead.

For most background tasks, use Wait. When losing a few messages is acceptable, DropWrite or DropOldest can be a suitable option.
You can use DropOldest when the latest event is more relevant than the older ones.

Real-World Application with Channels

In a real-world ASP.NET Core application, you can use Channels to implement Write Back Caching Strategy.

This caching strategy is used in high-speed, write-intensive scenarios.

The main idea is that the data is first written to the cache.
The cache asynchronously writes the data back to the database after a certain condition or interval.

Let's explore a real-world example: an Online Store application.

Users frequently add or remove items from their online shopping carts. The final state is only really critical at checkout.
Writes can be very fast since they hit the cache first, and the system can periodically flush updates to the database.

This enables high write throughput during peak shopping times, with the database eventually getting the final cart details.

Here is the WebApi endpoint that creates a product cart:

public record ProductCartRequest(string UserId, List<ProductCartItemRequest> ProductCartItems);

public record ProductCartItemRequest(Guid ProductId, int Quantity);

[HttpPost]
public async Task<ActionResult<ProductCartResponse>> CreateCart(ProductCartRequest request)
{
    var response = await _service.AddAsync(request);
    return CreatedAtAction(nameof(GetCart), new { id = response.Id }, response);
}

When creating a new ProductCart, it is immediately added to the cache only:

public class WriteBackCacheProductCartService
{
    private readonly HybridCache _cache;
    private readonly IProductCartRepository _repository;
    private readonly Channel<ProductCartDispatchEvent> _channel;

    public WriteBackCacheProductCartService(
        HybridCache cache,
        IProductCartRepository repository,
        Channel<ProductCartDispatchEvent> channel)
    {
        _cache = cache;
        _repository = repository;
        _channel = channel;
    }

    public async Task<ProductCartResponse> AddAsync(ProductCartRequest request)
    {
        var productCart = new ProductCart
        {
            Id = Guid.NewGuid(),
            UserId = request.UserId,
            CartItems = request.ProductCartItems.Select(x => new CartItem
            {
                Id = Guid.NewGuid(),
                Quantity = x.Quantity,
                Price = Random.Shared.Next(100, 1000)
            }).ToList()
        };

        var cacheKey = $"productCart:{productCart.Id}";

        var productCartResponse = MapToProductCartResponse(productCart);
        await _cache.SetAsync(cacheKey, productCartResponse);

        await _channel.Writer.WriteAsync(new ProductCartDispatchEvent(productCart));

        return productCartResponse;
    }
}

Here we use a Bounded Channel to publish ProductCartDispatchEvent.

public record ProductCartDispatchEvent(ProductCart ProductCart);

builder.Services.AddSingleton(_ => Channel.CreateBounded<ProductCartDispatchEvent>(new BoundedChannelOptions(100)
{
    FullMode = BoundedChannelFullMode.Wait
}));

A background reads from the Channel and writes cart data to the database asynchronously:

public class WriteBackCacheBackgroundService(IServiceScopeFactory scopeFactory,
    Channel<ProductCartDispatchEvent> channel) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var command in channel.Reader.ReadAllAsync(stoppingToken))
        {
            using var scope = scopeFactory.CreateScope();
            var repository = scope.ServiceProvider.GetRequiredService<IProductCartRepository>();

            var existingCart = await repository.GetByIdAsync(command.ProductCart.Id);
            if (existingCart is null)
            {
                await repository.AddAsync(command.ProductCart);
                return;
            }

            existingCart.CartItems = command.ProductCart.CartItems;
            await repository.UpdateAsync(existingCart);
        }
    }
}

Note: This pattern can significantly speed up writes, but it requires robust conflict resolution and failure handling to ensure consistency.
Ensuring the cart state is never lost in case of a cache failure, requires robust replication or backup mechanisms.

Best Practices and Tips for Working with Channels

Channels are a powerful tool, but to get the most out of them (and avoid problems), it's important to follow a few key best practices.
Here are some practical tips for using channels in your .NET applications.

1. Prefer Bounded Channels for Safety:

Most of the time, you should start with a bounded channel.
A bounded channel sets a limit on the amount of data that can be waiting to be processed.
This makes your application more stable under a heavy load.

Set the capacity to a reasonable number for your workload.
If you expect spikes in data, pick a value that covers typical bursts but is not too large.

Unbounded channels are only safe when you know the data rate is always low.

2. Remember to Complete the Channel:

When your producer is done writing, call .Writer.Complete() on the Channel.
This lets the consumer know that there will be no more data, allowing it to finish.

If you don't complete the Channel, your consumer's ReadAllAsync loop will never end.

3. Use await with Write and Read Operations:

Channels are made for async code.
Always use await when writing or reading to avoid blocking threads and to keep your app responsive.

await Channel.Writer.WriteAsync(data, cancellationToken);
await foreach (var item in channel.Reader.ReadAllAsync(cancellationToken))
{
    // process item
}

4. Handle Cancellation Properly:

Always pass a CancellationToken when reading or writing to a channel.
This allows you to stop processing if your app is shutting down or if a user cancels an operation.

await channel.Writer.WriteAsync(message, cancellationToken);

5. Don't Share Channels Between Too Many Producers or Consumers:

While channels can handle multiple writers and readers, having too many can make things hard to debug.
In most cases, stick to a single producer and a single consumer for best performance and easiest reasoning.

If you need more, .NET channels support multiple readers and writers, but you should design carefully to avoid surprises.

6. Monitor Your Channel Usage:

Watch your Channel's capacity in production.
If you often see the Channel filling up (producers waiting to write), it may mean your consumers are too slow.
You might need to speed up your processing or increase the channel size.

7. Choose the Right FullMode (For Bounded Channels):

When creating a bounded channel, you can set BoundedChannelFullMode to control what happens when the Channel is full.

P.S.: I publish all these blogs on my own website.: Read original post here
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

How To Implement Offset and Cursor-Based Pagination in EF Core

Anton Martyniuk — Tue, 29 Jul 2025 11:13:54 +0000

Efficient pagination is crucial for enhancing application performance and user experience, particularly when working with large datasets.
Pagination ensures quick data retrieval, reduces server load, and improves usability by delivering content in manageable chunks.

In this newsletter, you'll learn step-by-step how to implement two popular pagination techniques in EF Core: offset-based pagination and cursor-based pagination (also known as keyset or seek pagination).

In this post, we will explore:

How to implement offset-based pagination
How to implement cursor-based pagination
Advanced techniques to handle cursor pagination on multiple properties
Encoding and decoding cursors

Let's dive in!

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

How To Implement Offset-Based Pagination

Offset-based pagination is one of the simplest and most widely-used pagination methods.
It works by skipping a specified number of records (offset) and then fetching a set number of records (page size).

The offset-based approach uses two parameters:

Offset: The number of records to skip.
Limit (Page Size): The number of records to retrieve.

In EF Core, you typically achieve this by combining .Skip() and .Take() methods.

Let's explore an example with a Book's store:

public class Book
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public DateTime PublishedAt { get; set; }
    public string Isbn { get; set; }

    public Guid AuthorId { get; set; }
    public Author Author { get; set; }

    public int PageCount { get; set; }
    public decimal Price { get; set; }
    public decimal Rating { get; set; }
}

Here is a simple API endpoint that implements Offset-Based pagination:

app.MapGet("/api/books", async (
    ApplicationDbContext context,
    [FromQuery] int page = 1,
    [FromQuery] int pageSize = 10,
    CancellationToken cancellationToken = default) => 
{
    if (pageSize > 100)
    {
        pageSize = 100;
    }

    var query = context.Books
        .Include(b => b.Author)
        .AsQueryable();

    var totalItems = await query.CountAsync(cancellationToken);

    var books = await query
        .OrderBy(b => b.Title)
        // We implement Offset-based pagination with Skip + Take
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .Select(b => new BookResponse(
            b.Id,
            b.Title,
            b.Year,
            b.AuthorId,
            b.Rating,
            b.PublishedAt))
        .ToListAsync(cancellationToken);

    var totalPages = (int)Math.Ceiling(totalItems / (double)pageSize);

    var result = new
    {
        Books = books,
        Pagination = new
        {
            CurrentPage = page,
            PageSize = pageSize,
            TotalItems = totalItems,
            TotalPages = totalPages,
            HasPrevious = page > 1,
            HasNext = page < totalPages
        }
    };

    return Results.Ok(result);
});

Note: always limit the maximum number of items per page on the backend.
This will prevent exploit issues with API methods that ask for too many items, which can slow down the entire server.

You can also combine filters with pagination.
For example, we can filter books by Year and return paginated results:

app.MapGet("/api/books", async (
    ApplicationDbContext context,
    [FromQuery] int page = 1,
    [FromQuery] int pageSize = 10,
    [FromQuery] int? year = null,
    CancellationToken cancellationToken = default) => 
{
    if (pageSize > 100)
    {
        pageSize = 100;
    }

    var query = context.Books
        .Include(b => b.Author)
        .AsQueryable();

    // Apply the filter if specified
    if (year.HasValue)
    {
        query = query.Where(b => b.Year == year.Value);
    }

    var totalItems = await query.CountAsync(cancellationToken);

    var books = await query
        .OrderBy(b => b.Title)
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        // Omitted for brevity
        .Select(b => new BookResponse(...)
        .ToListAsync(cancellationToken);

    var totalPages = (int)Math.Ceiling(totalItems / (double)pageSize);

    var result = new
    {
        Books = books,
        Pagination = new
        {
            CurrentPage = page,
            PageSize = pageSize,
            TotalItems = totalItems,
            TotalPages = totalPages,
            HasPrevious = page > 1,
            HasNext = page < totalPages
        }
    };

    return Results.Ok(result);
});

Here are the pros and cons of offset-based pagination.

Pros:

Simplicity: Easy to understand, implement, and debug.
Statelessness: Each request independently fetches a specific page without needing context from previous requests.

Cons:

Performance: Efficiency decreases with higher offsets because the database must scan all records up to the offset point. Even if you use indexes, the database still needs to go through all the rows.
Consistency Issues: If the underlying data changes frequently, users may experience inconsistencies, such as duplicated or missed records, when navigating between pages.

Offset-based pagination is ideal for small to medium-sized datasets or scenarios where the simplicity of implementation outweighs performance concerns.

Real-world example: online store where a user can navigate on a random page number.

How To Implement Cursor-Based Pagination

Cursor-based pagination, also known as keyset or seek pagination, is a more efficient method for large datasets.

Instead of skipping records, cursor-based pagination retrieves the next set of records starting from a specific point, called cursor, usually based on a unique or sorted column.
The cursor represents a unique column (or a group of unique columns) in the database, such as an ID or timestamp.

How it works:

The client requests the first page, and the server sends the cursor in response.
On the next request, the client sends this cursor to the server to fetch the next set of data.
The server queries records that are greater (or less) than the cursor value.

In our book's store, we can create a cursor based on the Id (primary key) column.

Here is a basic example of how to implement cursor-based pagination:

var query = context.Books
    .Include(b => b.Author)
    .AsQueryable();

if (lastId.HasValue)
{
    // Filter by cursor to get the next items
    query = query.Where(b => b.Id >= lastId.Value);
}

var books = await query
    .OrderBy(b => b.Id)
    .Take(limit + 1)
    .ToListAsync(cancellationToken);

The first time, the client sends an empty lastId and gets the first page.

To get the next page, the client must send an Id of the last item on the page.

Here is a complete example of a WebApi request:

private static async Task<IResult> HandleCursorPagination(
    ApplicationDbContext context,
    [FromQuery] Guid? lastId = null,
    [FromQuery] int limit = 10,
    CancellationToken cancellationToken = default)
{
    var query = context.Books
        .Include(b => b.Author)
        .AsQueryable();

    if (lastId.HasValue)
    {
        // Filter by cursor to get the next items
        query = query.Where(b => b.Id >= lastId.Value);
    }

    var books = await query
        .OrderBy(b => b.Id)
        .Take(limit + 1)
        .ToListAsync(cancellationToken);

    var hasMore = books.Count > limit;
    if (hasMore)
    {
        books.RemoveAt(books.Count - 1);
    }

    var result = new
    {
        Books = books
            // Omitted for brevity
            .Select(b => new BookResponse(...)
            .ToList(),
        Pagination = new
        {
            HasMore = hasMore
        }
    };

    return Results.Ok(result);
}

The server sorts the database records by the Id column and returns records that are bigger than the lastId.

Each time we perform pagination, we retrieve one additional record from the database to determine if there are more pages.

Here are the pros and cons of cursor-based pagination.

Pros:

Performance: Efficient even for large datasets, as it avoids scanning all records up to an offset.
Consistency: Provides consistent results even when data changes frequently, reducing duplicates and missing records between pages.

Cons:

Complexity: More challenging to implement and understand compared to offset-based pagination.
Statefulness: Requires maintaining the cursor state between requests.

Cursor-based pagination is ideal for scenarios that demand high performance and consistency, especially for handling large-scale data.

Real-world example: social media feed or an image gallery where you can only get the next items.

Using Multiple Fields in a Cursor-Based Pagination

In real-world use cases, you might need to use multiple properties in the cursor.

If your data can have duplicate values for the single-field cursor, you may need to add more fields to the cursor.

In the case of an online store, these could be Id and PublishedAt columns:

var query = context.Books
    .Include(b => b.Author)
    .OrderByDescending(b => b.PublishedAt)
    .ThenBy(b => b.Id)
    .AsQueryable();

if (publishedAt.HasValue)
{
    query = query.Where(b =>
        b.PublishedAt > publishedAt.Value ||
        (b.PublishedAt == publishedAt.Value && b.Id >= lastId!.Value));
}

var books = await query
    .Take(limit + 1)
    .ToListAsync(cancellationToken);

In this example, pagination handles two cases:

Books published after the cursor date
Books published on the same date but with ID greater than or equal to the last seen ID

This ensures proper pagination even when multiple books share the same publication date.

Real-world examples: paginating comments, transactions, or any time-series data with possible collisions.

Encoding and decoding Cursor

In practical terms, a cursor is a token representing the position of the last item on the current page.
When the client requests the next page, it sends this token back to the server, which uses it to continue the query from the correct position.

Sending multiple parameters from client to server in the paging requests has a few major drawbacks:

Each time when you need to update the cursor fields - you need to change both client and server
Raw property values (like IDs or timestamps) might expose internal details.

Instead, we can encapsulate the logic of cursor generation on the server by encoding and decoding the cursor.
Encoding the cursor hides sensitive implementation details and prevents users from easily guessing or manipulating pagination positions.

It also simplifies the process for clients using the API, as they don't need to know how to construct the cursor.
A client receives the next (and back if needed) cursor from the server and sends it in the next request.

Encoding a cursor involves the following steps:

Combine all the necessary cursor property values into a single string (such as JSON or a delimiter-separated string).
Encode the result using Base64 (or another encoding) so it's URL-safe.
Optionally, sign or encrypt the encoded cursor for extra security.

On the server, the decoding process is the reverse:

Decrypt the cursor (optionally)
Decode the cursor from Base64.
Parse the decoded string back into the original property values (e.g., parse JSON).

Here is how to implement Cursor encoding and decoding for our application:

public sealed record Cursor(Guid LastId, DateTime? PublishedAt = null)
{
    public static string Encode(Guid lastId, DateTime? publishedAt = null)
    {
        var cursor = new Cursor(lastId, publishedAt);
        var json = JsonSerializer.Serialize(cursor);
        return Base64UrlTextEncoder.Encode(Encoding.UTF8.GetBytes(json));
    }

    public static Cursor? Decode(string? cursor)
    {
        if (string.IsNullOrWhiteSpace(cursor))
        {
            return null;
        }

        try
        {
            var json = Encoding.UTF8.GetString(Base64UrlTextEncoder.Decode(cursor));
            return JsonSerializer.Deserialize<Cursor>(json);
        }
        catch
        {
            return null;
        }
    }
}

Here is an improved WebApi request that uses cursor encoding and decoding:

private static async Task<IResult> HandleCursorDatePagination(
    ApplicationDbContext context,
    [FromQuery] string? cursor = null,
    [FromQuery] int limit = 10,
    CancellationToken cancellationToken = default)
{
    var decodedCursor = Cursor.Decode(cursor);
    var lastId = decodedCursor?.LastId;
    var publishedAt = decodedCursor?.PublishedAt;

    var query = context.Books
        .Include(b => b.Author)
        .OrderByDescending(b => b.PublishedAt)
        .ThenBy(b => b.Id)
        .AsQueryable();

    if (publishedAt.HasValue)
    {
        query = query.Where(b =>
            b.PublishedAt > publishedAt.Value ||
            (b.PublishedAt == publishedAt.Value && b.Id >= lastId!.Value));
    }

    var books = await query
        .Take(limit + 1)
        .ToListAsync(cancellationToken);

    var hasMore = books.Count > limit;
    if (hasMore)
    {
        books.RemoveAt(books.Count - 1);
    }

    var lastBook = books.LastOrDefault();
    var nextCursor = hasMore && lastBook != null
        ? Cursor.Encode(lastBook.Id, lastBook.PublishedAt)
        : null;

    var result = new
    {
        Books = books
            // Omitted for brevity
            .Select(b => new BookResponse(...)
            .ToList(),
        Pagination = new
        {
            NextCursor = nextCursor,
            HasMore = hasMore
        }
    };

    return Results.Ok(result);
}

To get the first page, send the following request without a cursor:

GET {{host}}/api/books/cursor-date?limit=10

As a result, you will receive the following response:

{
  "books": [
    {
      "id": "01979c64-41bd-779c-9ef9-7252db9f00c0",
      "title": "Generic Soft Gloves",
      "year": 2020,
      "authorId": "9d6f4384-e89a-497a-8699-d4ed95a1803f",
      "rating": 1.83,
      "publishedAt": "2025-06-22T01:59:44.754392Z"
    },
    ...
  ],
  "pagination": {
    "nextCursor": "eyJMYXN0SWQiOiIwMTk3OWM2NC00MWI1LTdmNjgtODQ3OC1kMWRiYmYwODNlZjUiLCJQdWJsaXNoZWRBdCI6IjIwMjUtMDUtMjdUMDg6MzQ6MTQuMzM5MTEzWiJ9",
    "hasMore": true
  }
}

To get to the next page, send the received cursor:

GET {{host}}/api/books/cursor-date?cursor=eyJMYXN0SWQiOiIwMTk3OWM2NC00MWI1LTdmNjgtODQ3OC1kMWRiYmYwODNlZjUiLCJQdWJsaXNoZWRBdCI6IjIwMjUtMDUtMjdUMDg6MzQ6MTQuMzM5MTEzWiJ9&limit=10

Important Considerations:

Cursor Expiry: In fast-changing datasets, consider expiring or validating old cursors to avoid referencing deleted or changed data.
Validation: Always validate decoded cursor data to ensure it's well-formed and matches expected types.
Compatibility: If you change the sort logic or schema, old cursors may become invalid. Plan versioning or migration as needed.

Summary

Pagination is a foundational feature for any application working with large datasets, directly impacting performance, scalability, and user experience.
While offset-based pagination is simple and easy to implement, it can struggle with large data and real-time changes.

Cursor-based pagination (keyset/seek pagination) offers better performance and consistency, especially for large and dynamic datasets.
Though it comes with added complexity.

Use Offset-Based pagination when you need to access a random page or in scenarios where the simplicity of implementation outweighs performance concerns.

In other cases, you can use Cursor-Based pagination for better performance, control over pagination behavior, and enhanced security by encapsulation fields into the cursor without a client knowing about it.

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Real-Time Server-Sent Events in ASP.NET Core and .NET 10

Anton Martyniuk — Tue, 22 Jul 2025 11:01:16 +0000

You may need to integrate real-time updates in your .NET application from the backend to the frontend.
You have a few options to implement this:

Polling — frontend continuously checks the server for new data
SignalR — frontend subscribes to an event, and the server sends this event using WebSockets
Server-Sent Events (already available in .NET 10 preview)

Polling endpoints every few seconds can overload your server and waste bandwidth, while full-duplex WebSockets may be overkill for simple, one-way updates.

Server-Sent Events (SSE) provide a lightweight, reliable way for ASP.NET Core apps to push continuous streams of data without the complexity of bidirectional protocols.

Today, I want to show you how to use Server-Sent Events in .NET 10:

How SSE works and why it matters
Implementing an SSE endpoint with Minimal APIs
Handling reconnections via the Last-Event-ID header
Testing your SSE stream using an HTTP Request file in IDE
Building a simple Frontend Application to test SSE
Key differences between SSE and SignalR (WebSockets)

Let's dive in!

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

What Are Server-Sent Events

Server-Sent Events (SSE) is a web standard that enables a server to push real-time data to web clients over a single HTTP connection.
Unlike traditional request-response patterns where clients must repeatedly poll the server for updates, SSE allows the server to initiate communication and send data whenever new information becomes available.

Key Characteristics of SSE:

Unidirectional Communication: Data flows only from server to client
Built on HTTP/1.1: SSE works over plain HTTP, using the text/event-stream MIME type. No special WebSocket handshake is needed.
Built-in Reconnection: Browsers automatically reconnect if the connection is lost
Lightweight: Minimal overhead compared to other real-time solutions

Where is SSE supported?

Because SSE works over plain HTTP, all major browsers support it.
You can also use HTTP request files in the IDE and tools like curl, Postman, Apidog to test SSE.

Common Use Cases:

Live Data Feeds: Stock prices, sports scores, news updates
Real-time Notifications: Social Media Notifications, system alerts, status updates
Progress Tracking: File uploads, long-running operations
Live Dashboards: Monitoring systems, analytics displays

SSE is perfect when you need to push updates from the server to the client, but don't require bidirectional communication.
It's simpler to implement than WebSockets and works seamlessly with existing HTTP infrastructure.

Implementing SSE in ASP.NET Core 10

Starting in .NET 10 preview 4, ASP.NET Core adds support for Server-Sent Events.
Under the hood, it sets the Content-Type to text/event-stream, handles flushing, and integrates with cancellation.

You need to download a .NET 10 SDK preview to start using SSE

Let's create a StockService that generates an Async stream of stock price updates:

public record StockPriceEvent(string Id, string Symbol, decimal Price, DateTime Timestamp);

public class StockService
{
    public async IAsyncEnumerable<StockPriceEvent> GenerateStockPrices(
       [EnumeratorCancellation] CancellationToken cancellationToken)
    {
       var symbols = new[] { "MSFT", "AAPL", "GOOG", "AMZN" };

       while (!cancellationToken.IsCancellationRequested)
       {
          // Pick a random symbol and price
          var symbol = symbols[Random.Shared.Next(symbols.Length)];
          var price  = Math.Round((decimal)(100 + Random.Shared.NextDouble() * 50), 2);

          var id = DateTime.UtcNow.ToString("o");

          yield return new StockPriceEvent(id, symbol, price, DateTime.UtcNow);

          // Wait 2 seconds before sending the next update
          await Task.Delay(TimeSpan.FromSeconds(2), cancellationToken);
       }
    }
}

This method yields an endless IAsyncEnumerable stream of StockPriceEvent items at a fixed interval.

We can use TypedResults.ServerSentEvents result to send Server-Sent Events.

Let's create a Minimal API endpoint that sends Stock Price updates SSE:

builder.Services.AddSingleton<StockService>();

app.MapGet("/stocks", (StockService stockService, CancellationToken ct) =>
{
    return TypedResults.ServerSentEvents(
       stockService.GenerateStockPrices(ct),
       eventType: "stockUpdate"
    );
});

Reconnection Logic and the Last-Event-ID Header

One of SSE's most powerful features is automatic reconnection.
When a connection drops, browsers automatically attempt to reconnect and can resume from where they left off using the Last-Event-ID header.

If the connection is lost, the browser will reopen the stream and include the Last-Event-ID:

Last-Event-ID: 20250616T150430Z

On the backend, we can inspect HttpRequest.Headers["Last-Event-ID"] to determine where to resume.
You can skip older items, replay missed entries, or log the reconnect event.

Here is how to implement such logic:

app.MapGet("/stocks2", (
    StockService stockService,
    HttpRequest httpRequest,
    CancellationToken ct) =>
{
    // 1. Read Last-Event-ID (if any)
    var lastEventId = httpRequest.Headers.TryGetValue("Last-Event-ID", out var id)
       ? id.ToString()
       : null;

    // 2. Optionally log or handle resume logic
    if (!string.IsNullOrEmpty(lastEventId))
    {
       app.Logger.LogInformation("Reconnected, client last saw ID {LastId}", lastEventId);
    }

    // 3. Stream SSE with lastEventId and retry
    var stream = stockService.GenerateStockPricesSince(lastEventId, ct)
       .Select(evt =>
       {
          var sseItem = new SseItem<StockPriceEvent>(evt, "stockUpdate")
          {
             EventId = evt.Id
          };

          return sseItem;
       });

    return TypedResults.ServerSentEvents(
       stream,
       eventType: "stockUpdate"
    );
});

Here, we are creating SseItem and specifying the event identifier; this identifier will be sent from the client in the Last-Event-ID header when the reconnect happens.

Testing SSE Endpoint with an HTTP File

Almost every IDE (Visual Studio, Visual Studio Code, JetBrains Rider) supports HTTP request files, which you can use to test your API endpoints.
And they support Server-Sent Events.

@ServerSentEvents_HostAddress = http://localhost:5000

### Test SSE stream from .NET 10 Minimal API
GET {{ServerSentEvents_HostAddress}}/stocks
Accept: text/event-stream

Let's run the application and send the request.
You will get a new event as JSON every 2 seconds:

Response code: 200 (OK); Time: 410ms (410 ms)

event: stockUpdate
data: {"id":"2025-06-16T05:31:10.5426180Z","symbol":"AMZN","price":122.67,"timestamp":"2025-06-16T05:31:10.5445659Z"}

event: stockUpdate
data: {"id":"2025-06-16T05:31:12.5838704Z","symbol":"AAPL","price":118.88,"timestamp":"2025-06-16T05:31:12.5838771Z"}

event: stockUpdate
data: {"id":"2025-06-16T05:31:14.5937683Z","symbol":"AAPL","price":104.01,"timestamp":"2025-06-16T05:31:14.593772Z"}

Our SSE endpoint is working as expected.

Now, let's build a simple frontend application to consume the SSE.

How to Subscribe to Server-Sent Events from the Frontend

You can consume Server-Sent Events on the frontend using the native EventSource API.

Let's create a simple HTML page that shows stock price updates with some Tailwind CSS styling:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <title>Live Stock Ticker</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <link href="styles.css" rel="stylesheet">
</head>
<body class="bg-gray-50 min-h-screen p-8">
<div class="max-w-4xl mx-auto">
    <h1 class="text-3xl font-bold text-gray-800 mb-6 flex items-center">
        📈<span class="ml-2">Live Stock Market Updates</span>
    </h1>
    <div class="bg-white rounded-lg shadow-md p-6">
       <ul id="updates" class="divide-y divide-gray-200"></ul>
    </div>
</div>

<script src="scripts.js"></script>
</body>
</html>

We can use EventSource to subscribe to the "stockUpdate" event in JavaScript:

// 1. Connect to the SSE endpoint
const source = new EventSource('http://localhost:5000/stocks');

// 2. Listen for our named "stockUpdate" events
source.addEventListener('stockUpdate', e => {
    // Parse the JSON payload
    const { symbol, price, timestamp } = JSON.parse(e.data);

    // Create and prepend a new list item with Tailwind classes
    const li = document.createElement('li');
    li.classList.add('new', 'flex', 'justify-between', 'items-center');

    // Create time element
    const timeSpan = document.createElement('span');
    timeSpan.classList.add('text-gray-500', 'text-sm');
    timeSpan.textContent = new Date(timestamp).toLocaleTimeString();

    // Create symbol element
    const symbolSpan = document.createElement('span');
    symbolSpan.classList.add('font-medium', 'text-gray-800');
    symbolSpan.textContent = symbol;

    // Create price element
    const priceSpan = document.createElement('span');
    priceSpan.classList.add('font-bold', 'text-green-600');
    priceSpan.textContent = `$${price}`;

    // Append all elements to the list item
    li.appendChild(timeSpan);
    li.appendChild(symbolSpan);
    li.appendChild(priceSpan);

    const list = document.getElementById('updates');
    list.prepend(li);

    // Remove highlight after a moment
    setTimeout(() => li.classList.remove('new'), 2000);
});

// 3. Handle errors & automatic reconnection
source.onerror = err => {
    console.error('SSE connection error:', err);
};

// 4. (Optional) Inspect the last-received event ID
source.onmessage = e => {
    console.log('Last Event ID now:', source.lastEventId);
};

How it works:

new EventSource(url) opens a persistent HTTP connection to the /stocks endpoint with Accept header: text/event-stream.
addEventListener('stockUpdate', …) listens for the stockUpdate event.
source.lastEventId — represents the last event's id: value, which you can use for debugging or custom logic.
Automatic reconnection — if the connection drops, the browser waits for the server's retry interval before reopening, sending Last-Event-ID automatically.

To be able to test this locally, we need to allow CORS policies in Program.cs in development mode:

if (builder.Environment.IsDevelopment())
{
    builder.Services.AddCors(options =>
    {
       options.AddPolicy("AllowFrontend", policy =>
       {
          policy.WithOrigins("*")
             .AllowAnyHeader()
             .AllowAnyMethod();
       });
    });
}

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseCors("AllowFrontend");
}

This is what our page looks like where we receive stock updates every 2 seconds:

And this is what it looks like in the web browser DevTools in the Network tab:

SSE works over plain HTTP/1, and web browsers natively support it; it's very easy to debug and test these events.
If you have ever tried to view or debug WebSocket events, it's not that simple and requires 3rd party software tools.

SSE vs. SignalR (WebSockets)

While both Server-Sent Events (SSE) and SignalR enable real-time messaging in ASP.NET Core, they target different scenarios and trade-off complexity, features, and resource usage.

Here is the difference between them:

Protocol:

SSE: HTTP/1.1 streaming (text/event-stream)
SignalR: WebSocket (with HTTP fallback transports)

Communication direction:

SSE: Unidirectional (server → client only)
SignalR: Full-duplex (bi-directional)

Browser support:

SSE: Native in most modern browsers
SignalR: Native WebSocket + fallback via Long Polling

Connection overhead:

SSE: Single HTTP request, minimal framing
SignalR: WebSocket handshake + frame management

Automatic reconnect:

SSE: Built-in configurable retries
SignalR: Built-in configurable retries

Message types:

SSE: text only
SignalR: binary or text

Server API:

SSE: Minimal: TypedResults.ServerSentEvents
SignalR: Rich: Hubs, strongly-typed methods, groups

Scalability:

SSE: Scales like any HTTP endpoint
SignalR: Scales with backplane (Redis/Azure SignalR)

Use cases:

SSE: One-way updates: notifications, alerts, stock tickers, logs
SignalR: Interactive: chat apps, collaborative tools, live dashboards with user input

Summary

Server-Sent Events is an easy-to-integrate alternative to SignalR when you only need to push updates from the server to the client.

When to Choose SSE:

You only need server → client updates.
If your clients never need to send messages back over the same channel, SSE is simpler.
Lightweight streaming.
For dashboards, live metrics, logs, or stock-ticker feeds, SSE's minimal framing and HTTP base make it easy to manage and debug.
Non-complex implementation.
Native browser support and built-in ASP.NET Core classes utilities you to build SSE driven applications with ease.

When to Choose SignalR:

Bi-directional communication.
Chat rooms, collaborative whiteboards, or any scenario where clients push messages to the server and vice versa require WebSockets.
Advanced features.
SignalR Hubs lets you call methods on groups of connections, manage user identities, and broadcast to subsets of clients with minimal code.
Scale-out support.
If you expect to run your app on multiple servers or in a cloud environment, SignalR's Redis or Azure backplane integrations handle connection routing and message distribution automatically.

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Logging Requests and Responses for API Requests and HttpClient in ASP.NET Core

Anton Martyniuk — Tue, 15 Jul 2025 20:06:46 +0000

Logging HTTP requests and responses helps developers quickly troubleshoot issues, monitor performance and health, and audit user interactions within their applications.
ASP.NET Core provides built-in support with HttpLogging, which you can easily configure and extend according to your specific needs.

In today's newsletter, we'll cover in-depth:

How to enable and configure HTTP logging in your ASP.NET Core projects
Logging options and settings
Customizing logs and using endpoint-specific configurations
How to redact sensitive data in logs
How to log requests and responses when sending requests with HttpClient

Let's dive in.

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Getting Started with HttpLogging in ASP.NET Core

ASP.NET Core provides a built-in HttpLogging middleware that logs all incoming Web API requests and responses.

To enable HTTP logging, you only need two simple steps:

Step 1: Add HttpLogging middleware in Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Enable HTTP logging services
builder.Services.AddHttpLogging(options =>
{
    options.LoggingFields = HttpLoggingFields.Request | HttpLoggingFields.Response;
});

var app = builder.Build();

// Add middleware to the HTTP request pipeline
app.UseHttpLogging();

app.Run();

Step 2: Adjust Logging Levels in appsettings.json

To ensure HTTP logging output appears in your logs, you should adjust the logging level.
Typically, setting this to "Information" is enough:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.AspNetCore.Hosting.Diagnostics": "Warning",
      "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
    }
  }
}

Once configured, HTTP requests and responses will automatically log to your configured log outputs (console, file, etc.).
You should see log entries similar to this example when making a request:

info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[1]
      Request:
      Protocol: HTTP/1.1
      Method: GET
      Scheme: https
      PathBase: 
      Path: /
      Headers:
        Host: localhost:5001
        User-Agent: Mozilla/5.0...
      Response:
      StatusCode: 200
      Headers:
        Content-Type: text/plain; charset=utf-8

It works with a built-in ASP.NET Core logging provider - Microsoft.Extensions.Logging.
It also works with a custom logging provider, such as Serilog.

Serilog has a large ecosystem of sinks, and its flexible configuration makes it an excellent choice for logging.
A sink is a source where you can output and store your logs; it can be a console, file, database, or monitoring system.

This is how you can configure Serilog to support HttpLogging:

{
  "Serilog": {
    "Using": [
      "Serilog.Sinks.Console",
      "Serilog.Sinks.File"
    ],
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft.AspNetCore": "Warning",
        "Microsoft.AspNetCore.Hosting.Diagnostics": "Warning",
        "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      { "Name": "File", "Args": { "path": "service.log", "rollingInterval": "Day" } }
    ],
    "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
    "Properties": {
      "Application": "ApplicationName"
    }
  }
}

Configuring HttpLogging

HttpLogging middleware can be configured using the HttpLoggingOptions class.

The main option is the HttpLoggingFields enum, which controls what should be logged.
You can combine multiple flags to get the desired output in logs.

You can view all the available options in the Microsoft documentation.

Here is an example of how you can configure logging for HTTP requests:

builder.Services.AddHttpLogging(options =>
{
    options.LoggingFields = 
        HttpLoggingFields.RequestMethod |
        HttpLoggingFields.RequestPath |
        HttpLoggingFields.RequestQuery |
        HttpLoggingFields.RequestHeaders |
        HttpLoggingFields.ResponseStatusCode |
        HttpLoggingFields.Duration;
});

You can also limit the headers that are logged:

builder.Services.AddHttpLogging(options =>
{
    options.RequestHeaders.Add("X-API-Version");
    options.RequestHeaders.Add("User-Agent");
    options.ResponseHeaders.Add("Content-Type");
});

Logging request and response body is especially powerful for debugging APIs.
However, it's critical to consider the performance and security aspects:

Performance:
Logging request and response body can slow down your application, as it needs to read the entire object from the HTTP body.
Use this option sparingly in production.
Security and Privacy:
Bodies might contain sensitive user data (passwords, credit card information, personally identifiable information, etc.). Always implement redaction strategies or enable body logging only in safe environments (development and staging).

If your logs are growing too large, you can configure the maximum size of the request/response body that's allowed to be logged:

builder.Services.AddHttpLogging(options =>
{
    options.RequestBodyLogLimit = 4096; // limit in bytes
    options.ResponseBodyLogLimit = 4096;
});

The default value is 32 KB.

Here is how you can customize logging for development and production environments:

builder.Services.AddHttpLogging(options =>
{
    options.LoggingFields =
        HttpLoggingFields.RequestMethod |
        HttpLoggingFields.RequestPath |
        HttpLoggingFields.RequestQuery |
        HttpLoggingFields.RequestHeaders |
        HttpLoggingFields.ResponseStatusCode |
        HttpLoggingFields.ResponseHeaders |
        HttpLoggingFields.Duration;

    // Explicitly log only these headers
    options.RequestHeaders.Add("User-Agent");
    options.ResponseHeaders.Add("Content-Type");

    options.RequestBodyLogLimit = 2048; // 2 KB
    options.ResponseBodyLogLimit = 2048; // 2 KB

    // Limit request/response body logging for safe environments
    if (builder.Environment.IsDevelopment())
    {
        options.LoggingFields |= HttpLoggingFields.RequestBody | HttpLoggingFields.ResponseBody;
        options.RequestBodyLogLimit = 1024 * 32; // 32 KB
        options.ResponseBodyLogLimit = 1024 * 32; // 32 KB
    }
});

Customizing Logs Using IHttpLoggingInterceptor

You might want to customize log entries for specific endpoints:

Exclude particular headers dynamically
Do not log request and response bodies for specific endpoints
Modify logged data to enhance readability or security.

For these cases, you can create your own IHttpLoggingInterceptor implementation.
That allows you to intercept and customize logs before they are written to the logs.

Implementing this interface enables you to:

Dynamically exclude or include specific headers or fields.
Redact sensitive data from requests or responses.
Add custom information to logs for additional context.

Let's explore an example:

public class CustomLoggingInterceptor : IHttpLoggingInterceptor
{
    public ValueTask OnRequestAsync(HttpLoggingInterceptorContext context)
    {
        // Example: Remove specific headers from being logged
        context.HttpContext.Request.Headers.Remove("X-API-Key");

        // Example: Add custom information to log
        context.AddParameter("RequestId", Guid.NewGuid().ToString());

        return ValueTask.CompletedTask;
    }

    public ValueTask OnResponseAsync(HttpLoggingInterceptorContext context)
    {
        // Example: Remove sensitive response header
        logContext.HttpContext.Response.Headers.Remove("Set-Cookie");

        // Example: Log additional context
        context.AddParameter("new-response-field", Guid.NewGuid().ToString());

        return ValueTask.CompletedTask;
    }
}

In this example:

OnRequestAsync is called right before request data is logged, allowing you to customize request logs.
OnResponseAsync lets you adjust response logs.

Once you have your interceptor class, register it in the Program.cs:

builder.Services.AddHttpLogging(loggingOptions =>
{
    // ...
});

builder.Services.AddSingleton<IHttpLoggingInterceptor, CustomLoggingInterceptor>();

var app = builder.Build();

app.UseHttpLogging();

Endpoint-specific Logging Configuration

Often, not all endpoints require the same logging detail.
ASP.NET Core lets you configure HTTP logging on a per-endpoint basis.

Here's an example using minimal APIs:

app.MapGet("/health", () => Results.Ok())
   .DisableHttpLogging(); // This endpoint logs nothing.

app.MapPost("/api/orders", (OrderRequest request) => 
{
    // Handle order processing
    return Results.Created();
})
.WithHttpLogging(logging =>
{
    logging.LoggingFields = HttpLoggingFields.RequestBody | HttpLoggingFields.ResponseStatusCode;
});

How to Redact Sensitive Data in Logs

Keep in mind that logs can capture sensitive information such as passwords, API keys, tokens, and personally identifiable information (PII).
Exposing such data in logs can lead to serious security risks and compliance issues.

It's crucial to understand why redaction matters:

Security Risks:
Logs containing tokens, passwords, or API keys can expose your application to unauthorized access and breaches.
Compliance Requirements:
Regulations such as GDPR, HIPAA, or PCI DSS explicitly require the careful handling and logging of sensitive information.
Trust and Privacy:
Maintaining user privacy and trust demands proactively protecting personal and sensitive information.

ASP.NET Core provides built-in capabilities and best practices to redact sensitive data from HTTP logs securely:

Selective header logging:
Explicitly specify which headers to log, thus excluding sensitive headers.
Using IHttpLoggingInterceptor:
Dynamically remove or alter sensitive data from logs using a custom interceptor implementation.

Here is how you can allow logging only specific headers:

builder.Services.AddHttpLogging(options =>
{
    options.LoggingFields = 
        HttpLoggingFields.RequestMethod |
        HttpLoggingFields.RequestPath |
        HttpLoggingFields.ResponseStatusCode;

    // Only explicitly log non-sensitive headers
    options.RequestHeaders.Add("User-Agent");
    options.ResponseHeaders.Add("Content-Type");
});

Here is how you can redact sensitive data from logs using an interceptor:

public class SensitiveDataRedactionInterceptor : IHttpLoggingInterceptor
{
    public ValueTask OnRequestAsync(HttpLoggingInterceptorContext context)
    {
        if (context.HttpContext.Request.Method == "POST")
        {
            // Don't log anything if the request is a POST.
            context.LoggingFields = HttpLoggingFields.None;
        }

        // Don't enrich if we're not going to log any part of the request.
        if (!context.IsAnyEnabled(HttpLoggingFields.Request))
        {
            return default;
        }

        if (context.TryDisable(HttpLoggingFields.RequestPath))
        {
            RedactPath(context);
        }

        if (context.TryDisable(HttpLoggingFields.RequestHeaders))
        {
            RedactRequestHeaders(context);
        }

        EnrichRequest(context);

        return default;
    }

    public ValueTask OnResponseAsync(HttpLoggingInterceptorContext logContext)
    {
        // Don't enrich if we're not going to log any part of the response
        if (!logContext.IsAnyEnabled(HttpLoggingFields.Response))
        {
            return default;
        }

        if (logContext.TryDisable(HttpLoggingFields.ResponseHeaders))
        {
            RedactResponseHeaders(logContext);
        }

        EnrichResponse(logContext);

        return default;
    }

    private static void RedactPath(HttpLoggingInterceptorContext logContext)
    {
        logContext.AddParameter(nameof(logContext.HttpContext.Request.Path), "[REDACTED]");
    }

    private static void RedactRequestHeaders(HttpLoggingInterceptorContext logContext)
    {
        foreach (var header in logContext.HttpContext.Request.Headers)
        {
            logContext.AddParameter(header.Key, "[REDACTED]");
        }
    }

    private static void EnrichRequest(HttpLoggingInterceptorContext logContext)
    {
        logContext.AddParameter("new-request-field", Guid.NewGuid().ToString());
    }

    private static void RedactResponseHeaders(HttpLoggingInterceptorContext logContext)
    {
        foreach (var header in logContext.HttpContext.Response.Headers)
        {
            logContext.AddParameter(header.Key, "[REDACTED]");
        }
    }

    private static void EnrichResponse(HttpLoggingInterceptorContext logContext)
    {
        logContext.AddParameter("new-response-field", Guid.NewGuid().ToString());
    }
}

Let's test a few HTTP requests and how they are logged:

GET https://localhost:5000/api/books/7dcec396-4150-4354-a51c-f2f13be3ef4c

info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[1]
      Request:
      Path: [REDACTED]
      Accept: [REDACTED]
      Host: [REDACTED]
      User-Agent: [REDACTED]
      Accept-Encoding: [REDACTED]
      Authorization: [REDACTED]
      new-request-field: 8860d646-24a3-49d3-9405-e1eccc5b7c71
      Method: GET
      QueryString:
info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[2]
      Response:
      Content-Type: [REDACTED]
      new-response-field: a68d1cc0-269f-43e6-90e6-6f9a8ca178a2
      StatusCode: 200
info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[4]
      ResponseBody: {"id":"7dcec396-4150-4354-a51c-f2f13be3ef4c","title":"Fish","year":2024,"authorId":"91a2d8f6-a5cf-4689-8abf-4284bc8cd5a3"}
info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[8]
      Duration: 142.8386ms

In this example, the whole response body is logged.

And here is what the 404 Not Found response may look like:

GET https://localhost:5000/api/books/d81b2b46-b725-4594-9465-133c443641cb

info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[1]
      Request:
      Path: [REDACTED]
      Accept: [REDACTED]
      Host: [REDACTED]
      User-Agent: [REDACTED]
      Accept-Encoding: [REDACTED]
      Authorization: [REDACTED]
      new-request-field: d856b313-668f-42a7-b8d7-3b40363375bf
      Method: GET
      QueryString:
info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[2]
      Response:
      new-response-field: 3d1717f3-b23d-4689-ad09-de1b81d02cda
      StatusCode: 404
info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[8]
      Duration: 134.0404ms

Logging Request and Responses When Sending Requests with HttpClient

We have covered how to log HTTP requests and responses in ASP.NET Core.

However, it's essential to understand how to log requests and responses when using HttpClient to send requests to external services.
For observability and debugging purposes, it's essential to log interactions with external APIs or services.

You can use the DelegatingHandler to inspect all HTTP traffic from your HttpClient.
DelegatingHandler is a middleware to the HttpClient pipeline that allows you to intercept and modify requests and responses.

Let's explore an example of such a Handler:

public class HttpLoggingHandler : DelegatingHandler
{
    private readonly ILogger _logger;

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

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        var traceId = request.Headers.TryGetValues("trace-id", out var values) ? values.FirstOrDefault() : null;
        traceId ??= Guid.NewGuid().ToString();

        var requestBuilder = new StringBuilder();

        var url = $"{request.RequestUri?.Host}:{request.RequestUri?.Port}{request.RequestUri?.AbsolutePath}";
        var headers = request.Headers.ExceptSensitiveHeaders().Select(x => $"[{x.Key}, {string.Join(",", x.Value)}]");

        requestBuilder.AppendLine($"[REQUEST] {traceId}");
        requestBuilder.AppendLine($"{request.Method}: {request.RequestUri?.Scheme}://{url}");
        requestBuilder.AppendLine($"Headers: {string.Join(", ", headers)}");

        if (request.Content != null)
        {
            if (request.Content.Headers.Any())
            {
                var contentHeaders = request.Content.Headers
                    .ExceptSensitiveHeaders().Select(x => $"[{x.Key}, {string.Join(",", x.Value)}]");

                requestBuilder.AppendLine($"Content headers: {string.Join(", ", contentHeaders)}");
            }

            if (RequestCanBeLogged(request.RequestUri?.AbsolutePath))
            {
                requestBuilder.AppendLine("Content:");
                requestBuilder.AppendLine(await request.Content.ReadAsStringAsync(cancellationToken));
            }
        }

        _logger.LogDebug("{Request}", requestBuilder.ToString());

        var stopwatch = new Stopwatch();
        stopwatch.Start();

        var response = await base.SendAsync(request, cancellationToken);
        stopwatch.Stop();

        var responseBuilder = new StringBuilder();
        responseBuilder.AppendLine($"[RESPONSE] {traceId}");
        responseBuilder.AppendLine($"{request.Method}: {request.RequestUri?.Scheme}://{url} {(int)response.StatusCode} {response.ReasonPhrase} executed in {stopwatch.Elapsed.TotalMilliseconds} ms");
        responseBuilder.AppendLine($"Headers: {string.Join(", ", response.Headers.Select(x => $"[{x.Key}, {string.Join(",", x.Value)}]"))}");

        if (response.Content.Headers.Any())
        {
            var contentHeaders = response.Content
                .Headers.Select(x => $"[{x.Key}, {string.Join(",", x.Value)}]");

            requestBuilder.AppendLine($"Content headers: {string.Join(", ", contentHeaders)}");
        }

        if (ResponseCanBeLogged(request.RequestUri?.AbsolutePath) && ResponseCanBeLogged(request.RequestUri?.AbsolutePath))
        {
            responseBuilder.AppendLine("Content:");
            responseBuilder.AppendLine(await response.Content.ReadAsStringAsync(cancellationToken));
        }

        _logger.LogDebug("{Response}", responseBuilder.ToString());
        _logger.LogDebug("Request completed in {ElapsedTotalMilliseconds}ms", stopwatch.Elapsed.TotalMilliseconds);
        return response;
    }
}

Here, I use the following methods to redact the data:

ExceptSensitiveHeaders: Redact sensitive headers from the logs.
RequestCanBeLogged: Check if the request can be logged.
ResponseCanBeLogged: Check if the response can be logged.

For ExceptSensitiveHeaders, I have created an extension method on HttpRequestHeaders and HttpContentHeaders:

internal static class HttpLoggingHelpers
{
    public static IEnumerable<KeyValuePair<string, IEnumerable<string>>> ExceptSensitiveHeaders(
        this HttpRequestHeaders headers)
    {
        return headers.Where(x => !x.Key.Contains("Authorization",
            StringComparison.OrdinalIgnoreCase));
    }

    public static IEnumerable<KeyValuePair<string, IEnumerable<string>>> ExceptSensitiveHeaders(
        this HttpContentHeaders headers)
    {
        return headers.Where(x => !x.Key.Contains("secret-token",
            StringComparison.OrdinalIgnoreCase));
    }
}

Here is the naive implementation of checking for allowed URLs:

private static readonly List<string> NotAllowedRequestUrls = new()
{
    "/api/users/login",
    "/api/users/refresh"
};

private static readonly List<string> NotAllowedResponseUrls = new()
{
    "/api/users/login",
    "/api/users/refresh"
};

private static bool RequestCanBeLogged(string? url)
{
    if (string.IsNullOrEmpty(url))
    {
        return false;
    }

    return !NotAllowedRequestUrls.Any(x => x.Contains(url, StringComparison.OrdinalIgnoreCase));
}

private static bool ResponseCanBeLogged(string? url)
{
    if (string.IsNullOrEmpty(url))
    {
        return false;
    }

    return !NotAllowedResponseUrls.Any(x => x.Contains(url, StringComparison.OrdinalIgnoreCase));
}

For production, you should configure these options, but for example, it's more than sufficient.

To use this handler, you must register it when configuring HttpClient in Program.cs:

builder.Services.AddHttpClient<ITodoClient, TodoClient>(client =>
{
    client.BaseAddress = new Uri("https://jsonplaceholder.typicode.com/");
})
.AddHttpMessageHandler(configure =>
{
    var logger = configure.GetRequiredService<ILoggerFactory>()
        .CreateLogger("json-placeholder-todos");

    return new HttpLoggingHandler(logger);
});

This approach also fits well with Refit and Polly:

builder.Services.AddTransient<LoggingHandler>();

services
    .AddRefitClient<ITodoApi>()
    .ConfigureHttpClient((provider, c) =>
    {
        client.BaseAddress = new Uri("https://jsonplaceholder.typicode.com/");
    })
    .AddHttpMessageHandler(configure =>
    {
        var logger = configure.GetRequiredService<ILoggerFactory>()
            .CreateLogger("json-placeholder-todos");

        return new HttpLoggingHandler(logger);
    });

jsonplaceholder is a public API that allows you to test HTTP requests.
Let's send a request to https://jsonplaceholder.typicode.com/todos/50 and see what the logs look like:

dbug: json-placeholder-todos[0]
      [REQUEST] 4d251738-5aeb-4342-824e-5d23ddf738a2
      GET: https://jsonplaceholder.typicode.com:443/todos/50
      Headers:

dbug: json-placeholder-todos[0]
      [RESPONSE] 4d251738-5aeb-4342-824e-5d23ddf738a2
      GET: https://jsonplaceholder.typicode.com:443/todos/50 200 OK executed in 561,7971 ms
      Headers: [Date, Tue, 10 Jun 2025 05:18:23 GMT], [Cache-Control, max-age=43200]
      Content headers: [Content-Type, application/json; charset=utf-8], [Content-Length, 121]
      Content:
      {
        "userId": 3,
        "id": 50,
        "title": "cupiditate necessitatibus ullam aut quis dolor voluptate",
        "completed": true
      }

dbug: json-placeholder-todos[0]
      Request completed in 406,5857ms

Summary

Logging is essential for maintaining robust, secure, and maintainable ASP.NET Core applications.
Proper logging of HTTP requests and responses enables developers and teams to quickly diagnose issues, monitor application performance, and meet critical compliance requirements.

Throughout this guide, we've explored various built-in and advanced techniques provided by ASP.NET Core to achieve precise control over HTTP logging.

Follow these recommendations to keep sensitive data secure in logs:

Default to Exclusion:
Log only what's explicitly safe. Avoid logging sensitive information by default.
Environment-specific Logging:
Enable detailed logs with sensitive data only for testing purposes during development, and never in production.
Regex for Data Masking:
Carefully use regular expressions or structured data parsers (like JSON parsers) to mask sensitive fields precisely.
Testing:
Verify your redaction rules through automated tests, ensuring no sensitive data accidentally leaks into logs.

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Getting Started With HotChocolate GraphQL For Building a Social Media Platform

Anton Martyniuk — Tue, 08 Jul 2025 10:48:31 +0000

Modern client applications demand flexible data fetching.
Usually, when using REST APIs, clients call multiple REST endpoints and over-fetch data.

One way to solve it is by using a Backend-For-Frontend (BFF) pattern.
However, it is hard and tedious to build, and its flexibility is limited.

GraphQL was created to address these issues.
Hot Chocolate is the most efficient, feature-rich, open-source GraphQL server in the .NET ecosystem that helps developers build powerful GraphQL APIs and Gateways with ease.

It brings the following benefits compared to traditional REST APIs:

1. Selective data fetching:
Each client chooses exactly the fields it needs, no over- or under-fetching.
A web UI can pull rich profile details, while a mobile app requests only minimal essential fields.

2. Single request for multiple resources:
Bundle multiple requests into a single round-trip to the server.
Eliminate client choreography across three or more REST endpoints.

3. Strongly-typed schema & introspection:
Auto-generated docs, code generation, and IDE autocomplete help frontend and backend stay in sync.

4. Built-in filtering, sorting, and paging:
HotChocolate's middleware takes care of common patterns. No need for manual dynamic querying, sorting and filtering.
And it solves it better and easier than OData.

5. Enhanced developer experience:
The Nitro GraphQL UI in HotChocolate lets you explore types, build queries visually, and test in seconds.

I have been using HotChocolate GraphQL for more than 3 years in production.
And it significantly improved how I craft my APIs.

Today I will help you to get started with HotChocolate GraphQL.
We will explore how a simple Social Media application with REST APIs turns into a flexible GraphQL Server.

In this post, we will explore:

Social Media Application and the problem with REST APIs
What is GraphQL
How to add HotChocolate to the project
How to write GraphQL Queries
Nitro UI: schema browsing and query building
How HotChocolate integrates with EF Core for projections, filtering, sorting, and paging
How to organize code with best practices when using GraphQL

Let's dive in!

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

Application Overview: Simple Social Media Platform

Our example application manages users, posts, comments, likes, feeds, notifications, and categories.

Let's briefly explore the relations of entities of our Social Media Platform:

public class User
{
    public int Id { get; set; }
    public string Username { get; set; } = null!;
    public List<Post> Posts { get; set; } = [];
    public List<Comment> Comments { get; set; } = [];
    public List<Feed> Feeds { get; set; } = [];
    public List<Notification>? Notifications { get; set; } = [];
}

public class Post
{
    public Category Category { get; set; } = null!;
    public List<Like> Likes { get; set; } = [];
    public List<Comment> Comments { get; set; } = [];
}

public class Like
{
    public Post Post { get; set; } = null!;
    public User User { get; set; } = null!;
}

public class Comment
{
    public User User { get; set; } = null!;
    public Post Post { get; set; } = null!;
}

public class Category
{
    public List<Post> Posts { get; set; } = [];
}

public enum NotificationType
{
    Post,
    Like,
    Comment
}

public class Notification
{
    public User User { get; set; } = null!;
    public NotificationType Type { get; set; }
    public int ItemId { get; set; }
}

public class Feed
{
    public int UserId { get; set; }
    public User User { get; set; } = null!;
    public int PostId { get; set; }
}

You can download a complete source code of an application at the end of the post

Let's explore a real use case: a user opens a social media website, and they see:

Recent feed with new posts
User's own posts
Notifications with recent posts, comments and likes to the posts the user is interested in

Consider we have the following endpoints:

public class GetUserFeedEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapGet("/api/feed",
            async (int userId, int count, SocialMediaDbContext dbContext) => { }
        );
    }
}

public class GetUserNotificationsEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapGet("/api/notifications",
            async (int userId, int count, SocialMediaDbContext dbContext) => { }
        );
    }
}

public class GetUserPostsEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapGet("/api/users/{userId}/posts",
            async (int userId, int count, SocialMediaDbContext dbContext) => { }
        );
    }
}

A typical frontend application needs to send 3 separate requests to query the necessary data:

```http request

Get user feed

GET /api/feed?userId=1&count=10

Get user notifications

GET /api/notifications?userId=1&count=10

Get user posts

GET /api/users/1/posts?count=10




This implementation has two major drawbacks:
- Each client application must send 3 separate API requests to the server
- Each client application consumes all the fields the server returns. For a website it may be okay, but too much data will slow down a mobile application.

Let's explore what GraphQL offers to solve these drawbacks.


## Understanding GraphQL: Queries, Mutations & Subscriptions

Before we jump into adding HotChocolate to the project, let's take a closer look at the core GraphQL concepts and why they map so naturally to modern client needs.

At its heart, GraphQL is both:
- A type system: you define your object types and their fields in a schema
- A query language: clients ask for exactly the data they need

Rather than dozens of REST endpoints, you publish a single schema and let each client shape its requests.

### Queries

Queries are the read-only operations in GraphQL. You ask for a type and a selection of its fields:



```gql
query GetUserProfile {
  user(userId: 1) {
    id
    username
    posts {
      id
      content
    }
  }
}

The client controls exactly which fields are returned. No over-fetching or under-fetching.

Mutations

Mutations modify the server state (create, update or delete).
They look similar to queries:

mutation CreatePost {
  createPost(input: { userId: 1, content: "Hello World" }) {
    id
    content
    createdAt
  }
}

Mutations return the updated object(s) so the client can update its state.
You can send multiple mutations in a single request.

Subscriptions

Subscriptions enable real-time, server-to-client push. Under the hood, they use WebSockets:

subscription OnNewComment {
  commentAdded(postId: 42) {
    id
    text
    username
    createdAt
  }
}

Clients "subscribe" to events (e.g. new comments) and the server pushes updates automatically.
Much like in SignalR.

Now that we understand how GraphQL works conceptually, let's wire up HotChocolate in our ASP.NET Core application.

Getting Started with HotChocolate

To get started with HotChocolate, add the following Nuget packages to your solution:

<ItemGroup>
  <PackageReference Include="HotChocolate.AspNetCore" Version="15.1.5" />
  <PackageReference Include="HotChocolate.Data" Version="15.1.5" />
  <PackageReference Include="HotChocolate.Types.Analyzers" Version="15.1.5">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive;</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

Then configure GraphQLServer in DI:

var builder = WebApplication.CreateBuilder(args);

// Register GraphQL services
builder.Services
    .AddGraphQLServer()
    .AddQueryType()
    .DisableIntrospection(builder.Environment.IsProduction());

var app = builder.Build();

// exposes /graphql endpoint
app.MapGraphQL();

app.Run();

Introspection is a GraphQL feature that allows clients to discover the schema and its types.
Make sure you disable introspection in production for security reasons.

AddQueryType registers the QueryType, which is the root of the GraphQL schema.

Let's add a root query to our schema:

public record UserRootType(int UserId);

[QueryType]
public class UserQueries
{
    public UserRootType GetUser(int userId) => new(userId);
}

This is what the query looks like in GQL (Graph Query Language):

query GetUser {
  user(userId: 1) {

  }
}

The [QueryType] attribute tells HotChocolate that his class defines the root Query.

GetUser(int userId) becomes the user(userId: Int!) field in the schema.

Now let's add user's posts, feed and notifications to our schema.

Rather than adding all methods into one large class, we can split them into separate classes:

[ExtendObjectType(typeof(UserRootType))]
public class PostQueries
{
    public async Task<List<PostResponse>> GetUserPosts(
        SocialMediaDbContext dbContext,
        [Parent] UserRootType user,
        int count = 10)
    {
        var posts = await dbContext.Posts
            .Where(p => p.UserId == user.UserId)
            .OrderByDescending(p => p.Id)
            .Take(count)
            .Select(p => new PostResponse
            {
                // ...
            })
            .ToListAsync();

        return posts;
    }
}

Here we use [ExtendObjectType] attribute to tell HotChocolate that this class extends the UserRootType.

The [Parent] parameter injects the UserRootType, so we can get a User.Id inside our queries.

Other queries are similar:

[ExtendObjectType(typeof(UserRootType))]
public class NotificationQueries
{
    public async Task<List<NotificationResponse>> GetUserNotifications(
        SocialMediaDbContext dbContext,
        [Parent] UserRootType user,
        int count = 10)
    {
        var notifications = await dbContext.Notifications
            .Where(n => n.UserId == user.UserId)
            .OrderByDescending(n => n.CreatedAt)
            .Take(count)
            .Select(n => new NotificationResponse
            {
                /// ...
            })
            .ToListAsync();

        return notifications;
    }
}

[ExtendObjectType(typeof(UserRootType))]
public class FeedQueries
{
    public async Task<List<FeedResponse>> GetUserFeed(
        SocialMediaDbContext dbContext,
        [Parent] UserRootType user,
        int count = 10)
    {
        var feed = await dbContext.Feeds
            .Where(f => f.UserId == user.UserId)
            .OrderByDescending(f => f.CreatedAt)
            .Take(count)
            .Select(f => new FeedResponse
            {
                /// ...
            })
            .ToListAsync();

        return feed;
    }
}

We need to register these types in the GraphQL setup.
Luckily, HotChocolate.Types.Analyzers package supports source generation to simplify this process.

Add the ModuleInfo.cs file into your project where GraphQL Queries are defined:

using HotChocolate;

[assembly: Module("SocialMediaTypes")]

Now you can call the AddSocialMediaTypes extension method to register all types in the module:

builder.Services
    .AddGraphQLServer()
    .AddQueryType()
    .AddSocialMediaTypes() // Add this line
    .AddQueryContext()
    .DisableIntrospection(builder.Environment.IsProduction());

Here is our project's structure. I have defined all API endpoints and GraphQL queries in the HotChocolateGraphQL.Presentation project:

This project follows a combination of Vertical Slice and Clean Architecture.

Now it's time to run our project.

Exploring Nitro: HotChocolate's Built-In GraphQL UI

Once you have HotChocolate wired up and your app running, navigate to http://localhost:5000/graphql to explore the schema.

You'll be greeted by Nitro, HotChocolate's GraphQL IDE:

It doesn't require any extra configuration.

Press a "Browse Schema" button and Nitro will send an introspection query (__schema) to fetch all types, fields, enums, and directives:

On the "Schema" tab you can find:

All your query types like UserRootType
Response types (PostResponse, etc.)
Built-in scalars/ enums.

After you make changes in your schema and re-launch the app, press the "refresh" button to see the changes.

On the "Operation" tab you can write your queries:

Nitro has a built-in "Query Builder" that helps you build queries visually, just open the tree and select nodes you want to include in your query.

The "Request" tab shows the generated query and variables.
You can write the query manually, it supports intellisense just like in a regular IDE.

Nitro supports writing and executing GraphQL queries, mutations and subscriptions.

Hit "Run" to execute your query over HTTP (or WebSocket for subscriptions).

The Response panel shows JSON results, errors, and execution timings.

You can also view logs for every request and response:

Let's write a Query that returns the user's feed, notifications and posts:

query User {
  user(userId: 9) {
    userFeed(count: 10) {
      commentsCount
      content
      createdAt
      id
      likesCount
      postId
      username
    }
    userNotifications(count: 10) {
      createdAt
      id
      type
      itemId
      isRead
    }
    userPosts(count: 10) {
      commentsCount
      content
      createdAt
      id
      likesCount
      recentComments {
        createdAt
        id
        text
        username
      }
    }
  }
}

It returns the following response:

{
  "data": {
    "user": {
      "userFeed": [...],
      "userNotifications": [...],
      "userPosts": [...]
    }
  }
}

How this works under the hood:

Root resolver: GetUser(userId: 9) returns a UserRootType holding UserId = 9.
Field resolvers: HotChocolate sees three selections: userFeed, userNotifications, userPosts, and executes each corresponding method, passing in UserRootType and the count argument.
Projection & LINQ: Each resolver issues a LINQ query against SocialMediaDbContext, projects into the lightweight response DTO, and returns the list.
Single HTTP round-trip: Nitro (or any GraphQL client) makes one POST to /graphql with the above operation; the server returns a JSON payload combining all data.

By default, GraphQL executes each method in a query in parallel.
However, when we use EF Core's DbContext, it executes each query in sequence, as it's only allowed to access DbContext from a single thread.

Let's explore what powerful features HotChocolate offers when integrating with EF Core.

Built-in Tools for Projections, Filtering, Sorting, and Paging

HotChocolate comes with middleware attributes that plug directly into your query methods for projections, filtering, sorting and pagination.
These middlewares integrate directly with IQueryable or IEnumerable. And thus, integrate with EF Core.

Let's explore an example of an admin query that allows filtering, sorting, projecting and paging for Posts:

[QueryType]
public class PostQueries
{
    [UseOffsetPaging(MaxPageSize = 100, IncludeTotalCount = true)]
    [UseProjection]
    [UseFiltering]
    [UseSorting]
    public IQueryable<Post> GetPosts(SocialMediaDbContext dbContext)
    {
        return dbContext.Posts.AsNoTracking();
    }
}

Here, we return all posts from DbContext and HotChocolate hooks into the IQueryable to apply the filters, sort, projection and paging.

Make sure to add the following Nuget package to your project:

<ItemGroup>
    <PackageReference Include="HotChocolate.Types.OffsetPagination" Version="15.1.5" />
</ItemGroup>

And register the middlewares in the DI:

builder.Services
    //...
    .AddFiltering()
    .AddSorting()
    .AddProjections()
    .AddPagingArguments();

Here is a query we can send to the server to apply only paging:

query AdminArea {
  posts(skip: 0, take: 3, where: null, order: null) {
    totalCount
    items {
      id
      categoryId
      content
      createdAt
      category {
        id
        name
      }
      user {
        id
        username
      }
      comments {
        text
        userId
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
  }
}

Here is how we can filter, sort and project the results:

query AdminArea {
  posts(skip: 0, take: 3,
    where: {
        user:  {
            username:  {
                eq: "Rory6"
            }
        }
    },
    order: {
        category:  {
            name: ASC
        }
    }
  ) {
    items {
      id
      categoryId
      content
    }
  }

No magic, HotChocolate just does all the heavy lifting for you.

Behind the scenes, HotChocolate translates your GraphQL arguments into LINQ:

dbContext.Posts
    .OrderBy(p => /* order clause */)
    .Where(/* filter clause */)
    .Skip(0)
    .Take(3)
    .Select(/* projection based on requested fields */)

It's somewhat a similar experience to OData, but much more powerful and flexible.

Best Practices for Organizing Code With HotChocolate

IQueryable and DbContext may be not something you want to use in production code in your GraphQL queries.

Ideally, we want our GraphQL layer to be as thin as possible.
We may want to hide business logic inside our Application and Domain layers.

Let's explore how we can push this logic down into an Application Service layer:

[UseOffsetPaging(MaxPageSize = 100, IncludeTotalCount = true)]
[UseProjection]
[UseFiltering]
[UseSorting]
public IQueryable<Post> GetPosts(SocialMediaDbContext dbContext)
{
    return dbContext.Posts.AsNoTracking();
}

Here is how we can re-write it:

[UseOffsetPaging(MaxPageSize = 100)]
[UseProjection]
[UseFiltering]
[UseSorting]
public async Task<CollectionSegment<Post>> GetPostsNew(
    PostService postService,
    OffsetPagingArguments pagingArguments,
    QueryContext<Post>? query = null,
    CancellationToken cancellationToken = default)
    => await postService.GetPostsAsync(pagingArguments, query, cancellationToken);

Here we use 2 built-in HotChocolate types:

PagingArguments: represents the paging arguments, e.g. skip, take.
QueryContext<T>: encapsulates a selector expression, a filter expression, and a sort definition.

PostService implementation is straightforward:

public class PostService(SocialMediaDbContext dbContext)
{
    public async Task<CollectionSegment<Post>> GetPostsAsync(
        OffsetPagingArguments pagingArguments,
        QueryContext<Post>? query = null,
        CancellationToken cancellationToken = default)
        => await dbContext.Posts
            .OrderByDescending(x => x.CreatedAt)
            .With(query)
            .ApplyOffsetPaginationAsync(pagingArguments, cancellationToken);
}

The key point here is that we use With method to apply the filter, projection and sort expressions on the DbContext.
We call ApplyOffsetPaginationAsync to apply paging.

This is a new feature of HotChocolate 15, you learn more here.

You need to register the AddQueryContext in the GraphQL Server:

builder.Services
    //...
    .AddQueryContext();

Here is one more advice to consider: create a GraphQL schema each time you launch your application:

// Map GraphQL endpoint
app.MapGraphQL();

// Save schema into file to see the changed in GIT
var executor = await app.Services.GetRequestExecutorAsync();
await File.WriteAllTextAsync("schema.graphql", executor.Schema.ToString());

await app.RunAsync();

And commit schema.graphql to GIT.
This way you can control all the changes in your GraphQL schema and review every change to it.

Summary

In this post, we explored how to replace multiple REST endpoints with a single, flexible GraphQL schema using HotChocolate and EF Core.

Key takeaways:

GraphQL vs. REST: Clients fetch exactly the fields they need and combine multiple resources into one request, reducing over- and under-fetching.
Single-Round-Trip Queries: Clients send one GraphQL query to fetch feed items, notifications, and posts simultaneously, with only requested fields.
HotChocolate Setup: A few lines in Program.cs register the GraphQL server and enable filtering, sorting, projections, paging.
Query Types & Extensions: A thin UserRootType plus [QueryType] and [ExtendObjectType] classes let us expose userFeed, userNotifications, and userPosts under one user(userId: Int!) field.
Nitro UI: HotChocolate's built-in Nitro IDE instantly introspects your schema, provides a visual query builder, and lets you test GraphQL queries, mutations and subscriptions in the browser.
Advanced Patterns: Middleware attributes like [UseOffsetPaging], [UseFiltering], and [UseSorting] plug directly into IQueryable methods — automating filters, projections, sorting, and paging.

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

How to Implement Refresh Tokens and Token Revocation in ASP.NET Core

Anton Martyniuk — Tue, 01 Jul 2025 10:33:35 +0000

Nowadays JWT (JSON Web Token) authentication is the industry standard for maintaining stateless and secure user sessions.

JWTs have changed how we handle authentication in modern web applications.
Unlike traditional session-based authentication that stores session data on the server, JWTs carry all necessary user information within the tokens themselves.
This approach enhances scalability and performance.

However, the real challenge isn't implementing basic JWT authentication; it's managing security and user experience when tokens expire.

In today's post, we will explore:

What are Refresh Tokens and how they work
Implementing Refresh Tokens
Ensuring security best practices
Revoking Refresh Tokens to dynamically update user permissions

Let's dive in!

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.

What Are Refresh Tokens and How They Work?

Typically, JWT authentication involves two tokens: an access token and a refresh token.

The access token grants permission to access protected resources but is short-lived, often between 5 and 10 minutes.

A short lifespan reduces risk if access tokens are compromised.
But if your access token lives only for a few minutes, users would have to log in over and over.
This is a terrible user experience.

Here's where refresh tokens come in handy.
The refresh token has a single purpose: obtaining a new access token when the current one expires – without forcing users to log in again.
Typically, refresh tokens are long-lived, lasting days or weeks.

Here's the authentication flow using Refresh Tokens:

1. Login:

User logs in and receives an access token and a refresh token.

2. Store both tokens:

Tokens should be stored securely in HttpOnly cookies or encrypted storage.

3. Check Token Expiry:

When the access token expires or returns a 401 response, the client initiates a token refresh.

4. Call Refresh Endpoint:

The client sends a pair of access and refresh tokens to a special refresh URL over HTTPS.

5. Server Checks:

Server verifies the refresh token is valid, unexpired, and not revoked.

6. New Tokens Issued:

If it's all good, the server gives you a new pair of access and a refresh token.

7. Update Client:

The client replaces the old tokens and continues without asking the user to log in again.

Let's explore how to implement this in code.

How to Implement Refresh Tokens

If you're new to JWT or ASP.NET Core Authentication, check out my detailed article first.

In this article you can get familiar with the codebase we will be expanding today.

Here's a brief overview of our authentication setup:

var tokenValidationParameters = new TokenValidationParameters
{
    ValidateIssuer = true,
    ValidateAudience = true,
    ValidateLifetime = true,
    ValidateIssuerSigningKey = true,
    ValidIssuer = configuration["AuthConfiguration:Issuer"],
    ValidAudience = configuration["AuthConfiguration:Audience"],
    IssuerSigningKey = new SymmetricSecurityKey(
        Encoding.UTF8.GetBytes(configuration["AuthConfiguration:Key"]!))
};

services.AddSingleton(tokenValidationParameters);

services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
    options.TokenValidationParameters = tokenValidationParameters;
});

services.AddAuthorization(options =>
{
    options.AddPolicy("Admin", policy =>
    {
        policy.RequireRole("Admin");
    });

    options.AddPolicy("Author", policy =>
    {
        policy.RequireRole("Author");
    });
});

First, let's create a RefreshToken entity and connect it to a user with a foreign key:

public class RefreshToken
{
    public string Token { get; set; } = null!;

    public string JwtId { get; set; } = null!;

    public DateTime ExpiryDate { get; set; }

    public bool Invalidated { get; set; }

    public string UserId { get; set; } = null!;

    public User User { get; set; } = null!;
}

public void Configure(EntityTypeBuilder<RefreshToken> builder)
{
    builder.ToTable("refresh_tokens");

    builder.HasKey(e => e.Token);

    builder.Property(e => e.JwtId).IsRequired();
    builder.Property(e => e.ExpiryDate).IsRequired();
    builder.Property(e => e.Invalidated).IsRequired();
    builder.Property(e => e.UserId).IsRequired();
    builder.Property(e => e.CreatedAtUtc).IsRequired();
    builder.Property(e => e.UpdatedAtUtc);

    builder.HasOne(e => e.User)
        .WithMany()
        .HasForeignKey(e => e.UserId);
}

Here are our basic authentication models:

public sealed record LoginUserRequest(string Email, string Password);
public sealed record LoginUserResponse(string Token, string RefreshToken);

When a user logs in, the server returns both tokens.

Here is our endpoint for refreshing tokens:

public sealed record RefreshTokenRequest(string Token, string RefreshToken);
public sealed record RefreshTokenResponse(string Token, string RefreshToken);

public class RefreshTokenEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/users/refresh", Handle);
    }

    private static async Task<IResult> Handle(
        [FromBody] RefreshTokenRequest request,
        IClientAuthorizationService authorizationService,
        CancellationToken cancellationToken)
    {
        var result = await authorizationService.RefreshTokenAsync(
            request.Token,
            request.RefreshToken,
            cancellationToken);

        if (!result.IsSuccess)
        {
            return Results.Problem(
                statusCode: 400,
                detail: result.Errors?[0].Message,
                title: result.Errors?[0].Code);
        }

        var response = new RefreshTokenResponse(result.Data!.Token, result.Data.RefreshToken);
        return Results.Ok(response);
    }
}

Let's explore the implementation of authorizationService.RefreshTokenAsync in details:

public async Task<Result<RefreshTokenResponse>> RefreshTokenAsync(
    string token,
    string refreshToken,
    CancellationToken cancellationToken = default)
{
    // Validates the digital signature of the provided access token
    var validatedToken = GetPrincipalFromToken(token, _tokenValidationParameters);
    if (validatedToken is null)
    {
        return Result<RefreshTokenResponse>.Failure(ErrorInvalidToken, "Invalid token");
    }

    // Extracts JWT id from the claims
    var jti = validatedToken.Claims
        .SingleOrDefault(x => x.Type == JwtRegisteredClaimNames.Jti)?.Value;

    if (string.IsNullOrEmpty(jti))
    {
        return Result<RefreshTokenResponse>.Failure(ErrorInvalidToken, "Invalid token");
    }

    // Verifies if refresh token exists in the database
    var storedRefreshToken = await _dbContext.RefreshTokens
        .FirstOrDefaultAsync(x => x.Token == refreshToken, cancellationToken);

    if (storedRefreshToken is null)
    {
        return Result<RefreshTokenResponse>.Failure(ErrorInvalidToken,
            "This refresh token does not exist");
    }

    // Confirms that the refresh token hasn't expired yet
    if (DateTime.UtcNow > storedRefreshToken.ExpiryDate)
    {
        return Result<RefreshTokenResponse>.Failure(ErrorInvalidToken,
            "This refresh token has expired");
    }

    // Verifies that the refresh token hasn't been manually invalidated (revoked)
    if (storedRefreshToken.Invalidated)
    {
        return Result<RefreshTokenResponse>.Failure(ErrorInvalidToken,
            "This refresh token has been invalidated");
    }

    // Ensures the refresh token is paired with the correct JWT by comparing the IDs
    if (storedRefreshToken.JwtId != jti)
    {
        return Result<RefreshTokenResponse>.Failure(ErrorInvalidToken,
            "This refresh token does not match this JWT");
    }

    var userId = validatedToken.Claims.FirstOrDefault(x => x.Type == "userid")?.Value;
    if (userId is null)
    {
        return Result<RefreshTokenResponse>.Failure(ErrorUserNotFound,
            "Current user is not found");
    }

    // Search for a user in the database
    var user = await _userManager.FindByIdAsync(userId);
    if (user is null)
    {
        return Result<RefreshTokenResponse>.Failure(ErrorUserNotFound,
            "Current user is not found");
    }

    // Creates a brand new pair of tokens (access token and refresh token)
    var (newToken, newRefreshToken) = await GenerateJwtAndRefreshTokenAsync(user, refreshToken);

    var response = new RefreshTokenResponse(newToken, newRefreshToken);
    return Result<RefreshTokenResponse>.Success();
}

You can use JwtSecurityTokenHandler to validate a digital signature of an access token:

private static ClaimsPrincipal? GetPrincipalFromToken(
    string token,
    TokenValidationParameters parameters)
{
    var tokenHandler = new JwtSecurityTokenHandler();

    try
    {
        var tokenParameters = parameters.Clone();
        tokenParameters.ValidateLifetime = false;
        var principal = tokenHandler.ValidateToken(token, tokenParameters, out var validatedToken);
        return IsJwtWithValidSecurityAlgorithm(validatedToken) ? principal : null;
    }
    catch
    {
        return null;
    }
}

private static bool IsJwtWithValidSecurityAlgorithm(SecurityToken validatedToken)
    => validatedToken is JwtSecurityToken jwtSecurityToken
       && jwtSecurityToken.Header.Alg
            .Equals(SecurityAlgorithms.HmacSha256,StringComparison.InvariantCultureIgnoreCase);

Here is how to create an access (JWT) token:

private async Task<(string token, string refreshToken)> GenerateJwtAndRefreshTokenAsync(
    User user,
    string? existingRefreshToken)
{
    var roles = await _userManager.GetRolesAsync(user);
    var userRole = roles.FirstOrDefault() ?? "user";

    var role = await _roleManager.FindByNameAsync(userRole);
    var roleClaims = role is not null ? await _roleManager.GetClaimsAsync(role) : [];

    var token = GenerateJwtToken(user, _authOptions.Value, userRole, roleClaims);
    var refreshToken = await GenerateRefreshTokenAsync(token, user, existingRefreshToken);

    return (token, refreshToken);
}

And a refresh token:

private async Task<string> GenerateRefreshTokenAsync(
    string token,
    User user,
    string? existingRefreshToken)
{
    var tokenHandler = new JwtSecurityTokenHandler();
    var jwtToken = tokenHandler.ReadJwtToken(token);
    var jti = jwtToken.Id;

    var refreshToken = new RefreshToken
    {
        Token = Guid.NewGuid().ToString(),
        JwtId = jti,
        UserId = user.Id,
        ExpiryDate = DateTime.UtcNow.AddDays(7),
        CreatedAtUtc = DateTime.UtcNow,
    };

    if (!string.IsNullOrEmpty(existingRefreshToken))
    {
        var existingToken = await _dbContext.RefreshTokens
            .FirstOrDefaultAsync(x => x.Token == existingRefreshToken);

        if (existingToken != null)
        {
            _dbContext.Set<RefreshToken>().Remove(existingToken);
        }
    }

    await _dbContext.AddAsync(refreshToken);
    await _dbContext.SaveChangesAsync();

    return refreshToken.Token;
}

Here we generate a Refresh Token that is valid for 7 days.
If a user logs in before the token expires — a new token is generated (for another 7 days); otherwise, a user is logged out.

It's also important to ensure that old refresh tokens are deleted from the database — to prevent their reuse.

You can download the full source at the end of the post

Security Considerations for Token Refreshing

Implementing token refresh mechanisms introduces several security considerations that must be addressed to maintain a robust authentication system:

Token Storage: Store an access and a refresh token securely in HttpOnly cookies to prevent XSS attacks.
Token Rotation: Each refresh token use should invalidate the old token, limiting attackers' potential damage.
Token Revocation: Maintain a blacklist of invalidated tokens to handle logouts, password changes, and suspicious activity.
Detecting Token Theft: Implement mechanisms to detect potential token theft, such as tracking token usage patterns or implementing token binding to specific devices or IP ranges. Unusual patterns may indicate an unauthorized use of a stolen token.
Scope Limitation: Refresh tokens should have minimal privileges, limited solely to requesting new access tokens. They should not grant direct access to any protected resources or sensitive operations.

Access (JWT) tokens should be short-lived, ideally 5-10 minutes (the less - the better).
While refresh tokens can live from a few days to several weeks.

For some web and mobile applications that require a user to log in only once per month — you can make refresh tokens expire after 1-2 months.

On the other hand, financial or sensitive applications might use even shorter durations for enhanced security.
If the user is not active for 10-30 minutes — token is revoked and the user is logged out.

Revoking Refresh Tokens for Dynamic Permission Update

Sometimes, you need to update permissions dynamically through token revocation.

When a role or set of claims is updated on the server - user automatically refreshes the token on the next request and receives updated permissions.
The moment a user navigates or refreshes a page - he is granted new permissions and sees changes in the navigation menu.

Let's explore a UpdateUserRoleEndpoint:

[Authorize(Roles = "admin")]
public class UpdateUserRoleEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/users/{userId}/role", Handle)
            .RequireAuthorization("admin");
    }

    private static async Task<IResult> Handle(
        [FromRoute] string userId,
        [FromBody] UpdateUserRoleRequest request,
        IClientAuthorizationService service,
        CancellationToken cancellationToken)
    {
        var result = await service.UpdateUserRoleAsync(userId, request.NewRole, cancellationToken);

        if (!result.IsSuccess)
        {
            if (result.Errors?[0].Code == "user_not_found")
            {
                return Results.NotFound(new UpdateUserRoleResponse(false
                    result.Errors[0].Message));
            }

            return Results.BadRequest(new UpdateUserRoleResponse(false,
                result.Errors?[0].Message ?? "An error occurred"));
        }

        return Results.Ok(new UpdateUserRoleResponse(true, result.Data!));
    }
}

When roles or permissions change, mark the user's refresh tokens as invalidated and store them in MemoryCache or Distributed Cache (like Redis).

// Invalidate all refresh tokens for this user
var refreshTokens = await _dbContext.RefreshTokens
    .Where(rt => rt.UserId == userId && !rt.Invalidated)
    .ToListAsync(cancellationToken);

foreach (var refreshToken in refreshTokens)
{
    refreshToken.Invalidated = true;
    refreshToken.UpdatedAtUtc = DateTime.UtcNow;

    // Add to memory cache for the middleware to check
    _memoryCache.Set(refreshToken.JwtId, RevocatedTokenType.RoleChanged);
}

await _dbContext.SaveChangesAsync(cancellationToken);

Every incoming request checks if the access token was revoked.
If revoked, the server responds with a 401, triggering a token refresh.
This updates the user's claims instantly.

public class CheckRevocatedTokensMiddleware
{
    private readonly RequestDelegate _next;
    private readonly IMemoryCache _memoryCache;

    public CheckRevocatedTokensMiddleware(RequestDelegate next, IMemoryCache memoryCache)
    {
        _next = next;
        _memoryCache = memoryCache;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        if (context.Request.Path.StartsWithSegments("/login")
            || context.Request.Path.StartsWithSegments("/refresh"))
        {
            await _next(context);
            return;
        }

        var jwtId = context.User.FindFirst(JwtRegisteredClaimNames.Jti);
        var role = context.User.FindFirst(ClaimTypes.Role);
        if (jwtId is null || role is null)
        {
            await _next(context);
            return;
        }

        var revocationType = _memoryCache.Get<RevocatedTokenType?>(jwtId.Value);
        if (revocationType.HasValue)
        {
            context.Response.StatusCode = StatusCodes.Status401Unauthorized;
            return;
        }

        await _next(context);
    }
}

Remember to register the middleware:

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseAuthentication();
app.UseAuthorization();

app.UseMiddleware<CheckRevocatedTokensMiddleware>();

app.MapCarter();

await app.RunAsync();

Use a HostedService to load revoked tokens into MemoryCache on app startup to persist revocation across application restarts:

public class InvalidatedTokensHostedService : IHostedService
{
    private readonly IMemoryCache _memoryCache;
    private readonly IServiceProvider _serviceProvider;

    public InvalidatedTokensHostedService(
        IMemoryCache memoryCache,
        IServiceProvider serviceProvider)
    {
        _memoryCache = memoryCache;
        _serviceProvider = serviceProvider;
    }

    public async Task StartAsync(CancellationToken cancellationToken)
    {
        using var scope = _serviceProvider.CreateScope();
        var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();

        var invalidatedTokens = await dbContext.RefreshTokens
            .Where(x => x.Invalidated)
            .ToListAsync(cancellationToken: cancellationToken);

        foreach (var token in invalidatedTokens)
        {
            _memoryCache.Set(token.JwtId, RevocatedTokenType.Invalidated);
        }
    }

    public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}

In the same way you can revoke the token and forbid further access on the next refresh attempt.

Summary

Refresh tokens enable short-lived access tokens without repeatedly logging users.
By implementing the strategies outlined in this post, your application will achieve optimal security, performance, and user experience.
With careful planning, JWT refresh and revocation mechanisms can make your authentication system robust and secure.

On my website: antondevtips.com I share .NET and Architecture best practices.
Subscribe to my newsletter to improve your .NET skills.
Download the source code for this newsletter for free.