DEV Community: ZèD

Implementing Soft Delete with Filtered Indexes in Entity Framework Core

ZèD — Wed, 22 Apr 2026 16:32:18 +0000

Soft Delete with Global Query Filters and Filtered Indexes in Entity Framework Core

Soft delete sounds simple until it reaches production.

If you only add an IsDeleted flag, you have not finished the job. You still need:

Default queries that hide deleted rows
A write path that converts deletes into updates
Unique constraints that ignore soft-deleted rows
A restore path that does not break the model

This article shows a clean EF Core pattern that keeps the implementation explicit and maintainable.

The Core Idea

Soft delete is a domain concern, not just a database trick. The model should express that an entity can be deleted and restored.

An interface keeps the contract small and avoids forcing every entity into the same inheritance tree:

public interface ISoftDeletable
{
    bool IsDeleted { get; }
    DateTimeOffset? DeletedAt { get; }

    void Delete();
    void Restore();
}

A simple base entity can implement the behavior:

public abstract class BaseEntity : ISoftDeletable
{
    public Guid Id { get; private set; } = Guid.NewGuid();
    public bool IsDeleted { get; private set; }
    public DateTimeOffset? DeletedAt { get; private set; }

    public void Delete()
    {
        if (IsDeleted)
        {
            return;
        }

        IsDeleted = true;
        DeletedAt = DateTimeOffset.UtcNow;
    }

    public void Restore()
    {
        if (!IsDeleted)
        {
            return;
        }

        IsDeleted = false;
        DeletedAt = null;
    }
}

That gives the application one place to define the lifecycle of a deleted record.

Turn Deletes Into Updates

The easiest way to preserve EF Core's normal API is to intercept Deleted entities before they hit the database.

For most applications, a SaveChanges override is enough:

using System.Linq;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : DbContext
{
    private void ApplySoftDelete()
    {
        foreach (var entry in ChangeTracker.Entries<ISoftDeletable>()
                     .Where(e => e.State == EntityState.Deleted))
        {
            entry.State = EntityState.Modified;
            entry.Entity.Delete();
        }
    }

    public override int SaveChanges()
    {
        ApplySoftDelete();
        return base.SaveChanges();
    }

    public override Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
    {
        ApplySoftDelete();
        return base.SaveChangesAsync(cancellationToken);
    }
}

This keeps your service layer clean:

context.Users.Remove(user);
await context.SaveChangesAsync();

From the caller's perspective, it is still a delete. Internally, the row is retained and marked as deleted.

If your project already uses EF Core interceptors for auditing or multi-tenant behavior, you can move this logic there instead. The important part is consistency, not the specific hook.

Filter Rows By Default

Global query filters ensure deleted rows stay out of normal reads.

For one or two entities, a per-entity filter works. In a real system, that becomes repetition. The better approach is to let OnModelCreating run one convention pass across the model after loading your normal entity configurations:

using System.Linq;
using System.Linq.Expressions;

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.ApplyConfigurationsFromAssembly(typeof(SomeEntityConfiguration).Assembly);

    foreach (var entityType in modelBuilder.Model.GetEntityTypes())
    {
        if (typeof(ISoftDeletable).IsAssignableFrom(entityType.ClrType))
        {
            var parameter = Expression.Parameter(entityType.ClrType, "e");
            var isDeleted = Expression.Property(parameter, nameof(ISoftDeletable.IsDeleted));
            var isActive = Expression.Equal(isDeleted, Expression.Constant(false));
            var filter = Expression.Lambda(isActive, parameter);

            modelBuilder.Entity(entityType.ClrType).HasQueryFilter(filter);

            foreach (var index in entityType.GetIndexes().Where(i => i.IsUnique && i.GetFilter() is null))
            {
                index.SetFilter($"[{nameof(ISoftDeletable.IsDeleted)}] = 0");
            }
        }

        foreach (var foreignKey in entityType.GetForeignKeys())
        {
            foreignKey.DeleteBehavior = DeleteBehavior.NoAction;
        }
    }

    base.OnModelCreating(modelBuilder);
}

This is the important shift: OnModelCreating becomes the place where persistence conventions are enforced, not an area where each entity gets hand-tuned individually.

That gives you the default behavior you want without repeating Where(u => !u.IsDeleted) everywhere.

When you intentionally need deleted rows, use IgnoreQueryFilters():

var deletedUser = await context.Users
    .IgnoreQueryFilters()
    .FirstOrDefaultAsync(u => u.Id == userId && u.IsDeleted);

That is the right escape hatch for restore flows, admin views, and audits.

Protect Unique Constraints

This is where many soft-delete implementations break down.

If Email is unique, then a deleted user should not block another user from using the same email later. In the convention above, every unique index that does not already define its own filter gets the soft-delete predicate automatically.

The sample above uses SQL Server syntax:

index.SetFilter($"[{nameof(ISoftDeletable.IsDeleted)}] = 0");

For PostgreSQL, the equivalent would look like:

index.SetFilter($"\"{nameof(ISoftDeletable.IsDeleted)}\" = false");

The exact filter expression is provider-specific, but the architectural rule is not.

The architectural point is more important than the syntax:

Filter unique indexes on active rows only
Do not rely on IsDeleted alone to preserve uniqueness
Verify the generated migration for your provider

That same model pass is also a good place to set foreign keys to DeleteBehavior.NoAction so soft delete does not accidentally fight with cascade delete rules.

Restore Safely

Restoring a row should be a first-class operation, not a manual flag flip hidden in business code.

var user = await context.Users
    .IgnoreQueryFilters()
    .FirstOrDefaultAsync(u => u.Id == userId);

if (user is null)
{
    return;
}

user.Restore();
await context.SaveChangesAsync();

This works because the model already knows how deletion and restoration behave.

Design Notes

Prefer a global query filter over ad hoc Where clauses. It is harder to forget and easier to reason about.
Use filtered or partial indexes for business keys that must remain unique among active rows.
Do not add an index on IsDeleted by default. The column is usually low-selectivity and rarely useful on its own.
Test Include queries and required relationships. Global filters apply everywhere, and that can affect query shape.
If you use bulk operations such as ExecuteDelete, remember they bypass the change tracker and will not trigger your soft-delete pipeline.

When This Pattern Fits

This approach works well when you need:

Auditability
Recovery from accidental deletes
Safer admin tooling
Stable referential history

It is less useful when data must be physically removed for legal, privacy, or retention reasons. In those cases, hard delete is the correct answer.

Conclusion

Soft delete is a small feature that becomes a large architectural problem if you treat it as a single boolean column.

The production-ready version has three parts:

Convert deletes into updates
Filter deleted rows out of normal queries
Make unique constraints ignore deleted rows

Once those are in place, the rest of the application can use EF Core naturally without repeating soft-delete rules everywhere.

References

Building Dynamic Filters in Clean Architecture (CQRS) using ExpressionBuilder

ZèD — Wed, 25 Mar 2026 16:01:12 +0000

Building Dynamic Filters in Clean Architecture with ExpressionBuilder

Dynamic filtering becomes messy when the application layer must describe query rules without touching IQueryable.
This is common in Clean Architecture and CQRS, where query execution belongs to infrastructure.
In this article, you will see how ExpressionBuilder<T> helps compose safe dynamic predicates without breaking layer boundaries.

Why It Matters

Keeps filtering logic inside the application layer without leaking EF Core concerns.
Lets repositories receive one predicate instead of many optional filter parameters.
Reduces repetitive conditional code in handlers and services.
Produces expressions that LINQ providers can translate correctly.

Core Concepts

1. Pass Expressions Instead of Queries

The application layer should describe filtering logic, not build database queries directly.

Task<IReadOnlyList<TEntity>> ListAsync(
    Expression<Func<TEntity, bool>>? filter = null,
    CancellationToken cancellationToken = default);

This keeps the contract simple. Application builds the predicate. Infrastructure executes it.

2. Reassigning Filters Does Not Scale

A naive approach usually overwrites previous conditions.

Expression<Func<User, bool>>? filter = null;

if (request.IsActive.HasValue)
    filter = x => x.IsActive == request.IsActive.Value;

if (!string.IsNullOrWhiteSpace(request.Name))
    filter = x => x.Name.Contains(request.Name);

