DEV Community: Anton Martyniuk

Github Actions for .NET: Build, Test, and Ship With Docker

Anton Martyniuk — Tue, 28 Jul 2026 11:11:56 +0000

You just pushed your code, and now you wait.

Did the build pass? Did the tests run? Is the Docker image ready to ship?

If you are checking these by hand, you are doing work a machine should do for you.

A good CI/CD pipeline builds, tests, and ships every change the same way, every time - without you babysitting it.

Over the years, I have set up these pipelines for many .NET projects, and GitHub Actions has become my default.

It lives right next to your code, it is free for most projects, and it can take a single commit all the way from a pull request to a published Docker image.

In this post, we will explore:

What are GitHub Actions
Building and testing your .NET app
Publishing a NuGet package after tests pass
Building a Docker image that runs tests
Setting up secrets in GitHub Actions
Pushing the Docker image to the registry

Let's dive in.

What Are GitHub Actions?

GitHub Actions is a built-in automation platform inside every GitHub repository.

You describe what should happen when something occurs in your repository - a push, a pull request, a new tag, a schedule or manual - and GitHub runs it for you on a fresh virtual machine.

You need to know these terms to be able to read any workflow:

Workflow: an automated process defined in a YAML file under .github/workflows. A repository can have many.
Event: what triggers a workflow - a push, a pull_request, a release, or a schedule.
Job: a group of steps that runs on one machine. Jobs run in parallel by default, or in order when one needs another.
Step: a single task - either a shell command (run) or a reusable action (uses).
Runner: the machine that executes a job. GitHub hosts Linux, Windows, and macOS runners, and you can host your own.

Any workflow in GitHub Actions is a series of steps that run on a virtual machine.

With these, you can automate almost anything related to your code: run tests on every pull request, publish a NuGet package with a new release, build and push a Docker image, run a nightly security scan, or post a message to Slack.

Because a workflow is just a file in your repository, it is versioned with your code and reviewed in pull requests like everything else. The pipeline evolves together with the application it builds.

Every workflow is a single YAML file. Here is the smallest one that does real work - it runs on each push to main and prints a line on an Ubuntu runner:

name: HELLO

on:
  push:
    branches: [ "main" ]

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - run: echo "GitHub Actions is running"

Save this as .github/workflows/hello.yml, push it, and open the Actions tab in your repository to watch it run.

👉 Read the full article on my newsletter: https://antondevtips.com/blog/github-actions-for-dotnet-build-test-and-ship-with-docker

Why Every EF Core Developer Needs to Try Entity Framework Extensions

Anton Martyniuk — Fri, 24 Jul 2026 08:21:37 +0000

When building data-intensive applications with Entity Framework Core, you will eventually face a critical performance challenge: inserting, updating, or deleting thousands of records efficiently.

The standard EF Core approach using SaveChanges() works perfectly for small datasets or even a few hundred rows, but it becomes a significant bottleneck when you need to process thousands of records.

There is a better solution: Entity Framework Extensions provides high-performance bulk operations that can process thousands of records in less than a second. You still use the same code you have in EF Core with a new set of DbContext extension methods.

In this post, we will explore:

Why inserting 10,000+ rows with EF Core quickly becomes a performance bottleneck
What happens under the hood when you call SaveChanges() and why it slows down at scale
How Entity Framework Extensions solve bulk data problems without rewriting your EF Core code
How to import data at scale using BulkInsert to insert thousands of records in a single operation
How to apply mass updates with BulkUpdate to efficiently modify large datasets
How to clean up data with BulkDelete to remove large volumes of records in one database round-trip
How to perform upserts and sync external systems using BulkMerge with minimal code
How to run full data synchronization jobs using BulkSynchronize to keep databases in sync reliably

Let's dive in.

Why Inserting 10,000+ Rows with EF Core Becomes a Performance Bottleneck

You are building an IoT platform that collects telemetry data from thousands of devices every minute. Each device sends temperature readings, humidity levels, and status updates.

