DEV Community: dotnet

Any Language, One Store: How Zaris Speaks the Redis Protocol

Zero Heartbeat — Thu, 27 Aug 2026 09:23:14 +0000

Zaris is a distributed key/value store built for .NET, with its own binary protocol and native .NET clients. With 2.0.0, every Zaris node can also expose a Redis-protocol (RESP2) listener — so existing Redis clients, in any language, can connect to it without code changes.

Why put a Redis face on a .NET store

Redis has the widest client-library support of any key-value protocol. Adding RESP compatibility means polyglot teams get one replicated, highly-available store that every service can talk to today, regardless of language. The RESP front-end is opt-in and disabled by default per node.

The core hash is Redis-slot-aligned

Zaris uses the same key hashing Redis Cluster uses: CRC16(key) % 16384. That means cluster-aware Redis clients can route straight to the owning node, with no proxy in between:

redis client ──CRC16(key) % 16384 → slot → owner ──▶ node that holds the key ──▶ reply

Collections use a whole-value model

Native data structures (hashes, lists, sets, sorted sets) go through read-modify-write with compare-and-swap semantics, so concurrent writes don't conflict across replicas.

Transactions run on real 2PC, not a simulation

MULTI/EXEC executes on Zaris's native two-phase-commit transaction machinery rather than faking it — counter commands like INCR/DECR stay properly isolated inside a transaction block.

Three ways to fail over

Load balancer (recommended) — any node accepts any key; dead nodes just drop out of rotation.
Sentinel — Zaris answers Sentinel discovery commands so clients can re-resolve.
Cluster — CRC16-aligned slot topology, same as Redis Cluster.

What's in, and what's cleanly out

Testing against StackExchange.Redis: ~126 commands supported, ~92 cleanly not supported, zero failures. Supported: core strings, collections, Streams with consumer groups, MULTI/EXEC/WATCH, pub/sub. Not supported, by design: Lua scripting, geo commands, HyperLogLog, persistence commands — these assume infrastructure Zaris doesn't have.

Pin your client versions

The listener speaks RESP2 only. Pin your Redis client library version rather than floating it, so you don't get an unexpected negotiation attempt at a newer protocol version.

Connecting

redis-cli -h node-a.internal -p 6379 SET user:42 "ada"
redis-cli -h node-a.internal -p 6379 GET user:42

import redis
r = redis.Redis(host="node-a.internal", port=6379)
r.set("user:42", "ada")
print(r.get("user:42"))

// StackExchange.Redis, unchanged
var mux = ConnectionMultiplexer.Connect("node-a.internal:6379");
var db = mux.GetDatabase();
db.StringSet("user:42", "ada");

Full RESP config, the command compatibility matrix, and migration notes are in the docs.

Should Your Prompt Store Pick Your Model

Johnny Z — Thu, 27 Aug 2026 06:35:14 +0000

Langfuse with Microsoft.Extensions.AI has an appealing story: update prompts without redeploying. A prompt fetches its config blob—model, tokens, temperature—which the code passes straight to the LLM.

It works. But it puts a boundary in what I'd suggest might be better placed elsewhere — and moving it is a small enough change to be worth exploring.

This post is about where to move that line in a .NET codebase using Microsoft.Extensions.AI against OpenAI or Azure OpenAI, with Langfuse as the source of prompts.

What the current setup buys you

Let me be fair to it first, because the coupling is a deliberate design, not an accident.

Langfuse's prompt config is an optional JSON object versioned alongside the prompt. That means someone can open the Langfuse UI, change the model or a parameter, and ship it — no code change, no redeploy. Combined with labels (pointers to specific versions that your code references), a rollback is just moving the production label back to an earlier version. For prompt content iteration, that story is genuinely good, and there is a real audience of people who want model config coupled to prompt versions more tightly so each version is fully self-describing and reproducible.

So this is a trade-off, not a bug. The question is whether the thing you are optimizing for — non-engineers tuning prompts without a deploy — is worth what the coupling costs.

Why I think this deserves consideration

Three points stand out.

It is an untyped blob feeding provider selection. The Langfuse config is arbitrary JSON without schema enforcement. On the other end, whatever LLM plumbing you use will treat that model string as authoritative. A missing key, a stray max_tokens, or a gpt4o typo might not fail at build time or deploy time — it could fail on a live request, or silently do something unintended. You have a loosely-typed value driving an infrastructure decision, and the mistake may not surface until traffic hits it.

It conflates two change lifecycles with different risk profiles. Prompt wording is a content decision: low risk, iterate freely. Which model runs and what the token ceiling is are infrastructure, cost, and reliability decisions with different review considerations. When both live in the same editable object, whoever edits prompts effectively has influence over production model selection and spend. That's considerable authority to place in a text field.

Environment parameterization gets awkward. The config travels with the prompt version. So "cheap model in dev, strong model in prod" tends to push you toward label gymnastics or separate projects, rather than a straightforward per-environment mapping that lives with your other infra config.

The .NET insight that makes the fix clean

Here is the detail that makes this pleasant in Microsoft.Extensions.AI: for OpenAI and Azure OpenAI, the model identity is bound when you construct the client, not when you call it.