Only the last assignment survives. Once multiple optional filters appear, this pattern starts fighting you.

3. ExpressionBuilder Collects Predicate Blocks

ExpressionBuilder<T> stores independent expression blocks and combines them with AND.

var builder = new ExpressionBuilder<User>()
    .And(x => !x.IsDeleted)
    .And(x => x.Age >= 18 && x.Age <= 60)
    .And(x => x.Role == "Admin" || x.Role == "Manager");

The final predicate keeps the inner logic grouped while joining each block with Expression.AndAlso.

4. Parameter Rewriting Makes the Final Expression Valid

Each lambda expression has its own parameter instance.

x => x.IsActive
y => y.Age >= 18

These cannot be merged safely unless both bodies are rewritten to share the same parameter. That is why the builder uses a custom ExpressionVisitor.

Practical Example

The main thing should stay the main thing, so start with the builder only.

`ExpressionBuilder<T>`

public sealed class ExpressionBuilder<T>
{
    private readonly List<Expression<Func<T, bool>>> _conditions = new();

    public ExpressionBuilder<T> And(Expression<Func<T, bool>> condition)
    {
        ArgumentNullException.ThrowIfNull(condition);

        _conditions.Add(condition);
        return this;
    }

    public ExpressionBuilder<T> AndIf(bool shouldAdd, Expression<Func<T, bool>> condition)
    {
        if (shouldAdd)
            And(condition);

        return this;
    }

    public Expression<Func<T, bool>>? Build()
    {
        if (_conditions.Count == 0)
            return null;

        var parameter = Expression.Parameter(typeof(T), "x");
        Expression combinedBody = RewriteBody(_conditions[0], parameter);

        for (var i = 1; i < _conditions.Count; i++)
        {
            var nextBody = RewriteBody(_conditions[i], parameter);
            combinedBody = Expression.AndAlso(combinedBody, nextBody);
        }

        return Expression.Lambda<Func<T, bool>>(combinedBody, parameter);
    }

    private static Expression RewriteBody(
        Expression<Func<T, bool>> sourceExpression,
        ParameterExpression targetParameter)
    {
        return new ReplaceParameterVisitor(sourceExpression.Parameters[0], targetParameter)
            .Visit(sourceExpression.Body)
            ?? throw new InvalidOperationException("Failed to rewrite filter expression.");
    }

    private sealed class ReplaceParameterVisitor(ParameterExpression source, ParameterExpression target) : ExpressionVisitor
    {
        private readonly ParameterExpression _source = source;
        private readonly ParameterExpression _target = target;

        protected override Expression VisitParameter(ParameterExpression node)
            => node == _source ? _target : base.VisitParameter(node);
    }
}

This builder has one job. It collects predicates, keeps them as separate blocks, then combines them into one final expression. That makes it easy to reason about and easy to reuse.

Minimal Example: One Required Condition

This is the smallest useful case.

var filter = new ExpressionBuilder<User>()
    .And(x => !x.IsDeleted)
    .Build();

The final result is equivalent to:

x => !x.IsDeleted

Minimal Example: Required and Optional Conditions

This is the common CQRS handler scenario. Some filters always apply, while others depend on request values.

var filter = new ExpressionBuilder<User>()
    .And(x => !x.IsDeleted)
    .AndIf(request.IsActive.HasValue, x => x.IsActive == request.IsActive!.Value)
    .AndIf(!string.IsNullOrWhiteSpace(request.Name), x => x.Name.Contains(request.Name!))
    .Build();

This stays readable even when the request grows. The handler reads like business rules instead of if-statement plumbing.

Minimal Example: Grouped Logic Inside One Block

You can keep more complex logic inside a single predicate block.

var filter = new ExpressionBuilder<User>()
    .And(x => !x.IsDeleted)
    .And(x => x.Role == "Admin" || x.Role == "Manager")
    .And(x => x.Age >= 18 && x.Age <= 60)
    .Build();

The builder joins blocks with AND, but it does not break the logic inside each block. That detail is important because real filters are rarely one simple comparison.

Using It in a Query Handler

In the application layer, the handler builds the predicate and sends it to the repository.

public sealed record SearchUsersQuery(bool? IsActive, string? Name);

public sealed class SearchUsersQueryHandler(IUserRepository userRepository)
{
    private readonly IUserRepository _userRepository = userRepository;

    public Task<IReadOnlyList<User>> Handle(SearchUsersQuery request, CancellationToken cancellationToken)
    {
        var filter = new ExpressionBuilder<User>()
            .And(x => !x.IsDeleted)
            .AndIf(request.IsActive.HasValue, x => x.IsActive == request.IsActive!.Value)
            .AndIf(!string.IsNullOrWhiteSpace(request.Name), x => x.Name.Contains(request.Name!))
            .Build();

        return _userRepository.ListAsync(filter, cancellationToken);
    }
}

This keeps the application layer focused on what should be filtered, not how the database query is constructed.

Repository Side

The repository receives the composed expression and applies it only if it exists.

public interface IUserRepository
{
    Task<IReadOnlyList<User>> ListAsync(
        Expression<Func<User, bool>>? filter = null,
        CancellationToken cancellationToken = default);
}

public sealed class UserRepository(AppDbContext dbContext) : IUserRepository
{
    private readonly AppDbContext _dbContext = dbContext;

    public async Task<IReadOnlyList<User>> ListAsync(
        Expression<Func<User, bool>>? filter = null,
        CancellationToken cancellationToken = default)
    {
        IQueryable<User> query = _dbContext.Users;

        if (filter is not null)
            query = query.Where(filter);

        return await query.ToListAsync(cancellationToken);
    }
}

If Build() returns null, the repository skips .Where(...). If it returns a predicate, EF Core receives one clean expression tree instead of scattered condition logic.

Common Mistakes

Reassigning the filter variable and losing previously added conditions.
Returning x => true everywhere instead of allowing null for no filter.
Combining expression bodies without rewriting parameters first.
Exposing IQueryable to the application layer just to support dynamic filters.
Mixing repository execution details into handlers.

Quick Recap

Clean Architecture works better when application passes predicates, not queries.
ExpressionBuilder<T> composes optional filters into one expression.
AndIf keeps conditional filtering compact and readable.
Inner AND and OR logic stays grouped inside each predicate block.
Parameter rewriting is what makes the final expression safe for EF Core translation.

Next Steps

Add unit tests for zero, one, and multiple conditions.
Extend the builder with Or support if your use case needs it.
Check generated SQL for your heavier predicates in EF Core.
Review the official docs for more expression tree details: https://learn.microsoft.com/dotnet/csharp/advanced-topics/expression-trees/

Cursor vs Offset Pagination in EF Core: What Actually Works in Production

ZèD — Thu, 19 Mar 2026 10:18:33 +0000

Cursor vs Offset Pagination in EF Core: What Actually Works in Production

Pagination is easy to implement, but hard to get right when data grows.

Most applications start with Skip/Take. It works fine… until it doesn’t.

This article explains where each approach fits, what breaks, and how to choose properly.

Why This Matters

When pagination is wrong, you will see:

slow queries on large pages
duplicate or missing rows
unnecessary database load

The goal is not just pagination — it is consistent and scalable data access.

1. Offset Pagination (Skip/Take)

The most common approach:

var items = await context.Posts
    .AsNoTracking()
    .OrderByDescending(x => x.CreatedAt)
    .ThenByDescending(x => x.Id)
    .Skip((pageNumber - 1) * pageSize)
    .Take(pageSize)
    .ToListAsync();

Why it works well

simple and predictable
supports page numbers (page 1, 2, 3...)
easy to expose in APIs

Where it breaks

Offset pagination becomes inefficient as the offset grows.

Even if you request 20 rows, the database still processes all skipped rows before returning results.

Also, if data changes between requests:

some rows may appear twice
some rows may be skipped

Because pagination is based on position, not actual data.

2. Cursor Pagination (Keyset)

Cursor pagination moves through data using a reference point.

Instead of page number, you pass the last item from the previous result.

