Forem: Adrián Bailador

🚀 I've been quietly building new features into The Coffee Timer ☕ — my Pomodoro productivity app — and I'm excited to share what's new!

Adrián Bailador — Sun, 12 Apr 2026 19:24:04 +0000

Here's what just shipped:

☕ Focus Stats Dashboard — See your last 7 days of focus time, top tasks by

pomodoros, and key productivity metrics. (Premium)

🗺️ Interactive Onboarding Tour — A step-by-step guided tour with spotlight

tooltips so new users know exactly what everything does from day one.

🌍 Spanish / English toggle — One click to switch the entire UI between EN
and ES. Building for a global audience from the start.

All of this on top of Spotify integration, ambient sounds, streak tracking, and a beautiful coffee cup that fills as you work. ☕

If you're curious, give it a try → https://thecoffeetimer.com/

Built with React, TypeScript, .NET 8, Supabase & Stripe. Solo project, shipping fast. 🛠️

Health Checks in ASP.NET Core: Beyond the Basic /health Endpoint

Adrián Bailador — Sun, 12 Apr 2026 11:09:54 +0000

A service returning 200 OK on /health doesn't mean it's healthy. It means the process is alive and the route handler executed. Your database could be unreachable, your message broker offline, your disk at 99% capacity — and /health would still return green.

I've seen this exact situation cause a silent outage. The load balancer was happy, Kubernetes wasn't restarting anything, and the monitoring dashboard showed all services up. Meanwhile, every request that touched the database was failing. The health check was lying.

Here's how to make it tell the truth.

The Setup Everyone Has

// Program.cs — the version that gives you false confidence
app.MapGet("/health", () => "Healthy");

Or slightly better, using the built-in middleware:

builder.Services.AddHealthChecks();
app.MapHealthChecks("/health");

Both return 200 OK as long as the process is running. Neither checks anything meaningful.

What ASP.NET Core Health Checks Actually Give You

The Microsoft.AspNetCore.Diagnostics.HealthChecks package (included in the ASP.NET Core metapackage) provides an extensible pipeline where each check implements IHealthCheck:

public interface IHealthCheck
{
    Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default);
}

A HealthCheckResult is one of three states:

HealthCheckResult.Healthy() — everything is fine
HealthCheckResult.Degraded() — working but not at full capacity
HealthCheckResult.Unhealthy() — something is broken

The overall status of the endpoint is the worst status across all registered checks. One Unhealthy check makes the whole endpoint return 503 Service Unavailable.

Checking What Actually Matters

Database Connectivity

The most critical check for most APIs. Install the NuGet package for your database:

dotnet add package AspNetCore.HealthChecks.SqlServer
dotnet add package AspNetCore.HealthChecks.NpgSql       # PostgreSQL
dotnet add package AspNetCore.HealthChecks.MySql         # MySQL

builder.Services.AddHealthChecks()
    .AddSqlServer(
        connectionString: builder.Configuration.GetConnectionString("DefaultConnection")!,
        healthQuery: "SELECT 1",
        name: "sql-server",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["database", "sql"])
    .AddNpgSql(
        connectionString: builder.Configuration.GetConnectionString("Postgres")!,
        name: "postgresql",
        tags: ["database", "postgres"]);

A note on SELECT 1: It's the industry standard for this check — fast, universally supported, and harmless. Some purists argue it only verifies the connection, not whether the database is locked or whether the application user has write permissions. They're right. For most services, connectivity is enough. If you need deeper assurance, replace it with a lightweight query against a known table: SELECT TOP 1 1 FROM Orders WITH (NOLOCK). Just don't go overboard — a health check query that takes 500ms under load is worse than SELECT 1.

Redis Cache

dotnet add package AspNetCore.HealthChecks.Redis

builder.Services.AddHealthChecks()
    .AddRedis(
        redisConnectionString: builder.Configuration.GetConnectionString("Redis")!,
        name: "redis",
        failureStatus: HealthStatus.Degraded, // degraded, not unhealthy — cache miss is survivable
        tags: ["cache"]);

Notice I'm using Degraded here. If Redis is down, my app still works — it'll be slower, but it won't fail. This distinction matters for Kubernetes probes, as we'll see later.

External HTTP Dependencies

dotnet add package AspNetCore.HealthChecks.Uris

builder.Services.AddHealthChecks()
    .AddUrlGroup(
        uri: new Uri("https://api.stripe.com/v1/"),
        name: "stripe-api",
        failureStatus: HealthStatus.Degraded,
        tags: ["external"]);

Writing a Custom Health Check

When a package doesn't exist for your dependency, write your own. It's straightforward:

public class OrderServiceHealthCheck : IHealthCheck
{
    private readonly IOrderRepository _orderRepository;

    public OrderServiceHealthCheck(IOrderRepository orderRepository)
    {
        _orderRepository = orderRepository;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        try
        {
            var canConnect = await _orderRepository.CanConnectAsync(cancellationToken);

            if (!canConnect)
            {
                return HealthCheckResult.Unhealthy("Order repository is unreachable.");
            }

            var pendingOrders = await _orderRepository.GetPendingCountAsync(cancellationToken);

            // Degraded if queue is building up — not broken, but worth knowing
            if (pendingOrders > 10_000)
            {
                return HealthCheckResult.Degraded(
                    $"Order queue is growing: {pendingOrders} pending orders.",
                    data: new Dictionary<string, object> { ["pending_orders"] = pendingOrders });
            }

            return HealthCheckResult.Healthy(
                data: new Dictionary<string, object> { ["pending_orders"] = pendingOrders });
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy(
                "Order service check threw an exception.",
                exception: ex);
        }
    }
}

builder.Services.AddHealthChecks()
    .AddCheck<OrderServiceHealthCheck>(
        name: "order-service",
        failureStatus: HealthStatus.Unhealthy,
        tags: ["orders", "database"]);

Disk Space

A check that's almost always missing — and that bites you at the worst moment:

public class DiskSpaceHealthCheck : IHealthCheck
{
    private readonly long _minimumFreeBytesThreshold;

    public DiskSpaceHealthCheck(long minimumFreeMegabytes = 500)
    {
        _minimumFreeBytesThreshold = minimumFreeMegabytes * 1024 * 1024;
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        var drive = DriveInfo.GetDrives()
            .FirstOrDefault(d => d.IsReady && d.Name == "/");

        if (drive is null)
        {
            return Task.FromResult(HealthCheckResult.Unhealthy("Root drive not found."));
        }

        var freeBytes = drive.AvailableFreeSpace;
        var freeMb = freeBytes / (1024 * 1024);

        var data = new Dictionary<string, object>
        {
            ["free_mb"] = freeMb,
            ["total_mb"] = drive.TotalSize / (1024 * 1024)
        };

        if (freeBytes < _minimumFreeBytesThreshold)
        {
            return Task.FromResult(
                HealthCheckResult.Unhealthy($"Low disk space: {freeMb} MB free.", data: data));
        }

        if (freeBytes < _minimumFreeBytesThreshold * 2)
        {
            return Task.FromResult(
                HealthCheckResult.Degraded($"Disk space getting low: {freeMb} MB free.", data: data));
        }

        return Task.FromResult(HealthCheckResult.Healthy(data: data));
    }
}

Tagging Checks for Kubernetes Probes

This is where health checks go from useful to essential. Kubernetes uses three probes:

Probe	Purpose	Consequence if failing
Liveness	Is the process alive?	Restart the container
Readiness	Can it serve traffic?	Remove from load balancer
Startup	Has it finished starting up?	Don't check liveness/readiness yet

You don't want a slow Redis to restart your pod. You want it to stop receiving traffic until Redis recovers. Tags let you route different checks to different endpoints:

builder.Services.AddHealthChecks()
    .AddSqlServer(
        connectionString: connectionString,
        name: "sql-server",
        tags: ["ready"])                        // readiness only
    .AddRedis(
        redisConnectionString: redisConnection,
        name: "redis",
        failureStatus: HealthStatus.Degraded,
        tags: ["ready"])                        // readiness only
    .AddCheck<DiskSpaceHealthCheck>(
        name: "disk-space",
        tags: ["live", "ready"])                // both
    .AddCheck<OrderServiceHealthCheck>(
        name: "order-service",
        tags: ["ready"]);                       // readiness only

Map separate endpoints filtered by tag:

// Liveness — only checks the process is alive and has disk space
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,    // degraded still alive
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

// Readiness — checks everything needed to serve requests
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready"),
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,    // degraded can still serve
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

Kubernetes configuration:

livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 15
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3

startupProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 0
  periodSeconds: 5
  failureThreshold: 30   # 30 * 5s = 150 seconds to start up

Rich JSON Responses

By default, the health endpoint returns plain text (Healthy, Degraded, Unhealthy). For monitoring dashboards and debugging, you want JSON:

app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = WriteHealthCheckResponse
});

static Task WriteHealthCheckResponse(HttpContext context, HealthReport report)
{
    context.Response.ContentType = "application/json";

    var response = new
    {
        status = report.Status.ToString(),
        duration = report.TotalDuration.TotalMilliseconds,
        checks = report.Entries.Select(e => new
        {
            name = e.Key,
            status = e.Value.Status.ToString(),
            description = e.Value.Description,
            duration = e.Value.Duration.TotalMilliseconds,
            data = e.Value.Data,
            exception = e.Value.Exception?.Message
        })
    };

    return context.Response.WriteAsync(
        JsonSerializer.Serialize(response, new JsonSerializerOptions
        {
            WriteIndented = true,
            PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
        }));
}

Output:

{
  "status": "Degraded",
  "duration": 142.5,
  "checks": [
    {
      "name": "sql-server",
      "status": "Healthy",
      "duration": 12.3,
      "data": {}
    },
    {
      "name": "redis",
      "status": "Degraded",
      "description": "Redis connection timeout after 5000ms",
      "duration": 5001.2,
      "data": {}
    },
    {
      "name": "disk-space",
      "status": "Healthy",
      "duration": 0.8,
      "data": {
        "free_mb": 42301,
        "total_mb": 102400
      }
    }
  ]
}

Adding a Timeout per Check

A health check that hangs is worse than one that fails fast. Add a timeout so a slow dependency doesn't block the entire health endpoint:

public class ExternalPaymentApiHealthCheck : IHealthCheck
{
    private readonly HttpClient _httpClient;

    public ExternalPaymentApiHealthCheck(IHttpClientFactory factory)
    {
        _httpClient = factory.CreateClient("payment-api");
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        cts.CancelAfter(TimeSpan.FromSeconds(3)); // never wait more than 3 seconds

        try
        {
            var response = await _httpClient.GetAsync("/ping", cts.Token);

            return response.IsSuccessStatusCode
                ? HealthCheckResult.Healthy()
                : HealthCheckResult.Degraded($"Payment API returned {(int)response.StatusCode}");
        }
        catch (OperationCanceledException)
        {
            return HealthCheckResult.Degraded("Payment API timed out after 3 seconds.");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Payment API unreachable.", ex);
        }
    }
}

Common Mistakes

Mistake 1: Exposing health check details publicly

The JSON response with database names, connection info hints, and exception messages shouldn't be public. I've seen exception stack traces leak connection strings through a public /health/detail endpoint. Restrict it.

The simplest option is filtering by host:

// Public endpoint — minimal response
app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = (ctx, report) =>
    {
        ctx.Response.ContentType = "text/plain";
        return ctx.Response.WriteAsync(report.Status.ToString());
    }
});

// Internal endpoint — full details, restricted by host
app.MapHealthChecks("/health/detail", new HealthCheckOptions
{
    ResponseWriter = WriteHealthCheckResponse
}).RequireHost("*.internal.mycompany.com");

But in corporate environments with a Service Mesh like Istio, filtering by host can be unreliable — the mesh rewrites headers and internal routing makes RequireHost unpredictable. In those cases, a simple API key middleware is more robust:

app.MapHealthChecks("/health/detail", new HealthCheckOptions
{
    ResponseWriter = WriteHealthCheckResponse
}).AddEndpointFilter(async (context, next) =>
{
    var config = context.HttpContext.RequestServices.GetRequiredService<IConfiguration>();
    var expectedKey = config["HealthChecks:ApiKey"];
    var providedKey = context.HttpContext.Request.Headers["X-Health-Key"].FirstOrDefault();

    if (string.IsNullOrEmpty(expectedKey) || providedKey != expectedKey)
    {
        context.HttpContext.Response.StatusCode = StatusCodes.Status401Unauthorized;
        return Results.Unauthorized();
    }

    return await next(context);
});

Store the key in your secrets manager, not in appsettings.json. Your monitoring tool sends it as a header. No network topology assumptions needed.

Mistake 2: Running expensive checks too frequently

Kubernetes probes can run every 5-10 seconds. A check that runs a full database query on every probe request adds load you don't need. Cache the result:

public class CachedDatabaseHealthCheck : IHealthCheck
{
    private readonly IDbConnectionFactory _factory;
    private HealthCheckResult _cachedResult = HealthCheckResult.Healthy();
    private DateTime _lastCheck = DateTime.MinValue;
    private static readonly TimeSpan CacheDuration = TimeSpan.FromSeconds(30);

    public CachedDatabaseHealthCheck(IDbConnectionFactory factory)
    {
        _factory = factory;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        if (DateTime.UtcNow - _lastCheck < CacheDuration)
            return _cachedResult;

        try
        {
            await using var conn = await _factory.CreateConnectionAsync(cancellationToken);
            await conn.ExecuteAsync("SELECT 1");
            _cachedResult = HealthCheckResult.Healthy();
        }
        catch (Exception ex)
        {
            _cachedResult = HealthCheckResult.Unhealthy("Database check failed.", ex);
        }

        _lastCheck = DateTime.UtcNow;
        return _cachedResult;
    }
}

Mistake 3: Using the same endpoint for liveness and readiness

If your database is down and readiness returns 503, Kubernetes will also restart your pod if that same endpoint is used for liveness. You end up in a restart loop for a problem that has nothing to do with your process health. Always separate them.

Mistake 4: Not checking the things that actually fail

A health check that only verifies the process is running adds zero observability. Check the things that have actually caused incidents: the database, the message broker, the external APIs your service depends on, the file system if you write logs or uploads.

Best Practices

Name your checks clearly. sql-server, redis-cache, stripe-api — names that appear in logs and dashboards should be immediately recognizable.

Use Degraded generously. Not every problem is Unhealthy. A slow cache, a high queue depth, a non-critical external service being down — these deserve Degraded, not a pod restart.

Always include data in your results. Queue depth, free disk space, response times — the data dictionary in HealthCheckResult is your debugging surface when something goes wrong at 2am.

Test your health checks in staging. Deliberately take down your database and verify the readiness probe returns 503 and pods stop receiving traffic. Don't discover your health check doesn't work during an actual incident.

Register health checks as singletons or transient carefully. If your check holds state (like the cached result above), register it as a singleton. If it takes a scoped dependency like DbContext, register it as transient and resolve dependencies per-check execution.

Bonus: HealthCheck UI in Two Lines

If you want to impress a client or a manager with minimal effort, install the UI package:

dotnet add package AspNetCore.HealthChecks.UI
dotnet add package AspNetCore.HealthChecks.UI.InMemory.Storage

Configure it:

builder.Services.AddHealthChecksUI(options =>
{
    options.SetEvaluationTimeInSeconds(30); // poll every 30 seconds
    options.AddHealthCheckEndpoint("API", "/health/detail");
}).AddInMemoryStorage();

// After app.MapHealthChecks(...)
app.MapHealthChecksUI(options => options.UIPath = "/health-ui");

Navigate to /health-ui and you get a live dashboard showing the status of every check, historical trend, and response times — all generated from the JSON your endpoint already returns.

It's not something you'd expose publicly, but for internal dashboards, staging environments, or a demo to stakeholders it's genuinely useful. One caveat: AddInMemoryStorage resets history on restart. For persistent history use AspNetCore.HealthChecks.UI.SqlServer.Storage or the PostgreSQL equivalent.