IChatClient client = new AzureOpenAIClient(
        new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient("my-deployment")   // <-- model bound HERE
    .AsIChatClient();

The provider comes from which client type you build and its endpoint. The deployment comes from GetChatClient. By the time you have an IChatClient, it already knows what model it is. You barely need to touch ChatOptions.ModelId at all.

That means model selection reduces to: pick the right pre-built client. And "pick a thing by name" is exactly what keyed dependency injection is for. So the plan is:

Langfuse owns the prompt template, its variables, and a logical alias like extractor-strong.
Your app owns a typed, environment-aware registry mapping each alias to a concrete client plus guardrails, resolved through keyed DI and validated at startup.

The prompt says what it wants done. Your infra config says which deployment and token budget executes it.

1. The registry: engineering-owned, typed, env-aware

Model wiring goes in appsettings.{Environment}.json, so the same aliases map to different deployments per environment:

// appsettings.Production.json
{
  "ModelRegistry": {
    "Models": {
      "extractor-strong": {
        "Provider": "AzureOpenAI",
        "Endpoint": "https://my-res.openai.azure.com/",
        "Deployment": "gpt-4o-prod",
        "MaxOutputTokensCeiling": 4096,
        "DefaultTemperature": 0
      },
      "summarizer-cheap": {
        "Provider": "AzureOpenAI",
        "Endpoint": "https://my-res.openai.azure.com/",
        "Deployment": "gpt-4o-mini",
        "MaxOutputTokensCeiling": 1024
      }
    }
  }
}

public sealed class ModelRegistryOptions
{
    public const string Section = "ModelRegistry";
    public Dictionary<string, ModelDefinition> Models { get; init; } = new();
}

public sealed class ModelDefinition
{
    [Required] public string Provider { get; init; } = default!;   // "AzureOpenAI" | "OpenAI"
    public string? Endpoint { get; init; }                          // Azure only
    [Required] public string Deployment { get; init; } = default!;  // Azure deployment or OpenAI model id
    [Range(1, 200_000)] public int MaxOutputTokensCeiling { get; init; } = 4096;
    public float? DefaultTemperature { get; init; }
}

2. Register one keyed client per alias, and fail fast

Each alias becomes a keyed IChatClient with its own middleware pipeline. Validation runs at startup, so a broken registry fails the deploy rather than the first request.

var registry = builder.Configuration
    .GetSection(ModelRegistryOptions.Section)
    .Get<ModelRegistryOptions>() ?? new();

builder.Services
    .AddOptions<ModelRegistryOptions>()
    .Bind(builder.Configuration.GetSection(ModelRegistryOptions.Section))
    .Validate(o => o.Models.Count > 0, "No models configured")
    .Validate(o => o.Models.Values.All(m =>
        m.Provider is not "AzureOpenAI" || !string.IsNullOrWhiteSpace(m.Endpoint)),
        "AzureOpenAI models require an Endpoint")
    .ValidateOnStart();

foreach (var (alias, def) in registry.Models)
{
    builder.Services
        .AddKeyedChatClient(alias, _ => BuildInner(def))
        .UseOpenTelemetry()     // per-model pipeline: telemetry, caching, retries…
        .UseLogging();
}

static IChatClient BuildInner(ModelDefinition d) => d.Provider switch
{
    "AzureOpenAI" => new AzureOpenAIClient(
            new Uri(d.Endpoint!), new DefaultAzureCredential())   // or ApiKeyCredential
        .GetChatClient(d.Deployment)   // model identity bound here
        .AsIChatClient(),
    "OpenAI" => new OpenAI.Chat.ChatClient(
            d.Deployment, Environment.GetEnvironmentVariable("OPENAI_API_KEY")!)
        .AsIChatClient(),
    _ => throw new InvalidOperationException($"Unknown provider {d.Provider}")
};

Because AddKeyedChatClient returns a ChatClientBuilder, you can attach caching, retries, rate limiting, and OpenTelemetry per model — centrally, once, instead of scattering it across call sites.

3. The validation boundary: the actual fix

This is the part that addresses the core complaint. Whatever comes back from Langfuse gets parsed once into a typed spec. Unknown aliases are rejected. Requested generation parameters are clamped to the registry's ceiling. Nothing free-form reaches the provider.

Note what the prompt spec deliberately does not contain: no provider, no endpoint, no deployment. A prompt may request a temperature or a token budget; it may not choose infrastructure.

// Fetching from Langfuse is a plain HTTP GET — no SDK, no magic.
// Whatever you use, hand this boundary the raw template + config dictionary.
public sealed record PromptSpec(string ModelAlias, int? MaxOutputTokens, float? Temperature);

public sealed class ResolvedPrompt
{
    public required IChatClient Client { get; init; }
    public required ChatOptions Options { get; init; }
    public required string Template { get; init; }
}

public sealed class PromptResolver(
    IServiceProvider sp,
    IOptions<ModelRegistryOptions> registry)
{
    public ResolvedPrompt Resolve(string template, IReadOnlyDictionary<string, object?> config)
    {
        // 1. Parse the loose blob into something typed — fail loudly, not at call time.
        if (!config.TryGetValue("modelAlias", out var aliasObj) || aliasObj is not string alias)
            throw new PromptConfigException("prompt config missing 'modelAlias'");

        if (!registry.Value.Models.TryGetValue(alias, out var def))
            throw new PromptConfigException($"unknown model alias '{alias}'"); // typo caught here

        // 2. Clamp requested params to the registry guardrails.
        int? requested = config.TryGetValue("maxOutputTokens", out var t) ? Convert.ToInt32(t) : null;
        int maxTokens = Math.Min(requested ?? def.MaxOutputTokensCeiling, def.MaxOutputTokensCeiling);

        float? temp = config.TryGetValue("temperature", out var tp)
            ? Convert.ToSingle(tp) : def.DefaultTemperature;

        return new ResolvedPrompt
        {
            Client   = sp.GetRequiredKeyedService<IChatClient>(alias),  // model already bound
            Options  = new ChatOptions { MaxOutputTokens = maxTokens, Temperature = temp },
            Template = template,
        };
    }
}

4. The call site

var prompt   = await _prompts.GetAsync("invoice-extractor", label: "production");
var resolved = _resolver.Resolve(prompt.Template, prompt.Config);

var messages = new[] { new ChatMessage(ChatRole.System, Render(resolved.Template, vars)) };
var response = await resolved.Client.GetResponseAsync(messages, resolved.Options);

That is the whole flow. Alias in, correct pre-built client out, guardrailed options attached.

Who owns what now

Langfuse keeps the prompt template, its variables, and a logical modelAlias. If you want, it can also carry temperature and maxOutputTokens — but as requests that the boundary clamps, not as commands. Non-engineers can still iterate freely and use the Playground. What they can no longer do is pin a raw provider deployment or exceed a token ceiling, because provider, endpoint, deployment, and hard limits live in your environment-specific ModelRegistry: under code review, resolved through keyed DI, validated at startup.

The trade-off is a genuine one. You give up some of Langfuse's "one object fully describes the run" reproducibility. In exchange, you get fail-at-startup instead of fail-on-request, environment-parameterized model selection you didn't have before, and a clearer separation between a content decision and an infrastructure one.

If you only do one thing

Add the validation boundary in step 3, even if you defer the keyed-registry refactor. Parsing the untyped blob into a typed spec and rejecting unknown aliases is the highest-leverage, lowest-effort change here — it turns a class of production-time failures into a single, obvious throw. The keyed registry is where you want to end up; the boundary is what you can ship this afternoon.

A nice follow-up, once the registry exists: a startup check that every modelAlias referenced by your live production prompts actually resolves in the registry, so a missing mapping fails the deploy rather than the first customer request. But start with the boundary. Your prompt store is a good place to manage prompts. It might be worth reconsidering whether it should also dictate which GPU your requests use.

Please feel free to reach out on twitter @roamingcode

Counts Match. The Data Can Still Be Wrong

Ivan Rossouw — Thu, 27 Aug 2026 06:26:55 +0000

Many systems eventually need to repartition one persisted record. A batch becomes several processing groups. A container becomes several parcels. A work queue becomes several assignments.

The domain changes, but the risk is consistent: every child must move from one source into exactly one result without being invented, duplicated, or lost.

The tempting safeguard is a count comparison:

The source contains twelve items.
The proposed results contain twelve items altogether.
Therefore, the split must be valid.

Unfortunately, equal counts prove only cardinality. They do not prove identity.

The blind spot in a passing count

Imagine that a source contains the item IDs A, B, and C.

A proposed split contains:

Result one: A, A
Result two: C

The source and outputs both contain three entries. A count check passes, even though A was duplicated and B disappeared.

Another invalid proposal might contain A, B, and D. Again, the count matches, but an unknown item has replaced a valid one.

These are not arithmetic failures. They are failures of identity conservation.

State the stronger invariant

For a valid repartition, the original identity set must equal the disjoint union of the output identity sets.

That gives us three useful requirements:

Every original ID appears in the outputs.
No unknown ID appears in the outputs.
No ID appears more than once.

Set equality proves membership. A duplicate check proves disjointness. Cardinality remains useful, but only as one part of the invariant.

Validate before mutation

A generalized C# guard can make that rule explicit:

static void EnsureExactPartition(
    IReadOnlyCollection<Guid> originalIds,
    IEnumerable<IReadOnlyCollection<Guid>> partitions)
{
    var original = originalIds.ToHashSet();
    var output = partitions.SelectMany(ids => ids).ToArray();

    var sourceHasDuplicates = original.Count != originalIds.Count;
    var outputHasDuplicates = output.Distinct().Count() != output.Length;

    if (sourceHasDuplicates ||
        outputHasDuplicates ||
        output.Length != original.Count ||
        !original.SetEquals(output))
    {
        throw new InvalidOperationException(
            "The requested split is not an exact partition.");
    }
}

This example is deliberately small. In a real application, authorization, lifecycle state, concurrency, and ownership rules may add further checks. The important ordering is that the complete proposal is validated before tracked entities or database state are changed.

That ordering makes failure cheap. An invalid request becomes a rejected request, not a cleanup exercise.

Move tracked children instead of copying them

When the children already exist as tracked entities, repartitioning should preserve their identities.

Creating new child objects by copying fields can accidentally turn a move into duplication. It may also lose historical references, introduce new primary keys, or leave the originals attached to the source.

Instead, load the authorized source and its children, resolve each requested ID to the existing tracked instance, and re-parent that instance to its destination. With EF Core, this usually means updating the relationship through the navigation property or foreign key and allowing relationship fix-up to track the move.

The output records are new. The children are not.

Make the whole transition atomic

A valid split still should not become partially visible.

Creating two results, failing on the third, and leaving the source marked as processed produces a state that is difficult to reason about and harder to retry safely.

Treat these changes as one unit:

Create every result.
Move every child.
Transition the source record.
Save the complete state atomically.

A single SaveChanges call is transactional for supported relational providers. If the workflow requires multiple saves or coordinates additional durable work, use an explicit transaction or an outbox-style boundary.

The desired outcome is simple: observers see either the original state or the complete repartitioned state, never a mixture.

Give every result an idempotency scope

Operation-level idempotency is helpful, but a split produces several distinct results. Each result therefore needs a stable scope of its own.

A compound uniqueness boundary such as (operationId, stableResultKey) lets a retry identify each intended result independently. The result key should come from stable input or deterministic content, not an array position whose meaning may change when ordering changes.

A database uniqueness constraint should enforce this promise. Application checks improve error messages; the constraint protects correctness under concurrency.

The trade-off is intentional friction

Exact set validation allocates collections. Transactions hold resources. Unique indexes add storage and write cost. The implementation is more involved than comparing two integers.

For very large partitions, validation may need to move closer to the database or use streaming and batching. That changes the mechanism, not the invariant.

The additional friction buys something valuable: failures occur before mutation, concurrent retries converge, and the persisted model remains explainable.

Tests that expose the boundary

A compact test suite should include:

A valid partition in a different order
One duplicated ID
One omitted ID
One foreign ID
A retry using the same per-result scopes

The negative cases should fail before any entity is re-parented or source state is changed.

The practical lesson is modest: whenever one persisted record becomes many, ask more than, “Did the counts match?”

Ask, “Did every identity move exactly once?”

Still Using Task.Run() in ASP.NET Core? Fix Your C# Async Await the Right Way

qodors — Thu, 27 Aug 2026 04:50:14 +0000

Your ASP.NET Core API is slow, so you add Task.Run() and expect things to get better.

It may look like a quick fix, but Task.Run() does not make every operation faster. In many cases, it only moves the same work to a thread-pool thread. For database queries, HTTP requests, and other I/O work, this does not solve the actual problem.

This is why it is important to understand how async and await work in your code. The goal is not to make every method async. It is to avoid blocking a thread while the application waits for an operation to finish.

What Do async and await Actually Do?
Many developers think async creates a new thread, but it does not create a new thread by itself.

When an ASP.NET Core endpoint waits for a database query, it does not need to keep a thread busy while waiting for the response.

public async Task<IActionResult> GetProducts()
{
    var products = await _db.Products.ToListAsync();
    return Ok(products);
}

The database may take some time to return the products, but the application does not need to keep a thread busy during that time. Once the database operation finishes, the method continues from await.

This allows an ASP.NET Core application to handle requests without keeping a thread busy during the wait.

The important thing is to understand what the code is waiting for, not just whether it uses await.

Why Task.Run() Is Often the Wrong Fix
Consider this code:

public async Task<IActionResult> GetProducts()
{
    var products = await Task.Run(() =>
        _db.Products.ToList());

    return Ok(products);
}

Although the code uses await, the database call itself is still synchronous. Task.Run() only moves ToList() to a thread-pool thread. That thread stays busy while the synchronous database call runs.

For normal I/O work in ASP.NET Core, there is usually no reason to do this. Instead, use the async method provided by the library:

public async Task<IActionResult> GetProducts()
{
    var products = await _db.Products.ToListAsync();
    return Ok(products);
}

The better approach is to call the database's async method directly. This avoids wrapping the synchronous call in Task.Run(). Look at the operation behind await instead of adding Task.Run() just because a method looks slow.

Use Async for I/O Work
A web API often spends a lot of time waiting for other systems. It may query a database, call another API, read a file, or work with cloud storage. In these situations, an async API lets the application wait without keeping a thread busy.

Common I/O operations include:

Database queries
HTTP requests
File operations
Network calls
Cloud storage

An HTTP request can be handled directly with the async API:

var response = await httpClient.GetAsync(url);

There is no need to put the HTTP call inside Task.Run().

The same applies to Entity Framework Core:

var user = await _db.Users
    .FirstOrDefaultAsync(x => x.Id == id);

The application can wait for the database response without blocking a thread.

What About CPU-Heavy Work?
CPU-heavy work is different because the application is not waiting for another system. The CPU is actively doing the work.

For instance:

public byte[] GenerateReport()
{
    // Expensive CPU calculation
}

In some situations, you may choose to move this work to another thread:

public async Task<byte[]> GenerateReportAsync()
{
    return await Task.Run(() => GenerateReport());
}

However, Task.Run() does not make the calculation itself faster. The CPU still has to perform the same amount of work.

For CPU-heavy work, Task.Run() can be useful when you intentionally want to move that work to another thread. It should not be used as a general solution for database queries or HTTP requests.

Avoid .Result and .Wait() in Async Code
Another common issue appears when an async method is called but the result is then requested synchronously:


var result = GetDataAsync().Result;

The same problem can happen with:

GetDataAsync().Wait();

The method may be asynchronous, but .Result and .Wait() block while waiting for it to finish. Instead, let the async operation continue with await:

var result = await GetDataAsync();

This keeps the code easier to follow and avoids unnecessary blocking.

A simple rule is: if you have an async operation, use await instead of waiting for it synchronously with .Result or .Wait().

Do You Really Need async Here?
Another important point is that not every method needs to be asynchronous.

Consider this:

public async Task<int> Add(int a, int b)
{
    return await Task.FromResult(a + b);
}

There is no real async work happening here. The method is only adding two numbers, so making it async adds unnecessary code.

A simple method is better:


public int Add(int a, int b)
{
    return a + b;
}

Use async when the method has something meaningful to wait for, such as a database query, HTTP request, or file operation. For simple calculations that finish immediately, a normal synchronous method is usually clearer.

Keep the Async Flow Going
An ASP.NET Core application often has several layers:

Controller
↓
Service
↓
Repository
↓
Database

If the database operation is async, keep that async flow through the application layers rather than turning it into a synchronous call somewhere in the middle.

public async Task<User?> GetUserAsync(int id)
{
    return await _db.Users
        .FirstOrDefaultAsync(x => x.Id == id);
}

The service can await the result:

var user = await _userService.GetUserAsync(id);

The controller can then return the result:

return Ok(user);

Try not to call an async method and then use .Result or .Wait() in another layer. Keeping the async flow consistent makes the code easier to maintain and avoids unnecessary blocking in an ASP.NET Core application.

Find Out Why the API Is Slow
If your ASP.NET Core API is slow, adding Task.Run() should not be the first thing you try. First, find out where the time is actually going.

Check things such as:

Database query time
External API response time
CPU usage
Thread-pool usage
Memory usage
Garbage collection
Number of requests
Slow synchronous code

The SQL query may be slow, an external API may take two seconds to respond, or another part of the application may be using too much CPU.

Find the actual problem before changing the async code. Async code can handle waiting better, but it cannot make a slow database query run faster.

Our Take
At Qodors, we often see Task.Run() added when a method is slow or when a developer wants to make synchronous code async. A common case is a database call being wrapped in Task.Run() even though the database library already provides an async method.

Moving the synchronous call to another thread does not fix the database operation. It only changes where that work runs.

For normal ASP.NET Core API work, use the async methods provided by the library. With Entity Framework Core, that means methods such as ToListAsync() and FirstOrDefaultAsync(). For HTTP calls, use the async methods available in HttpClient.

Before adding Task.Run(), first ask:

Am I doing CPU-heavy work, or am I waiting for I/O?

If the application is waiting for I/O, use the proper async API. If the work is CPU-heavy, Task.Run() may be useful when there is a clear reason to move that work.

Quick Reference

async does not create a new thread by itself.
Use await for async operations.
Do not wrap normal database calls in Task.Run().
Use EF Core methods such as ToListAsync() and FirstOrDefaultAsync().
Avoid .Result and .Wait() in async code.
Do not make every small method async.
Task.Run() does not make CPU work faster.
Keep async calls going through your application layers.
Find the real performance problem before changing your code.
Use Task.Run() only when there is a clear reason for it.

Don't add Task.Run() just because an ASP.NET Core API feels slow. First find out what the application is waiting for, use async APIs for database and HTTP work, and avoid blocking calls such as .Result and .Wait(). When the work is CPU-heavy, use Task.Run() only when it actually fits the situation.

CSharp #DotNet #ASPNetCore #AsyncAwait #CSharpProgramming #DotNetCore #WebAPI #API #Backend #QodorsEdge

How to Create and Update a Chart with C# and .NET

Marko Marks — Thu, 27 Aug 2026 03:55:15 +0000

This tutorial uses PlotMarks, an API-based charting service I'm building, for creating, hosting, and updating the chart.

Push metrics from a C# .NET service to a persistent embeddable chart using HttpClient. No SDK or NuGet packages, just what ships with .NET 8.

Many backend systems are built with .NET. If you have a service that tracks metrics: request counts, error rates, queue depths, or any time-series number, and you want to publish that data as a chart without building a frontend, you can do it with a few lines of HttpClient code.

This article shows how to create a persistent chart slot on PlotMarks and push data to it from a .NET application. The integration requires no SDK or NuGet package beyond what ships with the framework.

The scenario

An ASP.NET Core service counts incoming API requests per hour and publishes the current day's totals as an embedded bar chart. The chart is used on an internal status page. The service pushes a fresh dataset each hour; the page shows the latest numbers when someone opens it.

Architecture

Chart creation is a one-time setup step, usually done manually from a console app or a startup routine. Data pushes happen on the production schedule, hourly in this case.

Prerequisites

.NET 8 or later
A PlotMarks account and API key sign up free at plotmarks.com
PLOTMARKS_API_KEY set as an environment variable or app secret

No additional NuGet packages are required.

Step 1. Create a chart slot

Run this once to provision the chart. You can place it in a Program.cs setup block, a one-time migration tool, or a simple console app. Save the chart ID that is returned.

using System.Net.Http;
using System.Net.Http.Json;

// Typed models ───────────────────────────────────────────────────────────

record ChartConfig(string title, string xLabel, string yLabel);
record CreateChartRequest(string type, string output_type, ChartConfig config);
record CreateChartResponse(string id, string embedUrl);

// Setup ──────────────────────────────────────────────────────────────────

const string BaseUrl = "https://www.plotmarks.com";
string apiKey = Environment.GetEnvironmentVariable("PLOTMARKS_API_KEY")
    ?? throw new InvalidOperationException("PLOTMARKS_API_KEY is not set");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", apiKey);

// Create chart slot ──────────────────────────────────────────────────────

var createBody = new CreateChartRequest(
    type: "bar",
    output_type: "static_iframe",
    config: new ChartConfig(
        title: "API Requests — Today",
        xLabel: "Hour",
        yLabel: "Requests"
    )
);

using var createResponse = await client.PostAsJsonAsync($"{BaseUrl}/api/charts", createBody);
createResponse.EnsureSuccessStatusCode();

var chart = await createResponse.Content.ReadFromJsonAsync<CreateChartResponse>()
    ?? throw new InvalidOperationException("Empty response");

Console.WriteLine($"Chart ID : {chart.id}");
Console.WriteLine($"Embed URL: {chart.embedUrl}");

output_type: "static_iframe" creates a chart that shows the latest pushed dataset when a viewer loads the page. No in-page auto-refresh. This is appropriate here because the page is loaded on demand and hourly data does not need to update while someone has the page open.

Step 2. Push data

Typically called from the part of your service that runs on the hourly schedule:

// Push hourly request counts ─────────────────────────────────────────────

// In production this comes from your metrics store.
// Keys are hour labels; values are request counts.
var hourlyCounts = new Dictionary<string, int>
{
    ["00:00"] = 412,
    ["01:00"] = 298,
    ["02:00"] = 187,
    ["03:00"] = 143,
    ["04:00"] = 201,
    ["05:00"] = 334,
    ["06:00"] = 589,
    ["07:00"] = 847,
    ["08:00"] = 1204,
    ["09:00"] = 1531,
    ["10:00"] = 1688,
    ["11:00"] = 1743
};

var dataPoints = hourlyCounts
    .Select(kvp => new Dictionary<string, object>
    {
        ["x"] = kvp.Key,
        ["Requests"] = kvp.Value
    })
    .ToList();

var pushBody = new
{
    plots = new[]
    {
        new
        {
            color = "#4F46E5",
            borderRadius = 4,
            data = dataPoints
        }
    }
};

string chartId = "ch_abc123"; // from the create step above
using var pushResponse = await client.PostAsJsonAsync(
    $"{BaseUrl}/api/charts/{chartId}/data",
    pushBody
);
pushResponse.EnsureSuccessStatusCode();
Console.WriteLine("Data pushed successfully");

Each call to POST /api/charts/{id}/data replaces the chart's entire dataset. There is no delta or append mode. Pushing a new dataset with 12 data points replaces the previous one, the chart always shows exactly what was in the most recent push.

Step 3. Embed the chart

The embed URL returned during chart creation is public. No login or API key is needed to view it.

<iframe
  src="https://www.plotmarks.com/charts/ch_abc123"
  width="640"
  height="360"
  frameborder="0"
  style="border-radius: 8px"
></iframe>

Making it a background service

If you want the push to happen automatically on a schedule inside the service itself, wrap it in a BackgroundService:

public class HourlyChartUpdater : BackgroundService
{
    private readonly HttpClient _http;
    private readonly string _chartId;

    public HourlyChartUpdater(IHttpClientFactory factory, IConfiguration config)
    {
        _http = factory.CreateClient("plotmarks");
        _chartId = config["PlotMarks:ChartId"]
            ?? throw new InvalidOperationException("PlotMarks:ChartId is not configured");
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            await PushCurrentHourlyData(stoppingToken);

            // Wait until the next hour boundary
            var now = DateTime.UtcNow;
            var nextHour = now.AddHours(1).Date.AddHours(now.AddHours(1).Hour);
            await Task.Delay(nextHour - now, stoppingToken);
        }
    }

    private async Task PushCurrentHourlyData(CancellationToken ct)
    {
        // Retrieve from your metrics store
        var counts = await GetHourlyCountsFromMetricsStore(ct);

        var pushBody = new
        {
            plots = new[]
            {
                new
                {
                    color = "#4F46E5",
                    borderRadius = 4,
                    data = counts.Select(c => new Dictionary<string, object>
                    {
                        ["x"] = c.Hour,
                        ["Requests"] = c.Count
                    }).ToList()
                }
            }
        };

        using var res = await _http.PostAsJsonAsync(
            $"/api/charts/{_chartId}/data",
            pushBody,
            ct
        );
        res.EnsureSuccessStatusCode();
    }

    private Task<IEnumerable<(string Hour, int Count)>> GetHourlyCountsFromMetricsStore(
        CancellationToken ct)
    {
        // Replace with your actual data source
        throw new NotImplementedException();
    }
}