var items = await context.Posts
    .AsNoTracking()
    .OrderByDescending(x => x.CreatedAt)
    .ThenByDescending(x => x.Id)
    .Where(x => x.CreatedAt < lastCreatedAt
        || (x.CreatedAt == lastCreatedAt && x.Id < lastId))
    .Take(pageSize)
    .ToListAsync();

Why it works better for large data

no row skipping
uses index efficiently
stable even if data changes

The database jumps directly to the correct position instead of scanning.

3. Ordering Must Be Stable

This is critical for both approaches.

Bad:

.OrderBy(x => x.CreatedAt)

Good:

.OrderBy(x => x.CreatedAt)
.ThenBy(x => x.Id)

Without a unique order, pagination will eventually return inconsistent results.

4. Performance Comparison

Scenario	Offset	Cursor
small dataset	good	good
large page number	slow	stable
data frequently changing	inconsistent	stable
sequential navigation	ok	best

Cursor pagination avoids unnecessary work, especially at scale.

5. Limitations of Cursor Pagination

Cursor pagination is not a full replacement.

It does not support:

jumping to arbitrary page
clean page numbers
accurate “page X of Y” navigation

Because it works with positions, not pages.

6. When to Use What

Use offset pagination when:

UI requires page numbers
users jump between pages
dataset size is manageable

Example: admin dashboard

Use cursor pagination when:

data is large
users navigate sequentially
consistency matters

Example: feeds, logs, activity streams

7. Practical Recommendation

In many systems, the best approach is:

offset pagination → for page-based navigation
cursor pagination → for next/previous navigation

Each solves a different problem. Using both is normal.

8. Indexing Matters

For cursor pagination to perform well:

modelBuilder.Entity<Post>()
    .HasIndex(x => new { x.CreatedAt, x.Id });

Without proper indexing, both approaches degrade.

Quick Recap

Offset is simple but slows down with large offsets
Cursor is efficient and stable but limited in navigation
Always use a unique ordering
Choose based on how users interact with data

Final Thought

Offset solves UI navigation.
Cursor solves data traversal.

Pick based on the problem, not the implementation.

Understanding EF.Functions.Like and ILike in Entity Framework Core

ZèD — Sat, 28 Feb 2026 05:21:15 +0000

Understanding EF.Functions.Like and ILike in Entity Framework Core

Pattern-based string search in EF Core should run in the database, not in application memory. EF.Functions.Like and EF.Functions.ILike help translate wildcard filtering into SQL-friendly expressions.

This guide explains when to use each, what they replace, and how they affect performance.

Why It Matters

Keeps filtering server-side for scalability.
Avoids heavy client-side string processing.
Improves control over case-sensitive/insensitive matching.
Makes wildcard search behavior explicit in LINQ.

Core Concepts

1. What `Like` Does

EF.Functions.Like maps to SQL LIKE pattern matching.

% matches any sequence of characters.
_ matches a single character.

2. What `ILike` Does

EF.Functions.ILike performs case-insensitive pattern matching where supported (commonly PostgreSQL via Npgsql).

3. Replacing Common String Methods

Contains("foo") -> Like(column, "%foo%")
StartsWith("foo") -> Like(column, "foo%")
EndsWith("foo") -> Like(column, "%foo")

4. Example with `Like`

var users = await context.Users
    .Where(u => EF.Functions.Like(u.Name, "%John%"))
    .ToListAsync();

var usersByPrefix = await context.Users
    .Where(u => EF.Functions.Like(u.Name, "J%"))
    .ToListAsync();

var usersByPattern = await context.Users
    .Where(u => EF.Functions.Like(u.Name, "_a%"))
    .ToListAsync();

5. Example with `ILike`

var products = await context.Products
    .Where(p => EF.Functions.ILike(p.Description, "%widget%"))
    .ToListAsync();

var productsByCategory = await context.Products
    .Where(p => EF.Functions.ILike(p.Category, "electronics"))
    .ToListAsync();

6. Provider and Collation Behavior

Like behavior depends on database collation.
ILike is provider-specific; check your EF provider support.
Always validate generated SQL and execution plan.

Practical Example

Search endpoint pattern:

public Task<List<User>> SearchUsersAsync(string query)
{
    var pattern = $"%{query}%";

    return context.Users
        .Where(u => EF.Functions.ILike(u.Name, pattern) || EF.Functions.ILike(u.Email, pattern))
        .ToListAsync();
}

This keeps search logic readable and database-executed. Good for user-facing search boxes where case-insensitive behavior is expected.

Common Mistakes

Using ToLower()/ToUpper() in LINQ and damaging index usage.
Assuming ILike is universally supported by all providers.
Overusing %term% patterns on huge tables without strategy.
Not checking query plan after adding wildcard searches.
Falling back to client-side filtering for large datasets.

Quick Recap

Use Like for SQL wildcard matching.
Use ILike for case-insensitive patterns where provider supports it.
Keep matching on server side for performance.
Prefix patterns (term%) are more index-friendly than %term%.
Always test with real data volume and query plans.

Next Steps

Benchmark Like/ILike queries with realistic table size.
Add proper indexes for frequent search fields.
Consider full-text search for heavy text-search workloads.
Standardize search pattern strategy across repositories.

BCrypt vs Argon2: Password Hashing in .NET – A Practical Deep Dive

ZèD — Sat, 28 Feb 2026 04:41:09 +0000

BCrypt vs Argon2 Password Hashing in .NET: A Practical Deep Dive

Password storage is one place where shortcuts become incidents. Fast hashes are good for integrity checks, but bad for password protection.

This guide compares BCrypt and Argon2 in .NET with practical trade-offs and usage patterns.

Why It Matters

Password hashing must be intentionally expensive.
Attackers use GPU/ASIC parallelism for brute-force attacks.
Algorithm choice impacts long-term security posture.
Good defaults reduce human error in auth systems.

Core Concepts

1. Why Fast Hashes Are Not Enough

Algorithms like SHA-256 are designed for speed. That is the opposite of what password hashing needs.

2. BCrypt Basics

BCrypt is battle-tested and simple to configure.

CPU-bound design
Single tuning parameter (work factor)
Low fixed memory cost

using BCrypt.Net;

public static class BcryptPasswordHasher
{
    private const int WorkFactor = 13;

    public static string Hash(string password)
        => BCrypt.Net.BCrypt.HashPassword(password, WorkFactor);

    public static bool Verify(string password, string hash)
        => BCrypt.Net.BCrypt.Verify(password, hash);
}

3. Argon2 Basics

Argon2 is newer and designed to be memory-hard.

Recommended variant for passwords: Argon2id
Tunable memory/time/parallelism
Stronger resistance to large-scale parallel cracking

using Isopoh.Cryptography.Argon2;

public static class Argon2PasswordHasher
{
    public static string Hash(string password)
        => Argon2.Hash(password);

    public static bool Verify(string password, string hash)
        => Argon2.Verify(hash, password);
}

4. Internal Difference Summary

BCrypt: mostly CPU cost
Argon2: CPU + memory cost

Memory hardness is the major advantage when defending against GPU-heavy attacks.

5. Parameter Tuning Reality

Benchmark on production-like hardware. Target latency often lands around 400ms-800ms per hash, depending on your SLA and login throughput.

6. Migration Strategy

When upgrading algorithm, rehash on next successful login and store new hash format.

Practical Example

Algorithm-selection helper pattern:

public interface IPasswordHasher
{
    string Hash(string password);
    bool Verify(string password, string hash);
}

public sealed class PasswordService
{
    private readonly IPasswordHasher _hasher;

    public PasswordService(IPasswordHasher hasher)
    {
        _hasher = hasher;
    }

    public string CreateHash(string password) => _hasher.Hash(password);

    public bool Validate(string password, string storedHash) => _hasher.Verify(password, storedHash);
}

This keeps your domain logic clean and lets you switch hashing strategy without rewriting auth flows.

Common Mistakes

Using SHA-256 directly for passwords.
Keeping hash cost too low for modern hardware.
Migrating algorithms without rehash-on-login plan.
Ignoring memory pressure when tuning Argon2 under concurrency.
Relying on hashing alone without rate limiting and MFA.

Quick Recap