Conclusion

A health endpoint that always returns 200 OK isn't a health check — it's a heartbeat. The difference matters at 2am when your database connection pool is exhausted, your Redis cluster is split-brained, or your disk is 98% full and nobody noticed.

The silent outage I described at the start? It cost us two hours of debugging because every signal said "healthy". Once we had real health checks in place, the next incident took ten minutes to diagnose — the Redis check was Degraded, the readiness probe had already removed that pod from rotation, and the logs had the exact connection timeout.

The setup takes an hour. The payoff is every incident after that.

One liveness endpoint — is the process worth keeping alive?
One readiness endpoint — is it ready to serve traffic right now?
Custom checks for every dependency that has caused an incident before
Rich JSON so you know why, not just that
And if you want bonus points with your team, the UI takes five minutes

Questions? Found an issue with the examples? Open an issue on GitHub.

IAsyncEnumerable in C#: Streaming Data Without Loading Everything into Memory

Adrián Bailador — Sun, 05 Apr 2026 11:38:54 +0000

My API crashed in production. 500,000 database records, a List, and a server with 8GB RAM. The math didn't work.

I spent two hours staring at the logs before I understood what happened. The fix took ten minutes. This is what I learned — and how it will save you the same headache.

The Problem We're Solving

I know, I know. You've written this a hundred times:

// ❌ The problem: 1 million records in memory
public async Task<List<LogEntry>> GetAllLogsAsync()
{
    return await _context.LogEntries.ToListAsync(); // Boom! Memory explosion
}

For a handful of records? Fine. But the day your dataset grows beyond what fits in RAM, that innocent ToListAsync() becomes a ticking bomb.

What Is IAsyncEnumerable?

Introduced in C# 8.0 (.NET Core 3.0), IAsyncEnumerable<T> lets you stream data asynchronously — processing items one by one as they arrive, without ever holding the full collection in memory. Think of it like reading a book page by page instead of photocopying the entire thing before you start.

// ✅ The solution: stream as data arrives
public IAsyncEnumerable<LogEntry> StreamLogsAsync()
{
    return _context.LogEntries.AsAsyncEnumerable(); // Memory-efficient
}

Production-Grade Patterns

These are the four patterns I reach for most often. Not theory — things I've actually shipped.

Pattern 1: Entity Framework Core Streaming

This is where most people start, and for good reason. If you have EF Core and a table that grows over time, you need this pattern sooner or later.

public class LogRepository
{
    private readonly AppDbContext _context;

    public LogRepository(AppDbContext context)
    {
        _context = context;
    }

    /// <summary>
    /// Streams logs matching criteria without loading all into memory.
    /// WARNING: Do NOT use with OrderBy/Limit without careful consideration.
    /// </summary>
    public async IAsyncEnumerable<LogEntry> StreamLogsAsync(
        DateTime from,
        DateTime to,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await foreach (var log in _context.LogEntries
            .Where(l => l.Timestamp >= from && l.Timestamp <= to)
            .AsAsyncEnumerable()
            .WithCancellation(ct))
        {
            yield return log;
        }
    }

    /// <summary>
    /// Chunks large exports to prevent connection timeouts.
    /// </summary>
    public async IAsyncEnumerable<IReadOnlyList<LogEntry>> StreamBatchedLogsAsync(
        int batchSize = 1000,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        var query = _context.LogEntries
            .OrderBy(l => l.Id)
            .AsAsyncEnumerable();

        var batch = new List<LogEntry>(batchSize);

        await foreach (var log in query.WithCancellation(ct))
        {
            batch.Add(log);

            if (batch.Count >= batchSize)
            {
                yield return batch.ToList();
                batch.Clear();
            }
        }

        // Don't forget the partial batch
        if (batch.Count > 0)
        {
            yield return batch;
        }
    }
}

Pattern 2: HttpClient Streaming with JSON

Third-party APIs that return thousands of records in a single response are surprisingly common. Without streaming, you buffer the entire response before deserializing a single object. HttpCompletionOption.ResponseHeadersRead is the line that changes everything here — don't forget it.

public class StreamingApiClient
{
    private readonly HttpClient _httpClient;
    private readonly JsonSerializerOptions _jsonOptions;

    public StreamingApiClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
        _jsonOptions = new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true,
            DefaultBufferSize = 4096 // Tune for your payload size
        };
    }

    /// <summary>
    /// Streams items from an NDJSON endpoint.
    /// Each line is a separate JSON object.
    /// </summary>
    public async IAsyncEnumerable<T> StreamFromNdJsonAsync<T>(
        string url,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        using var response = await _httpClient.GetAsync(
            url, 
            HttpCompletionOption.ResponseHeadersRead, // Critical: stream, don't buffer
            ct);

        response.EnsureSuccessStatusCode();

        await using var stream = await response.Content.ReadAsStreamAsync(ct);
        using var reader = new StreamReader(stream, Encoding.UTF8);

        string? line;
        while ((line = await reader.ReadLineAsync(ct)) != null)
        {
            if (string.IsNullOrWhiteSpace(line))
                continue;

            // Deserialize each line independently
            var item = JsonSerializer.Deserialize<T>(line, _jsonOptions);

            if (item != null)
                yield return item;
        }
    }

    /// <summary>
    /// Streams using System.Text.Json's built-in async deserialization.
    /// Requires JSON array format: [{}, {}, {}]
    /// </summary>
    public async IAsyncEnumerable<T> StreamJsonArrayAsync<T>(
        string url,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        using var response = await _httpClient.GetAsync(
            url,
            HttpCompletionOption.ResponseHeadersRead,
            ct);

        response.EnsureSuccessStatusCode();

        await using var stream = await response.Content.ReadAsStreamAsync(ct);

        await foreach (var item in JsonSerializer.DeserializeAsyncEnumerable<T>(
            stream, 
            _jsonOptions, 
            ct))
        {
            if (item != null)
                yield return item;
        }
    }
}

Pattern 3: File Processing Pipeline

CSV imports, log analysis, data migrations — anything that reads a file line by line and does something with each row. The key insight here is that you can chain multiple IAsyncEnumerable<T> methods into a pipeline where memory stays flat regardless of file size.

public class LogFileProcessor
{
    /// <summary>
    /// Reads, transforms, and writes logs in a streaming pipeline.
    /// Memory usage stays constant regardless of file size.
    /// </summary>
    public async IAsyncEnumerable<ProcessedLog> ProcessLogFileAsync(
        string filePath,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await foreach (var rawLog in ReadLinesAsync(filePath, ct))
        {
            // Transform on the fly - no memory buildup
            if (TryParseLog(rawLog, out var parsed))
            {
                var enriched = await EnrichLogAsync(parsed, ct);
                yield return enriched;
            }
        }
    }

    private static async IAsyncEnumerable<string> ReadLinesAsync(
        string path,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        using var reader = new StreamReader(path, Encoding.UTF8);

        string? line;
        while ((line = await reader.ReadLineAsync(ct)) != null)
        {
            yield return line;
        }
    }

    private static bool TryParseLog(string raw, out ParsedLog parsed)
    {
        // Your parsing logic here
        parsed = default!;
        return true;
    }

    private static async Task<ProcessedLog> EnrichLogAsync(
        ParsedLog log, 
        CancellationToken ct)
    {
        // Async enrichment (e.g., lookup user info)
        await Task.Delay(1, ct); // Simulate async work
        return new ProcessedLog(log);
    }
}

public record ParsedLog(string Timestamp, string Level, string Message);
public record ProcessedLog(ParsedLog Original);

Pattern 4: Controller Action with Streaming Response

ASP.NET Core handles IAsyncEnumerable<T> return types natively — it serializes as NDJSON and starts sending data to the client immediately. The client doesn't wait for the full dataset; it starts receiving records as soon as the first one is ready.

[ApiController]
[Route("api/[controller]")]
public class ReportsController : ControllerBase
{
    private readonly IReportService _reportService;

    public ReportsController(IReportService reportService)
    {
        _reportService = reportService;
    }

    /// <summary>
    /// Streams CSV data directly to the client.
    /// Client starts receiving data immediately, no server buffering.
    /// </summary>
    [HttpGet("export")]
    public IAsyncEnumerable<ReportRow> ExportData(
        [FromQuery] DateTime from,
        [FromQuery] DateTime to,
        CancellationToken ct)
    {
        // ASP.NET Core automatically serializes IAsyncEnumerable as NDJSON
        // or use custom formatting for CSV
        return _reportService.StreamReportAsync(from, to, ct);
    }

    /// <summary>
    /// Custom streaming for Server-Sent Events (SSE).
    /// </summary>
    [HttpGet("live-events")]
    public async IAsyncEnumerable<ServerSentEvent> GetLiveEvents(
        [EnumeratorCancellation] CancellationToken ct)
    {
        await foreach (var evt in _reportService.SubscribeToEventsAsync(ct))
        {
            yield return new ServerSentEvent
            {
                Id = evt.Id,
                Event = evt.Type,
                Data = JsonSerializer.Serialize(evt.Payload)
            };
        }
    }
}

public record ReportRow(string Id, string Name, decimal Value);
public record ServerSentEvent(string Id, string Event, string Data);

Before vs After: Performance Comparison

Let's make it concrete. Same data, same operation, two approaches.

The Old Way: List (Before)

public async Task<List<LargeRecord>> ProcessAllRecordsAsync()
{
    // Memory: O(n) - grows with dataset size
    // Time to first result: O(n) - wait for all
    var allRecords = await _repository.GetAllAsync();

    var processed = new List<LargeRecord>();
    foreach (var record in allRecords)
    {
        processed.Add(await ProcessAsync(record));
    }

    return processed;
}

// Usage - memory spikes here
var results = await ProcessAllRecordsAsync();
foreach (var item in results)
{
    await WriteToDiskAsync(item);
}

1M records at 100KB each — what actually happens:

Peak Memory: ~95 GB (yes, gigabytes)
Time to first output: 45 seconds of waiting
Result: OutOfMemoryException — your server gives up before you do

The New Way: IAsyncEnumerable (After)

public async IAsyncEnumerable<LargeRecord> ProcessAllRecordsAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    // Memory: O(1) - constant regardless of dataset size
    // Time to first result: O(1) - immediate streaming
    await foreach (var record in _repository.StreamAllAsync(ct))
    {
        yield return await ProcessAsync(record);
    }
}

// Usage - constant memory footprint
await foreach (var item in ProcessAllRecordsAsync().WithCancellation(ct))
{
    await WriteToDiskAsync(item);
}

Same 1M records — completely different story:

Peak Memory: ~150 MB (constant, regardless of dataset size)
Time to first output: 50ms — the client starts receiving data almost instantly
Result: Smooth streaming, server stays healthy

BenchmarkDotNet Results

Common Errors and How to Fix Them

I've made every single one of these. You don't have to.

Error 1: Forgetting CancellationToken

// ❌ Bad: No way to cancel mid-stream
public async IAsyncEnumerable<Item> GetItemsAsync()
{
    await foreach (var item in _source.GetAsync())
    {
        yield return item; // Can't cancel this!
    }
}

// ✅ Good: Always include cancellation support
public async IAsyncEnumerable<Item> GetItemsAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await foreach (var item in _source.GetAsync().WithCancellation(ct))
    {
        yield return item;
    }
}

Error 2: Buffering with ToListAsync()

// ❌ Bad: You just defeated the purpose
public async Task<List<Item>> GetItemsAsync() // Returns List<T>, not IAsyncEnumerable
{
    var items = new List<Item>();
    await foreach (var item in _source.GetAsync())
    {
        items.Add(item);
    }
    return items;
}

// ✅ Good: Return IAsyncEnumerable<T> directly
public IAsyncEnumerable<Item> GetItemsAsync(CancellationToken ct)
{
    return _source.GetAsync(); // Stream through
}

Error 3: Disposing Resources Too Early

// ❌ Bad: reader disposed before streaming completes
public async IAsyncEnumerable<string> ReadFileAsync(string path)
{
    using var reader = new StreamReader(path); // Disposed on first yield!

    while (await reader.ReadLineAsync() is { } line)
    {
        yield return line; // reader is already disposed
    }
}

// ✅ Good: Keep scope alive
public async IAsyncEnumerable<string> ReadFileAsync(
    string path,
    [EnumeratorCancellation] CancellationToken ct = default)
{
    using var reader = new StreamReader(path);

    try
    {
        while (await reader.ReadLineAsync(ct) is { } line)
        {
            yield return line;
        }
    }
    finally
    {
        // reader disposed when iteration completes or breaks
    }
}

Error 4: Not Configuring DbContext Lifetime

// ❌ Bad: Scoped DbContext disposed mid-stream in ASP.NET Core
[HttpGet("stream")]
public async IAsyncEnumerable<Order> GetOrders()
{
    var db = _serviceProvider.GetRequiredService<OrderDbContext>();
    // db will be disposed after the action method returns!

    await foreach (var order in db.Orders.AsAsyncEnumerable())
    {
        yield return order; // DbContext disposed here
    }
}

// ✅ Good: Use factory pattern for streaming
public class StreamingOrderService
{
    private readonly IDbContextFactory<OrderDbContext> _contextFactory;

    public async IAsyncEnumerable<Order> StreamOrdersAsync(
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await using var db = await _contextFactory.CreateDbContextAsync(ct);

        await foreach (var order in db.Orders.AsAsyncEnumerable().WithCancellation(ct))
        {
            yield return order;
        }
        // DbContext properly disposed when iteration completes
    }
}

Error 5: Ignoring Transaction Timeouts

// ❌ Bad: Long-running query may timeout
public async IAsyncEnumerable<Item> GetItemsAsync()
{
    await foreach (var item in _context.Items.AsAsyncEnumerable())
    {
        yield return item; // Connection held open indefinitely
    }
}

// ✅ Good: Set explicit command timeout
public async IAsyncEnumerable<Item> GetItemsAsync(CancellationToken ct)
{
    _context.Database.SetCommandTimeout(TimeSpan.FromMinutes(5));

    await foreach (var item in _context.Items.AsAsyncEnumerable().WithCancellation(ct))
    {
        yield return item;
    }
}

Best Practices

A few rules I now follow without thinking.

1. Always Accept CancellationToken

public async IAsyncEnumerable<T> StreamAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await foreach (var item in _source.WithCancellation(ct))
    {
        ct.ThrowIfCancellationRequested(); // Optional: check between operations
        yield return await TransformAsync(item, ct);
    }
}

2. Use WithCancellation in Callers

await foreach (var item in service.StreamAsync().WithCancellation(ct))
{
    // Proper cancellation propagation
}

3. Configure JSON Buffer Sizes for HttpClient

var options = new JsonSerializerOptions
{
    DefaultBufferSize = 8192 // Adjust based on average payload size
};

await foreach (var item in JsonSerializer.DeserializeAsyncEnumerable<T>(
    stream, options, ct))
{
    // Optimal memory usage
}

4. Add Backpressure with ConfigureAwait

await foreach (var item in source.ConfigureAwait(false))
{
    // false reduces context switching in high-throughput scenarios
    await SlowOperationAsync(item).ConfigureAwait(false);
}

5. Use IAsyncDisposable for Resource Cleanup

public async IAsyncEnumerable<byte[]> StreamFileChunksAsync(
    string path,
    int chunkSize = 8192,
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await using var fs = new FileStream(
        path, 
        FileMode.Open, 
        FileAccess.Read, 
        FileShare.Read,
        bufferSize: chunkSize, 
        useAsync: true);

    var buffer = new byte[chunkSize];
    int bytesRead;

    while ((bytesRead = await fs.ReadAsync(buffer, ct)) > 0)
    {
        yield return buffer.AsSpan(0, bytesRead).ToArray();
    }
}