Your system needs to insert 50,000 telemetry records into the database every few minutes.

You start with the standard Entity Framework Core approach:

app.MapPost("/telemetries", async (IotDbContext dbContext, InsertTelemetryRequest request) =>
{
   var telemetryEntries = request.MapToTelemetryEntries();

   dbContext.Telemetries.AddRange(telemetryEntries);
   await dbContext.SaveChangesAsync();

   return Results.Ok();
});

Using the standard SaveChanges() approach, this operation could take several seconds or even minutes and consume excessive memory. This is a common problem when working with Entity Framework Core at scale.

EF Core is excellent for typical CRUD operations, but it was not designed for bulk data operations. When you need to insert, update, or delete thousands of records, the standard SaveChanges() method becomes a performance bottleneck.

Entity Framework Extensions is a library that solves this problem. It extends EF Core with high-performance bulk operations that can handle large datasets efficiently.

All examples in this post were tested on a SQL Server database using the IoT telemetry application.

👉 Read the full article on my newsletter: https://antondevtips.com/blog/why-every-ef-core-developer-needs-to-try-entity-framework-extensions

10 Reasons to Upgrade to .NET 10

Anton Martyniuk — Thu, 23 Jul 2026 20:21:58 +0000

.NET 10 and C# 14 were released on November 11, 2025.

Today, I want to show 10 reasons why you should consider upgrading your projects to .NET 10.

1. Long-Term Support (LTS) Release

Here is a lifecycle for the currently supported .NET versions:

.NET 10

Release date: November 11, 2025
Release type: LTS
End of support: November 14, 2028

.NET 9

Release date: November 12, 2024
Release type: STS
End of support: November 10, 2026

.NET 8

Release date: November 14, 2023
Release type: LTS
End of support: November 10, 2026

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.

Support for .NET 8 ends on November 10, 2026, so you should consider upgrading to .NET 10 as soon as possible.

👉 Read the full article on my newsletter: https://antondevtips.com/blog/10-reasons-to-upgrade-to-dotnet-10

Top 10 Things Every .NET Developer Needs to Do in 2026

Anton Martyniuk — Thu, 23 Jul 2026 18:42:31 +0000

I have been working with .NET since .NET Framework 3.5, and I have learned that staying ahead means adopting the right tools and practices at the right time. In this post, I want to share 10 actionable steps that will help you grow as a .NET developer in 2026.

These are practices I follow myself and recommend to every developer I work with.

Let's dive in.

1. Migrate Your Existing Projects to .NET 10

.NET 10 and C# 14 were released on 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.

Here are the most amazing new features in this release:

C# 14:

Extension Members
Null-Conditional Assignment
The Field Keyword
Lambda Parameters with Modifiers
Partial Constructors and Events

File-Based Apps:

Starting with .NET 10, you can create a single *.cs file and run it directly, without solution file (sln) and project file (csproj).

ASP.NET Core:

Validation Support in Minimal APIs
JSON Patch Support in Minimal APIs
Server-Sent Events (SSE)
OpenAPI 3.1 Support

EF Core:

Optional Complex Types
JSON and struct Support for Complex Types
LeftJoin and RightJoin Operators
Named Query Filters
ExecuteUpdate for JSON Columns
Regular Lambdas in ExecuteUpdate

Here is a list of resources to help you migrate your existing projects to .NET 10:

My in-depth article on the new features.
Breaking changes in .NET 10
How Migrate from ASP.NET Core in .NET 9 to ASP.NET Core in .NET 10
.NET Upgrade Assistant

It's a good time to start migrating your projects to .NET 10 in 2026.

👉 Read the full article on my newsletter: https://antondevtips.com/blog/top-10-things-every-dotnet-developer-needs-to-do-in-2026

Named Global Query Filters Were Updated in EF Core 10

Anton Martyniuk — Mon, 20 Jul 2026 19:41:09 +0000

Global query filters in Entity Framework Core (EF Core) is a powerful feature that can be effectively used to manage data access patterns.