Use password-specific hashing, never plain fast hashes.
BCrypt is simple and stable for many systems.
Argon2id is generally stronger for modern threat models.
Tune cost on real hardware, not guesswork.
Combine with lockout, rate limit, and MFA for layered defense.

Next Steps

Benchmark BCrypt vs Argon2 on your production-like environment.
Define acceptable login latency and tune parameters accordingly.
Implement rehash-on-login migration path.
Add rate limiting and MFA to strengthen auth pipeline.

Implementing Event-Driven Order Processing with Kafka using KafkaFlow in .NET

ZèD — Fri, 30 Jan 2026 20:34:10 +0000

Implementing Event-Driven Order Processing with Kafka Using KafkaFlow in .NET

In real systems, producer and consumer workloads usually scale differently. API services publish events quickly, while background processors handle heavier business work. Mixing both in one deployment unit becomes messy.

This guide shows a clean KafkaFlow setup with producer-only and consumer-only registration, sharing one config contract.

Why It Matters

Producer and consumer can scale independently.
Keeps API processes lightweight and focused.
Isolates heavy event processing in worker services.
Uses one shared configuration shape across projects.

Core Concepts

1. Shared Configuration Model

Define one options model used by both producer and consumer projects.

public sealed class KafkaFlowConfiguration
{
    public string ServerUrl { get; set; } = string.Empty;
    public OrderConfig Orders { get; set; } = new();
}

public sealed class OrderConfig
{
    public string TopicName { get; set; } = string.Empty;
    public string ConsumerGroup { get; set; } = string.Empty;
    public string ConsumerName { get; set; } = string.Empty;
}

2. Producer-Only Registration

Use this in API/command services.

public static class KafkaFlowProducerExtensions
{
    public static IServiceCollection AddKafkaFlowProducer(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        var config = configuration
            .GetSection("KafkaConfiguration")
            .Get<KafkaFlowConfiguration>()
            ?? throw new InvalidOperationException("KafkaConfiguration is missing.");

        services.AddKafka(kafka => kafka
            .AddCluster(cluster => cluster
                .WithBrokers(config.ServerUrl.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
                .CreateTopicIfNotExists(config.Orders.TopicName, 10, 1)
                .AddProducer("order-producer", producer =>
                    producer.DefaultTopic(config.Orders.TopicName))));

        return services;
    }
}

3. Consumer-Only Registration

Use this in worker/processor services.

public static class KafkaFlowConsumerExtensions
{
    public static IServiceCollection AddKafkaFlowConsumer(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        var config = configuration
            .GetSection("KafkaConfiguration")
            .Get<KafkaFlowConfiguration>()
            ?? throw new InvalidOperationException("KafkaConfiguration is missing.");

        services.AddKafka(kafka => kafka
            .AddCluster(cluster => cluster
                .WithBrokers(config.ServerUrl.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
                .CreateTopicIfNotExists(config.Orders.TopicName, 10, 1)
                .AddConsumer(consumer => consumer
                    .Topic(config.Orders.TopicName)
                    .WithGroupId(config.Orders.ConsumerGroup)
                    .WithName(config.Orders.ConsumerName)
                    .WithBufferSize(10)
                    .WithConsumerLagWorkerBalancer(maxWorkers: 100, minWorkers: 10, lagThreshold: 25)
                    .WithWorkerDistributionStrategy<FreeWorkerDistributionStrategy>()
                    .AddMiddlewares(middlewares => middlewares
                        .AddTypedHandlers(handlers => handlers
                            .AddHandler<OrderCreatedHandler>()
                            .AddHandler<OrderPaidHandler>()
                            .AddHandler<OrderShippedHandler>())))));

        return services;
    }
}

4. Shared Event Contracts

public record OrderCreated(Guid OrderId, Guid CustomerId, decimal TotalAmount, DateTime CreatedAt);
public record OrderPaid(Guid OrderId, string PaymentId, DateTime PaidAt);
public record OrderShipped(Guid OrderId, string TrackingNumber, DateTime ShippedAt);

5. Consumer Typed Handlers

public sealed class OrderCreatedHandler : IMessageHandler<OrderCreated>
{
    private readonly IInventoryService _inventory;

    public OrderCreatedHandler(IInventoryService inventory)
    {
        _inventory = inventory;
    }

    public Task Handle(OrderCreated message, CancellationToken cancellationToken)
    {
        return _inventory.ReserveStockAsync(message.OrderId);
    }
}

public sealed class OrderPaidHandler : IMessageHandler<OrderPaid>
{
    private readonly IShippingService _shipping;

    public OrderPaidHandler(IShippingService shipping)
    {
        _shipping = shipping;
    }

    public Task Handle(OrderPaid message, CancellationToken cancellationToken)
    {
        return _shipping.InitiateAsync(message.OrderId);
    }
}

public sealed class OrderShippedHandler : IMessageHandler<OrderShipped>
{
    private readonly INotificationService _notification;

    public OrderShippedHandler(INotificationService notification)
    {
        _notification = notification;
    }

    public Task Handle(OrderShipped message, CancellationToken cancellationToken)
    {
        return _notification.SendOrderUpdateAsync(message.OrderId, "shipped");
    }
}

6. Producer Publisher Service

Use strongly typed key selector to avoid reflection-heavy magic.

public sealed class OrderEventPublisher
{
    private readonly IMessageProducer _producer;

    public OrderEventPublisher(IMessageProducer producer)
    {
        _producer = producer;
    }

