DEV Community: Spyros Ponaris

Abstract Factory Pattern in C# – Step-by-Step Tutorial

Spyros Ponaris — Mon, 11 May 2026 08:20:18 +0000

Abstract Factory Pattern in C# – Step-by-Step Tutorial (Using My Project)

In this tutorial, I’ll explain how I implemented the Abstract Factory Pattern in C# using my project:

GitHub Repository: https://github.com/stevsharp/AbstractFactoryDemo

This project demonstrates how to support multiple database providers like:

SQL Server
MySQL

Each database needs related objects such as:

Database Connection
Database Command

Instead of hardcoding these objects directly, we use the Abstract Factory Pattern to make the code cleaner and scalable.

Step 1: The Problem

Imagine your application supports multiple databases.

Without using Abstract Factory, your code may look like this:

if(databaseType == "SQL")
{
    var connection = new SqlConnection();
    var command = new SqlCommand();
}
else
{
    var connection = new MySqlConnection();
    var command = new MySqlCommand();
}

Why this is bad:

Too many if/else statements
Hard to maintain
Difficult to scale
Tight coupling with concrete classes

We need a better approach.

Step 2: Create Abstract Products

These interfaces define common behavior for all database implementations.

IDbConnection.cs

public interface IDbConnection
{
    void Connect();
}

IDbCommand.cs

public interface IDbCommand
{
    void Execute();
}

Now every database provider must implement these interfaces.

Step 3: Create SQL Server Products

SqlConnection.cs

public class SqlConnection : IDbConnection
{
    public void Connect()
    {
        Console.WriteLine("Connecting to SQL Server...");
    }
}

SqlCommand.cs

public class SqlCommand : IDbCommand
{
    public void Execute()
    {
        Console.WriteLine("Executing SQL command...");
    }
}

These classes handle SQL Server operations.

Step 4: Create MySQL Products

MySqlConnection.cs

public class MySqlConnection : IDbConnection
{
    public void Connect()
    {
        Console.WriteLine("Connecting to MySQL...");
    }
}

MySqlCommand.cs

public class MySqlCommand : IDbCommand
{
    public void Execute()
    {
        Console.WriteLine("Executing MySQL command...");
    }
}

These classes handle MySQL operations.

Step 5: Create the Abstract Factory

Now we create a factory interface.

IDatabaseFactory.cs

public interface IDatabaseFactory
{
    IDbConnection CreateConnection();
    IDbCommand CreateCommand();
}

This ensures every factory creates:

Connection objects
Command objects

Step 6: Create SQL Server Factory

SqlServerFactory.cs

public class SqlServerFactory : IDatabaseFactory
{
    public IDbConnection CreateConnection()
    {
        return new SqlConnection();
    }

    public IDbCommand CreateCommand()
    {
        return new SqlCommand();
    }
}

This factory creates SQL-related objects.

Step 7: Create MySQL Factory

MySqlFactory.cs

public class MySqlFactory : IDatabaseFactory
{
    public IDbConnection CreateConnection()
    {
        return new MySqlConnection();
    }

    public IDbCommand CreateCommand()
    {
        return new MySqlCommand();
    }
}

This factory creates MySQL-related objects.

Step 8: Use the Factory in Client Code

Now the client works with the factory instead of concrete classes.

Program.cs

class Program
{
    static void Main()
    {
        IDatabaseFactory factory = new MySqlFactory();

        var connection = factory.CreateConnection();
        var command = factory.CreateCommand();

        connection.Connect();
        command.Execute();
    }
}

Output

Connecting to MySQL...
Executing MySQL command...

Step 9: Why This Pattern Is Useful

Let’s say your application needs to support PostgreSQL in the future.

You would simply add:

PostgresConnection
PostgresCommand
PostgresFactory

And your client code stays exactly the same.

That makes your code:

✅ Flexible
✅ Maintainable
✅ Scalable
✅ Easy to test

Visual Flow

Client
   ↓
IDatabaseFactory
   ↓
--------------------------------
↓                              ↓
SqlServerFactory         MySqlFactory
↓                              ↓
SqlConnection            MySqlConnection
SqlCommand               MySqlCommand

Real Interview Explanation

Here’s how you can explain this in an interview:

In this project, I used the Abstract Factory Pattern to create families of related database objects. Each database provider creates its own connection and command objects. This reduces tight coupling and makes the application easier to extend when adding new databases.

When Should You Use Abstract Factory?

Use Abstract Factory when:

You need to create families of related objects
You want loose coupling
Your system supports multiple implementations
You want easier scalability

Examples:

Database providers
UI themes
Payment gateways
Cloud providers

Final Thoughts

Abstract Factory is a great design pattern when your application needs flexibility.

Instead of hardcoding object creation logic everywhere, you centralize it through factories and keep your code clean.

If you want to see the full implementation, check out the repository:

https://github.com/stevsharp/AbstractFactoryDemo

Reference

https://refactoring.guru/design-patterns/abstract-factory

This version is fully formatted for Dev.to Markdown, so you can paste it directly into your article editor.

Refactoring a Simple C# Method Step by Step

Spyros Ponaris — Wed, 06 May 2026 09:01:29 +0000

Refactoring is not about changing what the code does. It is about improving how the code is written.

The goal is to make the code easier to read, easier to test, and easier to maintain.

In this tutorial, we will refactor a simple user registration method step by step.

The Original Code

Imagine we have a method like this:

public void RegisterUser(string username, string password, int age, string email)
{
    if (username == null || username == "")
    {
        throw new Exception("Username is required");
    }

    if (password == null || password == "")
    {
        throw new Exception("Password is required");
    }

    if (password.Length < 8)
    {
        throw new Exception("Password must be at least 8 characters");
    }

    if (age < 18 || age > 120)
    {
        throw new Exception("Invalid age");
    }

    if (email == null || !email.Contains("@") || !email.Contains("."))
    {
        throw new Exception("Invalid email");
    }

    Console.WriteLine("User registered successfully!");
}

The code works, but it has some problems.

What Is Wrong With This Code?

The method has too many responsibilities.

It validates the username, password, age, and email. It also performs the registration logic.

This makes the method harder to read and harder to test.

Some other issues are:

Validation logic is mixed with business logic.
The method is becoming too long.
The same type of checks are repeated.
The validation rules cannot easily be reused.
The method uses primitive values everywhere, like string and int.

This is a common problem called primitive obsession.

It means we are using simple types like string, int, or decimal for values that have business meaning.

For example, an email is not just a string. A password is not just a string. They both have rules.

Step 1: Use Guard Clauses

A guard clause is a validation check placed at the beginning of a method.

If the input is invalid, the method stops immediately.

This is also called Fail Fast.

public void RegisterUser(string username, string password, int age, string email)
{
    ArgumentException.ThrowIfNullOrWhiteSpace(username);
    ArgumentException.ThrowIfNullOrWhiteSpace(password);

    if (password.Length < 8)
        throw new ArgumentException("Password must be at least 8 characters.", nameof(password));

    if (age is < 18 or > 120)
        throw new ArgumentOutOfRangeException(nameof(age), "Age must be between 18 and 120.");

    if (!IsValidEmail(email))
        throw new FormatException("Invalid email format.");

    Console.WriteLine("User registered successfully!");
}

private bool IsValidEmail(string email)
{
    return !string.IsNullOrWhiteSpace(email)
           && email.Contains("@")
           && email.Contains(".");
}

This version is already better.

We improved the code by using:

Guard Clauses
Extract Method
Fail Fast

The IsValidEmail method makes the code easier to read because the email validation is separated from the main method.

Step 2: Use a Request Object

The method currently receives four parameters.

public void RegisterUser(string username, string password, int age, string email)

This is fine for small examples, but in real applications, this can become messy.

A better approach is to group the input into a request object.

public class UserRegistrationRequest
{
    public string Username { get; set; } = string.Empty;
    public string Password { get; set; } = string.Empty;
    public int Age { get; set; }
    public string Email { get; set; } = string.Empty;
}

Now the method becomes cleaner:

public void RegisterUser(UserRegistrationRequest request)
{
    ArgumentNullException.ThrowIfNull(request);

    ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
    ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

    if (request.Password.Length < 8)
        throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

    if (request.Age is < 18 or > 120)
        throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

    if (!IsValidEmail(request.Email))
        throw new FormatException("Invalid email format.");

    Console.WriteLine("User registered successfully!");
}

This uses the DTO pattern, or Data Transfer Object.

A DTO is useful when we want to pass data between layers, for example from the UI to the application layer.

Step 3: Extract Validation Into a Validator

The registration method still contains validation logic.

We can move that logic into a separate class.

public class UserRegistrationValidator
{
    public void Validate(UserRegistrationRequest request)
    {
        ArgumentNullException.ThrowIfNull(request);

        ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
        ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

        if (request.Password.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

        if (request.Age is < 18 or > 120)
            throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

        if (!IsValidEmail(request.Email))
            throw new FormatException("Invalid email format.");
    }

    private static bool IsValidEmail(string email)
    {
        return !string.IsNullOrWhiteSpace(email)
               && email.Contains("@")
               && email.Contains(".");
    }
}

Now the registration method becomes very small:

public void RegisterUser(UserRegistrationRequest request)
{
    var validator = new UserRegistrationValidator();

    validator.Validate(request);

    Console.WriteLine("User registered successfully!");
}

This is much better.

The service now focuses on the registration process.

The validator focuses on validation.

This follows the Single Responsibility Principle.

Step 4: Inject the Validator

Creating the validator inside the method works, but it is not ideal for testing.

This line creates a direct dependency:

var validator = new UserRegistrationValidator();

A better approach is to inject the validator through the constructor.

First, create an interface:

public interface IUserRegistrationValidator
{
    void Validate(UserRegistrationRequest request);
}

Then update the validator:

public class UserRegistrationValidator : IUserRegistrationValidator
{
    public void Validate(UserRegistrationRequest request)
    {
        ArgumentNullException.ThrowIfNull(request);

        ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
        ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

        if (request.Password.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

        if (request.Age is < 18 or > 120)
            throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

        if (!IsValidEmail(request.Email))
            throw new FormatException("Invalid email format.");
    }

    private static bool IsValidEmail(string email)
    {
        return !string.IsNullOrWhiteSpace(email)
               && email.Contains("@")
               && email.Contains(".");
    }
}

Now the service can receive the validator from dependency injection:

public class UserRegistrationService
{
    private readonly IUserRegistrationValidator _validator;

    public UserRegistrationService(IUserRegistrationValidator validator)
    {
        _validator = validator;
    }

    public void RegisterUser(UserRegistrationRequest request)
    {
        _validator.Validate(request);

        Console.WriteLine("User registered successfully!");
    }
}

This improves testability because we can mock the validator in unit tests.

Step 5: Use Value Objects for Stronger Domain Rules

In a more domain-driven design approach, we can create value objects.

For example, instead of passing email as a plain string, we create an Email type.

public sealed record Email
{
    public string Value { get; }

