DEV Community: ZèD

Configuring GitHub Container Registry with Kubernetes for Private Images

ZèD — Thu, 14 May 2026 15:36:42 +0000

Configuring GitHub Container Registry with Kubernetes for Private Images

Private container images are common in real production workloads. Your app image might live in GitHub Container Registry, but Kubernetes cannot pull that image unless the cluster has valid registry credentials.

This guide shows a YAML-first setup for pulling private images from GitHub Container Registry in Kubernetes.

GitHub Container Registry uses ghcr.io, and private image pulls require authentication. GitHub documents personal access token authentication for Container Registry, and private package access usually needs at least read:packages. (GitHub Docs)

Why It Matters

Keep application images private.
Deploy private images directly from ghcr.io.
Avoid manual login on cluster nodes.
Keep workload YAML clean with ServiceAccounts.
Fits well with GitOps, CI/CD, Helm, and Kustomize.

Core Concepts

1. GitHub Container Registry Image

A private GHCR image usually looks like this:

ghcr.io/OWNER/IMAGE_NAME:TAG

Example:

ghcr.io/my-org/private-api:1.0.0

Kubernetes will try to pull this image when the Pod starts. If the image is private and no credentials are configured, the Pod will fail with errors like:

ImagePullBackOff
ErrImagePull
unauthorized

2. Registry Credential Secret

Kubernetes uses an image pull Secret to authenticate with a private registry. The standard Secret type is:

kubernetes.io/dockerconfigjson

Kubernetes supports using a Secret with private registry credentials and referencing it through imagePullSecrets in a Pod spec. (Kubernetes)

The Docker config JSON looks like this before base64 encoding:

{
  "auths": {
    "ghcr.io": {
      "username": "YOUR_GITHUB_USERNAME",
      "password": "YOUR_GITHUB_TOKEN",
      "email": "you@example.com",
      "auth": "BASE64_USERNAME_COLON_TOKEN"
    }
  }
}

The auth value is:

base64(YOUR_GITHUB_USERNAME:YOUR_GITHUB_TOKEN)

Then the whole JSON content is base64 encoded and placed in the Kubernetes Secret.

apiVersion: v1
kind: Secret
metadata:
  name: ghcr-secret
  namespace: demo
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: BASE64_DOCKER_CONFIG_JSON

This Secret must exist in the same namespace as the Pod that uses it.

3. ServiceAccount-Based Image Pull

Instead of adding imagePullSecrets to every Deployment, attach it to a ServiceAccount.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-service-account
  namespace: demo
imagePullSecrets:
  - name: ghcr-secret

A ServiceAccount gives an identity to Pods, and Pods can be configured to use a specific ServiceAccount. Kubernetes documents ServiceAccounts as API objects used by processes running inside Pods. (Kubernetes)

This keeps the Deployment clean.

4. Deployment Using the ServiceAccount

Now the Deployment only needs to reference the ServiceAccount.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: private-api
  namespace: demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: private-api
  template:
    metadata:
      labels:
        app: private-api
    spec:
      serviceAccountName: app-service-account
      containers:
        - name: private-api
          image: ghcr.io/my-org/private-api:1.0.0
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8080

At startup, Kubernetes uses the ServiceAccount’s imagePullSecrets, reads the GHCR credentials, and pulls the private image. Clean Deployment YAML, no repeated registry config drama.

5. Complete YAML Setup

A minimal full setup can be kept in one file:

apiVersion: v1
kind: Namespace
metadata:
  name: demo

---
apiVersion: v1
kind: Secret
metadata:
  name: ghcr-secret
  namespace: demo
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: BASE64_DOCKER_CONFIG_JSON

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-service-account
  namespace: demo
imagePullSecrets:
  - name: ghcr-secret

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: private-api
  namespace: demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: private-api
  template:
    metadata:
      labels:
        app: private-api
    spec:
      serviceAccountName: app-service-account
      containers:
        - name: private-api
          image: ghcr.io/my-org/private-api:1.0.0
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8080

Practical Example

Suppose your private image is:

ghcr.io/octocat/order-service:2026.05.14

Your Kubernetes objects should look like this:

apiVersion: v1
kind: Namespace
metadata:
  name: production

---
apiVersion: v1
kind: Secret
metadata:
  name: ghcr-secret
  namespace: production
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: BASE64_DOCKER_CONFIG_JSON

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: order-service-sa
  namespace: production
imagePullSecrets:
  - name: ghcr-secret

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  namespace: production
spec:
  replicas: 2
  selector:
    matchLabels:
      app: order-service
  template:
    metadata:
      labels:
        app: order-service
    spec:
      serviceAccountName: order-service-sa
      containers:
        - name: order-service
          image: ghcr.io/octocat/order-service:2026.05.14
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8080

Same cluster, private image, YAML-managed deployment, zero manual registry login.

Alternative: Direct `imagePullSecrets`

For small apps, you can reference the Secret directly from the Deployment.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: private-api
  namespace: demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: private-api
  template:
    metadata:
      labels:
        app: private-api
    spec:
      imagePullSecrets:
        - name: ghcr-secret
      containers:
        - name: private-api
          image: ghcr.io/my-org/private-api:1.0.0

This works, but it gets repetitive when many workloads need private images.

The ServiceAccount approach is usually cleaner.

GitOps-Friendly Secret Handling

Raw Kubernetes Secrets are only base64 encoded. They are not encrypted.

Avoid committing this directly to Git:

data:
  .dockerconfigjson: BASE64_DOCKER_CONFIG_JSON

Better production options:

Sealed Secrets
External Secrets Operator
SOPS with age or KMS
Vault
AWS Secrets Manager
Google Secret Manager
Azure Key Vault

A better flow is:

Secret Manager
  -> ExternalSecret
  -> Kubernetes Secret
  -> ServiceAccount
  -> Deployment

Example ExternalSecret shape:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: ghcr-secret
  namespace: demo
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: cluster-secret-store
    kind: ClusterSecretStore
  target:
    name: ghcr-secret
    creationPolicy: Owner
    template:
      type: kubernetes.io/dockerconfigjson
      data:
        .dockerconfigjson: |
          {
            "auths": {
              "ghcr.io": {
                "username": "{{ .githubUsername }}",
                "password": "{{ .githubToken }}",
                "email": "you@example.com",
                "auth": "{{ printf "%s:%s" .githubUsername .githubToken | b64enc }}"
              }
            }
          }
  data:
    - secretKey: githubUsername
      remoteRef:
        key: github-username
    - secretKey: githubToken
      remoteRef:
        key: github-token

Common Mistakes

Creating the Secret in the wrong namespace.
Using a GitHub token without read:packages.
Forgetting to give the token access to the private package or repository.
Committing raw base64 Kubernetes Secrets to Git.
Adding imagePullSecrets to the Deployment but using a different ServiceAccount setup.
Typing the image path incorrectly, especially the owner or package name.
Using latest everywhere and not knowing what version is running.

Quick Recap

GHCR private images need registry authentication.
Kubernetes uses kubernetes.io/dockerconfigjson Secrets for private registry pulls.
Attach the Secret to a ServiceAccount for clean workload YAML.
Use serviceAccountName in the Deployment.
Store real credentials outside Git when possible.
Prefer pinned image tags over latest.

Next Steps

Move the GHCR token into External Secrets or Sealed Secrets.
Create one ServiceAccount per application or namespace.
Add image tag promotion through CI/CD.
Rotate GitHub package tokens periodically.
Add deployment checks for ImagePullBackOff and failed image pulls.

SQL-First-in-Migrations: Governing Every Database Artifact Through EF Core Migrations

ZèD — Tue, 12 May 2026 11:12:11 +0000

SQL-First-in-Migrations: Governing Every Database Artifact Through EF Core Migrations

1. Introduction

Entity Framework Core's code-first approach is frequently understood as limited to entity classes and their table mappings. A production database contains more than tables: views, functions, stored procedures, triggers, indexes that EF Core does not natively model, and baseline operational data. If these artifacts are created or managed outside the migration stream, the project loses the single source of truth that code-first promises.

The solution is to treat any SQL object on which the system depends as a first-class migration artifact. The pattern uses the EF Core migration timeline as the authoritative history for schema changes, SQL object changes, and baseline data, all driven from versioned SQL files.