Global query filters are LINQ query predicates applied to EF Core entity models. These filters are automatically applied to all queries that involve the corresponding entities. This is especially useful in multi-tenant applications or scenarios requiring soft deletion.

In EF Core 10, Global Query Filters were renamed to Named Query Filters.

This update now solves a significant limitation EF Core previously had: support for multiple global query filters on a single entity.

In this post, we will explore:

Query Filters for a Soft Delete use case
Query Filters for a Multi-Tenant application
Named Query Filters

Let's dive in.

Query filters for a soft delete use case

Let's explore a use case where global query filters are particularly useful — entity soft deletion. In some applications, entities can't be completely deleted from the database and should remain for statistics and historical purposes. Or to ensure that related data remains unchanged, i.e, referenced by foreign keys. A solution for this use case is soft deletion.

Soft deletion is implemented by adding an is_deleted column to the database table for required entities. Whenever an entity is considered deleted, this column is set to true. In most application database queries, "deleted" entities should be ignored in read operations and not be visible to end users.

Let's explore an example for the following entities:

public class Author
{
    public required Guid Id { get; set; }
    public required string Name { get; set; }
    public required string Country { get; set; }
    public required List<Book> Books { get; set; } = [];
}

public class Book
{
    public required Guid Id { get; set; }
    public required string Title { get; set; }
    public required int Year { get; set; }
    public required bool IsDeleted { get; set; }
    public required Guid TenantId { get; set; }
    public required Author Author { get; set; }
}

We need to create and set up our DbContext with a global query filter:

public class ApplicationDbContext : DbContext
{
    public DbSet<Author> Authors { get; set; } = default!;

    public DbSet<Book> Books { get; set; } = default!;

    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Book>()
            .HasQueryFilter(x => !x.IsDeleted);

        base.OnModelCreating(modelBuilder);

        modelBuilder.Entity<Author>(entity =>
        {
            entity.ToTable("authors");

            entity.HasKey(x => x.Id);
            entity.HasIndex(x => x.Name);

            entity.Property(x => x.Id).IsRequired();
            entity.Property(x => x.Name).IsRequired();
            entity.Property(x => x.Country).IsRequired();

            entity.HasMany(x => x.Books)
                .WithOne(x => x.Author);
        });

        modelBuilder.Entity<Book>(entity =>
        {
            entity.ToTable("books");

            entity.HasKey(x => x.Id);
            entity.HasIndex(x => x.Title);

            entity.Property(x => x.Id).IsRequired();
            entity.Property(x => x.Title).IsRequired();
            entity.Property(x => x.Year).IsRequired();
            entity.Property(x => x.IsDeleted).IsRequired();

            entity.HasOne(x => x.Author)
                .WithMany(x => x.Books);
        });
    }
}

In this code, we're applying a query filter to the Book entity on the IsDeleted property:

modelBuilder.Entity<Book>()
    .HasQueryFilter(x => !x.IsDeleted);

Here we are filtering out all softly deleted books from the result query. When querying books from DbContext, this query filter is applied automatically. Let's have a look at the following minimal API endpoint:

app.MapGet("/api/books", async (ApplicationDbContext dbContext) =>
{
    var nonDeletedBooks = await dbContext.Books.ToListAsync();
    return Results.Ok(nonDeletedBooks);
});

Every time we query books, we only get those that are not deleted, thus we don't need to use a LINQ Where statement in all DbContext queries.

In some cases, however, we might need to access all entities and ignore the query filter. EF Core has a special method called IgnoreQueryFilters for such a case:

app.MapGet("/api/all-books", async (ApplicationDbContext dbContext) =>
{
    var allBooks = await dbContext.Books
        .IgnoreQueryFilters()
        .Where(x => x.IsDeleted)
        .ToListAsync();

    return Results.Ok(allBooks);
});

That way, all the books are retrieved from the database, and the query filter on the Book entity is completely ignored.

👉 Read the full article on my newsletter: https://antondevtips.com/blog/named-global-query-filters-were-updated-in-ef-core-10

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.