    public Email(string value)
    {
        if (string.IsNullOrWhiteSpace(value) ||
            !value.Contains("@") ||
            !value.Contains("."))
        {
            throw new FormatException("Invalid email format.");
        }

        Value = value;
    }

    public override string ToString() => Value;
}

We can do the same for password.

public sealed record Password
{
    public string Value { get; }

    public Password(string value)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new ArgumentException("Password is required.", nameof(value));

        if (value.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(value));

        Value = value;
    }
}

Now the method can receive stronger types:

public void RegisterUser(string username, Password password, int age, Email email)
{
    ArgumentException.ThrowIfNullOrWhiteSpace(username);

    if (age is < 18 or > 120)
        throw new ArgumentOutOfRangeException(nameof(age), "Age must be between 18 and 120.");

    Console.WriteLine("User registered successfully!");
}

This is powerful because invalid email or password values cannot exist in the system.

The validation happens when the object is created.

Step 6: Use the Specification Pattern for Complex Rules

Sometimes validation rules become more complex.

For example, age validation may start simple:

if (age is < 18 or > 120)
    throw new ArgumentOutOfRangeException(nameof(age));

But later, the rule may change depending on the country, user type, subscription, product, or business scenario.

In that case, we can move the rule into a separate specification class.

The Specification Pattern allows us to define business rules as reusable objects.

public interface ISpecification<T>
{
    bool IsSatisfiedBy(T entity);
}

Now we can create a specific rule for age validation:

public class AgeSpecification : ISpecification<int>
{
    public bool IsSatisfiedBy(int age)
    {
        return age is >= 18 and <= 120;
    }
}

Then we can use it inside our validator:

public class UserRegistrationValidator
{
    private readonly ISpecification<int> _ageSpecification;

    public UserRegistrationValidator(ISpecification<int> ageSpecification)
    {
        _ageSpecification = ageSpecification;
    }

    public void Validate(UserRegistrationRequest request)
    {
        ArgumentNullException.ThrowIfNull(request);

        ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
        ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

        if (request.Password.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

        if (!_ageSpecification.IsSatisfiedBy(request.Age))
            throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

        if (!IsValidEmail(request.Email))
            throw new FormatException("Invalid email format.");
    }

    private static bool IsValidEmail(string email)
    {
        return !string.IsNullOrWhiteSpace(email)
               && email.Contains("@")
               && email.Contains(".");
    }
}

This gives us a cleaner and more flexible design.

If the age rule changes later, we do not need to modify the validator directly. We can create a new specification.

For example:

public class AdultUserSpecification : ISpecification<UserRegistrationRequest>
{
    public bool IsSatisfiedBy(UserRegistrationRequest request)
    {
        return request.Age >= 18;
    }
}

Or we can create a more complete business rule:

public class ValidUserRegistrationSpecification : ISpecification<UserRegistrationRequest>
{
    public bool IsSatisfiedBy(UserRegistrationRequest request)
    {
        return !string.IsNullOrWhiteSpace(request.Username)
               && !string.IsNullOrWhiteSpace(request.Password)
               && request.Password.Length >= 8
               && request.Age is >= 18 and <= 120
               && !string.IsNullOrWhiteSpace(request.Email)
               && request.Email.Contains("@")
               && request.Email.Contains(".");
    }
}

The Specification Pattern is useful when:

Business rules are complex.
Rules change often.
Rules must be reused in different places.
Rules need to be combined.
You want to avoid large if statements inside services.

For simple validation, a validator is usually enough.

For complex domain rules, the Specification Pattern gives you more flexibility.

Patterns used here:

Specification Pattern
Open/Closed Principle
Single Responsibility Principle

Step 7: Use Result Instead of Exceptions

Exceptions are fine for unexpected errors.

But in APIs, UI forms, and validation-heavy workflows, returning a result can sometimes be cleaner.

public record Result(bool Success, string Error)
{
    public static Result Ok() => new(true, string.Empty);

    public static Result Fail(string error) => new(false, error);
}

Now the registration method can return a result:

public Result RegisterUser(UserRegistrationRequest request)
{
    if (string.IsNullOrWhiteSpace(request.Username))
        return Result.Fail("Username is required.");

    if (string.IsNullOrWhiteSpace(request.Password))
        return Result.Fail("Password is required.");

    if (request.Password.Length < 8)
        return Result.Fail("Password must be at least 8 characters.");

    if (request.Age is < 18 or > 120)
        return Result.Fail("Age must be between 18 and 120.");

    if (!IsValidEmail(request.Email))
        return Result.Fail("Invalid email format.");

    return Result.Ok();
}

private static bool IsValidEmail(string email)
{
    return !string.IsNullOrWhiteSpace(email)
           && email.Contains("@")
           && email.Contains(".");
}

This is useful when you do not want validation failures to throw exceptions.

It is especially useful in:

APIs
Blazor forms
MVC forms
CQRS command handlers
UI validation flows

Final Recommended Version

For a real application, a clean structure would look like this:

public class UserRegistrationService
{
    private readonly IUserRegistrationValidator _validator;

    public UserRegistrationService(IUserRegistrationValidator validator)
    {
        _validator = validator;
    }

    public void RegisterUser(UserRegistrationRequest request)
    {
        _validator.Validate(request);

        Console.WriteLine("User registered successfully!");
    }
}

public interface IUserRegistrationValidator
{
    void Validate(UserRegistrationRequest request);
}

public class UserRegistrationValidator : IUserRegistrationValidator
{
    private readonly ISpecification<int> _ageSpecification;

    public UserRegistrationValidator(ISpecification<int> ageSpecification)
    {
        _ageSpecification = ageSpecification;
    }

    public void Validate(UserRegistrationRequest request)
    {
        ArgumentNullException.ThrowIfNull(request);

        ArgumentException.ThrowIfNullOrWhiteSpace(request.Username);
        ArgumentException.ThrowIfNullOrWhiteSpace(request.Password);

        if (request.Password.Length < 8)
            throw new ArgumentException("Password must be at least 8 characters.", nameof(request.Password));

        if (!_ageSpecification.IsSatisfiedBy(request.Age))
            throw new ArgumentOutOfRangeException(nameof(request.Age), "Age must be between 18 and 120.");

        if (!IsValidEmail(request.Email))
            throw new FormatException("Invalid email format.");
    }

    private static bool IsValidEmail(string email)
    {
        return !string.IsNullOrWhiteSpace(email)
               && email.Contains("@")
               && email.Contains(".");
    }
}

public interface ISpecification<T>
{
    bool IsSatisfiedBy(T entity);
}

public class AgeSpecification : ISpecification<int>
{
    public bool IsSatisfiedBy(int age)
    {
        return age is >= 18 and <= 120;
    }
}

public class UserRegistrationRequest
{
    public string Username { get; set; } = string.Empty;
    public string Password { get; set; } = string.Empty;
    public int Age { get; set; }
    public string Email { get; set; } = string.Empty;
}

Summary

Refactoring Technique	What It Improves
Guard Clauses	Makes validation clearer
Extract Method	Makes code easier to read
DTO	Groups related input data
Validator Pattern	Separates validation from business logic
Dependency Injection	Improves testability
Value Objects	Protects domain integrity
Specification Pattern	Makes complex rules reusable
Open/Closed Principle	Allows adding new rules without changing existing code
Result Pattern	Works well for APIs and UI flows
Single Responsibility Principle	Keeps classes focused

Conclusion

The best refactoring is not always the most advanced one.

Start simple.
First, use guard clauses.
Then extract repeated logic into methods.
After that, move validation into its own class.
When the domain becomes more important, consider value objects.
When business rules become more complex, consider the Specification Pattern.

And when working with APIs or UI forms, consider returning a result instead of throwing exceptions for expected validation failures.

A good refactor should make the code easier to understand without making it unnecessarily complicated.

The Rule Pattern in C#

Spyros Ponaris — Tue, 28 Apr 2026 09:12:19 +0000

The Rule Pattern in C#, and Why It Works So Well with the Result Pattern

Business rules have a bad habit of spreading everywhere. A little validation in a command handler, another check in a service, one more if in the entity, and before long the real policy of the system is buried under conditionals. The Rule pattern solves that by giving each business rule its own object and a clear name. In practice, this style is very close to what Fowler describes as the Specification pattern, especially when you start combining rules with AND, OR, and NOT. (martinfowler.com)

At the same time, many of us do not want to throw exceptions for expected business failures. That is where the Result pattern fits naturally. Instead of throwing, we return a success or failure object that makes the outcome explicit to the caller. This is a common way to model expected failures in application code. (Enterprise Craftsmanship)

Put those two together, and the design becomes very clean:

Rule pattern decides whether something is allowed
Result pattern communicates the outcome back to the caller

That combination is not a formal framework rule, but it is a very practical pairing. One expresses business intent, the other expresses application flow. (martinfowler.com)

So, what is the Rule pattern?

The Rule pattern wraps one business condition in one class.

Instead of writing this:

if (order.TotalAmount < 50m)
    return Result.Failure("Order must be at least 50.");

if (!order.Customer.IsVerified)
    return Result.Failure("Customer must be verified.");

if (order.Customer.CurrentBalance + order.TotalAmount > order.Customer.CreditLimit)
    return Result.Failure("Credit limit exceeded.");

You move each rule into its own object:

public interface IRule<T>
{
    bool IsSatisfiedBy(T entity);
    string ErrorMessage { get; }
}

That interface is tiny, but it already gives you two important things: a way to evaluate a business rule, and a way to describe why it failed.

This is the heart of the pattern. A rule becomes a first-class concept in the codebase instead of just another anonymous if. Fowler’s Specification write-up is essentially about doing exactly this, making business criteria explicit and composable. (martinfowler.com)

A base class makes rules composable

Your BaseRule<T> adds the nice part:

public abstract class BaseRule<T> : IRule<T>
{
    public abstract bool IsSatisfiedBy(T entity);
    public abstract string ErrorMessage { get; }

    public BaseRule<T> And(IRule<T> other) => new AndRule<T>(this, other);
    public BaseRule<T> Or(IRule<T> other) => new OrRule<T>(this, other);
    public BaseRule<T> Not() => new NotRule<T>(this);
}

Now a rule is no longer just a check. It is a building block. You can combine simple rules into richer business policies, which is one of the main strengths of Specification-style modeling. (martinfowler.com)

That means your code can start reading more like the business itself:

var rule = new OrderMinimumAmountRule(50m)
    .And(new CustomerVerifiedRule())
    .And(new CreditLimitRule());

This is much easier to understand than a long block of unrelated conditions.

The supporting rule combinators

Your AndRule<T> is straightforward:

public class AndRule<T> : BaseRule<T>
{
    private readonly IRule<T> _left, _right;
    public AndRule(IRule<T> left, IRule<T> right) => (_left, _right) = (left, right);

    public override bool IsSatisfiedBy(T entity) =>
        _left.IsSatisfiedBy(entity) && _right.IsSatisfiedBy(entity);

    public override string ErrorMessage =>
        _left.ErrorMessage + "; " + _right.ErrorMessage;
}

This says both rules must pass.

Your OrRule<T> says at least one rule must pass:

public class OrRule<T> : BaseRule<T>
{
    private readonly IRule<T> _left, _right;
    public OrRule(IRule<T> left, IRule<T> right) => (_left, _right) = (left, right);