2. The Core Idea

EF Core's MigrationBuilder already records every entity-model change as a C# migration. This pattern extends that single timeline to include every other database concern:

Stored procedures
Functions
Views (including materialized views)
Triggers
Custom indexes or constraints not mapped by EF
Seed or baseline data that the system requires to function

By routing all of these through MigrationBuilder.Sql, the migration order remains deterministic, the history auditable, and the database fully reproducible from source control.

3. The Pattern

The migration class remains thin, acting as an orchestrator that delegates SQL content to external files. The following example creates a stored procedure that calculates order totals:

public partial class AddCalculateOrderTotalsStoredProc : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.Sql(
            SqlFileLoader.Read("StoredProcedures/CalculateOrderTotals/v1/Up.sql"));
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.Sql(
            SqlFileLoader.Read("StoredProcedures/CalculateOrderTotals/v1/Down.sql"));
    }
}

The SqlFileLoader helper reads raw SQL from embedded resources, decoupling SQL logic from C# string literals entirely:

using System.Reflection;

namespace YourApp.Persistence.Helpers;

public static class SqlFileLoader
{
    private const string RootNamespace = "YourApp.Persistence.SqlScripts";

    public static string Read(string relativePath)
    {
        var resourceName = $"{RootNamespace}.{relativePath.Replace('\\', '.').Replace('/', '.')}";

        using var stream = Assembly.GetExecutingAssembly().GetManifestResourceStream(resourceName)
            ?? throw new FileNotFoundException($"Embedded SQL script not found: {resourceName}");

        using var reader = new StreamReader(stream);

        return reader.ReadToEnd();
    }
}

The versioned folder convention (v1, v2, ...) ensures that each deployed SQL file remains immutable; changes spawn a new version folder, preserving the full history.

4. Why This Works Better Than Inline SQL

Inline SQL embedded in C# migration classes creates several problems. SQL mixed with string concatenation is difficult to read and review. When a reviewer examines a diff, they must mentally separate C# logic from SQL. Complex procedural logic written in languages such as PL/pgSQL or T-SQL becomes painful to manage inside string literals. Rollback logic must be manually mirrored in the Down method, often leading to mistakes.

External SQL files solve these issues. The SQL code lives in its native syntax and benefits from syntax highlighting in editors. The Up.sql / Down.sql pairing makes reversibility explicit and testable. Database administrators can review pure SQL changes without opening a C# file. The separation also allows the same migration to be applied to different database providers by swapping the SQL file set.

5. Real-World Use Cases

5.1 Stored Procedures

A stored procedure that aggregates order line items and updates the total_amount column on the orders table.

Up.sql

CREATE OR REPLACE PROCEDURE calculate_order_totals()
LANGUAGE plpgsql
AS $$
BEGIN
    UPDATE orders o
    SET total_amount = sub.total
    FROM (
        SELECT order_id, SUM(price * quantity * (1 - discount)) AS total
        FROM order_items
        GROUP BY order_id
    ) sub
    WHERE o.id = sub.order_id;
END;
$$;

Down.sql

DROP PROCEDURE IF EXISTS calculate_order_totals();

The migration references these files using SqlFileLoader.Read("StoredProcedures/CalculateOrderTotals/v1/Up.sql").

5.2 Functions

A scalar function that returns a formatted full name, used in reporting queries where EF Core's LINQ translation would be inefficient.

Up.sql

CREATE OR REPLACE FUNCTION get_user_full_name(first_name text, last_name text)
RETURNS text
LANGUAGE sql
IMMUTABLE
AS $$
    SELECT TRIM(first_name || ' ' || last_name);
$$;

Down.sql

DROP FUNCTION IF EXISTS get_user_full_name(text, text);

5.3 Views

A view that filters out soft-deleted users, encapsulating the filtering logic so that multiple application queries do not repeat the condition.

Up.sql

CREATE VIEW active_users AS
SELECT id, email, first_name, last_name, created_at
FROM users
WHERE is_deleted = false;

Down.sql

DROP VIEW IF EXISTS active_users;