6. Batch When Individual Items Are Too Small

public async IAsyncEnumerable<IReadOnlyList<T>> StreamBatchesAsync<T>(
    int batchSize = 100,
    [EnumeratorCancellation] CancellationToken ct = default)
    where T : class
{
    var batch = new List<T>(batchSize);

    await foreach (var item in _context.Set<T>().AsAsyncEnumerable().WithCancellation(ct))
    {
        batch.Add(item);

        if (batch.Count >= batchSize)
        {
            yield return batch;
            batch = new List<T>(batchSize);
        }
    }

    if (batch.Count > 0)
    {
        yield return batch;
    }
}

Conclusion

The mental shift is simple once it clicks:

Before: Load everything → Process everything → Return everything
After: Stream one item → Process it → Move to the next

That's it. No magic, no complex setup. Just a different way of thinking about data flow.

Reach for IAsyncEnumerable when:

✅ You're exporting database records by the thousands
✅ You're processing large files (CSV, logs, JSON dumps)
✅ You're consuming a streaming API
✅ Memory is a real concern on your server

Stick with List when:

❌ Your dataset is small (under ~1,000 items) — the overhead isn't worth it
❌ You need random access or multiple iterations
❌ You're chaining complex LINQ operations that don't support streaming

The 95% memory reduction I got wasn't theoretical. It was the difference between a service that crashed under load and one that handled the same data without breaking a sweat. Start with your EF Core queries and API clients — that's where you'll feel the impact immediately.

🚀 Big update drop for The Coffee Timer! ☕

Adrián Bailador — Mon, 30 Mar 2026 19:00:00 +0000

I've been heads-down building new features and polishing the experience — Here's what's new:

☕ Redesigned coffee cup: A fully SVG-based ceramic mug with realistic porcelain gradients, a 3D handle, crema/foam with latte art details, and smooth steam animations. It even fills up as your The Coffee Timer session progresses.

🎵 Spotify integration (Premium) Connect your Spotify account and play playlists, songs, or artists directly inside the app while you focus. Full search + library browsing — no need to switch tabs.

🔔 Background push notifications: The timer now sends a system notification even when the tab is closed or minimised. Never miss the end of a session again.

📱 Mobile responsiveness overhaul: Bigger touch targets, responsive layouts, no more overflow on small screens. The app now feels at home on any device.

⚡ Instant premium status Subscription state loads from cache instantly — no more waiting spinner before the UI unlocks.

🔒 Smart feature gating Non-premium users see a teaser of the Spotify player (blurred, with a lock icon) to show what they're missing. Guests get a "Sign in to unlock" CTA, and free users get "Upgrade to Premium".

The Coffee Timer is a productivity app built with React + TypeScript, .NET backend, Supabase, and Stripe — designed to make focused work feel a little more enjoyable.

https://thecoffeetimer.com/

If you want to try it or give feedback, drop a comment 👇

How I Fixed Supabase Rate Limiting in Production

Adrián Bailador — Sat, 28 Mar 2026 22:21:30 +0000

The Coffee Timer was hitting Supabase's rate limits in production. Here's the exact problem, why it happened, and the four-part fix that solved it.

The Problem: Frontend Calling Supabase Directly

The Coffee Timer is a subscription-based web app. The original architecture was straightforward — the frontend called Supabase directly for everything: authentication, subscription checks, feature flags, and data reads. It worked fine in development and in early production with a small user base.

Then it didn't.

Under real load, the frontend was making multiple Supabase calls per page render. A logged-in user opening the app would trigger:

A call to fetch the user profile
A call to check subscription status
A call to load their saved timers
A call to fetch feature flags

That's four Supabase requests for a single page load. Multiply that by concurrent users refreshing the app, and you hit HTTP 429 — Too Many Requests — fast.

POST https://[project].supabase.co/rest/v1/rpc/check_subscription
→ 429 Too Many Requests
Retry-After: 60

The UI would hang, subscriptions appeared as expired, and users were getting locked out of features they had paid for. Not great.

Understanding Supabase Rate Limits

Supabase rate limits operate at several levels. The ones that matter most for this problem are:

REST API requests per second — per project, across all clients
Auth requests per hour — per IP and per user
Realtime connections — concurrent subscriptions

The key insight is that Supabase is designed for moderate, server-side usage — not to act as a direct database connection from thousands of browser tabs. When you call Supabase directly from the frontend, every user's browser is a separate client hammering the same rate limit pool.

The fix is architectural: the browser should not be the one talking to Supabase for anything critical.

Fix 1 — Move Critical Operations to the .NET Backend

The most impactful change was moving subscription checks and write operations off the frontend and behind a .NET API. The browser now calls my API, and the API calls Supabase with a service-level key. One server-to-server connection, not hundreds of browser-to-Supabase connections.

// SubscriptionService.cs
public class SubscriptionService
{
    private readonly SupabaseClient _supabase;
    private readonly ILogger<SubscriptionService> _logger;

    public SubscriptionService(SupabaseClient supabase, ILogger<SubscriptionService> logger)
    {
        _supabase = supabase;
        _logger = logger;
    }

    public async Task<SubscriptionStatus> GetSubscriptionStatusAsync(string userId)
    {
        var response = await _supabase
            .From<Subscription>()
            .Where(s => s.UserId == userId && s.IsActive)
            .Single();

        if (response is null)
            return SubscriptionStatus.Free;

        return response.Plan switch
        {
            "pro"        => SubscriptionStatus.Pro,
            "enterprise" => SubscriptionStatus.Enterprise,
            _            => SubscriptionStatus.Free
        };
    }
}

The API endpoint the frontend calls:

[ApiController]
[Route("api/[controller]")]
[Authorize]
public class SubscriptionController : ControllerBase
{
    private readonly SubscriptionService _subscriptionService;

    public SubscriptionController(SubscriptionService subscriptionService)
    {
        _subscriptionService = subscriptionService;
    }

    [HttpGet("status")]
    public async Task<IActionResult> GetStatus()
    {
        var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
        if (userId is null) return Unauthorized();

        var status = await _subscriptionService.GetSubscriptionStatusAsync(userId);
        return Ok(new { status = status.ToString().ToLower() });
    }
}

The frontend now makes one call to GET /api/subscription/status, which returns a clean response. Supabase never sees the browser again for subscription checks.

A note on the Supabase .NET SDK: The official supabase-csharp SDK works, but it is not as actively maintained as the JavaScript client, and its fluent query API has known edge cases around complex filters and RPC deserialization. For production backends, you may want to fall back to a raw HttpClient against Supabase's REST endpoint — it is more explicit, easier to debug, and not subject to SDK-level bugs. I use the SDK for simple CRUD operations but switch to HttpClient for anything involving RPCs or custom headers.

Fix 2 — Use Supabase RPCs for Batched Operations

Even with the backend in place, there were still cases where a single operation needed to read and write across multiple tables. Doing that as separate sequential calls from the backend still generates N requests to Supabase.

The solution is Supabase RPCs — PostgreSQL functions exposed as a single HTTP call. Instead of three reads and a write, one function call handles the entire operation atomically.

-- Supabase SQL editor: create the function
CREATE OR REPLACE FUNCTION get_user_dashboard(p_user_id UUID)
RETURNS JSON
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
    result JSON;
BEGIN
    SELECT json_build_object(
        'subscription', (
            SELECT row_to_json(s)
            FROM subscriptions s
            WHERE s.user_id = p_user_id AND s.is_active = true
            LIMIT 1
        ),
        'timers', (
            SELECT json_agg(t)
            FROM timers t
            WHERE t.user_id = p_user_id
            ORDER BY t.updated_at DESC
            LIMIT 20
        ),
        'feature_flags', (
            SELECT json_agg(f)
            FROM feature_flags f
            WHERE f.user_id = p_user_id OR f.is_global = true
        )
    ) INTO result;

    RETURN result;
END;
$$;

Calling the RPC from the .NET backend:

public async Task<DashboardData> GetDashboardAsync(string userId)
{
    var response = await _supabase
        .Rpc("get_user_dashboard", new { p_user_id = userId });

    if (response.ResponseMessage?.IsSuccessStatusCode != true)
    {
        _logger.LogError("RPC get_user_dashboard failed for user {UserId}", userId);
        throw new InvalidOperationException("Failed to load dashboard data.");
    }

    return JsonSerializer.Deserialize<DashboardData>(response.Content!)
        ?? throw new InvalidOperationException("Empty response from dashboard RPC.");
}

One HTTP call to Supabase replaces three. The function runs inside the database — no network round-trips between tables.

Security note: SECURITY DEFINER means the function runs with the privileges of the function creator, not the caller. This is appropriate here because the backend uses a service-level key and the call never reaches the frontend. However, if you ever expose an RPC directly from the frontend, SECURITY DEFINER bypasses Row Level Security — validate p_user_id against auth.uid() explicitly inside the function body in that case, or switch to SECURITY INVOKER and rely on RLS policies instead.

When not to use RPCs: RPCs are great for batching reads or encapsulating complex transactional logic. They're not ideal for operations that need to be easily unit-tested or debugged in isolation. Use them selectively — one RPC for the dashboard load makes sense; one RPC for every operation in your app creates a maintenance burden.

Fix 3 — Add Server-Side Caching with IMemoryCache

A client-side cache eliminates redundant calls per user. But it doesn't help when many users are doing their first load simultaneously — each of their requests still hits Supabase independently from the backend.

The missing layer is a server-side cache using IMemoryCache. Subscription status is the same answer for a given user regardless of which request fetches it. Caching it on the backend means that 50 concurrent logins don't generate 50 Supabase calls — they generate one, and the rest are served from memory.

// Program.cs
builder.Services.AddMemoryCache();

// SubscriptionService.cs
public class SubscriptionService
{
    private readonly SupabaseClient _supabase;
    private readonly IMemoryCache _cache;
    private readonly ILogger<SubscriptionService> _logger;

    private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(1);

    public SubscriptionService(
        SupabaseClient supabase,
        IMemoryCache cache,
        ILogger<SubscriptionService> logger)
    {
        _supabase = supabase;
        _cache = cache;
        _logger = logger;
    }

    public async Task<SubscriptionStatus> GetSubscriptionStatusAsync(string userId)
    {
        var cacheKey = $"subscription:{userId}";

        if (_cache.TryGetValue(cacheKey, out SubscriptionStatus cached))
            return cached;

        var response = await _supabase
            .From<Subscription>()
            .Where(s => s.UserId == userId && s.IsActive)
            .Single();

        var status = response?.Plan switch
        {
            "pro"        => SubscriptionStatus.Pro,
            "enterprise" => SubscriptionStatus.Enterprise,
            _            => SubscriptionStatus.Free
        };

        _cache.Set(cacheKey, status, CacheTtl);
        return status;
    }

    public void InvalidateCache(string userId)
    {
        _cache.Remove($"subscription:{userId}");
    }
}

Always get the userId from the authenticated JWT claim — never from the request body — when invalidating the cache. Accepting a userId from the client would allow one user to invalidate another user's cache entry:

// ✅ userId comes from the JWT, not from the request body
[HttpPost("checkout/complete")]
public async Task<IActionResult> CompleteCheckout([FromBody] CheckoutRequest request)
{
    var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
    if (userId is null) return Unauthorized();

    await _checkoutService.ProcessAsync(request.SessionId);
    _subscriptionService.InvalidateCache(userId);
    return Ok();
}