    public override bool IsSatisfiedBy(T entity) =>
        _left.IsSatisfiedBy(entity) || _right.IsSatisfiedBy(entity);

    public override string ErrorMessage => _left.ErrorMessage;
}

And NotRule<T> flips the result:

public class NotRule<T> : BaseRule<T>
{
    private readonly IRule<T> _inner;
    public NotRule(IRule<T> inner) => _inner = inner;

    public override bool IsSatisfiedBy(T entity) => !_inner.IsSatisfiedBy(entity);
    public override string ErrorMessage => $"Negated: {_inner.ErrorMessage}";
}

Conceptually, this is exactly the kind of composite behavior Fowler describes for specifications. (martinfowler.com)

A real example, order placement

Let’s say your domain has three simple rules:

The order must be at least 50
The customer must be verified
The customer must stay within their credit limit

Those rules become very small classes:

public sealed class OrderMinimumAmountRule : BaseRule<Order>
{
    private readonly decimal _minimumAmount;

    public OrderMinimumAmountRule(decimal minimumAmount)
    {
        _minimumAmount = minimumAmount;
    }

    public override bool IsSatisfiedBy(Order order)
        => order.TotalAmount >= _minimumAmount;

    public override string ErrorMessage
        => $"Order must be at least {_minimumAmount:C}.";
}

public sealed class CustomerVerifiedRule : BaseRule<Order>
{
    public override bool IsSatisfiedBy(Order order)
        => order.Customer.IsVerified;

    public override string ErrorMessage
        => "Customer must be verified.";
}

public sealed class CreditLimitRule : BaseRule<Order>
{
    public override bool IsSatisfiedBy(Order order)
        => order.Customer.CurrentBalance + order.TotalAmount <= order.Customer.CreditLimit;

    public override string ErrorMessage
        => "Credit limit exceeded.";
}

Each class has one job. Each class is easy to test. Each class has a business name, not a technical name. That clarity is one of the biggest wins of this pattern. (martinfowler.com)

Where the Result pattern enters the picture

A rule can tell us whether the order is valid. But something still has to return that outcome to the caller.

That is where Result becomes useful.

Your handler already shows the idea well:

public class PlaceOrderCommandHandler(
    IOrderRepository orders,
    ICustomerRepository customers) : ICommandHandler<PlaceOrderCommand>
{
    private readonly IOrderRepository _orders = orders;
    private readonly ICustomerRepository _customers = customers;

    public async Task<Result> Handle(PlaceOrderCommand command, CancellationToken cancellationToken)
    {
        var customer = await _customers.GetByIdAsync(command.CustomerId, cancellationToken);
        if (customer is null)
            return Result.Failure("Customer not found.");

        var lines = command.Lines.Select(l => OrderLine.Create(l.ProductId, l.Quantity, l.UnitPrice));
        var order = Order.Draft(customer, lines);

        var rule = new OrderMinimumAmountRule(50m)
            .And(new CustomerVerifiedRule())
            .And(new CreditLimitRule());

        if (!rule.IsSatisfiedBy(order))
            return Result.Failure(rule.ErrorMessage);

        order.Place();
        await _orders.AddAsync(order, cancellationToken);

        return Result.Success();
    }
}

This reads nicely because the responsibilities are split cleanly. The rule answers, “Is this order allowed?” The result answers, “What happened when we tried?” That aligns well with Result-based error handling, where expected failures are returned explicitly instead of being hidden behind exceptions. (Enterprise Craftsmanship)

Why these two patterns fit together so naturally

The Rule pattern is about decision making.

The Result pattern is about outcome modeling.

That distinction matters.

A rule does not need to know anything about HTTP, APIs, UI messages, or pipeline behavior. It just checks business truth. The application layer then takes that truth and wraps it in a Result, which can be returned to a controller, endpoint, or caller in a predictable way. That separation lines up well with layered DDD guidance, where the application layer coordinates work and the domain layer holds the business logic. (Microsoft Learn)

A small refinement that makes the pairing even better

One nice improvement is to teach rules how to convert themselves into a Result.

For example:

public static class RuleExtensions
{
    public static Result ToResult<T>(this IRule<T> rule, T entity)
    {
        return rule.IsSatisfiedBy(entity)
            ? Result.Success()
            : Result.Failure(rule.ErrorMessage);
    }
}

Then the handler becomes even cleaner:

public async Task<Result> Handle(PlaceOrderCommand command, CancellationToken cancellationToken)
{
    var customer = await _customers.GetByIdAsync(command.CustomerId, cancellationToken);
    if (customer is null)
        return Result.Failure("Customer not found.");

    var lines = command.Lines.Select(l => OrderLine.Create(l.ProductId, l.Quantity, l.UnitPrice));
    var order = Order.Draft(customer, lines);

    var rule = new OrderMinimumAmountRule(50m)
        .And(new CustomerVerifiedRule())
        .And(new CreditLimitRule());

    var validationResult = rule.ToResult(order);
    if (validationResult.IsFailure)
        return validationResult;

    order.Place();
    await _orders.AddAsync(order, cancellationToken);

    return Result.Success();
}

Now the handler is just orchestration, which is exactly what many DDD and CQRS guides recommend for the application layer. (Microsoft Learn)

One important DDD note

For a tutorial, putting the rule composition in the command handler is totally fine because it makes the pattern easy to see.

In a richer domain model, though, the most important invariants often belong inside the aggregate itself. Microsoft’s DDD guidance is very explicit here: aggregates are responsible for enforcing invariants across state changes, and application code should not become the real guardian of business consistency. (Microsoft Learn)

So a more domain-driven version could look like this:

public Result Place()
{
    var rule = new OrderMinimumAmountRule(50m)
        .And(new CustomerVerifiedRule())
        .And(new CreditLimitRule());

    if (!rule.IsSatisfiedBy(this))
        return Result.Failure(rule.ErrorMessage);

    Status = OrderStatus.Placed;
    return Result.Success();
}

Then the handler becomes:

public async Task<Result> Handle(PlaceOrderCommand command, CancellationToken cancellationToken)
{
    var customer = await _customers.GetByIdAsync(command.CustomerId, cancellationToken);
    if (customer is null)
        return Result.Failure("Customer not found.");

    var lines = command.Lines.Select(l => OrderLine.Create(l.ProductId, l.Quantity, l.UnitPrice));
    var order = Order.Draft(customer, lines);

    var result = order.Place();
    if (result.IsFailure)
        return result;

    await _orders.AddAsync(order, cancellationToken);
    return Result.Success();
}

This version is often closer to true DDD, because the order protects its own validity. (Microsoft Learn)

One honest limitation in the current implementation

Your example is great for teaching, but there is one thing worth mentioning in the article so readers do not copy it blindly.

Right now, AndRule.ErrorMessage always concatenates both messages:

public override string ErrorMessage =>
    _left.ErrorMessage + "; " + _right.ErrorMessage;

That means it can return messages for rules that actually passed.

And OrRule.ErrorMessage always returns the left message:

public override string ErrorMessage => _left.ErrorMessage;

So for production code, many teams move toward one of these options:

evaluate all broken rules and return a list
return a richer Result with structured errors
expose something like IReadOnlyList<string> GetErrors(T entity)

That kind of richer error modeling fits especially well with Result-based application flows. (Enterprise Craftsmanship)

A simple improvement could look like this:

public interface IRule<T>
{
    bool IsSatisfiedBy(T entity);
    IEnumerable<string> GetErrors(T entity);
}

But for a beginner-friendly tutorial, your current shape is still excellent because it keeps the idea small and easy to follow.

Final takeaway

The Rule pattern is a clean way to model business rules as reusable objects. Instead of burying domain knowledge inside scattered conditionals, you give each rule a name, a purpose, and a place in the model. When you add composition with AND, OR, and NOT, the code starts to read much closer to the business language itself. (martinfowler.com)

The Result pattern complements that perfectly. Rules decide whether an operation is allowed, while Results communicate whether the operation succeeded or failed in a clear and explicit way. Used together, they produce application code that is easier to read, easier to test, and much harder to misunderstand. (Enterprise Craftsmanship)

References

Martin Fowler, Specifications. (martinfowler.com)

Microsoft Learn, Designing validations in the domain model layer. (Microsoft Learn)

Microsoft Learn, Implementing the microservice application layer using the Web API. (Microsoft Learn)

Microsoft Learn, Implementing a microservice domain model with .NET. (Microsoft Learn)

Vladimir Khorikov, Specification Pattern vs Always-Valid Domain Model. (Enterprise Craftsmanship)

Vladimir Khorikov, Error handling: Exception or Result? (Enterprise Craftsmanship)

Milan Jovanović, Functional Error Handling in .NET With the Result Pattern. (Milan Jovanović)

I can also turn this into a LinkedIn/dev.to version with a stronger hook and shorter paragraphs.

Building a Clean Master-Detail App with Blazor Server, MudBlazor, and EF Core

Spyros Ponaris — Thu, 26 Mar 2026 11:09:59 +0000

Building a Clean Master-Detail App with Blazor Server, MudBlazor, and EF Core

When building business applications, one of the most common requirements is a master-detail workflow. Orders and order items are a perfect example.

You need a clean list view, a reliable detail page, inline editing, validation, filtering, and a structure that can grow without becoming messy.

That is exactly what BlazorOrderApp is designed to demonstrate.

This application is a production-ready Blazor Server solution built with MudBlazor for the UI, EF Core with SQL Server for persistence, and a clean architecture that separates concerns across Domain, Application, Infrastructure, and Web layers.

Instead of placing everything in pages or code-behind files, the app keeps business rules, data access, validation, and UI responsibilities clearly divided.

At the core of the app is a classic master-detail pattern. The Orders.razor page acts as the master list, giving users filtering, search, pagination, and a structured overview of all orders. The OrderDetail.razor page handles the detail side, where users can inspect customer information, manage order items, and update order status in a focused way.

A big strength of this project is its use of the Repository and Specification patterns. The repository layer keeps EF Core logic centralized and testable, while specifications allow queries to be defined as reusable objects instead of scattered LINQ expressions. This makes filtering, paging, and retrieving complex data much easier to maintain over time.

Validation is handled with FluentValidation, which keeps rules explicit and easy to evolve as business needs grow. Combined with MudBlazor dialogs for create, edit, and delete operations, the result is a workflow that feels polished and user-friendly without sacrificing structure behind the scenes.

Overall, BlazorOrderApp is a strong example of how to build a modern internal business application in Blazor. It shows that you can create a clean, scalable CRUD system with a professional UI, solid architecture, and maintainable backend patterns, all within the .NET ecosystem.

Source code : https://github.com/stevsharp/BlazorOrderApp

Building a Blazor Form with the Command Pattern and Undo

Spyros Ponaris — Fri, 20 Mar 2026 08:39:06 +0000

Building a Blazor Form with the Command Pattern and Undo

In a typical Blazor form, inputs update the model directly. That is simple and works fine for basic CRUD screens, but it starts to feel limiting when you want more control over how changes happen, especially if you want undo support.

That is where the Command Pattern becomes useful.

Instead of letting the form change the model directly, each meaningful edit is wrapped inside a command object. That command is responsible for two things: applying the change and reversing it later if the user clicks Undo.

In other words, the form is no longer just changing values. It is recording actions.

The basic idea

In this approach, every field change becomes its own small object.

So if the user changes FirstName, that is one command.
If they change Email, that is another command.
If they toggle IsActive, that is a third command.

Those commands are stored in a stack, and Undo simply reverses the most recent one.

The core interface is very small:

public interface IUndoableCommand
{
    string Name { get; }
    void Execute();
    void Undo();
}

This keeps the pattern easy to understand. Every command knows what it does, and how to undo it.

The undo manager

To store the history of changes, we use a simple UndoManager:

public sealed class UndoManager
{
    private readonly Stack<IUndoableCommand> _undoStack = new();