builder.Services.AddHttpClient("plotmarks", client =>
{
    client.BaseAddress = new Uri("https://www.plotmarks.com");
    client.DefaultRequestHeaders.Add("X-API-Key", builder.Configuration["PlotMarks:ApiKey"]);
});
builder.Services.AddHostedService<HourlyChartUpdater>();

Switching to a live chart

If the background service is pushing data automatically, you may also want the chart to refresh in the browser without requiring a page reload. Switch output_type to "live_iframe" when creating the chart, for example if it is displayed on a TV screen or a monitoring wall:

var createBody = new CreateChartRequest(
    type: "bar",
    output_type: "live_iframe",
    config: new ChartConfig(
        title: "API Requests Today",
        xLabel: "Hour",
        yLabel: "Requests"
    )
);

The data push code and the embed HTML stay exactly the same. The browser-side polling is handled by the embedded chart page automatically.

What PlotMarks handles here

Storing the current dataset
Serving the chart as an embeddable page
Rendering the chart in the browser
Polling logic for live charts

The .NET code is two POST requests. PlotMarks removes the need for a hosted frontend that accepts data from the service and renders a chart from it.

Grand Theft Auto VI (GTA 6): The Next Revolution in Open-World Gaming

Ahmad Linkbuilder — Wed, 26 Aug 2026 22:26:39 +0000

Grand Theft Auto VI (GTA 6) has become the most anticipated and hyped title in the history of the video game industry. Rockstar Games has consistently redefined standards for open-world gaming with every major release. Following the monumental success of GTA 5 and over a decade of waiting, GTA 6 is positioned to usher in a new era for interactive entertainment.

This article provides an in-depth breakdown of GTA 6, detailing its release timeline, storyline, playable characters, world design, gameplay mechanics, and technical innovations.

1. Release Date and Launch Platforms

Rockstar Games has scheduled the official release of GTA 6 for November 19, 2026. The initial launch will focus on current-generation hardware.

Console Launch: The game will launch exclusively on next-generation consoles, specifically the PlayStation 5 and Xbox Series X|S.

PC Version: Following Rockstar's historical release patterns, a PC port is expected to follow after the initial console launch window.

Digital Pre-Orders: Digital pre-orders and pre-loading options will open ahead of the launch date to enable day-one playability without delays.

2. World Setting: The State of Leonida and Vice City

GTA 6 takes place within the State of Leonida, a fictional depiction modeled heavily after modern-day Florida. The centerpiece of this expansive region is the iconic, neon-lit metropolis of Vice City.

Map Scale and Biome Diversity

The world map for GTA 6 is significantly larger and more detailed than GTA 5's Los Santos, featuring several distinct biomes:

Vice City: A sprawling urban center filled with art deco architecture, Ocean Beach, shopping districts, and vibrant nightlife.

Leonida Keys: An archipelago inspired by the Florida Keys, featuring maritime boat yards, beaches, and coastal environments.

Grassrivers: Dangerous, expansive wetlands inspired by the Everglades, populated by swamps, dense vegetation, and native wildlife.

Port Gellhorn & Ambrosia: Industrial hubs, small suburban towns, manufacturing plants, and territories controlled by local biker gangs.

Mount Kalaga National Park: A northern wilderness area dominated by dense forests, elevated terrain, and rural activity centers.

3. Protagonists and Narrative: Lucia and Jason

The narrative of GTA 6 centers around themes of modern crime, trust, and survival. For the first time in the franchise's modern 3D era, the game introduces a playable female protagonist.

The Protagonist Duo (Bonnie & Clyde Dynamic)

The storyline focuses on two main characters tied together by circumstance and criminal ambition:

Lucia Caminos: The franchise's first female co-protagonist. Tough, strategic, and resourceful, Lucia enters the criminal underworld to survive following her release from the Leonida Penitentiary.

Jason Duval: A pragmatic operator with a military background who handles low-level operations around the Keys region.

Character Dynamics: Lucia and Jason operate as both romantic partners and partners-in-crime. Following a failed heist, the duo finds themselves caught in a broader conflict across Leonida's criminal networks.

Supporting Cast

The broader narrative introduces several key side characters, including Brian Heder (a local boat yard owner), Cal Hampton, Boobie Ike, and Dre'Quan Priest, all of whom influence side activities and main storyline progression.

4. Next-Gen Gameplay Mechanics and Physics

Rockstar Games has rebuilt several underlying systems for GTA 6, drawing from advancements introduced in Red Dead Redemption 2 to increase structural realism.

Character Switching System

Players can seamlessly switch between Jason and Lucia during free-roam exploration or execute coordinated tactics when both characters are deployed together during heists and missions.

Advanced NPC AI and World Dynamics

Non-Playable Characters (NPCs) feature enhanced artificial intelligence, reacting dynamically to player behavior, outfit choices, driving habits, and regional events.

The law enforcement response system has been overhauled to emphasize tactical maneuvers, roadblocks, and coordinated encirclement rather than straightforward chases.

Physicalized Inventory Management

Moving away from carrying an unlimited array of weapons, players manage inventory through vehicle trunks, duffel bags, and physical holsters, adding tactical considerations to mission preparation.

5. Graphics, Visual Systems, and Environmental Rendering

Water and Environmental Physics: Real-time fluid simulation governs ocean tides, boat wakes, waves, and weather-driven storm surges.

Lighting and Ray Tracing: Advanced ray tracing handles reflection management across Vice City's glass structures, wet pavement, and neon displays.

Character Fidelity: Real-time sweat mechanics, dynamic hair physics, precise physical damage modeling, and expanded facial animations enhance cinematic presentation.

Ecosystem and Wildlife: Wetlands and rural environments feature diverse wildlife—including alligators, deer, marine life, and bird species—operating within an active food chain.

6. Social Media Integration and Cultural Satire

Satire of contemporary culture remains a core pillar of the series. GTA 6 adapts this focus to reflect the modern digital landscape:

In-Game Social Platforms: Short-form video networks mirroring platforms like TikTok and Instagram are integrated into the world. In-game feeds broadcast NPC footage, street events, and ambient occurrences in real time.

Cultural Parodies: The game lampoons modern influencer culture, reality television trends, and tech-driven lifestyles through in-world branding and media broadcasts.

7. The Evolution of GTA Online

Building upon the multi-year ecosystem of GTA 5, the multiplayer component for GTA 6 is engineered as a long-term platform.

The new map of Leonida will serve as the foundation for expanded properties, business operations, and multi-stage online heists.

Improved server architecture and built-in support for community-driven roleplay features are designed into the online framework from launch.

Conclusion

GTA 6 represents more than a standard software release; it stands as a major landmark event for the entertainment industry. By combining high-fidelity graphics, structural physics, complex character dynamics, and open-world freedom, Rockstar Games aims to set a new benchmark for gaming design.

redb 3.7.1: props search up to 100x faster. An alternative to EF Core, or a companion to it

rinat kozin — Wed, 26 Aug 2026 17:14:21 +0000

Query cost did not depend on what you searched for: the filter sat above GROUP BY. Now the cut happens before the aggregate, on three engines, with no application code changed. Up to 100x on a date range and 5.3x on a full result set in SQL Server.

There is a class of performance problem you cannot see on small data and cannot miss on large. Ours looked like this: a query hunting for one rare order number among a hundred thousand objects took exactly as long as a search that found nothing at all. Selectivity did not move the clock. At all.

The cause was the shape of the generated SQL. Props values live one per row, so the query first folds them into a wide row through GROUP BY and only then applies the filter. The condition sat above the aggregate, filtering the result of a fold rather than a column. No index can help there: by the time the condition runs, the engine has already read and folded every value of every object in the scheme. The trigram index on strings sat unused.

3.7.1 adds a step that narrows the object set before the aggregate runs.

How it works

The planner walks the filter tree and tries to express it as a condition on a single value row. A row belongs to exactly one structure, so a disjunction falls out naturally: "this is a Position row and it contains the needle, or this is a Department row and it contains the needle". That condition is spliced straight into the value scan, and the fold now receives an already narrowed set.

The key property: the prefilter is built as a superset. It may let extra objects through, it may never lose one. The authoritative filter stays exactly where it was, above GROUP BY. Anything the planner cannot analyse yields no prefilter and today's behaviour unchanged, so the worst outcome is the absence of a speedup rather than a change of results.

What already worked before

Without this caveat the numbers below read wrong, so it goes here rather than in a footnote.

Cutting before the aggregate has always existed in redb. Just not for props, but for the object's own fields: id, parent, creation and modification dates, name. Such a condition was spliced straight into the value scan:

AND v._id_object IN (SELECT o_src._id FROM _objects o_src
                     WHERE o_src._id_scheme = $1 AND <your condition>)

In code that is WhereRedb, and it is what production queries have been leaning on all along. In our own production and in redb.Identity such filters are almost everywhere: pick within a subtree, within a date range, within a set of ids, by owner. As long as objects were cut by _objects, the fold received an already narrowed set and ran fast.

The hole was exactly where there is nothing to cut by on _objects. Then the only selective condition left was props, and props sat above the aggregate and cut nothing: one rare order number cost the same as searching for nothing. 3.7.1 closes that case, and the two cuts now compose: first by objects, then by value rows.

What was measured

Two shapes, both plain LINQ, no special calls. And both without WhereRedb, which is the worst case: nothing to narrow by on _objects, the whole weight falls on props.

The first is one search box across several fields. This is what a UI search looks like when the user has typed a word and you have to look in both the job title and the department.

var found = await redb.Query<Employee>()
    .Where(e => e.Position.Contains("Design") || e.Department.Contains("Design"))
    .OrderByRedb(o => o.Id)
    .Take(100)
    .ToListAsync();

One needle, Design, two fields, an OR between them. In the table below this is the needle row. Before 3.7.1 that query read and folded the values of every employee in the scheme and only then checked for "Design". Now the rows that obviously cannot match are cut on the way in.

The second is a date range matching 3 288 objects out of 100 000, or 3.3%.

var hired = await redb.Query<Employee>()
    .Where(e => e.HireDate >= new DateTime(2030, 1, 1)
             && e.HireDate <  new DateTime(2031, 1, 1))
    .Take(100)
    .ToListAsync();

The numbers

All three engines seeded identically: 100 000 objects, roughly 8.4M value rows, statistics refreshed. Server-side time, best of three runs.

query	PostgreSQL	SQLite	SQL Server
one needle across two string fields, ordered	188 → 91 ms	1150 → 311 ms	55 → 17 ms
the same, whole result, no paging	338 → 156 ms	1201 → 314 ms	7037 → 1327 ms
date range, 3.3% of the scheme	154 → 1.5 ms	17 → under 1 ms	2 → 2 ms

Read this table as the upper bound of the gain rather than as an expectation for any query. If you have a WhereRedb, you were already fast and the absolute difference will be smaller. The gain grows the less there was to narrow by on _objects.

One caveat about what is being measured. This is query time, without materialising objects in memory. A real call adds materialisation on top, and materialisation is identical in both modes. So the search itself got faster by exactly the ratios above, while the share of that gain in the end-to-end call depends on how many objects you pull.

Which is where a second, independent lever comes in: projections. Select fetches only the fields you actually need instead of the whole object. One mechanism cuts the engine's work, the other cuts the materialiser's, and they compose.

Three engines, three different mechanisms

The same algebra, and every engine wins for its own reason. Worth knowing before predicting numbers on your own data.

PostgreSQL engages the trigram GIN and reads far fewer rows: the string index returns 40 958 rows where the structure index returns 200 000. SQLite engages a covering partial index and stops going back to the table. SQL Server reads the same pages but saves CPU instead, because the string column is NVARCHAR(MAX) and the comparison carries an explicit collation.

The spread shows most clearly on the date range: a hundredfold gain on PostgreSQL, sixteenfold on SQLite, and nothing whatsoever on SQL Server.

That last one is not a misfire, it is a sign that there was nothing left to cut. The condition matches 3.3% of the scheme, the query asks for a hundred rows, and the work is already bounded by the limit rather than by the size of the scheme: at that density you find a hundred matches after visiting roughly three thousand objects. Two milliseconds before, two after. Remove the limit, force a walk over the whole scheme, and the gain shows up there too: 88 ms against 65. That is a useful rule of thumb for your own data. The prefilter pays off where the engine would otherwise fold the entire scheme, and gives nothing where a limit already keeps the work small.

What this means in practice

We got very close to a flat table with an index. On simple conditions, an equality or a range on one field, the query now travels an index the way it would travel an ordinary column of an ordinary table.

And it keeps what a flat schema cannot have by construction. No row multiplication from joins: values fold per object in a single pass, and related collections do not turn a result set into a cartesian product you then have to collapse. No Include either: the graph loads by depth rather than by naming every branch by hand. On deep graphs that lands somewhere a classic ORM built on joins and Include does not reach.