For materialized views, the Up.sql would include CREATE MATERIALIZED VIEW and any required index creation; the Down.sql drops the materialized view and its indexes, restoring the pre-migration state.

5.4 Custom Indexes Not Modeled by EF

EF Core can model many indexes through attributes or the Fluent API. However, specialized indexes such as filtered indexes, partial indexes, or PostgreSQL GIN/GiST indexes often require raw SQL. The pattern handles them naturally:

// Inside a migration Up method
migrationBuilder.Sql("CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_events_timestamp ON events (timestamp);");

Because the C# class owns the migration timestamp, the index creation is sequenced relative to all other schema changes, eliminating the risk of race conditions that arise from running ad-hoc scripts.

5.5 Seed / Baseline Data

Some data is not optional; the application requires a known set of product categories, configuration rows, or lookup values to function correctly. The pattern treats these as versioned SQL inserts.

Up.sql

INSERT INTO product_categories (id, name)
VALUES
    (1, 'Electronics'),
    (2, 'Books'),
    (3, 'Clothing')
ON CONFLICT (id) DO NOTHING;

-- Reset the sequence if using serial/bigserial primary keys
SELECT setval('product_categories_id_seq', (SELECT MAX(id) FROM product_categories));

Down.sql

DELETE FROM product_categories WHERE id IN (1, 2, 3);

The migration SeedBaseCategories places the SQL files in SeedData/BaseCategories/v1/ and calls SqlFileLoader.Read in exactly the same way as any other artifact.

6. Recommended Project Structure

All SQL scripts reside under a SqlScripts folder inside the persistence project. They are embedded resources and accessed via the SqlFileLoader. The folder layout mirrors the artifact type and name.

YourApp.Persistence/
  Migrations/
    20260421062959_SeedBaseCategories.cs
    20260501000000_AddCalculateOrderTotalsStoredProc.cs
    20260505120000_AddGetUserFullNameFunction.cs
    20260510120000_AddActiveUsersView.cs
  SqlScripts/
    StoredProcedures/
      CalculateOrderTotals/
        v1/
          Up.sql
          Down.sql
    Functions/
      GetUserFullName/
        v1/
          Up.sql
          Down.sql
    Views/
      ActiveUsers/
        v1/
          Up.sql
          Down.sql
    SeedData/
      BaseCategories/
        v1/
          Up.sql
          Down.sql
  Helpers/
    SqlFileLoader.cs

Each version folder is immutable after deployment. When the logic changes, a new version folder (v2) is added and the corresponding migration references it.

7. Implementation Details

7.1 SqlFileLoader Configuration

All .sql files must have their Build Action set to Embedded resource. The RootNamespace in SqlFileLoader must match the assembly's root namespace plus the folder path to the scripts. The helper converts path separators to dots to form the full resource name.

For multi-provider support, you can extend the helper to select a provider-specific file (for example, Up.psql.sql vs. Up.mssql.sql) based on MigrationBuilder.ActiveProvider.

7.2 Migration Scaffolding Workflow

When adding a new SQL-backed artifact:

Create the migration shell: dotnet ef migrations add AddMyNewView.
Remove the auto-generated body from Up() and Down() if any.
Create the versioned SQL files in the appropriate folder under SqlScripts.
Call SqlFileLoader.Read inside the migration methods.
Test both Up and Down against a development database.

7.3 Deterministic Rollback

Because every Up.sql is paired with a corresponding Down.sql, rolling back a migration is deterministic. This is difficult to guarantee when SQL statements are interleaved with C# operations. The pairing is critical for CI/CD pipelines that apply migrations in one direction and may need to reverse them in a disaster-recovery scenario.

8. When This Pattern Fits

The pattern is suitable when the project requires:

EF migration ordering combined with native SQL power.
Full source-controlled database history that includes tables, functions, procedures, views, and baseline data.
Reliable environment parity across development, staging, and production.
Code-first governance that extends beyond entity tables to all database objects the application uses.

This pattern does not replace EF's model-driven migrations. It complements them for the portion of the database surface that EF cannot model declaratively. The EF Core documentation itself recommends custom operations via Sql() as the extension point when built-in operations are insufficient.