    public bool CanUndo => _undoStack.Count > 0;

    public void Execute(IUndoableCommand command)
    {
        command.Execute();
        _undoStack.Push(command);
    }

    public void Undo()
    {
        if (_undoStack.Count == 0)
            return;

        var command = _undoStack.Pop();
        command.Undo();
    }

    public void Clear()
    {
        _undoStack.Clear();
    }
}

The idea is straightforward. When a command runs, it is pushed onto the stack. When the user clicks Undo, the last command is popped and reversed.

A reusable command for field changes

For a form, a generic SetPropertyCommand is often enough to get started.

public sealed class SetPropertyCommand<TModel, TValue> : IUndoableCommand
{
    private readonly TModel _model;
    private readonly Func<TModel, TValue> _getter;
    private readonly Action<TModel, TValue> _setter;
    private readonly TValue _newValue;

    private TValue? _oldValue;
    private bool _captured;

    public string Name { get; }

    public SetPropertyCommand(
        string name,
        TModel model,
        Func<TModel, TValue> getter,
        Action<TModel, TValue> setter,
        TValue newValue)
    {
        Name = name;
        _model = model;
        _getter = getter;
        _setter = setter;
        _newValue = newValue;
    }

    public void Execute()
    {
        if (!_captured)
        {
            _oldValue = _getter(_model);
            _captured = true;
        }

        _setter(_model, _newValue);
    }

    public void Undo()
    {
        if (!_captured)
            return;

        _setter(_model, _oldValue!);
    }
}

What makes this useful is that it does not permanently track the whole form. It only represents one change at a time.

That is an important distinction.

SetPropertyCommand is not a background tracker watching every field. It is more like a history entry. One command instance represents one action, like:

change FirstName from "Maria" to "Anna"

change Email from "old@mail.com" to "new@mail.com"

change IsActive from false to true

Example from the form

In the Blazor form, a field change is turned into a command like this:

ExecutePropertyCommand(
    "Change First Name",
    m => m.FirstName,
    (m, v) => m.FirstName = v,
    value ?? string.Empty,
    nameof(CustomerEditModel.FirstName));

This is a nice example because it shows exactly what the command needs:

how to read the property
how to set the property
what the new value is
which field changed

Then inside ExecutePropertyCommand, the actual command is created:

var command = new SetPropertyCommand<CustomerEditModel, TValue>(
    name,
    _model,
    getter,
    setter,
    newValue);

And then executed through the undo manager:

_undoManager.Execute(command);

Why this feels cleaner

This approach separates form editing from raw property assignment.

Without the pattern, a form usually does this:

_model.FirstName = value;

That works, but the change is gone the moment it happens. There is no history, no reversible action, and no good place to add undo logic later.

With the Command Pattern, the change becomes a first-class action. That makes the form behavior more predictable, easier to test, and easier to extend.

Why Save should stay separate

One important design choice is keeping Save outside the command stack.

Undo should reverse form edits, not database persistence.

That is why Save is better as a separate action:

private Task SaveAsync()
{
    ValidateModel();

    if (!_editContext.Validate())
        return Task.CompletedTask;

    // persist here

    _undoManager.Clear();
    RefreshPreview();

    return Task.CompletedTask;

This keeps responsibilities clear:

commands handle reversible UI changes

Save persists the current state

Trying to make Save itself a command usually creates confusion, because undoing a database write is a completely different problem.

A good fit for Blazor forms

This pattern is especially useful when a form has:

multiple editable fields
toggles or switches
add/remove actions
sections that can be reset
a real requirement for undo

The Command Pattern gives you a clean way to implement it without scattering logic all over the component.

Final thought

The most helpful way to think about this is not that the command is “tracking fields.” It is not.

What it is really doing is turning every meaningful edit into a small object that remembers what changed, so the form can step backward when needed.

That is what makes undo possible, and that is what makes the pattern useful in a Blazor form.

Source Code : https://github.com/stevsharp/BlazorCommandLab

ETag in ASP.NET Core + EF Core, caching reads and protecting updates

Spyros Ponaris — Tue, 03 Mar 2026 14:01:21 +0000

ETag in ASP.NET Core + EF Core, a practical guide for real APIs

ETag is one of those features that looks “extra” until you ship an app that people actually use. Then you see the same problems everywhere:

The UI keeps reloading the same data even when nothing changed.
Two users edit the same record, the second save silently overwrites the first.
Mobile clients waste bandwidth and feel slow.

ETag solves these in a clean HTTP-native way.

What an ETag really is

An ETag is a short string that represents the current version of a resource.

When you return a resource, you also return an ETag header:

ETag: "abc123"

Later, clients can use it in two ways.

1) Fast reads (caching style)

Client sends:

If-None-Match: "abc123"

If the resource is unchanged, the server returns:

304 Not Modified (no body)

2) Safe writes (optimistic concurrency style)

Client sends on update:

If-Match: "abc123"

If the resource changed since the client last fetched it, the server returns:

412 Precondition Failed

If the client did not send If-Match at all, best practice is:

428 Precondition Required

This is exactly what your helper is designed to do.

public static class ETagHelper
{
    public static void SetETag(HttpResponse response, string etag)
    {
        response.Headers.ETag         = $"\"{etag}\"";
        response.Headers.CacheControl = "private, must-revalidate";
    }

    public static bool IsNotModified(HttpRequest request, string currentETag)
    {
        var clientETag = request.Headers.IfNoneMatch.ToString().Trim('"');
        return !string.IsNullOrWhiteSpace(clientETag) && clientETag == currentETag;
    }

    public static void ValidateIfMatch(HttpRequest request, string currentETag)
    {
        var ifMatch = request.Headers.IfMatch.ToString();
        if (string.IsNullOrWhiteSpace(ifMatch))
            throw new PreconditionRequiredException(
                "If-Match header is required for update operations.");

        var clientETag = ifMatch.Trim('"');
        if (clientETag != "*" && clientETag != currentETag)
            throw new PreconditionFailedException(
                "The resource has been modified since you last retrieved it. " +
                "Fetch the latest version (including its ETag) and retry.");
    }
}

Why this matters in CRUD apps

Where it helps a lot

Details screens: /products/{id}, /orders/{id}
Admin panels: multiple users editing same entity
Polling dashboards: refresh every 10 seconds without downloading unchanged payloads
Mobile apps: reduce data usage, speed up screens
Any “edit then save” flow: prevents “last write wins” accidents

What it does not magically solve

Business conflicts (two users legitimately editing different fields), you still need merge logic if you want automatic merging.
List endpoints are trickier, ETag for lists needs careful versioning per query.

Your helper, what it enforces

You already have a good ETag helper:

SetETag sets both ETag and Cache-Control: private, must-revalidate
IsNotModified compares the client ETag to the current one
ValidateIfMatch enforces If-Match on update operations, rejects stale versions, supports If-Match: *

About the Cache-Control you set:

private means shared caches should not store it (good for user-specific data).
must-revalidate means if a cache has a stale copy, it must check with the server before using it.

This is a sensible default for most authenticated apps.

Picking the ETag value in EF Core

The best ETag is one that changes whenever the record changes.

Option A (recommended): RowVersion concurrency token

This is the cleanest for EF Core, because it doubles as real concurrency control.

using System.ComponentModel.DataAnnotations;

public sealed class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public decimal Price { get; set; }

    [Timestamp]
    public byte[] RowVersion { get; set; } = [];
}

Then convert RowVersion to an ETag string:

static string ToETag(byte[] rowVersion) => Convert.ToBase64String(rowVersion);
static byte[] FromETag(string etag) => Convert.FromBase64String(etag);

Option B: UpdatedAt timestamp (works, but weaker)

If you do not want RowVersion, you can use UpdatedAt and make ETag from it, for example ticks. It works, but you must guarantee UpdatedAt changes on every update, including “no-op” updates if you allow them.

RowVersion is usually safer.

Read endpoint (GET), add “more to read” behavior

The core flow is:

Load entity (AsNoTracking for GET)
Compute ETag
If client already has it, return 304
Else return 200 with ETag

[HttpGet("{id:int}")]
public async Task<IActionResult> Get(int id, CancellationToken ct)
{
    var product = await db.Products
        .AsNoTracking()
        .FirstOrDefaultAsync(x => x.Id == id, ct);

    if (product is null) return NotFound();

    var currentETag = ToETag(product.RowVersion);

    if (ETagHelper.IsNotModified(Request, currentETag))
        return StatusCode(StatusCodes.Status304NotModified);

    ETagHelper.SetETag(Response, currentETag);

    return Ok(new { product.Id, product.Name, product.Price });
}

What clients gain on GET

If nothing changed, they get a fast 304 and skip JSON parsing.
If changed, they get the new body and a new ETag.

Update endpoints (PUT, PATCH), protect the record

PUT example

Your logic is:

Load entity
Compute current ETag
Validate If-Match
Apply changes
Set EF Core OriginalValue so SaveChanges performs concurrency check
Save, return updated entity plus new ETag

[HttpPut("{id:int}")]
public async Task<IActionResult> Update(int id, UpdateProductDto dto, CancellationToken ct)
{
    var product = await db.Products.FirstOrDefaultAsync(x => x.Id == id, ct);
    if (product is null) return NotFound();

    var currentETag = ToETag(product.RowVersion);
    ETagHelper.ValidateIfMatch(Request, currentETag);

    var clientETag = Request.Headers.IfMatch.ToString().Trim('"');

    product.Name = dto.Name;
    product.Price = dto.Price;

    if (clientETag != "*")
        db.Entry(product).Property(x => x.RowVersion).OriginalValue = FromETag(clientETag);

    try
    {
        await db.SaveChangesAsync(ct);
    }
    catch (DbUpdateConcurrencyException)
    {
        throw new PreconditionFailedException(
            "The resource has been modified since you last retrieved it. Fetch the latest version and retry.");
    }

    var newETag = ToETag(product.RowVersion);
    ETagHelper.SetETag(Response, newETag);

    return Ok(new { product.Id, product.Name, product.Price });
}

PATCH

Same idea, just update selected fields. ETag logic stays identical.