    public Task PublishAsync<T>(string key, T eventPayload) where T : class
    {
        var message = new Message<string, T>
        {
            Key = key,
            Value = eventPayload
        };

        return _producer.ProduceAsync(message);
    }
}

Practical Example

Program.cs in API/command project:

builder.Services.AddKafkaFlowProducer(builder.Configuration);

Program.cs in worker project:

builder.Services.AddKafkaFlowConsumer(builder.Configuration);

Shared config in appsettings.json:

{
  "KafkaConfiguration": {
    "ServerUrl": "kafka-1:9092,kafka-2:9092",
    "Orders": {
      "TopicName": "orders",
      "ConsumerGroup": "order-processing",
      "ConsumerName": "order-events-handler"
    }
  }
}

This separation keeps architecture clean. Producers push fast, consumers process heavy, everyone stays sane.

Common Mistakes

Registering consumers accidentally inside API projects.
Hardcoding broker list separately across services.
Using inconsistent topic names between producer and consumer.
Ignoring consumer group strategy during horizontal scaling.
Publishing events without deterministic keys when ordering matters.

Quick Recap

Use one shared config model, two separate registrations.
Producers and consumers should live in different deployment units.
Typed handlers keep event processing explicit.
KafkaFlow channel balancing helps under variable lag.
This pattern scales better and is easier to operate.

Next Steps

Add serializer strategy and schema evolution contract.
Add retry/dead-letter handling for failed events.
Add idempotency safeguards in consumers.
Add end-to-end tests for producer-to-consumer flow.

Runtime Environment Variables for React Apps with Nginx and Docker

ZèD — Thu, 25 Dec 2025 12:38:37 +0000

Runtime Environment Variables for React Apps with Nginx and Docker

React frontend env values are usually baked at build time. That means one environment change can force a full rebuild, which is painful when the same image should run in staging, UAT, and production.

This guide shows runtime env injection for a static React app served by Nginx in Docker.

Why It Matters

Build once, deploy anywhere.
Change API endpoints and feature flags without rebuilding image.
Keeps config external and environment-driven.
Fits well with Docker, Kubernetes, and CI/CD pipelines.

Core Concepts

1. Runtime Template File

Create public/runtime-env.template.js:

window.RUNTIME_ENV = {
  API_URL: "${API_URL}",
  FEATURE_FLAG_ANALYTICS: "${FEATURE_FLAG_ANALYTICS}",
  FEATURE_FLAG_NEW_DASHBOARD: "${FEATURE_FLAG_NEW_DASHBOARD}",
  SENTRY_DSN: "${SENTRY_DSN}",
};

2. Load Runtime Config in HTML

Add this in public/index.html inside <head>:

<script src="/runtime-env.js"></script>

3. Consume Config in App Code

const config = {
  API_URL: "https://fallback.com",
  FEATURE_FLAG_ANALYTICS: false,
  FEATURE_FLAG_NEW_DASHBOARD: false,
  SENTRY_DSN: "",
  ...(window.RUNTIME_ENV || {}),
};

export default config;

4. Docker Multi-Stage Setup

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
RUN apk add --no-cache gettext
COPY --from=builder /app/build /usr/share/nginx/html
COPY public/runtime-env.template.js /usr/share/nginx/html/runtime-env.template.js
COPY entrypoint.sh /docker-entrypoint.d/40-runtime-env.sh
RUN chmod +x /docker-entrypoint.d/40-runtime-env.sh

5. Entrypoint Script for Env Substitution

#!/bin/sh
set -eu

export API_URL=${API_URL:-}
export FEATURE_FLAG_ANALYTICS=${FEATURE_FLAG_ANALYTICS:-}
export FEATURE_FLAG_NEW_DASHBOARD=${FEATURE_FLAG_NEW_DASHBOARD:-}
export SENTRY_DSN=${SENTRY_DSN:-}

envsubst '${API_URL} ${FEATURE_FLAG_ANALYTICS} ${FEATURE_FLAG_NEW_DASHBOARD} ${SENTRY_DSN}' \
  < /usr/share/nginx/html/runtime-env.template.js \
  > /usr/share/nginx/html/runtime-env.js

rm -f /usr/share/nginx/html/runtime-env.template.js

6. Runtime Injection Scope

Expose only explicit variables in template and envsubst command.

Practical Example

Run container with environment values:

docker run -p 80:80 \
  -e API_URL=https://api.prod.com \
  -e FEATURE_FLAG_ANALYTICS=true \
  -e FEATURE_FLAG_NEW_DASHBOARD=false \
  -e SENTRY_DSN=https://example@sentry.io/123 \
  your-image:latest

Container startup generates runtime-env.js, and React app reads values immediately. Same image, different environment, zero rebuild drama.

Common Mistakes

Trying to read process.env directly in browser runtime.
Forgetting to include /runtime-env.js before app bundle.
Exposing unintended environment variables in template.
Using shell script that overrides Nginx entrypoint behavior incorrectly.
Not setting safe fallbacks in frontend config.

Quick Recap

Build static app once.
Generate runtime-env.js on container startup.
Inject only approved environment variables.
Load config before app bootstraps.
Reuse same image across all environments.

Next Steps

Add schema validation for window.RUNTIME_ENV values.
Add environment-specific monitoring tags via runtime config.
Add Kubernetes config map/secret mapping for runtime vars.
Add startup checks to fail fast on required missing variables.

Named Configuration Binding in .NET Using the Modern Options Pattern

ZèD — Sat, 29 Nov 2025 18:51:53 +0000

Named Configuration Binding in .NET Using the Modern Options Pattern

When tenant/client identities are fixed in code, named options are a clean way to bind per-tenant settings from configuration. This avoids custom config loaders and keeps everything in the built-in .NET options system.

This guide shows a practical global + tenant configuration structure using modern options registration.

Why It Matters

Keeps tenant configuration strongly typed and predictable.
Uses built-in dependency injection and options features.
Avoids manual dictionary parsing logic.
Scales cleanly when fixed tenant list grows.

Core Concepts

1. Configuration Shape

Use separate sections for global settings and tenant-specific settings.

{
  "GlobalSettings": {
    "FeatureXEnabled": true,
    "ApiEndpoint": "https://example.com"
  },
  "Clients": {
    "ClientA": {
      "ConnectionString": "Server=A",
      "Region": "EU"
    },
    "ClientB": {
      "ConnectionString": "Server=B",
      "Region": "US"
    }
  }
}

2. Fixed Tenant Identifiers

Represent tenants as enum values for stable names.

public enum Client
{
    ClientA,
    ClientB
}

3. Strongly Typed Options Models

public sealed class GlobalSettings
{
    public bool FeatureXEnabled { get; init; }
    public string ApiEndpoint { get; init; } = string.Empty;
}

public sealed class ClientSettings
{
    public string ConnectionString { get; init; } = string.Empty;
    public string Region { get; init; } = string.Empty;
}

4. Global Options Registration

Bind and validate global section once.

builder.Services
    .AddOptions<GlobalSettings>()
    .Bind(builder.Configuration.GetSection("GlobalSettings"))
    .Validate(settings => !string.IsNullOrWhiteSpace(settings.ApiEndpoint), "ApiEndpoint is required")
    .ValidateOnStart();

5. Named Options per Tenant

Bind one named options instance per enum value.

foreach (Client client in Enum.GetValues<Client>())
{
    var clientName = client.ToString();

    builder.Services
        .AddOptions<ClientSettings>(clientName)
        .Bind(builder.Configuration.GetSection($"Clients:{clientName}"))
        .Validate(settings => !string.IsNullOrWhiteSpace(settings.ConnectionString), $"{clientName} ConnectionString is required")
        .Validate(settings => !string.IsNullOrWhiteSpace(settings.Region), $"{clientName} Region is required")
        .ValidateOnStart();
}

6. Tenant Options Consumption

Resolve tenant settings through IOptionsSnapshot<T>.Get(name).

public sealed class ClientConsumer
{
    private readonly IOptionsSnapshot<ClientSettings> _clientSettings;

    public ClientConsumer(IOptionsSnapshot<ClientSettings> clientSettings)
    {
        _clientSettings = clientSettings;
    }

    public ClientSettings Get(Client client)
    {
        return _clientSettings.Get(client.ToString());
    }
}

Practical Example

Minimal startup wiring:

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddOptions<GlobalSettings>()
    .Bind(builder.Configuration.GetSection("GlobalSettings"))
    .ValidateOnStart();

foreach (Client client in Enum.GetValues<Client>())
{
    var name = client.ToString();
    builder.Services
        .AddOptions<ClientSettings>(name)
        .Bind(builder.Configuration.GetSection($"Clients:{name}"))
        .ValidateOnStart();
}

var app = builder.Build();
app.Run();

This keeps tenant config deterministic and explicit. No magic, no hidden fallback surprises.

Common Mistakes

Using free-form tenant names that drift from code identifiers.
Skipping validation and discovering missing settings only at runtime.
Mixing global and tenant settings in one model.
Injecting IConfiguration everywhere instead of typed options.
Forgetting named options lookup (Get(name)) for tenant config.

Quick Recap

Fixed tenant list maps naturally to named options.
Global config and tenant config should be split clearly.
Use ValidateOnStart() to fail fast on bad config.
Keep consumption through typed options, not manual parsing.
This pattern is clean, testable, and production-friendly.

Next Steps

Add per-tenant secret loading from secure vault providers.
Add health checks that verify required tenant settings.
Add integration tests for each configured tenant binding.
Add migration path if tenants become dynamic in future.

.NET 9 dropped Swashbuckle — but you can still keep Swagger UI backed by OpenAPI

ZèD — Fri, 24 Oct 2025 03:23:25 +0000

.NET 9 Dropped Swashbuckle Generator, but You Can Still Keep Swagger UI Backed by OpenAPI

In .NET 9, the default approach moved toward built-in OpenAPI generation. That does not mean interactive API docs are gone. You can still use Swagger UI as a frontend while keeping document generation native.

This setup uses AddOpenApi + transformers for schema/security behavior, then serves docs in Swagger UI.

Why It Matters

Uses native OpenAPI generation in ASP.NET Core.
Keeps Swagger UI developer experience.
Avoids legacy generator-specific plumbing.
Supports JWT auth and problem-details response shaping.

Core Concepts

1. Built-In OpenAPI Document Registration

public static IServiceCollection AddOpenApiDocumentation(this IServiceCollection services)
{
    services.AddOpenApi("v1", options =>
    {
        options.AddDocumentTransformer<JwtBearerSecurityDocumentTransformer>();
        options.AddOperationTransformer<ProblemDetailsOperationTransformer>();
    });

    return services;
}

2. OpenAPI + Swagger UI Pipeline

Map OpenAPI endpoint and configure Swagger UI against /openapi/v1.json.

public static void UseOpenApiDocumentation(this WebApplication app)
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
        options.EnablePersistAuthorization();
        options.DisplayRequestDuration();
        options.EnableTryItOutByDefault();
        options.EnableFilter();
        options.DocExpansion(DocExpansion.List);
        options.DefaultModelsExpandDepth(0);
    });
}