9. Conclusion

The value of this pattern lies not in placing seed data inside a migration, but in treating SQL artifacts as first-class migration history. The migration timeline becomes the single source of truth for every database object the system depends on.

By keeping migration classes thin and delegating SQL to versioned files, teams gain:

Clean, reviewable code diffs
Native SQL syntax for complex logic
Reversible, testable deployments
A single, reproducible timeline of the entire database state

Whether the artifact is a stored procedure, a view, a function, or a set of baseline rows, the pattern scales naturally and keeps the project truly code-first, not just entity-first.

References

Microsoft Docs. "Custom Migrations Operations - EF Core." learn.microsoft.com (see MigrationBuilder.Sql).
EF Core Issues. "Adding Stored Procedures/View/Functions using Function within the migration flow." GitHub/dotnet/efcore #34469.
EF Core Docs. "Managing Migrations - Custom DDL Examples." GitHub/dotnet/EntityFramework.Docs #694.
Npgsql EF Core Provider. "Migrations and Schema Management." DeepWiki.
Redgate. "Working with Flyway and Entity Framework Code First: An Overview." Redgate Blog.
SSW Rules. "Do you save each script as you go?" SSW Rules.
EFCore.MigrationExtensions. "NuGet Package for PostgreSQL SQL Objects in Migrations." NuGet.

Atomic Redis Value Replacement Without Downtime: The Temporary Key Pattern

ZèD — Wed, 29 Apr 2026 17:41:50 +0000

Atomic Redis Value Replacement Without Downtime: The Temporary Key Pattern

When Redis holds mission‑critical data—authorization rules, feature flags, live configuration—native key updates can cause outages. A simple DELETE followed by SET opens a window where the key doesn’t exist, and a HSET on a live hash can leave stale fields behind. The temporary key pattern uses Redis’s atomic RENAME to swap entire data structures in one seamless motion. No gap, no stale leftovers. Let’s see how to implement it in C# with StackExchange.Redis, and later add a distributed lock so even concurrent writers can’t trip each other.

The Problem: Delete First, Set Later

When you need to replace an entire Redis value, the first instinct looks like this:

await db.KeyDeleteAsync("config:site");
await db.StringSetAsync("config:site", newJson);

Between the two commands the key is gone. Any concurrent reader gets a null (or a default), which for critical data can throw the whole system off. Even worse, if StringSetAsync throws, the data is permanently lost until someone runs a backfill job.

For cache‑only data you might tolerate this. For anything that acts as a source of truth, it’s a ticking bomb.

The Merge Trap: Hash and Set Updates That Won’t Go Away

A common attempt to avoid the gap is updating a hash field by field:

await db.HashSetAsync("user:123:meta", new HashEntry[] {
    new("role", "user")
});

HSET only adds or overwrites the fields you pass. It never deletes fields that were present before. If the previous state had beta_access: true, it stays—and suddenly a downgraded user still enjoys beta features. The same happens with Set if you only add members but never remove the old ones.

You could call KeyDelete first, but that brings back the empty‑window problem. So we need a way to completely swap the data structure without ever exposing an empty or stale version.

The Solution: Write to a Temporary Key, Then Swap

The pattern is simple enough to fit on a sticky note:

Write the brand‑new, complete value into a temporary key (e.g., key:tmp).
Use the RENAME command to atomically replace the real key with the temporary one.

RENAME is a single Redis command. It deletes the destination if it exists and renames the source in one step. Readers will see either the old, fully correct data, or the new, fully correct data—nothing in between.

We’ll use StackExchange.Redis transactions to bundle the write and the rename together, so a failure during population leaves the original key untouched.

Generic String Replacement Helper

If you store serialized objects as JSON (or any byte blob), here’s a reusable method:

public async Task<bool> ReplaceAsync<T>(
    IDatabase db, string key, T value, TimeSpan? expiry = null)
{
    string tempKey = $"{key}:tmp";
    TimeSpan ttl = expiry ?? TimeSpan.FromHours(1);

    var txn = db.CreateTransaction();

    // Write the complete serialized object to temp key
    var setTask = txn.StringSetAsync(
        tempKey, JsonSerializer.Serialize(value), ttl);

    // Atomically rename: this is the magic
    var renameTask = txn.KeyRenameAsync(tempKey, key);

    bool committed = await txn.ExecuteAsync();
    await Task.WhenAll(setTask, renameTask);

    return committed;
}