Hence the two-sided positioning in the title. Nobody is asking you to replace EF Core wholesale: the two live side by side in one application, on one database. The relational part, where the schema is stable and the table is flat, stays with EF, which is the right home for it. redb takes what a flat model finds hard: shifting sets of fields, heterogeneous entities inside one scheme, trees and graphs that would otherwise become a chain of Include and a pile of duplicated rows. The choice is about the shape of your data, not about ideology.

There is no head-to-head benchmark against EF in this article, and I am not going to invent one. What is described here are properties of the execution model, not a measurement we did not take.

That measurement is coming separately. A deep dive is in preparation with code for both sides, execution plans and numbers: a simple condition against a flat indexed table, a graph several levels deep against Include, collections where a join multiplies rows, and what projections do about all of it. This post is short and about one change; that one will be long and about where this model wins and where it loses.

The boundaries, honestly

The prefilter is opt-in through EnablePvtPrefilter and off by default.

Today it covers a disjunction over selective fields and a range or equality on a single field. A top-level AND across different fields does not qualify: a value row belongs to one structure, and a conjunction of different fields is not expressible at row level. Filters over arrays, dictionaries, null checks, cross-field comparisons and computed expressions are recognised as unanalysable and yield no prefilter.

There is also a case where the prefilter had to step aside. On SQLite a query with a limit and no ordering at all streams without the prefilter and stops at the hundredth group; with it the planner switches to a multi-index OR, loses the ordering, needs a temporary B-tree and materialises everything. Measured: 8-12 ms against 388-521 ms, with no overlap between the ranges. So on SQLite, in that single shape, no prefilter is emitted. PostgreSQL knows no such trouble, and SQL Server cannot even produce the offending shape, because its paging is required to carry an ORDER BY.

A word on how this was verified. The invariant that results must match row for row is held by a suite of differential tests: every query runs twice, with the flag and without, over the same data, and the id sets are compared. That suite caught a defect that would otherwise have shipped: the row form cuts rows rather than objects, so an object qualifying through one branch of a disjunction lost the column values belonging to the other branches. The object set stayed intact, which is why fifteen hundred existing tests noticed nothing, while DistinctBy and OrderBy over such a field quietly lied. Fixed before publication.

What you get

Search finally costs what you are searching for. A rare condition is now cheap instead of costing the same as a query that finds nothing.

Three engines, one flag, zero changes in application code. The same LINQ, the same model, nothing to rewrite: turn it on and go.

up to 100x faster on a date range in PostgreSQL, 154 ms became one and a half;
3.7x on string search in SQLite and twice as fast in PostgreSQL;
5.3x on a full result set in SQL Server, where seven seconds became 1.3.

And not a single row of any result changed. The prefilter is a superset by construction, and the invariant is pinned by differential tests that run every query both ways and compare id sets exactly. That is not a figure of speech but a working tool, and it is what caught the defect that would otherwise have shipped.

Compose that with projections and you get two independent levers: one cuts the engine's work, the other the materialiser's. On simple conditions the query travels an index the way a flat table would, and on deep graphs you keep what a flat schema does not have: no rows multiplied by joins, no Include written by hand.

Where it lives

The prefilter lives inside redb and works on all three Pro providers: PostgreSQL, SQL Server, SQLite. One flag, EnablePvtPrefilter in RedbServiceConfiguration, turns it on. It is a step of query compilation rather than a separate mode: the same LINQ, the same result set, the same result, the same observability. The difference is that the aggregate now receives not the whole scheme, but only what could possibly match.

If this was useful — a ⭐ on GitHub helps others find it.

More of my writing: redbase.app/articles, and on dev.to.

10 EF Core Performance Mistakes That Ship to Production

Majdi Zlitni — Wed, 26 Aug 2026 16:16:05 +0000

If your API is fast with seed data but slows down in production, EF Core is rarely the root cause. It is usually the amplifier.

Most teams do not have one catastrophic query. They have many small query-shape decisions that compound into high P95 latency, lock pressure, and unnecessary database scale-up.

This article is a practical field guide to 10 EF Core performance mistakes I keep seeing in production .NET APIs, and the fixes that usually move the needle first.

In this post

Why this matters in production
How to spot issues fast
Architecture map of the anti-patterns
Quick summary of all 10 mistakes
Mistake 1: N+1 Queries
Mistake 2: Missing AsNoTracking
Mistake 3: Loading Whole Entities
Mistake 4: No Pagination
Mistake 5: Client-Side Evaluation
Mistake 6: Tracking Read-Only Data
Mistake 7: Cartesian Explosion
Mistake 8: No Compiled Queries
Mistake 9: Missing Indexes
Mistake 10: SaveChanges in a Loop
Batch ops caveat: ExecuteUpdate and ExecuteDelete
Decision matrix: what to fix first
What EF Core 10 improves
Troubleshooting checklist
Production baseline checklist
Wrap-up

What counts as a performance mistake?

An EF Core performance mistake is any data-access pattern that:

returns correct results in development
passes tests
but degrades badly under real data volume or concurrency

In other words: correctness is not enough. Query shape is architecture.

How to detect issues quickly

Before changing code, instrument first.

builder.Services.AddDbContext<AppDbContext>(options =>
        options.UseNpgsql(connectionString)
                     .LogTo(Console.WriteLine, LogLevel.Information)
                     .EnableSensitiveDataLogging(builder.Environment.IsDevelopment()));

Use this as your first pass:

many SELECTs per request: likely N+1
huge result row count for small parent set: likely cartesian explosion
read endpoints with heavy tracking snapshots: missing AsNoTracking
list endpoints without LIMIT/TOP: missing pagination

The anti-pattern map

Prefer scalable quality for sharing and zoom:

TL;DR

The 10 mistakes:

N+1 queries
Loading full entities instead of projections
Missing AsNoTracking on read paths
No pagination on list endpoints
Client-side evaluation patterns
Tracking read-only graphs
Cartesian explosion from multiple collection Includes
No compiled queries on hot paths
Missing indexes on hot filters and joins
SaveChanges inside loops

Plus one operational caveat: ExecuteUpdate and ExecuteDelete bypass the change tracker and should be coordinated with explicit transaction boundaries when mixed with tracked changes.

1) N+1 Queries

Problem

You load a parent set, then each navigation access triggers another database round trip.

Smell

Request count looks normal
SQL command count explodes

Fix

Use projection or eager loading intentionally.

var orders = await db.Orders
    .Where(o => o.CustomerId == customerId)
    .Select(o => new OrderDto
    {
        Id = o.Id,
        Total = o.Items.Sum(i => i.Price * i.Quantity),
        ItemCount = o.Items.Count
    })
    .ToListAsync();

Use projection for API contracts. Use Include when domain logic needs full related aggregates in memory.

2) Missing AsNoTracking

Problem

Tracking every entity in read paths increases memory and CPU for change detection.

Fix

Default to no tracking on query endpoints.

var posts = await db.Posts
    .AsNoTracking()
    .Where(p => p.Published)
    .OrderByDescending(p => p.PublishedAt)
    .ToListAsync();

For write paths, opt back in explicitly:

var entity = await db.Orders
    .AsTracking()
    .FirstAsync(o => o.Id == id);

3) Loading Whole Entities

Problem

Fetching full rows when you only need 2-3 columns inflates payload and materialization cost.

Fix

Project to DTOs.

var users = await db.Users
    .AsNoTracking()
    .Select(u => new UserListItem(u.Id, u.DisplayName, u.AvatarUrl))
    .ToListAsync();

Projection usually improves all of these at once:

less SQL payload
lower materialization cost
better API boundary control

4) No Pagination

Problem

Unbounded lists eventually become accidental load tests.

Fix

Apply deterministic ordering and pagination.

var page = await db.Articles
    .AsNoTracking()
    .OrderByDescending(a => a.CreatedAt)
    .Skip((request.Page - 1) * request.PageSize)
    .Take(request.PageSize)
    .ToListAsync();

Always cap server-side page size to prevent accidental heavy requests.

5) Client-Side Evaluation

Problem

Non-translatable logic forces EF Core to pull data and evaluate in memory.

Fix

Keep filters SQL-translatable, move complex logic after narrowing rows.

var filtered = await db.Payments
    .AsNoTracking()
    .Where(p => p.Status == PaymentStatus.Settled && p.Amount > 1000)
    .Select(p => new { p.Id, p.Amount, p.Reference })
    .ToListAsync();

Rule: filter, sort, and paginate before materialization. Terminal operators like ToListAsync end translation and execute the query.

6) Tracking Read-Only Data

Problem

Long-running request flows with tracked entities increase memory pressure and GC churn.

Fix

Use one of these:

AsNoTracking for pure reads
AsNoTrackingWithIdentityResolution when graph identity consistency matters

var graph = await db.Orders
    .AsNoTrackingWithIdentityResolution()
    .Include(o => o.Customer)
    .Include(o => o.Items)
    .ToListAsync();

Use AsNoTrackingWithIdentityResolution when you need consistent identity for repeated references in the same result graph without full tracking overhead.

7) Cartesian Explosion

Problem

Multiple collection Includes on one query create row multiplication.

Fix

Use split queries when shape is unavoidable.

var orders = await db.Orders
    .AsNoTracking()
    .Include(o => o.Items)
    .Include(o => o.Events)
    .AsSplitQuery()
    .ToListAsync();

Split queries trade one huge cross-product for multiple smaller round trips. Measure both modes on your dataset.

8) No Compiled Queries

Problem

Hot endpoints repeatedly pay query translation overhead.

Fix

Precompile stable high-frequency queries.

private static readonly Func<AppDbContext, Guid, Task<User?>> GetUserByIdCompiled =
    EF.CompileAsyncQuery((AppDbContext ctx, Guid id) =>
        ctx.Users.AsNoTracking().FirstOrDefault(u => u.Id == id));

var user = await GetUserByIdCompiled(db, userId);

Apply compiled queries selectively to the highest-throughput read paths.

9) Missing Indexes

Problem

Critical filters run as scans instead of seeks.

Fix

Create indexes for common predicates and sort keys.

modelBuilder.Entity<Order>()
    .HasIndex(o => new { o.CustomerId, o.CreatedAt });

Also verify generated SQL and query plan. If your API filter is index-friendly but still scanning, check collation mismatches and implicit conversions.

Index guidance for hot endpoints:

index frequent WHERE columns
index JOIN keys
index ORDER BY columns used with pagination
prefer composite indexes that match filter plus sort order

10) SaveChanges in a Loop

Problem

Each SaveChanges call is a round trip and transaction boundary.

Fix

Batch entity changes, then persist once.

foreach (var item in items)
{
    item.MarkProcessed();
}

await db.SaveChangesAsync();

If this runs inside import or reconciliation jobs, moving SaveChanges out of the loop is often the fastest immediate win.

Batch operations caveat: ExecuteUpdate and ExecuteDelete

ExecuteUpdate and ExecuteDelete bypass the change tracker.

If you mix them with tracked updates in the same unit of work, wrap all operations in an explicit transaction to protect consistency.

await using var tx = await db.Database.BeginTransactionAsync();

await db.Orders
    .Where(o => o.Status == OrderStatus.Pending && o.CreatedAt < cutoff)
    .ExecuteUpdateAsync(setters => setters
        .SetProperty(o => o.Status, OrderStatus.Expired));

var audit = new CleanupAudit { RanAtUtc = DateTime.UtcNow, Affected = affectedRows };
db.CleanupAudits.Add(audit);

await db.SaveChangesAsync();
await tx.CommitAsync();

Why this matters:

batch operators bypass change tracker
SaveChanges interceptors may not run for those operations
mixed write workflows should be explicit about consistency boundaries

Decision matrix: what to fix first

Symptom	First fix	Then
many SQL commands per request	projection or Include cleanup	check for lazy loading
large payload and high serialization cost	projection DTOs	AsNoTracking
high read-path memory	AsNoTracking	query-level projection
huge row count from multi-Include	AsSplitQuery	endpoint-specific projection
slow large updates/deletes	ExecuteUpdate/ExecuteDelete	transaction + audit strategy
list endpoint timeout	pagination	indexes + projection
hot endpoint CPU overhead	compiled query	caching strategy

What EF Core 10 helps with

EF Core 10 improves the baseline, but does not remove bad query-shape costs.

Useful platform gains to leverage:

improved LINQ ergonomics for complex joins
stronger behavior around split-query ordering consistency
runtime improvements in .NET 10 that help materialization paths

Bottom line: framework improvements help good patterns more than bad ones.

Troubleshooting checklist

If performance is still poor after applying fixes:

inspect SQL plans, not just LINQ
verify index usage in production-like data
confirm no hidden lazy-loading path in serialization
verify query count per request in high-traffic endpoints
re-check page size limits and default sort columns

A practical baseline for production APIs

Default reads to no tracking
Project to DTOs, not entities
Always paginate collection endpoints
Measure query count per request
Add indexes for every top-traffic filter
Compile truly hot queries
Avoid SaveChanges inside loops
Treat batch operations as transaction-sensitive writes

EF Core performance is rarely about a single trick. It is about query-shape discipline applied consistently.

If your P95 latency is climbing, start here before scaling the database tier.

Wrap-up

Most EF Core incidents are not caused by obscure ORM bugs. They come from convenient defaults used past their safe limits.

If you adopt one rule, make it this: shape data intentionally at query time. Projection, no-tracking reads, pagination, and index-aware filters will solve most production regressions before you need heavier architecture changes.

System Design: Payment Processing System

Rhuturaj Takle — Wed, 26 Aug 2026 15:18:29 +0000

System Design: Payment Processing System

A capstone system design walkthrough — designing a payment processing system end to end — covering the core domain model, the ledger as the system's source of truth, idempotency and exactly-once-effect guarantees, integrating with external payment gateways and card networks, handling asynchronous webhooks, reconciliation, fraud and risk checks, and the specific correctness and compliance demands that make payments a uniquely unforgiving system design problem.

Introduction
Why Payment Systems Are a Different Kind of Hard
The Core Domain Model
The Ledger: Double-Entry Bookkeeping as the Source of Truth
Idempotency: The Single Most Important Property
Integrating with Payment Gateways and Card Networks
The Payment State Machine
Webhooks: Handling Asynchronous Gateway Callbacks
The Saga: Coordinating Payment Across Multiple Services
Reconciliation
Fraud and Risk Checks
Data Security and Compliance
Consistency, Availability, and the CAP Trade-off for Money
Scaling the System
Observability for a Payment System
Common Pitfalls
Quick Reference Table
Conclusion

Introduction