3. JWT Security Scheme Transformer

Add JWT bearer scheme and default security requirement in document.

public sealed class JwtBearerSecurityDocumentTransformer : IOpenApiDocumentTransformer
{
    private const string SecuritySchemeId = JwtBearerDefaults.AuthenticationScheme;

    public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        document.Info = new OpenApiInfo
        {
            Title = "DevInsightForge.API",
            Version = "v1",
            Description = "The DevInsightForge API built with ASP.NET Core, it ensures secure and efficient communication through JSON Web Tokens (JWT) for authentication."
        };

        document.Components ??= new OpenApiComponents();
        document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
        document.Components.SecuritySchemes[SecuritySchemeId] = new OpenApiSecurityScheme
        {
            BearerFormat = "JWT",
            Name = "JWT Authentication",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.Http,
            Scheme = JwtBearerDefaults.AuthenticationScheme,
            Description = "Put **_ONLY_** your JWT Bearer token on the textbox below!"
        };

        document.Security ??= [];
        document.Security.Add(new OpenApiSecurityRequirement
        {
            [new OpenApiSecuritySchemeReference(SecuritySchemeId, document, null)] = []
        });

        return Task.CompletedTask;
    }
}

4. Operation Transformer for Problem Details

Add a reusable 4xx/5xx response contract.

public sealed class ProblemDetailsOperationTransformer : IOpenApiOperationTransformer
{
    public async Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
    {
        operation.Responses ??= [];

        var errorResponseSchema = await context.GetOrCreateSchemaAsync(typeof(ErrorResponse), null, cancellationToken);

        operation.Responses["4xx/5xx"] = new OpenApiResponse
        {
            Description = typeof(ErrorResponse).Name,
            Content = new Dictionary<string, OpenApiMediaType>
            {
                ["application/problem+json"] = new OpenApiMediaType
                {
                    Schema = errorResponseSchema
                }
            }
        };

        return;
    }
}

5. Extension Class (Full)

using DevInsightForge.WebAPI.Contracts;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;
using Swashbuckle.AspNetCore.SwaggerUI;

namespace DevInsightForge.WebAPI.Extensions;

public static class OpenApiExtensions
{
    public static IServiceCollection AddOpenApiDocumentation(this IServiceCollection services)
    {
        services.AddOpenApi("v1", options =>
        {
            options.AddDocumentTransformer<JwtBearerSecurityDocumentTransformer>();
            options.AddOperationTransformer<ProblemDetailsOperationTransformer>();
        });

        return services;
    }

    public static void UseOpenApiDocumentation(this WebApplication app)
    {
        app.MapOpenApi();

        app.UseSwaggerUI(options =>
        {
            options.SwaggerEndpoint("/openapi/v1.json", "v1");
            options.EnablePersistAuthorization();
            options.DisplayRequestDuration();
            options.EnableTryItOutByDefault();
            options.EnableFilter();
            options.DocExpansion(DocExpansion.List);
            options.DefaultModelsExpandDepth(0);
        });
    }
}

public sealed class JwtBearerSecurityDocumentTransformer : IOpenApiDocumentTransformer
{
    private const string SecuritySchemeId = JwtBearerDefaults.AuthenticationScheme;

    public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        document.Info = new OpenApiInfo
        {
            Title = "DevInsightForge.API",
            Version = "v1",
            Description = "The DevInsightForge API built with ASP.NET Core, it ensures secure and efficient communication through JSON Web Tokens (JWT) for authentication."
        };

        document.Components ??= new OpenApiComponents();
        document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
        document.Components.SecuritySchemes[SecuritySchemeId] = new OpenApiSecurityScheme
        {
            BearerFormat = "JWT",
            Name = "JWT Authentication",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.Http,
            Scheme = JwtBearerDefaults.AuthenticationScheme,
            Description = "Put **_ONLY_** your JWT Bearer token on the textbox below!"
        };

        document.Security ??= [];
        document.Security.Add(new OpenApiSecurityRequirement
        {
            [new OpenApiSecuritySchemeReference(SecuritySchemeId, document, null)] = []
        });

        return Task.CompletedTask;
    }
}

public sealed class ProblemDetailsOperationTransformer : IOpenApiOperationTransformer
{
    public async Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
    {
        operation.Responses ??= [];

        var errorResponseSchema = await context.GetOrCreateSchemaAsync(typeof(ErrorResponse), null, cancellationToken);

        operation.Responses["4xx/5xx"] = new OpenApiResponse
        {
            Description = typeof(ErrorResponse).Name,
            Content = new Dictionary<string, OpenApiMediaType>
            {
                ["application/problem+json"] = new OpenApiMediaType
                {
                    Schema = errorResponseSchema
                }
            }
        };

        return;
    }
}

6. Program Wiring

builder.Services.AddControllers();
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:SecurityKey"]!))
        };
    });

builder.Services.AddOpenApiDocumentation();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UseOpenApiDocumentation();
app.MapControllers();

app.Run();

Practical Example

With this setup running:

OpenAPI JSON: /openapi/v1.json
Swagger UI: /swagger

JWT auth appears in Swagger UI authorize dialog, and problem-details response schema is injected consistently.

Common Mistakes

Keeping old AddSwaggerGen assumptions in .NET 9-native OpenAPI setup.
Forgetting app.MapOpenApi() and only configuring Swagger UI.
Adding JWT scheme in auth middleware but not in OpenAPI document.
Inconsistent problem-details schema across endpoints.
Mixing incompatible package versions.

Quick Recap

Generate docs with built-in OpenAPI.
Display docs with Swagger UI package.
Use document transformer for JWT security contract.
Use operation transformer for standard error contract.
Keep startup wiring minimal and explicit.

Next Steps

Add multiple named OpenAPI docs for versioned APIs.
Add operation tags/grouping conventions for large APIs.
Add CI check to validate generated OpenAPI spec.
Add environment-based toggle for Swagger UI exposure.

JWT with OIDC Authentication in Distributed Systems: Building Trust at Scale

ZèD — Wed, 17 Sep 2025 15:31:13 +0000

JWT with OIDC Authentication in Distributed Systems: Building Trust at Scale

In distributed systems, services should validate tokens independently without sharing signing secrets. That is exactly where asymmetric JWT + OIDC discovery works beautifully.

This guide shows a trust model where one authority signs tokens and all services validate them using public keys from standard discovery endpoints.

Why It Matters

Removes shared-secret sprawl across services.
Enables independent token validation per service.
Supports safe key rotation with minimal friction.
Aligns with OIDC/JWKS standards used across modern ecosystems.

Core Concepts

1. Central Signing Authority

One token service signs JWTs with private RSA key. Other services never see that private key.

2. Distributed Validation

Consumer services validate signature using public keys loaded from authority metadata/JWKS.

3. OIDC Discovery Endpoints

Expose .well-known/openid-configuration and jwks endpoints.

4. Key Identification and Rotation

Set kid in signing key and JWT header so validators pick correct public key.

5. Middleware Trust Configuration

Use Authority, issuer/audience validation, and lifetime checks.

6. Security Baselines

Use HTTPS metadata in production and protect private key lifecycle.

Practical Example

Token Service (Signer)

public sealed class AsymmetricTokenProvider
{
    private readonly RsaSecurityKey _signatureKey;
    private readonly JwtSecurityTokenHandler _tokenHandler = new();
    private readonly TokenConfiguration _config;
    private readonly JsonWebKey _publicJwk;

    public AsymmetricTokenProvider(TokenConfiguration config)
    {
        _config = config;

        var rsa = RSA.Create();
        rsa.ImportFromPem(config.PrivateKey);

        _signatureKey = new RsaSecurityKey(rsa)
        {
            KeyId = GenerateKeyFingerprint(rsa)
        };

        _publicJwk = GeneratePublicJwk(_signatureKey);
    }