IMemoryCache vs IDistributedCache: IMemoryCache is process-local — if you run multiple backend instances behind a load balancer, each instance has its own cache and a user might hit a stale entry on a different node. For single-instance deployments (like Render's free/starter tier), IMemoryCache is fine. If you scale horizontally, switch to IDistributedCache backed by Redis to share cache state across instances.

Fix 4 — Cache Subscription State in localStorage with a TTL

Even with server-side caching, the browser still makes one API call per page load per user. For a subscription status that doesn't change often, that's unnecessary. A client-side cache in localStorage eliminates redundant calls for users navigating within the app.

// subscriptionCache.ts
const CACHE_KEY = "subscription_status";
const TTL_MS = 60 * 1000; // 1 minute

interface CachedSubscription {
  status: string;
  cachedAt: number;
}

export function getCachedSubscription(): string | null {
  try {
    const raw = localStorage.getItem(CACHE_KEY);
    if (!raw) return null;

    const cached: CachedSubscription = JSON.parse(raw);
    const age = Date.now() - cached.cachedAt;

    if (age > TTL_MS) {
      localStorage.removeItem(CACHE_KEY);
      return null;
    }

    return cached.status;
  } catch {
    localStorage.removeItem(CACHE_KEY);
    return null;
  }
}

export function setCachedSubscription(status: string): void {
  const entry: CachedSubscription = {
    status,
    cachedAt: Date.now(),
  };
  localStorage.setItem(CACHE_KEY, JSON.stringify(entry));
}

export function invalidateSubscriptionCache(): void {
  localStorage.removeItem(CACHE_KEY);
}

Using it when loading the app:

// useSubscription.ts
export async function getSubscriptionStatus(): Promise<string> {
  // Return cached value if still fresh
  const cached = getCachedSubscription();
  if (cached) return cached;

  // Fetch from backend, not Supabase directly
  const response = await fetch("/api/subscription/status", {
    headers: { Authorization: `Bearer ${await getAuthToken()}` },
  });

  if (!response.ok) throw new Error("Failed to fetch subscription status.");

  const { status } = await response.json();
  setCachedSubscription(status);
  return status;
}

Invalidate the cache whenever the subscription actually changes — on checkout completion, on plan upgrade, on logout:

// After a successful checkout
await completeCheckout(sessionId);
invalidateSubscriptionCache(); // Force fresh fetch on next load

Why 1 minute? The TTL is a balance between freshness and request volume. Too short (< 30s) and you still trigger frequent fetches for users navigating quickly. Too long (> 5min) and a user who just upgraded won't see their new features without a manual refresh. One minute means a subscription change feels near-instant while eliminating redundant calls under normal usage. If your use case needs faster propagation, consider pushing subscription changes to the client via a WebSocket and invalidating the cache explicitly — rather than shortening the TTL.

Important caveat: The localStorage cache means a user who cancels their subscription may continue to see Pro features for up to 1 minute on the client, until the TTL expires. This is an acceptable trade-off for most SaaS apps — the backend enforces the real access control, and client-side UI state catching up within 60 seconds is not a meaningful security gap. However, if you need stricter enforcement (e.g. metered API access or high-value feature gating), shorten the TTL or push subscription changes via WebSocket rather than relying on TTL expiry.

The Result: Before and After

Before:

4 direct Supabase REST calls per page load, from every browser tab
~120 Supabase requests/minute at peak with ~30 concurrent active users
429 errors appearing consistently above ~25 concurrent users
Subscription checks failing 8–12% of requests during busy periods
Median time-to-interactive: ~1,400ms (waiting on sequential Supabase calls)

After:

0 direct Supabase calls from the browser
Backend makes 1 RPC call to Supabase per cache miss — most page loads served from IMemoryCache
Supabase request volume dropped ~85% at equivalent user load
429 errors: eliminated
Median time-to-interactive: ~310ms (single backend call, mostly cache hits)

The Supabase dashboard's API usage graph made the change visible immediately — the spike pattern on every deployment flattened out the same day the caching layers went live.

Common Mistakes to Avoid

Calling Supabase directly from the frontend for subscription or billing checks
Subscription status is both critical and sensitive. It should never be computed or fetched client-side. A user can intercept and modify the response from a direct Supabase call. Route it through your backend where you control validation.

Not invalidating the cache after state changes
If you cache subscription status but forget to invalidate it after checkout, users will complete a payment and still see themselves on the free plan until the TTL expires. Always call invalidateSubscriptionCache() on any action that changes subscription state.

// ❌ Forgot to invalidate — user sees stale Free status after upgrading
await processUpgrade(userId);

// ✅ Invalidate immediately after the state change
await processUpgrade(userId);
invalidateSubscriptionCache();

Caching on the frontend but not on the backend
A localStorage cache eliminates redundant calls per user. It does nothing for simultaneous first-time loads. Without IMemoryCache on the backend, 50 users logging in at the same time still generate 50 Supabase calls. Both layers are necessary.

Using a short TTL as a substitute for proper cache invalidation
A 5-second TTL is not a caching strategy — it's a polling strategy with extra steps. Either cache with a meaningful TTL and invalidate on change, or don't cache at all.

// ❌ 5-second TTL — you're just polling Supabase every 5 seconds
const TTL_MS = 5 * 1000;

// ✅ 1-minute TTL + explicit invalidation on subscription change
const TTL_MS = 60 * 1000;

Sharing a service-level Supabase key in the frontend
The backend uses a service role key that bypasses Row Level Security. This key must never be exposed to the browser. Keep it server-side in environment variables.

// appsettings.json (server-side only)
{
  "Supabase": {
    "Url": "https://[project].supabase.co",
    "ServiceKey": "eyJ..."  // Never expose this in frontend code
  }
}

Best Practices

Never call Supabase directly from the browser for subscription, billing, or access control. These operations belong in your backend.
Use RPCs to batch related reads into a single HTTP call. Fewer calls = fewer chances to hit rate limits.
Add server-side caching with IMemoryCache for any data that is expensive to fetch and doesn't change per-request. It protects against burst load, not just steady-state traffic.
Cache on the client too, but only for non-sensitive UI state like subscription tier. Always enforce real access control on the backend.
Always invalidate both caches on state changes — the server-side cache and the localStorage cache — not just let the TTL expire.
Always derive userId from the JWT claim on the server, never from the request body, when performing sensitive operations like cache invalidation.
Use the Supabase service role key only on the backend. The frontend should use the anonymous key scoped to RLS policies.
Monitor your Supabase project's rate limit usage in the dashboard. Set up alerts before you hit limits, not after.
If you scale horizontally, switch IMemoryCache to IDistributedCache backed by Redis to avoid stale cache entries across instances.

Conclusion

Rate limiting is not a Supabase problem — it's an architecture problem. Supabase is a hosted service with usage boundaries, and calling it directly from every browser tab treats it like a local database. It isn't.

The fix for The Coffee Timer came down to four things: move critical operations to the backend, reduce the number of calls using RPCs, cache aggressively on the server with IMemoryCache, and add a client-side TTL cache as a last-mile optimization. None of these are complex changes, but together they eliminated 429 errors entirely, cut Supabase request volume by ~85%, and reduced time-to-interactive by more than 4x.

If your frontend is calling Supabase directly for anything that matters — subscription status, access control, billing — move it to your backend. Then cache it. The sooner, the better.

What Your .NET Exceptions Are Telling Attackers (And How to Stop It)

Adrián Bailador — Fri, 20 Mar 2026 21:08:58 +0000

How unhandled exceptions leak stack traces, connection strings, and internal architecture — and how to fix it properly in ASP.NET Core.

Introduction: The Exception That Becomes a Roadmap

Imagine you're building an API. A developer forgets to handle an edge case, and a request triggers an unhandled exception. What does the caller see?

In a default ASP.NET Core project in development mode, they see something like this:

System.NullReferenceException: Object reference not set to an instance of an object.
   at MyApi.Services.OrderService.GetOrderAsync(Int32 id)
      in /home/runner/work/MyApi/src/Services/OrderService.cs:line 47
   at MyApi.Controllers.OrdersController.GetOrder(Int32 id)
      in /home/runner/work/MyApi/src/Controllers/OrdersController.cs:line 23
   at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor...

ConnectionString: Server=prod-db.internal;Database=orders;User=sa;Password=Sup3rS3cr3t!

That response just told an attacker:

Your internal folder structure and project layout
The exact class and method where the error occurred
Your database server hostname
Your database credentials

This isn't hypothetical. Error responses are one of the most common sources of information disclosure in web APIs — and one of the easiest to fix.

What Attackers Learn from Your Exceptions

Different types of exceptions leak different types of information. Understanding what gets exposed helps prioritise what to fix first.

Stack Traces — Your Internal Architecture

A stack trace reveals the exact call chain inside your application. Attackers use this to understand how your code is structured, what libraries you use, and where to look for known vulnerabilities.

System.Data.SqlClient.SqlException: Invalid column name 'user_id'.
   at System.Data.SqlClient.SqlConnection.OnError(...)
   at MyApi.Repositories.UserRepository.FindByEmailAsync(String email)
   at MyApi.Services.AuthService.LoginAsync(LoginRequest request)

From this single exception, an attacker now knows:

You're using SQL Server (SqlClient)
A column is named user_id — useful for SQL injection attempts
Your authentication flow goes through AuthService.LoginAsync

Database Errors — Your Schema

Database exceptions are particularly dangerous because they expose table names, column names, and sometimes the exact query that failed.

Microsoft.EntityFrameworkCore.DbUpdateException:
An error occurred while saving the entity changes.
Table 'orders_db.dbo.CustomerPayments' doesn't exist.

Table names and database names are handed to the attacker on a silver platter.

Validation Errors — Your Business Rules

Even seemingly harmless validation errors can expose internal logic:

FluentValidation.ValidationException:
  -- OrderId: Order ID must be between 100000 and 999999. Severity: Error
  -- CustomerId: Customer must have a verified account with status 'Premium' or 'Enterprise'.

Now the attacker knows your ID ranges, your account tiers, and the status values your system uses internally.

The Fix: Global Exception Handling Middleware

The most important step is ensuring that no raw exception ever reaches the client in production. ASP.NET Core provides two clean ways to do this.

Option 1: UseExceptionHandler (Built-in)

For most APIs, the built-in UseExceptionHandler is the right starting point:

// Program.cs
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage(); // Full details in development only
}
else
{
    app.UseExceptionHandler("/error"); // Safe response in production
}

Add a dedicated error endpoint:

[ApiController]
public class ErrorController : ControllerBase
{
    [Route("/error")]
    [ApiExplorerSettings(IgnoreApi = true)]
    public IActionResult HandleError()
    {
        return Problem(
            title: "An unexpected error occurred.",
            statusCode: StatusCodes.Status500InternalServerError
        );
    }
}

This returns a standardised RFC 7807 Problem Details response with no internal information:

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "An unexpected error occurred.",
  "status": 500
}

Option 2: Custom Middleware (More Control)

For more control over logging, correlation IDs, and response shaping, write your own middleware:

public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public ExceptionHandlingMiddleware(
        RequestDelegate next,
        ILogger<ExceptionHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            await HandleExceptionAsync(context, ex);
        }
    }

    private async Task HandleExceptionAsync(HttpContext context, Exception exception)
    {
        var correlationId = context.TraceIdentifier;

        // Log the full exception internally — never lose observability
        _logger.LogError(exception,
            "Unhandled exception. CorrelationId: {CorrelationId}, Path: {Path}",
            correlationId,
            context.Request.Path);

        var (statusCode, title) = exception switch
        {
            UnauthorizedAccessException => (401, "Unauthorised."),
            KeyNotFoundException        => (404, "Resource not found."),
            ArgumentException           => (400, "Invalid request."),
            _                           => (500, "An unexpected error occurred.")
        };

        context.Response.StatusCode = statusCode;
        context.Response.ContentType = "application/problem+json";

        // Return safe response — correlation ID allows support to look up the real error
        var problem = new
        {
            type    = "https://httpstatuses.com/" + statusCode,
            title   = title,
            status  = statusCode,
            traceId = correlationId   // Safe: links to logs without exposing details
        };

        await context.Response.WriteAsJsonAsync(problem);
    }
}

app.UseMiddleware<ExceptionHandlingMiddleware>();

The correlationId in the response is the key insight here: the client gets a reference they can provide to support, while you can look up the full exception in your logs. No information leakage, full observability.

Option 3: IExceptionHandler (ASP.NET Core 8+ — The Modern Approach)

If you're on .NET 8 or later, skip writing middleware from scratch. The IExceptionHandler interface is the clean, officially supported way to handle exceptions globally:

public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        var correlationId = httpContext.TraceIdentifier;

        _logger.LogError(exception,
            "Unhandled exception. CorrelationId: {CorrelationId}, Path: {Path}",
            correlationId,
            httpContext.Request.Path);

        var (statusCode, title) = exception switch
        {
            UnauthorizedAccessException => (401, "Unauthorised."),
            KeyNotFoundException        => (404, "Resource not found."),
            ArgumentException           => (400, "Invalid request."),
            _                           => (500, "An unexpected error occurred.")
        };

        httpContext.Response.StatusCode = statusCode;

        var problem = new ProblemDetails
        {
            Title  = title,
            Status = statusCode,
            Extensions = { ["traceId"] = correlationId }
        };

        await httpContext.Response.WriteAsJsonAsync(problem, cancellationToken);

        // Return true = exception is handled, pipeline stops here
        // Return false = pass to the next handler in the chain
        return true;
    }
}

builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();

// ...

app.UseExceptionHandler();

You can register multiple handlers in order — useful when you want different handlers for domain exceptions vs unexpected errors:

builder.Services.AddExceptionHandler<DomainExceptionHandler>();   // handles first
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();   // fallback

If a handler returns false from TryHandleAsync, the next registered handler gets a chance. This gives you a clean chain of responsibility without messy if/else trees in a single middleware class. For new projects on .NET 8+, this is the approach to use.

Problem Details: The Standard Way to Return Errors

ASP.NET Core 7+ has built-in support for RFC 7807 Problem Details. Use it instead of rolling your own error response format:

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = context =>
    {
        // Add correlation ID to every problem response
        context.ProblemDetails.Extensions["traceId"] =
            context.HttpContext.TraceIdentifier;

        // Never include exception details in production
        context.ProblemDetails.Extensions.Remove("exception");
    };
});

// In Program.cs
app.UseExceptionHandler();
app.UseStatusCodePages();

For custom domain exceptions, create specific Problem Details responses:

public class OrderNotFoundException : Exception
{
    public int OrderId { get; }
    public OrderNotFoundException(int orderId)
        : base($"Order {orderId} was not found.")
    {
        OrderId = orderId;
    }
}

// In your exception handler
if (exception is OrderNotFoundException notFound)
{
    return TypedResults.Problem(
        title: "Order not found.",
        detail: $"No order with ID {notFound.OrderId} exists.",  // Safe — no internal details
        statusCode: 404
    );
}

Logging Exceptions Safely

Fixing the response is half the job. The other half is making sure you're not accidentally logging sensitive data.

What NOT to Log

// ❌ Logs the full request body — may contain passwords, card numbers, PII
_logger.LogError("Request failed: {Request}", JsonSerializer.Serialize(request));

// ❌ Logs the connection string from the exception message
_logger.LogError("DB error: {Message}", exception.Message);

// ❌ Logs authentication tokens
_logger.LogInformation("User authenticated with token: {Token}", token);

// ❌ String interpolation bypasses structured logging — if user.ToString()
//    accidentally includes a password hash or sensitive field, it leaks to your logs
_logger.LogError($"Error processing user {user}");

What to Log Instead

// ✅ Log the exception object — structured logging handles it safely
_logger.LogError(exception, "Order processing failed for OrderId: {OrderId}", orderId);

// ✅ Always use message templates, never string interpolation
//    This logs the UserId value, not the entire object
_logger.LogWarning("Authentication failed for UserId: {UserId}", user.Id);

// ✅ Log that sensitive data was present, not its value
_logger.LogInformation("Payment processed. CardLastFour: {Last4}", card.LastFour);

Why string interpolation is dangerous in logs: When you write _logger.LogError($"Error for {user}"), the entire user object is serialised via ToString() before the logger ever sees it. If your model's ToString() override (or a default JSON serialiser) includes a password hash, an API key, or a session token, that value ends up in your log store in plain text. Structured logging with message templates ({UserId}) passes the value as a typed parameter — you control exactly what gets captured.

Filtering Sensitive Properties in Serilog

If you're using Serilog, use destructuring policies to automatically redact sensitive fields:

Log.Logger = new LoggerConfiguration()
    .Destructure.ByTransforming<LoginRequest>(r => new
    {
        r.Email,
        Password = "***REDACTED***"
    })
    .WriteTo.Console()
    .CreateLogger();

Validating Input Before It Throws

Many exception-based information leaks start with unvalidated input. If you validate properly at the boundary, the dangerous exceptions never get thrown.

// ❌ Throws SqlException with schema details if input is malicious
public async Task<Order> GetOrderAsync(string rawId)
{
    var id = int.Parse(rawId); // throws FormatException with the raw input
    return await _db.Orders.FindAsync(id);
}

// ✅ Validate at the boundary — exception never reaches the DB layer
public async Task<IActionResult> GetOrder([FromRoute] int id)
{
    if (id <= 0)
        return BadRequest(new { error = "Invalid order ID." });

    var order = await _orderService.GetOrderAsync(id);
    return order is null ? NotFound() : Ok(order);
}

For complex validation, use FluentValidation and return structured errors without exposing internal rules:

public class CreateOrderValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderValidator()
    {
        RuleFor(x => x.ProductId)
            .GreaterThan(0)
            .WithMessage("Invalid product.");   // Generic — doesn't reveal ID ranges

        RuleFor(x => x.Quantity)
            .InclusiveBetween(1, 100)
            .WithMessage("Quantity must be between 1 and 100.");
    }
}

Hiding Server and Technology Information

Beyond exceptions, ASP.NET Core leaks information through HTTP response headers by default. Remove them:

// Program.cs — remove the Server header
builder.WebHost.ConfigureKestrel(options =>
{
    options.AddServerHeader = false;
});

Also remove the X-Powered-By header if you're behind IIS:

<!-- web.config -->
<system.webServer>
  <httpProtocol>
    <customHeaders>
      <remove name="X-Powered-By" />
    </customHeaders>
  </httpProtocol>
</system.webServer>

And never expose the ASP.NET Core version in error responses. Verify this with your production error handler:

// ❌ Reveals framework version
context.Response.Headers["X-AspNet-Version"] = Environment.Version.ToString();

// ✅ Remove it entirely
context.Response.Headers.Remove("X-AspNet-Version");

Environment-Specific Configuration

The most common mistake is accidentally deploying with ASPNETCORE_ENVIRONMENT=Development in production. This enables the developer exception page, which shows full stack traces.

Lock this down explicitly:

// Program.cs — explicit check, not implicit trust
if (!app.Environment.IsProduction())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler();
    app.UseHsts();
}

And verify it in your CI/CD pipeline. In GitHub Actions:

- name: Verify production environment
  run: |
    if [ "$ASPNETCORE_ENVIRONMENT" = "Development" ]; then
      echo "ERROR: Cannot deploy with Development environment"
      exit 1
    fi
  env:
    ASPNETCORE_ENVIRONMENT: ${{ vars.ASPNETCORE_ENVIRONMENT }}

Common Errors and How to Avoid Them

Showing stack traces in production
This is the most critical issue. Always configure UseExceptionHandler or custom middleware for production. Use IHostEnvironment.IsProduction() — never rely on #if DEBUG for security decisions.

Returning exception messages directly to clients
Never do return BadRequest(exception.Message). Exception messages are written for developers, not clients. They frequently contain internal paths, SQL fragments, or configuration values. Always return a message you explicitly wrote.

// ❌
return BadRequest(ex.Message);

// ✅
return BadRequest("The request could not be processed. Please check your input.");

Catching and swallowing exceptions silently
Hiding exceptions without logging them destroys your ability to debug production issues.

// ❌ Exception disappears — you'll never know this happened
try { await ProcessOrderAsync(order); }
catch (Exception) { }

// ✅ Log it, then decide how to respond
try { await ProcessOrderAsync(order); }
catch (Exception ex)
{
    _logger.LogError(ex, "Failed to process order {OrderId}", order.Id);
    throw; // or return a safe error response
}