A payment processing system takes the general system design vocabulary covered in this series' System Design guide — databases, caching, queues, load balancing — and applies it to a domain where the ordinary consequences of a bug are dramatically higher: a double-charged customer, a lost payment, or a corrupted ledger isn't a degraded user experience, it's real money moved incorrectly, sometimes irreversibly. This guide walks through designing such a system end to end, drawing directly on this series' DDD, Event-Driven Architecture, Database Migrations, and Secret Management guides, each of which turns out to be load-bearing infrastructure for getting payments right rather than optional architectural polish.

Client → Payment API → [validate, risk-check] → Payment Gateway (Stripe/Adyen/etc.) → Card Network → Bank
                              ↓                           ↓ (async webhook)
                          Ledger (source of truth)  ←  Payment State Machine

1. Why Payment Systems Are a Different Kind of Hard

The cost of a bug is measured in money, not just user experience

Most systems covered in this series can tolerate a transient bug with a bounded, recoverable cost — a stale cache entry, a brief outage, a duplicate email. A payment system's failure modes are different in kind: a duplicate charge is real money taken from a real customer without their consent; a lost payment confirmation can mean a customer paid but never received their order, or a merchant shipped goods without ever being paid. This is why idempotency (Section 4) and the ledger's correctness (Section 3) dominate this guide's concerns more than raw throughput does.

Money must reconcile — silently "close enough" isn't a valid state

A social media "likes" counter being off by one, briefly, is invisible and harmless.
A ledger being off by one cent, ANYWHERE, is a genuine defect that must be found and explained.

Unlike most eventually-consistent systems covered in this series' Event-Driven Architecture guide, where "briefly stale, then converges" is an acceptable trade-off, a payment ledger must reconcile to the cent, provably, against the external systems (card networks, banks) it represents — this is a stricter correctness bar than "eventually consistent," and Section 9's reconciliation process exists specifically to enforce it continuously, not just trust that it holds.

You are almost never processing the actual money movement yourself

A critical, freeing realization for the design that follows: a payment processing system, in the overwhelming majority of real-world designs, does not itself move money between bank accounts — it orchestrates a request to a payment gateway (Stripe, Adyen, Braintree, or a similar processor), which in turn talks to card networks (Visa, Mastercard) and banks. Your system's job is to reliably record intent, submit the request, track the outcome, and maintain an accurate internal ledger of what happened — not to reimplement banking infrastructure, which is precisely the kind of "don't build what a specialized provider already does well" guidance echoed in this series' Secret Management and OAuth2/OIDC guides for identity, applied here to money movement.

2. The Core Domain Model

Modeled with DDD, per this series' companion guide

public record PaymentId(Guid Value);
public record Money(long MinorUnits, string Currency); // e.g., 4999 minor units + "USD" = $49.99 — see Section 3's note on this

public enum PaymentStatus { Initiated, Authorized, Captured, Failed, Refunded, PartiallyRefunded }

public class Payment // the AGGREGATE ROOT, per this series' DDD guide
{
    public PaymentId Id { get; }
    public Money Amount { get; }
    public PaymentStatus Status { get; private set; }
    private readonly List<PaymentEvent> _domainEvents = new();

    public void Authorize(string gatewayAuthorizationId)
    {
        if (Status != PaymentStatus.Initiated)
            throw new InvalidOperationException($"Cannot authorize a payment in status {Status}");
        Status = PaymentStatus.Authorized;
        _domainEvents.Add(new PaymentAuthorizedEvent(Id, gatewayAuthorizationId));
    }

    public void Capture()
    {
        if (Status != PaymentStatus.Authorized)
            throw new InvalidOperationException($"Cannot capture a payment in status {Status}");
        Status = PaymentStatus.Captured;
        _domainEvents.Add(new PaymentCapturedEvent(Id, Amount));
    }
}

This directly applies this series' DDD guide's aggregate pattern — Payment is the aggregate root, enforcing its own state transitions (you cannot capture a payment that was never authorized) rather than trusting every caller to check status before mutating it, and raising domain events at exactly the points those transitions genuinely occur.

Why money should never be a floating-point or plain `decimal` type without care

// ❌ Floating-point arithmetic on money is a well-known, serious source of rounding errors
double amount = 49.99; // binary floating point cannot represent this exactly

// ✅ Store money as an integer count of the smallest currency unit (cents, minor units)
public record Money(long MinorUnits, string Currency); // 4999 minor units = $49.99

Representing money as double risks genuine, real rounding errors accumulating over many operations — the standard, widely-adopted practice is storing an amount as an integer number of the currency's smallest unit (cents for USD, pence for GBP), only converting to a display-formatted decimal string at the presentation layer, never performing arithmetic in that display format. decimal in C# is safer than double for money (base-10, not binary floating point), but many production payment systems still prefer integer minor units specifically for unambiguous cross-language, cross-system interoperability — worth being deliberate about which convention a given system adopts and applying it consistently everywhere money is represented.

Value objects for currency-safety

public Money Add(Money other)
{
    if (Currency != other.Currency) throw new InvalidOperationException("Cannot add different currencies");
    return this with { MinorUnits = MinorUnits + other.MinorUnits };
}

As covered in this series' DDD guide's value object discussion, wrapping a raw amount in a Money value object that enforces currency-matching on any arithmetic operation prevents an entire class of bugs (accidentally adding USD to EUR) at the type level, rather than relying on every call site to remember to check currencies match.

3. The Ledger: Double-Entry Bookkeeping as the Source of Truth

Why a simple "balance" column is insufficient

-- ❌ A single mutable balance column has no audit trail and is trivially corruptible by a single bad UPDATE
UPDATE accounts SET balance = balance - 100 WHERE id = 1;

A payment system needs more than "what is the current balance" — it needs an immutable, auditable record of every movement of money that ever occurred, and the ability to prove, at any point, exactly how the current balance was arrived at. A mutable balance column, updated in place, destroys that history the moment it's overwritten, and provides no structural protection against a bug (or a malicious actor) silently corrupting a balance with no trace of how it happened.

Double-entry bookkeeping: every movement recorded as two balanced entries

CREATE TABLE ledger_entries (
    id BIGINT PRIMARY KEY,
    transaction_id UUID NOT NULL,   -- groups the debit and credit belonging to one logical movement
    account_id BIGINT NOT NULL,
    amount_minor_units BIGINT NOT NULL, -- positive for a credit, negative for a debit
    currency CHAR(3) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- A $49.99 payment captured: money moves from "customer owes" to "merchant receivable"
INSERT INTO ledger_entries (transaction_id, account_id, amount_minor_units, currency) VALUES
  ('a1b2c3d4-...', /* customer_receivable_account */ 100, -4999, 'USD'),
  ('a1b2c3d4-...', /* merchant_payable_account */    200,  4999, 'USD');
-- these two rows, sharing one transaction_id, must ALWAYS sum to zero

Double-entry bookkeeping — the centuries-old accounting technique this system borrows directly — records every movement of money as (at least) two balanced entries: a debit from one account and a credit to another, always summing to exactly zero for any given transaction. This isn't accounting ceremony for its own sake; it's a structural, mathematically-verifiable invariant: at any point, summing every ledger entry for a given transaction ID must equal zero, and summing every entry for a given account gives that account's genuine, provable current balance, derived entirely from the append-only history rather than trusted as a separately-maintained, corruptible number.

The ledger table is append-only, never updated or deleted

-- Correcting a mistake means inserting a NEW, compensating entry — never UPDATE or DELETE an existing row
INSERT INTO ledger_entries (transaction_id, account_id, amount_minor_units, currency) VALUES
  ('correction-e5f6...', /* customer_receivable_account */ 100, 4999, 'USD'),  -- reverses the original debit
  ('correction-e5f6...', /* merchant_payable_account */    200, -4999, 'USD'); -- reverses the original credit

This directly echoes the append-only log philosophy covered in this series' Kafka and Event Sourcing (via the DDD and Event-Driven Architecture guides) discussions — the ledger is never mutated in place; a mistake is corrected by inserting a new, compensating entry that reverses the original, preserving the complete, honest history of everything that happened, including the mistake and its correction, rather than erasing evidence that a mistake occurred at all. This property is what makes the ledger auditable and, critically, what regulators and auditors expect from any genuine financial system.

Balance as a derived, always-recomputable value

SELECT SUM(amount_minor_units) AS current_balance
FROM ledger_entries
WHERE account_id = 100;

An account's current balance is always a SUM query over its ledger entries — never a separately-stored, independently-updatable number that could drift out of sync with the entries that supposedly produced it. For performance (summing potentially millions of historical entries on every balance check is genuinely expensive), a cached/materialized balance is a reasonable optimization (directly connecting to this series' caching and materialized-view discussions), but it must always be treated as a derived cache of the ledger's truth, recomputable and re-verifiable against it at any time — never the authoritative source itself.

4. Idempotency: The Single Most Important Property

Why this is even more critical here than in any other system covered in this series

As covered throughout this series' RabbitMQ, Kafka, Azure Service Bus, and Event-Driven Architecture guides, every messaging technology provides at-least-once delivery, and every network call can time out ambiguously (did the request actually succeed server-side, or not, before the client gave up waiting?) — for most systems, a resulting duplicate action is an annoyance (a duplicate email, a slightly wasted computation). For a payment system, an un-idempotent retry means charging a customer twice for the same purchase, which is precisely why idempotency is this guide's single most emphasized property.

Idempotency keys: the standard mechanism

[HttpPost("/payments")]
public async Task<IActionResult> CreatePayment(
    [FromHeader(Name = "Idempotency-Key")] string idempotencyKey,
    CreatePaymentRequest request)
{
    var existing = await _idempotencyStore.GetResultAsync(idempotencyKey);
    if (existing is not null)
    {
        return Ok(existing); // the SAME response as the original request, no new charge attempted
    }

    var payment = await _paymentService.ProcessAsync(request);
    await _idempotencyStore.SaveResultAsync(idempotencyKey, payment);
    return Ok(payment);
}

This is the concrete implementation of the idempotency pattern introduced generally in this series' Redis guide's rate-limiting section and REST guide's discussion — a client generates a unique idempotency key for each logical payment attempt (not regenerated on retry) and includes it on every request, including retries; the server checks whether that key has already been processed and, if so, returns the original result rather than attempting the charge again. This is precisely how Stripe, Adyen, and every major payment gateway's own API is designed, and any payment system built on top of one should propagate this exact same discipline to its own client-facing API.

Idempotency at every layer the payment touches, not just the outermost API