    public string CreateToken(IEnumerable<Claim> assertions)
    {
        var descriptor = new SecurityTokenDescriptor
        {
            Issuer = _config.Issuer,
            Audience = _config.Audience,
            Subject = new ClaimsIdentity(assertions),
            Expires = DateTime.UtcNow.Add(_config.DefaultDuration),
            SigningCredentials = new SigningCredentials(_signatureKey, SecurityAlgorithms.RsaSha256)
        };

        var token = _tokenHandler.CreateToken(descriptor);
        return _tokenHandler.WriteToken(token);
    }

    public JsonWebKey GetPublicJwk() => _publicJwk;

    private static string GenerateKeyFingerprint(RSA rsa)
    {
        var parameters = rsa.ExportParameters(false);
        using var hasher = SHA256.Create();
        var hash = hasher.ComputeHash(parameters.Modulus!);
        return Base64UrlEncoder.Encode(hash.AsSpan(0, 16));
    }

    private static JsonWebKey GeneratePublicJwk(RsaSecurityKey signatureKey)
    {
        var publicParams = signatureKey.Rsa!.ExportParameters(false);
        var publicKey = RSA.Create();
        publicKey.ImportParameters(publicParams);

        var jwk = JsonWebKeyConverter.ConvertFromRSASecurityKey(
            new RsaSecurityKey(publicKey) { KeyId = signatureKey.KeyId }
        );

        jwk.Alg = SecurityAlgorithms.RsaSha256;
        jwk.Use = "sig";
        return jwk;
    }
}

JWT Bearer Validation Middleware

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = configuration["Jwt:AuthorityUrl"];
        options.RequireHttpsMetadata = true;

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            ValidateIssuer = true,
            ValidIssuer = configuration["Jwt:IssuingAuthority"],
            ValidateAudience = true,
            ValidAudience = configuration["Jwt:Audience"],
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromMinutes(2)
        };
    });

OIDC Discovery + JWKS Endpoints

[ApiController]
[Route(".well-known")]
[AllowAnonymous]
public sealed class DiscoveryEndpoints : ControllerBase
{
    private readonly AsymmetricTokenProvider _tokenProvider;
    private readonly LinkGenerator _urlGenerator;

    public DiscoveryEndpoints(AsymmetricTokenProvider tokenProvider, LinkGenerator urlGenerator)
    {
        _tokenProvider = tokenProvider;
        _urlGenerator = urlGenerator;
    }

    [HttpGet("openid-configuration")]
    public IActionResult GetOpenIdConfiguration()
    {
        var keysEndpoint = _urlGenerator.GetUriByAction(
            HttpContext,
            nameof(GetJsonWebKeys),
            controller: "DiscoveryEndpoints"
        );

        return Ok(new
        {
            issuer = "https://api.example.com",
            jwks_uri = keysEndpoint
        });
    }

    [HttpGet("jwks")]
    public IActionResult GetJsonWebKeys()
    {
        var jwk = _tokenProvider.GetPublicJwk();
        return Ok(new { keys = new[] { jwk } });
    }
}

This pattern keeps trust centralized while validation remains distributed. High scale, low secret chaos.

Common Mistakes

Sharing private signing keys with downstream services.
Setting RequireHttpsMetadata = false in production.
Mismatching token issuer and discovery issuer values.
Rotating keys without stable kid strategy.
Overly large clock skew windows that weaken validation strictness.

Quick Recap

One authority signs JWTs with private key.
Services validate via public keys from JWKS.
OIDC discovery standardizes trust metadata distribution.
kid enables safe key rotation.
HTTPS + strict token validation keep system trustworthy.

Next Steps

Add automated key rotation with overlap window for old/new keys.
Add token revocation strategy for high-risk scenarios.
Add distributed audit logging for auth failures.
Add integration tests for discovery and JWKS rollover behavior.

EF Core 10's ExecuteUpdateAsync: Finally, Delegates That Don't Hate Developers

ZèD — Wed, 27 Aug 2025 05:59:08 +0000

EF Core 10's ExecuteUpdateAsync Finally Uses Delegates Developers Can Actually Live With

Conditional batch updates in older EF versions often pushed developers into expression-tree gymnastics. It worked, but readability and maintenance were painful.

EF Core 10 improved this by allowing delegate-based setters in ExecuteUpdateAsync, which makes update logic much more natural.

Why It Matters

Makes conditional batch updates readable again.
Removes most manual expression tree composition.
Keeps compile-time safety with cleaner syntax.
Reduces maintenance overhead in data access code.

Core Concepts

1. Old Pain: Expression Tree Composition

Before delegate-friendly update composition, conditional update logic often looked like this:

Expression<Func<SetPropertyCalls<Blog>, SetPropertyCalls<Blog>>> setters =
    s => s.SetProperty(b => b.Views, 8);

if (nameChanged)
{
    var blogParameter = Expression.Parameter(typeof(Blog), "b");
    setters = Expression.Lambda<Func<SetPropertyCalls<Blog>, SetPropertyCalls<Blog>>>(
        Expression.Call(
            instance: setters.Body,
            methodName: nameof(SetPropertyCalls<Blog>.SetProperty),
            typeArguments: new[] { typeof(string) },
            arguments: new Expression[]
            {
                Expression.Lambda<Func<Blog, string>>(
                    Expression.Property(blogParameter, nameof(Blog.Name)),
                    blogParameter),
                Expression.Constant("foo")
            }),
        setters.Parameters);
}

2. EF Core 10 Delegate-Based Update Style

With delegate-friendly setters, logic becomes standard C#.

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

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

    return s;
});

3. Why This Is Better

You can use normal control flow.
Update logic is easier to review.
Less custom helper code needed.

4. Migration Shape

Main migration direction:

Old: expression-tree composition-heavy update builders
New: delegate-based setter composition in ordinary code

5. SQL and Performance Expectations

ExecuteUpdateAsync still performs set-based SQL updates and avoids entity materialization.

6. Refactor Opportunity

If your codebase built complex update-expression utilities, many can now be simplified or removed.

Practical Example

public async Task<int> UpdateBlogAsync(AppDbContext context, bool nameChanged)
{
    return await context.Blogs
        .Where(b => b.IsActive)
        .ExecuteUpdateAsync(s =>
        {
            s.SetProperty(b => b.Views, b => b.Views + 1);

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

            return s;
        });
}

Cleaner updates with fewer expression hacks means fewer headaches during code reviews and fewer "who wrote this" moments.

Common Mistakes

Keeping old expression-tree boilerplate after upgrade.
Forgetting return s; in block-bodied setter delegates.
Assuming ExecuteUpdateAsync tracks entities like normal updates.
Mixing batch updates with stale tracked entity assumptions.
Skipping generated SQL verification during migration.

Quick Recap

EF Core 10 makes ExecuteUpdateAsync setter composition easier.
Delegate-based style enables readable conditional logic.
You can remove a lot of expression-tree plumbing.
Batch updates remain set-based and efficient.
Migration is mostly syntax and helper cleanup.

Next Steps

Refactor existing batch-update helpers to delegate-based style.
Add tests that verify conditional setter behavior.
Validate generated SQL for critical updates.
Document team conventions for ExecuteUpdateAsync usage.

References

The Secret to Scalability: Architecting a High-Performance .NET Puppeteer Page Pool

ZèD — Thu, 31 Jul 2025 17:39:47 +0000

The Secret to Scalability: Architecting a High-Performance .NET Puppeteer Page Pool

Launching a new Chromium process per request does not scale. Startup latency, renderer memory overhead, and unbounded concurrency will eventually collapse the service.

This guide shows a production-ready page-pool architecture in .NET using PuppeteerSharp.

Why It Matters

Reduces per-request rendering latency.
Prevents memory spikes from unbounded browser/page creation.
Adds backpressure under load instead of crashing.
Improves reliability with health checks and page recycling.

Core Concepts

1. Split Responsibilities by File

Recommended structure:

PooledChromiumPdfEngine.cs
ChromiumRenderingHealthCheck.cs
ChromiumRenderingServiceCollectionExtensions.cs
Program.cs
PdfRenderController.cs
appsettings.json

2. Use a Bounded Page Pool

Use Channel<IPage> as a reusable page pool and concurrency limiter.

using System.Threading.Channels;
using PuppeteerSharp;

public sealed class PooledChromiumPdfEngine
{
    private IBrowser? _browserInstance;
    private readonly int _maxPooledPages;
    private readonly Channel<IPage> _availablePages;