Leaking internal IDs in error messages
Avoid returning internal identifiers (auto-increment IDs, GUIDs from internal systems) in error messages. They help attackers enumerate resources.

// ❌ Confirms the resource exists and reveals the internal ID format
return NotFound($"Order with ID {id} not found in database.");

// ✅ Generic — reveals nothing
return NotFound();

Using Environment.StackTrace in responses or logs
Developers sometimes manually include Environment.StackTrace in log messages or error responses when debugging a tricky issue — and forget to remove it. This is just as dangerous as an unhandled exception reaching the client: it exposes the full call stack, file paths, and line numbers.

// ❌ Never include Environment.StackTrace in HTTP responses
return StatusCode(500, new {
    error = "Something went wrong",
    stack = Environment.StackTrace  // Full stack trace sent to the client
});

// ❌ Logging it is safer but still leaks internal structure to your log store
_logger.LogError("Error occurred. Stack: {Stack}", Environment.StackTrace);

// ✅ Log the exception object instead — it includes the stack trace
//    in a structured way, scoped to the actual exception that was thrown
_logger.LogError(exception, "Unhandled error processing order {OrderId}", orderId);

The exception object passed to _logger.LogError(exception, ...) captures the stack trace as a structured field in your log store. You get full context without manually concatenating strings — and it never accidentally ends up in an HTTP response.

Different error responses for valid vs invalid users
If your API returns different error messages for "user not found" vs "wrong password", attackers can enumerate valid usernames. Use identical responses:

// ❌ Reveals whether the email exists
if (user is null) return Unauthorized("Email address not registered.");
if (!VerifyPassword(user, request.Password)) return Unauthorized("Incorrect password.");

// ✅ Same message either way
if (user is null || !VerifyPassword(user, request.Password))
    return Unauthorized("Invalid credentials.");

Don't forget timing attacks. Identical messages aren't enough on their own. If validating a non-existent user takes 2ms (a quick null check) and validating a wrong password takes 200ms (a bcrypt hash comparison), an attacker can still enumerate valid emails by measuring response times — even without reading the message body. Use a constant-time dummy verification to equalise the response time regardless of whether the user exists:
var user = await _db.Users.FirstOrDefaultAsync(u => u.Email == request.Email);

// Always run the hash comparison — even for non-existent users
// This ensures the response time is the same whether the user exists or not
var passwordValid = user is not null
    ? VerifyPassword(user.PasswordHash, request.Password)
    : BCrypt.Verify(request.Password, _dummyHash); // constant-time dummy check

if (user is null || !passwordValid)
    return Unauthorized("Invalid credentials.");
This is a more advanced technique, but it closes the gap between "secure messages" and "truly secure authentication."

Best Practices

Never expose stack traces in production. Configure UseExceptionHandler before deploying — it's off by default in non-Development environments only if you set it up.
Return Problem Details (RFC 7807) for all error responses. It's a standard format that clients can handle generically.
Always include a correlation/trace ID in error responses. It lets clients report errors to support without exposing internal details.
Log the full exception internally — never sacrifice observability for security. The goal is to hide details from clients, not from your own monitoring.
Validate all input at the boundary. Most information leaks start with unvalidated data reaching layers that weren't designed to handle it.
Use identical error messages for authentication failures to prevent username enumeration.
Remove server headers (Server, X-Powered-By, X-AspNet-Version) from all responses.
Audit your error responses in staging before every release. Run your API against a tool like OWASP ZAP and check what error details leak.

Conclusion

Exceptions are not just a reliability concern — they're a security boundary. Every unhandled exception that reaches a client is a potential information disclosure vulnerability. Stack traces, database schemas, internal paths, and connection strings all become attacker intelligence when they leak through error responses.

The fixes are straightforward: global exception middleware, Problem Details responses, structured logging with redaction, and environment-specific configuration. None of this requires a security specialist — it's standard ASP.NET Core development practice that every team should have in place before going to production.

The goal is simple: your logs should have everything, your clients should have nothing they didn't need to know.

GitHub Actions for .NET: Build, Test, and Deploy Your API

Adrián Bailador — Sun, 15 Mar 2026 19:46:53 +0000

A complete guide to CI/CD for .NET developers — automated builds, test runs, Docker images, and deployments to Azure using GitHub Actions from scratch.

Introduction: Why CI/CD Is Not Optional

Every time you push code manually, run tests by hand, or deploy by copying files to a server, you're introducing risk. Human steps fail. They get skipped under pressure. They're not reproducible.

CI/CD (Continuous Integration / Continuous Deployment) solves this by automating the entire path from a git push to a running application. Every commit is built. Every build is tested. Every successful build on main can be deployed automatically.

GitHub Actions is the most natural CI/CD tool for .NET developers on GitHub. It's free for public repositories, deeply integrated with the GitHub ecosystem, and has a growing marketplace of pre-built actions. You write workflows in YAML, they run on Microsoft-hosted runners with .NET pre-installed, and you pay nothing for most use cases.

In this article I'll walk you through building a complete pipeline: automated builds, test runs with coverage, Docker image creation, NuGet caching, and deployment to Azure App Service.

GitHub Actions Core Concepts

Before writing any YAML, understand the four building blocks:

Workflow — a YAML file in .github/workflows/ that defines your automation. You can have multiple workflows per repository.

Event — what triggers the workflow. A push, a pull request, a schedule, or a manual trigger.

Job — a unit of work that runs on a runner (a virtual machine). Jobs run in parallel by default; you can make them sequential with needs.

Step — a single command or action within a job. Steps run sequentially within a job.

Workflow
  └── Job A (runs on ubuntu-latest)
        ├── Step 1: Checkout code
        ├── Step 2: Setup .NET
        ├── Step 3: Restore packages
        ├── Step 4: Build
        └── Step 5: Test
  └── Job B (runs after Job A)
        ├── Step 1: Build Docker image
        └── Step 2: Deploy to Azure

Your First .NET Workflow: Build + Test on Every Push

Create .github/workflows/ci.yml in your repository:

name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Restore dependencies
        run: dotnet restore

      - name: Build
        run: dotnet build --no-restore --configuration Release

      - name: Test
        run: dotnet test --no-build --configuration Release --verbosity normal

This workflow runs on every push to main or develop, and on every pull request targeting main. It checks out your code, sets up .NET 8, restores NuGet packages, builds in Release mode, and runs all tests.

Push this file to your repository and you'll see it appear under the Actions tab immediately.

Caching NuGet Packages for Faster Builds

By default, NuGet packages are downloaded fresh on every run. For a project with many dependencies, this adds 30–90 seconds per build. Caching fixes this:

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Cache NuGet packages
        uses: actions/cache@v4
        with:
          path: ~/.nuget/packages
          key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj') }}
          restore-keys: |
            ${{ runner.os }}-nuget-

      - name: Restore dependencies
        run: dotnet restore

      - name: Build
        run: dotnet build --no-restore --configuration Release

      - name: Test
        run: dotnet test --no-build --configuration Release

The cache key is based on the hash of all .csproj files. When you add or update a package, the hash changes, the cache misses, and packages are downloaded fresh. Otherwise, the cached packages are used immediately.

Running Tests and Publishing Coverage Reports

Knowing tests pass is good. Knowing coverage isn't dropping is better. Add coverage reporting with Coverlet:

First, add the package to your test project:

dotnet add package coverlet.collector

Then update your test step:

      - name: Test with coverage
        run: |
          dotnet test --no-build --configuration Release \
            --collect:"XPlat Code Coverage" \
            --results-directory ./coverage

      - name: Upload coverage report
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: ./coverage

For a richer experience, use Codecov or the built-in GitHub summary:

      - name: Test with coverage summary
        run: |
          dotnet test --no-build --configuration Release \
            --logger "trx;LogFileName=test-results.trx" \
            --collect:"XPlat Code Coverage"

      - name: Publish test results
        uses: dorny/test-reporter@v1
        if: always()
        with:
          name: .NET Test Results
          path: '**/*.trx'
          reporter: dotnet-trx

The if: always() ensures test results are published even when tests fail — so you can see which tests broke.

Matrix Builds: Testing on Multiple .NET Versions

If your library or API needs to support multiple .NET versions, matrix builds test all of them in parallel:

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        dotnet-version: [ '8.0.x', '9.0.x' ]

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup .NET ${{ matrix.dotnet-version }}
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ matrix.dotnet-version }}

      - name: Restore, Build, Test
        run: |
          dotnet restore
          dotnet build --no-restore --configuration Release
          dotnet test --no-build --configuration Release

This runs two parallel jobs — one for .NET 8, one for .NET 9 — and reports results for each independently.

Building and Pushing a Docker Image

Once tests pass, build a Docker image and push it to a container registry. First, make sure you have a Dockerfile in your project:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 8080

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["MyApi/MyApi.csproj", "MyApi/"]
RUN dotnet restore "MyApi/MyApi.csproj"
COPY . .
WORKDIR "/src/MyApi"
RUN dotnet build --configuration Release --output /app/build

FROM build AS publish
RUN dotnet publish --configuration Release --output /app/publish /p:UseAppHost=false

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyApi.dll"]

Now add a Docker job to your workflow that runs after the tests pass:

  docker:
    runs-on: ubuntu-latest
    needs: build-and-test
    if: github.ref == 'refs/heads/main'

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            yourusername/myapi:latest
            yourusername/myapi:${{ github.sha }}

The needs: build-and-test ensures Docker only runs if tests pass. The if: github.ref == 'refs/heads/main' ensures we only push images from the main branch, not from every feature branch.

Add your Docker Hub credentials as repository secrets under Settings → Secrets and variables → Actions.

Deploying to Azure App Service

For deploying to Azure App Service, use the official Azure action. You'll need an Azure publish profile stored as a secret:

  deploy:
    runs-on: ubuntu-latest
    needs: docker
    if: github.ref == 'refs/heads/main'
    environment: production

    steps:
      - name: Deploy to Azure App Service
        uses: azure/webapps-deploy@v3
        with:
          app-name: 'my-dotnet-api'
          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
          images: 'yourusername/myapi:${{ github.sha }}'

The environment: production adds a manual approval gate — someone must approve the deployment in the GitHub UI before it proceeds. Essential for production deployments.

To get the publish profile, go to your App Service in the Azure Portal → Get Publish Profile → download the file → paste the contents into a GitHub secret named AZURE_WEBAPP_PUBLISH_PROFILE.

Using Secrets and Environment Variables Safely

Never hardcode connection strings, API keys, or credentials in your workflow files. Use GitHub secrets for sensitive values and environment variables for non-sensitive configuration:

    steps:
      - name: Run integration tests
        env:
          # Non-sensitive — fine in the workflow file
          ASPNETCORE_ENVIRONMENT: Testing
          # Sensitive — always use secrets
          ConnectionStrings__DefaultConnection: ${{ secrets.TEST_DB_CONNECTION }}
          ExternalApi__ApiKey: ${{ secrets.EXTERNAL_API_KEY }}
        run: dotnet test --filter Category=Integration

For environment-specific configuration across multiple jobs, use workflow-level environment variables:

env:
  DOTNET_VERSION: '8.0.x'
  BUILD_CONFIGURATION: Release
  AZURE_APP_NAME: 'my-dotnet-api'

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ env.DOTNET_VERSION }}

      - name: Build
        run: dotnet build --configuration ${{ env.BUILD_CONFIGURATION }}

Complete Pipeline: Putting It All Together

Here's the full production-ready workflow combining everything above:

name: CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

env:
  DOTNET_VERSION: '8.0.x'
  BUILD_CONFIGURATION: Release
  DOCKER_IMAGE: yourusername/myapi

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ env.DOTNET_VERSION }}

      - name: Cache NuGet packages
        uses: actions/cache@v4
        with:
          path: ~/.nuget/packages
          key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj') }}
          restore-keys: ${{ runner.os }}-nuget-

      - name: Restore
        run: dotnet restore

      - name: Build
        run: dotnet build --no-restore --configuration ${{ env.BUILD_CONFIGURATION }}

      - name: Test
        run: |
          dotnet test --no-build \
            --configuration ${{ env.BUILD_CONFIGURATION }} \
            --collect:"XPlat Code Coverage" \
            --logger "trx;LogFileName=test-results.trx"

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: '**/*.trx'

  docker:
    runs-on: ubuntu-latest
    needs: build-and-test
    if: github.ref == 'refs/heads/main'

    steps:
      - uses: actions/checkout@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ env.DOCKER_IMAGE }}:latest
            ${{ env.DOCKER_IMAGE }}:${{ github.sha }}

  deploy:
    runs-on: ubuntu-latest
    needs: docker
    if: github.ref == 'refs/heads/main'
    environment: production

    steps:
      - name: Deploy to Azure App Service
        uses: azure/webapps-deploy@v3
        with:
          app-name: 'my-dotnet-api'
          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
          images: '${{ env.DOCKER_IMAGE }}:${{ github.sha }}'

This gives you three jobs in sequence: build and test → build Docker image → deploy to Azure, with manual approval on the final step.

Common Errors and How to Avoid Them

Error: Process completed with exit code 1 on dotnet test
This usually means a test failed, not a configuration problem. Check the test output in the Actions log. If tests pass locally but fail in CI, the most common cause is a missing environment variable or a test that depends on local state (file system, local database). Use --verbosity normal to see detailed output.

Docker build fails with COPY failed: file not found
The Docker build context in GitHub Actions is the repository root by default. If your Dockerfile references files with relative paths, make sure those paths are relative to the root, not to the Dockerfile's location. Set context: . explicitly in the docker/build-push-action step.

Secrets not available in pull requests from forks
For security, GitHub doesn't expose secrets to workflows triggered by pull requests from forks. This is intentional. Run integration tests that need secrets only on push events, not on pull_request from external contributors.

NuGet cache never hits
If the cache key changes on every run, check whether any .csproj file is being modified during the build (e.g. by a code generator). Use restore-keys as a fallback to get a partial cache hit even when the primary key misses.

Deployment runs even when tests fail
Always use needs: build-and-test on your deployment job. Without it, jobs run in parallel and a failing test won't stop a deployment. Add if: success() for extra safety.

azure/webapps-deploy fails with 403
The publish profile may be expired or from the wrong slot. Re-download it from the Azure Portal and update the secret. Also verify the app-name matches exactly — it's case-sensitive.

Best Practices

Never skip tests in CI. If tests are slow, fix the tests — don't disable them.
Pin action versions with a full SHA for security-critical workflows. actions/checkout@v4 is convenient; actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 is safer.
Use environments with required reviewers for production deployments. A manual approval gate prevents accidents.
Tag Docker images with the git SHA, not just latest. latest is a moving target that makes rollbacks painful.
Keep secrets minimal. Each secret should have the minimum permissions needed. Rotate them regularly.
Add a status badge to your README. It signals professionalism and shows the current build status at a glance.
Use concurrency groups to cancel in-progress runs when a new push arrives on the same branch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Conclusion

A CI/CD pipeline is one of the highest-ROI investments you can make in a .NET project. The first time it catches a broken build before it reaches production, or saves you from a failed manual deployment at 6pm on a Friday, it pays for itself.

The workflow in this article gives you everything you need for a real project: fast builds with NuGet caching, test results with coverage, Docker images tagged by commit SHA, and a deployment to Azure with a manual approval gate.

Start with just the build and test job. Add Docker and deployment once that's stable. Complexity can always be added later — the habit of always having CI running is what matters from day one.

In the next article in this series, we'll look at deploying .NET applications to Azure in depth — App Service, Container Apps, managed identity, and Application Insights for production monitoring.

🚀 Just shipped major updates to The Coffee Timer!

Adrián Bailador — Sun, 08 Mar 2026 19:50:41 +0000

New features that make focusing on deep work actually enjoyable:

📋 Task Integration
Connect your pomodoros to actual tasks. See what you're working on, track progress, and get that dopamine hit when tasks are completed.

⚡ Real-Time Sync
Using Supabase Realtime. Add a task on your phone? It's instantly on your desktop. No refresh needed.

🔥 Smart Streaks
The app tracks your daily goals and longest streaks. Gamification that actually works.

🤖 AI Daily Summaries (Premium)
End-of-day summaries powered by Claude AI. What you achieved, patterns spotted, recommendations for tomorrow.

🎨 Beautiful UX
Dark mode, ambient sounds, smooth animations. Because productivity tools shouldn't be ugly.

Built with: React + TypeScript | .NET 8 | Supabase | Stripe | Claude AI

🔗 Try it: https://thecoffeetimer.com/

What features would make YOUR perfect productivity timer? 👇

Messaging in .NET: Queues, Topics, and Why You Need Them

Adrián Bailador — Sat, 07 Mar 2026 10:59:44 +0000

An introduction to asynchronous messaging in .NET — what queues and topics are, how delivery semantics work, and which broker to choose for your next project.

Introduction: The Problem with Direct API Calls

Imagine you have an e-commerce application. When a customer places an order, your API needs to:

Save the order to the database
Send a confirmation email
Notify the warehouse system
Update the inventory
Trigger a loyalty points calculation

The naive approach is to do all of this synchronously in a single HTTP request. Your controller calls five different services, waits for each one to respond, and then returns a 200 OK to the user.

This works — until it doesn't.

What happens when the email service is slow? The user waits. What happens when the warehouse system is down? The entire order fails. What happens under heavy traffic? Your API becomes a bottleneck, holding connections open while it waits for downstream services to respond.

This is the problem that messaging solves. Instead of calling downstream services directly, you publish a message to a broker. The broker stores it. The downstream services consume it when they're ready. Your API returns immediately. The customer gets a fast response. Everything else happens in the background, reliably, even if individual services are temporarily unavailable.

In this article, I'll cover the core concepts you need before diving into any specific broker — queues, topics, delivery semantics, and the key patterns that make distributed messaging reliable.

Synchronous vs Asynchronous Communication

Before queues and topics, it's worth being precise about what we mean by synchronous and asynchronous.

Synchronous communication means the caller waits for a response. HTTP REST calls are synchronous. Your API calls the inventory service and blocks until it gets a reply. The caller and the receiver are temporally coupled — they must both be available at the same moment.

Asynchronous communication means the caller sends a message and moves on. The receiver processes it independently, at its own pace, potentially much later. The caller and receiver are decoupled in time — the receiver doesn't even need to be running when the message is sent.

// Synchronous — tight coupling
var result = await _inventoryService.UpdateStockAsync(productId, quantity);
// If inventory service is down, this throws. Order fails.

// Asynchronous — loose coupling
await _messageBus.PublishAsync(new StockUpdateRequested(productId, quantity));
// Message is stored. Even if inventory service is down, it processes when it recovers.

Asynchronous messaging doesn't replace synchronous communication — it complements it. Use HTTP when you need an immediate response. Use messaging when you need reliability, scalability, or decoupling.

Queues vs Topics: What's the Difference?

These two concepts are the foundation of every messaging system, and they're frequently confused.

Queues — One Producer, One Consumer

A queue is a first-in, first-out data structure. A producer sends a message to the queue. One consumer picks it up and processes it. Once processed, the message is gone.

Producer → [Queue] → Consumer A

This is a point-to-point pattern. If you have multiple consumers reading from the same queue, each message goes to exactly one of them (competing consumers). This is ideal for work distribution — multiple workers processing jobs in parallel without duplicating the work.

Use queues when:

You need to distribute work across multiple workers
Each message should be processed exactly once
You're building task queues, job runners, or command handlers

Topics — One Producer, Many Consumers

A topic (sometimes called an exchange or a pub/sub channel) allows one producer to send a message that gets delivered to multiple independent consumers simultaneously. Each consumer gets its own copy.

Producer → [Topic] → Consumer A (sends email)
                   → Consumer B (updates warehouse)
                   → Consumer C (calculates points)

This is the publish/subscribe (pub/sub) pattern. When an OrderPlaced event is published, every service that cares about orders receives it independently. The order service doesn't know or care who's listening.

Use topics when:

Multiple independent services need to react to the same event
You want to add new subscribers without modifying the producer
You're building an event-driven architecture

The Practical Difference in Code

// Queue: send a command to be processed once
await bus.Send(new ProcessPaymentCommand
{
    OrderId = orderId,
    Amount = total
});

// Topic: publish an event that multiple services can react to
await bus.Publish(new OrderPlacedEvent
{
    OrderId = orderId,
    CustomerId = customerId,
    TotalAmount = total,
    PlacedAt = DateTime.UtcNow
});

The naming convention reveals the intent: commands are sent (to a specific queue), events are published (to anyone who's interested).

Delivery Semantics: At Most Once, At Least Once, Exactly Once

This is where things get interesting — and where many developers make mistakes that lead to data corruption or silent data loss.

At Most Once

The broker delivers the message once and doesn't retry if something goes wrong. The message may be lost if the consumer crashes mid-processing. No duplicates, but possible data loss.

Broker → Consumer (crashes mid-process)
Message is lost. No retry.

When to use it: Metrics, analytics, log events — data where occasional loss is acceptable.

At Least Once

The broker keeps the message until the consumer explicitly acknowledges (acks) it. If the consumer crashes before acking, the broker redelivers. This guarantees no data loss, but the same message may be delivered more than once.

Broker → Consumer (processes but crashes before ack)
Broker → Consumer (redeliver — message processed twice)

This is the default in most production systems. RabbitMQ, Azure Service Bus, and AWS SQS all default to at-least-once delivery.

The consequence: your consumers must be idempotent — processing the same message twice must produce the same result as processing it once.

public async Task HandleAsync(OrderPlacedEvent message)
{
    // ✅ Idempotent — checking prevents duplicate processing
    if (await _db.Orders.AnyAsync(o => o.Id == message.OrderId))
        return;

    await _db.Orders.AddAsync(new Order(message));
    await _db.SaveChangesAsync();
}

Exactly Once

The broker guarantees each message is processed exactly once. In theory this is ideal. In practice, true exactly-once delivery is extremely difficult to achieve across distributed systems and comes with significant performance overhead.

Most teams don't need exactly-once delivery at the broker level. At-least-once delivery with idempotent consumers achieves the same result in practice.

Key Concepts Every .NET Developer Should Know

Dead Letter Queues (DLQ)

When a message can't be processed — because of an exception, a schema mismatch, or too many failed retries — it gets moved to a dead letter queue instead of being lost.

[Main Queue] → Consumer (fails 3 times)
                    ↓
             [Dead Letter Queue] ← inspect, fix, replay

Dead letter queues are essential for observability. Without them, failed messages vanish silently. With them, you can inspect what went wrong, fix the bug, and replay the messages.

Idempotency Keys

Since at-least-once delivery means duplicates are possible, consumers need a way to detect them. An idempotency key is a unique identifier per message that the consumer checks before processing.

public class ProcessPaymentHandler
{
    private readonly IIdempotencyStore _store;

    public async Task HandleAsync(ProcessPaymentCommand command)
    {
        // Check if already processed
        if (await _store.ExistsAsync(command.MessageId))
            return;

        await ProcessPaymentAsync(command);

        // Mark as processed
        await _store.MarkAsync(command.MessageId);
    }
}

Deduplication Windows

Some brokers (Azure Service Bus, AWS SQS FIFO) support server-side deduplication. Within a time window, messages with the same deduplication ID are automatically discarded.

// Azure Service Bus — set the message ID for deduplication
var message = new ServiceBusMessage(payload)
{
    MessageId = $"order-{orderId}-placed"  // Broker deduplicates on this
};

Retry Policies and Backoff

Most brokers support automatic retries on failure. The key is to use exponential backoff — increasing the delay between retries to avoid hammering a struggling downstream service.

// MassTransit retry policy
cfg.UseMessageRetry(r =>
    r.Exponential(
        retryLimit: 5,
        minInterval: TimeSpan.FromSeconds(1),
        maxInterval: TimeSpan.FromMinutes(5),
        intervalDelta: TimeSpan.FromSeconds(5)
    ));

Which Broker to Choose

The three most common options in the .NET ecosystem each have different strengths.

RabbitMQ

Open source, self-hosted, extremely flexible. Supports complex routing rules, multiple exchange types, and fine-grained control over message flow. The AMQP protocol gives you features that cloud-managed services don't offer.

Choose RabbitMQ when: you need full control, want to self-host, or need advanced routing. Ideal for on-premises or containerised deployments.

docker run -d --hostname rabbit --name rabbitmq \
  -p 5672:5672 -p 15672:15672 \
  rabbitmq:3-management

Azure Service Bus

Fully managed, enterprise-grade messaging on Azure. Supports queues, topics, subscriptions, sessions (for ordered processing), and has native integration with the Azure ecosystem.

Choose Azure Service Bus when: you're already on Azure and want zero infrastructure management. Excellent SLA, built-in geo-redundancy, and deep integration with Azure Functions and Logic Apps.

AWS SQS + SNS

SQS is a managed queue service. SNS is a managed pub/sub service. They're designed to be used together — SNS fans out to multiple SQS queues. Extremely scalable, pay-per-use, and deeply integrated with the AWS ecosystem.

Choose SQS + SNS when: you're on AWS and want fully managed, highly scalable messaging without the operational overhead.

Quick Comparison

	RabbitMQ	Azure Service Bus	AWS SQS + SNS
Hosting	Self-managed	Fully managed	Fully managed
Protocol	AMQP	AMQP / HTTPS	HTTPS
Routing flexibility	Very high	Medium	Medium
Cost	Infrastructure only	Per operation	Per operation
Best for	On-prem / containers	Azure workloads	AWS workloads

When to Use Messaging (and When NOT To)

Messaging adds complexity. It introduces eventual consistency, requires idempotent consumers, and adds operational overhead. It's not always the right tool.

Use messaging when:

Operations are slow and don't need an immediate result (email sending, PDF generation, report processing)
Multiple services need to react to the same event independently
You need to buffer traffic spikes and protect downstream services
Reliability matters more than immediacy — the work must eventually happen even if a service is temporarily down

Don't use messaging when:

You need an immediate response — use HTTP
The operation is simple and happens within a single bounded context
You're adding unnecessary complexity to a problem that a simple service call solves
Your team isn't ready for the operational complexity of a message broker

A common mistake is reaching for messaging too early. Start with synchronous calls, identify where coupling, latency, or reliability becomes a problem, and introduce messaging at those specific seams.

Common Errors and How to Avoid Them

Processing messages without idempotency checks
At-least-once delivery means duplicates will happen. Without idempotency, you'll charge customers twice, send duplicate emails, or create duplicate records. Always check whether a message has already been processed before acting on it.

Not configuring a dead letter queue
Without a DLQ, failed messages are silently dropped or cause infinite retry loops. Always configure a DLQ and set up alerts when messages arrive there.

// RabbitMQ — declare a dead letter exchange
channel.QueueDeclare("orders", arguments: new Dictionary<string, object>
{
    { "x-dead-letter-exchange", "orders.dlx" },
    { "x-max-retries", 3 }
});

Putting too much data in the message payload
Messages should carry just enough information to identify the event and trigger processing — not entire object graphs. Large payloads increase latency and make schema evolution painful. Use the Claim Check pattern for large data: store the payload elsewhere and put only a reference in the message.

// ❌ Too much data in the message
new OrderPlacedEvent { Order = entireOrderObjectWithAllRelations };

// ✅ Just the identifiers — consumers fetch what they need
new OrderPlacedEvent { OrderId = orderId, CustomerId = customerId };

Ignoring message ordering
Most brokers don't guarantee message ordering by default. If your consumer assumes OrderUpdated always arrives after OrderCreated, you'll have subtle bugs. Either design consumers to handle out-of-order messages, or use ordering guarantees (SQS FIFO, Service Bus sessions) where ordering truly matters.

Forgetting about schema evolution
Once you publish messages, consumers depend on their shape. Changing a field name or removing a property breaks consumers. Use additive changes only — add new optional fields, never remove or rename existing ones. Consider a schema registry for large teams.

Best Practices

Start with a queue, move to topics when you have multiple consumers. Don't over-architect from day one.
Make every consumer idempotent. Assume every message will be delivered more than once.
Always configure dead letter queues. Failed messages must be observable, not silently lost.
Use exponential backoff for retries. Hammering a failing service makes things worse.
Keep message payloads small. Include identifiers, not full objects.
Name messages as past-tense events. OrderPlaced, not PlaceOrder. Events describe what happened; commands describe what to do.
Version your message contracts. Plan for schema evolution before you ship.
Monitor consumer lag. If messages are accumulating in a queue faster than they're being consumed, something is wrong.

Conclusion

Messaging is one of the most powerful tools for building resilient, scalable .NET applications — and one of the most misunderstood. The core ideas are simpler than they seem: queues for point-to-point work distribution, topics for broadcasting events to multiple consumers, and at-least-once delivery with idempotent consumers as the default approach.

Understanding these fundamentals before picking a broker will save you from the most common pitfalls: messages that silently disappear, consumers that process the same event multiple times, and systems that fail in non-obvious ways under load.

In the next article in this series, we'll put these concepts into practice with RabbitMQ: setting it up with Docker, sending and consuming messages in .NET, implementing dead letter queues, and building a real order processing example from scratch.

Getting Started with PostgreSQL in .NET: From Zero to Production

Adrián Bailador — Sun, 22 Feb 2026 13:43:13 +0000

Getting started with PostgreSQL in .NET using Entity Framework Core and Dapper. Learn how to set up PostgreSQL with Docker, run migrations, use JSONB and arrays, and connect your ASP.NET Core API to a production-ready database.

Introduction: Why PostgreSQL Over SQL Server?

If you've been working with SQL Server for a while, switching to PostgreSQL might feel unnecessary. But more and more .NET teams are making the move — and for good reasons.

PostgreSQL is open source, free, and runs on any platform. It's battle-tested at scale by companies like Apple, Instagram, and Spotify. It handles relational data as well as SQL Server, but also supports native JSON storage, full-text search, arrays, custom types, and vector search through the pgvector extension — all without additional licensing costs.

For .NET developers, the ecosystem is mature. The Npgsql driver has first-class support for Entity Framework Core and Dapper, and the development experience is practically identical to what you're used to.

In this article, I'll walk you through everything you need to go from zero to a working .NET application backed by PostgreSQL — locally with Docker, through migrations, and into production-ready territory.

Setting Up PostgreSQL Locally with Docker

The fastest way to get PostgreSQL running locally is with Docker. No installation, no PATH conflicts, no version headaches.

Create a docker-compose.yml in your project root:

version: '3.8'

services:
  postgres:
    image: postgres:16
    container_name: pg_dev
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: yourpassword
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Start it with:

docker compose up -d

Verify it's running:

docker exec -it pg_dev psql -U admin -d myapp

You can also use a GUI like pgAdmin or DBeaver if you prefer a visual interface. Connect with:

Host: localhost
Port: 5432
User: admin
Password: yourpassword
Database: myapp

Connecting to PostgreSQL with Entity Framework Core (Npgsql)

Install the packages

dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add package Microsoft.EntityFrameworkCore.Design

Create your models

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public DateTime CreatedAt { get; set; }
    public bool IsAvailable { get; set; }
}

Configure the DbContext

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    public DbSet<Product> Products => Set<Product>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Product>(entity =>
        {
            entity.HasKey(e => e.Id);
            entity.Property(e => e.Name).IsRequired().HasMaxLength(200);
            entity.Property(e => e.Price).HasColumnType("numeric(18,2)");
            entity.Property(e => e.CreatedAt).HasDefaultValueSql("NOW()");
        });
    }
}