Client → Payment API (idempotency key checked here)
            → Payment Gateway call (the GATEWAY also expects and enforces its own idempotency key)
            → Ledger write (a database-level unique constraint on transaction_id prevents a duplicate insert)
            → Event published (per this series' Event-Driven Architecture guide, consumers must ALSO be idempotent)

Idempotency needs to be enforced at every hop, not just the client-facing entry point — the call to the external payment gateway itself should include its own idempotency key (most major gateways support and expect this natively), the ledger write should have a database constraint preventing a duplicate transaction ID from ever being inserted twice, and any downstream event consumers (per this series' Event-Driven Architecture guide) must independently be idempotent against redelivery, since a payment system is exactly the kind of system where "we'll just be extra careful" is not an acceptable substitute for structural, enforced guarantees at every layer.

5. Integrating with Payment Gateways and Card Networks

The layers between your system and an actual bank

Your system → Payment Gateway (Stripe, Adyen, Braintree) → Card Network (Visa, Mastercard) → Issuing Bank

A payment gateway is the specialized third party that actually handles the sensitive complexity of talking to card networks and banks — authorization, settlement, PCI compliance for card data handling (Section 11) — so that a payment system, in the overwhelming majority of real designs, never directly touches raw card numbers or talks to a card network itself at all.

Authorization vs. capture: a two-phase pattern most gateways support

// Phase 1: authorize — places a hold on the customer's funds, doesn't yet move money
var authResult = await _gateway.AuthorizeAsync(new AuthorizeRequest(amount, cardToken));
payment.Authorize(authResult.GatewayAuthorizationId);

// Phase 2: capture — actually moves the money, typically once the order genuinely ships
var captureResult = await _gateway.CaptureAsync(authResult.GatewayAuthorizationId, amount);
payment.Capture();

Separating authorization (verifying funds are available and placing a hold) from capture (actually completing the charge) is a deliberate, widely-used design pattern — it lets a merchant confirm a customer can pay before committing to ship an order, and only finalize the charge once the order genuinely ships, reducing the need for refunds on orders that turn out to be unfulfillable, and directly mapping onto the Payment aggregate's state machine from Section 2.

Using gateway-provided tokens, never touching raw card numbers directly

// Card details are tokenized CLIENT-SIDE, by the gateway's own JS SDK — your server NEVER sees the raw card number
const { token } = await stripe.createToken(cardElement);
// only this opaque token is ever sent to YOUR backend

The standard, essentially universal pattern: raw card numbers are tokenized directly in the client (browser or mobile app), by the payment gateway's own SDK, before ever reaching your server — your backend only ever handles an opaque token representing the card, never the actual card number itself. This dramatically reduces your own system's PCI compliance burden (Section 11) since sensitive card data structurally never touches your infrastructure at all.

6. The Payment State Machine

An explicit, enumerable set of states and legal transitions

Initiated → Authorized → Captured → (Refunded | PartiallyRefunded)
     ↓            ↓
   Failed       Failed

As covered in Section 2's Payment aggregate, a payment's lifecycle is a small, explicit state machine — and the aggregate's own methods (Authorize(), Capture()) are what enforce that only legal transitions are ever possible, throwing rather than silently succeeding if called out of order (attempting to capture a payment that was never authorized, for instance).

Why an explicit state machine matters more here than for most domain objects

Given this guide's emphasis on the cost of a payment-related bug, having every legal and illegal state transition explicitly enumerated and enforced by the aggregate itself — rather than scattered conditional checks across application code — is precisely the kind of rigor this series' DDD guide argues pays for itself most clearly in domains with genuinely complex, high-stakes business rules, and few domains fit that description more clearly than payments.

Terminal states and their permanence

public void Refund(Money refundAmount)
{
    if (Status is not (PaymentStatus.Captured or PaymentStatus.PartiallyRefunded))
        throw new InvalidOperationException($"Cannot refund a payment in status {Status}");
    // ... a Refunded/PartiallyRefunded payment can never transition back to Captured
}

Certain states are genuinely terminal or near-terminal (a Failed payment doesn't transition anywhere further; a fully Refunded payment shouldn't be refundable again) — encoding these as hard constraints in the aggregate is what prevents an entire category of "this should never happen but somehow did" production incidents specific to payment state.

7. Webhooks: Handling Asynchronous Gateway Callbacks

Why payment gateways rely on webhooks, not just synchronous API responses

Your system → gateway.charge() → gateway returns "pending" immediately
    ... (minutes later, potentially) ...
Gateway → POST /webhooks/payment-status → your system, asynchronously reporting the FINAL outcome

Many payment flows (particularly certain card types requiring additional authentication, or bank transfers) don't resolve synchronously within the original API call — the gateway instead sends an asynchronous webhook once the final outcome is known, directly connecting to this series' Event-Driven Architecture guide's core theme: your system needs to handle this exactly like consuming an event from an external, asynchronous source, with all the same discipline (idempotency, per Section 4; ordering awareness) that guide covers for internal messaging.

Verifying webhook authenticity — this is not optional

[HttpPost("/webhooks/payment-gateway")]
public async Task<IActionResult> HandleWebhook()
{
    var payload = await new StreamReader(Request.Body).ReadToEndAsync();
    var signature = Request.Headers["Stripe-Signature"];

    // Verifies the payload genuinely came from the gateway, using a shared secret — per this series'
    // Secret Management and JWT Validation guides' emphasis on never trusting an unverified sender
    var isValid = _gatewaySignatureVerifier.Verify(payload, signature, _webhookSecret);
    if (!isValid) return Unauthorized();

    var evt = ParseWebhookEvent(payload);
    await ProcessWebhookEventAsync(evt);
    return Ok();
}

A webhook endpoint is a publicly reachable URL, by necessity — without verifying the gateway's cryptographic signature on every incoming webhook (using a shared secret, stored per this series' Secret Management guide), an attacker could submit a forged "payment succeeded" webhook and trick your system into believing a payment completed when it never did. This is a direct, concrete application of this series' OWASP Top 10 guide's broken-authentication and injection categories, applied specifically to a payment system's most externally-exposed surface.

Webhook idempotency and out-of-order delivery

if (await _processedWebhookEvents.ExistsAsync(evt.EventId)) return Ok(); // already processed, safe no-op

if (evt.Timestamp < payment.LastUpdatedAt) return Ok(); // an OLDER event arriving late — ignore, don't regress state

As covered in this series' Event-Driven Architecture guide, webhooks are subject to the same at-least-once delivery and potential out-of-order arrival as any other asynchronous message — tracking processed event IDs (idempotency, Section 4 again) and comparing event timestamps against the payment's own last-known state (to avoid a late-arriving, stale webhook incorrectly reverting a payment to an earlier state) are both essential, not optional hardening.

8. The Saga: Coordinating Payment Across Multiple Services

Payment as one step in a larger, cross-service business process

OrderSaga (per this series' Event-Driven Architecture guide):
  1. OrderService: create order (pending)
  2. InventoryService: reserve stock — compensating action: release stock
  3. PaymentService: charge payment — compensating action: REFUND
  4. OrderService: confirm order

As covered directly in this series' Event-Driven Architecture and Microservices guides, "place an order" typically spans multiple services with separate databases — payment is one step in that larger saga, and its compensating action, should a later step fail, is a refund, not a database rollback (since, per Section 1, there's no cross-service ACID transaction spanning the order, inventory, and payment services' separate databases).

Why the compensating action for a payment is itself a genuine, auditable transaction

public async Task CompensateAsync(PaymentId paymentId)
{
    var payment = await _repository.GetByIdAsync(paymentId);
    var refund = payment.Refund(payment.Amount); // a NEW ledger transaction, per Section 3 — never erasing the original charge
    await _gateway.RefundAsync(payment.GatewayCaptureId, payment.Amount);
}

Unlike compensating actions in many other domains (releasing a reserved inventory count, say), a payment's compensation is itself a fully real, ledger-recorded, gateway-executed transaction — this directly reinforces Section 3's append-only ledger principle: a failed downstream step doesn't erase the original charge from history, it records a new, compensating refund transaction alongside it, preserving the complete, honest record of what actually happened.

9. Reconciliation

Why "the ledger looks right" isn't sufficient — it must be proven against external truth

Your ledger says: $48,392.17 captured today
The payment gateway's own settlement report says: $48,392.17 settled today
→ these must match, EXACTLY, every single day

Reconciliation is the (often nightly, automated) process of comparing your system's own ledger against the payment gateway's independently-generated settlement reports, and ultimately against your bank's actual statements — this is the concrete, continuously-enforced verification that Section 1's "money must reconcile" property actually holds, not just an assumption resting on your own system's internal consistency checks alone.

Automating reconciliation, and surfacing discrepancies immediately

public async Task ReconcileAsync(DateOnly date)
{
    var ourRecords = await _ledgerRepository.GetCapturedPaymentsForDateAsync(date);
    var gatewayRecords = await _gateway.GetSettlementReportAsync(date);

    var discrepancies = FindMismatches(ourRecords, gatewayRecords);
    if (discrepancies.Any())
    {
        await _alerting.RaiseAsync("Reconciliation discrepancy detected", discrepancies); // per this series'
                                                                                             // Prometheus/Grafana guide's
                                                                                             // alerting discipline
    }
}

A discrepancy found during reconciliation — a payment your system believes captured that the gateway's settlement report doesn't show, or vice versa — is a genuinely serious signal, treated with the same urgency as a security incident (per this series' OWASP Top 10 guide) rather than a routine data-quality issue to quietly patch; every discrepancy needs to be understood and explained, not merely corrected and forgotten.

Reconciliation as a recurring, automated background process

public class NightlyReconciliationWorker : BackgroundService // per this series' Background Services guide
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // scheduled, per this series' Background Services guide's recurring-job patterns, using Hangfire or Quartz.NET
    }
}

This directly reuses the scheduled background job patterns covered in this series' Background Services guide — reconciliation is precisely the kind of recurring, automated job those patterns are built for, run nightly (or more frequently) without manual intervention, with its own health monitoring (per this series' Health Checks guide's "last successful run" pattern) to ensure the reconciliation job itself hasn't silently stopped running.

10. Fraud and Risk Checks

Where fraud checks fit in the payment flow

Payment request → [Risk scoring: velocity checks, device fingerprinting, address verification]
                        ↓
              Score below threshold: proceed to gateway authorization
              Score above threshold: hold for manual review, or decline outright

A production payment system layers fraud/risk assessment before (or alongside) the actual gateway authorization call — checking transaction velocity (has this card/account attempted an unusual number of payments recently), device and IP reputation, and billing/shipping address consistency, often using a specialized third-party risk-scoring service (analogous to how gateways themselves are typically third-party specialists, per Section 1) rather than building fraud detection from scratch.

The trade-off between fraud prevention and legitimate-customer friction

Every fraud check has a real cost in false positives — a legitimate customer wrongly declined or delayed by an overly aggressive risk check is a genuine, measurable business cost, not a harmless extra precaution; this is a deliberate, ongoing tuning exercise (adjusting risk thresholds based on observed false-positive and fraud-loss rates over time) rather than a "more strict is always better" default.

3D Secure and step-up authentication

Card payment → gateway determines additional authentication is required (3D Secure) →
  customer redirected to their bank's own authentication challenge → returns, payment proceeds

For card payments specifically, 3D Secure (the "Verified by Visa"/"Mastercard Identity Check" flow many customers have encountered) shifts liability for certain fraud disputes from the merchant to the card issuer, in exchange for an additional authentication step — most gateways handle the actual challenge flow, but your system's payment flow (and its state machine, per Section 6) needs to accommodate this additional, asynchronous authentication step as a legitimate part of the payment lifecycle, not an edge case.

11. Data Security and Compliance

PCI DSS: why tokenization (Section 5) is the practical answer, not a checklist to satisfy directly

The Payment Card Industry Data Security Standard (PCI DSS) imposes extensive, genuinely burdensome requirements on any system that stores, processes, or transmits raw card data — the practical, almost universally adopted strategy for a system built on top of a gateway (per Section 5) is to never let raw card data touch your own infrastructure at all, via client-side tokenization, which dramatically narrows your own PCI compliance scope rather than requiring you to build and audit a full PCI-compliant environment yourself.

Encryption and secret management for whatever sensitive data your system does hold

// API keys for the payment gateway itself are exactly the kind of secret covered in this series'
// Secret Management guide — never in source control, ideally via Managed Identity + Key Vault
var gatewayApiKey = await _secretClient.GetSecretAsync("payment-gateway-api-key");

Even with card data itself tokenized away, a payment system still holds genuinely sensitive secrets — gateway API keys, webhook signing secrets — and every principle covered in this series' Secret Management guide applies directly and without exception here: no hardcoded credentials, Managed Identity where the platform supports it, and rotation discipline for anything that could grant an attacker the ability to initiate fraudulent charges or forge webhook events.

Audit logging as a compliance and forensic requirement, not just an operational nicety

logger.LogInformation("Payment {PaymentId} captured for {Amount} by {ActorId}", payment.Id, payment.Amount, actorId);

As covered in this series' Structured Logging and OWASP Top 10 guides, every sensitive action (a payment captured, a refund issued, a risk override applied) needs to be logged with enough context (who, what, when) to support both regulatory audit requirements and forensic investigation after an incident — this is a stricter, more comprehensive logging bar than most systems require, precisely because of Section 1's stakes.

12. Consistency, Availability, and the CAP Trade-off for Money

Why payment systems generally favor consistency over availability, unlike much of this series' general guidance

As covered in this series' System Design guide's CAP theorem discussion, most systems in this series lean toward availability and eventual consistency where possible — a payment system is one of the clearer, most defensible exceptions: it is generally preferable for a payment attempt to fail cleanly (the customer retries, or sees a clear error) than for the system to accept it under uncertain, potentially-inconsistent conditions and risk a ledger discrepancy that reconciliation (Section 9) later has to painstakingly untangle.

Where eventual consistency is still acceptable, deliberately scoped

The LEDGER write (money moved) → strong consistency required, no compromise
A downstream ANALYTICS dashboard showing "today's revenue" → eventual consistency is genuinely fine

Not every part of a payment system needs the same consistency bar — the core ledger write absolutely does, but downstream, read-only projections (a merchant's revenue dashboard, an analytics pipeline) can and should tolerate the same eventual consistency this series' Event-Driven Architecture and CQRS discussions describe generally, since a dashboard being a few seconds stale carries none of the risk a genuinely inconsistent ledger does.

13. Scaling the System

Applying this series' System Design guide's building blocks, with payment-specific emphasis

Read replicas (per this series' SQL Server/PostgreSQL guides): safe for READ-heavy queries
  (transaction history, dashboards) — never route a WRITE that must be immediately consistent to a replica
Caching (per this series' Redis guide): appropriate for relatively static data (merchant configuration,
  fee schedules) — NEVER cache a payment's current status, which must always reflect genuine current state
Queues (per this series' RabbitMQ/Kafka guides): appropriate for the asynchronous parts of the flow
  (webhook processing, sending receipt emails, updating analytics) — NOT for the synchronous
  authorization call itself, which the customer is actively waiting on

Every technique from this series' System Design guide applies here, with the caveat that each one needs to be evaluated against this guide's stricter consistency bar (Section 12) before being applied — the general principle "identify the bottleneck, then apply the specific technique" holds, but payments narrow which techniques are safe to apply to which specific part of the flow.

Sharding the ledger, and the partition key that actually matters

Sharding by account_id (or merchant_id) keeps all of one account's ledger entries together,
  making "what is this account's balance" a single-shard query rather than a cross-shard fan-out

As covered in this series' System Design and Cosmos DB/MongoDB guides, choosing the ledger's partition/shard key deliberately — typically the account or merchant ID, since balance queries are the most common and most latency-sensitive access pattern — avoids the expensive cross-shard fan-out that a poorly chosen key (transaction ID, say) would force on every balance check.

14. Observability for a Payment System

Every guide in this series' observability trio, applied with payment-specific stakes

Structured logs (per this series' Structured Logging guide): every payment state transition, logged
  with the payment ID and correlation ID, NEVER logging raw card data or full gateway tokens
Distributed tracing (per this series' Distributed Tracing guide): tracing a single payment's journey
  across the risk check, gateway call, and ledger write — essential for diagnosing where a specific
  slow or failed payment actually got stuck
Metrics (per this series' Prometheus/Grafana guide): payment success rate, gateway latency,
  authorization decline rate — the aggregate health signals a payments team watches continuously

Every technique from this series' observability guides applies directly, with one payment-specific addition worth stating explicitly: logs and traces must never capture raw card numbers, full gateway tokens, or CVV data, even for debugging purposes — this is a hard, non-negotiable line directly extending this series' OWASP Top 10 and Secret Management guides' "never log sensitive data" principle, applied here with genuinely higher stakes than almost any other domain in this series.

Alerting on payment-specific symptoms

# Per this series' Prometheus/Grafana guide's symptom-based alerting principle, applied to payments
rate(payment_declined_total[5m]) / rate(payment_attempted_total[5m]) > 0.15  # a sudden decline-rate spike

A sudden spike in the payment decline rate, or in gateway latency, is exactly the kind of user-facing symptom this series' Prometheus/Grafana guide argues alerts should be built around — and for a payment system, the on-call response to such an alert carries unusually direct business consequences (lost revenue, frustrated customers), which is precisely why this category of alert deserves genuinely fast, well-rehearsed incident response.

15. Common Pitfalls

Pitfall	Why it hurts	Better approach
Storing money as `double` or unvalidated raw decimals	Real rounding errors, currency-mismatch bugs	Integer minor units or a currency-aware `Money` value object
A mutable balance column instead of an append-only ledger	No audit trail; a single bad `UPDATE` silently corrupts financial history	Double-entry, append-only ledger entries; balance as a derived `SUM`
No idempotency key on payment creation/retry	A network timeout retry genuinely double-charges the customer	Idempotency keys enforced at every layer: API, gateway call, and ledger write
Trusting an unverified webhook	An attacker can forge a fake "payment succeeded" event	Always verify the gateway's cryptographic signature on every webhook
Handling raw card numbers on your own servers	Enormous PCI DSS compliance burden, real breach risk	Client-side tokenization; never let raw card data touch your infrastructure
No reconciliation process, trusting your own ledger's internal consistency alone	A silent, undetected discrepancy against the gateway's own records	Automated, daily reconciliation against the gateway's settlement reports
Caching a payment's current status	Stale cached status shown to a customer or downstream system during an active, changing payment	Never cache genuinely time-sensitive payment state; cache only static reference data
Logging raw card numbers or full tokens for debugging	A severe compliance and security violation	Redact/exclude sensitive fields from all logs and traces, without exception

Quick Reference Table

Concept	Purpose
`Payment` aggregate + state machine	Enforces only legal payment state transitions, per this series' DDD guide
Double-entry, append-only ledger	The provably correct, auditable source of truth for all money movement
Idempotency key	Prevents duplicate charges from retries at every layer of the flow
Authorization / capture	Separates "verify funds available" from "actually move the money"
Tokenization	Keeps raw card data off your own infrastructure, narrowing PCI scope
Webhook signature verification	Prevents forged, unauthorized payment-status events
Saga + compensation (refund)	Coordinates payment correctly across a larger, multi-service business process
Reconciliation	Continuously proves the ledger matches the gateway's/bank's own records
Fraud/risk scoring	Balances fraud prevention against legitimate-customer friction

Conclusion

A payment processing system takes every general system design technique covered throughout this series and applies it under a stricter, less forgiving correctness bar — because the cost of a bug here is measured in real money moved incorrectly, not just degraded user experience. The design that actually holds up under that bar rests on a small number of non-negotiable foundations: a double-entry, append-only ledger as the provable source of truth; idempotency enforced at every single layer a payment touches; an explicit, aggregate-enforced state machine governing what transitions are even possible; and continuous, automated reconciliation that treats any discrepancy as a genuine incident rather than a rounding error to quietly absorb.

Nearly every architectural pattern covered elsewhere in this series shows up here in service of that bar — DDD's aggregates enforcing business rules, Event-Driven Architecture's sagas and idempotent consumers, Secret Management's discipline around gateway credentials, and the full observability trio watching over a system where "we'll notice eventually" is never an acceptable answer. Payments are, in that sense, less a distinct discipline from everything else in this series than the place where its cumulative lessons about correctness, idempotency, and honest reconciliation with reality matter more visibly and more unforgivingly than almost anywhere else.

Found this useful? Feel free to star the repo, open an issue with corrections, or share the reconciliation discrepancy that turned out to matter far more than a rounding error ever should.

.NET WebCIL Container Meets WebForms Core 2.1

Elanat Framework — Wed, 26 Aug 2026 14:02:10 +0000

What is WebForms Core?

WebForms Core is a modern multi-platform web technology from Elanat designed to build interactive web applications without requiring traditional client-side business logic.

WebForms Core uses a server-centric architecture in which the server defines UI behavior through commands, while a lightweight client engine executes those commands in the browser.

With the upcoming WebForms Core 2.1 (WFC), this architecture is being extended with another interesting capability: C# code running inside a .NET WebAssembly environment can use WebForms Core itself to generate UI commands.

This makes it possible to combine:

C#
.NET WebAssembly
WebForms Core
WebForms Core's declarative UI commands

inside the same WebAssembly application.

.NET WebCIL Container

One of the new possibilities demonstrated with WFC 2.1 is the use of a .NET WebCIL Container.

Instead of compiling C# into a standalone native-style WASM function such as:

add(10000, 3)

the application can load the .NET WebAssembly runtime and execute exported C# methods through dotnet.js.

For example:

using System.Runtime.InteropServices.JavaScript;
using WebFormsCore;

public partial class MyClass
{
    [JSExport]
    public static int Add(int a, int b)
    {
        return a + b;
    }

    [JSExport]
    public static string SetData(string inputPlace, string text, string backgroundColor, string fontSize)
    {
        WebForms form = new WebForms();

        form.SetText(inputPlace, text);
        form.SetBackgroundColor("-", backgroundColor);
        form.SetFontSize("-", fontSize);

        return form.Response();
    }

    [JSExport]
    public static string GetHtml()
    {
        return "<marquee>Tag From Wasm!</marquee>";
    }
}

public class Program
{
    public static void Main()
    {
    }
}

The important part is that WebForms.cs from WebForms Core is included in the WebAssembly project.

Therefore, C# code running inside the WebAssembly environment can directly create WebForms Core commands.

Creating the .NET WebCIL Project

Create a new .NET 10 WebAssembly console project:

dotnet new wasmconsole -n NativeWasmModule -f net10.0

Then enter the project:

cd NativeWasmModule

The project can use the following configuration:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <WasmEnableExceptionHandling>false</WasmEnableExceptionHandling>
    <RuntimeIdentifier>browser-wasm</RuntimeIdentifier>
    <OutputType>Exe</OutputType>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <WasmMainJSPath>main.mjs</WasmMainJSPath>
  </PropertyGroup>

</Project>

The project targets:

<TargetFramework>net10.0</TargetFramework>

and uses:

<RuntimeIdentifier>browser-wasm</RuntimeIdentifier>

The main.mjs file is specified as the JavaScript entry point:

<WasmMainJSPath>main.mjs</WasmMainJSPath>

Adding WebForms Core

The WebForms.cs class from WebForms Core is added to this project.

This is important because the WebAssembly C# code is now capable of using WebForms Core's API.

For example:

WebForms form = new WebForms();

form.SetText(inputPlace, text);
form.SetBackgroundColor("-", backgroundColor);
form.SetFontSize("-", fontSize);

return form.Response();

The C# method doesn't directly manipulate the browser DOM.

Instead, it generates a WebForms Core response.

This keeps the same philosophy used throughout WebForms Core.

Exporting C# Methods

Methods that should be accessible from JavaScript are marked with:

[JSExport]

For example:

[JSExport]
public static int Add(int a, int b)
{
    return a + b;
}

The method can then be accessed through the .NET WebAssembly runtime.

A method can also return a WebForms Core response:

[JSExport]
public static string SetData(string inputPlace, string text, string backgroundColor, string fontSize)
{
    WebForms form = new WebForms();

    form.SetText(inputPlace, text);
    form.SetBackgroundColor("-", backgroundColor);
    form.SetFontSize("-", fontSize);

    return form.Response();
}

This is where the combination becomes particularly interesting.

The WASM code isn't merely calculating a value.

It can generate WebForms Core UI behavior.

Using C# WebAssembly from WebForms Core

A WebForms Core controller can invoke the C# WebAssembly runtime:

using CodeBehind;

public partial class CsharpMediatorWasmController : CodeBehindController
{
    public void PageLoad(HttpContext context)
    {
        string WasmPath = "/web-assembly/csharp-publish/_framework/dotnet.js";

        WebForms form = new WebForms();

        form.AddText("<b>", Fetch.WasmMethod(WasmLanguage.CSharpMediator, WasmPath, "MyClass.Add", [10000, 3]));

        form.SetWasmEvent("WasmEvent", HtmlEvent.OnClick, WasmLanguage.CSharpMediator, WasmPath, "MyClass.SetData", ["h3Tag", "Text From Wasm", "lightgreen", "30px"]);

        form.SetWasmEvent("WasmEventWithOutput", HtmlEvent.OnClick, WasmLanguage.CSharpMediator, WasmPath, "MyClass.GetHtml", [], "WasmHtmlOutput");

        Write(form.ExportToHtmlComment());
    }
}

Notice the method names:

MyClass.Add
MyClass.SetData
MyClass.GetHtml

The class name can be specified before the method name.

This makes it possible to address exported methods belonging to different C# types.

HTML

The HTML remains simple:

@page
@controller CsharpMediatorWasmController
@layout "/layout.aspx"

@{
    ViewData.Add("title", "C# Mediator Wasm");
}

<h3>.NET WebCIL Container</h3>

<b>C# Mediator WASM Result: </b>

<br>

<button id="WasmEvent">
    Wasm Event
</button>

<br>

<h3 id="h3Tag">
    Wasm Tag Changing!
</h3>

<button id="WasmEventWithOutput">
    Wasm Event With Output
</button>

<p id="WasmHtmlOutput">
    Wasm Html Output
</p>

There is no custom WebAssembly element.

There is no special DOM component.

There is no C# component syntax.

The HTML remains standard HTML.

The Interesting Part

Consider this:

form.SetWasmEvent("WasmEvent", HtmlEvent.OnClick, WasmLanguage.CSharpMediator, WasmPath, "MyClass.SetData", ["h3Tag", "Text From Wasm", "lightgreen", "30px"]);

The server declares:

When this button is clicked, execute MyClass.SetData inside the C# WebAssembly runtime.

The method executes:

WebForms form = new WebForms();

form.SetText(inputPlace, text);
form.SetBackgroundColor("-", backgroundColor);
form.SetFontSize("-", fontSize);

return form.Response();

The result is then handled by WebForms Core.

The C# WebAssembly method therefore becomes another source of WebForms Core commands.

WASM Event With Output

The same mechanism can return HTML:

[JSExport]
public static string GetHtml()
{
    return "<marquee>Tag From Wasm!</marquee>";
}

and:

form.SetWasmEvent("WasmEventWithOutput", HtmlEvent.OnClick, WasmLanguage.CSharpMediator, WasmPath, "MyClass.GetHtml", [], "WasmHtmlOutput");

The returned value is placed into:

<p id="WasmHtmlOutput"></p>

This demonstrates that the WASM method can be used not only for calculations, but also as a source of dynamic UI output.

The screenshot below shows the HTML page after clicking the buttons.

What Makes This Different?

This is not simply:

"Run C# in the browser."

That capability already exists.

The interesting part is the combination of C# WebAssembly and WebForms Core.

A C# method running inside WebAssembly can use:

WebForms

and produce WebForms Core commands.

That creates a pipeline like this:

C# WebAssembly
      ↓
  WebForms.cs
      ↓
WebForms Core Response
      ↓
WebForms Core Client Engine
      ↓
     DOM

The WebAssembly code does not need to know how the browser DOM is implemented.

It can describe the desired UI behavior through WebForms Core.

Native WASM and .NET WebCIL Are Different

WebForms Core can work with different types of WebAssembly environments.

For example, a native WASM module may expose a function such as:

add

and can be loaded directly as a .wasm module.

The .NET approach is different.

With the .NET WebCIL environment, the entry point is:

dotnet.js

and the .NET runtime loads the necessary WebAssembly components.

Therefore:

Native WASM
     ↓
module.wasm
     ↓
WebAssembly.instantiate()

is conceptually different from:

.NET WebAssembly
     ↓
dotnet.js
     ↓
.NET runtime
     ↓
C# exported method

WebForms Core can provide an abstraction over these different execution models.

No JavaScript Business Logic

One of the most interesting properties of this example is that the application does not require custom JavaScript business logic.

The C# code contains:

public static string SetData(...)
{
    WebForms form = new WebForms();

    form.SetText(...);
    form.SetBackgroundColor(...);
    form.SetFontSize(...);

    return form.Response();
}

The HTML contains:

<button id="WasmEvent">
    Wasm Event
</button>

And the WebForms Core server code connects them:

form.SetWasmEvent("WasmEvent", HtmlEvent.OnClick, WasmLanguage.CSharpMediator, WasmPath, "MyClass.SetData", [...]);

The application logic remains in C#.

WebForms Core 2.1

WebForms Core 2.1, or simply WFC, is coming soon.

This release expands the possibilities of WebForms Core by allowing WebAssembly methods to participate more deeply in the WebForms Core execution model.

The .NET WebCIL scenario is particularly interesting because developers can write C# methods such as:

[JSExport]
public static string SetData(...)

and use the existing WebForms Core API inside those methods.

This means that the same WebForms Core command model can be used from:

Server-side C#
C# WebAssembly
Native WebAssembly modules
Other WASM-capable languages

while the browser continues to use the WebForms Core client engine (WebFormsJS).

Final Result

This example demonstrates a new direction for WebForms Core:

C# WebAssembly can become an execution layer for WebForms Core rather than simply a replacement for JavaScript.

The architecture can be summarized as:

              WebForms Core
                    │
        ┌───────────┴───────────┐
        │                       │
     Server                 WebAssembly
        │                       │
   WebForms.cs               C# / WASM
        │                       │
        └───────────┬───────────┘
                    ↓
          WebForms Core Commands
                    ↓
               Browser DOM

And perhaps the most interesting point is this:

WebAssembly does not have to replace the WebForms Core model. It can become another execution environment for it.

That opens the door to using high-performance compiled languages and .NET WebAssembly together with the declarative command architecture of WebForms Core.

WebForms Core 2.1 is coming soon!

WebForms Core vs Blazor WebAssembly

Compared with Blazor WebAssembly, this approach in WebForms Core is not intended to run a complete .NET application in the browser. Instead, it can invoke a specific C# method as a WASM capability and return its result to WebForms Core. In the example above, MyClass.Add, MyClass.SetData, and MyClass.GetHtml are executed only when they are actually needed. Therefore, the architecture is much closer to a WASM Function Runtime than to a WASM-based SPA. Furthermore, by using WebForms within the C# code, even UI modification logic can be defined directly inside the C# method, with its output then passed to the WebForms Core engine.

In contrast, Blazor WASM provides a complete programming model for building .NET user interfaces in the browser, with a significant portion of the application logic and required runtime running on the client. WebForms Core can take a different approach: HTML remains standard HTML, WebForms Core manages UI behavior, and WASM is used only when specific capabilities need to be executed. Therefore, the two are not necessarily direct competitors. Blazor WASM primarily focuses on running .NET applications in the browser through WebAssembly, whereas WebForms Core is not limited to WebAssembly and provides a broader architecture for developing and executing web behavior.

redb.Route: Control Bus for .NET routes: stop, restart and react to route events at runtime

rinat kozin — Wed, 26 Aug 2026 09:31:00 +0000

Manage routes at runtime by sending a message: start, stop, suspend, restart, plus a consumer that turns route lifecycle events into messages.

A running integration is not a static thing. A deploy needs to drain a queue and stop a route before the new build takes over. A downstream service falls over, and the route hammering it should back off instead of piling up retries. An operator needs to suspend one branch of the flow without restarting the whole process. Something fails at 3am, and the on-call dashboard should light up on its own, not because someone was tailing logs.

Apache Camel solved the operational half of this a long time ago with the Control Bus pattern: you manage routes by sending a message to a special endpoint, the same way you move any other message. redb.Route brings that pattern to .NET, with the Camel command set, and adds one thing Camel does not have: a consumer that turns route lifecycle events back into messages you can route.

So there are two directions here. Outbound: tell a route to start, stop, suspend, resume or restart. Inbound: subscribe to what routes are doing and react. Both are ordinary steps of a pipeline. Let us look at the code.

Control Bus in one minute

The component is registered out of the box, there is no package to add. Address it by URI or by the fluent DSL.

// Stop a route by id
.To("controlbus:route?routeId=orders&action=stop")

// Same thing, fluent
.ControlBus(ControlBusAction.Stop, "orders")

That is a producer step. When a message reaches it, the named route is stopped. Everything else is variations on the action and one consumer for events.

Manage a route by sending a message

The action is the verb. The full set mirrors Camel:

Action	Effect
`Start`	Start the route.
`Stop`	Stop the route (consumer removed, the route stays registered).
`Suspend`	Suspend the route.
`Resume`	Resume a stopped or suspended route.
`Restart`	Stop, then start after `restartDelay` (default 1000 ms).
`Status`	Report the route's status.
`Stats`	Report the route's statistics.
`Fail`	Stop the route and mark it failed.

In the fluent form the action is an enum; as a URI it is the action query parameter.

using redb.Route.ControlBus;

.ControlBus(ControlBusAction.Suspend, "payments")
.ControlBus(ControlBusAction.Restart, "orders", async: true)   // fire-and-forget

// URI equivalents
.To("controlbus:route?routeId=payments&action=suspend")
.To("controlbus:route?routeId=orders&action=restart&async=true")

Because it is a normal route step, the control action can be the tail of any pipeline. A timer that suspends a batch route outside business hours. A webhook that restarts a route on a config change. A choice branch that stops a consumer when a poison message is seen. You are not calling a management API from the outside; you are routing a message, with all the same retries, error handling and observability as the rest of the flow.

A route can manage itself

Pass current as the route id and the action targets the route that is sending the message. This is how a route reacts to its own condition.

From("kafka://orders")
    .Process(CheckHealth)
    .Choice()
        .When(e => e.In.GetHeader<bool>("downstreamDown"))
            .ControlBus(ControlBusAction.Suspend, "current")   // back off, stop consuming
    .End();

A route that detects its downstream is unhealthy suspends itself instead of spinning through failures. Something external, a timer or an operator message, resumes it later.

The part Camel does not have: react to route events

This is the direction that is usually missing. In Camel the Control Bus is producer-only: you send commands, you do not subscribe to what happens. redb.Route adds controlbus:notify, a consumer that emits route and context lifecycle events as messages. You put it on the From side and route the events anywhere.

From("controlbus:notify")
    .Process(e =>
    {
        var evt   = e.In.GetHeader<string>(ControlBusHeaders.Event);    // RouteStarted, RouteStopped, RouteErrored, ...
        var route = e.In.GetHeader<string>(ControlBusHeaders.RouteId);
        var when  = e.In.GetHeader<DateTimeOffset>(ControlBusHeaders.Timestamp);
    })
    .To("kafka://route-events");

The events cover the lifecycle of routes and of the context itself: RouteStarted, RouteStopped, RouteSuspending, RouteErrored, ContextStarting, ContextStarted, ContextStopping, ContextStopped, ExchangeTimedOut. Each message carries the details as headers: the event name, the affected route id, a timestamp, and where relevant the error, the exchange id and the elapsed time.

Filter to what you care about with the events and routeId parameters:

// Only failures and stops, only for the orders route
From("controlbus:notify?events=RouteErrored,RouteStopped&routeId=orders")
    .To("slack://alerts");

Now the interesting part is that both directions compose. Events on the way in, commands on the way out, in one route: this is a self-healing loop with no external control plane.

From("controlbus:notify?events=RouteErrored")
    .Process(e => e.In.SetHeader("failed", e.In.GetHeader<string>(ControlBusHeaders.RouteId)))
    .Delay(TimeSpan.FromSeconds(30))
    .ControlBus(ControlBusAction.Restart, "current");   // or the captured route id

An errored route emits an event, a route consumes it, waits, and restarts the offender. The supervision logic is a pipeline, visible and testable like any other, not a hardcoded policy buried in the engine.

What this replaces

Without a Control Bus, runtime route management is a pile of one-off plumbing. A custom admin controller that reaches into the engine to stop a route. A BackgroundService that polls a flag table to know when to pause. A logging appender wired to an alerting SDK so someone hears about a failure. Each is a separate mechanism, with its own lifecycle, its own tests, its own way of being wrong.

The Control Bus turns all of that into routing. Management commands are messages To an endpoint. Lifecycle events are messages From an endpoint. They go through the same DSL, the same error handling, the same OpenTelemetry traces as your business flows, and they land in the same place your team already looks.

Zero-downtime deploys: suspend and drain a route on a signal, flip, resume.
Backpressure and circuit-breaking at the route level: a route suspends itself when its downstream is unhealthy.
Operational events as data: pipe RouteErrored and RouteStopped into Kafka, Slack, a metrics sink, an incident tool, an audit log.
Self-healing: notify in, restart out, in one small route.

The same control from a dashboard: redb.Tsak

Everything above is the programmatic face: a message drives a route's lifecycle. There is an operational face too. redb.Tsak, the runtime that hosts your routes, exposes the same route and context lifecycle in a dashboard, so an operator can start, stop, suspend or resume a route, and manage whole contexts, live, without writing a route or shipping a deploy. One capability, two entry points: a message from inside a flow, or a click from outside it, over the same engine.

Camel parity, and beyond

If you come from Camel, the command side is familiar: controlbus:route with routeId and action, plus controlbus:language for expression-based control, producer-only, the standard verbs. redb.Route matches that command set. The controlbus:notify consumer is the addition: Camel gives you EventNotifier as an SPI you implement in Java and register; redb.Route gives you the same information as a first-class endpoint you route from, no interface to implement, no wiring, just From("controlbus:notify").

FAQ

Is it a separate package? No. Control Bus is part of core redb.Route and is registered out of the box. Nothing to install.

Does stopping a route remove it? No. Stop and Suspend remove the consumer but keep the route registered, so Resume or Start brings it back. Fail stops it and marks it errored.

Can a route control another route, not just itself? Yes. Pass the target route id instead of current.

What events are available? Route lifecycle (RouteStarted, RouteStopped, RouteSuspending, RouteErrored), context lifecycle (ContextStarting through ContextStopped), and ExchangeTimedOut. Filter with events= and routeId=.

Is the command synchronous? By default yes; pass async=true (or async: true in the DSL) for fire-and-forget, which also avoids a route trying to stop itself synchronously mid-exchange.

Where it lives

Control Bus ships inside redb.Route on NuGet; the DSL and the controlbus:notify event set are in the documentation. It is one of the 30+ EIP patterns in the framework, and like the rest it is a step of a route: the same From → … → To, the same observability. The difference is that the message it carries is a route telling you what it just did, or you telling a route what to do next.

If this was useful — a ⭐ on GitHub helps others find it.

More of my writing: redbase.app/articles, and on dev.to.

NET Framework Essentials: Web Development Simplified

Sahil Khurana — Wed, 26 Aug 2026 09:20:32 +0000

Your backend framework will outlive your current team. Choose one that the next team can still navigate — here's why .NET has been that framework for Netflix, GitHub, and Stack Overflow for over two decades.

Summary

Twenty-three years. That's how long .NET has been running in production. Most frameworks from that era got abandoned, forked beyond recognition, or replaced entirely — .NET kept showing up. Netflix still uses it. GitHub uses it. Stack Overflow, which has probably saved more developer careers than any single resource on the internet, runs on ASP.NET. None of these teams are using it out of inertia. They're using it because it works under conditions that expose every weakness in a poorly designed system. This article gets into how .NET actually works, what it gives teams day-to-day, and whether it makes sense for what you're building now.

Key Takeaways:

One codebase, five platforms — Windows, macOS, Linux, Android, iOS. No rewrites, no platform-specific forks.
Three languages, one project — C#, F#, and Visual Basic coexist without forcing a rewrite.
The performance tooling ships with it — JIT compiler, AOT compiler, CLR memory management, Garbage Collector. All out of the box.

Why Is .NET Still Around?

Honestly, this question is worth sitting with for a second — because in software, most things don't survive twenty years. They solve the problem of the moment, get widely adopted before anyone finds the sharp edges, and then get quietly replaced when something newer comes along and the migration pain seems worth it.

.NET didn't go that way.

Some of that is Microsoft backing — resources, long-term support commitments, a developer community that doesn't dissolve when priorities shift. But backing alone doesn't explain it. Plenty of well-resourced frameworks have died. What actually kept .NET alive is that the foundational architecture held up. The cross-platform capability wasn't duct-taped on in 2020 because everyone suddenly cared about Linux. It was in the compiler design from early on. When .NET Core went open-source and the licensing fees went away, it wasn't a rebrand — it was the framework catching up to how people already wanted to use it.

There's a second reason, quieter but just as important. Code gets handed off. The engineers who built version one are almost never the engineers maintaining version four. Comments get stale. Context lives in heads that leave the company. The frameworks that age well are the ones that stay readable, stay consistent, and don't require tribal knowledge to navigate after three years of turnover. .NET handles that transition better than most.

How .NET Works — No Documentation Filler

Here's the actual sequence, stripped of the marketing layer.

Developer opens Visual Studio or VS Code. Writes in C#, F#, or Visual Basic — whichever the team is using. The compiler takes that code and converts it into Common Intermediate Language (CIL). This isn't Windows-specific code or Linux-specific code. It's a neutral middle format — doesn't care about the OS — and it gets stored in an assembly file.

User runs the app. The Common Language Runtime (CLR) takes over as the execution engine. It passes the CIL to a Just-in-Time (JIT) compiler, which converts it into actual machine code for whatever OS is running at that exact moment.

That's the mechanism. Same assembly, different output depending on the environment. No separate Windows build. No Linux-specific rewrite. One file that works across platforms because the conversion happens at runtime, not at compile time.

💡 Pro tip: First time you watch a codebase that lived exclusively on Windows servers for years boot cleanly inside a Linux container, the pipeline earns a whole new level of respect.

There's also an Ahead-of-Time (AOT) compiler — does the conversion before runtime instead of during. Better startup speed, lower memory footprint at launch. Some deployments need it; others don't. Both compilers are included, no additional configuration required.

Under all of this, the Garbage Collector runs continuously, clearing unused objects from memory. The CLR manages allocation and deallocation. Developers don't handle it manually. That removes an entire category of bugs — the memory-related ones that tend to show up in production at the worst possible time — not through careful coding, but through the framework just doing it automatically.

Here's what a minimal .NET 6 web app entry point looks like:

// Program.cs — minimal hosting model (.NET 6+)
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello from .NET");

app.Run();

Same file. Runs on Windows, Linux, and macOS without a single change.

What Developers Actually Get

Skip the bullet-point feature list for a second, because that format lies through omission — it makes everything look equally important, and it isn't.

The standard library depth is the thing that matters most on a real project. File handling, networking, security, database access — .NET covers it. Teams aren't patching together five community packages, each with independent release cycles and varying levels of maintainer attention. At any real scale, every third-party dependency is a potential vulnerability and a future upgrade headache. Fewer dependencies isn't just cleaner — it's safer.

ASP.NET for web, MAUI for mobile, Entity Framework for database management — these live in the same ecosystem. They share conventions, share documentation, and work together without needing compatibility shims. When something breaks at the seam between the web layer and the data layer, there's one system to debug. Teams who've spent weeks chasing down breakage between mismatched third-party libraries know exactly why that matters.

Language flexibility sounds minor until you're three years into a project and inheriting a module written in F# by a contractor who's long gone. .NET lets C# and F# coexist in the same project — no forced rewrite, no language migration before you can touch the code. It's not a feature you use daily. It's a pressure valve you're glad exists when you need it.

Security defaults aren't opt-in. Authentication, encryption, access control — built in and maintained by Microsoft's security team, not left to per-developer implementation. Combined with CLR memory management, the framework actively closes the kinds of attack surfaces that manual implementations routinely leave cracked open.

Azure integration is genuinely worth something for enterprise teams already in the Microsoft world. SQL Server, Microsoft 365, Power BI — same vendor, same support chain. It just fits. No custom connectors, no compatibility hacks, no extra configuration layer sitting between the app and the infrastructure.

.NET Core and .NET 5+ are open-source. Zero licensing fees. Across a team of ten people on a three-year project, that's a real line item — the kind that shows up in engineering budget reviews and doesn't get questioned.

What Gets Built on .NET

Enterprise apps are the obvious fit. Complex security requirements, multi-platform deployment needs, long timelines, existing Microsoft infrastructure — .NET was built for exactly that profile and the production record backs it up.

Web apps and REST APIs through ASP.NET are well-trodden. Stack Overflow processes millions of requests through ASP.NET under load conditions that surface architectural problems fast. It holds.

Windows desktop software still largely runs on WPF and WinForms. Mobile through MAUI — which replaced Xamarin — lets a single codebase target both Android and iOS. Cloud-first work fits naturally on Azure, though .NET runs on AWS and GCP too. Azure is just the path with the least friction.

Microservices, internal tooling, cloud-native applications — all reasonable use cases. The framework is broad enough that it's genuinely hard to name a common app type it doesn't handle.

Should You Use It?

Depends entirely on the context.

Enterprise build, long timeline, Microsoft infrastructure already in place, security requirements with actual teeth — yes, probably. .NET was designed for that profile. The fit is real.

Small team, Python or Node.js fluency across the board, project scope that doesn't need what .NET specifically does well — switching creates friction without proportional benefit. That's not a criticism of the framework. It's just a mismatch.

The thing worth pushing back on is choosing frameworks based on the demo. Demos are fast, clean, and don't have to survive a team changing twice and a product pivot. The real question is what it looks like to maintain the codebase in three years. On that measure, .NET has a long track record that newer options simply don't have yet.

Final Thoughts: Is .NET the Right Call for Your Project?

Two decades in production is a real signal. Not a marketing claim, not a vanity metric — actual evidence that the thing holds up when conditions change. New platforms arrived. Deployment models shifted. Team expectations around open-source changed completely. .NET adjusted each time without breaking what was already working.

What you build on top of it inherits that history. Not glamorous. Probably not the choice that gets applause in a tech talk. But solid, well-supported, and unlikely to become someone else's problem to unwind in two years.

If you want to talk through whether it fits what you're working on, the Innostax team has been in this space long enough to give you a straight answer.

Sahil Khurana - Chief Technology Officer at Innostax

Innostax is a global software consulting and custom development company helping growth-stage startups, scaleups, and enterprises build reliable, scalable digital products. Founded in 2014, headquartered in Framingham, Massachusetts.