You call it like this:

var myConfig = new { Theme = "dark", CacheTimeout = 30 };
bool ok = await ReplaceAsync(db, "app:config", myConfig);

No need to delete, no chance for an empty read. If the transaction fails, key remains completely untouched and you can retry.

Why a Transaction Matters

You might ask: can’t I just chain StringSetAsync and KeyRenameAsync without CreateTransaction? Technically yes, but if the StringSetAsync succeeds and the KeyRenameAsync fails (network blip), the :tmp key is left dangling and the real key still holds old data. That’s not disastrous, but it’s a cleanup headache. A transaction ensures both commands are queued together (MULTI/EXEC)—they either both happen or both don’t. Atomicity at the network round‑trip level.

Note: The transaction doesn’t isolate reads from outside clients. But because RENAME itself is a single atomic command, the viewer never sees the intermediate :tmp key in the real key’s place. The old value transparently turns into the new one.

Replacing a Set the Same Way

Need to refresh a set of allowed IPs or permission identifiers? Use exactly the same pattern:

public async Task ReplaceSetAsync(
    IDatabase db, string key, string[] members)
{
    string tempKey = $"{key}:tmp";

    var txn = db.CreateTransaction();

    // Clean any leftover temp key from a previous crash
    txn.KeyDeleteAsync(tempKey);

    // Add all new members to the temp set
    txn.SetAddAsync(tempKey, members.Select(m => (RedisValue)m).ToArray());

    // Atomically swap
    txn.KeyRenameAsync(tempKey, key);

    await txn.ExecuteAsync();
}

No members get lost, no members stay behind that should have been removed. The set is replaced in one instant.

await ReplaceSetAsync(db, "ip:allowlist", new[] { "10.0.0.1", "10.0.0.2" });

Replacing a Hash: Fields Come and Go Together

This is the fix for the stale‑admin story (you know the one). Instead of calling HashSet on the live key, do this:

public async Task ReplaceHashAsync(
    IDatabase db, string key, HashEntry[] entries)
{
    string tempKey = $"{key}:tmp";

    var txn = db.CreateTransaction();
    txn.KeyDeleteAsync(tempKey);
    txn.HashSetAsync(tempKey, entries);
    txn.KeyRenameAsync(tempKey, key);

    await txn.ExecuteAsync();
}

Now every old field disappears because you replace the entire hash.

await ReplaceHashAsync(db, "user:123:meta", new HashEntry[] {
    new("role", "user")
    // beta_access is gone – intentionally
});

Redis Cluster? Keep the Keys Together

If you run Redis Cluster, RENAME only works when source and destination are in the same hash slot. Use curly‑brace hash tags to enforce that:

string mainKey = $"{{user:{userId}}}:permissions";
string tempKey = $"{{user:{userId}}}:permissions:tmp";

Redis calculates the slot based on the substring inside the {}. Both keys end up on the same node, and the rename works without a cross‑slot error.

When Things Don’t Go as Planned

Even an atomic pattern needs a safety net.

Transaction fails (ExecuteAsync returns false): The original key is untouched. Just retry. If the temp key already existed (a previous crash), the KeyDeleteAsync inside the transaction clears it first.
Crash after :tmp is written but before rename: The temp key hangs around. The expiry on the string helper will clean it automatically after TTL. For sets and hashes you can add an explicit KeyExpireAsync(tempKey, TimeSpan.FromMinutes(5)) inside the transaction or run a janitor that deletes keys matching *:tmp that are older than a few minutes.
Multiple writers racing on the same key: The rename pattern alone doesn’t prevent two processes from both writing to :tmp and trying to rename. One will overwrite the other’s work, and there’s no guarantee which one survives. We can fix this with a distributed lock.

Taking It Further with a Distributed Lock