Register in Program.cs

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Postgres")));

Add the connection string to appsettings.json

{
  "ConnectionStrings": {
    "Postgres": "Host=localhost;Port=5432;Database=myapp;Username=admin;Password=yourpassword"
  }
}

Connecting with Dapper

For scenarios where you need raw SQL — reports, complex joins, stored procedures — Dapper is a great companion to EF Core.

Install the package

dotnet add package Dapper
dotnet add package Npgsql

Create a connection factory

public interface IDbConnectionFactory
{
    NpgsqlConnection CreateConnection();
}

public class PostgresConnectionFactory : IDbConnectionFactory
{
    private readonly string _connectionString;

    public PostgresConnectionFactory(IConfiguration configuration)
    {
        _connectionString = configuration.GetConnectionString("Postgres")!;
    }

    public NpgsqlConnection CreateConnection()
    {
        return new NpgsqlConnection(_connectionString);
    }
}

builder.Services.AddSingleton<IDbConnectionFactory, PostgresConnectionFactory>();

Query with Dapper

public class ProductRepository
{
    private readonly IDbConnectionFactory _factory;

    public ProductRepository(IDbConnectionFactory factory)
    {
        _factory = factory;
    }

    public async Task<IEnumerable<Product>> GetAvailableAsync()
    {
        using var connection = _factory.CreateConnection();

        return await connection.QueryAsync<Product>(
            "SELECT * FROM products WHERE is_available = true ORDER BY created_at DESC");
    }

    public async Task<Product?> GetByIdAsync(int id)
    {
        using var connection = _factory.CreateConnection();

        return await connection.QuerySingleOrDefaultAsync<Product>(
            "SELECT * FROM products WHERE id = @Id",
            new { Id = id });
    }

    public async Task<int> CreateAsync(Product product)
    {
        using var connection = _factory.CreateConnection();

        return await connection.ExecuteScalarAsync<int>(
            """
            INSERT INTO products (name, price, is_available)
            VALUES (@Name, @Price, @IsAvailable)
            RETURNING id
            """,
            product);
    }
}

PostgreSQL-Specific Features You'll Love

This is where PostgreSQL starts to shine beyond standard relational databases.

JSONB — Storing Flexible Data

JSONB stores JSON as binary, making it fast to query and index. Perfect for dynamic attributes, metadata, or configuration data.

public class Order
{
    public int Id { get; set; }
    public string CustomerEmail { get; set; } = string.Empty;
    public JsonDocument Metadata { get; set; } = JsonDocument.Parse("{}");
}

Configure it in your DbContext:

modelBuilder.Entity<Order>()
    .Property(o => o.Metadata)
    .HasColumnType("jsonb");

Query specific JSONB keys with Dapper:

SELECT * FROM orders
WHERE metadata->>'region' = 'EU'
  AND (metadata->>'total')::numeric > 500;

Arrays — Native List Support

No junction tables needed for simple lists of primitive values.

public class Article
{
    public int Id { get; set; }
    public string Title { get; set; } = string.Empty;
    public string[] Tags { get; set; } = [];
}

Configure it:

modelBuilder.Entity<Article>()
    .Property(a => a.Tags)
    .HasColumnType("text[]");

Query articles that have a specific tag:

var articles = await context.Articles
    .Where(a => a.Tags.Contains("dotnet"))
    .ToListAsync();

Enum Types — Readable Data in the Database

Instead of storing magic numbers or plain strings, use PostgreSQL native enums.

public enum OrderStatus
{
    Pending,
    Processing,
    Shipped,
    Delivered,
    Cancelled
}

public class Order
{
    public int Id { get; set; }
    public OrderStatus Status { get; set; }
}

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("Postgres"),
        o => o.MapEnum<OrderStatus>("order_status")));

And in OnModelCreating:

modelBuilder.HasPostgresEnum<OrderStatus>("order_status");

Running Migrations with EF Core

Install the CLI tool (if you haven't already)

dotnet tool install --global dotnet-ef

Create and apply your first migration

dotnet ef migrations add InitialCreate
dotnet ef database update

Generating a script for production

Never run dotnet ef database update directly in production. Instead, generate a SQL script and run it through your deployment pipeline:

dotnet ef migrations script --idempotent -o migrations.sql

The --idempotent flag makes the script safe to run multiple times — it only applies migrations that haven't been applied yet.

Applying migrations programmatically on startup

For containerised environments, you can apply pending migrations automatically when the app starts:

using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
}

⚠️ Use this pattern with care in multi-instance deployments. Consider using an init container or a dedicated migration job instead.

Common Errors and How to Avoid Them

Npgsql.PostgresException: column does not exist
PostgreSQL is case-sensitive by default. Column and table names created without quotes are lowercased automatically. If your model has CreatedAt, EF Core maps it to created_at with snake_case conventions (enabled via UseSnakeCaseNamingConvention()). Enable it explicitly:

options.UseNpgsql(connectionString)
       .UseSnakeCaseNamingConvention();

System.InvalidOperationException: No suitable constructor found for entity type
EF Core needs either a parameterless constructor or one it can match to properties. Add a protected parameterless constructor if you have a custom one:

public class Product
{
    protected Product() { } // For EF Core
    public Product(string name, decimal price) { ... }
}

NpgsqlException: SSL connection is required
Production PostgreSQL instances (like Azure Database for PostgreSQL) enforce SSL. Update your connection string:

Host=myserver.postgres.database.azure.com;...;Ssl Mode=Require;Trust Server Certificate=true;

Enum migration fails with type already exists
If you drop and recreate the database during development, Npgsql may try to create the enum type again. Wrap the enum creation in a migration check, or use HasPostgresEnum() which handles this safely.

Slow queries after a large data load
PostgreSQL relies on table statistics to build query plans. After bulk inserts, run:

ANALYZE products;

Or let the autovacuum daemon handle it automatically in production.

Best Practices

Use snake_case naming conventions with UseSnakeCaseNamingConvention() — this avoids constant quoting issues and aligns with PostgreSQL conventions.
Don't use dotnet ef database update in production — always generate and review SQL scripts before applying them.
Index foreign keys — PostgreSQL does not create indexes on foreign key columns automatically, unlike SQL Server.
Use NOW() for server-side timestamps — instead of setting DateTime.UtcNow in C#, use HasDefaultValueSql("NOW()") to let the database handle it.
Prefer jsonb over json — jsonb is stored as parsed binary and supports indexing. json stores raw text and is slower to query.
Pool your connections — Npgsql includes connection pooling by default. Avoid creating NpgsqlConnection instances as singletons; always open and dispose per request.
Monitor with pg_stat_statements — enable this extension to track slow queries across your application in production.

Conclusion

PostgreSQL is a powerful, production-proven database that integrates seamlessly with the .NET ecosystem. Whether you're using Entity Framework Core for its migration and LINQ support, or Dapper for raw SQL performance, the tooling is mature and the developer experience is excellent.

The features covered here — JSONB, arrays, enum types, and EF Core migrations — are the ones you'll reach for most often in real projects. Start with them, and you'll quickly see why so many teams are moving away from SQL Server and never looking back.

In the next article in this series, we'll go deeper into PostgreSQL query performance: understanding EXPLAIN ANALYZE, building the right indexes, and optimising the queries that EF Core generates under the hood.

Vertical Slice Architecture in .NET

Adrián Bailador — Fri, 13 Feb 2026 19:46:30 +0000

Organize your code by what it does, not where it lives

Most .NET applications are organized in horizontal layers: Presentation, Business Logic, and Data Access. But what if we organized code by business features instead?

Welcome to Vertical Slice Architecture (VSA), a pattern that's changing how we structure modern .NET applications.

TL;DR: Vertical Slice Architecture groups all code for a feature together (API → Logic → Database). No more jumping between 5 folders to understand one thing.

🎂 What is Vertical Slice Architecture?

Vertical Slice Architecture is a code organization pattern that groups all code for a single feature or use case together, from the user interface down to the database.

The Core Concept

Think of your application as a cake. Traditional architectures cut the cake horizontally into layers:

Top layer: Presentation (Controllers, Views)
Middle layer: Business Logic (Services, Commands)
Bottom layer: Data Access (Repositories, DbContext)

Vertical Slice Architecture cuts the cake vertically. Each slice contains everything needed for one specific feature:

Slice 1: "Create Product" → Complete from API to Database
Slice 2: "Ship Order" → Complete from API to Database
Slice 3: "Register User" → Complete from API to Database

Why "Vertical"?

A vertical slice cuts through all layers for a single feature. When you need to add a field to "Create Product", you only touch files in Features/Products/Create/. No jumping between Controllers → Services → Repositories.

📁 Project Structure

MyApp/
├── Features/
│   ├── Products/
│   │   ├── Create/
│   │   │   ├── CreateProduct.cs
│   │   │   └── CreateProductEndpoint.cs
│   │   ├── Update/
│   │   ├── Delete/
│   │   └── GetById/
│   ├── Orders/
│   │   ├── Create/
│   │   ├── Ship/
│   │   └── Cancel/
│   └── Customers/
├── Common/              # Only truly shared infrastructure
│   ├── Behaviors/       # MediatR pipeline behaviors
│   └── Results/
├── Data/
│   ├── AppDbContext.cs
│   └── Entities/
└── Program.cs

Everything for "Create Product" lives in one place: Features/Products/Create/.

⚖️ Core Principles

1. Feature-First Organization

Code is organized by what it does (business capability), not by what it is (technical role).

Traditional (Layered)	Vertical Slice
`Controllers/ProductsController.cs`	`Features/Products/Create/CreateProduct.cs`
`Services/ProductService.cs`	`Features/Products/Create/CreateProductEndpoint.cs`
`Repositories/ProductRepository.cs`	(Logic & Data access are inside the slice)

To understand "Create Product", you read one folder instead of three files in three different folders.

2. High Cohesion, Low Coupling

High Cohesion: Related code stays together. Command, validation, and logic are all in one file or folder. You see the complete picture immediately.
Low Coupling: Features don't depend on each other. Deleting "Create Product" won't break "Ship Order". Each feature can evolve independently.

3. Minimal Abstractions

Create abstractions only when you have actual shared behavior. In VSA, we often use the DbContext directly in the handler.

Don't do this:

// Abstraction for a single implementation
public interface IProductRepository
{
    Task<Product> GetByIdAsync(int id);
}

public class ProductRepository : IProductRepository
{
    // Only implementation, will never be swapped
}

Do this:

// Direct database access in the handler
public class Handler : IRequestHandler<Query, Result<ProductDto>>
{
    private readonly AppDbContext _db;

    public async Task<Result<ProductDto>> Handle(Query request, CancellationToken ct)
    {
        var product = await _db.Products
            .Where(p => p.Id == request.Id)
            .Select(p => new ProductDto { Id = p.Id, Name = p.Name })
            .FirstOrDefaultAsync(ct);

        return product != null 
            ? Result<ProductDto>.Success(product)
            : Result<ProductDto>.Failure("Product not found");
    }
}

If you aren't swapping your DB for a text file tomorrow, you probably don't need a Repository Layer.

4. Duplication Over Wrong Abstraction

It's okay to duplicate a DTO or a small piece of logic between slices if it keeps them independent.

// Products/Create
var product = new Product {
    CreatedAt = DateTime.UtcNow,
    CreatedBy = _currentUser.Id
};

// Orders/Create - Same code, that's OK!
var order = new Order {
    CreatedAt = DateTime.UtcNow,
    CreatedBy = _currentUser.Id
};

The Rule of Three: Extract common code only when you use it in 3+ features, not before.

Why? Because those two features might diverge in the future. Premature abstraction creates coupling.

🛠️ Complete Implementation: "Create Product"

Let's build a feature from scratch using MediatR and Minimal APIs.

Step 1: The Command and Handler

// Features/Products/Create/CreateProduct.cs

namespace MyApp.Features.Products.Create;

public static class CreateProduct
{
    // The request
    public record Command(
        string Name, 
        decimal Price, 
        int CategoryId
    ) : IRequest<Result<int>>;

    // Validation rules
    public class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(x => x.Name).NotEmpty().MaximumLength(100);
            RuleFor(x => x.Price).GreaterThan(0).LessThan(1000000);
            RuleFor(x => x.CategoryId).GreaterThan(0);
        }
    }

    // Business logic
    public class Handler : IRequestHandler<Command, Result<int>>
    {
        private readonly AppDbContext _db;
        private readonly ILogger<Handler> _logger;

        public Handler(AppDbContext db, ILogger<Handler> logger)
        {
            _db = db;
            _logger = logger;
        }

        public async Task<Result<int>> Handle(Command request, CancellationToken ct)
        {
            // Business rule: Category must exist
            var categoryExists = await _db.Categories
                .AnyAsync(c => c.Id == request.CategoryId, ct);

            if (!categoryExists)
                return Result<int>.Failure("Category not found");

            // Create product
            var product = new Product {
                Name = request.Name,
                Price = request.Price,
                CategoryId = request.CategoryId,
                CreatedAt = DateTime.UtcNow
            };

            _db.Products.Add(product);
            await _db.SaveChangesAsync(ct);

            _logger.LogInformation(
                "Created product {ProductId}: {ProductName}",
                product.Id, product.Name);

            return Result<int>.Success(product.Id);
        }
    }
}

Everything in one file: Request, validation, and business logic. You can understand the entire feature without opening multiple files.

Step 2: The Endpoint

// Features/Products/Create/CreateProductEndpoint.cs

public class CreateProductEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/api/products", async (
            CreateProduct.Command request, 
            IMediator mediator,
            CancellationToken ct) =>
        {
            var result = await mediator.Send(request, ct);

            return result.IsSuccess 
                ? Results.Created($"/api/products/{result.Value}", new { id = result.Value }) 
                : Results.BadRequest(new { error = result.Error });
        })
        .WithName("CreateProduct")
        .WithTags("Products");
    }
}

That's it! A complete feature in 2 files.

Step 3: Supporting Types

// Common/Results/Result.cs

public class Result<T>
{
    public bool IsSuccess { get; }
    public T Value { get; }
    public string Error { get; }

    private Result(bool isSuccess, T value, string error)
    {
        IsSuccess = isSuccess;
        Value = value;
        Error = error;
    }

    public static Result<T> Success(T value) => new(true, value, string.Empty);
    public static Result<T> Failure(string error) => new(false, default!, error);
}

🌊 How a Request Flows

Let's trace a request through the system:

User Request: POST /api/products

{
  "name": "Laptop",
  "price": 1299.99,
  "categoryId": 5
}

Flow:

Endpoint receives request → Deserializes into CreateProduct.Command
MediatR pipeline begins → mediator.Send(request)
Validation runs automatically → ValidationBehavior intercepts and runs CreateProduct.Validator
- If validation fails → Returns 400 Bad Request
- If validation passes → Continues to handler
Logging (automatic) → LoggingBehavior logs the request
Handler executes → Business rules, database operations
Response returned → Result<int> converted to HTTP response
- Success → 201 Created
- Failure → 400 Bad Request

Key insight: Validation and logging happen automatically via MediatR pipeline behaviors. You don't write that code in every handler.

🔄 Cross-Cutting Concerns with MediatR Behaviors

Common functionality is handled by pipeline behaviors, not inheritance or base classes.

Validation Behavior

// Common/Behaviors/ValidationBehavior.cs

public class ValidationBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        if (!_validators.Any())
            return await next();

        var context = new ValidationContext<TRequest>(request);
        var failures = _validators
            .Select(v => v.Validate(context))
            .SelectMany(result => result.Errors)
            .Where(f => f != null)
            .ToList();

        if (failures.Any())
            throw new ValidationException(failures);

        return await next();
    }
}

Logging Behavior

// Common/Behaviors/LoggingBehavior.cs