DELETE with If-Match (highly recommended)

Deletes are also “writes”, they can also overwrite someone else’s change, especially if the UI shows “Delete” after viewing old data.

[HttpDelete("{id:int}")]
public async Task<IActionResult> Delete(int id, CancellationToken ct)
{
    var product = await db.Products.FirstOrDefaultAsync(x => x.Id == id, ct);
    if (product is null) return NotFound();

    var currentETag = ToETag(product.RowVersion);
    ETagHelper.ValidateIfMatch(Request, currentETag);

    db.Products.Remove(product);

    try
    {
        await db.SaveChangesAsync(ct);
    }
    catch (DbUpdateConcurrencyException)
    {
        throw new PreconditionFailedException(
            "The resource has been modified since you last retrieved it. Fetch the latest version and retry.");
    }

    return NoContent();
}

Proper HTTP codes, make your API feel “professional”

You already throw:

PreconditionRequiredException for missing If-Match (428)
PreconditionFailedException for stale ETag (412)

Add an exception filter (or middleware) so this is consistent across the API.

public sealed class PreconditionRequiredException : Exception
{
    public PreconditionRequiredException(string message) : base(message) { }
}

public sealed class PreconditionFailedException : Exception
{
    public PreconditionFailedException(string message) : base(message) { }
}

public sealed class HttpPreconditionExceptionFilter : IExceptionFilter
{
    public void OnException(ExceptionContext context)
    {
        if (context.Exception is PreconditionRequiredException ex428)
        {
            context.Result = new ObjectResult(new { error = ex428.Message })
            { StatusCode = StatusCodes.Status428PreconditionRequired };
            context.ExceptionHandled = true;
            return;
        }

        if (context.Exception is PreconditionFailedException ex412)
        {
            context.Result = new ObjectResult(new { error = ex412.Message })
            { StatusCode = StatusCodes.Status412PreconditionFailed };
            context.ExceptionHandled = true;
        }
    }
}

builder.Services.AddControllers(o => o.Filters.Add<HttpPreconditionExceptionFilter>());

Client examples you can paste in docs

curl demo (GET, then conditional GET)

curl -i https://localhost:5001/api/products/10
# copy the ETag header value

curl -i https://localhost:5001/api/products/10 \
  -H 'If-None-Match: "PASTE_ETAG_HERE"'
# 304 if unchanged

curl demo (safe update)

curl -i -X PUT https://localhost:5001/api/products/10 \
  -H 'Content-Type: application/json' \
  -H 'If-Match: "PASTE_ETAG_HERE"' \
  -d '{"name":"New Name","price":9.99}'

If someone else updated it, you get 412 and you know you must refetch.

Lists and search endpoints, how to think about them

ETag on /api/products/10 is easy.

ETag on /api/products?category=1&page=2&sort=price is harder, because the “resource” is the result set, not one row.

If you still want it, the ETag must depend on:

Query parameters
The set of returned IDs
A version indicator for each item (or a global “catalog version”)

A practical approach is to start with ETag only on single-resource endpoints, then add list ETags later when you have a clear versioning strategy.

Common pitfalls (quick checklist)

Do not generate ETag from “now”. It must represent the resource version, not the response time.
Always return the new ETag after successful updates, so clients can continue editing safely.
For GET, use AsNoTracking() to keep it cheap.
Enforce If-Match for PUT, PATCH, DELETE, otherwise concurrency protection is optional and clients will forget it.
If your API is user-specific, private cache-control is the right call (your helper already does it).

Closing

With your ETagHelper plus EF Core concurrency, you get:

Faster reads via If-None-Match and 304 Not Modified
Safer writes via If-Match, 428 when missing, 412 when stale
EF Core protects the database update with real optimistic concurrency

When IDbContextFactory enters the chat, and what it actually fixes.

Spyros Ponaris — Mon, 16 Feb 2026 09:49:55 +0000

When `IDbContextFactory` enters the chat, and what it actually fixes

Most EF Core examples use a scoped DbContext. In a normal Web API request, that’s fine, the request ends, the context is disposed.

Then you build Blazor Server.

A Blazor Server circuit can stay alive for a long time, minutes or hours. If your DbContext is scoped, it can also stay alive that long. That’s when things start to break in annoying ways.

What problems show up

1) “A second operation was started on this context…”
DbContext is not thread-safe. In Blazor Server it’s easy to trigger overlapping work (clicks, timers, loading states). If two queries happen at the same time on the same context, you get this error.

2) Tracking bloat
A long-lived context keeps tracking entities. Over time:

memory grows
queries can feel slower
SaveChanges can get heavy
you hit “already being tracked” errors

3) Stale or confusing data
Because the context tracks objects, you can end up reusing old instances without realizing it, the UI feels out of sync.

What `IDbContextFactory` changes

It gives you a fresh DbContext per operation.

create context
run the query or command
dispose the context

So each click, each load, each action gets its own clean context. No shared state, no concurrency fights, no growing tracker.

When to use it

Use IDbContextFactory when you have:

Blazor Server
background jobs or hosted services
timers, polling, signalR style event flows
any parallel DB work

In simple controller-per-request apps, scoped DbContext is still perfectly fine.

The takeaway

IDbContextFactory is not a “nice to have”, it’s the safer default when your app is long-lived and event-driven. It prevents a whole category of EF Core bugs before they happen.

Source Code :

https://github.com/stevsharp/BlazorFactoryDemo

ASP.NET Core Custom Logger — Save Logs to Database (SQL)

Spyros Ponaris — Fri, 30 Jan 2026 09:32:59 +0000

ASP.NET Core already gives you solid logging out of the box, and if you want richer sinks and structured logs, Serilog is a common choice.

But sometimes you cannot use a ready made sink, because the company already has a legacy logging table with a fixed schema. In that case, you build a custom database logger that writes into that table.

This tutorial includes:

Database table
Logger options
Custom logger
Logger provider
Background queue (Channel)
Dapper SQL insert
Registration in Program.cs
Usage example

1️⃣ Create the SQL table

CREATE TABLE dbo.AppLogs
(
    LogId     BIGINT IDENTITY PRIMARY KEY,
    Ts        DATETIME2(3) NOT NULL,
    Level     NVARCHAR(20) NOT NULL,
    Category  NVARCHAR(200) NOT NULL,
    TraceId   NVARCHAR(64) NULL,
    Message   NVARCHAR(MAX) NOT NULL,
    Exception NVARCHAR(MAX) NULL,
    Scopes    NVARCHAR(MAX) NULL
);

CREATE INDEX IX_AppLogs_Ts    ON dbo.AppLogs(Ts);
CREATE INDEX IX_AppLogs_Level ON dbo.AppLogs(Level);

2️⃣ Add NuGet packages

bash dotnet add package Dapper dotnet add package Microsoft.Data.SqlClient

3️⃣ Logger options

`csharp
public sealed class DbLogOptions
{
public string ConnectionString { get; set; } = string.Empty;
public LogLevel MinLevel { get; set; } = LogLevel.Information;

// Max number of log entries waiting in memory
public int MaxQueue { get; set; } = 5000;

}
`

4️⃣ Log entry model

csharp public sealed class DbLogEntry { public DateTime Ts { get; set; } public string Level { get; set; } = ""; public string Category { get; set; } = ""; public string? TraceId { get; set; } public string Message { get; set; } = ""; public string? Exception { get; set; } public string? Scopes { get; set; } }

5️⃣ Custom database logger

`csharp
using System.Diagnostics;
using System.Text.Json;
using System.Threading.Channels;
using Microsoft.Extensions.Logging;

public sealed class DbLogger : ILogger
{
private readonly string _category;
private readonly DbLogOptions _options;
private readonly Channel _channel;
private readonly IExternalScopeProvider? _scopeProvider;

public DbLogger(
    string category,
    DbLogOptions options,
    Channel<DbLogEntry> channel,
    IExternalScopeProvider? scopeProvider)
{
    _category = category;
    _options = options;
    _channel = channel;
    _scopeProvider = scopeProvider;
}

public IDisposable BeginScope<TState>(TState state) =>
    _scopeProvider?.Push(state) ?? NullScope.Instance;

public bool IsEnabled(LogLevel logLevel) => logLevel >= _options.MinLevel;

public void Log<TState>(
    LogLevel logLevel,
    EventId eventId,
    TState state,
    Exception? exception,
    Func<TState, Exception?, string> formatter)
{
    if (!IsEnabled(logLevel)) return;
    if (formatter is null) return;

    var traceId = Activity.Current?.TraceId.ToString();

    string? scopesJson = null;
    if (_scopeProvider is not null)
    {
        var scopes = new List<object?>();
        _scopeProvider.ForEachScope((s, list) => list.Add(s), scopes);

        if (scopes.Count > 0)
            scopesJson = JsonSerializer.Serialize(scopes);
    }

    var entry = new DbLogEntry
    {
        Ts = DateTime.UtcNow,
        Level = logLevel.ToString(),
        Category = _category,
        TraceId = traceId,
        Message = formatter(state, exception),
        Exception = exception?.ToString(),
        Scopes = scopesJson
    };

    // If queue is full, this returns false and the log is dropped
    _ = _channel.Writer.TryWrite(entry);
}

private sealed class NullScope : IDisposable
{
    public static readonly NullScope Instance = new();
    public void Dispose() { }
}

}
`

6️⃣ Logger provider (writes to SQL using Dapper)

This provider uses a bounded channel and a single background reader so request threads never block on SQL.

`csharp
using System.Threading.Channels;
using Dapper;
using Microsoft.Data.SqlClient;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;

public sealed class DbLoggerProvider : ILoggerProvider, ISupportExternalScope
{
private readonly DbLogOptions _options;
private readonly Channel _channel;
private readonly CancellationTokenSource _cts = new();
private IExternalScopeProvider? _scopeProvider;

public DbLoggerProvider(IOptions<DbLogOptions> options)
{
    _options = options.Value;

    var channelOptions = new BoundedChannelOptions(_options.MaxQueue)
    {
        SingleReader = true,
        SingleWriter = false,
        FullMode = BoundedChannelFullMode.DropOldest
    };

    _channel = Channel.CreateBounded<DbLogEntry>(channelOptions);

    _ = Task.Run(ProcessQueueAsync);
}

public ILogger CreateLogger(string categoryName) =>
    new DbLogger(categoryName, _options, _channel, _scopeProvider);

public void SetScopeProvider(IExternalScopeProvider scopeProvider) =>
    _scopeProvider = scopeProvider;

public void Dispose()
{
    _cts.Cancel();
    _channel.Writer.TryComplete();
    _cts.Dispose();
}

private async Task ProcessQueueAsync()
{
    const string sql = @"

INSERT INTO dbo.AppLogs (Ts, Level, Category, TraceId, Message, Exception, Scopes)
VALUES (@ts, @Level, @category, @TraceId, @message, @exception, @Scopes);";

    try
    {
        while (await _channel.Reader.WaitToReadAsync(_cts.Token))
        {
            while (_channel.Reader.TryRead(out var entry))
            {
                await using var conn = new SqlConnection(_options.ConnectionString);
                await conn.ExecuteAsync(sql, entry);
            }
        }
    }
    catch (OperationCanceledException)
    {
        // graceful shutdown
    }
}

}
`