If more than one process can trigger a replacement for the same key—like two admin panels or concurrent background jobs—you need a mutex to serialize the operation. StackExchange.Redis provides built‑in primitives for that: LockTake and LockRelease.

Here’s a generic locking helper that executes any action under a Redis‑based lock:

public async Task<bool> ExecuteWithLockAsync(
    IDatabase db, string lockKey, TimeSpan lockExpiry, Func<Task> action)
{
    string token = Guid.NewGuid().ToString("N");
    bool acquired = await db.LockTakeAsync(lockKey, token, lockExpiry);

    if (!acquired)
        return false;

    try
    {
        await action();
        return true;
    }
    finally
    {
        // Release the lock – fire‑and‑forget is enough here
        await db.LockReleaseAsync(lockKey, token, CommandFlags.FireAndForget);
    }
}

The token ensures only the locker can release the lock. If the process crashes, the lock auto‑expires after lockExpiry, preventing deadlocks.

Now wrap any of the Replace* methods. For example, safe set replacement with a lock:

public async Task SafeReplaceSetAsync(
    IDatabase db, string key, string[] members)
{
    string lockKey = $"lock:{key}";
    TimeSpan lockExpiry = TimeSpan.FromSeconds(10);

    bool lockAcquired = await ExecuteWithLockAsync(
        db, lockKey, lockExpiry, () => ReplaceSetAsync(db, key, members));

    if (!lockAcquired)
        throw new Exception("Could not acquire lock for replacement");
}

What we gain:

Serialized writers: Only one updater touches the temp key at a time. No more last‑writer‑wins anarchy.
Complete safety: The lock is held only around the write + rename transaction, not during data preparation.
No external packages: Everything uses the same IDatabase instance and standard Redis commands.

You can apply the same wrapper to ReplaceHashAsync or ReplaceAsync<T>. Just pick a lock expiry longer than your worst‑case operation time.

This Trick Is Old and Everywhere

The idea of “write to a temp file and rename” is used by Linux package managers, file systems, and even Redis internally for its own persistence. It’s not a workaround—it’s the standard way to atomically replace something that can’t be replaced in‑place. Adding a lock turns a great trick into a bulletproof asset.

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.

DEV Community: ZèD

Configuring GitHub Container Registry with Kubernetes for Private Images

Configuring GitHub Container Registry with Kubernetes for Private Images

Why It Matters

Core Concepts

1. GitHub Container Registry Image

2. Registry Credential Secret

3. ServiceAccount-Based Image Pull

4. Deployment Using the ServiceAccount

5. Complete YAML Setup

Practical Example

Alternative: Direct imagePullSecrets

GitOps-Friendly Secret Handling

Common Mistakes

Quick Recap

Next Steps

SQL-First-in-Migrations: Governing Every Database Artifact Through EF Core Migrations

SQL-First-in-Migrations: Governing Every Database Artifact Through EF Core Migrations

1. Introduction

2. The Core Idea

3. The Pattern

4. Why This Works Better Than Inline SQL

5. Real-World Use Cases

5.1 Stored Procedures

5.2 Functions

5.3 Views

5.4 Custom Indexes Not Modeled by EF

5.5 Seed / Baseline Data

6. Recommended Project Structure

7. Implementation Details

7.1 SqlFileLoader Configuration

7.2 Migration Scaffolding Workflow

7.3 Deterministic Rollback

8. When This Pattern Fits

9. Conclusion

References

Atomic Redis Value Replacement Without Downtime: The Temporary Key Pattern

Atomic Redis Value Replacement Without Downtime: The Temporary Key Pattern

The Problem: Delete First, Set Later

The Merge Trap: Hash and Set Updates That Won’t Go Away

The Solution: Write to a Temporary Key, Then Swap

Generic String Replacement Helper

Why a Transaction Matters

Replacing a Set the Same Way

Replacing a Hash: Fields Come and Go Together

Redis Cluster? Keep the Keys Together

When Things Don’t Go as Planned

Taking It Further with a Distributed Lock

This Trick Is Old and Everywhere

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

Alternative: Direct `imagePullSecrets`

`ExpressionBuilder<T>`

1. What `Like` Does

2. What `ILike` Does

4. Example with `Like`

5. Example with `ILike`