public class LoggingBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly ILogger<LoggingBehavior<TRequest, TResponse>> _logger;

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken ct)
    {
        _logger.LogInformation("Handling {RequestName}", typeof(TRequest).Name);
        var response = await next();
        _logger.LogInformation("Handled {RequestName}", typeof(TRequest).Name);
        return response;
    }
}

Register Behaviors in Program.cs

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
    cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
});

Every feature automatically gets validation and logging without touching each handler.

🧪 Testing Strategy

In VSA, we prioritize Integration Tests. Since the slice is self-contained, testing the API endpoint with a real (or in-memory) database gives you the highest confidence with the least effort.

public class CreateProductTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public CreateProductTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task CreateProduct_WithValidData_ReturnsCreated()
    {
        // Arrange
        var command = new { 
            name = "Laptop", 
            price = 999, 
            categoryId = 1 
        };

        // Act
        var response = await _client.PostAsJsonAsync("/api/products", command);

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.Created);
        var productId = await response.Content.ReadFromJsonAsync<int>();
        productId.Should().BeGreaterThan(0);
    }

    [Fact]
    public async Task CreateProduct_WithInvalidPrice_ReturnsBadRequest()
    {
        // Arrange
        var command = new { 
            name = "Laptop", 
            price = -10,  // Invalid
            categoryId = 1 
        };

        // Act
        var response = await _client.PostAsJsonAsync("/api/products", command);

        // Assert
        response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
    }
}

Why integration tests?

Tests the entire slice end-to-end
Validates that all pieces work together
Catches integration issues early
Closer to how users actually use the system

🔧 Essential Setup

Required NuGet Packages

# MediatR for request/response pattern
dotnet add package MediatR

# FluentValidation for validation
dotnet add package FluentValidation
dotnet add package FluentValidation.DependencyInjectionExtensions

# Carter for minimal API organization (optional)
dotnet add package Carter

# Entity Framework Core
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer

Program.cs Configuration

var builder = WebApplication.CreateBuilder(args);

// Database
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

// MediatR with behaviors
builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
    cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
});

// FluentValidation
builder.Services.AddValidatorsFromAssemblyContaining<Program>();

// Carter (if using)
builder.Services.AddCarter();

var app = builder.Build();

app.UseHttpsRedirection();
app.MapCarter();  // Maps all endpoints

app.Run();

📚 Common Patterns

Pattern 1: Query Features (Read-Only)

// Features/Products/GetById/GetProduct.cs

public static class GetProduct
{
    public record Query(int Id) : IRequest<Result<ProductDto>>;

    public record ProductDto(int Id, string Name, decimal Price, string CategoryName);

    public class Handler : IRequestHandler<Query, Result<ProductDto>>
    {
        private readonly AppDbContext _db;

        public async Task<Result<ProductDto>> Handle(Query request, CancellationToken ct)
        {
            var product = await _db.Products
                .Where(p => p.Id == request.Id)
                .Select(p => new ProductDto(
                    p.Id,
                    p.Name,
                    p.Price,
                    p.Category.Name
                ))
                .FirstOrDefaultAsync(ct);

            return product != null
                ? Result<ProductDto>.Success(product)
                : Result<ProductDto>.Failure("Product not found");
        }
    }
}

Key points:

Use Select to project only needed data
Return DTOs, not entities
One query, optimized for this specific use case

Pattern 2: List/Search Features

// Features/Products/List/ListProducts.cs

public static class ListProducts
{
    public record Query(
        int Page = 1,
        int PageSize = 20,
        string? SearchTerm = null,
        int? CategoryId = null
    ) : IRequest<Result<PagedResult<ProductDto>>>;

    public record ProductDto(int Id, string Name, decimal Price);

    public record PagedResult<T>(List<T> Items, int TotalCount, int Page, int PageSize);

    public class Handler : IRequestHandler<Query, Result<PagedResult<ProductDto>>>
    {
        private readonly AppDbContext _db;

        public async Task<Result<PagedResult<ProductDto>>> Handle(
            Query request,
            CancellationToken ct)
        {
            var query = _db.Products.AsQueryable();

            // Apply filters
            if (!string.IsNullOrWhiteSpace(request.SearchTerm))
                query = query.Where(p => p.Name.Contains(request.SearchTerm));

            if (request.CategoryId.HasValue)
                query = query.Where(p => p.CategoryId == request.CategoryId.Value);

            // Get total count
            var totalCount = await query.CountAsync(ct);

            // Pagination
            var items = await query
                .Skip((request.Page - 1) * request.PageSize)
                .Take(request.PageSize)
                .Select(p => new ProductDto(p.Id, p.Name, p.Price))
                .ToListAsync(ct);

            return Result<PagedResult<ProductDto>>.Success(
                new PagedResult<ProductDto>(items, totalCount, request.Page, request.PageSize));
        }
    }
}

Pattern 3: Features with Domain Events

// Features/Orders/Create/CreateOrder.cs

public static class CreateOrder
{
    public record Command(int CustomerId, List<OrderItemDto> Items) : IRequest<Result<int>>;

    public class Handler : IRequestHandler<Command, Result<int>>
    {
        private readonly AppDbContext _db;
        private readonly IMediator _mediator;

        public async Task<Result<int>> Handle(Command request, CancellationToken ct)
        {
            var order = new Order
            {
                CustomerId = request.CustomerId,
                Status = OrderStatus.Pending,
                CreatedAt = DateTime.UtcNow
            };

            _db.Orders.Add(order);
            await _db.SaveChangesAsync(ct);

            // Publish event - other features can react
            await _mediator.Publish(new OrderCreated(order.Id, request.Items), ct);

            return Result<int>.Success(order.Id);
        }
    }
}

// Features/Inventory/ReserveStock/OrderCreatedHandler.cs

public class OrderCreatedHandler : INotificationHandler<OrderCreated>
{
    private readonly AppDbContext _db;

    public async Task Handle(OrderCreated notification, CancellationToken ct)
    {
        // Update inventory in its own feature
        foreach (var item in notification.Items)
        {
            var product = await _db.Products.FindAsync(item.ProductId, ct);
            if (product != null)
                product.ReservedStock += item.Quantity;
        }

        await _db.SaveChangesAsync(ct);
    }
}

Key insight: Features stay decoupled but can react to each other's events through MediatR notifications.

🚀 Can I Use This in an Existing App?

Yes! VSA's superpower is that you can start TODAY without rewriting anything.

Incremental Adoption Strategy

Phase 1: Coexistence (Month 1-2)

Keep your layered code. Build new features as slices. They can coexist:

MyApp/
├── Controllers/          # Old layered code - still works
│   ├── ProductsController.cs
│   └── OrdersController.cs
├── Services/             # Old layered code - still works
│   ├── ProductService.cs
│   └── OrderService.cs
├── Repositories/         # Old layered code - still works
│   └── ProductRepository.cs
├── Features/             # New slices - start here!
│   ├── Shipping/
│   │   ├── CalculateRate/
│   │   └── TrackPackage/
│   └── Notifications/
│       └── SendEmail/

Benefits:
✅ Zero risk to existing functionality

✅ Team learns VSA gradually

✅ New features ship faster

✅ Easy to rollback if needed

Phase 2: Strategic Migration (Month 3-6)

Migrate one feature at a time. Start with simple CRUD:


// Step 1: Pick a simple feature
// Good candidates:
// - Recently added features (less legacy baggage)
// - Features that change frequently
// - Simple CRUD with few dependencies

// Step 2: Create slice
Features/Products/Archive/ArchiveProduct.cs

// Step 3: Test thoroughly

// Step 4: Delete old code ONLY after new code is in production

Phase 3: Live with Both (Ongoing)

After 6 months:

70-80% slice-based
20-30% still layered
That's perfectly fine!

Don't force migration if the old code works. Focus on new development in slices.

Real Timeline Example:

Month 1:  Build 3 new features as slices
Month 2:  Migrate 5 simple CRUD operations
Month 3:  Migrate 3 medium features
Month 4:  Build all new features as slices
Month 5:  Migrate 2 complex features
Month 6:  Stop migrating, focus on new development
Result:   ~75% slice-based, team velocity up 40%

When to Stop Migrating:

Feature is complex and working fine
Migration cost > benefit
Feature rarely changes
Team isn't comfortable yet

⚠️ Common Pitfalls (And How to Avoid Them)

Even with its simplicity, it's easy to lose the "Vertical" spirit. Here are the most common mistakes:

1. The "Shared" Folder Trap

The #1 question when starting with VSA: "Where do I put code that's used by multiple features? Won't I end up with a huge Shared folder?"

The Problem:

You see two features that both send emails and immediately create:

Common/
├── Services/
│   └── EmailService.cs
├── DTOs/
│   ├── ProductDto.cs         # Feature-specific!
│   └── OrderDto.cs           # Feature-specific!
├── Validators/
│   └── CreateOrderValidator.cs  # Feature-specific!
└── Helpers/
    └── (Everything else)

Before you know it, Common is a dumping ground and features are tightly coupled.

The Solution: A Simple Rule

Share infrastructure, duplicate business logic.

✅ OK to share:

Common/
├── Behaviors/              # MediatR pipeline (logging, validation)
├── Results/               # Generic Result<T> type
├── Interfaces/
│   ├── IEmailSender.cs    # External services
│   └── IFileStorage.cs
└── Extensions/
    └── ValidationExtensions.cs  # Simple reusable rules

Why: These are cross-cutting concerns that apply to ALL features uniformly.

❌ Don't share:

DTOs between features (each feature has its own)
Business logic between features (duplicate instead)
Feature-specific validators
"Helpers" or "Utilities" folders

The Key Insight:

Just because features share the same database entity doesn't mean they share DTOs:

// Data/Entities/Product.cs - Shared database entity
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

// Features/Products/Create/CreateProduct.cs
public record Command(string Name, decimal Price); // Only what Create needs

// Features/Products/List/ListProducts.cs  
public record ProductDto(int Id, string Name, decimal Price); // Different!

// Features/Products/GetDetails/GetProductDetails.cs
public record DetailedProductDto(
    int Id, 
    string Name, 
    decimal Price, 
    string Description,
    List<ReviewDto> Reviews
); // Completely different!

The Health Check:

Your Common folder is healthy if:

✅ < 10 files total

✅ No business logic

✅ No feature-specific code

✅ Could be published as a NuGet package

Your Common folder has problems if:

❌ > 20 files

❌ Has "Helpers" folder

❌ Has DTOs

❌ Features depend on it heavily

When in Doubt:

Ask: "Is this infrastructure or business logic?"

Infrastructure → Common (maybe)
Business logic → Feature (definitely)

Remember: Three files in Common is better than thirty.

2. Logic Leaking into Endpoints

The Error: Putting if/else business rules inside the Minimal API or Controller.

// ❌ DON'T DO THIS
app.MapPost("/api/products", async (CreateProductRequest request, AppDbContext db) =>
{
    // Business logic in endpoint!
    if (string.IsNullOrEmpty(request.Name))
        return Results.BadRequest("Name is required");

    if (request.Price <= 0)
        return Results.BadRequest("Price must be positive");

    var product = new Product { ... };
    db.Products.Add(product);
    await db.SaveChangesAsync();

    return Results.Created(...);
});

The Solution: The endpoint should be a thin wrapper. Its only job is to receive the request and call mediator.Send().

// ✅ DO THIS
app.MapPost("/api/products", async (CreateProduct.Command request, IMediator mediator) =>
{
    var result = await mediator.Send(request);
    return result.IsSuccess ? Results.Created(...) : Results.BadRequest(result.Error);
});

All business logic and validation stays in the handler and validator.

3. Creating "God" Slices

The Error: Creating a single slice called ProductManagement that handles Create, Update, Delete, List, Search, Export, Import.

Features/
└── Products/
    └── ProductManagement/     # ❌ God slice
        └── ProductManager.cs   # 2000 lines of code

The Solution: Split them! Each use case is its own slice.

Features/
└── Products/
    ├── Create/               # ✅ One responsibility
    ├── Update/               # ✅ One responsibility
    ├── Delete/               # ✅ One responsibility
    ├── List/                 # ✅ One responsibility
    └── Search/               # ✅ One responsibility

Why: Keeping them separate makes code easier to:

Find (knows exactly where "Create Product" lives)
Test (smaller, focused tests)
Modify (changes don't affect other operations)
Delete (remove entire folder if feature is deprecated)

4. Premature Extraction to Common

The Error: Seeing similar code twice and immediately extracting to Common.

// Two features have similar validation
// Features/Products/Create - validates price
// Features/Orders/Create - validates total

// DON'T immediately create:
// Common/Validators/MoneyValidator.cs

The Solution: Wait for the third usage (Rule of Three). The code might diverge:

Products might need different price rules per category
Orders might need different rules for wholesale vs retail

Copy-paste twice. Extract on the third usage.

✅ When to Use Vertical Slice Architecture

Perfect for:

✅ CRUD-heavy applications - E-commerce, CMS, dashboards

✅ Microservices - Each service naturally organized by features

✅ APIs with many endpoints - Easy to find and modify specific operations

✅ Teams that value velocity - Less ceremony = faster development

✅ Evolutionary systems - When you don't know how the system will grow

Consider alternatives when:

❌ Complex shared domain logic - Heavy domain modeling with aggregates

❌ Need to swap infrastructure frequently - Multiple database providers

❌ Building frameworks or libraries - Reusability > feature velocity

🎯 Key Takeaways

Organize by feature, not by layer - Everything for "Create Product" in one place
High cohesion, low coupling - Features are self-contained and independent
Minimal abstractions - Only create them when you have actual shared behavior
Incremental adoption - Start today with new features, migrate gradually
Share infrastructure, duplicate business logic - Keep the Common folder small
MediatR behaviors handle cross-cutting concerns - Validation and logging are automatic
Integration tests give highest confidence - Test complete slices end-to-end

💬 What's Next?

Now that you understand Vertical Slice Architecture, here are some questions you might have:

"How do I handle Domain Events to communicate between slices without coupling them?"

Domain events with MediatR notifications let features react to each other while staying independent. A OrderCreated event can trigger inventory updates, email notifications, and analytics tracking - all in separate handlers.

"What about complex business rules shared across features?"

If you truly have shared domain logic (not just similar code), you can create a small Domain layer with that core logic. Features call into it, but remain independent slices.

"Can I mix this with DDD?"

Absolutely! Use Vertical Slices for most features, and a Domain layer for your core business aggregates. They complement each other well.

☕ Just launched The Coffee Timer - my personal productivity project 🚀

Adrián Bailador — Fri, 06 Feb 2026 21:50:38 +0000

My time management app is finally in production. It combines the Pomodoro technique with a coffee-inspired aesthetic and smart automation.

🎯 What is The Coffee Timer?
A web application that helps you stay focused with 25-minute work sessions, intelligent task management, and productivity insights.

✨ Key features:

Pomodoro timer with animated coffee cup visualization
Auto-start sessions - maintains your flow between work and breaks
Session feedback tracking - understand when you're most productive
Live timer in browser tab - no need to switch windows
Task management with priorities, tags, and categories
AI-powered daily summary and smart suggestions (Google Gemini)
Ambient sounds for better focus
Focus Mode for distraction-free work
Dark/light mode
PWA - works offline, installable as a native app
Google authentication
Premium subscription with advanced analytics via Stripe

🛠️ Tech stack:
Frontend: React + TypeScript + Tailwind CSS
Backend: .NET 8
Database: Supabase (PostgreSQL)
AI: Google Gemini API
Payments: Stripe

This project taught me about Stripe payment integration, JWT authentication, generative AI APIs, real-time browser tab updates, and building smooth UX flows that reduce friction instead of adding it.

The biggest lesson? Shipping version 1.0 with core features beats waiting for perfection.

🔗 Try it free: https://thecoffeetimer.com

Do you use the Pomodoro technique? What features would make a productivity tool actually useful for you? I'd love to hear your thoughts!