7️⃣ Add registration extension

`csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

public static class DbLoggerExtensions
{
public static ILoggingBuilder AddDbLogger(
this ILoggingBuilder builder,
Action configure)
{
builder.Services.Configure(configure);
builder.Services.AddSingleton();
return builder;
}
}
`

8️⃣ Register in Program.cs

`csharp
var builder = WebApplication.CreateBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddConsole();

builder.Logging.AddDbLogger(options =>
{
options.ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection")!;
options.MinLevel = LogLevel.Information;
options.MaxQueue = 5000;
});

var app = builder.Build();

app.MapGet("/test", (ILogger logger) =>
{
logger.LogInformation("Hello from DB Logger");
logger.LogError(new Exception("Test"), "Something failed");
return Results.Ok("OK");
});

app.Run();
`

Why we used Channels in the DB logger

Your logger needs to accept logs from many producers (web requests, background jobs, services) and write them to the DB via one efficient writer without blocking request threads or losing control when traffic spikes. Channels are a great fit:

Non blocking producers
Backpressure with bounded capacity
Single reader, many writers
Async, allocation friendly
Graceful shutdown

Source code:
https://github.com/stevsharp/DbLoggerSample

Chain of Responsibility pattern

Spyros Ponaris — Mon, 19 Jan 2026 09:26:10 +0000

Chain of Responsibility

About 8 years ago I came across the Chain of Responsibility pattern. I remember I was genuinely happy when I understood it, because all those long if / else if / else blocks suddenly felt unnecessary. Instead of one method trying to decide everything, you build a small chain of handlers. Each handler either handles the request, or passes it to the next one.

Wikipedia describes it as a source of requests and a series of processing objects. Each processing object contains logic that decides what it can handle, and forwards the rest to the next one. The nice part is that the chain can be rearranged and extended without rewriting one big method. (Wikipedia)

The classic example (your repo)

In your repo, the idea is very clear:

You have a base Handler with a successor
Employee, Supervisor, GeneralManager try to approve a PurchaseOrder
Each handler checks rules (your Specification<T>), and if it cannot approve, it forwards to the next handler

This is the object-oriented alternative to the “if ladder”, but with better structure and easier extension. (GitHub)

The base building blocks

This is the base handler that wires the chain:

public abstract class Handler
{
    protected Handler successor;

    public void SetSuccessor(Handler purchaseOrder)
    {
        this.successor = purchaseOrder;
    }

    public abstract void HandleRequest(PurchaseOrder purchase);
}

And this is the small Specification<T> concept used to keep rules readable:

public interface ISpecification<T>
{
    bool IsSatisfiedBy(T o);
}

public class Specification<T> : ISpecification<T>
{
    private Func<T, bool> expression;

    public Specification(Func<T, bool> expression)
    {
        if (expression == null)
            throw new ArgumentNullException();
        else
            this.expression = expression;
    }

    public bool IsSatisfiedBy(T o)
    {
        return this.expression(o);
    }
}

Example handler, Employee approves only small purchase orders. If it cannot approve, it forwards to the next handler:

public class Employee : Handler
{
    public override void HandleRequest(PurchaseOrder purchase)
    {
        ISpecification<PurchaseOrder> specification =
            new Specification<PurchaseOrder>(x => x.Price < 100);

        specification.And(new Specification<PurchaseOrder>(x => x.Amount == 1));

        if (specification.IsSatisfiedBy(purchase))
            Console.WriteLine("{0} approved purchase request #{1}",
                this.GetType().Name, purchase.RequestNumber);
        else if (successor != null)
            successor.HandleRequest(purchase);
    }
}

A quick example, building the chain

This is the part that made the pattern “click” for me. You create the handlers, link them together, and then you send requests to the first handler:

var emp = new Employee();
var superVisor = new Supervisor();
var generalManager = new GeneralManager();

emp.SetSuccessor(superVisor);
superVisor.SetSuccessor(generalManager);

List<PurchaseOrder> purchaseOrders = new List<PurchaseOrder>
{
    new PurchaseOrder { RequestNumber = 1, Amount = 1, Price = 50, Name = "Test Room 1" },
    new PurchaseOrder { RequestNumber = 1, Amount = 1, Price = 150, Name = "Test Room 2" },
    new PurchaseOrder { RequestNumber = 1, Amount = 1, Price = 200, Name = "Test Room 3" },
};

purchaseOrders.ForEach(x => emp.HandleRequest(x));

The caller doesn’t need to know who will approve. It only knows the start of the chain. Adding a new role later is just inserting one more handler, without rewriting the calling code.

How this shows up today with MediatR behaviors

What I like is that this pattern is not old school. You see the same idea a lot in MediatR pipeline behaviors.

A MediatR request goes through a chain of behaviors (validation, logging, performance, transaction, etc.). Each behavior can run logic before and after calling the next step in the pipeline, very similar to middleware. In practice, this is a Chain of Responsibility around your handler, used in a modern CQRS way. (CodeOpinion)

In my projects, the most common example is TransactionBehavior. I run a database transaction only for commands (write operations). Queries skip it. That keeps reads lightweight, while writes stay consistent. The chain idea is the same, each step has one job, and the next step continues the flow.

Typical chain steps in CQRS are:

Validation (FluentValidation), stop early if invalid
Logging (request, response, timing)
Authorization (permissions, policies)
Caching (usually queries only)
Transactions (usually commands only, begin, commit, rollback)
Retries / idempotency (depending on the system)

So the “chain” is not only about deciding who approves a purchase order. It’s also about running a request through cross-cutting concerns, without bloating controllers or handlers.

Why I still like it

You can add a new rule without editing a giant method
You can reorder behavior, or swap parts, without rewriting everything
It fits naturally with CQRS, because commands and queries are already separated by intent

References

Wikipedia, Chain-of-responsibility pattern (Wikipedia)
Repo example, ChainOfResponsibility- (GitHub)
MediatR behaviors overview (CodeOpinion)

If you want, in the next part we can break it down with a concrete CQRS flow, like CreatePurchaseOrderCommand with ValidationBehavior, TransactionBehavior, and an approval chain implemented as a pipeline (or inside the command handler, depending on what you prefer).

Why learning to build your own ORM is worth it (even if you use EF Core or Dapper)

Spyros Ponaris — Fri, 19 Dec 2025 13:55:04 +0000

Why learning to build your own ORM is worth it (even if you use EF Core or Dapper)

Most developers meet ORMs the same way they meet electricity, you flip a switch and things work. That’s great, until something gets slow, a query behaves oddly, or you hit a transaction or concurrency edge case and you suddenly need to know what’s happening under the hood.

Building a small ORM, even a deliberately limited one, is one of the fastest ways to close the gap between “I can use EF Core or Dapper” and “I understand data access.”

To keep it grounded, I’ll anchor this around my tiny demo ORM (MicroOrm), a .NET 8 sample using SQLite, simple POCOs, a lightweight Include for eager loading, and CancellationToken propagation end to end. (GitHub)

1) You stop treating the database like a black box

When you write mapping yourself, you’re forced to answer questions full ORMs often hide:

What SQL is actually executed?
How are parameters created and bound?
How do nulls map into value types vs nullable types?
What happens when schema changes, column names drift, or types don’t match?
How do you retrieve identities safely after inserts?

This is where “I know EF” turns into “I can debug a data issue under pressure.”

2) Reflection becomes a tool, not a mystery

A tiny ORM almost always starts with reflection.

You inspect a type, find its attributes, discover the key property, build a column list, and map rows back into objects. In MicroOrm’s demo, entities like Blog and Post use familiar attributes like [Table], [Key], [ForeignKey], and [InverseProperty], which is exactly the kind of metadata you typically read via reflection. (GitHub)

The payoff is immediate because you hit two truths fast:

Reflection is powerful, it removes a ton of repetitive glue code.
Reflection is not free, so you learn to cache metadata and keep reflection out of hot paths.

Those instincts carry straight into EF Core too.

3) Generics give you type safety and a clean API surface

Generics are the other superpower of a micro ORM.

They let you write APIs that feel natural in C# and stay strongly typed:

GetById<T>(id) returns a T, not object
GetAll<T>() returns List<T>, not dictionaries
One set of operations can work across your entities without repetition

In practice, building a micro ORM becomes a “generics + reflection” exercise done right, compile-time safety on the outside, runtime discovery on the inside.

4) You finally learn ADO.NET for real (SqlConnection, SqlCommand, and friends)

EF Core and Dapper sit on top of ADO.NET. When you build your own ORM, you stop skipping the fundamentals:

Connections (SqlConnection, SqliteConnection, or DbConnection)
You learn what “open late, close early” actually looks like, why using or await using matters, and how connection pooling changes the way you should think about lifetime.
Commands (SqlCommand, DbCommand)
You get comfortable with parameterized queries (and why they’re non negotiable), command timeouts, and how provider differences show up.
Readers (DbDataReader)
You learn what streaming results means, how mapping happens row by row, and where conversions and null handling can bite you.
Transactions (DbTransaction)
You start treating transaction boundaries as a deliberate design choice, not an incidental side effect of the ORM.

MicroOrm’s demo explicitly highlights cancellation support across opening connections and executing commands, which is exactly the sort of detail you only appreciate once you’re directly using these classes. (GitHub)

5) You learn the real price of convenience (and why loading strategy matters)

MicroOrm’s Include supports both references and collections, implemented as extra queries per entity. It’s intentionally simple, and extremely educational because you can feel the tradeoff immediately: clearer code and predictable behavior, plus a very real risk of N+1 query explosions if you’re not careful. (GitHub)

After you build even a basic Include, you start spotting inefficient loading patterns everywhere, including in mature ORMs.

6) You learn portability the honest way

“Database agnostic” always has seams.

The sample calls it out plainly: switching from SQLite to SQL Server means swapping the provider and adjusting identity retrieval in SqlBuilder.Insert to use SELECT SCOPE_IDENTITY();. That single detail teaches a big lesson, database behavior differences are real and they show up fast. (GitHub)

The takeaway

Writing a tiny ORM is not about shipping a competitor to EF Core.

It’s about gaining X-ray vision for what’s underneath, reflection, generics, ADO.NET primitives like SqlConnection and SqlCommand, query cost, round trips, and transactions. Then, when you choose EF Core or Dapper, you’re not just using them, you’re using them with intent.

Building a Simple Cron Scheduler in .NET with Cronos

Spyros Ponaris — Fri, 28 Nov 2025 18:34:40 +0000

1. Introduction

Most .NET apps need some kind of background work. Sending emails, generating reports, cleaning data, all of these are better when they run automatically on a schedule, instead of being triggered by users.

You do not always need a heavy framework like Quartz or Hangfire. For many scenarios a lightweight cron based scheduler in a console or worker service is more than enough.

In this tutorial you will build a small but powerful console scheduler that:

Uses Cronos, a library for parsing cron expressions and calculating next run times
Runs multiple jobs with different cron expressions
Executes jobs in parallel, so a slow job does not block the rest
Handles graceful shutdown using CancellationToken

Cronos itself does not execute jobs, it only parses cron expressions and calculates occurrences, which makes it perfect as a building block for your own scheduler. (GitHub)

2. Prerequisites

You will need:

.NET 8 SDK or newer
Basic C# knowledge
NuGet package Cronos

3. Project setup

Create a new console project and add Cronos.

dotnet new console -n ConsoleCronSchedulerDemo
cd ConsoleCronSchedulerDemo

dotnet add package Cronos

Your final structure will look like this:

ConsoleCronSchedulerDemo/
 ├─ Program.cs
 ├─ Jobs/
 │   ├─ ICronJob.cs
 │   ├─ EmailJob.cs
 │   ├─ ReportJob.cs
 │   └─ Scheduler.cs
 └─ README.md  (optional)

4. Defining the cron job contract

First, create a Jobs folder and add ICronJob.cs. This interface describes what every scheduled job must provide.

// Jobs/ICronJob.cs
using System.Threading;
using System.Threading.Tasks;

namespace ConsoleCronSchedulerDemo.Jobs;

public interface ICronJob
{
    /// <summary>
    /// Human friendly name, used in logs.
    /// </summary>
    string Name { get; }
    /// <summary>
    /// Cron expression in standard 5 field format
    /// for example "*/1 * * * *".
    /// </summary>
    string CronExpression { get; }
    /// <summary>
    /// Job logic.
    /// </summary>
    Task ExecuteAsync(CancellationToken stoppingToken);
}

Each job knows:

Its name, for logging
Its cron expression, a simple string

* The work it needs to perform, exposed as `ExecuteAsync`

5. Implementing concrete jobs

Now create two simple demo jobs.

5.1 EmailJob

// Jobs/EmailJob.cs
using System;
using System.Threading;
using System.Threading.Tasks;

public class EmailJob(string cronExpression, IEmailService emailService) : ICronJob
{
    private readonly IEmailService _emailService = emailService;
    public string Name => "EmailJob";
    public string CronExpression { get; } = cronExpression;

    public async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        await _emailService.SendReportAsync();

        Console.WriteLine($"[{Name}] Email sent at {DateTimeOffset.Now}");
    }
}

5.2 ReportJob

// Jobs/ReportJob.cs
using System;
using System.Threading;
using System.Threading.Tasks;

public class ReportJob(string cronExpression, IReportService reportService) : ICronJob
{
    private readonly IReportService _reportService = reportService;
    public string Name => "ReportJob";
    public string CronExpression { get; } = cronExpression;

    public async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        await _reportService.GenerateReportAsync();

        Console.WriteLine($"[{Name}] Report generated at {DateTimeOffset.Now}");
    }
}

These jobs are just writing to the console, but in a real application they could send emails, generate reports, call APIs, clean a database, or whatever your business needs.

6. The scheduler that uses Cronos

Now you create a scheduler that:

Takes a list of ICronJob implementations
Uses Cronos to parse each cron expression and compute the next occurrence
Loops continuously, checking if any job is due
Runs each due job in its own Task
Respects a CancellationToken so you can shut down cleanly

Create Jobs/Scheduler.cs.

// Jobs/Scheduler.cs
public sealed class Scheduler
{
    private readonly ILogger<Scheduler> _logger;
    private readonly List<(ICronJob job, CronExpression expression)> _jobs;
    private readonly TimeZoneInfo _timeZoneInfo;
    private readonly SemaphoreSlim _semaphore;
    private readonly SchedulerSettings _settings;

    public Scheduler(
        IEnumerable<ICronJob> cronJobs,
        ILogger<Scheduler> logger,
        SchedulerSettings settings)
    {
        _logger = logger;
        _settings = settings ?? new SchedulerSettings();
        _jobs = [.. cronJobs.Select(job => (job, CronExpression.Parse(job.CronExpression)))];
        _timeZoneInfo = TimeZoneInfo.Local;

        var max = _settings.MaxConcurrentJobs > 0 ? _settings.MaxConcurrentJobs : 1;

        _semaphore = new SemaphoreSlim(max);
    }
    /// <summary>
    /// 
    /// </summary>
    /// <param name="stoppingToken"></param>
    /// <returns></returns>
    public async Task StartAsync(CancellationToken stoppingToken)
    {
        var nextRuns = _jobs.ToDictionary(
            j => j.job.Name,
            j => j.expression.GetNextOccurrence(DateTimeOffset.Now, _timeZoneInfo));

        _logger.LogInformation("Scheduler started with {JobCount} jobs, max {Max} concurrent.", _jobs.Count, _settings.MaxConcurrentJobs);

        while (!stoppingToken.IsCancellationRequested)
        {
            var now = DateTimeOffset.Now;

            foreach (var (job, expression) in _jobs)
            {
                var next = nextRuns[job.Name];

                if (!next.HasValue || next.Value > now)
                    continue;

                _logger.LogInformation("Running {Job} at {Now}", job.Name, now);

                _ = Task.Run(() => RunJobWithRetryAsync(job, stoppingToken), stoppingToken);

                nextRuns[job.Name] = expression.GetNextOccurrence(now.AddSeconds(1), _timeZoneInfo);

                _logger.LogInformation("Next run of {Job} scheduled at {Next}",job.Name, nextRuns[job.Name]);
            }

            try
            {
                await Task.Delay(1000, stoppingToken);
            }
            catch (OperationCanceledException)
            {
                _logger.LogInformation("Scheduler cancellation requested.");

                break;
            }
        }

        _logger.LogInformation("Scheduler stopped.");
    }
    /// <summary>
    /// 
    /// </summary>
    /// <param name="job"></param>
    /// <param name="ct"></param>
    /// <returns></returns>
    private async Task RunJobWithRetryAsync(ICronJob job, CancellationToken ct)
    {
        bool acquired = false;
        try
        {
            await _semaphore.WaitAsync(ct);

            acquired = true;

            var maxRetries = Math.Max(0, _settings.MaxRetries);
            var attempt = 0;

            while (!ct.IsCancellationRequested)
            {
                attempt++;

                try
                {
                    await job.ExecuteAsync(ct);

                    _logger.LogInformation("{Job} completed successfully (attempt {Attempt}).", job.Name, attempt);

                    return;
                }
                catch (OperationCanceledException) when (ct.IsCancellationRequested)
                {
                    _logger.LogInformation("{Job} cancelled during execution.", job.Name);

                    return;
                }
                catch (Exception ex)
                {
                    if (attempt > maxRetries)
                    {
                        _logger.LogError(ex, "{Job} failed after {Attempts} attempts.", job.Name, attempt - 1);
                        return;
                    }

                    var delay = GetBackoffDelay(attempt);

                    _logger.LogWarning(ex, "{Job} failed on attempt {Attempt}. Retrying in {Delay}...", job.Name, attempt, delay);

                    await Task.Delay(delay, ct);
                }
            }
        }
        catch (OperationCanceledException)
        {
            _logger.LogInformation("{Job} scheduling cancelled before start.", job.Name);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Unexpected error while scheduling/executing {Job}.", job.Name);
        }
        finally
        {
            if (acquired)
            {
                _semaphore.Release();
            }
        }
    }
    /// <summary>
    /// 
    /// </summary>
    /// <param name="attempt"></param>
    /// <returns></returns>
    private TimeSpan GetBackoffDelay(int attempt)
    {
        var baseSeconds = Math.Max(1, _settings.RetryDelaySeconds);
        // Exponential backoff: 1, 2, 4, 8, ...
        var exponent = Math.Min(attempt - 1, 10);

        var seconds = baseSeconds * (int)Math.Pow(2, exponent);

        // Add small jitter to avoid thundering herd
        var jitterMs = Random.Shared.Next(100, 500);

        var delay = TimeSpan.FromSeconds(seconds) + TimeSpan.FromMilliseconds(jitterMs);

        var maxDelay = TimeSpan.FromMinutes(2);

        return delay <= maxDelay ? delay : maxDelay;
    }
}

Why use Cronos here

Cronos gives you CronExpression.Parse(string) and GetNextOccurrence which calculates the next valid date time in a given time zone. This means:

You do not have to manually calculate future dates
Time zones and daylight saving changes are handled according to cron semantics (GitHub)

Your scheduler is now focused on one thing, deciding when to run jobs and starting tasks, and Cronos handles the calendar rules.

7. Wiring everything in Program.cs

Finally, wire everything together in Program.cs.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using NetCoreCronSchedulerDemo.Jobs;
using NetCoreCronSchedulerDemo.Model;
using NetCoreCronSchedulerDemo.Sevice;

class Program
{
    static async Task Main(string[] args)
    {
        // Build configuration
        var configuration = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
            .Build();

        // Setup DI
        var services = new ServiceCollection();
        services.AddLogging(config => config.AddConsole());
        services.AddSingleton<IEmailService, EmailService>();
        services.AddSingleton<IReportService, ReportService>();

        var schedulerSettings = configuration.GetSection("SchedulerSettings").Get<SchedulerSettings>() ?? throw new InvalidOperationException("SchedulerSettings section is missing in appsettings.json.");

        services.AddSingleton(schedulerSettings);

        // Load jobs from config
        var cronJobsConfig = configuration.GetSection("CronJobs").Get<List<CronJobConfig>>();

        if (cronJobsConfig == null || cronJobsConfig.Count == 0)
        {
            throw new InvalidOperationException("No cron jobs configured in appsettings.json.");
        }

        foreach (var jobConfig in cronJobsConfig)
        {
            if (jobConfig.Name == "EmailJob")
            {
                var emailService = services.BuildServiceProvider().GetService<IEmailService>() 
                    ?? throw new InvalidOperationException("IEmailService is not registered in the service collection.");

                services.AddSingleton<ICronJob>(new EmailJob(jobConfig.CronExpression, emailService));
            }
            else if (jobConfig.Name == "ReportJob")
            {
                var reportService = services.BuildServiceProvider().GetService<IReportService>() 
                    ?? throw new InvalidOperationException("IReportService is not registered in the service collection.");

                services.AddSingleton<ICronJob>(new ReportJob(jobConfig.CronExpression, reportService));
            }

        }

        services.AddSingleton<Scheduler>();

        var provider = services.BuildServiceProvider();

        var scheduler = provider.GetRequiredService<Scheduler>();

        Console.WriteLine("========================================");

        Console.WriteLine("Console Cron Scheduler (Advanced) started.");

        Console.WriteLine("========================================");

        await scheduler.StartAsync(CancellationToken.None);
    }
}

Run the application.

dotnet run

You should see something similar to:

Console Cron Scheduler started.
Running ReportJob at 2025-11-28T18:00:00.0000000+02:00
Next run of ReportJob scheduled at 2025-11-28T18:01:00.0000000+02:00
Running EmailJob at 2025-11-28T18:00:00.0000000+02:00
Next run of EmailJob scheduled at 2025-11-28T20:00:00.0000000+02:00
[2025-11-28T18:00:02.0000000+02:00] ReportJob finished.
[2025-11-28T18:00:05.0000000+02:00] EmailJob finished.
...