    public PooledChromiumPdfEngine(IConfiguration configuration)
    {
        var configuredPageLimit = configuration.GetValue<int>("PdfRendering:MaxConcurrentPages");

        if (configuredPageLimit < 1 || configuredPageLimit > 64)
            throw new ArgumentOutOfRangeException(nameof(configuredPageLimit));

        _maxPooledPages = configuredPageLimit;
        _availablePages = Channel.CreateBounded<IPage>(new BoundedChannelOptions(_maxPooledPages)
        {
            FullMode = BoundedChannelFullMode.Wait,
            SingleReader = false,
            SingleWriter = false
        });
    }
}

3. Warm Up Browser and Pages at Startup

Initialize Chromium once and pre-create pool pages.

public async Task WarmUpAsync()
{
    var executablePath = Environment.GetEnvironmentVariable("PUPPETEER_EXECUTABLE_PATH");

    if (string.IsNullOrWhiteSpace(executablePath) || !File.Exists(executablePath))
    {
        var revision = await new BrowserFetcher().DownloadAsync();
        executablePath = revision.GetExecutablePath();
    }

    _browserInstance = await Puppeteer.LaunchAsync(new LaunchOptions
    {
        ExecutablePath = executablePath,
        Headless = true,
        Timeout = 300000,
        Args =
        [
            "--no-sandbox",
            "--disable-setuid-sandbox",
            "--disable-dev-shm-usage",
            "--disable-gpu",
            "--disable-extensions"
        ]
    });

    for (var i = 0; i < _maxPooledPages; i++)
    {
        var page = await _browserInstance.NewPageAsync();
        await page.SetJavaScriptEnabledAsync(false);
        await _availablePages.Writer.WriteAsync(page);
    }
}

4. Render with Checkout/Return Pattern

Each request borrows one page, renders, then returns or replaces it.

public async Task<byte[]> RenderAsync(string htmlMarkup)
{
    if (_browserInstance == null || !_browserInstance.IsConnected)
        throw new InvalidOperationException("Chromium backend unavailable.");

    var page = await _availablePages.Reader.ReadAsync();
    var shouldRecyclePage = true;

    try
    {
        await page.SetContentAsync(htmlMarkup, new NavigationOptions
        {
            WaitUntil = [WaitUntilNavigation.Load],
            Timeout = 300000
        });

        var pdfBytes = await page.PdfDataAsync(new PdfOptions
        {
            PrintBackground = true,
            Format = PaperFormat.A4
        });

        shouldRecyclePage = false;
        return pdfBytes;
    }
    finally
    {
        if (shouldRecyclePage || page.IsClosed)
        {
            if (!page.IsClosed)
                await page.DisposeAsync();

            page = await _browserInstance.NewPageAsync();
            await page.SetJavaScriptEnabledAsync(false);
        }

        await page.GoToAsync("about:blank");
        await _availablePages.Writer.WriteAsync(page);
    }
}

5. Add Health Check Integration

public sealed class ChromiumRenderingHealthCheck(
    PooledChromiumPdfEngine pdfEngine) : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        return await pdfEngine.IsBrowserResponsiveAsync(cancellationToken)
            ? HealthCheckResult.Healthy()
            : HealthCheckResult.Unhealthy();
    }
}

6. Register via DI Extensions

public static class ChromiumRenderingServiceCollectionExtensions
{
    public static IServiceCollection AddChromiumPdfEngine(this IServiceCollection services)
    {
        services.AddSingleton<PooledChromiumPdfEngine>();
        services.AddSingleton<IHealthCheck, ChromiumRenderingHealthCheck>();
        return services;
    }

    public static async Task WarmUpChromiumPdfEngineAsync(this IServiceProvider provider)
    {
        var engine = provider.GetRequiredService<PooledChromiumPdfEngine>();
        await engine.WarmUpAsync();
    }
}

Practical Example

Program Startup

builder.Services
    .AddChromiumPdfEngine()
    .AddHealthChecks()
    .AddCheck<ChromiumRenderingHealthCheck>(nameof(ChromiumRenderingHealthCheck));

var app = builder.Build();

await app.Services.WarmUpChromiumPdfEngineAsync();

app.MapHealthChecks("/healthz");
app.Run();

API Endpoint

[ApiController]
public sealed class PdfRenderController(PooledChromiumPdfEngine pdfEngine) : ControllerBase
{
    [HttpPost("/api/render/pdf")]
    public async Task<IActionResult> RenderPdfAsync([FromBody] string htmlMarkup)
    {
        var pdfBytes = await pdfEngine.RenderAsync(htmlMarkup);
        return File(pdfBytes, "application/pdf");
    }
}

This keeps controllers thin and rendering complexity isolated where it belongs.

Common Mistakes

Launching Chromium per request.
No bounded concurrency control for render pages.
Returning dirty/crashed pages to pool.
Skipping startup warm-up and paying first-request penalty.
No health probe for browser responsiveness.

Quick Recap

One browser instance, many pooled pages.
Bounded channel enforces concurrency/backpressure.
Warm-up pages at startup for predictable latency.
Recycle unhealthy pages immediately.
Wire health checks and DI for operational stability.

Next Steps

Add load tests to tune MaxConcurrentPages against memory limits.
Add metrics for checkout wait time and render duration.
Add graceful shutdown disposal for browser/page resources.
Add HTML sanitization and template validation for input safety.

DEV Community: ZèD

Implementing Soft Delete with Filtered Indexes in Entity Framework Core

Soft Delete with Global Query Filters and Filtered Indexes in Entity Framework Core

The Core Idea

Turn Deletes Into Updates

Filter Rows By Default

Protect Unique Constraints

Restore Safely

Design Notes

When This Pattern Fits

Conclusion

References

Building Dynamic Filters in Clean Architecture (CQRS) using ExpressionBuilder

Building Dynamic Filters in Clean Architecture with ExpressionBuilder

Why It Matters

Core Concepts

1. Pass Expressions Instead of Queries

2. Reassigning Filters Does Not Scale

3. ExpressionBuilder Collects Predicate Blocks

4. Parameter Rewriting Makes the Final Expression Valid

Practical Example

ExpressionBuilder<T>

Minimal Example: One Required Condition

Minimal Example: Required and Optional Conditions

Minimal Example: Grouped Logic Inside One Block

Using It in a Query Handler

Repository Side

Common Mistakes

Quick Recap

Next Steps

Cursor vs Offset Pagination in EF Core: What Actually Works in Production

Cursor vs Offset Pagination in EF Core: What Actually Works in Production

Why This Matters

1. Offset Pagination (Skip/Take)

Why it works well

Where it breaks

2. Cursor Pagination (Keyset)

Why it works better for large data

3. Ordering Must Be Stable

4. Performance Comparison

5. Limitations of Cursor Pagination

6. When to Use What

Use offset pagination when:

Use cursor pagination when:

7. Practical Recommendation

8. Indexing Matters

Quick Recap

Final Thought

Understanding EF.Functions.Like and ILike in Entity Framework Core

Understanding EF.Functions.Like and ILike in Entity Framework Core

Why It Matters

Core Concepts

1. What Like Does

2. What ILike Does

3. Replacing Common String Methods

4. Example with Like

5. Example with ILike

6. Provider and Collation Behavior

Practical Example

Common Mistakes

Quick Recap

Next Steps

BCrypt vs Argon2: Password Hashing in .NET – A Practical Deep Dive

BCrypt vs Argon2 Password Hashing in .NET: A Practical Deep Dive

Why It Matters

Core Concepts

1. Why Fast Hashes Are Not Enough

2. BCrypt Basics

3. Argon2 Basics

4. Internal Difference Summary

5. Parameter Tuning Reality

6. Migration Strategy

Practical Example

Common Mistakes

Quick Recap

Next Steps

Implementing Event-Driven Order Processing with Kafka using KafkaFlow in .NET

Implementing Event-Driven Order Processing with Kafka Using KafkaFlow in .NET

Why It Matters

Core Concepts

`ExpressionBuilder<T>`

1. What `Like` Does

2. What `ILike` Does

4. Example with `Like`

5. Example with `ILike`