8. Understanding the flow

To recap how everything works:

Program creates a list of ICronJob implementations
Scheduler wraps each job in a ScheduledJob that holds the CronExpression and NextRun time
The scheduler loop:
- Looks at current time
- Checks which jobs are due
- Starts each due job in a Task.Run
- Asks Cronos for the next occurrence and updates NextRun
The loop waits one second and repeats until CancellationToken is cancelled

Because each job runs on its own task, a long running email job will not block a quick report job.

10. Conclusion

With a few small classes you have built a reusable cron scheduler around the Cronos library that can run multiple jobs in parallel, respect time zones, and shut down cleanly.

Cronos gives you clean handling of cron expressions and their next occurrences, and your scheduler focuses on orchestrating job execution. This pattern can be reused in console apps, worker services, or even as part of a larger ASP.NET Core backend.

Source Code : https://github.com/stevsharp/NetCoreCronSchedulerDemo

Tutorial: Building a .NET 9 Console App with Hangfire and Channels

Spyros Ponaris — Thu, 20 Nov 2025 07:58:43 +0000

Tutorial: Building a .NET 9 Console App with Hangfire and Channels

Overview

In this tutorial, you will build a .NET 8 console application that:

Polls data from an API, or simulates it
Uses System.Threading.Channels for producer consumer messaging
Runs background tasks using Hosted Services
Enqueues jobs in Hangfire using in memory storage

Why Use System.Threading.Channels

Traditional producer consumer patterns often rely on BlockingCollection or custom queues, which can introduce:

Thread contention
Blocking calls
Complex synchronization

System.Threading.Channels provides:

Asynchronous, non blocking communication between producers and consumers
Built in backpressure when using bounded channels
High performance with low allocation

In this app:

DataPollingService is the producer, it writes work items into the channel
ChannelConsumerService is the consumer, it reads items and enqueues Hangfire jobs

Why Hosted Services

Hosted services, BackgroundService, integrate with the .NET Generic Host. You get:

Graceful lifecycle management, start and stop
Dependency injection
Logging and configuration
Non blocking background loops

This app uses two hosted services:

DataPollingService simulates fetching data and writes work items to the channel
ChannelConsumerService reads from the channel and enqueues Hangfire jobs

What is `BackgroundService`

BackgroundService is a base class that implements IHostedService and gives you a long running ExecuteAsync loop. It plugs into the Generic Host, so you get DI, logging, and coordinated shutdown.

Use cases

Poll APIs or message brokers
Drain a queue or channel
Run internal maintenance tasks

Key points

Use ExecuteAsync(CancellationToken) as your main loop
Respect the cancellation token for fast shutdown
Prefer PeriodicTimer over Task.Delay in recurring loops

What is Hangfire

Hangfire is a background job processor for .NET. You enqueue a method call, Hangfire persists and executes it with workers. It supports fire and forget, delayed, recurring, continuations, and batches.

Why it helps here

The consumer stays lightweight, it only enqueues work
Processing is retried and observable with a dashboard
You can swap storage later for durability

Common job types

Fire and forget, BackgroundJob.Enqueue(() => DoWork())
Delayed, BackgroundJob.Schedule(() => DoWork(), TimeSpan.FromMinutes(5))
Recurring, RecurringJob.AddOrUpdate("nightly", () => DoWork(), "0 2 * * *")

Notes, in memory storage is fine for demos, not for production. Jobs should be idempotent.

What is `System.Threading.Channels`

Channels are high performance, async friendly, in process queues. You get a ChannelWriter<T> for producers and a ChannelReader<T> for consumers. Channels work with async and IAsyncEnumerable<T>, and avoid blocking threads.

Why they shine

Async reads and writes
Bounded channels provide backpressure
Options like SingleReader and SingleWriter reduce overhead when true

Fast read loop

while (await reader.WaitToReadAsync(ct))
    while (reader.TryRead(out var item))
        await HandleAsync(item, ct);

Steps to Build

1. Create the Project

dotnet new console -n CustomerSyncConsole
cd CustomerSyncConsole

2. Add NuGet Packages

dotnet add package Hangfire
dotnet add package Hangfire.MemoryStorage
dotnet add package Microsoft.Extensions.Hosting
dotnet add package Microsoft.Extensions.Logging.Console

3. Implement the Code

Below is a complete Program.cs with comments. It uses an unbounded channel for simplicity. See the optional bounded channel section that follows if you want backpressure.

using System.Threading.Channels;
using Hangfire;
using Hangfire.MemoryStorage;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

namespace CustomerSyncConsole;

public sealed record CustomerWorkItem(int CustomerId, string PayloadId, DateTimeOffset ReceivedAt, string RawJson);

public interface ICustomerJobs
{
    Task ProcessCustomer(int customerId, string payloadId, CancellationToken ct = default);
}

public sealed class CustomerJobs(ILogger<CustomerJobs> logger) : ICustomerJobs
{
    private readonly ILogger<CustomerJobs> _logger = logger;

    public async Task ProcessCustomer(int customerId, string payloadId, CancellationToken ct = default)
    {
        _logger.LogInformation("Hangfire job started for Customer {CustomerId}, Payload {PayloadId}", customerId, payloadId);
        await Task.Delay(TimeSpan.FromSeconds(2), ct);
        _logger.LogInformation("Hangfire job completed for Customer {CustomerId}, Payload {PayloadId}", customerId, payloadId);
    }
}

public interface IStorage
{
    Task SaveAsync(string payloadId, string rawJson, CancellationToken ct);
}

public sealed class InMemoryStorage(ILogger<InMemoryStorage> logger) : IStorage
{
    private readonly ILogger<InMemoryStorage> _logger = logger;
    private readonly Dictionary<string, string> _store = new();

    public Task SaveAsync(string payloadId, string rawJson, CancellationToken ct)
    {
        _store[payloadId] = rawJson;
        _logger.LogInformation("Saved payload {PayloadId} in-memory (size={Size}).", payloadId, _store.Count);
        return Task.CompletedTask;
    }
}

public sealed class DataPollingService(
    ILogger<DataPollingService> logger,
    Channel<CustomerWorkItem> channel,
    IConfiguration config,
    IStorage storage) : BackgroundService
{
    private readonly ILogger<DataPollingService> _logger = logger;
    private readonly ChannelWriter<CustomerWorkItem> _writer = channel.Writer;
    private readonly IConfiguration _config = config;
    private readonly IStorage _storage = storage;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var intervalSeconds = _config.GetValue("Polling:IntervalSeconds", 10);
        var timer = new PeriodicTimer(TimeSpan.FromSeconds(intervalSeconds));

        _logger.LogInformation("Polling started. Interval={Interval}s", intervalSeconds);

        try
        {
            while (await timer.WaitForNextTickAsync(stoppingToken))
            {
                var simulated = new[]
                {
                    new IncomingDto { CustomerId = 1, PayloadId = Guid.NewGuid().ToString("N") },
                    new IncomingDto { CustomerId = 2, PayloadId = Guid.NewGuid().ToString("N") },
                };

                foreach (var dto in simulated)
                {
                    var raw = System.Text.Json.JsonSerializer.Serialize(dto);
                    await _storage.SaveAsync(dto.PayloadId, raw, stoppingToken);

                    var item = new CustomerWorkItem(dto.CustomerId, dto.PayloadId, DateTimeOffset.UtcNow, raw);
                    await _writer.WriteAsync(item, stoppingToken);
                    _logger.LogInformation("Queued work item for Customer {CustomerId}, Payload {PayloadId}", dto.CustomerId, dto.PayloadId);
                }
            }
        }
        finally
        {
            _writer.TryComplete();
        }
    }

    private sealed class IncomingDto
    {
        public int CustomerId { get; set; }
        public string PayloadId { get; set; } = Guid.NewGuid().ToString("N");
    }
}

public sealed class ChannelConsumerService(
    Channel<CustomerWorkItem> channel,
    IBackgroundJobClient backgroundJobClient,
    ILogger<ChannelConsumerService> logger) : BackgroundService
{
    private readonly ChannelReader<CustomerWorkItem> _reader = channel.Reader;
    private readonly IBackgroundJobClient _backgroundJobClient = backgroundJobClient;
    private readonly ILogger<ChannelConsumerService> _logger = logger;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("Channel consumer started.");
        await foreach (var item in _reader.ReadAllAsync(stoppingToken))
        {
            if (item.CustomerId == 1)
            {
                var jobId = _backgroundJobClient.Enqueue<ICustomerJobs>(job => job.ProcessCustomer(item.CustomerId, item.PayloadId, CancellationToken.None));
                _logger.LogInformation("Enqueued Hangfire job {JobId} for Customer {CustomerId}, Payload {PayloadId}", jobId, item.CustomerId, item.PayloadId);
            }
        }
        _logger.LogInformation("Channel consumer stopping.");
    }
}

public static class Program
{
    public static async Task Main(string[] args)
    {
        using var host = Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration(cfg =>
            {
                cfg.AddInMemoryCollection(new Dictionary<string, string?>
                {
                    ["Polling:IntervalSeconds"] = "10"
                });
            })
            .ConfigureLogging(logging =>
            {
                logging.ClearProviders();
                logging.AddSimpleConsole(o =>
                {
                    o.TimestampFormat = "HH:mm:ss ";
                    o.SingleLine = true;
                });
                logging.SetMinimumLevel(LogLevel.Information);
            })
            .ConfigureServices((ctx, services) =>
            {
                // Unbounded for simplicity in this tutorial
                services.AddSingleton(Channel.CreateUnbounded<CustomerWorkItem>());

                // Hangfire in memory
                services.AddHangfire(config => config.UseMemoryStorage());
                services.AddHangfireServer();

                services.AddSingleton<ICustomerJobs, CustomerJobs>();
                services.AddSingleton<IStorage, InMemoryStorage>();
                services.AddHostedService<DataPollingService>();
                services.AddHostedService<ChannelConsumerService>();
            })
            .Build();

        await host.RunAsync();
    }
}

Optional, switch to a bounded channel

For services that can receive spikes, prefer bounded channels to get backpressure.

services.AddSingleton(_ =>
{
    var opts = new BoundedChannelOptions(capacity: 512)
    {
        FullMode = BoundedChannelFullMode.Wait,
        SingleReader = true,   // one consumer service
        SingleWriter = true    // one producer service
    };
    return Channel.CreateBounded<CustomerWorkItem>(opts);
});

Replace the unbounded registration with the code above.

Best Practices

Pass CancellationToken to every WriteAsync and ReadAllAsync
Complete the writer during shutdown, then await reader completion
Make Hangfire jobs idempotent, retries can occur
Consider persistent Hangfire storage for real workloads, for example SQL Server or SQLite
Expose channel depth as a metric if you need visibility, current size versus capacity

Run it

dotnet run

You should see logs from both services. The producer writes items into the channel. The consumer enqueues Hangfire jobs for customer 1. The Hangfire server executes those jobs.