Coder Legion - Recent posts tagged csharp

A JSON-RPC Library With No Method Registration: How Does It Decide What Can Be Called?

Thu, 29 Oct 2026 16:15:05 +0000

JSON-RPC 2.0 is a small specification: the client sends {"jsonrpc":"2.0","method":"...","params":{...},"id":1}, and the server answers with a result or an error. REST makes you decide on routes, HTTP verbs and status codes; JSON-RPC only cares about which method to call and with what parameters. For an API where you own both the front end and the back end, that is pleasant to work with.

Polhem.JsonRpc is a set of .NET packages for JSON-RPC 2.0: a transport-independent server, an ASP.NET Core endpoint and a client, built on System.Text.Json alone. It started as the API layer of the Polhem framework. I have now extracted it into standalone packages that do not depend on the framework, so other projects can reference them directly. The source is on GitHub under the MIT license, and the packages are on NuGet.

1️⃣ What it covers

Full JSON-RPC 2.0: ordinary calls, notifications (calls that expect no response), and batches (several calls in one message). An id can be a string, an integer or null.
A transport-independent server: the dispatcher (the part that finds and runs the method) knows nothing about HTTP. The ASP.NET Core endpoint is a separate package.
A client: an HTTP transport, batches, notifications, and interceptors that can rewrite the parameters and result of each call.
Optional payload encryption: the parameters and result go into an envelope that can be compressed and encrypted, and replayed calls can be rejected.

It is split into several NuGet packages, so an application references only what it needs:

Package	Use
Polhem.JsonRpc	Message types, error codes and the transport abstraction shared by the server and the client
Polhem.JsonRpc.Server	The dispatcher: method resolution, parameter binding and filters
Polhem.JsonRpc.AspNetCore	The ASP.NET Core endpoint, `MapJsonRpc`
Polhem.JsonRpc.Client	The client, `JsonRpcConnector`
Polhem.JsonRpc.Payload	Optional: the payload envelope, compression, encryption and replay protection
Polhem.JsonRpc.Payload.Client	Optional: a client that seals the parameters and opens the result of every call
Polhem.JsonRpc.Payload.Server	Optional: opens the envelope and checks for replays on the server

The server references Polhem.JsonRpc.AspNetCore, and the client references only Polhem.JsonRpc.Client. The split keeps a client, whether a desktop app or a mobile app, from pulling in ASP.NET Core and the reflection-based dispatcher.

Native AOT compiles an app to native code at publish time, so nothing can rely on reflection at run time; iOS and WebAssembly both need it. The shared package, the client and the payload packages are marked AOT-compatible, and CI publishes a test program with Native AOT and runs it. The server package finds methods by reflection, so it does not support AOT. The target framework is net10.0.

2️⃣ Getting started

ASP.NET Core server (Minimal API)

The server uses ASP.NET Core Minimal APIs (endpoints mapped directly in Program.cs with MapXxx, without MVC controllers). MapJsonRpc creates a POST endpoint at the given path, and every JSON-RPC call comes in through it. AddControllers is not needed.

Program.cs needs three things: register the object factory, register the JSON-RPC services, and map the endpoint.

using Polhem.JsonRpc.AspNetCore;
using Polhem.JsonRpc.Server;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IJsonRpcObjectFactory, AppObjectFactory>();
builder.Services.AddJsonRpcServer();

var app = builder.Build();
app.MapJsonRpc("/api");
await app.RunAsync();

AddJsonRpcServer takes two sets of options. The first configures the server itself, such as filters, the method policy, the batch limit and serializer options. The second configures the HTTP endpoint, such as the request body size limit and which HTTP status code an error returns. Leave them out and the defaults apply.

builder.Services.AddJsonRpcServer(
    options =>
    {
        options.MaxBatchSize = 50;
        options.Filters.Add(new ApiKeyFilter(apiKey)); // see section 5
    },
    http => http.MaxRequestBodySize = 1024 * 1024);

MapJsonRpc returns the same thing as any other Minimal API endpoint, so authorization, CORS and rate limiting chain on the usual way, for example app.MapJsonRpc("/api").RequireAuthorization();.

The object factory and the class that handles the calls:

public sealed class AppObjectFactory : IJsonRpcObjectFactory
{
    public object? CreateObject(string progId, JsonRpcRequestContext context) => progId switch
    {
        "Calculator" => new Calculator(),
        _ => null,
    };
}

public sealed class Calculator
{
    public AddResponse Add(AddRequest request) => new() { Sum = request.A + request.B };
}

Client

using var http = new HttpClient { BaseAddress = new Uri("http://localhost:5080/api") };
var rpc = new JsonRpcConnector(new HttpTransport(http));

var added = await rpc.InvokeAsync<AddResponse>("Calculator.Add", new AddRequest { A = 1, B = 2 });

That is enough to call Calculator.Add. Note that the server has no AddMethod or similar registration, and Calculator carries no attribute.

3️⃣ With no registration, which methods can be called?

Skipping registration is convenient, but it raises a worry: if one day I add a public method to the class for internal use, can it be called from the network too? When the server receives Calculator.Add, it runs the following checks in order.

Name format. The method name must be ProgId.Action. A ProgId (program identifier) may contain letters, digits, underscores and hyphens; an action letters, digits and underscores; each at most 64 characters. A malformed name is rejected before any lookup.

The application decides the object. The ProgId is passed to your implementation of IJsonRpcObjectFactory.CreateObject, which decides which object to create; returning null means the ProgId is unknown. The packages keep no registry of names, so which ProgIds exist is entirely up to the factory. After the call, the object is passed to ReleaseObjectAsync to be released.

Method signature. An action maps only to a public, non-generic instance method with exactly one parameter. Static methods, property accessors and methods declared by object do not count. If two or more methods with the same name qualify, the server does not pick one; it treats the method as not found.

Naming convention. The parameter type must be named {Action}Request, and the return type (or the result type of Task<T> or ValueTask<T>) must be named {Action}Response. Add takes an AddRequest and returns an AddResponse. This is the default method policy; any public method that does not follow it is treated as nonexistent and answered with -32601 Method not found. An internal helper method that does not follow this naming cannot be called from outside.

The rule can be replaced through JsonRpcServerOptions.MethodPolicy. The Polhem framework replaces it with one that reads its own access-control attribute.

Policy before filters. The method policy runs before every filter, so filters such as authorization checks or decryption only ever see calls that are allowed to run.

Only after these checks are the params bound. params must be a JSON object, deserialized into the request class with camelCase names by default; missing params or an array (positional parameters) are answered with -32602 Invalid params. To return a custom error, a method throws JsonRpcErrorException; any other exception is answered with -32603 Internal error, and the exception message is not sent to the client.

4️⃣ The client

An error returned by the server becomes a JsonRpcErrorException, which carries the error code and message:

try
{
    await rpc.InvokeAsync<DivideResponse>("Calculator.Divide", new DivideRequest { Dividend = 1, Divisor = 0 });
}
catch (JsonRpcErrorException ex)
{
    Console.WriteLine($"Error {ex.Code}: {ex.Message}");
}

Notifications and batches:

// The server runs it but does not respond.
await rpc.NotifyAsync("Calculator.Log", new LogRequest { Message = "Hello" });

// Two calls sent in the same message.
var batch = rpc.CreateBatch();
var first = batch.Add<AddResponse>("Calculator.Add", new AddRequest { A = 2, B = 3 });
var second = batch.Add<AddResponse>("Calculator.Add", new AddRequest { A = 4, B = 5 });
await batch.SendAsync();
Console.WriteLine($"{(await first)!.Sum}, {(await second)!.Sum}");

The request and response classes usually live in a project shared by both sides, which is how the samples in the repo are arranged.

5️⃣ Extension points: filters and interceptors

A server filter wraps every call. It can reject the call, rewrite the parameters before the method runs, and rewrite the result afterwards. For example, checking an API key:

public sealed class ApiKeyFilter(string expectedKey) : IJsonRpcFilter
{
    public ValueTask InvokeAsync(JsonRpcRequestContext context, JsonRpcFilterDelegate next)
    {
        context.Transport.Headers.TryGetValue("X-Api-Key", out var key);
        if (!CryptographicOperations.FixedTimeEquals(
                Encoding.UTF8.GetBytes(key ?? ""), Encoding.UTF8.GetBytes(expectedKey)))
        {
            throw new JsonRpcErrorException(-32001, "Unauthorized");
        }
        return next(context);
    }
}

builder.Services.AddJsonRpcServer(options => options.Filters.Add(new ApiKeyFilter(apiKey)));

To add an HTTP header on the client, use HttpClient's own DelegatingHandler; the packages add no layer of their own. To rewrite the parameters and result of every call, add an IJsonRpcClientInterceptor.

The Polhem framework plugs its sessions and authorization checks into these extension points (the object factory, the method policy and filters). None of that logic is in the packages themselves.

6️⃣ Encrypted payloads

HTTPS protects the connection. If the parameters and results also need end-to-end protection, or a call must not run a second time when it is resent, add the optional payload packages.

They put params and result into an envelope with three formats: plain JSON, encoded (serialized, then gzip-compressed), and encrypted (AES-256-CBC with HMAC-SHA256, encrypt-then-MAC). A frame carrying a timestamp and a sequence number can also be put in front of the content, so the server can reject expired or repeated requests; that is the replay protection.

// Server: the application's policy decides the keys and which methods must be encrypted or replay-protected.
builder.Services.AddJsonRpcServer(options => options.UsePayload(payloadOptions, new MyPayloadPolicy()));

// Client: called the same way as an ordinary call; each call seals its parameters and opens its result.
var rpc = new PayloadConnector(connector, new PayloadProcessor(payloadOptions),
    new PayloadConnectorOptions { KeyProvider = () => sessionKey });
var added = await rpc.InvokeAsync<AddResponse>("Calculator.Add", request);

A few more security details:

The HMAC is compared in constant time and verified before anything is decrypted.
The HMAC covers the method name and the direction, so an intercepted call cannot be redirected to another method, and a response cannot be sent back as a request.
A method can require a minimum format; a request in a lower format is rejected before any key is asked for.

How keys are negotiated (exchanged after sign-in, provisioned in advance, and so on) is outside the packages and left to the application.

7️⃣ How it differs from common libraries

There are quite a few JSON-RPC libraries for .NET; here are two common ones for comparison. The version in each column header is the latest stable release on NuGet as of October 2026, and the details come from that release's documentation and NuGet dependency list. Later releases may differ.

	StreamJsonRpc 2.25.29	Tochka.JsonRpc 7.4.1	Polhem.JsonRpc 1.2.0
JSON library	Newtonsoft.Json by default, switchable to System.Text.Json; the package still depends on Newtonsoft.Json and MessagePack	System.Text.Json	System.Text.Json, with no other dependencies
Transport model	Full duplex over a Stream, WebSocket or Pipe	HTTP on ASP.NET Core MVC	HTTP request and response on ASP.NET Core Minimal APIs
Client	Yes, with proxies generated from interfaces	Yes	Yes
How methods are registered	`AddLocalRpcTarget` adds a target object whose public methods become callable	Controllers that inherit `JsonRpcControllerBase`; each action is a method	No registration; found by `ProgId.Action` and the naming convention
Native AOT	Partially supported, within the limits its documentation lists	Tied to MVC, not supported	The shared package, the client and the payload packages support it; the server does not
Good fit	Two-way communication, such as Visual Studio extensions or LSP	You already use MVC and want to keep writing controllers	An API where you own both ends, possibly with desktop or mobile clients

StreamJsonRpc is the most complete, with cancellation, progress reporting and server-to-client calls, but it is designed for streams and full duplex; turning it into an HTTP request/response API means building the endpoint yourself.

Tochka.JsonRpc is the closest in scope to Polhem.JsonRpc. It builds on MVC controllers, so MVC filters and model binding work as they are, at the cost of sharing MVC's lack of AOT support.

Polhem.JsonRpc goes in a different direction: it trades a fixed call shape for "no registration" and "an API that can evolve", as the next section explains.

8️⃣ Design trade-offs

The fixed call shape is there so the API can evolve. The ProgId.Action name, one request class and one response class are a deliberate restriction. When a member is added to a request or response class, a member an older front end does not send binds to its default on the server, and a result member an older front end does not know is simply skipped when read. Old and new front ends call the same method, with no v1 and v2 endpoints to maintain. Positional parameters cannot do this: add, remove or reorder one parameter and every caller has to change.

Defaults follow the specification. The internal error code is -32603, a response carries only jsonrpc, result or error, and id, and id is always written, as null when it cannot be determined. The Polhem framework's original response format differed from the specification in places; when the packages were extracted, it was the framework that changed to follow the specification, not the packages that bent to the old format.

The reasoning behind each decision is recorded as ADRs (Architecture Decision Records) in the repo's maintainers/adr/, and the security design is summarized in docs/security.md.

✅ Wrapping up

Install the server and client packages:

dotnet add package Polhem.JsonRpc.AspNetCore
dotnet add package Polhem.JsonRpc.Client

The repo includes samples: an ASP.NET Core Minimal API server, a console client (ordinary calls, error handling, notifications and batches), and a server and client using encrypted payloads.

These packages do convention-based JSON-RPC, not general-purpose JSON-RPC. Protocols whose method names and parameters are defined by someone else, such as the Language Server Protocol, MCP or an Ethereum node's API (names like textDocument/didOpen and eth_call with positional parameters), cannot be implemented with them; StreamJsonRpc or the MCP C# SDK fit those better. Nor do they offer a full-duplex connection where the server calls the client: one call is one HTTP request and its response.

If you own both ends of your API, want JSON-RPC that relies on System.Text.Json alone, or have clients that run as desktop or mobile apps, give it a try. Feedback, issues and pull requests are welcome.

From Anemic Models to Rich Domain Models, DDD Base Entities, and C# Records

Tue, 27 Oct 2026 10:51:17 +0000

When building enterprise applications in C#, a common architectural trap is writing procedural code disguised as object-oriented code. This usually happens when we rely entirely on anemic data bags (public get; set; DTOs) for business logic, forcing our application services to manage all validation and state changes manually.

In this guide, we will tie together Object-Oriented Programming (OOP), the Single Responsibility Principle (SRP), Domain-Driven Design (DDD) Entity base classes, C# Records for Value Objects, Combining Interfaces & Abstract Classes, EF Core Persistence, and Unit Testing into a complete, publication-ready reference.

Part 1: The Anti-Pattern (Anemic Models & DTO Misuse)

An anemic model treats classes as passive data structures with zero behavior. When every model exposes public setters, any part of the codebase can mutate state arbitrarily, bypassing business rules.

The Problematic Approach

// 1. The Anemic Entity (Just a data bag)
public class OrderDto
{
    public Guid Id { get; set; }
    public string CustomerEmail { get; set; }
    public decimal TotalAmount { get; set; }
    public string Status { get; set; } // Can be set to anything from anywhere!
}

// 2. The God Service handling all procedural logic
public class OrderService
{
    public void ProcessOrder(OrderDto order)
    {
        // Business logic scattered in services instead of living in the model
        if (order.TotalAmount <= 0) throw new Exception("Invalid amount");
        order.Status = "Processed"; // Direct mutation without invariant checks
    }
}

Why Anemic Models Fail

Repeated Validation Checks: Since anemic models can't check their own rules, every service or controller writes the same validation code over and over. If a developer forgets one check, a business rule breaks silently.
Unprotected Data (Broken States): Public setters mean code can accidentally create broken data—like a negative order total or an incomplete order marked as completed—which then gets saved to the database.
Hard-to-Fix Rules ("Shotgun Surgery"): When business rules change, you have to hunt through 10 different files and controllers to update identical if statements.

Part 2: DDD Foundation — Entity Base Class & C# Records

In Domain-Driven Design, Entities are defined by their unique identity rather than their attributes, while Value Objects (idiomatically implemented using C# records) are defined entirely by their structural values and are strictly immutable.

1. DDD Entity Base Class

Notice how EqualityComparer<TId> is used below to robustly handle generic identifier comparisons across different types (Guid, int, string, etc.) while ensuring unpersisted entities do not falsely equal each other:

public abstract class Entity<TId>
{
    public TId Id { get; protected set; }

    public override bool Equals(object? obj)
    {
        if (obj is not Entity<TId> other) return false;
        if (ReferenceEquals(this, other)) return true;
        if (GetType() != other.GetType()) return false;

    if (EqualityComparer<TId>.Default.Equals(Id, default!) || 
        EqualityComparer<TId>.Default.Equals(other.Id, default!))
        return false;


        return EqualityComparer<TId>.Default.Equals(Id, other.Id);
    }

public override int GetHashCode() => (GetType().ToString() + Id).GetHashCode();

public static bool operator ==(Entity<TId>? a, Entity<TId>? b) => a?.Equals(b) ?? b is null;
public static bool operator !=(Entity<TId>? a, Entity<TId>? b) => !(a == b);

2. C# Records for Value Objects

Using record gives us value-based structural equality out-of-the-box and immutability by default (init setters).

public record EmailAddress
{
    public string Value { get; init; }

    public EmailAddress(string value)
    {
        if (string.IsNullOrWhiteSpace(value) || !value.Contains("@"))
            throw new ArgumentException("Invalid email format.");
        Value = value;
    }
}

Part 3: Combining Interfaces, Abstract Classes, and DDD Entities

Now we structure our customer hierarchy by inheriting from our DDD Entity<Guid>, implementing our ICustomer interface, and using our EmailAddress value object.

// 1. The Interface defines the full contract
public interface ICustomer
{
    Guid Id { get; }
    EmailAddress Email { get; }
    decimal TotalSpent { get; }
    
    decimal CalculateDiscount(decimal orderAmount);
    void RecordPurchase(decimal amount);
}

// 2. The Abstract Base Class inherits from DDD Entity and implements ICustomer
public abstract class CustomerBase : Entity<Guid>, ICustomer
{
    public EmailAddress Email { get; private set; }
    public decimal TotalSpent { get; private set; }

    protected CustomerBase(Guid id, EmailAddress email)
    {
        Id = id;
        Email = email ?? throw new ArgumentNullException(nameof(email));
        TotalSpent = 0m;
    }

    public void RecordPurchase(decimal amount)
    {
        if (amount <= 0) throw new ArgumentException("Purchase amount must be positive.");
        TotalSpent += amount;
    }

    public abstract decimal CalculateDiscount(decimal orderAmount);
}

// 3. Concrete Implementations
public class RegularCustomer : CustomerBase
{
    public RegularCustomer(Guid id, EmailAddress email) : base(id, email) { }

    public override decimal CalculateDiscount(decimal orderAmount) => 0m;
}

public class VipCustomer : CustomerBase
{
    public decimal CreditLimit { get; private set; }

    public VipCustomer(Guid id, EmailAddress email, decimal creditLimit) : base(id, email)
    {
        if (creditLimit < 0) throw new ArgumentException("Credit limit cannot be negative.");
        CreditLimit = creditLimit;
    }

    public override decimal CalculateDiscount(decimal orderAmount) => orderAmount * 0.10m;
}

Part 4: The Rich Domain Model (`Order`)

Our Order inherits from Entity<Guid>, enforces business invariants, and coordinates with ICustomer.

public class Order : Entity<Guid>
{
    public ICustomer Customer { get; }
    public decimal TotalAmount { get; private set; }
    public OrderStatus Status { get; private set; }

    public Order(Guid id, ICustomer customer, decimal initialAmount)
    {
        Id = id;
        Customer = customer ?? throw new ArgumentNullException(nameof(customer));
        
        if (initialAmount <= 0)
            throw new ArgumentException("Order amount must be greater than zero.");

        TotalAmount = initialAmount;
        Status = OrderStatus.Draft;

        ApplyCustomerDiscount();
    }

    private void ApplyCustomerDiscount()
    {
        decimal discount = Customer.CalculateDiscount(TotalAmount);
        TotalAmount -= discount;
    }

    public void AddItem(decimal itemPrice)
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException("Cannot modify an order after it has been submitted.");

        TotalAmount += itemPrice;
    }

    public void SubmitPayment()
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException("Order is already processed.");

        Status = OrderStatus.Submitted;
    }
}

public enum OrderStatus { Draft, Submitted, Completed }

Part 5: Orchestrating with SRP and Dependency Injection

Our application service (OrderProcessor) focuses purely on coordination (following the Single Responsibility Principle).

public class OrderProcessor
{
    private readonly IOrderRepository _repository;
    private readonly IPaymentGateway _paymentGateway;
    private readonly IEmailNotifier _notifier;
    private readonly ILogger<OrderProcessor> _logger;

    public OrderProcessor(
        IOrderRepository repository,
        IPaymentGateway paymentGateway,
        IEmailNotifier notifier,
        ILogger<OrderProcessor> logger)
    {
        _repository = repository;
        _paymentGateway = paymentGateway;
        _notifier = notifier;
        _logger = logger;
    }

    public async Task ProcessAsync(Guid orderId)
    {
        var order = await _repository.GetByIdAsync(orderId);
        if (order == null) throw new KeyNotFoundException("Order not found.");

        order.SubmitPayment();

        if (!await _paymentGateway.ChargeAsync(order.TotalAmount))
        {
            throw new InvalidOperationException("Payment failed.");
        }

        order.Customer.RecordPurchase(order.TotalAmount);

        await _repository.SaveAsync(order);
        await _notifier.SendConfirmationAsync(order.Customer.Email.Value);

        _logger.LogInformation("Successfully processed order {OrderId}", order.Id);
    }
}

Part 6: Persistence with EF Core (Mapping Records & TPH)

Using EF Core Entity configurations to map our DDD entities, value objects (records via owned types), and inheritance hierarchy.

public class AppDbContext : DbContext
{
    public DbSet<CustomerBase> Customers => Set<CustomerBase>();
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Configure Customer Inheritance (TPH)

modelBuilder.Entity()

        .HasKey(c => c.Id);

    modelBuilder.Entity<CustomerBase>()
        .OwnsOne(c => c.Email, email =>
        {
            email.Property(e => e.Value).HasColumnName("Email").IsRequired();
        });

    modelBuilder.Entity<CustomerBase>()
        .HasDiscriminator<string>("CustomerType")
        .HasValue<RegularCustomer>("Regular")
        .HasValue<VipCustomer>("VIP");

    // Configure Order Entity
    modelBuilder.Entity<Order>()
        .HasKey(o => o.Id);

    modelBuilder.Entity<Order>()
        .HasOne(o => o.Customer)
        .WithMany()
        .HasForeignKey("CustomerId");

}
}

Part 7: Unit Testing with Records & Entities

public class DomainTests
{
    [Fact]
    public void VipCustomer_WithValidData_CalculatesDiscountAndTracksSpend()
    {
        var email = new EmailAddress("*Emails are not allowed*");
        ICustomer customer = new VipCustomer(Guid.NewGuid(), email, 5000.00m);
        var order = new Order(Guid.NewGuid(), customer, 200.00m);

        // 200 - 10% = 180
        Assert.Equal(180.00m, order.TotalAmount);

        customer.RecordPurchase(order.TotalAmount);
        Assert.Equal(180.00m, customer.TotalSpent);
    }
}

References & Further Reading

Martin Fowler (2003): AnemicDomainModel — Read article.
Eric Evans (2003): Domain-Driven Design: Tackling Complexity in the Heart of Software — Addison-Wesley Professional.
Robert C. Martin (2017): Clean Architecture: A Craftsman's Guide to Software Structure and Design — Prentice Hall.

Tuesday Coding Tip 28 — (de)serializing JSON string enum in C#

Tue, 27 Oct 2026 09:59:00 +0000

Tuesday coding tips are super short posts about various tidbits mainly from C++, but also from other programming languages I use. You can also follow the #TuesdayCodingTips hashtag on Mastodon and Linkedin.

Last time I covered C# JSON serialization, I only showcased the Newtonsoft.Json library. This time, I will also show the System.Text.Json way.

You might want to (de)serialize enums as strings, rather than numeric values. Since C# does not support enums with an underlying type of string, you need to do some extra work. Namely, you have to annotate each value using the EnumMember annotation and then select the correct converter, once again using annotations.

using System.Runtime.Serialization;
using Newtonsoft.Json;
using Newtonsoft.Json.Converters;

public enum Mood
{
    [EnumMember(Value = "happy")]
    Happy,
    [EnumMember(Value = "sad")]
    Sad,
}

public class Object
{
    [JsonProperty("mood")]

    [JsonConverter(typeof(StringEnumConverter))]
    public Mood Mood { get; set; }
}

public static class Program
{
    public static void Main()
    {
        string json = JsonConvert.SerializeObject(new Object
        {
            Mood = Mood.Sad
        });

        Console.WriteLine(json);
        // {"mood":"sad"}
        Console.WriteLine(JsonConvert.DeserializeObject<Object>(json)!.Mood);
        // Sad
    }
}

However, System.Text.Json doesn’t support EnumMember annotations out of the box. It takes the literal name of the property instead. You can play with capitalization using options object, but that’s it. Or you can write your own converter. Or you can just use one of the dozen converters from the Internet that do the hard work for you.

using System.Runtime.Serialization;
using System.Text.Json.Serialization;

public enum Mood
{
    [EnumMember(Value = "happy")]
    Happy,
    [EnumMember(Value = "sad")]
    Sad,
}

public class Object
{
    [JsonPropertyName("mood")]
    // To use EnumMember annotations, install Macross.Json.Extensions nuget
    // and use a different converter
    // [JsonConverter(typeof(JsonStringEnumMemberConverter))]
    [JsonConverter(typeof(JsonStringEnumConverter))]
    public Mood Mood { get; set; }
}

public static class Program
{
    public static void Main()
    {
        Object obj = new()
        {
            Mood = Mood.Sad,
        };

        string json = System.Text.Json.JsonSerializer.Serialize(obj);
        Console.WriteLine(json);
        // {"mood":"Sad"}
        Console.WriteLine(System.Text.Json.JsonSerializer.Deserialize<Object>(json)!.Mood);
        // Sad
    }
}

A Query Window Is Not a Calendar Day

Mon, 26 Oct 2026 20:12:29 +0000

Software often uses broad time windows for good reasons. A dashboard may need recent history, work that is actionable now, and the next scheduled item. Fetching all of that in one bounded query can be efficient and easy to reason about.

The trouble begins when the retrieval window quietly becomes the business definition of “today.”

This is a small distinction with a very visible failure mode: shortly after midnight, yesterday’s missed item appears under today’s heading. The query is returning exactly what it was asked to return. The selection rule is wrong.

Retrieval and meaning are different jobs

Imagine a “Today” screen that loads items from several hours in the past through the next day. The look-back allows the screen to include work that recently closed or may still be open. The look-ahead allows it to show what comes next.

That range is a retrieval concern. It answers:

Which records could be relevant enough to inspect?

It does not answer:

Which record belongs to the user’s current calendar day?

If selection simply chooses the first item whose state is due or missed, a previous day’s missed item can win after midnight. If display text assumes every future item is later today, tomorrow morning can be described as though it were later tonight.

Both errors come from using temporal proximity as a substitute for calendar meaning.

Define “today” in the relevant time zone

Server time is rarely the correct authority for a human-facing day. UTC is excellent for storing instants and comparing elapsed time. It is not a user’s calendar.

The safer sequence is:

Read the current instant from an injected clock.
Convert it once into the time zone that owns the workflow.
Derive a local date from that value.
Use that date when classifying calendar-bound states.

Computing the value once matters. It keeps every decision in one request anchored to the same instant, including the unlikely case where execution crosses midnight.

The relevant time zone also needs to be explicit. It may belong to a person, site, account, or workflow. The correct choice is a domain decision, not an infrastructure default.

Preserve the exception that actually matters

A tempting fix is to discard every record whose local date is not today. That is neat and wrong when an actionable window crosses midnight.

Suppose a task opened before midnight and remains valid until shortly afterwards. A strict date filter would hide it at the exact moment it still needs attention.

This is where explicit domain rules beat blanket filtering:

missed and completed items count as current only when their local date is today;
a still-open item remains current while it is actionable, regardless of its start date;
a scheduled item on another day can still appear as next, but its wording names that day.

The rule is slightly longer because the product meaning is slightly richer. That extra branch is not accidental complexity. It records why two superficially similar records are treated differently.

Make wording part of correctness

Time bugs are not confined to sorting and filtering. Labels can encode false claims too.

“Later today” is only correct if the next item is on the same local day. “Between 08:00 and 09:00” may be ambiguous when viewed the night before. Adding “tomorrow” or a concrete day makes the model visible to the user.

That wording also gives tests a useful public outcome. A test can verify that the screen says tomorrow without reaching into a private helper or asserting a particular LINQ expression.

Test the boundary as a sequence

A single test at noon will not find this class of defect. The useful test moves a controllable clock through the state transition.

One focused integration scenario can prove three behaviours:

On the item’s own evening, the missed item is still classified as belonging to today.
The next day’s scheduled item is labelled explicitly as tomorrow.
After midnight, the old missed item no longer becomes the current card.

Using the real persistence provider is valuable when stored dates, generated occurrences, or query translation participate in the behaviour. The clock is the external boundary worth controlling; internal services do not need to be mocked if the public result proves the rule.

Also test a window that genuinely spans midnight. Without that case, a cleanup that filters everything by date can look correct while introducing a different regression.

The engineering trade-off

Explicit local-date classification costs a few things:

more branches than a simple state check;
a time-zone conversion at the application boundary;
boundary-focused tests and more deliberate copy.

In return, the system becomes predictable at the moment when implicit assumptions fail most often. Retrieval can remain broad for performance and completeness. Domain selection becomes precise. User-facing language reflects the same model.

The broader leadership lesson is to ask two questions whenever a time range appears in code:

Is this range finding candidates, or defining business membership?
Whose calendar gives words such as today, tomorrow, and missed their meaning?

Keeping those answers separate prevents an implementation convenience from becoming an accidental policy.

Practical checklist

When building a day-oriented view:

store and compare instants consistently;
identify the domain-owned time zone;
derive the local date once per operation;
keep retrieval windows separate from classification rules;
preserve intentionally actionable cross-midnight windows;
make off-day wording explicit;
test before midnight, after midnight, and a spanning window.

The code may still query eighteen or thirty hours. The user should experience a calendar day.

Idempotency Should Resume Partial Work, Not Hide It

Sun, 25 Oct 2026 19:34:58 +0000

Idempotency is usually introduced with a simple promise: run the operation again and it will not create a duplicate.

That promise is useful, but it can become dangerous when we apply it to an entire workflow instead of the specific durable step it protects.

I recently reviewed a recurring integration job with two independent writes. First, it appended a status note to an external record. Second, it moved that record into a terminal state. The note contained a unique marker, so retries could see that the note had already been written.

The marker worked. The workflow did not.

When the state transition failed once, the note remained. On the next sweep, the job saw the marker and skipped the record completely. A local sign of success for step one had accidentally become a global completion flag for steps one and two.

That is a subtle reliability bug because the automation appears idempotent while the real process is only half finished.

A checkpoint is not the whole journey

Consider a generalized background job:

Write a durable note with a unique operation marker.
Move the remote record into a terminal workflow state.
Repeat the scan for a bounded period so temporary failures can heal.

The marker proves exactly one fact: the note exists.

It does not prove that the state move succeeded. It does not prove that a notification was delivered, a file was copied, or a later API call completed. Yet it is tempting to write an early return such as “marker found, therefore this item is done.”

The safer model gives each durable step its own completion evidence. In this case, the marker suppresses only another note. Later sweeps still inspect the remote record and decide whether the second step is pending.

This sounds like a small distinction. In production, it is the difference between duplicate prevention and recovery prevention.

Reconciliation makes partial completion explicit

A resumable job expects to encounter intermediate states:

no note and no terminal state;
note present but transition still pending;
note present and record already terminal;
note present but a person changed the record afterwards;
remote workflow metadata that no longer matches our assumptions;
a temporary failure that should be tried again;
a permanent incompatibility that needs attention.

Those are not exotic edge cases. They are the normal state space of a multi-step integration.

The repaired design runs the state decision on every bounded reconciliation sweep. If the note is missing, it writes the note once. Whether the note was just written or already existed, it then evaluates the transition separately.

That separation makes the control flow honest. We can retry the unfinished part without repeating the finished part.

Ask the external system what its workflow means

The original failure was also a reminder that external state names are rarely universal. One workflow may call its terminal state “Done”; another may use a different label. Hard-coding one friendly name works until a customized process rejects it.

The stronger approach reads the record's type and the available states for that type. It prefers an explicitly configured state when that state exists. Otherwise, it can select a state by semantic category, such as completed or removed.

This adds metadata reads and some branching. It also moves compatibility knowledge to the boundary where it belongs. The integration stops pretending that its vocabulary is the external system's vocabulary.

That fallback must remain bounded. If no suitable category exists, the job should surface the incompatibility rather than inventing a transition.

Human intent outranks automation

Retrying forever is not the same as reconciling safely.

Suppose the automation wrote its note yesterday, then a person deliberately reopened or reclassified the record today. A later sweep should not force the record back into the automation's preferred state.

The reconciliation rule therefore needs ordering evidence. If the external state changed after our durable note, leave it alone. If ordering is unknown, prefer the conservative choice and do not overwrite. If the record is already in any terminal category, there is nothing to repair.

This is an important boundary: the job owns completion of its own intent, not the external workflow itself.

Retry by failure class

Not every failure deserves the same response.

A timeout or temporary service error can be retried by the next sweep. A missing permission or incompatible workflow definition will not improve through repetition. That condition should be reported, with noise controlled, while unrelated records continue.

This classification keeps the job useful during partial outages. One bad record does not starve the batch, and operators are not flooded with alerts for failures that the normal reconciliation loop can heal.

Caching workflow metadata for the duration of one sweep can also limit API traffic without letting old assumptions live indefinitely.

Test the half-finished states

Happy-path tests are not enough for resumable automation. The valuable tests begin after something durable has already happened.

I would want focused coverage proving that:

an existing marker prevents a duplicate note but not a pending transition;
a previously failed transition is attempted on a later sweep;
different state names can resolve through semantic metadata;
terminal records are left untouched;
a newer human change is preserved;
unknown ordering is handled conservatively;
one record's failure does not block the others;
temporary and permanent failures take different paths.

These tests describe the recovery contract more clearly than a mock verifying one ideal call sequence.

The practical rule

For every multi-step job, list the durable evidence produced by each step. Then ask what the next run should do when execution stops after any one of them.

Idempotency should let a workflow resume safely. If an “already processed” check prevents the system from finishing later steps, it is not protecting reliability. It is hiding incomplete work.

An Empty Field Is Still Signed Data

Thu, 22 Oct 2026 06:11:15 +0000

An empty form field looks unimportant. In ordinary application logic, treating an empty value like a missing value is often reasonable. In signature verification, that assumption can reject a legitimate message—or, in a different protocol, verify a representation the sender never signed.

The important lesson is simple: canonicalization is not generic data cleanup. It is part of the cryptographic protocol.

The tidy abstraction that hid a real difference

Consider an integration with two flows:

The application builds an outbound form and signs it.
A provider later sends an inbound form notification that the application verifies.

Both flows need URL encoding, ordered key=value pairs, a digest, and a comparison. A shared helper therefore seems sensible.

But suppose the protocol defines different empty-field rules. The outbound form omits empty values. The inbound notification includes every posted field, even an empty one represented as description=. Reusing the outbound rule during verification silently removes part of the inbound canonical representation.

Nothing is wrong with the network message. Nothing is wrong with the secret. The application simply hashes different bytes from the sender.

That is the dangerous kind of bug: the code is deterministic, the crypto primitive behaves correctly, and the abstraction looks clean. The failure lives in the representation contract.

Empty and absent are different inputs

Application code tends to reason semantically:

note= means there is no useful note.
no note field also means there is no useful note.

A signing algorithm reasons syntactically. It may see:

reference=abc&note=&status=complete

as a different message from:

reference=abc&status=complete

The same applies to field order, repeated keys, character encoding, spaces, escaping, decimal formatting, and line endings. Two representations can produce the same business meaning while producing different signatures.

That is why “normalize before verifying” is unsafe advice unless the protocol defines the normalization precisely. The verifier’s job is not to improve the input. Its job is to reconstruct exactly what the other side signed.

The repair pattern I prefer keeps the truly common pieces together while making direction-specific rules visible.

Shared mechanics may include:

the exact form-encoding routine;
digest calculation;
secret or passphrase handling;
fixed-time signature comparison;
consistent fail-closed behaviour.

The canonicalization policies remain separate:

outbound signing can omit empty fields when the outbound specification says so;
inbound verification can retain empty fields when the inbound specification says so;
both can exclude the signature field itself;
both can preserve their required ordering.

This introduces a small amount of repetition. That is a healthy trade when the alternative is a boolean option buried inside a generic helper whose callers must remember invisible protocol rules. If a shared primitive is retained, give the public operations names and documentation that make the distinction impossible to miss.

Test the representation, not your implementation

Signature tests often contain a subtle circularity: the test calls the production signing helper to create the expected signature, then asks the same helper to verify it. The test proves internal consistency, not compatibility with the protocol.

A stronger test builds the canonical input independently. For the inbound case, start from a literal ordered field sequence containing several key= entries. Calculate the expected digest with a small test-only oracle or a published fixture. Then submit the body to the real verification path.

Useful negative cases include:

remove one empty field and expect rejection;
change field order and expect rejection when order is significant;
replace an empty field with an absent field;
vary spaces and reserved characters;
include a blank expected signature and fail closed;
change only the signature field and confirm it is excluded from canonical input.

These tests describe the protocol boundary directly. They are harder for a refactor to accidentally “update” into agreeing with the bug.

Exercise the framework pipeline too

A pure canonicalization test is necessary, but it is not sufficient for a web endpoint.

Framework model binding and form parsing can consume a request stream, decode characters, merge values, or present fields through an API with different ordering behaviour. Middleware can also affect buffering or body access. A verifier that works against a handcrafted dictionary may still fail when the real HTTP pipeline handles the request first.

Add one focused integration test that:

creates the literal encoded body;
independently calculates the signature over that exact representation;
sends an actual form POST through the application’s HTTP stack;
verifies that the original body remains available where required;
proves the request reaches the normal accepted outcome.

This is not an argument for turning every edge case into a slow end-to-end test. Keep the combinatorial matrix in fast unit tests. Use the HTTP-level case as a boundary witness that the framework and your canonicalization contract still agree.

Verification is necessary, not complete trust

Correct signature verification answers a narrow question: does this message match the shared signing contract and secret?

It does not automatically prove that the event is fresh, unique, authorized for the referenced resource, or safe to apply twice. Production handlers may still need replay protection, timestamp or nonce validation, amount and ownership checks, idempotency, audit evidence, and careful failure handling.

Keeping that claim bounded matters. Strong security engineering is usually a chain of explicit checks, not one impressive cryptographic step.

A practical review checklist

When reviewing a signed integration, ask:

What exact bytes or characters are signed in each direction?
Are empty and missing values distinct?
Is field order defined and preserved?
When does decoding or encoding happen?
Are repeated fields possible?
Does the comparison avoid timing leaks?
Do invalid inputs fail closed?
Is at least one expected signature calculated independently?
Does a real HTTP test cover framework parsing?

The broader engineering principle is worth carrying elsewhere: an abstraction should share sameness, not erase difference. At a cryptographic boundary, the awkward representational details are often the contract itself.

Put the Concurrency Gate Before the Side Effect

Wed, 21 Oct 2026 05:40:24 +0000

Many concurrency bugs begin with code that looks entirely reasonable:

Read the current row.
Check that the operation is still allowed.
Create something durable elsewhere.
Save the original row as complete.

Run once, the workflow is correct. Run twice at almost the same time, and both callers can pass the check before either caller records completion. If step three is irreversible, the system can create duplicate work even though every individual condition was true when evaluated.

The core lesson is simple: when a state transition guards a side effect, make the database choose the winner before the side effect begins.

Why read-then-check is not ownership

An application-level check answers, “What did I observe?” It does not answer, “Do I exclusively own this transition?”

Imagine a parent record representing an open request. Accepting one option creates a downstream record and closes the parent. Two callers can follow this timeline:

Caller A reads the parent as open.
Caller B reads the same parent as open.
Caller A creates a downstream record.
Caller B creates another downstream record.
Both callers try to close the parent.

Optimistic concurrency on the final save may reject one update, but by then the rejected caller may already have created the duplicate side effect. Detecting a conflict after the irreversible action is too late.

Move the decision forward

A stronger shape puts a conditional write immediately before downstream creation. In generalized SQL, the intention is:

UPDATE WorkItems
SET ClaimToken = @token, ClaimedAt = @now
WHERE Id = @id
  AND Status = 'Open'
  AND ClaimToken IS NULL;

The affected-row count becomes the decision:

One affected row means this caller owns the transition.
Zero affected rows means another caller won, or the operation is no longer valid.

That losing result is not exceptional. It is a normal concurrency outcome and should stop before any downstream creation call.

This is stronger than reading again because the predicate and the update are evaluated atomically by the database. There is no application-level gap between “still open” and “now mine.”

The claim is a state, not a boolean trick

Once a claim exists, the domain has an in-progress state whether or not the schema calls it that. Treating it explicitly improves the design.

The workflow needs to answer:

Can a user retry while a claim is fresh?
Which failures can safely release the claim?
When is a claim considered abandoned?
Can another caller take over an abandoned claim?
What happens if the process fails after downstream creation?

A practical rule is to release ownership only when the system knows that no durable side effect exists. If downstream creation fails before producing a record, clearing the claim can make a retry safe. Once a durable result may exist, blindly clearing the claim risks creating another one.

A timeout is recovery policy, not exactly once

A bounded stale-claim timeout prevents an interrupted process from blocking the workflow forever. A new caller may take over only if the stored claim and timestamp still match what it read, so competing recovery attempts cannot both win.

That solves abandoned ownership before the side effect. It does not solve every crash window.

Suppose the downstream service successfully creates a record and the process dies before the parent records completion. After the timeout, replaying the operation could create a second record. The conditional claim narrowed the risk, but it did not create a distributed transaction.

For that boundary, choose an additional mechanism according to the cost of duplication:

Pass a stable idempotency key to the downstream operation.
Record an outbox message in the same transaction as the claim.
Make downstream creation upsert by the originating command identity.
Reconcile incomplete claims against downstream records before replay.

The honest claim is “one winner during concurrent admission,” not “exactly once under every failure.”

Test the overlap, not two sequential calls

A concurrency fix deserves a test that opens the original race window deliberately.

Hold the first caller inside downstream creation. While it is paused, submit the same command again and also submit a competing choice. Then release the first caller.

The useful assertions are concrete:

The downstream creation service was called once.
One winner completed.
Both competing calls received a clear losing result.
The parent stored one selected result.
Other candidates moved to their expected terminal state.

Add two recovery tests as well. First, make downstream creation fail before producing anything and prove that a retry can acquire the released claim. Second, seed a fresh claim and an expired claim, proving that the fresh claim blocks while the expired one can be reclaimed.

This test shape is more valuable than sending two tasks and hoping their timing overlaps. A controlled pause makes the race deterministic and keeps the assertion focused on the contract.

A compact design checklist

Before shipping a command that crosses a data boundary:

Identify the first irreversible side effect.
Put the ownership decision before it.
Use one conditional database write, not a read-then-write promise.
Treat zero affected rows as a normal loser.
Release only when no durable effect exists.
Define stale ownership and takeover semantics.
Add idempotency or reconciliation for the post-side-effect crash window.
Test with a deliberately paused winner and active losers.

The broader principle is not limited to any framework. Checks describe observations. Conditional writes grant ownership. When a workflow can create something you cannot casually undo, that distinction is part of correctness.

Test the Owner, Not the Teardown

Tue, 20 Oct 2026 17:41:25 +0000

Flaky lifecycle tests often produce a tempting diagnosis: the cleanup code must be unreliable. Sometimes that is true. Sometimes the test is asking a framework harness to prove a narrower ownership contract, and the harness is free to finish work on a different schedule.

That distinction matters in interactive server-side UI systems. A component may subscribe to live updates, start a timer, register an observer, or attach a callback. The resource needs a clear owner and a reliable release path. But the test for that contract should not depend entirely on whether a whole rendered tree has completed teardown at one particular instant.

The shape of the failure

Consider a header component that subscribes to a process-local notification service. A child pop-up also owns a separate subscription. The component test renders the tree, publishes an update, observes the visual change, disposes the test context, and immediately expects the global subscription count to be zero.

That sounds reasonable. It is also broader than the claim we really want to prove.

Under a full test-suite load, the notification can overlap a render. The harness teardown call may return while the renderer still has a queued batch. At that instant the header might not yet have received its disposal callback. The non-zero count is therefore ambiguous: either the header leaked, or the harness has not disposed it yet.

A test with two possible explanations is a weak regression guard.

Waiting is not the same as proving

The first instinct is usually to add a retry window: wait for the subscription count to reach zero, perhaps for a few seconds.

That is appropriate when the product contract is genuinely eventual. It is not a universal cure for lifecycle tests. If the harness has left the component alive, waiting merely spends more time observing the wrong boundary. The test remains dependent on incidental scheduling and can still fail without a cleanup defect.

The key question is not, “How long should we wait?” It is, “Which object owns the resource, and what exact behaviour are we trying to prove?”

Put the assertion at the ownership boundary

The stronger test calls the owning component's disposal contract directly, on the correct renderer context, and checks only the resource that component owns.

If the header owns one subscription and a still-rendered child owns another, disposing the header should reduce the count by one. Expecting zero would incorrectly make the header test responsible for the child's lifetime as well.

That narrower assertion is not weaker. It is more precise:

the owner releases its resource;
an independently owned resource is not silently claimed by the parent test;
the result does not depend on whole-tree teardown timing; and
removing the owner's cleanup call makes the test fail consistently.

That last point is especially valuable. A small mutation check—temporarily disabling the cleanup call—shows whether the test detects the regression it claims to detect. If the test still passes, it is probably measuring something else.

Production code still needs lifecycle discipline

A focused test does not excuse fragile implementation. Cleanup should normally be idempotent because framework callbacks, navigation, error handling, and explicit shutdown can converge on the same release path.

The object should also refuse to acquire new resources after disposal. An asynchronous load may resume after the component has gone away. If its continuation subscribes again, a perfectly correct earlier disposal becomes irrelevant because nothing will release the new subscription.

The same reasoning applies beyond subscriptions. Failed in-flight loads should close or abandon temporary buffers. Retained arrivals should have a sensible bound. Work dispatched to another recipient should not accidentally carry ambient request state from the publisher. These are all lifecycle questions: who owns the state, when does ownership end, and what context is allowed to cross the boundary?

Keep two layers of evidence

Direct ownership tests and integration tests answer different questions.

An owner-level test asks: when this component is disposed, does it release what it owns, and can it remain released?

An integration test asks: does navigation, circuit shutdown, or framework teardown actually invoke the right lifecycle path across the rendered tree?

Both matter. The mistake is using only the second, broad test as proof of the first, narrow contract. When the broad test fails, you cannot tell whether ownership or orchestration is broken.

Separating the layers improves diagnosis. A direct test failure points toward the owner. An integration-only failure points toward wiring, scheduling, or framework interaction. The test suite becomes a map of contracts instead of a collection of timing guesses.

A practical checklist

For each subscription, timer, observer, or callback:

Name the owner explicitly.
Make release safe to call more than once.
Prevent acquisition after the owner is disposed.
Test the owner's release contract directly.
Give child-owned resources separate coverage.
Keep one integration test for the framework path.
Prove the test's sensitivity by breaking cleanup locally and seeing it fail.

The trade-off is a few more focused tests and slightly more explicit lifecycle code. In return, failures become actionable. You know whether the owner leaked, the child still legitimately owns something, or the framework has not completed teardown.

Reliable tests do not merely wait longer. They make ownership visible.

Soft Delete Is a Model Contract, Not a Repository Habit

Sat, 17 Oct 2026 05:45:59 +0000

Soft deletion often begins innocently: add an IsDeleted flag, remember to exclude retained rows, and move on. That works until the application grows into several modules, several DbContext types, and configuration spread across assemblies.

At that point, soft deletion is no longer a local query concern. It is a visibility boundary for the complete EF Core model.

The difference is practical. A repository predicate protects the query paths that remember to use it. A model contract protects ordinary reads by default and makes exceptional reads visible in code review.

The dangerous partial success

Imagine a shared base context that scans the entity types it knows and installs a query filter. Later, a module applies another configuration assembly and adds more entities. The base code is correct for the model it saw, but its timing was wrong. Some retained rows are hidden and others are returned normally.

This failure is uncomfortable because both sides look reasonable in isolation. The entity has the deletion marker. The shared context contains filter code. A few tests pass. Yet the effective model has uneven visibility rules.

The lesson is to configure cross-cutting rules at a lifecycle point where the model is complete. An EF Core model-finalising convention can inspect every registered type after the contexts and configuration assemblies have contributed their mappings.

For each root entity carrying the deletion marker, the convention can add the standard predicate. Owned types follow their owner, and derived types inherit the root filter. Existing filters must be preserved: combine with an anonymous filter, or add a separate named filter when the model uses named filters. Any always-visible audit type should be an explicit, narrow exception rather than an accidental omission.

Test the effective predicate

Checking that a filter exists is too weak.

An entity might have an unrelated visibility filter. It might even mention the deletion marker beneath a logical OR:

not deleted OR visible to this user

That expression can still admit a retained row. The required property is stronger: not deleted must be a mandatory conjunct of the effective filter.

A reusable model audit can enumerate all root entity types with the marker, exclude only documented exceptions, and fail if any type lacks that mandatory predicate. It should have tests against itself: prove that it rejects an unrelated filter and rejects the OR case. Otherwise the audit risks becoming a green check that does not guard the boundary it names.

Provider-backed tests add the next layer of evidence. Insert one active row and one retained row. Show that normal queries return only the active row, while an explicit bypass can retrieve both. This verifies the generated query and provider behaviour rather than only evaluating a compiled expression in memory.

A correct filter changes workflows

When global filtering becomes consistent, previously accidental behaviour may break. That is useful information.

Restoration is the clearest example. Suppose a retained row still owns a unique business slot. A normal lookup cannot see it, so a naive create path tries to insert a replacement and collides with the database constraint.

The solution is not to weaken the global filter. Give the restoration path an explicit way to ignore model filters, then make its intention precise:

creating into a slot held by a retained row restores that same row;
editing a different active row into the reserved slot is refused;
failure leaves both rows unchanged;
historical or restoration reads are the only paths allowed to bypass the boundary.

Putting the bypass on a named specification or dedicated query object is easier to review than scattering IgnoreQueryFilters() through services. The name communicates why the exception exists, and focused tests can pin its scope.

Watch required navigations

Global filters also interact with relationship shape. If a required navigation uses an inner join and the principal is filtered out, the dependent can disappear from a query even when the dependent itself is active.

That may be correct, but it should be a decision.

An inventory of required relationships that cross filtered and unfiltered types gives reviewers a bounded list of hazards. For each one, choose deliberately: align filters on both sides, make the navigation optional, change the query shape, or accept and test the disappearance.

This is one reason metadata-driven verification scales better than a long list of hand-written repository tests. The model can tell you what exists now, including a new entity or relationship added by a future module.

A practical verification stack

A durable soft-delete boundary has four layers:

Apply the convention after the model is complete.
Audit every soft-deletable root for the exact mandatory predicate.
Keep bypasses explicit and limited to restoration or historical use.
Run real-provider tests for visibility, restoration, uniqueness, and required-navigation behaviour.

There is a cost: more model infrastructure, a deliberate exception list, and tests that can expose old assumptions. Some teams may decide that hard deletion or temporal tables better match particular data. The point is not that soft deletion is always right.

The point is that, once chosen, it must behave like one coherent contract.

The most valuable outcome is not the filter itself. It is that a future entity cannot quietly arrive outside the boundary—and that exceptional access reads like an exception.

A Passing Test Can Still Prove Nothing

Wed, 14 Oct 2026 06:12:33 +0000

Some of the most misleading tests are not flaky, slow, or obviously incomplete. They are fast, deterministic, and green.

They also pass for the wrong reason.

That is especially dangerous in fault-tolerant code. A test may claim that a failed dependency is contained, a fallback runs, or an established workflow continues. Yet its assertion may observe an outcome that can occur both before and after the recovery boundary. The suite reports confidence while the behaviour named by the test remains unproved.

The false-positive shape

Imagine a dispatcher with an optional policy source in front of an established workflow. The intended behaviour is straightforward:

Ask the policy source whether the old workflow should stand down.
If that optional source fails, contain the fault.
Continue into the established downstream path.

The unit test configures a policy source that throws. It also uses a strict downstream test double that throws if reached, because the rest of that workflow is outside the test's concern.

Then it asserts only that dispatch throws an exception.

At first glance, this can feel reasonable. An exception from the strict downstream dependency appears to prove that execution continued. But the same broad assertion also accepts the earlier exception from the policy source. If the recovery logic is deleted, the first exception simply escapes and the test remains green.

The assertion recognizes the shape of the final outcome, not the path that produced it.

Test the claim, not the punctuation

The claim is not “an exception occurs.” The claim is “a fault at this boundary does not stop progress into the established path.”

That distinction changes what the test must observe.

A useful test needs a stable witness on the far side of the boundary. Depending on the design, that witness could be:

a recorded call to the downstream collaborator;
a domain result that only the fallback path can produce;
a distinct exception identity from a deliberately strict dependency;
a state transition committed after the failed operation; or
an emitted event that occurs only after recovery has completed.

The specific technique matters less than the causal guarantee. The witness must be impossible—or at least deliberately difficult—to observe if execution stops at the failure being contained.

In the example above, the corrected test distinguishes the downstream failure from the policy-source failure. It therefore passes only when execution crosses the recovery boundary. A recording test double would also work and may be clearer when the downstream call itself is the contract.

Why mutation testing helped

Code coverage could not expose this weakness. Both the recovery code and the test might execute during the normal run. Coverage tells us which lines ran; it does not tell us whether an assertion depended on their behaviour.

Mutation testing asks a sharper question: if a meaningful piece of behaviour is changed or removed, does a test fail?

Removing the recovery behaviour created a surviving mutant. That was valuable evidence. It did not necessarily mean the production design was wrong. It meant the suite could not distinguish the intended implementation from a broken one.

This is one of mutation testing's best uses: finding assertions that observe something adjacent to the claim rather than the claim itself.

You do not need mutation tooling to apply the same reasoning in review. Mentally invert the behaviour:

If the catch disappeared, would the test fail?
If the fallback were skipped, would the test fail?
If execution stopped one step early, would the test fail?
Could a different branch produce the same asserted result?

If the answer is uncomfortable, look for a witness beyond the boundary.

The trade-off: path awareness without brittleness

Path-sensitive assertions carry a real cost. A test that verifies every internal call order can become coupled to implementation detail and obstruct harmless refactoring. Replacing one collaborator with another should not require rewriting an entire suite if the observable contract is unchanged.

The answer is not to avoid path awareness altogether. It is to choose the smallest stable witness that represents the behaviour promised by the test.

Prefer domain-visible evidence when it exists: a returned decision, a committed state, a durable message, or a recorded recovery status. Use collaborator verification when crossing that collaborator boundary is itself the contract. Use exception type or identity when a strict test double intentionally marks progress, but make that intent explicit so a future reader understands why the exception matters.

This produces a useful hierarchy:

Assert the externally meaningful result when it uniquely proves recovery.
Assert a durable checkpoint when the final result is produced asynchronously.
Assert a boundary interaction when progress across that boundary is the behaviour under test.
Use a distinct failure identity as a narrow witness when a strict dependency deliberately terminates the test.

The closer the witness is to the real reliability contract, the less brittle the test will be.

A practical review habit

When reading a test name, underline the verb: continues, retries, falls back, persists, publishes, or rejects. Then find the assertion that proves that verb happened.

If you can only find evidence that something threw, returned, or logged, ask whether the same evidence could appear before the named behaviour occurred.

Green is not the standard. Discrimination is. A useful test must distinguish the system we intended from a nearby broken version.

For fault-tolerance tests in particular, do not merely observe the aftermath of a failure. Prove that the system crossed the boundary it promised to survive.

Tuesday Coding Tip 26 — JSON (de)serialization in C#

Tue, 13 Oct 2026 09:59:00 +0000

In need of a JSON (de)serializer in C#? One option could be to use the built-in System.Text.Json functionality. Probably the most popular way is to use the Newtonsoft.Json library which has a richer feature set while maintaining overall simplicity.

Things are as simple as having a class with a bunch of public attributes and calling serialize on it. Those attributes don’t even have to be trivial types — anything from DateTime to HashSet can be easily handled.

Deserialization is similarly easy — if a key is present, it will be deserialized. If not, the default value for the attribute will be picked instead.

using Newtonsoft.Json;

namespace NetSandbox;

public class ExtendedValues
{
    public long ErrorCode { get; set; }

    public string Message { get; set; } = string.Empty;
};

public class Property
{
    public string Value { get; set; } = "";
};

public class Protocol
{
    public long Version { get; set; } = -1;

    [JsonProperty("extended", NullValueHandling = NullValueHandling.Ignore)]
    public ExtendedValues? ExtendedValues { get; set; } = default;


    [JsonProperty("machineGuid")]
    public Guid MachineGuid { get; set; }

    public List<Property> Properties { get; set; } = new List<Property>();
};

public static class Program
{
    public static void Main()
    {
        Protocol schema = new()
        {
            Version = 1,
            MachineGuid = Guid.NewGuid(),
            Properties = new List<Property> {
                new Property {
                    Value = "hello"
                },
                new Property {
                    Value = "world"
                }
            }
        };

        var json = JsonConvert.SerializeObject(schema);
        // {"Version":1,"machineGuid":"156717fd-0904-47af-bcb8-ad74d23b9cc7","Properties":[{"Value":"hello"},{"Value":"world"}]}

        var obj = JsonConvert.DeserializeObject<Protocol>(
            """{"machineGuid": "156717fd-0904-47af-bcb8-ad74d23b9cc7"}""");
        // obj.Version contains -1
        // obj.MachineGuid containts "156717fd-0904-47af-bcb8-ad74d23b9cc7"
        // obj.ExtendedValues is null
        // obj.Properties is empty list
    }
}

If you need to, you can use annotations to for example customize the name of the serialized property or whether it will be serialized when it is null.

Extra thought: I originally wrote this post in late 2023. Since then, many people would probably advice you System.Text.Json on the merit of being faster and getting more and more on-part with Newtonsoft on each major release. Since we did a switch to it some time ago, I cannot wholeheartedly recommend it - it is great for simple use cases, but once you have some data structure that evolved over time and you need to be lenient of what you accept over wire and strict in what you send, working with System.Text.Json is a bigger pain, especially around NullValueHandling and DefaultValueHandling.

The Async Result Belongs to the Snapshot That Started It

Sat, 10 Oct 2026 06:01:28 +0000

Modern client components are long-lived, reactive, and full of asynchronous work. That combination creates a subtle class of defect: a response can be factually correct for the request that produced it, yet wrong for the screen that exists when it arrives.

This is especially important when a component mixes route parameters with identity-scoped state. The user can navigate while a request is in flight. Authentication can resolve, refresh, or change. The component instance may survive both events. Unless the component tracks which context owns each result, an older task can update a newer view.

The core rule is simple:

An awaited result belongs to the input snapshot that started it.

That snapshot is more than a component reference. It can include the current route value, the current authentication-state operation, and a monotonically increasing generation number.

How the race forms

Imagine a detail page that loads an item, then asks whether the current viewer has reacted to it. The page shows a highlighted action when the answer is yes.

The component begins loading item A for identity A. Before the viewer-specific request returns, the user signs out and another identity becomes current—or the same component navigates to item B. The old request then completes with a truthful answer: identity A did react to item A.

If the continuation writes directly to a shared isActive field, that truth is now displayed in the wrong context. Item B may appear active, or identity B may see state derived from identity A.

This is not merely a cosmetic race. Identity-derived state can influence which actions are enabled, what ownership badges appear, and which command a user can submit next.

Make ownership explicit

A practical pattern is to treat every meaningful input change as a new generation.

When a route or authentication input changes:

Increment the generation.
Capture the route and authentication input in local variables.
Clear state derived from the previous identity.
Disable identity-scoped actions while the new identity is unresolved.
After each await, confirm that the generation and captured inputs are still current.
Apply results only when those checks pass.

The checks matter after every awaited boundary, not only at the end. A component may load the main item, related content, entitlement state, reaction state, and cart state in sequence. Any await is a point where navigation or identity can change.

Cancellation tokens can reduce wasted work, and they are worth using when the underlying operation supports cancellation. But cancellation alone is not the ownership proof. Cancellation can race with completion, and some dependencies cannot cancel promptly. The continuation still needs to ask, “Does this result belong to the current snapshot?”

Fail closed while identity is unknown

There is another important state between old identity and new identity: unresolved identity.

Keeping the old viewer-specific UI visible during that interval is convenient, but unsafe. The component should clear ownership badges, active reactions, and similar derived state before awaiting the new authentication result. Any action that depends on identity should be disabled until the new snapshot is ready.

That brief disabled state is honest. The application does not yet know which identity owns the next command.

This principle also prevents an action from being sent using newly refreshed credentials while the visible UI still describes the previous viewer. Read state and write authority move together.

Test the interleaving, not only the outcome

Ordinary happy-path tests rarely expose this defect because requests finish in the same order they started.

A stronger component test controls the schedule:

Start a viewer-specific read and hold its response.
Change the route or authentication identity.
Wait for the new screen to settle.
Release the old response.
Assert that the current screen does not adopt the old result.

A separate test should hold authentication unresolved and verify that identity-scoped actions remain disabled. This proves that the UI fails closed during the transition.

There is also a useful counter-test: rerender with exactly the same inputs while a valid request is pending. The component should not discard or duplicate work merely because the framework rendered again. The boundary is a meaningful input change, not every render cycle.

These tests are valuable because they verify time and ownership, not just a final value. They turn a race that might appear once in a thousand interactions into a deterministic scenario.

The trade-off

Generation markers, captured snapshots, and repeated currentness checks add code. Temporarily disabling an action can introduce a small pause. Overusing the pattern can also make a component difficult to read.

The answer is not to attach a counter to every asynchronous line. Use the pattern where results are scoped to changing inputs: routes, selected records, authentication identity, workspace, locale, or another boundary that can change while the component remains mounted. Extract a small helper when the same ownership rule appears repeatedly.

The payoff is larger than visual correctness. Explicit async ownership reduces stale-route updates, prevents state from crossing identity boundaries, and stops commands from being enabled under an unresolved context.

The humble takeaway is this: asynchronous correctness is not only about receiving the right answer. It is also about proving that the answer still belongs here.

Building Reliable Backend Applications with C# and .NET

Tue, 06 Oct 2026 02:40:20 +0000

Backend development is more than writing code that works. For me, it is about building systems that are reliable, maintainable, secure, and capable of supporting real business needs.

My main experience is with C#, .NET, ASP.NET Core, SQL Server, and Entity Framework. I enjoy working on backend systems where there are real requirements to understand, databases to design, APIs to build, and performance problems to solve.

Turning Business Requirements into Backend Solutions

A typical project starts with understanding what the business actually needs. Before writing code, I try to understand the workflow, the data involved, and how different parts of the application will communicate.

Once the requirements are clear, I focus on creating a backend structure that is easy to maintain and can grow with the application.

This usually involves:

Designing backend architecture
Developing APIs with ASP.NET Core
Working with SQL Server databases
Creating data models with Entity Framework
Implementing authentication and authorization
Writing business logic in C#
Improving database queries and application performance
Debugging and maintaining existing applications

Working with Databases

A backend application is only as good as the data layer behind it.

I have worked extensively with SQL Server and Entity Framework, including database design, relationships, queries, stored procedures, migrations, and performance optimization.

One thing I have learned is that database performance should not be treated as an afterthought. A poorly designed query or database structure can affect the entire application.

Efficient database design and optimized queries can make a huge difference in application performance.

Building Secure APIs

Modern applications often depend heavily on APIs. I focus on creating APIs that are organized, predictable, and secure.

From handling requests and validation to authentication, authorization, error handling, and database communication, every layer needs to work together properly.

I also believe that an API should be designed with the consumers in mind. Clear responses, consistent error handling, and proper validation make applications much easier to maintain.

Performance and Problem Solving

Backend development often involves finding problems that are not immediately obvious.

An application may work correctly but become slow when the amount of data increases. A database query may work with a few records but become inefficient with thousands or millions of records.

That is where debugging and performance analysis become important.

I enjoy investigating these types of problems, finding the root cause, and improving the implementation rather than simply applying a temporary fix.

Maintaining Existing Applications

Not every project starts from scratch.

A large part of backend development can involve working with existing applications, understanding someone else's code, fixing bugs, improving functionality, and gradually making the system better.

This requires patience and the ability to understand existing architecture before making changes.

Good backend development is not always about rewriting code. Sometimes the best solution is improving what already exists.

Continuous Learning

Technology keeps changing, so there is always something new to learn.

Even while working primarily with C# and .NET, I continue exploring better development practices, modern backend architecture, API design, database optimization, and new tools that can improve the development process.

For me, programming is a continuous process of learning, building, debugging, and improving.

I enjoy taking a business requirement, breaking it down into smaller technical problems, and eventually turning those ideas into a backend system that people can actually use.

Always learning. Always building. Always looking for a better way to solve the problem.

Project the Response, Not the Cache

Thu, 01 Oct 2026 05:50:20 +0000

A response can be correct for one caller and still leave the application in a worse state for everyone who follows.

This is an easy trap in ASP.NET Core when a result filter, formatter, or middleware needs to change a few fields before a response leaves the server. Localization is a useful example: a DTO contains source-language text, the current request asks for another language, and the pipeline replaces selected strings before serialization.

The first response looks right. The implementation may even be pleasantly small.

The danger is ownership. If the returned DTO came from an in-process cache, the response pipeline may be holding the same object instance that another request, background job, or command path will read later. What looked like response formatting was actually a write to shared state.

The broader lesson is this: request-specific presentation should be a projection, not a mutation.

The Bug Hides Behind a Successful Response

Imagine a cached catalogue item with a description in the system’s source language. A request asks for a translated version. The tempting implementation walks the object graph and assigns the translated string to the DTO property.

The response is translated correctly. A test that checks only that response passes.

Now consider the next reader. If the cache returns the same instance, the cached item is no longer in its authoritative source form. A source-language request may receive translated text. A command that maps the DTO back into another model may persist presentation text as source data. A background process may observe a value chosen for somebody else’s request.

Nothing about the first HTTP response reveals this. The defect is temporal: the observable failure belongs to a later reader.

That is why “the output is correct” is not a sufficient assertion when inputs can be shared.

Draw the Ownership Boundary Explicitly

A useful model is to separate three things:

The cached or domain DTO is authoritative input.
Request context selects presentation rules.
The HTTP payload is response-owned output.

Once those roles are explicit, several safe implementations become available. You can map into a dedicated response model. You can clone the graph and change the clone. Or you can project replacement values at the serialization boundary.

In the last approach, the traversal discovers which string properties need different values but never assigns those values to the source objects. The serializer then substitutes the replacements while creating a JSON tree owned by the response. Nested objects, collections, readonly wrappers, and init-only properties keep their wire shape because the original serializer contract still defines the payload.

The important property is not the particular API used. It is that no request-specific operation writes into caller-owned or cache-owned objects.

This idea also applies to redaction, unit formatting, enrichment, API-version shaping, and field masking. If the transformation varies by caller or request, it probably belongs in an output projection.

Preserve the Common-Case Fast Path

Projection has a cost. It may require an additional JSON materialization, replacement lookup, and short-lived allocations. That cost should be acknowledged rather than hidden behind a correctness slogan.

The practical response is to make the cheap path obvious. When the request already uses the source representation, pass the original result through untouched. Only requests that need transformation pay for projection.

Failure behavior also matters. If the projection cannot handle an unusual graph, the pipeline should not leave a half-mutated object behind. A safe fallback retains the original result and logs the failure according to the application’s policy. Whether returning the untransformed payload is acceptable depends on the feature and data classification; sensitive redaction may need to fail closed instead.

Security-sensitive payloads and error results may also deserve explicit exclusion. Presentation machinery should not accidentally inspect tokens, secrets, or payload shapes that were never part of its contract.

Test the Second Reader

The highest-value test is a sequence, not a snapshot:

Put a source-language object into the real cache implementation used by the host.
Request a transformed response and verify its output.
Read the cached object again and verify that it is unchanged.
Issue a source-language request and verify that it still receives the source value.

Run that sequence through the real result filter and serializer options, not only a mocked translation service. The ownership bug lives in the composition between cache identity, result handling, graph traversal, and serialization.

Add focused cases for ordinary object results and explicit JSON results, nested collections, readonly response wrappers, init-only properties, error responses, exempt payloads, and projection failure. These tests establish both the intended transformation and the things it must never change.

A mutation-resistance assertion is especially valuable: keep a reference to the original object and prove its properties retain their exact values after the response executes.

The Trade-Off Is Isolation Versus Local Simplicity

In-place mutation is easy to understand in one method and can avoid an extra materialization. Its cost appears elsewhere: temporal coupling, language or user context leaking between requests, and tests that pass individually while failing in sequence.

Response projection adds code, allocations, and serializer-specific reasoning. In return, it makes ownership visible. The cache remains authoritative, requests remain isolated, and failures cannot leave shared objects partially transformed.

That is a trade I will usually take. I would still measure the transformed path with representative payload sizes and keep the source path cheap. But performance work should begin after the ownership contract is correct.

The practical rule is short: if a value is shared, treat it as immutable. If presentation depends on the request, produce response-owned output. And when you test it, always ask what the next reader sees.

Treat Every ID as an Authorization Claim

Wed, 30 Sep 2026 10:38:55 +0000

Authentication answers one important question: who made this request? It does not answer a second question that often hides inside an ordinary-looking query parameter: may this caller name the record represented by this identifier?

That gap is easy to miss in APIs that accept a parent ID, child ID, account ID, project ID, or tenant ID. The route is authenticated. The identifier has the correct shape. The query returns a valid result. Yet none of those facts proves that the record belongs inside the caller's authorized scope.

A useful engineering rule is to treat every caller-supplied identifier as an authorization claim before treating it as a query input.

Authentication Is Not Object Ownership

Imagine an endpoint that returns activities for a supplied household record. The controller requires a signed-in user, then passes the supplied ID into a query service. If the ID is changed in transit, the query may still succeed—just for somebody else's data.

The vulnerable assumption is subtle: “signed in” becomes “allowed to ask about any existing record.” The database faithfully answers the question it receives. The missing control belongs before the query.

The server should derive the caller's authority from trusted identity and relationship data. For an ordinary user, that might mean resolving the account to its authoritative person record, then traversing explicit relationships to the permitted records. For an operational role, a specific permission may allow a wider scope because that role already performs work requiring the same visibility.

This also explains why email equality is a poor ownership rule. Addresses are corrected, reused, shared by families, copied into contact fields, and sometimes retained after account changes. An email can help locate a candidate during migration, but it should not silently replace an authoritative account-to-person relationship.

Put the Boundary Before the Query

A safe request pipeline makes the order explicit:

Identify the caller from trusted authentication state.
Resolve the caller's authoritative records and relationships on the server.
Evaluate each supplied identifier against that scope.
Only then construct and execute the data query.

This order prevents a common failure mode: retrieving a broad result and hoping a later projection removes everything sensitive. Late filtering spreads the security contract across repositories, mappers, and UI code. Early scope resolution gives the query a smaller, already-authorized input.

Do not bundle independent identifiers into one vague decision. If a request contains both a parent filter and a child filter, check each one. Mixed requests are exactly where “one valid field makes the request valid” bugs appear. A valid parent must not bless an unrelated child; an unrelated parent must not erase a valid child's boundary.

Reject by Default, Narrow Only Deliberately

For most data-specific routes, a cross-scope identifier should be rejected. Rejection is direct, observable, and easier to reason about. It tells the client that its request crossed a boundary and gives operators a signal worth investigating.

Legacy mobile clients complicate that clean answer. An installed client may send an old identifier shape, interpret a forbidden response as a session failure, or sign the user out. Waiting for every old version to disappear can leave a real data boundary open longer than necessary.

There is a narrow alternative: compatibility-preserving narrowing. The server validates every supplied identifier, discards any that are not authorized, and executes only a known-safe baseline query. The key invariant is monotonicity: removing an unauthorized filter must never widen the response into the requested protected data.

For example, a calendar route might combine household-specific entries with public entries. If an old client sends an account ID where a domain record ID is expected, the server can remove that invalid household filter and return only the public baseline. It must not substitute another household, guess from a weak attribute, or run an unscoped “all entries” query.

This is not a general recommendation to hide authorization failures. It is an endpoint-specific migration tool. Document why it exists, record how it is used, and give it a removal condition.

Test the Boundary, Not Just the Happy Path

Authorization tests should form a matrix around relationships and permissions:

the caller names their own authoritative record;
the caller names a related child record;
the caller names another household's record;
the caller has no corresponding relationship;
a shared or copied email appears on a record the caller does not own;
a staff role lacks the exact cross-scope permission;
a staff role holds that permission;
one filter is authorized while another is not;
the legacy request shape still receives the same safe baseline.

The last two cases are especially valuable. Mixed filters catch accidental “any match” logic. Legacy-shape tests prevent a future cleanup from turning a deliberate compatibility response back into either a leak or a destructive client error.

Tests should assert returned data as well as status codes. A successful response is safe only if its contents stay inside the proven scope. A forbidden response is useful only if the client contract can tolerate it.

Make the Exception Expensive to Forget

Compatibility code tends to become permanent when its rationale lives only in memory. Keep the exception close to the boundary, name the safe baseline, add telemetry that contains no sensitive identifiers, and define the client version or date after which strict rejection can replace narrowing.

The trade-off is real. Strict rejection gives a simpler model and clearer misuse signals. Narrowing adds policy, tests, and the possibility of masking a broken client. Its value is speed: the server can close the data boundary now while preserving a safe experience for older installations.

The practical standard is modest but powerful: never let a caller-provided ID reach a query merely because it parses. First prove that the caller may name it. If compatibility forces an exception, make the request narrower, make the safe response explicit, and make the exception temporary.

At 43, the Vietnamese IT Market Calls Me "Too Old" — I Still Write Code Every Day

Wed, 30 Sep 2026 09:02:40 +0000

Originally published at vnmlstudio.runasp.net

I'm 43 years old. Last week, a recruiter told me I'm "too old for the position" — politely, of course, but the message was clear.

I stopped applying 7 months ago. Not out of defeat — out of realization.

Instead of sending more CVs, I opened Visual Studio and started building something.

What I built

VNML Agent Framework — an open-source multi-agent AI system that runs 100% locally on my laptop with a GTX 3050 Ti and 4GB VRAM. No cloud. No API keys. No team. Just me and my machine.

The framework has 4 layers:

P0 Reflection — the agent critiques its own decisions before moving forward
P1 Planning — DAG-based multi-agent orchestration
P2 Learning — agents extract reusable skills from experience
P3 Synthesis — agents write and compile their own C# tools at runtime

Six months of work. On a laptop. On a CPU.

The moment I almost gave up

There were nights I sat in front of the screen asking myself: "How much longer can I keep doing this?"

Every rejection email felt like validation of a cruel joke the industry plays on developers over 35: "Your experience is valuable, but... we're looking for someone more junior."

I considered quitting tech. Driving for a ride-hailing app. Opening a small coffee shop. Anything that didn't require me to explain why my birth year is 1983.

But every time I felt like giving up, I opened Visual Studio again. And I wrote.

The moment Microsoft noticed

Two weeks ago, I typed vnml agent framework into Bing on a whim.

Microsoft Copilot Search returned a 200-word AI-generated summary of my project.

Not just a GitHub link. A full description that captured exactly what I'd built — architecture, tool synthesis, local execution, everything.

I read it three times. Then it hit me: one of the largest tech companies in the world had read my code, understood my architecture, and written about it.

Nobody called. No email. No announcement. Bing just crawled and indexed my public repo — like it does for every other project in the world.

But for me, that moment changed everything.

What I learned

1. README matters more than you think.
Copilot extracted 90% of its summary from my README. Clear structure → AI understands.

2. Personal blogs still have power.
Copilot cited my blog on runasp.net, not Medium, not Dev.to. Own your platform.

3. GitHub is a real SEO channel now.
Repos get read, understood, and summarized by AI. Nobody predicted this 5 years ago.

4. Nobody needs to give you permission.
You don't need a company to notice you. You don't need funding. You just need to build something real and publish it.

Why I'm writing this

Not for sympathy. Not for job offers.

For every developer out there who feels the industry has moved on without them. For every 40-something programmer who wonders if they should just become a manager or change careers.

The industry moves on. But the craft doesn't.

Age doesn't define the value of a developer. Persistence beats prejudice.

I'm 43. I have no team. No funding. No office. Just a laptop, an idea, and the stubborn refusal to stop.

And I still choose to write code. Every single day.

If you're building with local LLMs, connecting with the C# community, or just want to see what a solo dev can ship in 2026 — the full framework is open source:

🔗 GitHub: https://github.com/hoangnc/VNMLAgentFramework

I'd love to hear: what keeps you going when the industry says you don't belong anymore?

A Lifetime Is a Hold, Not the Worker

Tue, 29 Sep 2026 05:58:20 +0000

IDisposable and IAsyncDisposable make lifetime management feel pleasantly local: acquire something, use it, dispose it. That model is reliable when the acquired value has exclusive ownership of an independent resource.

It becomes dangerous when several activations share one background worker.

Mobile applications encounter this more often than it first appears. Returning online can reconcile a capability that is already running. A foreground transition can overlap an earlier activation. A bounded startup wait can stop waiting for slow native work, while that work completes after a newer activation has already joined the same resource.

If every returned lifetime means “stop the worker,” one participant can tear down work that another still needs. The sharper contract is: a returned lifetime is a hold on shared work. Disposing it releases only that participant’s hold. The worker stops when the final hold leaves.

The bug hides behind a reasonable API

Imagine a mobile shell with two optional capabilities: a small status refresher and a device-token relay. Each activation returns an asynchronous lifetime to the orchestrator. The orchestrator keeps the latest lifetime and disposes the one it replaces.

That sounds tidy, but activations are not necessarily independent. The second activation may join the refresher or event relay started by the first. If the first lifetime calls a global StopAsync, disposing the replaced lifetime stops the shared worker beneath the second activation.

The state machine can now tell a convincing lie. Its newest activation completed successfully, so the capability still appears ready. Underneath, polling has stopped or the event handler has been removed.

Warning, cancellation, and stale-completion paths deserve the same scrutiny. Cleanup code is often written defensively in several branches. If each branch performs terminal teardown, one failed attempt can shut down a resource held by a successful attempt.

Write the ownership sentence first

Before implementing the lifetime, describe what disposal means:

Disposing this value releases this activation’s participation. It does not necessarily stop the shared resource.

That sentence changes the design. Starting becomes “start or join, then take a hold.” Releasing becomes “release this hold, then stop only if it was the last.” Both transitions need one synchronization boundary.

It is not enough to increment a counter and subscribe in separate steps. Another thread can observe the gap. A release can unsubscribe after a new hold has been counted, or two starts can install duplicate listeners. The zero-to-one decision and the actual start belong in one atomic operation. So do the one-to-zero decision and the stop.

The hold itself should release at most once. A double Dispose must not decrement the count twice. A failed start must not record a hold, otherwise the next activation may “join” work that never started.

Old holds must not reach into new runs

Reference counting alone is not sufficient when the resource can stop and restart.

Suppose an old activation holds generation A. The application moves offline, so generation A is stopped. Later, the application returns online and starts generation B. If the late lifetime from A merely decrements a global count, it can steal a hold from B and stop the restarted worker.

Bind each hold to the run it joined. Releasing a hold from an ended run becomes a no-op for the current one.

The orchestrator may need a run identity too. Some stop events invalidate a broad session lease; others, such as backgrounding or going offline, may intentionally leave that session identity unchanged. A slow activation can therefore finish with a lease that still looks current even though the capability run it belonged to has ended. Tracking the capability run separately prevents that late completion from being adopted as ready.

This distinction is useful beyond mobile software. Connection pools, shared subscriptions, refresh loops, file watchers, and in-process event relays all have “same logical session, different resource run” failure modes.

Test transitions, not only outcomes

A happy-path test that starts and stops once proves very little about shared ownership.

Useful tests make each boundary visible:

take two holds, release one, and prove the worker remains active;
release the final hold and prove the worker stops exactly once;
dispose one hold twice and prove it releases once;
fail the first start and prove a later acquisition tries again;
restart the resource and prove an old hold cannot affect the new run;
complete an abandoned activation after a newer one and prove the newer work survives; and
repeatedly take, inspect, and release holds from two threads while the count crosses zero.

That last test is important. A single-thread loop can leave mutation survivors because it never exposes the gap between “count says active” and “listener is actually active.” Two competing threads make zero crossings collide with acquisition and release, which is where split synchronization shows itself.

Concurrency tests still need discipline: bounded rounds, a clear invariant, and no claim that passing them mathematically proves correctness. Their job is to exercise the race window while deterministic tests pin the state-machine rules.

The honest trade-off

Counted holds add a lock, a run identifier, idempotent release state, and more involved tests. They also force a clear distinction between releasing one participant and terminally disposing the owning dependency scope.

The simpler design is to prohibit overlap. That can be the right choice when the orchestrator can guarantee one activation at a time, cancel it reliably, and wait for completion before starting another. But if native calls can outlive a budget, or reconciliation can join already-running work, the simplicity is imaginary.

The practical takeaway is broader than reference counting: make ownership semantics part of the public contract. When a lifetime represents participation in shared work, call it a hold and test it like one. A local cleanup action should never silently become a global stop.

Design the Cursor, Not Just the Query

Mon, 28 Sep 2026 06:23:05 +0000

Pagination is often introduced as a performance improvement: fetch fewer rows, render less markup, and keep response sizes predictable. That is only half the job.

For an operational queue that changes while people work, pagination also defines what it means to continue reading. If that contract is weak, the database can answer every query correctly while the person using the screen still sees duplicates or misses work.

The important design question is not merely, “How many rows should this query return?” It is, “What does the next request mean after the underlying set has changed?”

Why offset paging drifts

Consider a queue ordered newest first. A reviewer asks for the first twenty-five rows. The next request uses an offset of twenty-five.

Between those requests, a new row arrives at the top. Every earlier row has moved down one position. The second query now begins with the final row from page one, so the reviewer sees a duplicate. More importantly, one unseen row has been pushed beyond the requested range.

This is not an exotic race. Append-mostly queues invite it because adding work is the ordinary operation. Offset paging treats positions as stable even though insertion changes every position below it.

Mutable sorting creates a similar problem. If the queue is ordered by status or last-updated time, an operator’s decision can move a row while the walk is in progress. A continuation based on that value inherits the instability of the workflow.

Continue from an immutable boundary

A stronger contract says: continue after the boundary returned by the previous read.

For a newest-first queue, that boundary can be an immutable creation or submission timestamp. New rows arriving above the boundary are not part of the current walk. They will appear when the reviewer starts again from the top, but they do not shift the meaning of “next.”

Equal timestamps need deliberate handling. Adding an identifier as a tie-breaker becomes fragile when data providers sort that type differently.

Another approach is to carry the boundary timestamp plus the number of rows already consumed at that exact timestamp. The database remains responsible for its native ordering within the tie, while the continuation records how far through that tie the walk has progressed. The detail matters less than the invariant: ties must neither duplicate nor hide rows.

Make the continuation part of the contract

An opaque cursor should not be a loosely encoded page number. It is protocol state, so treat it that way.

Useful safeguards include:

a version, so the format can evolve deliberately;
a strict length limit and parse validation;
the immutable boundary and tie position;
the active filter identity; and
sensible bounds on any stored count.

Binding the cursor to its filter is especially important. A position in “all open items” does not mean the same thing in “items for one category.” Reusing the cursor after changing filters can silently skip work. Rejecting that request is clearer than pretending the cursor is still meaningful.

Likewise, a malformed continuation should fail explicitly. Silently dropping it and returning the first page converts a bad request into a plausible-looking duplicate page. Operational software benefits from visible invalid states.

Keep every downstream read bounded

Paging the primary table is not enough if enrichment still loads data for the entire result set.

A common pattern reads the page, extracts its identifiers, and then fetches related summaries in a second query. That identifier list must come from the bounded page. Otherwise the visible query is paged while a hidden IN clause continues growing with the queue.

Fetching one extra primary row is a simple way to determine whether a continuation is needed. Return the requested page size, and issue a next cursor only when the extra row exists. The presence of that cursor—not whether the current page happens to be full—becomes the authoritative “has more” signal.

This also avoids an exact count on every read. For many live queues, “Page 3” plus Previous and Next is the more honest interface.

Carry the contract into the Blazor UI

Server-side continuation paging should not be wrapped in a client component that first downloads the entire queue. The UI has to follow the same contract.

A practical Blazor page can keep a small trail containing the cursor used to open each visited page. Next stores the returned cursor. Previous reuses the earlier cursor to re-read that logical page. After an operator records a decision, refresh the current page rather than throwing them back to the beginning.

Page changes should also clear any pending confirmation tied to a row that is no longer visible. That is a small state-management detail with a large clarity benefit: the user should never be asked to confirm an action on an item they cannot see.

Test the movement, not only the shape

Happy-path tests that assert “twenty-five rows returned” do not prove a paging contract.

The valuable cases exercise movement:

insert a newer row after reading page one, then verify page two has no gap or duplicate;
create several rows with the same boundary timestamp;
reject zero, negative, and excessive page sizes;
reject malformed, oversized, and filter-mismatched cursors;
verify related-data queries receive only current-page identifiers;
navigate Next and Previous in the component; and
perform an action and confirm the current page is refreshed.

These tests describe the promise a reviewer experiences, not merely an implementation detail.

The honest trade-off

Continuation paging is more work than offset paging. It needs a stable sort, a cursor format, versioning, filter binding, careful tie semantics, and focused tests. It also makes random access and exact page counts less convenient.

That cost is justified when the list is both live and operationally important. Bounded queries protect the system under bursty load; stable continuation protects the human workflow under concurrent change.

Takeaway: choose pagination from the mutation pattern, not from the table widget. If ordinary inserts can change what “next” means, the continuation itself deserves first-class design.

Recommendations Are Not Decisions: Designing an Auditable Human Boundary

Wed, 23 Sep 2026 14:53:09 +0000

Software is very good at making a calculation look authoritative. Give a rule engine enough inputs and it can return a crisp result in milliseconds. In a consequential workflow, that neatness is dangerous: a computed recommendation can quietly become a decision without anyone deliberately granting it that authority.

A better design treats computation and authority as different responsibilities. The software may evaluate evidence, explain what it found, and suggest an outcome. A person still records the actual decision. The data model preserves both.

That separation is more than a user-interface disclaimer. It has to reach the evaluator, persistence model, activation workflow, and tests.

Keep the evaluator pure

Start with an evaluator that has no write path. It accepts a versioned rule and a set of observations, then returns an explanation:

which inputs contributed;
which requirements passed or failed;
what evidence was missing;
which rule version was used; and
what outcome, if any, is suggested.

The return value should say “suggested,” not “decided.” Naming is not sufficient, but it makes accidental authority harder to hide.

Purity matters here. A preview operation should be safe to run repeatedly without creating decisions, sending notifications, or mutating state. That keeps calculation testable and prevents a read-like action from acquiring an unexpected side effect.

When essential evidence is missing, the evaluator should return an advisory state with no suggestion. A nullable recommendation can be a feature: it says the software cannot justify a conclusion. Returning the most likely answer would make uncertainty easy to rubber-stamp.

Make rules prove their intended behaviour

Syntactically valid configuration is not the same as reviewed policy. A collection of thresholds can pass field validation and still express something the author did not mean.

Before a configurable rule becomes active, require named worked examples. Each example contains representative inputs and the outcome the author expects. Activation replays every example through the same evaluator used by real records. If one disagrees, activation stops.

Using the same evaluator is important. A second “fixture evaluator” would only prove that two implementations can disagree in production.

Malformed examples should fail before replay. If a parser silently misreads an input and the example happens to reach the expected result, the gate gives false confidence. An explicit failure is safer than a coincidental pass.

These examples act as executable policy conversations. They let reviewers ask, “What should happen in this borderline case?” before the rule affects a real decision.

Persist recommendation and decision separately

The final record should not overwrite the computed recommendation. Store both:

the recommendation available at decision time;
the outcome the person recorded;
the exact rule version that informed it;
the actor and timestamp; and
a reason when the decision departs from the recommendation.

This turns disagreement into useful data instead of treating it as an error to conceal. A departure may reveal legitimate context that the model deliberately does not represent. It may also reveal a weak rule. Either way, preserving both facts makes later review possible.

The same principle applies to overrides. Do not edit the old outcome in place. Append a new version, mark it as current, retain the previous value, and require a reason. Historical records should describe what was known and decided then—not what today’s configuration would calculate now.

Pinning the rule version is crucial. If a rule changes next month, an old decision must still point to the version that produced its original recommendation. Otherwise, history becomes a moving target.

Test the boundary, not only the formula

Formula tests are necessary, but the more revealing tests are often about authority and time.

Useful cases include:

previewing produces an explanation and writes nothing;
missing essential evidence produces no recommendation;
a rule without worked examples cannot be activated;
an example that disagrees with the rule blocks activation;
departing from a recommendation without a reason is refused;
an override appends a version instead of editing history; and
changing a rule later does not alter an already recorded decision.

These tests express the operating model. They protect not only mathematical correctness, but also who is allowed to decide and whether past context remains trustworthy.

Accept the deliberate friction

This approach costs more than returning an enum and saving it. It introduces draft and active rule states, advisory outcomes, versioned decisions, reasons, worked examples, and review steps. Operators need to understand the distinction. Developers have more invariants to maintain.

That friction should be proportional to consequence. A low-stakes recommendation may not need an append-only ledger. A decision affecting access, eligibility, money, safety, or a person’s future probably deserves more than an opaque calculation.

Worked examples also have limits. They prove that the authored rule behaves as expected on selected cases. They do not prove that the policy is fair, lawful, complete, or statistically sound. Human approval can still be mistaken. Permissions, peer review, monitoring, and periodic policy review remain necessary.

A practical design question

When reviewing a rule-driven workflow, ask one question first: is this output evidence for a decision, or is the system silently making the decision itself?

If the answer matters, create a visible boundary. Keep evaluation pure. Refuse to guess when evidence is insufficient. Gate activation with executable examples. Record human choices separately. Preserve departures and history.

The goal is not to weaken automation. It is to make its authority honest.

cTrader cBot Risk Engine: High-Precision C# Dynamic Stop-Loss Architecture

Mon, 21 Sep 2026 08:26:11 +0000

Static stop-losses break across volatility regimes. A fixed 20-pip stop that is conservative on EUR/USD during Asia session is noise-level on XAU/USD during New York open. In cTrader Automate (C#), the robust pattern is a dedicated risk engine: signal logic decides direction, the engine decides size and stop distance from live volatility.

This post documents the architecture — educational, no trade signals, no return claims.

1. Separate Sizing From Signals

The most common cBot flaw is inline risk math inside OnBar(): volume computed next to entry conditions, stop distance hardcoded. When volatility doubles, the same stop gets hunted and the same volume carries twice the dollar risk.

Split the cBot into two units:

Signal module — produces direction only (e.g., breakout, trend filter).
Risk engine — given direction, computes stop distance from ATR and volume from a fixed monetary budget.

// RiskEngine.cs — pure logic, no cTrader dependencies (unit-testable)
public static class RiskEngine
{
    public static double StopDistancePrice(double atr, double multiplier)
    {
        return atr * multiplier;
    }

    public static long VolumeInUnits(double riskMoney, double stopDistancePrice,
                                     double tickValuePerUnit, double pipSize,
                                     long volumeMin, long volumeMax, long volumeStep,
                                     out bool clampedToMin, out double effectiveRisk)
    {
        double raw = riskMoney / (stopDistancePrice / pipSize * tickValuePerUnit);
        long floored = (long)Math.Floor(raw / volumeStep) * volumeStep;
        clampedToMin = false;
        if (floored < volumeMin) { floored = volumeMin; clampedToMin = true; }
        long finalVolume = Math.Min(floored, volumeMax);
        effectiveRisk = finalVolume * (stopDistancePrice / pipSize * tickValuePerUnit);
        return finalVolume;
    }
}

Note the clampedToMin flag: when the budgeted volume falls below the broker minimum, the engine clamps up and reports the effective risk, which now exceeds the budget. Silently reporting the original budget while carrying higher exposure is the exact failure we dissected in The Silent Position Sizer Bug — never repeat it.

2. ATR-Based Dynamic Stops

Average True Range adapts the stop to current volatility. A 1.5x–2.0x ATR stop keeps the exit outside normal noise on any symbol and any session:

private double GetAtrStopPips(int atrPeriod = 14, double multiplier = 2.0)
{
    var atr = Indicators.AverageTrueRange(atrPeriod, MovingAverageType.Exponential);
    double stopPrice = atr.Result.LastValue * multiplier;
    return stopPrice / Symbol.PipSize;
}

Because the stop distance is measured, not assumed, the same cBot behaves sanely on a 0.0001-pip Forex pair and a 2-decimal metal without retuning magic numbers.

3. Wiring It Into the cBot

Volume in cTrader is expressed in units (100,000 units = 1.0 standard lot on FX). Always read the broker limits from the symbol — never hardcode them:

protected override void OnBar()
{
    if (Positions.Count > 0) return; // single-position example
    if (!GetSignal()) return;

    double stopPips = GetAtrStopPips();
    double stopPrice = stopPips * Symbol.PipSize;

    long volume = RiskEngine.VolumeInUnits(
        RiskMoney, stopPrice, Symbol.TickValue / Symbol.TickSize * Symbol.PipSize,
        Symbol.PipSize, Symbol.VolumeInUnitsMin,
        Symbol.VolumeInUnitsMax, Symbol.VolumeInUnitsStep,
        out bool clamped, out double effectiveRisk);

    if (clamped)
        Print("WARNING: volume clamped to broker minimum. " +
              "Effective risk {0} exceeds budget {1}.", effectiveRisk, RiskMoney);

    ExecuteMarketOrder(TradeType.Buy, SymbolName, volume,
                       "atr-risk", stopPips, null);
}

4. Trailing Without Chasing

Move the stop only when price has banked a multiple of the ATR distance — ratcheting on every tick bleeds to spread:

private void TrailAtr(Position position, double atrDistancePrice)
{
    double newStop = Symbol.Bid - 1.0 * atrDistancePrice; // long example
    if (newStop > position.StopLoss + Symbol.PipSize)
        ModifyPosition(position, newStop, position.TakeProfit);
}

5. Validation Checklist (Demo First)

Run 60 days on demo across at least two volatility regimes (e.g., Forex + metal).
Log every clamp event; if clamps exceed ~5% of trades, the risk budget is too small for the account — top up or widen the stop, never silence the warning.
Backtest with real-tick data; reject any result you cannot reproduce forward on demo.

Educational content under Colombia SFC Decreto 2555 de 2010: this is financial-engineering study material, not investment advice. No signals, no managed accounts.

By Mahdi Goodarzi (g.dev/mahdigoodarzi), Gueta Quant — interactive risk tools at guetaquant.com. Companion guide: cTrader Copy setup in Colombia.

Pagination Is a Consistency Contract

Sun, 20 Sep 2026 07:52:36 +0000

Page numbers feel harmless. They are familiar, easy to render, and easy to explain. But on a mutable work queue, they can lie.

Imagine a reviewer reading a newest-first queue. They load the first 25 items. Before they request the next page, a new item arrives at the top. An offset such as skip 25 now starts one row later than it would have a moment ago. The last row from page one may appear again, and the row displaced by the insert may never appear in that walk.

Nothing crashed. No error was logged. The interface simply presented an inconsistent view of the work.

The engineering lesson is that pagination over changing data is a consistency contract, not a decorative control beneath a table.

Begin with the mutation model

The right pagination strategy depends on how the collection changes.

For an append-mostly queue ordered newest first, new work normally arrives above the operator's current position. Other fields, such as workflow status, may change while the operator is reviewing an item. Those two facts suggest a useful boundary: continue from something fixed when the item entered the queue, not from a mutable field and not from the current numeric position.

A submission timestamp can provide that boundary if it is frozen when the item is created. Status usually cannot; ordering by status lets a decision move rows between pages while someone is walking the list.

The principle is broader than timestamps: choose an ordering key whose meaning remains stable for the duration of a walk.

Make the server own the continuation

A client should not reconstruct position from a page number, a visible row, or a guessed offset. The server should return an opaque continuation and accept it unchanged on the next request.

For a newest-first queue, a continuation can describe the last timestamp boundary and how many rows at that exact instant have already been emitted. The next query includes rows at or below the boundary, skips only the already-seen ties at that boundary, and takes one extra row to determine whether another page exists.

Why count ties instead of comparing an identifier? Identifier ordering is not always portable across database providers. Let the query provider apply its established ordering, and record only how far through the boundary group the walk has progressed.

Opaque does not mean unchecked. Reject blank, malformed, oversized, or unsupported continuations. A bad continuation should not silently restart at the top, because a restart looks like valid data with unexplained duplicates.

Bind position to query context

A continuation names a position in one specific ordered result set. Change the filter and that position may no longer mean anything.

Suppose page one was filtered to one workflow cycle, then the same continuation was replayed with the filter removed. Honouring it could skip rows that were never part of the original walk. The continuation should therefore carry enough context to prove it belongs to the active query. If the context differs, refuse the request and let the client restart explicitly.

The same discipline applies to page size. Put a small upper bound in the contract and reject values outside it. Quietly shrinking an oversized request hides caller mistakes; accepting it defeats the point of paging.

Bounding the first query is only half the work. If each row needs evidence, comments, or another related record, fetch those details only for identifiers on the current page. Otherwise an apparently paged endpoint can still perform an unbounded secondary read.

Preserve the operator's place

Continuation cursors naturally move forward. A usable review screen also needs Back and refresh.

The client can keep a short trail of the server-provided continuations used to open each visited page. Previous then replays the cursor that originally opened the prior page. The client is not interpreting the cursor; it is remembering the path.

After a reviewer changes an item, refresh the page they are currently viewing. Returning to page one after every decision is technically simple and operationally punishing. It also encourages people to work around the interface rather than trust it.

There is one awkward edge case: a later page may become empty before it is refreshed. Do not render a global empty-state message that implies the entire queue has vanished. Reset to the first page and show the current truth from a valid starting position.

Test the walk, not only the query

Happy-path tests that assert “25 rows returned” are not enough. The important properties live between requests.

Useful executable checks include:

a new item arriving above the boundary neither duplicates nor hides an existing row;
a workflow status change does not alter page membership;
several items sharing one timestamp are neither repeated nor lost;
a continuation cannot be replayed with a different filter;
malformed continuations and invalid page sizes are refused;
forward and backward navigation use the exact server continuations;
a write refreshes the active page; and
an empty later page recovers without claiming the whole queue is empty.

These tests describe the contract more clearly than the word “paged” ever could.

The trade-off is explicit complexity

Cursor paging asks more of both sides. The server must define and validate a stable continuation. The client must retain a small history. Ties and disappearing pages need deliberate behaviour. Troubleshooting is less intuitive than looking at page=3 in a URL.

In return, database work stays bounded and a reviewer can walk a changing queue without silent duplicates or gaps. That is a worthwhile trade whenever missing one item matters more than keeping the paging code superficially simple.

Before choosing offsets for a mutable list, simulate one insert and one update between consecutive requests. If the same walk no longer produces the same set of rows, the pager needs a stronger contract.

Your Reader Cannot Be Stricter Than Your Schema

Thu, 17 Sep 2026 08:20:48 +0000

SingleOrDefault looks like a small query choice. In practice, it is an assertion about your data model: for this predicate, zero or one row may exist.

That assertion is valuable when storage enforces the same rule. When the database permits duplicates, however, the reader is relying on an invariant that does not exist. One unexpected row can turn an ordinary lookup into an exception before validation, authorization, or other normal handling begins.

I recently reviewed a committed recovery for exactly that class of mismatch. The useful lesson was not the specific lookup. It was how to contain the exception without pretending the data had become correct.

A query can encode a hidden contract

Consider a generalized account table:

Rows permitted by storage: 0..many per normalized key
Rows expected by reader:    0..1 per normalized key

The read path might be perfectly reasonable in isolation:

var record = await records.SingleOrDefaultAsync(x => x.LookupKey == key);

But the method name does not create uniqueness. It only checks cardinality at read time. If two rows match, the query throws.

This is why I now treat Single and SingleOrDefault as executable invariant assertions. During review, I ask: what proves the invariant? A unique index? A constrained aggregate? A transactionally protected write path? Or only an earlier existence check that can race?

Containment is not repair

When duplicate data already exists, immediately adding a unique index may be unsafe. Migration can fail on the existing rows. Previously accepted imports or registrations may begin failing without a useful remediation path.

At the same time, leaving a critical read path to throw can make a narrow data defect disproportionately disruptive.

A staged response separates two goals:

Containment: provide a deterministic, non-crashing resolution path while preserving security and making the defect visible.
Correction: repair the existing data and enforce the intended rule for future writes.

The distinction matters. A tolerant reader is a recovery mechanism, not evidence that duplicates are acceptable.

Properties of a safe recovery path

A useful containment pattern keeps the normal case boring:

try
{
    return await ReadExpectedSingleAsync(key);
}
catch (InvalidOperationException)
{
    var matches = await ReadBoundedCandidatesAsync(key);
    if (matches.Count < 2)
        throw;

    ReportCollision(matches.Select(x => x.OpaqueId));
    return ChooseDeterministically(matches);
}

This sketch is intentionally incomplete, but it highlights several important properties.

Keep the fast path unchanged

Most lookups are not ambiguous. Do not make every request pay for a corruption-recovery query. Invoke the fallback only after the expected lookup demonstrates the precise failure you are prepared to handle.

Prove ambiguity before handling it

InvalidOperationException can come from many places. Catching it and returning “not found” would turn an unrelated store failure into a silent wrong answer. Re-query narrowly; if there are not actually multiple matches, rethrow the original fault.

Choose deterministically

Never accept database enumeration order as a resolution policy. Define explicit ranking from legitimate domain facts, then add a stable final tie-break. The same data must produce the same candidate on every attempt.

Determinism does not make the selected record correct. It prevents the recovery itself from becoming random.

Preserve downstream verification

Resolving one candidate must not grant access, approve a transaction, or bypass an eligibility rule. Credential checks, authorization, state validation, and other security decisions still run after resolution. Containment should make the lookup deterministic, not weaken the boundaries that follow it. A legitimate candidate may still lose the ranking, so some affected operations can remain unavailable until the data is repaired.

Bound and observe the fallback

A pathological key should not cause an unbounded scan during a critical request. Cap diagnostic reads, raise a high-signal operational event, and log only what responders need. Opaque record identifiers may support repair; the sensitive lookup value often does not belong in logs.

The stronger end state lives in storage

After containment, the work is not finished. The durable sequence is usually:

inventory collisions
-> decide merge or deletion policy
-> repair existing rows
-> reject or reconcile conflicting writes
-> add the storage constraint
-> remove or narrow temporary recovery code

For relational data, that often means a unique index aligned with the normalization and null semantics used by the application. The write path should return a useful domain result when the constraint rejects a conflict. A pre-insert lookup can improve the message, but the database remains the concurrency-safe authority.

There is a real trade-off. Immediate enforcement gives the cleanest future guarantee but can break deployment against historical data. Temporary tolerance contains the exception but adds policy, cannot guarantee later verification will succeed, and can become permanent by neglect. Treat it as migration work with an owner, telemetry, and an exit condition.

Test the invariant and the escape hatch

Focused tests should cover more than “duplicates do not throw.” I would pin:

the ordinary single-row path remains untouched;
selection is stable when candidates arrive in different orders;
inactive or retired records cannot outrank valid ones;
unrelated exceptions escape unchanged;
downstream verification still decides the outcome;
diagnostics contain repairable identifiers but no sensitive key;
the candidate read is bounded;
the future uniqueness constraint rejects a conflicting concurrent write.

The deeper lesson is architectural: reads, writes, and storage must agree on cardinality. If a reader says “exactly one,” make that promise explicit at the boundary able to enforce it. Until then, the code is not reading an invariant. It is discovering, at runtime, whether the hope was true.

OpenSKP 1.1.0: A Native .skp Writer, Now in All Five Languages

Wed, 16 Sep 2026 15:34:15 +0000

Until 1.1.0, OpenSKP was a read path. You could parse a .skp file — either container format, all five languages — and get materials, layers, geometry, and metadata out of it. What you couldn't do was make a new one. 1.1.0 closes that gap: a real writer, producing files SketchUp itself opens without complaint, shipped in Python, TypeScript, .NET, Dart, and C++ at the same time.

Why write support is a different problem than read support

Parsing forgives sloppiness in a way writing doesn't. A parser that mishandles an obscure edge case just gets slightly wrong data for that one field — annoying, but survivable, and often invisible unless you're specifically checking. A writer that gets the container format wrong produces a file that SketchUp refuses to open at all, or worse, opens with silently corrupted geometry. There's no partial credit.

That asymmetry shaped how the writer got built. It targets the modern VFF container exclusively — the ZIP-based, TLV-tree format used by SketchUp 2021 and later — rather than also targeting the legacy MFC stream format, because VFF is what every current SketchUp install expects by default and where new files should live going forward. Every writer feature was validated the same way the parser's correctness was validated originally: produce a file, open it with the real SketchUp SDK, and confirm the SDK's own reading of geometry, materials, and layer assignments matches what was intended, field by field — not just "the file has a size greater than zero and doesn't crash on open."

What the writer actually does

The API surface is intentionally generic rather than shaped around specific object types. There's no Chair class or Table builder baked into the library — you compose scenes out of the same primitives SketchUp itself works with:

Materials — solid colors, opacity, and image textures
Layers (tags) — for organizing geometry the way SketchUp's own Tags panel does
Groups and component definitions — the same grouping/instancing model SketchUp uses natively, including nested groups
Curves and faces — arbitrary polygon geometry with material and layer assignment per face
create() for a brand-new file, and open_existing() for loading a file, editing it, and writing it back out

open_existing() in particular was the harder of the two entry points to get right. It isn't a byte-patcher that finds the one chunk you touched and surgically rewrites it in place — that approach is fragile against any structural change (add a face, and every downstream offset in the container shifts). Instead it does a full parse of the existing file into the same in-memory model the writer already knows how to serialize, applies your edits to that model, and replays the entire thing back out through the same write path a brand-new file goes through. Slower than a patch, but correct by construction: if create() is trustworthy, open_existing() inherits that trust instead of needing its own separate proof.

Five ports, five different sets of bugs

The writer shipped in Python first, since Python was already the most mature of the five ports and the fastest place to validate the design against the real SDK. Porting it to the other four languages wasn't a mechanical translation exercise — each port's own CI caught real, language-specific problems that the Python reference implementation simply couldn't have surfaced:

C++ — a check_writable helper failed to compile under the CI's stricter build flags, a class of error Python's dynamic typing has no equivalent to catching until runtime, if at all. The C++ port also turned up a clang-format issue where the CI's diff report was silently truncating on longer violations, which needed fixing in the tooling itself before it could be trusted to gate anything.
Dart — trigonometric rounding in transform-matrix math didn't match the other languages' output bit-for-bit, traced to a difference in how Dart's math library rounds versus Python's, and fixed by aligning the rounding step explicitly rather than relying on each language's default behavior.
Two of the ports hit test-ordering bugs — tests that passed individually but failed when run as part of the full suite, because they shared mutable fixture state that Python's test runner happened to isolate in a way the other runner didn't by default.

None of these were writer-logic bugs in the sense of "the geometry is wrong." They were the ordinary friction of porting real, non-trivial code across five different type systems, build toolchains, and test runners — exactly the kind of thing that's invisible if you only ever ship one language, and exactly why keeping five active ports is more expensive than it sounds, but catches more than a single-language project ever would.

Shipping five packages at once

1.1.0 went out to all five registries in the same release cycle — PyPI, npm, NuGet, pub.dev, and a tagged GitHub Release with prebuilt C++ artifacts (C++ has no package registry equivalent, so it ships as a downloadable tarball/zip pair instead). Coordinating that many release pipelines in one pass surfaced two more process-level snags worth naming honestly: a batched multi-language tag push needed the tags separated out per-language rather than pushed as one lump, and pub.dev's own publish flow has a gotcha around tag naming that isn't obvious until it rejects a push.

Neither was a code bug. Both are the kind of thing you only learn by actually running a five-language release end to end, which is exactly what 1.1.0 forced.

What's next

Read and write both exist now, but write support is currently VFF-only — no legacy-MFC writing, and no re-encoding a legacy file into the modern container. Conversion the other direction (glTF, IFC, OBJ into .skp) is on the roadmap but not started. If either of those is something you'd use, the issue tracker is open.

Install:

pip install openskp          # Python
npm install openskp          # TypeScript / JavaScript
dotnet add package OpenSKP   # .NET
dart pub add openskp         # Dart

OpenSKP is open source under the MIT license: github.com/iamahsanmehmood/openskp

Originally published at openskp.com and DEV Community.

Tuesday Coding Tip 21 — Dangers of Enums

Tue, 08 Sep 2026 09:59:00 +0000

C++ and C# have a caveat in their enum types. Each enum has an underlying storage type which limits a maximum number of values and how much space it takes in memory. However, it also works the other way — it says how many distinct values the enum handles.

If you define an enum with just three values, if it has an underlying type of uint8, it handles 256 distinct values. You can take any integer up to 255, cast it to that enum type, and get a “valid” value. When branching on an enum, you need to keep in mind that you might get an undefined value, especially if it was deserialized from the wire.

To add insult to injury, compilers won’t warn you by default. Only pattern matching does for C#. C++ can warn you if you don’t cover a defined enum value in a switch statement, but you must not use the default case — preventing you from correctly handling ill-formed values.

#include <iostream>

enum class Mode : char {
    Primary,
    Secondary
};

std::string to_string(Mode mode)
{   
    switch (mode)
    {
        case Mode::Primary: return "Primary";
        // With -Wswitch-enum
        // warning: enumeration value 'Secondary' not handled in switch
    }
}

std::string to_string2(Mode mode)
{
    switch (mode)
    {
        case Mode::Primary: return "Primary";
        // With -Wswitch-enum
        // no other warning
        default: return "Undefined";
    }
}

std::string to_string3(Mode mode)
{
    switch (mode)
    {
        case Mode::Primary: return "Primary";
        case Mode::Secondary: return "Secondary";
        // With -Wswitch-enum
        // no other warning
    }
}

int main()
{
    auto&& str = to_string3(static_cast<Mode>(42));
    std::cout << str << std::endl; // Output is an undefined behaviour
    return 0;
}

C# API CRUD Done Wrong, Then Done Right: A Complete Bad-Practices-vs-Best-Practices Walkthrough

Fri, 04 Sep 2026 14:12:06 +0000

Most bad-code examples in tutorials are contrived - obviously wrong in a way real code never actually looks. This post takes a different approach: a complete, realistic Product CRUD API, built with thirteen anti-patterns that genuinely show up in codebases. Each endpoint is walked through one at a time - the bad version, exactly what's wrong with it and why, then the good version, right next to each other, so nothing needs to be hunted down elsewhere on the page.

The scope: a Product entity, five CRUD endpoints - GetAll, GetById, Create, Update, Delete.

Shared Setup: Program.cs

Bad version:

var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddControllers();
builder.Services.AddSingleton<ProductsController>();
 
var app = builder.Build();
app.MapControllers();
app.Run();
 
// Inside ProductsController itself:
private readonly string _connectionString =
    "Server=prod-sql-01;Database=Products;User Id=sa;Password=Passw0rd123!;";

Issues:

Hardcoded connection string. A literal password is committed directly into source code. Anyone with repository access, including, eventually, anyone the repository is ever accidentally exposed to, has the production database password in plain text.
The fix: load the connection string from configuration, appsettings.json locally, environment variables or Key Vault in production, never as a literal string in a class.
Incorrect service lifetime, AddSingleton for a controller. Manually registering the controller itself with AddSingleton means exactly one instance of ProductsController is created and shared across every single request for the entire lifetime of the application, rather than the framework creating a fresh instance per request the normal way. This becomes genuinely dangerous the moment that controller, or anything it depends on, holds any per-request state, and it gets worse once a Scoped dependency like a DbContext enters the picture, since DbContext is explicitly not thread-safe and is designed to live for exactly one request. A Singleton capturing a Scoped dependency is a well-known anti-pattern called a "captive dependency" - the Scoped service effectively gets trapped inside the Singleton's lifetime, silently becoming a de facto singleton itself, shared across requests and threads it was never designed to be shared across.
The fix: never manually register a controller at all, AddControllers() already handles controller instantiation correctly per request, and give each dependency the lifetime that actually matches how it's meant to be used, which for something wrapping a DbContext means Scoped.

Good version:

var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddDbContext<ProductDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("ProductsDb")));
 
builder.Services.AddScoped<IProductService, ProductService>();
builder.Services.AddControllers();
 
var app = builder.Build();
app.MapControllers();
app.Run();

The connection string now comes from configuration. IProductService is registered as Scoped, not Singleton, one instance per HTTP request, matching the lifetime of the DbContext it wraps, and avoiding the captive dependency problem entirely. The controller itself is never manually registered at all; AddControllers() handles that correctly on its own.

Shared Setup: The Product Entity

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public int StockQuantity { get; set; }
    public string InternalSupplierNotes { get; set; }
    public decimal CostPrice { get; set; }
}

Identical in both versions - the entity itself isn't the problem. InternalSupplierNotes and CostPrice are genuinely internal fields, what the business actually pays a supplier, never meant for a customer-facing API to expose. What differs between versions is whether this exact class ever gets returned to a caller directly, covered in the GetById section below.

Endpoint 1: GetAll

Bad version:

[HttpGet]
public IActionResult GetAll()
{
    var products = GetAllProductsAsync().Result;
    return Ok(products);
}
 
private async Task<List<Product>> GetAllProductsAsync()
{
    var products = new List<Product>();
    using var connection = new SqlConnection(_connectionString);
    await connection.OpenAsync();
 
    var command = new SqlCommand("SELECT * FROM Products", connection);
    var reader = await command.ExecuteReaderAsync();
 
    while (await reader.ReadAsync())
    {
        products.Add(new Product
        {
            Id = reader.GetInt32(0),
            Name = reader.GetString(1),
            Price = reader.GetDecimal(2)
        });
    }
    return products;
}

Issues:

Missing await, .Result blocks the thread. GetAllProductsAsync().Result synchronously blocks the calling thread while waiting for the async method to complete, defeating the entire purpose of async and await, since the thread sits idle instead of being released back to the pool. In certain synchronization contexts, classic ASP.NET, WPF, WinForms, this specific pattern can cause a genuine deadlock.
The fix: use await all the way up the call chain, never call .Result or .Wait() on an async method.
Undisposed SqlCommand and SqlDataReader. Both command and reader implement IDisposable, but only connection gets a using statement here. SqlDataReader in particular keeps the underlying connection in a busy state until it's explicitly closed, so under real load, with many concurrent requests each doing this, connections return to the pool later than they need to, risking pool exhaustion faster than necessary. The outer using on connection happens to clean these up indirectly when it disposes, which is what keeps this specific method from actively breaking right now, but relying on that indirect cleanup rather than disposing each IDisposable explicitly is fragile, and won't hold up if the method returns early or the pattern changes later.
The fix: wrap every IDisposable in its own using statement, not just the outermost one.

Good version:

[HttpGet]
public async Task<ActionResult<List<ProductDto>>> GetAll()
{
    var products = await _productService.GetAllAsync();
    return Ok(products);
}
 
// Inside ProductService:
public async Task<List<ProductDto>> GetAllAsync()
{
    return await _context.Products
        .Select(p => new ProductDto
        {
            Id = p.Id,
            Name = p.Name,
            Price = p.Price,
            StockQuantity = p.StockQuantity
        })
        .ToListAsync();
}

Genuinely awaited from the controller all the way through the service call. EF Core's LINQ query is also parameterized automatically and projects directly to ProductDto - a preview of the DTO pattern the next endpoint introduces properly. There's also no manual connection, command, or reader to dispose at all here - EF Core's DbContext and its query execution manage the underlying ADO.NET resources internally, which is one more reason the disposal issue from the bad version simply can't occur in this version.

Endpoint 2: GetById

Bad version:

[HttpGet("{id}")]
public IActionResult GetById(int id)
{
    using var connection = new SqlConnection(_connectionString);
    connection.Open();
 
    var query = "SELECT * FROM Products WHERE Id = " + id;
    var command = new SqlCommand(query, connection);
    var reader = command.ExecuteReader();
 
    if (!reader.Read())
    {
        return Ok(null);
    }
 
    var product = new Product
    {
        Id = reader.GetInt32(0),
        Name = reader.GetString(1),
        Price = reader.GetDecimal(2)
    };
 
    return Ok(product);
}

Issues:

SQL injection. The id parameter is concatenated directly into the query string. A request to /api/products/1;DROP TABLE Products-- executes exactly that.
The fix: never build SQL by concatenating user input, use a parameterized query, or an ORM like EF Core that parameterizes automatically.
Ok(null) instead of NotFound(). When the product doesn't exist, this returns a 200 OK with an empty body. The caller can't distinguish "found nothing" from "succeeded, and the answer happens to be nothing," both look identical on the wire.
The fix: return NotFound(), a genuine 404, so the status code itself carries the information.
No DTO, full entity exposed. The returned product is the raw entity, including InternalSupplierNotes and CostPrice, fields that should never reach an API caller.
The fix: map to a ProductDto containing only the fields meant to be public.

Good version:

public class ProductDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public int StockQuantity { get; set; }
}
 
[HttpGet("{id}")]
public async Task<ActionResult<ProductDto>> GetById(int id)
{
    var product = await _productService.GetByIdAsync(id);
 
    if (product == null)
        return NotFound();
 
    return Ok(product);
}
 
// Inside ProductService:
public async Task<ProductDto?> GetByIdAsync(int id)
{
    var product = await _context.Products.FindAsync(id);
    // FindAsync uses the primary key safely - parameterized
    // automatically, no string concatenation anywhere
 
    if (product == null)
        return null;
    // Returning null here is fine - it's the CONTROLLER's
    // job to translate this into the correct HTTP response,
    // not the service's
 
    return new ProductDto
    {
        Id = product.Id,
        Name = product.Name,
        Price = product.Price,
        StockQuantity = product.StockQuantity
    };
}

All three issues fixed together: FindAsync makes SQL injection structurally impossible, NotFound() makes the response honest, and ProductDto makes leaking internal fields impossible rather than something to remember not to do.

Endpoint 3: Create

Bad version:

[HttpPost]
public IActionResult Create(Product product)
{
    using var connection = new SqlConnection(_connectionString);
    connection.Open();
 
    var query = $"INSERT INTO Products (Name, Price) " +
                 $"VALUES ('{product.Name}', {product.Price})";
    var command = new SqlCommand(query, connection);
    command.ExecuteNonQuery();
 
    _logger.LogInformation(
        "Product created by user {Email} with auth token {Token}: {Name}",
        currentUser.Email, currentUser.AuthToken, product.Name);
 
    return Ok(product);
}

Issues:

No validation. A request with an empty Name, a negative Price, or missing fields is accepted exactly as-is.
The fix: add validation attributes to a dedicated input DTO, paired with ApiController's automatic model validation.
SQL injection, again. Same pattern as GetById, product.Name concatenated directly, and this version breaks entirely if the name contains a single quote.
The fix: same as before, EF Core, parameterized automatically.
Wrong status code. Returns 200 OK for a successful creation.
The fix: 201 Created, with a Location header pointing to the new resource, since 200 doesn't communicate "a new thing was created."
Sensitive data logged in plain text. The user's email is reasonable to log, but the auth token is a genuine secret, and it's now sitting in plain text inside Application Insights or Log Analytics, visible to anyone with read access to logs, often retained for weeks or months. A leaked or overly-permissioned log query becomes a credential leak.
The fix: never log secrets, tokens, passwords, or other sensitive fields, log an identifier (a user ID) instead of the credential itself, and if a field must be referenced for debugging, mask or redact it before it reaches the logger.

Good version:

public class CreateProductDto
{
    [Required, MaxLength(200)]
    public string Name { get; set; }
 
    [Range(0.01, 1000000)]
    public decimal Price { get; set; }
 
    [Range(0, int.MaxValue)]
    public int StockQuantity { get; set; }
}
 
[HttpPost]
public async Task<ActionResult<ProductDto>> Create(CreateProductDto dto)
{
    // No manual validation check needed - [ApiController]
    // automatically returns 400 Bad Request if the DTO's
    // validation attributes aren't satisfied, before this
    // method body even runs
 
    var created = await _productService.CreateAsync(dto);
 
    _logger.LogInformation(
        "Product {ProductId} created by user {UserId}",
        created.Id, currentUser.Id);
    // Logs an IDENTIFIER, never a credential or token -
    // enough to trace who did what, without exposing
    // anything an attacker or an over-permissioned log
    // reader could actually use
 
    return CreatedAtAction(
        nameof(GetById),
        new { id = created.Id },
        created);
}
 
// Inside ProductService:
public async Task<ProductDto> CreateAsync(CreateProductDto dto)
{
    var product = new Product
    {
        Name = dto.Name,
        Price = dto.Price,
        StockQuantity = dto.StockQuantity
    };
 
    _context.Products.Add(product);
    await _context.SaveChangesAsync();
 
    return new ProductDto
    {
        Id = product.Id,
        Name = product.Name,
        Price = product.Price,
        StockQuantity = product.StockQuantity
    };
}

CreateProductDto's Required, MaxLength, and Range attributes are checked automatically by ApiController. CreatedAtAction returns the correct 201 with a Location header built from the GetById action. The log statement now records a user ID, not a credential, and EF Core removes the SQL injection path entirely.

Endpoint 4: Update

Bad version:

[HttpPut("{id}")]
public IActionResult Update(int id, Product product)
{
    try
    {
        using var connection = new SqlConnection(_connectionString);
        connection.Open();
 
        var query = $"UPDATE Products SET Name = '{product.Name}', " +
                    $"Price = {product.Price} WHERE Id = {id}";
        var command = new SqlCommand(query, connection);
        command.ExecuteNonQuery();
    }
    catch (Exception ex)
    {
        return Ok(new { error = ex.ToString() });
    }
 
    return Ok();
}

Issues:

Swallowed exception behavior masked as a response. The catch block doesn't silently discard the exception here, but it does something almost as problematic in a different way, it converts a failure into a 200 OK response body, meaning the HTTP status code itself claims success while the actual content says otherwise. Callers checking only the status code, which is the normal way to check for success, will treat this as a successful update.
The fix: return an actual error status code, and don't rely on the response body alone to communicate failure.
SQL injection, again. Same string-concatenation pattern as the previous two endpoints.
Full exception details leaked to the caller. ex.ToString() returns the complete exception message and full stack trace, including internal file paths, method names, and sometimes literal fragments of the failed SQL query itself, all sent directly to whoever called this endpoint. This is genuinely useful reconnaissance for an attacker probing the API, and it's an accidental disclosure of internal implementation detail even to a well-meaning caller.
The fix: log the full exception detail internally, server-side, and return only a generic, safe error message to the caller.

Good version:

[HttpPut("{id}")]
public async Task<IActionResult> Update(int id, CreateProductDto dto)
{
    var success = await _productService.UpdateAsync(id, dto);
 
    if (!success)
        return NotFound();
 
    return NoContent();
}
 
// Inside ProductService:
public async Task<bool> UpdateAsync(int id, CreateProductDto dto)
{
    var product = await _context.Products.FindAsync(id);
    if (product == null)
        return false;
 
    product.Name = dto.Name;
    product.Price = dto.Price;
    product.StockQuantity = dto.StockQuantity;
 
    try
    {
        await _context.SaveChangesAsync();
        return true;
    }
    catch (DbUpdateException ex)
    {
        // The FULL exception, including stack trace, is
        // logged INTERNALLY here - visible to the team via
        // Application Insights, never sent to the caller
        _logger.LogError(ex, "Failed to update product {Id}", id);
        return false;
    }
}

The exception is now caught narrowly, DbUpdateException, not the broad Exception base class, logged internally in full detail with _logger.LogError, and the method returns false so the controller responds with a correct NotFound or, in a fuller version, a generic 500 with a safe message, never the raw exception content itself.

Endpoint 5: Delete

Bad version:

[HttpDelete("{id}")]
public IActionResult Delete(int id)
{
    using var connection = new SqlConnection(_connectionString);
    connection.Open();
 
    var query = "DELETE FROM Products WHERE Id = " + id;
    var command = new SqlCommand(query, connection);
    command.ExecuteNonQuery();
 
    return Ok();
}

Issues:

SQL injection, again. The same concatenation pattern as every other endpoint above.
Wrong status code. Returns 200 OK with no body for a successful delete. The fix: 204 No Content, the correct response when an operation succeeds and there's genuinely nothing further to return.

Good version:

[HttpDelete("{id}")]
public async Task<IActionResult> Delete(int id)
{
    var success = await _productService.DeleteAsync(id);
 
    if (!success)
        return NotFound();
 
    return NoContent();
}
 
// Inside ProductService:
public async Task<bool> DeleteAsync(int id)
{
    var product = await _context.Products.FindAsync(id);
    if (product == null)
        return false;
 
    _context.Products.Remove(product);
    await _context.SaveChangesAsync();
    return true;
}

The Complete Good-Version Service Interface

Pulling every service method from above together into the one interface the controller actually depends on:

public interface IProductService
{
    Task<List<ProductDto>> GetAllAsync();
    Task<ProductDto?> GetByIdAsync(int id);
    Task<ProductDto> CreateAsync(CreateProductDto dto);
    Task<bool> UpdateAsync(int id, CreateProductDto dto);
    Task<bool> DeleteAsync(int id);
}

This is the layer that never existed in the bad version at all, the bad controller talked directly to SqlConnection. Having this interface is also what makes the controller genuinely unit-testable with a mock, something effectively impossible against the bad version's design.

Attribute Reference: What's Doing the Actual Work

ApiController enables automatic model validation, checking a DTO's validation attributes and returning 400 automatically if they fail, before the action method body runs. Present in both versions, but only doing real work in the good one, since the bad version's Product parameter has no validation attributes for it to check.

Route with the controller token sets the base route, "api/products," identical in both versions.

HttpGet, the id-scoped HttpGet, HttpPost, the id-scoped HttpPut, and the id-scoped HttpDelete map each method to its HTTP verb and route, the routing itself was never the problem in the bad version.

Required, MaxLength, and Range on CreateProductDto are declarative validation rules, good version only, paired with ApiController to reject invalid requests automatically, with zero manual if-checks.

Every Issue, At a Glance

Hardcoded connection string, in Program.cs and setup.
Bad: literal password committed in source code.
Good: loaded from configuration or Key Vault.
Incorrect service lifetime, AddSingleton for a controller, in Program.cs and setup.
Bad: the controller manually registered as Singleton, one shared instance forever, risking a captive dependency once a Scoped DbContext enters the picture.
Good: the controller is never manually registered at all, and IProductService is registered as Scoped, matching the DbContext's own lifetime.
Missing await / .Result, in GetAll.
Bad: .Result blocks the thread synchronously.
Good: await released the thread properly, all the way through.
Undisposed SqlCommand and SqlDataReader, in GetAll.
Bad: only connection wrapped in a using, command and reader never explicitly disposed, relying on indirect cleanup that isn't reliable.
Good: EF Core manages the underlying ADO.NET resources internally, so there's no manual disposal to get wrong.
SQL injection, appearing in GetById, Create, Update, and Delete.
Bad: string-concatenated raw SQL.
Good: EF Core LINQ or FindAsync, parameterized automatically.
Ok(null) instead of NotFound(), in GetById.
Bad: 200 OK with a null body when not found.
Good: NotFound(), a genuine 404.
No DTOs, full entity exposed, in GetById.
Bad: internal fields like CostPrice and supplier notes exposed.
Good: ProductDto excludes them entirely, structurally impossible to leak.
No validation, in Create.
Bad: any data accepted as-is.
Good: Required, MaxLength, and Range attributes plus ApiController auto-reject invalid requests.
Wrong status codes, in Create and Delete.
Bad: 200 OK for create and delete.
Good: 201 Created with a Location header for create, 204 No Content for delete.
Sensitive data logged in plain text, in Create.
Bad: an auth token logged directly, sitting in plain text in Application Insights.
Good: only a user ID logged, never a credential or token.
Swallowed exception behavior masked as a response, in Update.
Bad: a failure converted into a 200 OK response body, status code claims success while content says otherwise.
Good: an honest result returned, false propagated up so the controller can respond correctly.
Full exception details leaked to the caller, in Update.
Bad: ex.ToString(), including the full stack trace, returned directly in the API response.
Good: the full exception logged internally only, a generic safe message, if any, returned to the caller.
No service layer, structural, underneath all endpoints.
Bad: controller does raw data access directly.
Good: IProductService and ProductService, separated, testable, the natural home for every other fix.

Key Lessons

Every anti-pattern here is realistic, these are mistakes that genuinely appear in real production code, not exaggerated examples built just to be wrong.

The missing service layer is structurally connected to most of the other issues, a controller doing raw data access directly removes the natural place validation, parameterization, and error handling would otherwise live.

A DTO isn't just extra code, it's what makes leaking internal fields structurally impossible, rather than something a developer has to remember not to do.

Status codes are information, not decoration, Ok(null), 200 for a create, and 200 for a delete each communicate something genuinely false or ambiguous to the caller.

Logging and error responses are both genuine attack surfaces, not just debugging conveniences, a logged token or a leaked stack trace can hand an attacker exactly what they need, even when the code otherwise "works."

A swallowed exception, or one disguised as a success response, is worse than a crash, a crash is visible immediately, a silently hidden failure looks like success and can go unnoticed for a long time.

Summary

Every issue in the bad version compiles, runs, and looks like reasonable code at a glance, which is exactly why these patterns survive in real codebases far longer than obviously broken code ever would. Rebuilding the same five endpoints with a real service layer, correct dependency lifetimes, disciplined resource disposal, DTOs, parameterized queries, genuine async, proper validation, correct status codes, and careful logging doesn't just fix thirteen individual bugs, it changes the shape of the code so that several of those bugs become structurally difficult to reintroduce by accident.

Originally published at TechStack Blog: https://www.techstackblog.com/post.html?slug=csharp-api-crud-bad-vs-good-practices
More from TechStack Blog: C# / .NET: https://www.techstackblog.com/category.html?cat=csharp
CS Fundamentals: https://www.techstackblog.com/category.html?cat=cs-fundamentals

C# Coding Interview Prep Part 1: Variables, Strings, Arrays, Lists, Dictionaries, and Every Basic Building Block

Fri, 04 Sep 2026 14:08:32 +0000

This is a refresher built while preparing for C# coding interviews, and shared as a resource, because a genuinely comprehensive, practice-oriented guide is hard to find in one place. This series doesn't skip the basics to get to the "interesting" parts - the basics are exactly what trips people up under interview pressure, when a simple question about arrays suddenly requires recalling details nobody thinks about in day-to-day coding. Every topic in this series follows the same format: a plain-English explanation, an analogy, a code example, and a practice question at the end, so this can genuinely be used to test yourself, not just read passively.

This is Part 1 of three. Part 1 covers the basics - variables, data types, strings, arrays, List, Dictionary<TKey,TValue>, HashSet, tuples, value vs reference types, operators, control flow, loops, methods, enums, structs vs classes, nullable types, type conversion, and basic exception handling. Part 2 covers mid-level concepts - LINQ, generics, delegates and events, interfaces vs abstract classes, and exception handling in depth. Part 3 covers advanced concepts - async and Task, reflection, memory management and garbage collection, design patterns in practice, and performance considerations.

Topic 1: Variables and Data Types

A variable is a named storage location holding a value of a specific type. C# is statically typed - once a variable is declared with a type, it can only ever hold values of that type, or something compatible with it.

Think of a labeled storage box. A box labeled "int" can only hold integers - trying to put a sentence in it doesn't work, the same way a shoebox labeled for shoes doesn't neatly fit a stack of books.

// Value types - the actual data lives directly
// in the variable
int age = 30;
double price = 19.99;
bool isPublished = true;
char grade = 'A';
decimal exactMoney = 19.99m;  // decimal for money -
                               // no floating point
                               // rounding errors
 
// var - the compiler infers the type at compile
// time, this is still statically typed, NOT dynamic
var name = "Alex";  // compiler infers string
 
// Reference types - the variable holds a reference
// (address) to where the actual data lives
string title = "C# Basics";
int[] numbers = { 1, 2, 3 };
Post post = new Post();
 
// Constants - value is fixed at compile time,
// cannot ever change
const double Pi = 3.14159;
 
// Nullable value types - value types normally
// cannot be null, this opts in
int? nullableAge = null;

Practice question: What is the difference between const and readonly in C#? Write one example of each.

Topic 2: Strings and String Methods

A string is a sequence of characters, and in C# it's a reference type - but with a critical twist: strings are immutable. Once created, a string's actual content in memory never changes. Every operation that appears to modify a string actually creates a brand new string.

Think of a printed book page. You cannot erase and rewrite a word on a printed page - if you want different text, you print an entirely new page. Modifying a string works the same way: the old string still exists in memory until garbage collected, and a new one is created for the result.

string greeting = "Hello";
string name = "Manohari";
 
// Concatenation - creates a NEW string, does not
// modify 'greeting'
string message = greeting + ", " + name;
 
// String interpolation - cleaner syntax, same result
string message2 = $"{greeting}, {name}";
 
// Common string methods
string text = "  C# Interview Prep  ";
Console.WriteLine(text.Trim());           // "C# Interview Prep"
Console.WriteLine(text.ToUpper());        // "  C# INTERVIEW PREP  "
Console.WriteLine(text.Contains("Prep")); // true
Console.WriteLine(text.Replace("C#", "CSharp"));
Console.WriteLine(text.Split(' ').Length);
Console.WriteLine(text.Substring(2, 4));  // extracts a portion
Console.WriteLine(text.IndexOf("Prep"));  // position found at
 
// String comparison - == checks VALUE equality
// for strings specifically (special-cased), not
// reference equality
string a = "hello";
string b = "hello";
Console.WriteLine(a == b);         // true - value equality
Console.WriteLine(a.Equals(b));    // true - same result
 
// StringBuilder - for heavy concatenation, avoid
// creating thousands of throwaway strings in a loop
var sb = new StringBuilder();
for (int i = 0; i < 1000; i++)
{
    sb.Append(i).Append(", ");
}
string result = sb.ToString();

Practice question: Write a method that reverses a string without using any built-in reverse method.

Topic 3: Arrays

An array is a fixed-size, ordered collection of elements of the same type. The size is set at creation and cannot change afterward - to "resize," a new array must be created and the old data copied over.

Think of a row of numbered parking spaces painted onto pavement. The number of spaces is fixed the moment the lot is built - adding more spaces means literally repaving with a new, larger layout, not just adding to the existing one.

// Declaration and initialization
int[] numbers = { 1, 2, 3, 4, 5 };
string[] names = new string[3];  // size 3, all null initially
names[0] = "Alex";
names[1] = "Priya";
names[2] = "Sam";
 
// Accessing and modifying
Console.WriteLine(numbers[0]);   // 1
numbers[0] = 100;                // arrays ARE mutable in
                                  // content, just fixed size
 
// Iterating
foreach (var n in numbers)
{
    Console.WriteLine(n);
}
 
// Multi-dimensional array
int[,] grid = new int[3, 3];
grid[0, 0] = 1;
grid[1, 1] = 5;
 
// Jagged array - array of arrays, each inner
// array can be a different length
int[][] jagged = new int[3][];
jagged[0] = new int[] { 1, 2 };
jagged[1] = new int[] { 1, 2, 3, 4 };
 
// Common Array methods
Array.Sort(numbers);
Array.Reverse(numbers);
int index = Array.IndexOf(numbers, 100);
bool found = Array.Exists(numbers, n => n > 50);

Practice question: Given an integer array, write a method that finds the second largest number without sorting the entire array.

Topic 4: List

List is a resizable, ordered collection - the generic, flexible alternative to a fixed-size array. Internally it's backed by an array that gets replaced with a larger one automatically as items are added beyond current capacity.

Think of an expandable file folder versus a fixed shoebox. As more documents come in, the expandable folder just grows - you never have to buy a new one and manually move everything over, even though internally that's conceptually similar to what List does behind the scenes automatically.

var posts = new List<string>();
 
posts.Add("First Post");
posts.Add("Second Post");
posts.Insert(0, "Inserted at start");
 
posts.Remove("First Post");     // removes by value
posts.RemoveAt(0);               // removes by index
 
bool exists = posts.Contains("Second Post");
int index = posts.IndexOf("Second Post");
 
Console.WriteLine(posts.Count);  // current item count
 
// Iterating
foreach (var post in posts)
{
    Console.WriteLine(post);
}
 
// Converting between List and Array
int[] array = { 1, 2, 3 };
List<int> fromArray = array.ToList();
int[] backToArray = fromArray.ToArray();
 
// Sorting and searching
var numbers = new List<int> { 5, 2, 8, 1 };
numbers.Sort();
numbers.Sort((a, b) => b.CompareTo(a));  // descending,
                                            // custom comparer

Practice question: Write a method that removes all duplicate values from a List while preserving the original order.

Topic 5: Dictionary<TKey, TValue>

A Dictionary stores key-value pairs and provides fast, close-to-O(1) lookup by key, using a hash table internally. Every key must be unique.

Think of a labeled filing cabinet drawer system, where every drawer has exactly one unique name on it. Finding "the invoices drawer" doesn't require checking every drawer one by one - you go directly to the one labeled correctly.

var postsBySlug = new Dictionary<string, string>();
 
postsBySlug["csharp-basics"] = "C# Basics Post";
postsBySlug["csharp-linq"] = "LINQ Deep Dive";
 
// Safe lookup - does not throw if key is missing
if (postsBySlug.TryGetValue("csharp-basics", out var title))
{
    Console.WriteLine(title);
}
 
// Direct access - throws KeyNotFoundException if missing
string result = postsBySlug["csharp-basics"];
 
bool hasKey = postsBySlug.ContainsKey("csharp-linq");
postsBySlug.Remove("csharp-linq");
 
// Iterating - gives KeyValuePair<TKey,TValue>
foreach (var kvp in postsBySlug)
{
    Console.WriteLine($"{kvp.Key}: {kvp.Value}");
}
 
// Just keys or just values
foreach (var key in postsBySlug.Keys) { }
foreach (var value in postsBySlug.Values) { }
 
// Update or add in one call
postsBySlug["csharp-basics"] = "Updated Title";  // overwrites

Practice question: Given an array of words, write a method using a Dictionary that counts how many times each word appears.

Topic 6: HashSet

A HashSet stores unique values only, with no guaranteed order, and provides fast O(1) average lookup for "does this exist" checks - much faster than checking a List with Contains for large collections.

Think of a guest list at the door of an event, where a bouncer just needs to answer "is this name already checked in" as fast as possible - not caring about the order names were added, just whether a given name is present at all.

var uniqueTags = new HashSet<string>();
 
uniqueTags.Add("Azure");
uniqueTags.Add("C#");
uniqueTags.Add("Azure");  // silently ignored - duplicate
 
Console.WriteLine(uniqueTags.Count);  // 2
 
bool hasAzure = uniqueTags.Contains("Azure");  // O(1) check
 
// Set operations
var setA = new HashSet<int> { 1, 2, 3, 4 };
var setB = new HashSet<int> { 3, 4, 5, 6 };
 
setA.IntersectWith(setB);  // setA becomes {3, 4}
// UnionWith, ExceptWith also available

Practice question: Given two integer arrays, write a method that returns only the numbers that appear in both arrays, using a HashSet.

Topic 7: Tuples

A tuple bundles multiple values together into one object without needing to define a custom class. Modern C# tuples support named elements, making them readable at the point of use.

Think of a small labeled tray carrying a few different items together - a tray with "coffee" and "muffin" compartments lets you carry both at once without needing a whole custom carrying case built just for that specific combination.

// Named tuple
(string Name, int Age) person = ("Alex", 30);
Console.WriteLine(person.Name);  // "Alex"
Console.WriteLine(person.Age);   // 30
 
// Returning multiple values from a method
(int Min, int Max) FindMinMax(int[] numbers)
{
    return (numbers.Min(), numbers.Max());
}
 
var result = FindMinMax(new[] { 5, 2, 8, 1 });
Console.WriteLine($"Min: {result.Min}, Max: {result.Max}");
 
// Deconstruction
var (min, max) = FindMinMax(new[] { 5, 2, 8, 1 });
Console.WriteLine(min);
Console.WriteLine(max);
 
// Tuple vs custom class - when to use which
// Tuple: quick, internal, 2-3 short-lived values
// Class: the shape has real meaning, gets passed
// around broadly, or needs its own behavior/methods

Practice question: Write a method that takes a list of numbers and returns a tuple containing the sum, average, and count in one call.

Topic 8: Value Types vs Reference Types

This is one of the most frequently tested distinctions in C# interviews. Value types - int, bool, double, struct - store their actual data directly in the variable. Reference types - class, array, string, List, Dictionary - store a reference, a memory address, to where the actual data lives on the heap. The variable itself just holds that address.

Think of a value type as writing a number directly on a sticky note - the note is the data. A reference type is like writing a house address on a sticky note - the note points to where the actual house is, and copying the note just copies the address, not the house itself.

// Value type - assignment COPIES the actual value
int a = 5;
int b = a;   // b gets its OWN copy of 5
b = 10;
Console.WriteLine(a);  // still 5 - a was never touched
 
// Reference type - assignment copies the REFERENCE,
// both variables point to the SAME object
var list1 = new List<int> { 1, 2, 3 };
var list2 = list1;   // list2 points to the SAME list
list2.Add(4);
Console.WriteLine(list1.Count);  // 4 - list1 sees the
                                   // change too, because
                                   // it's the same object
 
// Passing to methods - same rule applies
void ModifyValue(int x) { x = 100; }
void ModifyReference(List<int> list) { list.Add(999); }
 
int number = 5;
ModifyValue(number);
Console.WriteLine(number);  // still 5
 
var myList = new List<int> { 1, 2 };
ModifyReference(myList);
Console.WriteLine(myList.Count);  // 3 - the SAME list
                                    // object was modified
 
// string is a special case - reference type, but
// immutable, so it BEHAVES like a value type in
// most practical situations
string s1 = "hello";
string s2 = s1;
s2 = s2 + " world";  // creates a NEW string for s2
Console.WriteLine(s1);  // still "hello" - unaffected

Practice question: Without running the code, predict the output: create a struct Point with a public int X, create var p1 = new Point with X set to 1, assign var p2 = p1, then set p2.X to 99. What is p1.X afterward, and why?

Topic 9: Operators

Operators perform operations on values - arithmetic, comparison, logical, and a few special ones worth knowing well for interviews specifically.

// Arithmetic
int sum = 5 + 3;
int remainder = 10 % 3;   // modulo - remainder after division
 
// Comparison
bool isEqual = (5 == 5);
bool isGreater = (5 > 3);
 
// Logical
bool result = true && false;   // AND
bool result2 = true || false;  // OR
bool result3 = !true;           // NOT
 
// Null-coalescing - returns left if not null,
// otherwise returns right
string name = null;
string display = name ?? "Unknown";  // "Unknown"
 
// Null-conditional - safely accesses a member,
// returns null instead of throwing if the object
// itself is null
Post post = null;
string title = post?.Title;  // null, no exception thrown
 
// Null-coalescing assignment
string cachedValue = null;
cachedValue ??= "default";  // assigns only if currently null
 
// Ternary conditional
int age = 20;
string category = age >= 18 ? "Adult" : "Minor";
 
// Increment/decrement
int count = 0;
count++;      // post-increment
++count;      // pre-increment - subtle difference in
              // expressions, same end result standalone

Practice question: What is the difference between x++ and ++x when used inside a larger expression, like int y = x++ + 1 versus int y = ++x + 1? Write out what each assigns to x and y given x starts at 5.

Topic 10: Control Flow - if, else, switch

Control flow statements decide which code actually runs based on conditions.

int score = 85;
 
// if / else if / else
if (score >= 90)
{
    Console.WriteLine("A");
}
else if (score >= 80)
{
    Console.WriteLine("B");
}
else
{
    Console.WriteLine("C or below");
}
 
// switch statement
string grade;
switch (true)
{
    case bool _ when score >= 90:
        grade = "A";
        break;
    case bool _ when score >= 80:
        grade = "B";
        break;
    default:
        grade = "C or below";
        break;
}
 
// switch expression (modern C#, more concise)
string grade2 = score switch
{
    >= 90 => "A",
    >= 80 => "B",
    _ => "C or below"
};
 
// Pattern matching in switch
object value = 42;
string description = value switch
{
    int i when i > 0 => "positive integer",
    int i when i < 0 => "negative integer",
    string s => $"a string: {s}",
    null => "null value",
    _ => "something else"
};

Practice question: Write a method using a switch expression that takes an integer representing a day of the week (1-7) and returns whether it's a "Weekday" or "Weekend".

Topic 11: Loops

Loops repeat a block of code, either a fixed number of times, while a condition holds, or once per element in a collection.

// for loop - when you know the iteration count
// or need the index
for (int i = 0; i < 5; i++)
{
    Console.WriteLine(i);
}
 
// while loop - condition checked BEFORE each iteration
int count = 0;
while (count < 5)
{
    Console.WriteLine(count);
    count++;
}
 
// do-while - condition checked AFTER each iteration,
// so the body ALWAYS runs at least once
int x = 10;
do
{
    Console.WriteLine(x);
    x++;
} while (x < 5);  // runs once even though condition
                    // is false from the start
 
// foreach - iterates every element in a collection,
// no manual index management
var posts = new List<string> { "A", "B", "C" };
foreach (var post in posts)
{
    Console.WriteLine(post);
}
 
// break and continue
for (int i = 0; i < 10; i++)
{
    if (i == 3) continue;  // skip this iteration
    if (i == 7) break;     // exit the loop entirely
    Console.WriteLine(i);
}

Practice question: Write a program using a loop that prints the Fibonacci sequence up to the 10th number.

Topic 12: Methods and Parameters

A method is a named, reusable block of code. Parameters pass data into a method; a return type defines what comes back out.

// Basic method
int Add(int a, int b)
{
    return a + b;
}
 
// Optional parameters - must come after required ones
void Greet(string name, string greeting = "Hello")
{
    Console.WriteLine($"{greeting}, {name}");
}
Greet("Alex");               // uses default "Hello"
Greet("Alex", "Hi");         // overrides default
 
// Named arguments - can be passed in any order
Greet(greeting: "Hey", name: "Alex");
 
// params - accepts a variable number of arguments
int Sum(params int[] numbers)
{
    int total = 0;
    foreach (var n in numbers) total += n;
    return total;
}
Sum(1, 2, 3);        // works
Sum(1, 2, 3, 4, 5);  // also works, any count
 
// ref - passes by REFERENCE, method can modify
// the caller's actual variable
void Double(ref int number)
{
    number = number * 2;
}
int value = 5;
Double(ref value);
Console.WriteLine(value);  // 10 - actually changed
 
// out - similar to ref, but the method MUST assign
// a value before returning, commonly used for
// "try" pattern methods
bool TryParse(string input, out int result)
{
    return int.TryParse(input, out result);
}
 
// Method overloading - same name, different
// parameter signatures
int Multiply(int a, int b) => a * b;
double Multiply(double a, double b) => a * b;

Practice question: What is the actual difference between ref and out parameters? Write a method using each that demonstrates the difference.

Topic 13: Enums

An enum defines a named set of related constant values, making code more readable than using raw numbers or strings for a fixed set of options.

public enum OrderStatus
{
    Pending,     // 0 by default
    Processing,  // 1
    Shipped,     // 2
    Delivered    // 3
}
 
var status = OrderStatus.Processing;
Console.WriteLine(status);          // "Processing"
Console.WriteLine((int)status);      // 1
 
// Assigning explicit values
public enum HttpStatusCode
{
    Ok = 200,
    NotFound = 404,
    ServerError = 500
}
 
// Converting from an int
var code = (HttpStatusCode)404;
Console.WriteLine(code);  // NotFound
 
// Parsing from a string
var parsed = Enum.Parse<OrderStatus>("Shipped");
 
// Switching on an enum
string GetMessage(OrderStatus status) => status switch
{
    OrderStatus.Pending => "Order received",
    OrderStatus.Shipped => "On its way",
    OrderStatus.Delivered => "Completed",
    _ => "Unknown status"
};

Practice question: Create an enum for days of the week, and write a method that returns true if a given day is a weekend.

Topic 14: Structs vs Classes

Both structs and classes group related data and behavior together, but a struct is a value type, copied on assignment, while a class is a reference type, shared on assignment - the same fundamental distinction as value types versus reference types, applied to your own custom types.

// struct - value type, typically small, simple data
public struct Point
{
    public int X;
    public int Y;
}
 
var p1 = new Point { X = 1, Y = 2 };
var p2 = p1;       // COPIES the values
p2.X = 99;
Console.WriteLine(p1.X);  // still 1 - p1 untouched
 
// class - reference type, typically larger objects
// with behavior, identity, and mutable state over time
public class Post
{
    public string Title;
    public int ViewCount;
}
 
var post1 = new Post { Title = "Hello", ViewCount = 0 };
var post2 = post1;  // SHARES the same object
post2.ViewCount = 5;
Console.WriteLine(post1.ViewCount);  // 5 - same object

Use a struct for small, immutable-feeling data with no real identity - a Point, a Color, a Money amount. Use a class for anything with real identity, larger data, or behavior that changes over the object's lifetime - a Post, a Customer, a Service. Most day-to-day domain modeling uses classes; structs are the exception, reached for deliberately.

Practice question: Explain why using a struct for a large object with 15 fields would generally be a bad idea, based on what you know about value type copying.

Topic 15: Nullable Types

Value types - int, bool, DateTime - cannot normally hold null; they always have some default value. Nullable value types, written as int?, opt into allowing null, useful for representing "no value provided" distinctly from an actual zero or false.

int? age = null;
int regularAge = 0;  // 0 is a real value,
                       // different from "no value"
 
if (age.HasValue)
{
    Console.WriteLine(age.Value);
}
 
// GetValueOrDefault - safe access with a fallback
int actualAge = age.GetValueOrDefault(18);
 
// Null-coalescing works here too
int displayAge = age ?? 18;
 
// Nullable reference types (C# 8+) - a compiler
// feature (not a runtime type change) that WARNS
// when a reference type that should never be null
// might actually be null
string? nullableName = null;   // explicitly allowed
string nonNullableName = "Alex"; // compiler warns if
                                   // this is ever assigned
                                   // null somewhere

Practice question: Why might a nullable int? be a better choice than a regular int for a "discount percentage" field on an order, where most orders have no discount at all?

Topic 16: Type Conversion and Casting

Converting a value from one type to another - sometimes safe and implicit, sometimes requiring an explicit cast, and sometimes needing a parsing method entirely.

// Implicit conversion - safe, no data loss possible,
// compiler does it automatically
int number = 100;
double asDouble = number;  // int fits safely into double
 
// Explicit conversion (casting) - REQUIRED when data
// loss is possible, forces you to acknowledge the risk
double price = 19.99;
int roundedDown = (int)price;  // 19 - truncates,
                                 // does not round
 
// Parsing strings to numbers
string input = "42";
int parsed = int.Parse(input);        // throws if invalid
bool success = int.TryParse(input, out int result);
                                        // safe, returns
                                        // false instead of
                                        // throwing
 
// Convert class - handles more conversions, including
// null handling
string text = Convert.ToString(42);
int fromString = Convert.ToInt32("42");
 
// as vs cast for reference types
object obj = "hello";
string s1 = (string)obj;      // throws if obj isn't
                                // actually a string
string s2 = obj as string;    // returns null instead
                                // of throwing if it fails
 
// is keyword with pattern matching
if (obj is string str)
{
    Console.WriteLine(str.Length);
}

Practice question: What is the actual difference between int.Parse() and int.TryParse()? When would you genuinely prefer one over the other?

Topic 17: Basic Exception Handling

Exceptions represent errors that occur during execution. try/catch lets code handle an error gracefully instead of crashing the entire program.

try
{
    int result = 10 / int.Parse("0");
}
catch (DivideByZeroException ex)
{
    Console.WriteLine($"Cannot divide by zero: {ex.Message}");
}
catch (FormatException ex)
{
    Console.WriteLine($"Invalid number format: {ex.Message}");
}
catch (Exception ex)
{
    // Generic catch-all - should be LAST, since more
    // specific catches above it would never be reached
    // if this came first
    Console.WriteLine($"Unexpected error: {ex.Message}");
}
finally
{
    // ALWAYS runs, whether an exception occurred or not -
    // used for cleanup (closing files, connections, etc.)
    Console.WriteLine("Cleanup runs here regardless");
}
 
// Throwing your own exceptions
void ValidateAge(int age)
{
    if (age < 0)
    {
        throw new ArgumentException("Age cannot be negative", nameof(age));
    }
}
 
// Custom exception types
public class InsufficientFundsException : Exception
{
    public InsufficientFundsException(string message) : base(message) { }
}

Practice question: Write a method that safely divides two numbers, catching a divide-by-zero error and returning 0 instead of letting the exception propagate.

Key Lessons

Value types copy on assignment; reference types share the same underlying object - this single distinction explains a huge share of "unexpected" C# behavior.

Arrays are fixed size; List resizes automatically - default to List unless the size is genuinely fixed and known.

Dictionary<TKey,TValue> gives fast key-based lookup; HashSet gives fast existence checks with no duplicates.

Strings are immutable - every apparent modification creates a new string, which is exactly why StringBuilder exists for heavy concatenation.

ref and out both pass by reference, but out requires the method to assign a value before returning, commonly used in the TryParse pattern.

Structs and classes mirror the value versus reference type distinction for your own custom types - most everyday modeling uses classes.

What's Next

Part 2 covers mid-level concepts - LINQ, generics, delegates and events, interfaces versus abstract classes, and exception handling in real depth.

Summary

Every C# codebase, no matter how advanced, is built from these same basic pieces - variables and types, strings, collections, control flow, methods, and basic error handling. Interview questions on these topics aren't testing whether you've memorized syntax - they're testing whether the underlying model, value versus reference, mutable versus immutable, fixed versus resizable, is genuinely internalized, since that's what actually predicts whether unfamiliar code will behave the way you expect it to.

Originally published at TechStack Blog: https://www.techstackblog.com/post.html?slug=csharp-interview-prep-basics-part1

More from TechStack Blog: C# / .NET: https://www.techstackblog.com/category.html?cat=csharp
CS Fundamentals: https://www.techstackblog.com/category.html?cat=cs-fundamentals

Building a Custom Modbus TCP Client in .NET: What a Production-Grade Poller Actually Needs

Tue, 25 Aug 2026 16:17:06 +0000

Most Modbus tutorials in .NET end at the same place: install a library, call ReadHoldingRegisters, print a number. That is enough to prove a device is reachable. It is not enough to run anything.

The moment you point that code at more than one device and leave it running, the questions change. What happens when a device stops responding? What happens when one slow device blocks the others? Why is that float reading 3.4e38 instead of 480? Where does the data actually go?

This article covers the layer that answers those questions: the application code you build around a Modbus library. Everything here runs against a simulated device included in the code, so you can execute the whole thing locally with nothing but the .NET SDK. All values and device names are illustrative.

A short Modbus refresher

Modbus TCP is a request/reply protocol. A client opens a TCP connection (port 502 by convention) and asks a device for data. The device answers. There is no subscription and no push, so the client polls on a schedule.

Data lives in four spaces:

Space	Size	Access
Coils	1 bit	read/write
Discrete inputs	1 bit	read
Input registers	16 bit	read
Holding registers	16 bit	read/write

Function code 3 reads holding registers and is the one you will use most. A request carries a transaction ID, a unit ID, a starting address, and a register count. The response carries the raw 16-bit words back.

Two properties of that design drive most of what follows. Registers are only 16 bits wide, so anything larger spans several of them. And the wire format is big-endian, which will not match your CPU.

Just use a library, then keep going

Do not reimplement Modbus framing for production. NModbus, FluentModbus, and EasyModbusTCP all handle the wire protocol, and FluentModbus ships a server implementation that is useful for testing.

What none of them give you is a client. They give you a read call. The distance between a read call and something you can deploy is:

connection lifecycle across devices that disappear and come back
a polling schedule per device that tolerates slow or dead peers
decoding raw registers into typed values you can reason about
somewhere for the data to go, decoupled from how it was acquired
enough visibility to know when a device went quiet

That is the custom part. It is specific to your system, which is exactly why no package solves it for you.

The code below writes the framing directly against System.Net.Sockets so the example has zero dependencies and you can read every byte. In a real build, swap that piece for a library and keep the structure around it.

Component 1: decoding registers into typed values

This is where most first attempts break, so start here.

A 32-bit float occupies two consecutive registers. To reconstruct it you concatenate both words in the order the device sent them and read the result as big-endian. Get the order wrong and you do not get an error, you get a plausible-looking wrong number, or a value like 1.7e38.

Rather than scatter that logic through the codebase, describe the device as data:

enum RegisterType { Float32, UInt16Enum }

record RegisterDefinition(string Name, ushort Address, RegisterType Type, string Unit);

record Reading(string DeviceName, string PointName, object Value, string Unit, DateTime TimestampUtc);

static class RegisterDecoder
{
    public static object Decode(RegisterDefinition def, ushort[] regs, int offset)
    {
        switch (def.Type)
        {
            case RegisterType.Float32:
                Span<byte> buf = stackalloc byte[4];
                BinaryPrimitives.WriteUInt16BigEndian(buf.Slice(0, 2), regs[offset]);
                BinaryPrimitives.WriteUInt16BigEndian(buf.Slice(2, 2), regs[offset + 1]);
                return Math.Round(BinaryPrimitives.ReadSingleBigEndian(buf), 2);

            case RegisterType.UInt16Enum:
                return regs[offset] switch
                {
                    0 => "Stopped",
                    1 => "Running",
                    _ => "Fault"
                };

            default:
                throw new NotSupportedException();
        }
    }
}

A register map then becomes a list, not code:

var map = new List<RegisterDefinition>
{
    new("Voltage",   0, RegisterType.Float32,    "V"),
    new("Frequency", 2, RegisterType.Float32,    "Hz"),
    new("Status",    4, RegisterType.UInt16Enum, ""),
};

Two things worth knowing before you fight them. Vendors disagree about word order, so some devices need the two registers swapped before decoding, which is why a WordSwapped flag usually appears in the map eventually. And documentation often numbers registers from 1 while the protocol numbers them from 0, which is a very common source of off-by-one addressing.

Component 2: connection management

BinaryPrimitives handles endianness. The socket handles nothing.

Set explicit timeouts. Without them a silent device leaves you waiting on a read that never returns, and one stalled device can quietly stop your entire pipeline.

public async Task ConnectAsync(CancellationToken ct)
{
    _client = new TcpClient { ReceiveTimeout = 1000, SendTimeout = 1000 };
    await _client.ConnectAsync(_host, _port, ct);
    _stream = _client.GetStream();
}

Also, never assume one ReadAsync returns a whole frame. TCP is a stream, not a message queue. A response can arrive in pieces, and the header tells you how many bytes to expect, so read until you have them all:

private async Task ReadExactAsync(byte[] buffer, CancellationToken ct)
{
    int read = 0;
    while (read < buffer.Length)
    {
        int n = await _stream!.ReadAsync(buffer.AsMemory(read, buffer.Length - read), ct);
        if (n == 0) throw new IOException("Connection closed by device.");
        read += n;
    }
}

Skipping that check is the classic bug that works perfectly on localhost and fails intermittently on a real network.

Component 3: the polling engine

Each device gets its own loop and its own interval. Independent loops mean a dead device cannot delay a healthy one.

Failures are normal, not exceptional. Devices reboot, networks drop, technicians unplug things. The loop treats a failure as an expected state and backs off exponentially instead of hammering a device that is down:

catch (Exception ex)
{
    _failures++;
    conn?.Dispose();
    conn = null;

    var delay = TimeSpan.FromMilliseconds(
        Math.Min(200 * Math.Pow(2, _failures - 1), 3000));

    Console.WriteLine($"{_cfg.Name}: read failed ({ex.GetType().Name}), " +
                      $"retry #{_failures} in {delay.TotalMilliseconds:F0}ms");

    await Task.Delay(delay, ct);
}

One detail is easy to get wrong, and I got it wrong first while writing this. Reset the failure counter after a successful read, not a successful connect. If you reset on connect, a device that accepts connections but immediately drops them looks healthy every cycle, the counter returns to zero, and the backoff never grows. You reconnect in a tight loop forever. The captured output below shows the corrected behavior.

Component 4: a pluggable sink

Polling and delivery are separate concerns. Keep them apart behind an interface:

interface IReadingSink
{
    Task WriteAsync(IReadOnlyList<Reading> readings, CancellationToken ct);
}

The demo uses a console sink. A real deployment might implement the same interface over Azure Event Hubs, MQTT, Kafka, or a time-series database, and a batching decorator that buffers readings and flushes on an interval slots in without the polling loop knowing about it.

The payoff is testability. The polling logic never knows where data lands, so you can verify it against a fake sink and a simulator with no cloud account involved.

Running it

The full program starts two simulated devices, points three pollers at them (the third at a port where nothing is listening), and takes one device offline mid-run. Real captured output:

[18:50:21] device-01: connected
[18:50:21] device-02: connected
[18:50:21] device-03: read failed (SocketException), retry #1 in 200ms
  [18:50:21] device-01  Voltage    = 478.99   V
  [18:50:21] device-01  Frequency  = 59.92    Hz
  [18:50:21] device-01  Status     = Running
  [18:50:21] device-02  Voltage    = 481.08   V
  [18:50:21] device-02  Frequency  = 59.98    Hz
  [18:50:21] device-02  Status     = Stopped
[18:50:21] device-03: read failed (SocketException), retry #2 in 400ms
[18:50:22] device-03: read failed (SocketException), retry #3 in 800ms
  [18:50:22] device-01  Voltage    = 481.09   V
  [18:50:22] device-01  Frequency  = 60.03    Hz
  [18:50:22] device-01  Status     = Running
[18:50:22] device-03: read failed (SocketException), retry #4 in 1600ms
  [18:50:23] device-02  Voltage    = 481.94   V
  [18:50:23] device-02  Frequency  = 59.92    Hz
  [18:50:23] device-02  Status     = Stopped
[18:50:24] device-03: read failed (SocketException), retry #5 in 3000ms
[18:50:25] *** simulating device-02 going offline ***
  [18:50:25] device-01  Voltage    = 479.28   V
  [18:50:25] device-01  Frequency  = 60.1     Hz
  [18:50:25] device-01  Status     = Fault
[18:50:27] device-02: read failed (IOException), retry #1 in 200ms
[18:50:27] device-03: read failed (SocketException), retry #6 in 3000ms
  [18:50:27] device-01  Voltage    = 480.82   V
  [18:50:27] device-01  Frequency  = 60.04    Hz
  [18:50:27] device-01  Status     = Fault
[18:50:27] device-02: connected
[18:50:27] device-02: read failed (IOException), retry #2 in 400ms
[18:50:28] device-02: connected
[18:50:28] device-02: read failed (IOException), retry #3 in 800ms
  [18:50:28] device-01  Voltage    = 478.37   V
  [18:50:28] device-01  Frequency  = 59.93    Hz
  [18:50:28] device-01  Status     = Running
[18:50:28] device-02: connected
[18:50:28] device-02: read failed (IOException), retry #4 in 1600ms
Shutdown complete.

The behavior worth noting: device-01 polls on schedule the entire time, unaffected by two failing neighbors. device-03, which never existed, walks its backoff up to the 3 second ceiling instead of spinning. device-02 degrades gracefully when pulled offline, and its retry counter climbs correctly because it only resets on a successful read.

What this buys you

Failure isolation. One bad device costs you that device, not the fleet.

Testability. A simulator plus a fake sink means the whole pipeline runs in CI.

Decoupled evolution. Protocol handling, decoding, and delivery change independently. Swapping Event Hubs for Kafka touches one class.

Configuration over code. New device model, new register map entry, no redeploy of polling logic.

Operability. Per-device failure counts and timestamps tell you which device went quiet and when.

When not to build this

If you have one device, read it occasionally, and can tolerate a crash and restart, use a library directly in twenty lines and stop reading. The structure here earns its cost when you have a fleet, uneven reliability, and a downstream system that expects a steady stream.

If your devices already speak MQTT or OPC UA, prefer those. Modbus is a 1979 protocol with no security model and no push, and you should not add a polling layer you do not need.

Takeaways

The interesting problems in industrial data collection are not in the protocol. They are in everything wrapped around it: endianness, partial reads, timeouts, backoff, isolation, and a clean seam between acquisition and delivery.

Four rules worth keeping:

Treat the register map as configuration, not code.
Assume every read can fail, and back off when it does.
Reset failure counters on successful reads, not successful connects.
Keep the sink behind an interface so polling never knows where data goes.

The complete runnable program, simulator included, is roughly 330 lines and requires only the .NET SDK.

Parallel Processing Gone Wrong

Mon, 24 Aug 2026 10:38:39 +0000

⚡ "Let's Make It Faster!" (Famous Last Words)

The Scene: Sprint planning. The feature? Bulk data processing.
Me (naive): "Let's just run everything in parallel! It'll be 10x faster!"
Production (3 days later): catches fire
What I Thought Would Happen:
• 100 items to process
• Run them all in parallel
• Finish in 1/10th the time
• Get promoted
• Become CTO
What Actually Happened:
• 100 concurrent database connections
• Database connection pool exhausted
• ALL requests start failing (not just ours)
• 2 AM phone call from the CTO (not a promotion call)
• Emergency rollback at 3 AM
• Very awkward Slack conversation
The Broken Code:

// "I'll just parallelize everything!"
foreach (var item in items) {
    Task.Run(() => ProcessItem(item)); // YOLO
}

Why This Implodes:
❌ No limit on concurrent operations
❌ No shared state protection
❌ No error handling per item
❌ Overwhelms downstream services
❌ Database can't handle the connections
❌ Network ports get exhausted
❌ And my ego gets crushed
The Fix That Saved My Job:

int passCount = 0;
int failCount = 0;
var errors = new ConcurrentDictionary<string, string>();

// Key: MaxDegreeOfParallelism controls concurrency
Parallel.For(0, items.Count, 
    new ParallelOptions { 
        MaxDegreeOfParallelism = Environment.ProcessorCount // Usually 4-8
    }, 
    (i) => {
        try {
            ProcessItem(items[i]);
            
            // Thread-safe counter increment
            Interlocked.Increment(ref passCount);
        } 
        catch (Exception ex) {
            Interlocked.Increment(ref failCount);
            
            // Thread-safe error collection
            errors.TryAdd(i.ToString(), ex.Message);
        }
    });

// Now you can safely check results
Console.WriteLine($"Success: {passCount}, Failed: {failCount}");

The Golden Rules I Learned:
1️⃣ Parallelism ≠ Performance - Too much parallelism kills performance
2️⃣ Know Your Bottleneck - If it's I/O bound, 4-8 threads is usually optimal
3️⃣ Protect Shared State - Use Interlocked or ConcurrentCollections
4️⃣ Configure, Don't Hardcode - Make MaxDegreeOfParallelism environment-specific
5️⃣ Test Under Load - It works on my machine ≠ it works in production
The Results After Proper Implementation:
Controlled concurrency = predictable performance
✅ Database connections stay healthy
⚡ 6x speedup (not 100x, but sustainable)
Zero production incidents
Sleep peacefully without 3 AM alerts
The Hard Truth:
More threads ≠ More speed
It's like adding more cooks to a kitchen. At some point, they just bump into each other.
What's your parallel processing horror story? I can't be the only one who learned this the hard way

dotnet #parallelprocessing #performanceoptimization #productionissues #softwareengineering #threading #scalability #lessonslearned #debugging #csharp #techleadership

P.S. If you're using Task.Run() in a loop or unbounded Parallel.ForEach(), you're one production deployment away from a very bad day.

HttpClient Socket Exhaustion

Mon, 24 Aug 2026 10:37:13 +0000

Your .NET API is Slowly Dying (And You Don't Even Know It)

Last month, our production system started timing out randomly. No errors. No warnings. Just... slow death.
After 3 sleepless nights and diving through 60+ microservices, I found the culprit:

var client = new HttpClient(); // This single line
Here's what was happening:
Every HTTP call was creating a NEW TCP socket. Under load, we exhausted the system's connection pool. Requests started queuing. Response times went from 200ms to 30+ seconds.

The Silent Killer:
• ✅ Your code compiles fine
• ✅ Your tests pass
• ✅ It works in dev/staging
• ❌ It crashes in production under real load

The Fix That Saved Our SLA:

// In Startup.cs
`services.AddHttpClient("MyService", client => {

client.Timeout = TimeSpan.FromSeconds(120);

}) .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler {

PooledConnectionLifetime = TimeSpan.FromMinutes(2),
PooledConnectionIdleTimeout = TimeSpan.FromMinutes(5),
MaxConnectionsPerServer = 20,
AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate

});`

`// In your service
public class MyService {

private readonly IHttpClientFactory _clientFactory;    
public MyService(IHttpClientFactory clientFactory) {
    _clientFactory = clientFactory;
}    
public async Task<string> GetDataAsync() {
    var client = _clientFactory.CreateClient("MyService");
    // Use the client
}

}
`

The Results:
95% reduction in connection failures
⚡ 40% improvement in throughput
Prevented potential revenue loss from timeouts

The Lesson:
IHttpClientFactory isn't just a "best practice" - it's a production survival tool.
Microsoft documented this in 2018, but I still see this anti-pattern EVERYWHERE.
Have you been bitten by socket exhaustion?

Share your battle story in comments

#performance #dotnet #csharp #softwareengineering #productionissues #microservices #debugging #azure #performanceoptimization #lessonslearned #techleadership

Adding custom methods for linq queries

Wed, 15 Jul 2026 09:29:45 +0000

Adding custom methods for LINQ queries (C#)

Introduction

By introducing extension methods to the IEnumerableT> interface, you may expand the set of methods available for LINQ queries. Any data sequence can be converted into one single value by creating your custom aggregate method in SQL Server.

You can also build a method that returns a new series of values and acts as a custom filter or a specialized data transform for a sequence of variables.

A few examples include the Distinct and Skip techniques, as well as the Reverse.

You may apply your methods to any enumerable collection when you extend the IEnumerableT> interface. In this article, we shall deeply take a look at various custom methods that are used in LINQ queries in C#.

Adding an aggregate method

When a set of values is aggregated, a single value can be generated. Average, Min, and Max are just a few of the aggregate techniques available in LINQ. By introducing an extension method to the IEnumerableT> interface, you can design your aggregate method.

Median is an extension method that computes the median of a sequence of double-valued numbers.

public static class LINQExtensionExample
{
    public static double Median(this IEnumerable<double>? source)
    {
        if (!(source?.Any() ?? false))
        {
            throw a new InvalidOperationException("A null or empty set cannot be used to compute the median..");
        }

        var sortedList = (from numberX in source
                          orderby numberX
                          select numberX).ToList();

        int itemIndex = sortedList.Count / 2;

        if (sortedList.Count % 2 == 0)
        {
            // Rerurning an even number of objects or items
            return (sortedList[itemIndex] + sortedList[itemIndex - 1]) / 2;
        }
        else
        {
            // Rerurning an odd number of objects or items
            return sortedList[itemIndex];
        }
    }
}

There is no difference between calling this extension method from the IEnumerableT> interface and calling any other aggregate function.

On a double array, the following code demonstrates using the Median method

double[] numbers1 = { 0.9, 5, 2, 9.3, 2.6, 7, 3.3, 4 };

var query = numbers1.Median();

Console.WriteLine("double: Median = " + query1);
/*
 The output of the above code is as shown below

 Double: Median = 5.95
*/

An aggregate method is overloaded by accepting a variety of types.

To accept sequences of different types, you can overload your aggregate method. Overloading each type is the typical technique. It's also possible to use a delegate to build an overload for a generic type. Combining both approaches is also an option.

To build a type overload

A separate overload for each kind you want to support can be created. Here's an int-type overload of the Median method, which you can see in the following code example.

//Overload of int
public static double Median(this IEnumerable<int> source) =>
    (from numX in source select (double)numX).Median();
With the new Median overloads available for both integer and double types, the following code shows how to use them:
double[] numbers2 = {  0.9, 5, 2, 9.3, 2.6, 7, 3.3, 4};

var query2 = numbers2.Median();

Console.WriteLine("double: Median = " + query2);

int[] numbers3 = { 14, 16, 15, 13, 11, 10, 9 };

var query3 = numbers3.Median();

Console.WriteLine("int: Median = " + query3);
/*
 Here's what it looks like when it runs:

 The Double part: Median = 5.95
 The Integer part: Median = 13
*/

Initiating a generic overflow

A list of generic objects can also be used as an input to an overload if you want to do that. Delegate is supplied as a variable in this overload which converts the generic objects into a specific type using the delegate.

An overload of Median's FuncT,TResult> delegate is shown in the following code. An object of generic type T is passed to this delegate, and it returns a double-type object as a result.

// Let us take a look
public static double Median<T>(this IEnumerable<T> numbersY,
                       Func<T, double> selector) =>
    (from num in numbersY select selector(num)).Median();

When working with sequences of objects of any type, you may now use the Median technique. A delegate parameter must be passed in if the type does not have its overload of the procedure. Lambda expressions are available in C# for this purpose. When using Aggregate or Group By clauses instead of a method call, this is only true in Visual Basic.

You can use the following code to call the Median method on a string array as well as an integer array. Using an array of strings, a median is derived for each string's lengths in the array. Use the Median method's delegate parameter for each scenario in the code. Use the Median method's delegate parameter for FuncT, TResult> for each scenario in which it's used.

int[] numbers4 = { 14, 16, 15, 13, 11, 10, 9 };

/*
   In this case, the compiler will implicitly convert num=>num's value to double when you pass it as a parameter to the Median method.
   Otherwise, the compiler will give the user an error message.
*/
var query4 = numbers4.Median(num => num);

Console.WriteLine("int: Median = " + query3);

string[] numbers5 = { "fourteen", "sixteen", "fifteen", "thirteen", "eleven", "ten", "nine" };

// A number of object properties are available with the generic overload.

var query5 = numbers5.Median(str => str.Length);

Console.WriteLine("String: Median = " + query5);

/*
Here's what it looks like when it runs:
 Integer: Median = 13
 String: Median = 13
*/

Adding a method that returns a sequence

IENumerableT can be extended with custom query methods to return a sequence of values. A collection of IEnumerableT> must be returned in this scenario. Filters or data transformations can be applied to a sequence of values using these methods.

Using the AlternateElements Extension Method, every other element in a collection, starting with the first element, is returned.

//The IEnumerableT> interface has an extension method.
// Every other element in a sequence is returned by the method.
public static IEnumerable<T> AlternateElements<T>(this IEnumerable<T> source)
{
    int y = 3;
    foreach (var element in source)
    {
        if (y % 2 == 1)
        {
            yield return element;
        }
        y++;
    }
}

This function can be used to extend any enumerable collection.

string[] strings = { "u", "v", "w", "x" };

var query4 = strings.AlternateElements();

foreach (var element in query6)
{
    Console.WriteLine(element);
}
/*
Here's what it looks like when it runs:
 u
 w
 
*/

Conclusion

In conclusion, we have looked at how one as a programmer can add custom methods for LINQ queries in c#.

LINQ Looks Clean Until You Care About Performance

Mon, 27 Apr 2026 19:03:37 +0000

LINQ is great. Until it isn't.

Let me explain.

When I first learned LINQ, I thought it was magic. You write these clean, readable queries. No more messy loops. No more inline SQL strings. Just beautiful C#.

And for small apps or quick prototypes? It works perfectly.

But then you start building real backend APIs. The kind that handle lots of requests, talk to big databases, and need to stay fast under pressure.

And that's when LINQ starts to surprise you. Not in a fun way.

What most tutorials don't tell you

Here's the thing. LINQ isn't just a nicer way to write loops. It's actually a way to describe a query that can run in two very different places:

Inside your database (good)
Inside your app's memory (can get dangerous)

And the difference between those two is where most performance problems quietly begin.

You write something that looks harmless. But behind the scenes, LINQ pulls an entire table into memory, then filters it. Or it makes five database trips when you expected one. You don't see it happening. Your code still works. It just gets slower over time.

Why it's so easy to mess up

LINQ encourages you to compose first and think later. You chain together Where, Select, OrderByand you assume it's all efficient by default.

But not all LINQ methods are equal.

Some turn into clean SQL.
Some force everything to load into memory right then and there.
Some look like one query but actually run multiple.

And when you're writing the code, none of this is obvious. The compiler won't warn you. Tests probably won't catch it. It only shows up when your API is under real load.

What changes in production

On your laptop with ten test records? No problem.

But in production, you've got:

Huge tables
Dozens or hundreds of requests per second
A database that's already busy
Users who notice every millisecond

And now those tiny LINQ mistakes start to pile up. Not with a dramatic crash. More like a slow, invisible drag on performance. One request takes 50ms longer. Then another. Then your database CPU creeps up.

Nobody blames LINQ. They just say "the API feels slow lately."

The mindset shift that helped me

Here's what I had to unlearn.

LINQ isn't just about writing clean code. It's about deciding where the work happens.

In the database? Fast and efficient.
In memory? Sometimes fine, sometimes a disaster.

Once I stopped thinking of LINQ as "nice syntax" and started thinking of it as "query execution planner for humans," everything got clearer.

Good backend code isn't about using LINQ correctly. It's about knowing:

What runs in the database
What runs in memory
What runs once
What runs way more times than you think

One last thought

I still love LINQ. It's one of the best tools in .NET.

But like any powerful tool, it rewards you for understanding what's actually happening. Not just knowing the syntax.

The more you know about the behind the scenes stuff, the fewer surprises you get at 2 AM when production starts acting weird.

And that's a win worth chasing.

LINQ in Real Backend APIs: The Mistakes That Hurt Performance

Tuesday Coding Tip 07 — Exposing internal bits of .NET projects

Tue, 14 Apr 2026 11:49:31 +0000

C# has a number of visibility keywords and their combinations. A peculiar one is ‘internal’ which restricts the visibility of the symbols to the current assembly. However, that can be tweaked.

You can manually specify the names of assemblies to which the ‘internal’ bits will be visible. Why is this useful? Because you can expose otherwise private parts of your code to assemblies like unit tests and test code with ease. No more ‘friend’ shenanigans like in C++ unit tests!

Ways how to configure this evolved over the years and the most up-to-date approach seems to be in configuring the project file directly (with the latest MSVC and .NET 5+).

<Project>
    <!-- ... --->

 <ItemGroup>
  <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
   <_Parameter1>$(AssemblyName).Tests</_Parameter1>
  </AssemblyAttribute>
 </ItemGroup>

</Project>

gRPC vs REST

Tue, 14 Apr 2026 07:25:32 +0000

TL;DR:
We benchmarked REST vs gRPC under identical local setups using .NET. While gRPC is widely believed to outperform REST, our results show REST can be equally, or even slightly faster in specific data-heavy operations.

As microservices multiply across modern systems, the choice of API protocol can make or break performance. REST has ruled for years, but gRPC promises to be faster, leaner and more efficient. So why hasn't it taken over? Microservices can be heavily dependent on each other, which means speed and stability is key. When gRPC claims to be faster than REST, why isn't it the de facto standard? In this blog we will put gRPC and REST head to head, to see which is actually faster.

gRPC is a superior technology to REST! At least that is what this1, this2, this3 and this blog4 claims. According to all the mentioned blogs, gRPC performs better and faster than a REST on several metrics. In this blog we will test specifically, how fast a REST client can handle different request and responses, and compare it to how fast a similar gRPC client handles the same requests and responses. This begs the question...

Is gRPC faster than REST?

We hypothesize that gRPC is able to send and receive requests faster than a traditional REST. To test this, the following experiments have been developed.

The experiment

To test the Hypothesis two experiments, one utilizing gRPC and one utilizing REST. These experiments have to adhere to the following:

Rules

To ensure accurate measurements, the results must be obtained from the same computer.
Multiple data structures will be tested.
The setup for both APIs has to be as similar as possible.
The time used for measuring should be obtained from the client.

Set up

To adhere to the multiple data structures rule, a local database has been created, this database will provide a single instance of an object, as well as multiple instances of objects that will be stored in a list.
Each API will have 12 methods to call.
- Three for a single instance which takes a parameter of Id.
  - Each one with a larger payload
- Three for a single instance which takes a parameter of Id.
  - Each one with a deeper payload
- Three for a collection of 100 instances, which takes no parameters.
  - Each one with a larger payload
- Three for a collection of 100 instances, which takes no parameters.
  - Each one with a deeper payload
Each API will be tested with a client written in C#, as a console app.
- Time will be measured with .NET Stopwatch18.
- The stopwatch will begin when the method is called and end when the API returns the full data.
To minimize anomalies and outliers, each operation will be executed 100 times, and the average call speed will be evaluated.

Specs

I7-9700k, 8 core, 4.6GHz

Samsung SSD 840 EVO 250GB

NVIDIA GeForce GTX 1070

2x8 GB HyperX Fury 2666MHz DDR4 Memory

REST

What is REST?

We have decided to work with the common implementation of REST and not the full implementation of a RESTful API5.

The key features to take note of when using rest:

Separation of client and server

Server and client can be implemented independently without knowing each other-
Server code can be changed without affecting the client.
Client code can be changed without affecting the server.
Both server and client are aware of methods available.

Statelessness

Stateless6 means that the server is not required to know the current state of the client and vice versa.
Either end can understand any method calls, without knowing the previously called methods.

Invocation

We invoke a method on the server via HTTP operations7
- GET
- POST
- PUT
- DELETE

Setting up the experiment for the REST API

The architecture for this experiment is a simple one:

Sample project and metrics

If you want to replicate this experiment yourself, the database setup can be found here and the source code for the rest-api can be found here

Running our setup yielded the following results:

Single payload

The difference between a single small payload and a single large payload is small in the context of a daily task. A single small payload has a mean response time of 0.0181 whilst a single large payload has a mean response time of 0.0204 seconds. But in relation to each other, it's a 12.7% increase in response time.

To put this into perspective a small payload contains 10 values of data. A large payload contains (4+(6*9))*6+4 or 352 values. This means that we have requested 3420% more data and it only took 12.7% longer.

To test different scenarios we also created a "deep" payload that contains a different amount of nested objects. The deepest payload contains a total of eight nested objects, however, the total amount of values is far less in comparison to the previous payload. The previously mentioned payload peaked at 352 values whereas the deepest payload peaks at (4+(6*4))+(4+(7*4))+(4+(8*4)) values, or 96 values in total. In other words, the deep payloads are much smaller in size but different in structure.

To give a concrete example, a large payload is structured like so:

large_payload {
    id,
    string_Value,
    int_value,
    double_value,
    medium_payload {
        id,
        string_value,
        int_value,
        double value,
        small_payload {
                id,
                string_value,
                int_value,
                double_value
            },
        small_payload {
                ...
            },
        ...
        },
    medium_payload {
            ...
        },
    ...
}

and the deepest_payload is structured like so:

deepest_payload {
    id,
    depth_seven {
        ...
    },
    depth_eight {
        ...
    },
    depth_nine {
        id,
        string_value,
        int_value,
        double_value,
        depth_eight {
            id,
            string_value,
            int_value,
            double_value,
            depth_seven {
                ...
                depth_six {
                    ...
                    dpeth_five {
                        ...
                        depth_four {
                            ...
                            depth_three {
                                ...
                                depth_two {
                                    ...
                                    depth_one {
                                        ...
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }

    }
}

Interestingly, larger payloads returned faster results, an unexpected outcome that could hint at CPU scheduling effects or cached object reuse.

To put things into perspective, a deep payload, which contains a total of 4+(4+4)+(4+4*2) values, or 24 values in total. Averaged at 0.0173 seconds, whereas the deepest payload, which carries a total of 96 values, which means it's 300% larger in size, averaged at 0.015 seconds. In other words, 300% more data was transferred 15.3% faster on average.

Collection of payloads

When we compare collections, the difference becomes very apparent. A small collection payload averaged 0.0256 seconds and a large average of 0.1006 seconds, which is an increase of 293%. It is apparent that when it comes to moving large collections of data over the REST API, it takes a considerate amount of time compared to smaller collections.

The results are very much alike when we tested on collections of deep payloads.

gRPC

What is gRPC?

gRPC8 is an open-source RPC framework, that can run in any environment. gRPC was recently included in the .Net core platform thereby easily accessible by thousands of developers.

Some key features we would like to highlight:

HTTP/2 support

HTTP/29 is HTTP/1's successor, which is what most websites and frameworks utilize today. In many ways, HTTP/2 is an improved version of HTTP/1, and HTTP/3 is already in the works.

Language independent

gRPC is language independent, which means it doesn't matter which language you develop in. The framework supports a handful of popular languages10. This is quite an advantage when you're developing microservices, which might have services developed in different languages and frameworks.

Contract First

gRPC is strictly contract first11 which is a design approach that works especially well in larger development teams. It also excels when developing microservices, as a contract would be created before any actual implementations can be done. The contract is designed in the .proto file12, which is also where gRPC gains some of its speed from, seeing as .proto files are...

Strongly typed As a by-product of a strongly typed proto file, which is used as a contract between client and server, but also used as an extensible mechanism for serializing13 structured data.

Setting up the gRPC project

For the gRPC architecture we use the same as the rest, we have a client and a server running locally. The client calls the methods exposed by the proto file. The method then gets executed on the server and queries the database, once the data has been obtained it replies to the client. When the client has received all the data, we stop and log the time elapsed since the call started.

Sample project and metrics

If you want to replicate this experiment yourself database setup can be found here and the source code for the grpc-project can be found here

Running our setup yielded the following results:

Single payloads

The test on single payloads yielded quite odd results, where the medium payload proved to be the fastest on average, and the largest payload only being slightly slower than the smallest. Just to recap the numbers; a larger payload contains 3400% more data than a small payload, and yet it only took 2.36% longer to get that data.

Even more odd were the results of the deep payloads. Once again the payload containing a "medium" amount of data, was the fastest, just like previously. But unlike previously, the deepest payload was significantly faster than the deep payload, to be precise; the deepest payload, which contains 300% more data than a deep payload was 28.63% faster. As the results are rather unexpected we have to take a close look at possible errors that could have occurred.

Collection of payloads

Collections paint a different picture, a small payload collection averaged 0.01911 seconds, while a collection of large payloads took 0.7025. This means a large payload on average took 267.6% longer to get. These results are much closer to what we would expect. We did the same test with a collection of deep payloads.

The results of this test, were as you would expect, as the payloads incrementally increase in size, they also increase incrementally in response time.

Conclusion

When we put the two charts next to each other, it's easy to see which one has an edge. The REST API is represented by the blue blocks, whilst gRPC is represented by the red blocks, just like previously.

This is the case for both single instances of objects as well as collections of objects.

We hypothesized that gRPC would be faster than the rest, based on the numerous blogs claiming this to be true, with their own tests. Contrary to popular belief, our experiments suggest that under certain conditions, REST can outperform gRPC in raw speed, reminding us that performance isn't universal but contextual.

These results might not seem as much, but it has been proven14 that people on average don't wait around for data to load and will abandon a web page or program if loading times are too long. When moving large amounts of data, a small amount of time can be the difference between keeping or losing a customer.

this prompts the question: When to use gRPC and when to use REST

We would argue that gRPC fit into a setting, where you need to have multiple programs or services talking to each other across different languages, especially when the task that needs to connect to an endpoint is an action that needs to be executed; one such action could be TurnOnTheWater(). This argument is based on the research made into gRPC, rather than the results of these particular tests.

REST on the other hand operates on the four aforementioned HTTP operations, these operations indicated data transfers of one sort or the other. While rest can execute the same actions as gRPC, the action TurnOnTheWater() doesn't fit into what a REST API was designed for. We would instead use REST where we required data transfers and other typical CRUD mechanics.

Ultimately, the right choice depends on your use case: REST for simplicity and interoperability, gRPC for high-efficiency internal microservice communication.

Possible errors

Network outage during some of the tests
The gRPC serverside logging was set to critical, tweaking this option might yield different results.

What's next?

This blog has only been about the differences in speed between REST and gRPC, but in reality, many other factors are present, if we were to truly compare the two frameworks. gRPC has claimed to not only be faster, but also more reliable, stable, and secure, and all of these metrics, as well as other metrics, would be interesting to cover, they are however out of scope in this particular blog-post.

Technologies used

References

Battle of the APIs gRPC v REST
gRPC/REST performance simplified gRPC v REST
Why milliseconds matter gRPC v REST
gRPC/REST evaluating performance gRPC v REST
REST vs RESTful REST
Statelessness REST
Http Methods REST
gRPC gRPC
HTTP/2 wiki
Suported gRPC languages gRPC
Design by Contract wiki
Google proto buffers gRPC
Serialization wiki
Website should load in 4 seconds blog
.NET Web API .NET
.NET Console App .NET
MySQL MySQL
.NET Stopwatch API .NET

Why I Built a Privacy-First AI Assistant for Visual Studio 2022 (Goodbye Cloud-Only Copilots!)

Wed, 25 Mar 2026 12:21:55 +0000

The Problem: Cloud AI is Great, but Privacy is Greater

We all love GitHub Copilot, but let's be honest: in an enterprise environment, Privacy isn't just a buzzword—it's a legal requirement. Sending proprietary codebases to cloud servers is often a strict "no-go" for many companies.

I realized that we needed a bridge between the power of LLMs and the security of a local environment. That’s why I built Local LLM Plugin Modern for Visual Studio 2022.

What is it?

It's a powerful, modern, and highly optimized AI assistant extension. It seamlessly integrates local LLMs via Ollama and cloud-based models like OpenAI, Anthropic (Claude), and Google Gemini directly into your coding environment.

Whether you want to run DeepSeek or Llama 3 entirely offline or leverage GPT-4o for heavy reasoning, this extension offers a native-feeling dark theme experience that boosts your productivity without leaving your IDE.

Engineering Highlights (Built for Performance)

Instead of just "making it work," I rebuilt this extension to meet enterprise standards:

Clean Architecture & MVVM: Separated UI, Core logic, and Infrastructure for maximum maintainability.
Dependency Injection: Utilizing Microsoft.Extensions.DependencyInjection to handle provider factories gracefully.
Lightning Fast Text Injection: Utilizes Visual Studio's native UndoContext. This ensures massive code blocks are applied instantly without freezing the editor and allows for a single-step Undo (Ctrl+Z).
Memory Efficiency: Optimized handling of large text blocks using StringBuilder and StringReader to prevent memory leaks.

Features that Boost DX (Developer Experience)

Multi-Provider AI Support: Switch seamlessly between Ollama, OpenAI, Claude, and Gemini.
Partial Selection Injection: Select a specific part of the AI's response to inject only that portion into your code, ignoring unnecessary conversational filler.
Smart Defaults: Automatically configures API URLs and model names based on the selected provider.
Advanced Text Manipulation Tools: Includes built-in tools to remove duplicates, modify and replicate variables, or batch-erase specific words.
Native Dark Theme: A sleek interface that perfectly matches Visual Studio 2022's native dark mode.

Keyboard Shortcuts (Power User Friendly)

The UI is entirely optimized for keyboard-only navigation:

Ctrl + 1: Open the AI Assistant (Global VS Shortcut).
Enter: Send your prompt to the AI.
Shift + Enter: Apply the response directly to your editor and close the window.
Esc: Cancel and close the assistant.

How to Get It?

You don't even need a link. Just open your Visual Studio 2022, go to Extensions -> Manage Extensions, and search for:

"Local LLM Plugin Modern"

Open Source & Contributing

This project is fully open source under the MIT License. I believe the best tools are built by the community, for the community.

Check out the repo here: furkiak/visualStudioLocalLLMPlugin

I'd love to hear your thoughts! Are you moving towards local LLMs for coding, or is cloud AI still your go-to? Let's discuss in the comments!

visualstudio #csharp #ai #productivity #programming

Shadow Logging via Events - Complete Decoupling of Business Logic and Logging in DI Environment

Tue, 10 Feb 2026 19:57:48 +0000

Hello, colleagues!

I want to share an approach to logging that radically simplifies architecture and strengthens SOLID principles.

I've created a code example on GitHub to demonstrate how shadow decoupled logging works through C# events.

What is Decoupled Logging?

Decoupled logging is an architectural approach where business classes do not contain direct logger calls (like ILogger.LogInformation). Instead:

Business classes generate events.
Specialized logger classes handle the events.
Business classes know nothing about loggers.
Logging is configured centrally at the application level, without polluting domain logic.

Pros and Cons of Decoupled Logging

There are opinions both "for" and "against" decoupled logging.

Typical arguments "for":

SRP purity: The class focuses on business logic; logging is an external concern.
Testability: No ILogger mocks needed; classes work standalone.
Flexibility and scalability: One event can be handled in all required ways: logs, metrics, audit. Easy to change event handling logic and logging libraries.
Decoupling for libraries: Consumers of business logic classes decide themselves whether to log events and which ones. No hard dependencies.
Performance: Business class does not format data for logs. When implementing event handlers, use smart fast caching of incoming events with subsequent post-processing - it doesn't block business logic.

Critics' objections boil down to a simple thesis: don't complicate things if not really needed - "inject ILogger and don't worry." This opinion sounds reasonable; I agree with such criticism - if you have a simple application, don't complicate it.

Extracting Logging from the Class

The simplest way to separate business logic and logging is to write a Wrapper for the business class.

Decorator/wrapper for logging is convenient but imposes usage rules:

Client code must work through the wrapper.
Refactoring becomes more complex.
Duplication and inheritance issues arise.

This approach makes logging not "shadow" - consumers indirectly know about it.

Complete Separation

Complete separation of business logic and logging is possible only using two independent objects: business class and log handler.

Simple example:

class OrderServiceLogger
{
    public OrderServiceLogger(FileLogger logger, OrderService orderService)
    {
        orderService.OrderCreated += (s, e) => logger.LogInformation($"Order {e.OrderId} created.");
    }
}

var orderService = new OrderService();
var fileLogger = new FileLogger();
var orderServiceLogger = new OrderServiceLogger(fileLogger, orderService);
orderService.CreateOrder(...);

This approach is straightforward, but if the application uses a DI container, it requires adaptation.

Shadowing Logging

DI containers perform 2 important tasks:

Object factory
Object lifetime management

Object creation is simple: the DI container will return 2 ready objects, with the log handler receiving the business class instance and logger instance upon creation.

var services = new ServiceCollection();
services.AddScoped<FileLogger>();
services.AddScoped<OrderServiceLogger>();
services.AddScoped<OrderService>();
var serviceProvider = services.BuildServiceProvider();

var orderService = serviceProvider.GetRequiredService<OrderService>();
var orderServiceLogger = serviceProvider.GetRequiredService<OrderServiceLogger>();

The problem is managing the lifetime of the log handler OrderServiceLogger, i.e., explicitly storing a reference to the created object and synchronizing its lifetime with the business class OrderService instance.

If we do nothing else, we'll have to explicitly create a new OrderServiceLogger instance wherever we create an OrderService instance and ensure their lifetimes match - that's not the behavior we want.

What we need:

Use only business logic object instances in business logic, in our example OrderService.
Business logic should know nothing about objects performing other tasks in the application, in our example logging via OrderServiceLogger.
When creating a business logic object, the application must guarantee all implemented service functions for it - if OrderServiceLogger is implemented for OrderService, it must be created in time and handle events.
Correct service function operation includes optimal application resource management - the OrderServiceLogger instance must be removed from memory after the associated OrderService object is destroyed.

These requirements are easy to implement, even within a DI container. We've sorted object creation; now we need to implement lifetime synchronization using weak references.

We need to ensure the created OrderServiceLogger object lives no less than the OrderService instance and is removed when no longer needed.

For this, we need an application-level object that:

Stores references to both dependent objects.
Monitors their lifetimes.
Removes OrderServiceLogger as soon as OrderService is removed.

We can implement such a class ourselves, where there is a key object and dependent objects. The architecture of such a class is simple:

Key object(s) are stored as weak references, which do not prevent the object from being garbage collected.
Dependent objects are stored as strong references, which prevent the garbage collector from destroying them.
The state of key objects is periodically checked - if they are removed, dependent objects are also removed.

For the simple case, we can use the ConditionalWeakTable<TKey,TValue> class from the System.Runtime.CompilerServices namespace, which already implements this logic.

Writing DI Logic

Let's implement an extension method for ServiceCollection and examine how it works.

public static class ServiceCollectionExtensions
{
    public static ServiceCollection AddScopedWithLogger<TService, TServiceInstance, TServiceLogger>(
        this ServiceCollection services)
        where TService : class
        where TServiceInstance : class, TService
        where TServiceLogger : class
    {
        // Register TServiceInstance.
        services.AddScoped<TServiceInstance>();
        // Register TServiceLogger.
        services.AddScoped<TServiceLogger>();
        // Register TService.
        services.AddScoped<TService>(sp =>
        {
            var instance = sp.GetRequiredService<TServiceInstance>();
            var logger = sp.GetRequiredService<TServiceLogger>();
            var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
            // Put instance and logger into ConditionalWeakTable.
            conditionalWeakTable.Add(instance, logger);

            return instance;
        });

        return services;
    }
}

The AddScopedWithLogger method does all the necessary work:

Registers all types in DI.
Implements the logic for creating and linking the business class and its event handler class.

Important - in the DI container, it is necessary to separate the logic for creating the business class object itself from the logic for creating the instance with all its shadow objects. For this, it is best to use business class contracts (interfaces).

public class OrderEventArgs : EventArgs
{
    public int OrderId { get; set; }
}

public interface IOrderService
{
    event EventHandler<OrderEventArgs> OrderCreated;
    void CreateOrder(int id, string customer);
}

Thus, the DI container will pass the OrderService instance to the OrderServiceLogger constructor.

In business logic, only contracts must be used, which is a recommended approach.

class OrderManager : IOrderManager
{
    public OrderManager(IOrderService orderService)
    {
        ...
    }
}

Correctly register all types in the container:

var services = new ServiceCollection();
services.AddScopedWithLogger<IOrderService, OrderService, OrderServiceLogger>();

Now, creating an object for its contract IOrderService will trigger the following code from the extension method:

...
// Register TService.
services.AddScoped<TService>(sp =>
{
    var instance = sp.GetRequiredService<TServiceInstance>();
    var logger = sp.GetRequiredService<TServiceLogger>();
    var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
    // Put instance and logger into ConditionalWeakTable.
    conditionalWeakTable.Add(instance, logger);

    return instance;
});
...

Here's the breakdown for the parameter combination IOrderService, OrderService, OrderServiceLogger:

services.AddScoped<IOrderService>(sp =>
{
    var instance = sp.GetRequiredService<OrderService>();
    var logger = sp.GetRequiredService<OrderServiceLogger>();
    var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
    // Put instance and logger into ConditionalWeakTable.
    conditionalWeakTable.Add(instance, logger);

    return instance;
});

As you can see, it's simple. OrderService and OrderServiceLogger objects are created with all dependencies, then both objects are saved in the ConditionalWeakTable<object, object>.

...
var conditionalWeakTable = sp.GetRequiredService<ConditionalWeakTable<object, object>>();
// Put instance and logger into ConditionalWeakTable.
conditionalWeakTable.Add(instance, logger);
...

The ConditionalWeakTable<object, object> object itself must be registered in the DI container with a lifetime equal to or greater than OrderService and OrderServiceLogger.

I recommend using Scoped if the registered objects live no longer. Singleton is not necessary.

And the last piece of the puzzle - at the application level, create a ConditionalWeakTable<object, object> instance that lives no less than the objects stored in it.

Simplest example:

class Program
{
    private static void Main()
    {
        var services = new ServiceCollection();
        services.AddScoped<ConditionalWeakTable<object, object>>();

        // Registration of all types and other application service code
        ...
        ...

        // Instance of ConditionalWeakTable that holds references to shadow objects.
        var conditionalWeakTable = serviceProvider.GetRequiredService<ConditionalWeakTable<object, object>>();
        // Start application work.
        Run(...);
    }
}

Conclusion

Advantages of the approach as I see them:

Logger is automatically bound to a specific class instance.
Weak references guarantee operation without memory leaks.
Centralized subscription in the DI container.
Ability to flexibly extend the number of shadow services and manage them.
Strong SOLID with minimal compromises.

I recommend using it for serious projects where quality architecture provides a tangible advantage.

Making Invalid States Unrepresentable: The Billion-Dollar Mistake That Wasn't

Thu, 29 Jan 2026 23:36:27 +0000

The billion-dollar mistake. That's what Tony Hoare, in a 2009 talk, called his invention of the null reference for ALGOL W in 1965. The quote gets repeated so often that "null is dangerous" has become conventional wisdom. Entry-level and intermediate developers especially hear it as dogma, without understanding the context or the alternatives that can be far worse.

But I think we're blaming the wrong villain. When developers avoid null, they often reach for a default instead of the fix Hoare himself had in mind, references the compiler checks. Compared with those defaults, null may have saved far more than it ever cost. In a managed runtime, a null reference exception stops the system at the moment it tries to use a value nobody supplied. A default would let it proceed with corrupted data and invalid logical decisions. The billion-dollar mistake framing counts the crashes but ignores the corruption that never happened.

Information security professionals value the CIA triad of Confidentiality, Integrity, and Availability. Software developers tend to obsess over availability, and that's understandable since a crashed service is visible, embarrassing, and can violate business SLAs. But in any system whose data outlives the request, integrity failures are often far worse. Data that looks valid but isn't can corrupt your system just as surely as SQL injection or a man-in-the-middle attack. The corruption just compounds slower and is harder to detect. This is the lens through which the null debate should be understood.

In managed runtimes like the CLR and the JVM, null crashes loudly at the point of misuse, which is an availability problem you can see and fix. A default value that masks missing data? That proceeds quietly until it causes a security vulnerability, a financial miscalculation, or data corruption that might require weeks to detect and more to fix.

What "Making Invalid States Unrepresentable" Actually Means

Yaron Minsky popularized the idea as "make illegal states unrepresentable" in his Effective ML material at Jane Street, including the 2011 post "Effective ML Revisited." It comes from functional programming, but the concept is practical: structure your data so that invalid combinations cannot exist. Invalid states should fail at construction time, not at runtime deep in business logic.

Consider a user registration:

public class UserRegistration
{
    public string Email { get; set; } = "";
    public string Password { get; set; } = "";
}

This class allows every invalid state imaginable. Empty email, empty password, any combination. The defaults make it easy to construct an object that looks valid but isn't. Code that receives this object has no way to know whether the empty string represents "not provided" or "explicitly set to empty" or "bug in upstream code."

Compare:

public class UserRegistration
{
    public string Email { get; }
    public string Password { get; }

    public UserRegistration(string email, string password)
    {
        if (string.IsNullOrWhiteSpace(email))
            throw new ArgumentException("Email is required", nameof(email));

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

        Email = email;
        Password = password;
    }
}

Now invalid states cannot be constructed, and there's no default email to mask a missing value.

C# 11 introduced the required keyword, which moves this enforcement to compile time for simpler cases:

public class UserRegistration
{
    public required string Email { get; init; }
    public required string Password { get; init; }
}

The compiler rejects any object initializer for UserRegistration that skips either property.

required enforces presence, and constructors enforce validity. required guarantees assignment, not a non-null value, so Email = null! still compiles. Use required when presence is all you need. Use constructors when you need validation logic, like checking that the email contains an @ or that the password meets complexity requirements.

At system boundaries, objects are often built by reflection rather than by code the compiler checks, so required can't protect them. Many serializers, ORMs, some dependency injection containers, and mocking frameworks can create the object without ever setting the property. For API contracts and external data, you still need runtime validation with [Required] attributes or explicit checks. System.Text.Json partly closes this gap. It has honored required since .NET 7, but it accepts an explicit null unless you enable RespectNullableAnnotations, added in .NET 9.

Where the Problem Usually Starts: API Contracts

The domain model above is clean, but most developers encounter this tension at the API boundary first. Consider a typical request DTO:

public class CreateUserRequest
{
    [Required]
    public string Email { get; set; } = "";

    [Required]
    public string Password { get; set; } = "";

    [Required]
    public bool RegisterForAlerts { get; set; } = false;
}

The [Required] attribute signals intent, but the developer adds = "" out of habit, a misguided sense of defensive coding, or to silence the compiler's CS8618 warning about an uninitialized non-nullable property. Now there's a contradiction: the attribute says "required" while the code says "default to empty string."

Which half wins depends on how the object gets created. A test or internal caller that builds the object directly never runs validation, so its empty string passes silently. Through the serializer, the default does no harm. The serializer creates the object before reading the payload, so a missing Email becomes "", and [Required] still rejects it because it treats empty strings as missing by default.

The bool is worse. Microsoft's ASP.NET Core model validation documentation notes that a non-nullable field is always valid, so [Required] on a bool can never fail, and a client that omits RegisterForAlerts gets false with no error.

The fix is simple. Don't add the default, and declare every field nullable so its absence is visible.

public class CreateUserRequest
{
    [Required]
    public string? Email { get; set; }

    [Required]
    public string? Password { get; set; }

    //The business could decide that this should default to false but test that assumption first!
    [Required]
    public bool? RegisterForAlerts { get; set; }
}

The [Required] attribute ensures the framework validates these fields before your code ever touches them, and bool? finally gives it a null to reject. If validation is bypassed, calling a method on the null Email throws a NullReferenceException and reading RegisterForAlerts.Value throws an InvalidOperationException, rather than handing back values that look valid.

But null is loud only where code dereferences it. Coalescing with ?? false, string interpolation, and a nullable database column all let it pass quietly. So null needs a partner. Validate at the boundary, then hand the value to a non-nullable domain type or database column, which turns any null that slips through back into a loud failure.

Why Defaults Are More Dangerous Than Null

Default values create four categories of problems that a null checked at construction avoids.

Silent propagation of invalid state. When a required field defaults to an empty string or zero, the invalid state propagates through the system. Each layer assumes the previous layer validated the data. Nobody validated it because it never looked invalid. The corruption accumulates until something finally breaks far from the source.

Consider a payment processing system:

public class PaymentRequest
{
    public decimal Amount { get; set; } = 0m;
    public string Currency { get; set; } = "USD";
    public string MerchantId { get; set; } = "";
}

A bug upstream fails to set the amount. The payment proceeds with Amount = 0, and an internal ledger that allows zero-value entries for credits and free tiers records it without complaint. No crash, no exception, no alert. The transaction logs show a valid-looking payment. Days later, someone notices revenue is wrong. The investigation takes hours because nothing obviously failed. Deleting = 0m wouldn't help, because a decimal is zero anyway. The fix is decimal? or required, which gives absence somewhere to show.

Ambiguous semantics. Does Amount = 0 mean "free transaction," "not set," or "bug"? Does Email = "" mean "user declined to provide" or "form field wasn't rendered"? Null keeps absence separate from every legitimate value.

A default value claims knowledge it doesn't have. Null admits ignorance.

This ambiguity becomes critical in update operations. When a client submits an update request, the API needs to distinguish between "set this field to empty" and "don't touch this field." In a typed object, null is the simplest way to express that distinction. The alternatives, such as JSON Merge Patch documents, protobuf field masks, or an Optional<T> wrapper, add machinery to every update contract. That machinery earns its place when a client must also be able to set a field to null, because plain null can't tell that request apart from "leave it alone."

Validation bypass. Code that checks if (amount != null) correctly identifies missing data. Code that checks if (amount != 0) conflates "missing" with "zero." Legitimate zero values become impossible to represent.

Security vulnerabilities. Consider a RateLimitPerMinute field that defaults to 0. In some systems, zero means "no limit" (nginx reads client_max_body_size 0 that way), so a malformed request that should be rejected instead gets unlimited access. Or a Permissions string that defaults to empty, which a downstream parser interprets as "inherit all permissions from parent." With null, the missing field stays distinguishable from a deliberate zero, so a validator can reject the request, require the field, or make a conscious decision about what absence means. A parser that reads null as "unlimited" repeats the same mistake.

Hoare's Mistake Was Unchecked Null, Not Null

Hoare called null his billion-dollar mistake, and the criticism was valid for its time. His own account says his goal was references checked automatically by the compiler, and the mistake he confessed was adding a null the compiler didn't check. The slogan dropped the compiler-checking half. His confession holds up. What doesn't hold up is the slogan's reading of it, that null itself is the danger.

ALGOL W and its descendants treated every reference as implicitly nullable. The compiler couldn't help you, and nothing forced developers to consider absence. In C and C++, where dereferencing null is undefined behavior rather than a guaranteed crash, unchecked null also produced the silent failures and vulnerabilities Hoare's talk describes.

But modern type systems address this problem without eliminating null. C# 8.0 introduced nullable reference types, compiler analysis that distinguishes string (expected never to be null) from string? (might be null) and warns when code dereferences a value that might be null. Kotlin distinguishes String from String? and refuses to compile the unchecked dereference. TypeScript has strict null checks. The billion-dollar mistake wasn't null itself; it was nullable references in type systems that never flagged missing handling.

Hoare's mistake wasn't inventing null. It was inventing null without inventing string?.

The mistake we keep making today is different. It's the pattern of masking errors with defaults instead of failing fast. Every system that returned -1 instead of throwing an exception. Every API that substituted empty arrays for error responses. Every constructor that initialized required fields to placeholder values. Null can mask an error too, when a function returns it in place of the error, and it raises the alarm only where presence was required. So the line isn't null versus default. It's whether something forces the absence to be handled.

Counterarguments and When Defaults Make Sense

"Null reference exceptions are the most common runtime error." They're among the most common, and that's the point. The frequency of null reference exceptions reflects how often code fails to handle absent values, not a flaw in null itself. Non-nullable types do cut that frequency, by moving the failure to compile time rather than hiding it. Replacing null with defaults doesn't. It turns the same bugs into data corruption instead of crashes.

The frequency also says something about the team. Most of those exceptions are ordinary oversights. But some keep recurring, in places where a field everyone assumed was required turns up missing. Those can signal something deeper, a continuous misalignment between the development team and stakeholders about what the system should accept and produce. Unit tests exist to test assumptions and prove agreement in both application logic and API contracts. If null reference exceptions keep appearing, the team hasn't captured those agreements in tests, or the agreements themselves are unclear. In those cases, the exceptions are symptoms of a collaboration problem, not just a coding problem.

"Option/Maybe types are strictly better than null." For representing intentional absence, they are better. Option<User> makes it explicit that a user might not exist, and pattern matching forces you to handle both cases. That's also why Option.getOrElse(default), used to silence a None the code should have handled, defeats the purpose. The whole point is to force handling, not to provide an escape hatch.

But this proves my argument rather than refuting it. In a language with exhaustive matching, like Rust, a match that ignores the None case won't compile. That's the same principle I'm advocating: force handling, don't mask absence. Most runtimes depend on null, and used correctly with modern type systems, it comes close to the guarantee Option types give in functional languages.

C#'s analysis is advisory, and !, default, and deserializers can all defeat it, so its guarantee is weaker than Rust's. Treating nullable warnings as errors closes the gaps the compiler can see. Arrays, struct defaults, and reflection-based construction stay outside its analysis, and boundary validation has to cover them.

"Defensive programming means providing safe defaults." This conflates two different concerns. Resilience at system boundaries means handling malformed external input gracefully, but that's different from masking bugs internally. Providing "safe" defaults inside the system just moves the failure somewhere harder to diagnose.

"Users shouldn't see crashes." Correct, which is why you handle errors at system boundaries. But the crash should still happen internally. Catch exceptions at the API layer, log the details, return a user-friendly error. The internal crash gave you the information to fix the bug. A silent default would have hidden it. In a queue or batch job, outside any request, the crash should send the one record to a dead-letter queue, not stall the records behind it.

"Some fields genuinely have sensible defaults." True. A CreatedAt timestamp defaulting to DateTime.UtcNow makes sense. A RetryCount defaulting to 0 represents legitimate initial state, and so does an empty order list for a customer who has never ordered. The same empty list returned for a failed fetch masks the failure. The distinction is between defaults that represent valid initial state versus defaults that mask missing required data. User-provided data, external inputs, and required business fields typically don't have one.

Exceptions for Bugs, Result Types for Expected Outcomes

If failing loudly is the goal, why not use exceptions everywhere?

A null on a required field represents a violated constraint, something the system was promised it wouldn't receive. That's a bug. The correct response is to crash, log, and fix the code. A Result type represents an expected domain outcome: "user not found" or "validation failed" aren't bugs. They're legitimate results that correct code produced from valid input.

If correct code with valid input could produce this result, use a Result type. If not, fail fast with an exception. Both approaches force handling; neither lets you ignore failure and proceed with corrupted state. The danger is when either mechanism gets misused to mask absence: catching exceptions and substituting defaults, or calling Result.GetValueOrDefault() without handling the failure case.

Validate at Construction, Trust at Consumption

The confusion around null often stems from conflating two different phases.

At construction time, invalid states should fail immediately. Validation should happen once, at the boundary, with clear errors for invalid input. Objects that exist should be valid by construction.

At consumption time, code shouldn't need to check validity. Internal code that receives a UserRegistration shouldn't need to re-validate the email because the constructor already guarantees it's present and valid.

This unsettles developers who've been taught to validate defensively at every layer. But spreading validation across layers is itself a source of bugs. When validation logic lives in the controller, the service, the repository, and the domain model, you've scattered what should be encapsulated business rules across your entire codebase. When validation rules change, you update three places and miss the fourth.

This doesn't mean a single validation layer. Systems have multiple trust boundaries: the API gateway, service boundaries, aggregate roots, database constraints. Each boundary validates what it needs to trust. Validate at each door, trust everyone inside that room.

Practical Guidelines

Enforce requirements at the correct layer. At ingress boundaries (API DTOs, deserialization), fields may be nullable because input might be missing. After validation, domain objects should have non-nullable required fields because their existence proves validity. Inside the domain, a nullable int? signals "this is optional."

Reserve defaults for genuinely optional fields with valid initial states. Retry counts, timestamps, tuning settings like timeouts, and accumulators qualify.

Prefer crashes to silent corruption. A null reference exception fails at the first dereference of the missing value instead of at an unknown later point. A default value that hides the bug lets it reach production and corrupt data.

Failing Loudly Is a Feature

The fear of null comes from the pain of decades of null reference exceptions in production, and systems that crashed when they should have kept running in theory. But crashes are symptoms, not the disease. The disease is code that doesn't handle absence properly. The cure isn't eliminating null; it's using null correctly as part of a system that makes invalid states unrepresentable.

Default values do the opposite. When you substitute a default for missing data, you're creating records that claim to represent reality but don't. Every downstream system that trusts that data inherits the lie.

The billion-dollar mistake we're still making isn't null. It's the widespread practice of substituting defaults for validation, prioritizing code that runs over code that runs correctly. In a system whose data outlives the request, given the choice between an availability problem you can see and fix, and an integrity problem that compounds invisibly until something important breaks, I'll take the availability problem every time.

I Shipped a Lightweight Uptime & SSL Monitor — Here’s a Quick Demo

Thu, 08 Jan 2026 19:26:03 +0000

I built Site Informant because I wanted a monitoring tool that was:

simple
affordable
developer-friendly
and not overloaded with features I don’t need

It checks uptime, tracks response time, and warns before SSL certificates expire, with clean alerts and predictable pricing.

I put together a quick 30-second demo video that shows exactly what it does, no fluff:

Watch the demo:
https://www.youtube.com/watch?v=JM2GJ_504Q0

The stack behind it is mostly .NET 8, Web API, Blazor WebAssembly, EF Core, SQLite, and Stripe, with a background service doing the monitoring work.

If you’re curious or want to try it on your own site:
https://siteinformant.com

Feedback welcome, especially from other devs who’ve built or used monitoring tools before.

~ Sergey

Optimization Log: How One Line of Code Unlocked 33,000 Agents

Mon, 08 Dec 2025 20:32:48 +0000

Subtitle: A developer diary on breaking the 66k ceiling and the power of Object Pooling in .NET.

In my last deep dive, "The Quick Brown Fox 2: The Silent Hordes," we pushed the FSM_API to its absolute limits. We built a dynamic, expanding world where Foxes tried to survive a landscape littered with Sleeping Dogs.

We hit a hard ceiling: 66,000 Agents at 30 FPS.

At the time, I assumed the bottleneck was purely architectural—specifically, the overhead of our string-based state lookups. I was ready to accept that 66k was the limit until we refactored the entire core to use Integer Hashing.

I was wrong. The bottleneck wasn't just the architecture; it was a "Design Miss" in my own simulation logic.

The "Oops" Moment

While gathering data for my article on the "$320 Billion Garbage Tax," I ran a profiler on the "Silent Hordes" demo to measure memory allocation. The results were horrifying. The simulation was generating 20 MB of garbage every single frame.

For a C# developer, this is the equivalent of lighting your CPU on fire. The Garbage Collector (GC) was stopping the world constantly to clean up a mess I was creating 30 times a second.

I tracked the allocation to the Spatial Hashing loop—the system the agents use to find each other.

The Culprit:

// Inside the Update Loop...
foreach (var agent in _allAgents)
{
    // ... calculate cellKey ...
    if (!Grid.TryGetValue(cellKey, out var cell))
    {
        cell = new GridCell(); // <--- THE KILLER
        Grid[cellKey] = cell;
    }
    // ...
}

In my rush to build the stress test, I was allocating a new GridCell() for every populated cell in the world, every single frame, only to discard them at the end of the tick. At 66,000 agents, that is thousands of allocations per millisecond.

The Fix: Don't Create, Reuse.

The solution was a classic game development pattern: Object Pooling.

Instead of letting the GC eat those cells, I created a Queue<GridCell>. When the frame ends, instead of clearing the dictionary and letting the cells rot in memory, I wipe their data and shove them into the queue. When the next frame starts, I pull them out.

The Impact:

Allocations per Frame: 0 MB.
GC Pressure: Non-existent.

The New Ceiling

The results of this single optimization were instant and violent. We didn't just inch past the previous record; we smashed it.

Previous Limit: 66,000 Agents @ 30 FPS.
New Limit: 99,000 Agents @ 30 FPS.

We gained 33,000 additional agents—a 50% increase in total capacity—just by stopping the memory churn.

If we look at the previous cap of 64,000 agents, the performance jumped from 30 FPS to 53 FPS (a 76% increase in speed).

What This Means

This discovery validates the thesis of our "Garbage Tax" article: we are often paying for performance we already own but are wasting on bad memory management.

The FSM_API was ready to handle 100,000 agents all along. The logic was fast enough. The architecture was sound. It was simply drowning in digital trash.

With the memory leak plugged, we are now standing at the door of 100,000 active, logic-driven entities. And remember—we still haven't switched to Integer Hashing yet.

When we combine this memory efficiency with the upcoming O(1) lookup refactor, 100k might just be the starting line.

Read the Full Story:

Part 1: The Quick Brown Fox 2: The Silent Hordes (The Setup)
Part 2: The $320 Billion Garbage Tax (The Economic Analysis)

Get the Code & Run the Test:
Clone the repo and run the StressProfiler to see these numbers on your own machine.
https://github.com/TrentBest/SimpleDemos

Resources & Code:

The FSM Package (Unity Asset Store):
https://assetstore.unity.com/packages/slug/332450

NuGet Package (Non-Unity Core):
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API

GitHub Repository:
https://github.com/TrentBest/FSM_API

Simple Demos Repository (Run the Stress Test):
https://github.com/TrentBest/SimpleDemos (Clone this repo and run the StressProfiler project to reproduce these numbers.)

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

We'd love to hear your thoughts! Please Like this post, Love the code, and Share your feedback or what you've built with the API in the comments.

The $320 Billion Garbage Tax: What My Stress Tests Revealed About C# Memory Costs

Sun, 07 Dec 2025 21:37:34 +0000

In the world of high-performance computing, we often obsess over Big O notation and algorithmic complexity. We optimize our loops, we thread our logic, and we pat ourselves on the back. I thought I knew performance. I thought I was writing efficient code.

But recently, while stress-testing my FSM (Finite State Machine) API, I ran into an invisible wall. It wasn’t a logic bottleneck. It wasn’t a threading issue. It was a "Garbage Tax" I was paying without even realizing it.

When you look at the global compute market—cloud, enterprise, and desktop—it is an industry valued at just over $1 Trillion USD. My benchmarks suggest that due to inefficient memory management, we are paying a hidden 32% tax on that execution time. That amounts to nearly $320 Billion dollars wasted every year, burned on CPU cycles doing nothing but cleaning up digital trash.

Part 1: The Methodology

To truly understand where the performance floor was, I ran two distinct stress tests.

1. The "Raw" Stress Test
First, I subjected the API to a pure computational crucible. I created agents that did nothing but heavy mathematical processing and asynchronous tasks, isolating the FSM logic from any rendering or physics noise. I wanted to see the raw "ops per second" the architecture could handle.

2. The "Quick Brown Fox" Simulation
Second, I needed to validate this behavior in a "real" scenario. I deployed a 1D simulation called "The Quick Brown Fox & The Lazy Dog."

Foxes traverse a world, jumping over obstacles and fleeing.
Dogs sleep, wake up, and chase foxes using spatial lookups.

This forced the API to handle actual game logic—patrolling, chasing, fleeing—at a massive scale.

Part 2: The Data

The results were immediate, quantifiable, and humbling.

Table A: The Raw Stress Test (Math & Async)
In the raw test, performance held up well, but the memory cost was evident.

130,000 Agents @ 34 FPS
Memory Delta: 20 MB per frame

Table B: The "Quick Brown Fox" (Behavioral Simulation)
When we added spatial hashing and actual gameplay logic, the "Garbage Tax" became the dominant factor.

Agents	FPS	Mem Delta (MB)	World Size	Density
10,000	857	-1	7,028	1.4
30,000	166	7	114,000	0.26
50,000	50	16	1,880,000	0.02
64,000	30	20	13,300,000	0.004

[Data Source: qbf\_stress\_data.csv]

At 64,000 agents, my system was churning through ~20 MB of garbage every single frame. At 30 FPS, that is 600 MB of allocations per second.

Part 3: The Lamentation (Ego Death)

I’ll be honest: looking at this table dragged my ego through the mud.

I pride myself on being a programmer who "knows" performance. I engineered this API to be robust. I built it to scale. But the data doesn't lie. I was effectively asking the CPU to spend 32% of its time acting as a janitor, cleaning up temporary objects I shouldn't have allocated in the first place.

I realized I wasn't just hitting a hardware limit; I was hitting a design limit of my own making.

Part 4: The 32% Tax on Your Desktop

What does this "Garbage Tax" actually mean for you?

We often talk about cloud costs, but let's talk about the machine sitting on your desk right now. My technology is designed to run on any .NET system—your laptop, your gaming rig, your workstation.

When software carries a 32% overhead due to inefficient memory management:

Gamers: That’s the difference between a stuttering 45 FPS and a buttery smooth 60 FPS.
Laptops: That’s 32% more battery power burned just to create and destroy temporary strings.
Workstations: That’s your fan spinning up to 100% because the CPU is thrashing memory instead of compiling your code.

My currently-in-progress refactoring to a Hash-Based API (moving from Strings to Integers) is designed to eliminate the 25% computational overhead of string lookups. But that 32% memory tax? That required a deeper look at how I was writing code.

Part 5: The "Bonus" Optimization

While analyzing the QuickBrownFox results, I found a specific, glaring inefficiency. It was a "Design Miss"—a simple mistake that was generating millions of unnecessary allocations.

In my Spatial Hashing loop, I was doing this:

// The "Design Miss"
Grid.Clear(); 
foreach (var agent in _allAgents)
{
    // ...
    if (!Grid.TryGetValue(cellKey, out var cell))
    {
        cell = new GridCell(); // <--- ALLOCATION EVERY FRAME!
        Grid[cellKey] = cell;
    }
    // ...
}

For 64,000 agents, I was allocating thousands of new GridCell objects every single frame, only to throw them away milliseconds later.

The Fix: Grid Cell Pooling

I implemented a simple Object Pool. Instead of creating new cells, I reuse the old ones.

Before: new GridCell() -> GC Pressure.
After: _cellPool.Get() -> 0 Allocations.

I refactored the simulation to pool these cells. The logic is identical, but the memory footprint is completely different.

Part 6: The Results (Optimization Validated)

The impact of this single change was instant. By removing the allocation loop, we unlocked the CPU cycles that were previously drowning in garbage collection.

Table C: The Optimized "Quick Brown Fox"

Agents	FPS	Mem Delta (MB)	Improvement
10,000	971	0	+13% FPS
30,000	202	0	+21% FPS
50,000	77	-2	+54% FPS
64,000	53	1	+76% FPS
99,000	30	~0	NEW CEILING

[Data Source: qbf\_optimized\_data.csv]

The Takeaway

At the previous limit of 64,000 agents, we jumped from 30 FPS to 53 FPS—a nearly 76% performance increase just by stopping the garbage.

More importantly, we pushed the simulation ceiling from 64,000 to 99,000 agents.

We found the 32% tax, and we didn't just pay it—we abolished it. This is why I am building the Singularity Workshop: to ensure that when you run your code, you are using the whole machine, not just the parts the Garbage Collector isn't using.

Catch Up on the Series

Before the big fight, check out the data that led us here:

The Control Group: Benchmarking the "dirty" version of the API.
https://coderlegion.com/7988/the-control-group-benchmarking-the-dirty-version-of-my-fsm-api
The Quick Brown Fox: Validating behavior against the silent hordes.
https://coderlegion.com/8009/the-quick-brown-fox-2-the-silent-hordes
Fight Night Announcement: The Lightweight Challenger vs The Heavyweight Champ.
https://coderlegion.com/8147/fight-night-announcement-the-lightweight-challenger-vs-the-heavyweight-champ

Get Ready for Fight Night!

This optimization is just the warm-up. We are heading toward Fight Night, where we will see our Lightweight Champion—now punching up at nearly 100,000 agents at a smooth 30 FPS—take on the heavyweights of the industry. The benchmarks are set, the gloves are off, and the garbage tax has been repealed. Stay tuned.

Resources & Code:

The FSM Package (Unity Asset Store):
https://assetstore.unity.com/packages/slug/332450

NuGet Package (Non-Unity Core):
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API

GitHub Repository:
https://github.com/TrentBest/FSM_API

Simple Demos Repository (Run the Stress Test):
https://github.com/TrentBest/SimpleDemos
(Clone this repo and run the StressProfiler project to reproduce these numbers.)

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

We'd love to hear your thoughts! Please Like this post, Love the code, and Share your feedback or what you've built with the API in the comments.

FIGHT NIGHT ANNOUNCEMENT: The Lightweight Challenger vs. The Heavyweight Champ

Wed, 03 Dec 2025 23:20:00 +0000

In the Red Corner: Weighing in with a massive learning curve and complex boilerplate... the reigning champion of performance: Unity ECS (DOTS)!

In the Blue Corner: Weighing in at a lean 45kb... the Object-Oriented underdog: FSM_API!

We are preparing for the ultimate showdown.

THE ROAD TO THE TITLE FIGHT:

Before we step into the Unity Ring for the visual bout, we had to prove the challenger could take a punch. We put the FSM_API through "The Gauntlet"—a raw, Console-Only C# simulation involving 66,000 active agents ("Quick Brown Foxes" vs. "Lazy Sleeping Dogs").

The results were bloody. The performance was undeniable.

THE TALE OF THE TAPE (The Articles):

Round 1: The Massacre (Benchmarks)
See the breakdown of the "Silent Hordes" simulation where we maintained a stable 30 FPS under massive idle load.
Read the Benchmark:
https://coderlegion.com/8009/the-quick-brown-fox-2-the-silent-hordes

Round 2: The Training Camp (Optimization Deep Dive)
A true fighter knows their weaknesses. In this second technical breakdown, I expose the raw memory profiles. I’m embarrassed to admit how much optimization headroom is still left on the table—which is terrifying, because even unoptimized, our extrinsic benchmarks are putting us in contention with the Champ (ECS).
See the Optimization Data:
https://coderlegion.com/7988/the-control-group-benchmarking-the-dirty-version-of-my-fsm-api

COMING SOON: THE MAIN EVENT
Stay tuned for our next article, where we bring the carnage into the Unity Scene View.

Will the lightweight 45kb DLL show its raw digital power? Or will the heavyweight bloat of ECS deliver yet another TKO?

Get to know the Challenger before the bell rings:

Asset Store ($30):
https://assetstore.unity.com/packages/tools/behavior-ai/the-singularity-workshop-fsm-api-advanced-332450

GitHub (Free):
https://github.com/TrentBest/FSM_API

Coach's Advice:
"Don't step into the ring without the right gear, kid. Grab the package. It's on the house."
NuGet (Free):
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API/#supportedframeworks-body-tab

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

The Control Group: Benchmarking the "Dirty" Version of My FSM API

Sun, 30 Nov 2025 08:32:53 +0000

In software architecture, optimization without measurement is just guessing.

I am currently in the process of a major refactor for my C# Finite State Machine API (FSM_API). We discovered some concurrency friction in the underlying dictionary lookups and realized that my heavy reliance on string keys was creating unnecessary O(N) overhead.

The plan is to switch to ConcurrentDictionary and implement Integer Hashing to eliminate string allocations entirely. But before I tear the engine apart, I needed a baseline. I needed to know exactly how much "tax" I was paying for those strings.

So, I built a Stress Profiler.

The Torture Test

I designed a benchmark to intentionally break the system. The goal wasn't to see if it would fail, but how it would fail.

The test setup is simple but brutal:

The Crowd: We spawn between 50,000 and 240,000 Agents.
The Payload: Each agent performs basic math, some branching logic, and—crucially—a ToString() allocation every update to simulate
memory pressure (Heap Thrashing).
The Variable: We test three different "Time-Slicing" intervals:

1.) Interval 1: Every agent updates every frame (100% Load).

2.) Interval 2: Agents skip 1 frame (50% Load).

3.) Interval 3: Agents skip 2 frames (33% Load).

The Hypothesis

My theory was that the Dictionary<string, ...> lookups would become the primary bottleneck as the agent count rose. Even when agents are "sleeping" (skipping frames), the API still has to iterate through the list to check if it's their turn.

If the architecture is sound, "Interval 2" should theoretically double our capacity. If it doesn't, we know the overhead of the list management itself is too high.

Here is the raw data from the "Dirty" version of the API—before the optimization pass which will be shared the moment I've accomplished the refactoring.

Stress Test Results (Baseline API)

Interval	Agents	FPS	Logic Ops/Frame	Mem Delta (MB)
1	50000	58.78	150,000	8
1	55000	106.30	11,000	27
1	60000	72.01	180,000	8
1	65000	100.64	13,000	30
1	70000	63.44	210,000	13
1	75000	96.77	15,000	38
1	80000	57.21	240,000	36
1	85000	87.40	17,000	43
1	90000	46.43	270,000	16
1	95000	75.70	19,000	48
1	100000	41.40	300,000	16
1	105000	62.54	21,000	54
1	110000	38.60	330,000	27
1	115000	58.02	23,000	59
1	120000	34.88	360,000	26
1	125000	57.30	25,000	61
1	130000	33.57	390,000	32
1	135000	53.90	27,000	68
1	140000	31.47	420,000	26
1	145000	50.50	29,000	70
1	150000	28.80	450,000	29
2	80000	70.34	8,000	55
2	85000	71.45	127,500	12
2	90000	83.53	13,500	45
2	95000	62.50	142,500	27
2	100000	69.49	15,000	-4
2	105000	59.55	157,500	23
2	110000	67.81	16,500	53
2	115000	53.22	172,500	40
2	120000	57.58	18,000	-1
2	125000	50.64	187,500	28
2	130000	56.93	19,500	64
2	135000	42.57	202,500	46
2	140000	48.11	21,000	2
2	145000	44.63	217,500	33
2	150000	48.52	22,500	74
2	155000	40.62	232,500	51
2	160000	45.80	24,000	87
2	165000	35.97	247,500	42
2	170000	38.35	25,500	4
2	175000	35.65	262,500	41
2	180000	40.20	27,000	86
2	185000	32.44	277,500	57
2	190000	37.83	28,500	93
2	195000	31.51	292,500	60
2	200000	33.02	30,000	2
2	205000	30.64	307,500	50
2	210000	34.37	31,500	100
2	215000	28.08	322,500	64
3	120000	46.49	6,000	79
3	130000	56.15	130,000	30
3	140000	49.74	14,000	-9
3	150000	47.27	150,000	21
3	160000	44.20	16,000	75
3	170000	39.76	170,000	35
3	180000	37.77	18,000	1
3	190000	37.70	190,000	32
3	200000	35.25	20,000	97
3	210000	32.49	210,000	57
3	220000	30.48	22,000	2
3	230000	31.41	230,000	37
3	240000	29.61	24,000	116

The Analysis

The results gave us the exact "Failure Floor" we were looking for.

The Hard Limit: At 140,000 agents running every frame, we hit the 30 FPS floor.

The Overhead: Notice that switching to Interval 2 didn't perfectly double our capacity (we capped around 215k, not 280k). This confirms that simply iterating through 200,000 string-based handles costs CPU time, even if the agents do nothing.

The GC Spike: The memory delta column shows the "Sawtooth" pattern where the Garbage Collector had to step in aggressively to clean up those string allocations.

Now we have our target. The next version of the API needs to beat these numbers to prove the value of the refactor. Let's get to work.

Resources & Code:
Simple Demos Repository (Run the Stress Test): https://github.com/TrentBest/SimpleDemos (Clone this repo and run the StressProfiler project to reproduce these numbers.)

The FSM Package (Unity Asset Store):
https://assetstore.unity.com/packages/slug/332450

NuGet Package (Non-Unity Core):
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API

GitHub Repository:
https://github.com/TrentBest/FSM_API

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

We'd love to hear your thoughts! Please Like this post, Love the code, and Share your feedback or what you've built with the API in the comments.

The Sentient Primitive: Waking Up Your Data with FSMs

Sat, 29 Nov 2025 07:09:59 +0000

In standard game development, we are taught that variables are silent containers. A bool is just a box that holds true or false. It doesn't do anything. To know if it changed, we have to pester it constantly:

// The Old Way: The Polling Trap
void Update() {
    if (isDead == true) { // Asking every single frame...
        PlayDeathAnimation();
    }
}

This is the "Silent Variable" problem. It leads to spaghetti code, race conditions, and Update() loops clogged with thousands of if statements checking for things that haven't changed.

But what if a Boolean wasn't just a box? What if it was a Finite State Machine?

1. The FSM_Bool: The Atomic Unit of Behavior

By wrapping a primitive in an FSM, we transform it from Passive Data into Active Behavior. It doesn't just hold a value; it has a lifecycle.

Enter True: Fire the event (e.g., "Turn on Light").
Update True: Maintain state (e.g., "Humming sound").
Exit True: Cleanup (e.g., "Fade out light").

Suddenly, your logic is decoupled. The code controlling the light doesn't need to check the switch. The switch tells the light what to do.

// The New Way: Reactive Primitives
var lightSwitch = new FSM_Boolean(
    name: "LivingRoomLight",
    startValue: false, 
    onTrue: (ctx) => LightFixture.TurnOn(),  // Fire and forget
    onFalse: (ctx) => LightFixture.TurnOff() // Fire and forget
);

// To operate it, we just change the target. The FSM handles the logic.
lightSwitch.Set(true);

2. Evolution: The FSM_FloatLimit

The concept explodes in potential when we move beyond Booleans. Consider the float. Usually, we use floats for Health, Stamina, or Mana.

In the old world, a Health System is a messy manager class. In the FSM world, a Health System is just a single Float with a Threshold.

Introducing the FSM_FloatLimit. It is an FSM that monitors a value and triggers a transition when a threshold is crossed.

The Constructor:

var healthSystem = new FSM_FloatLimit(
    currentValue: 100.0f, 
    threshold: 0.0f, 
    OnThreshold: (ctx) => Player.Kill()
);

The Internal Logic (Abstracted):
Inside the black box, this FSM has two states: Safe and Breached.

State "Safe": The value is above the threshold.
Transition: If Value <= Threshold -> Go to Breached.
State "Breached": Execute OnThreshold.

You no longer need a PlayerHealthManager.cs. You just need a smart float.

3. Complex Data Shapes from Simple Primitives

When you start composing these "Smart Primitives" together, you aren't writing code anymore; you are sculpting Logic Shapes.

Imagine a Weapon Reload System constructed entirely of primitives:

AmmoCount (FSM_IntLimit): Triggers "Empty" when it hits 0.
ReloadTimer (FSM_FloatTimer): Triggers "Complete" after 2.0 seconds.
IsReloading (FSM_Bool): The master switch.

The architecture becomes a chain reaction:

AmmoCount hits 0 -> Sets IsReloading to True.
IsReloading (True) -> Starts ReloadTimer.
ReloadTimer (Complete) -> Refills AmmoCount and sets IsReloading to False.

Beyond Numbers: The Reactive String

The power of the "Sentient Primitive" isn't limited to simple math. It transforms how we handle text and input.

Consider the standard way we handle cheat codes or spell casting in games: we log every keystroke into a buffer and run a string comparison every frame. It is tedious and error-prone.

In our FSM-driven world, we treat the String as a Stateful Pattern Matcher.

The FSM_Regex

Imagine an FSM initialized with a Regular Expression. It doesn't just "hold" a string; it hunts for a pattern within the stream of data you feed it.

// Defining a "Spell" using a Reactive String
var fireballSpell = new FSM_Regex(
    pattern: "UP, DOWN, A, B", // The Konami Code of magic
    OnMatch: (ctx) => CastFireball(),
    OnFail: (ctx) => PlayFizzleSound()
);

// We just feed it inputs. The FSM tracks the sequence state internally.
fireballSpell.Input("UP");   // State: Tracking...
fireballSpell.Input("DOWN"); // State: Tracking...
fireballSpell.Input("X");    // State: Failed -> Trigger OnFail -> Reset

This turns complex input handling into a simple definition. You aren't writing an "Input Manager"; you are just defining the shape of a valid command.

The Paradigm Shift: Composition over Management

When you adopt this mindset, the "Manager Classes" that plague modern software development start to disappear.

You don't need a HealthManager; you have an FSM_Float.
You don't need an InputComboManager; you have an FSM_Regex.
You don't need a DayNightCycleManager; you have an FSM_Timer.

You are creating a visual language where the "bricks" of your building aren't dead clay; they are active participants in the architecture. They know when to hold together, and they know exactly when to break apart.

Visualizing the FSM_Regex

Resources & Code:

The FSM Package (Unity Asset Store):
https://assetstore.unity.com/packages/slug/332450

NuGet Package (Non-Unity Core):
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API

GitHub Repository:
https://github.com/TrentBest/FSM_API

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

We'd love to hear your thoughts! Please Like this post, Love the code, and Share your feedback in the comments.

10. FSM_API for Non-Coders: A Big Picture Overview (From our Documentation)

Sat, 15 Nov 2025 22:14:52 +0000

We believe the most reliable software logic is logic everyone can understand.

The complex systems that drive modern applications—from character AI in games to business workflows and industrial robotics—are often best articulated not by a developer, but by the subject matter experts. These experts instinctively express domain behavior as an organized set of phases and rules, often visualized as hierarchical Finite State Machines.

This natural structure is the foundation of the Finite State Machine (FSM), and it is why we created this overview. FSMs are not merely a developer’s tool; they are a universal language. This guide is designed to bridge the gap, enabling your domain expertise to translate seamlessly and reliably into the design of robust, predictable, and maintainable software systems.

Without any further ado:

10. FSM_API for Non-Coders: A Big Picture Overview

Have you ever tried to describe a complex process to someone, like making coffee ☕ or building a LEGO castle , and found yourself saying, "First you do this, then if that happens, you do this other thing, otherwise you do something else entirely"? If so, you've already grasped the core idea behind Finite State Machines (FSMs)!

At its heart, FSM_API is a powerful tool designed to make complex software behaviors predictable, organized, and easier to manage, even if you don't write code yourself. It helps turn messy, "if-this-then-that" logic into clear, step-by-step instructions.

What is a Finite State Machine (FSM)? (The Simple Version)

A simple, real-world example of an FSM: a traffic light.

Imagine anything that changes its behavior based on its current situation.

A traffic light is either Red, Yellow, or Green. It can't be Red and Green at the same time. It changes from Green to Yellow only, not directly to Red.
A door is either Closed, Opening, Open, or Closing.
A game character might be Idle, Walking, Running, Jumping, or Attacking.

An FSM is just a way to formally describe these behaviors:

States: These are the specific "situations" or "modes" an entity can be in at any given moment (like "Green" for a traffic light, or "Walking" for a character). An FSM is always in exactly one state at a time.
Transitions: These are the rules that dictate how an entity moves from one state to another (e.g., from "Green" to "Yellow" when a timer runs out, or from "Walking" to "Jumping" when the player presses the jump button).

FSM_API helps developers build and manage these FSMs in a clear and organized way, making sure all the rules are followed and behaviors are predictable.

How FSM_API Helps You (Even if You Don't Code)

While FSM_API is a coding tool, its benefits directly impact anyone involved in designing or understanding the behavior of a system, like game designers, project managers, or QA testers.

1. Clearer Communication

An FSM diagram like this gives the whole team a clear map of how the AI should behave.

Instead of ambiguous descriptions, an FSM provides a visual and logical map of how something behaves. Everyone on the team can look at an FSM diagram and immediately understand the flow.

Example: "The enemy moves from 'Patrolling' to 'Chasing' when it 'sees' the player." This becomes a clear transition rule.

2. Fewer Bugs & More Reliable Behavior

When behaviors are explicitly defined, it's much harder for unexpected "edge cases" or illogical situations to occur (like a character trying to jump while they are already dead). This leads to more stable and reliable software.

Benefit: Less time spent fixing frustrating, unpredictable issues.

3. Easier to Change and Expand

Because the behavior is modular (broken into states and transitions), adding new features or changing existing ones becomes much simpler. You don't have to overhaul the entire system.

Example: Want to add a "Stealth" state to your enemy? You simply add the new state and define how to get into and out of it, without breaking the existing "Patrol" or "Chase" logic.

4. Better Performance

FSM_API is built to be fast. This means your games or applications will run smoother, even when managing many complex characters or systems at once.

Benefit: A more responsive and enjoyable experience for the end-user.

5. Empowers Non-Coders (The "Context" Connection)

The FSM (the brain) contains the logic, while the Context (the body) is the actual object that performs the actions.

When a developer uses FSM_API, they link the FSM to an actual "thing" in your game or application (this "thing" is called the Context).

Example: A game designer might say, "When the character is in the 'Jumping' state, I want them to play the 'Jump_Anim' and add an upward force." The developer then connects the FSM's "Jumping" state to the character's script (their Context) which knows how to play animations and apply force.
Benefit: This clear connection means designers can specify behavior in terms of game actions, and developers can implement it precisely, using the FSM as the bridge.

Who is This For?

Game Designers: Visualize and plan complex character AI, game mechanics, and UI flows with clarity.
Project Managers: Understand the scope and complexity of features related to dynamic behaviors.
QA Testers: Clearly define and test expected behaviors in various scenarios.
Technical Writers: Document system behaviors accurately and concisely.

FSM_API provides a common language and structure that helps bridge the gap between design and implementation, leading to more robust, understandable, and maintainable applications. We are actively working on integrating this into AnyApp, and also preparing it for submission to the Unity Asset Store so developers everywhere can benefit!

Want to Learn More About Development?

If you're interested in learning about the coding side of things from a clear, practical perspective, we highly recommend checking out Tim Corey. He's widely recognized as a fantastic resource for software development, and you can find his insightful content, courses, and community on his platform, DevForge, at iamtimcorey.com.

Resources & Code:

The FSM Package (Unity Asset Store):
https://assetstore.unity.com/packages/slug/332450

NuGet Package (Non-Unity Core):
https://www.nuget.org/packages/TheSingularityWorkshop.FSM_API

GitHub Repository:
https://github.com/TrentBest/FSM_API

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

06_FSM_Modifier Deep Dive: Modifying Your FSMs at Runtime (From our Documentation)

Fri, 14 Nov 2025 17:46:04 +0000

The FSM_API Advantage: Runtime Modification Technology

What sets the FSM_API apart is our FSMModifier technology, which allows for the dynamic reconstitution or definition of your Finite State Machines (FSMs) during runtime. No other FSM implementation offers this level of dynamic control over an FSM's blueprint after creation.

We believe in providing the deepest, most robust tools while allowing you to engage only as far as you need. We've done the deep theoretical work so you don't have to.

06. FSMModifier Deep Dive: Modifying Your FSMs at Runtime

The FSMModifier provides advanced capabilities to dynamically alter the blueprint (definition) of your Finite State Machines at runtime. This allows for highly adaptive behaviors, hot-swappable logic, or configuration changes without rebuilding your application.

While the FSMBuilder is used to initially design and build an FSM's definition, the FSMModifier allows you to change that definition after it has been created and registered with FSM_API. This is a powerful feature for scenarios requiring:

Adaptive AI: Changing an enemy's behavior patterns on the fly (e.g., learning new attacks, adapting to player strategies).
Dynamic UI: Adding or removing navigation paths or UI states based on user unlocks or content downloads.
Hot Reloading: Modifying FSM logic in a live environment (e.g., development tools for rapid iteration).
A/B Testing: Dynamically switching between different FSM behaviors for experimentation.

Table of Contents (Disabled for this article)

0. Introduction to FSM_API

Core Concepts: Your Guide to FSM_API
Getting Started with C# (Non-Unity)
FSMBuilder Deep Dive: Building Your FSMs
Understanding and Implementing Your Context (IStateContext)
Robust Error Handling: Cascading Degradation System
FSMModifier Deep Dive
Performance Tips & Best Practices
Common Use Cases & Examples
FSM_API for Non-Coders: A Big Picture Overview
Frequently Asked Questions (FAQ)

Accessing and Using the FSMModifier

The FSMModifier is an internal class, so you can't create it directly. Instead, you access its functionality through a set of public, static helper methods on FSM_API.Interaction. These methods are designed to simplify common modification tasks like adding or removing states and transitions.

The FSMModifier uses a fluent API pattern where you first stage the changes you want to make and then apply them with a single ModifyDefinition() call. All changes are batched and applied sequentially when ModifyDefinition() is called, making the process safe and predictable.

FSMModifier Methods: Altering the Blueprint

All the methods below are called on an instance of the FSMModifier class. You get this instance by calling a public method on FSM_API.Interaction.

Staging Changes with With... and Without...

`WithState()`: Adding a New State

This method adds a new state to an existing FSM definition. If a state with the given name already exists, the operation is ignored. Use WithModifiedState() to change an existing state.

C# Example:

FSM_API.Interaction.AddStateToFSM(
    "PlayerFSM",
    "SpecialAttack",
    onEnter: ctx => Console.WriteLine("Prepare special attack!"),
    onUpdate: ctx => Console.WriteLine("Execute special attack."),
    onExit: ctx => Console.WriteLine("Cleanup after special attack.")
);

`WithModifiedState()`: Updating an Existing State

This method modifies the actions (onEnter, onUpdate, and onExit) of a state that is already part of the FSM blueprint. If the state doesn't exist, the operation is ignored.

C# Example:

// Change the "Idle" state's behavior
FSM_API.Interaction.ModifyState(
    "PlayerFSM",
    "Idle",
    onEnter: ctx => Console.WriteLine("Entered a NEW and improved Idle state."),
    onUpdate: null, // You can pass null to remove an action
    onExit: ctx => Console.WriteLine("Exiting new Idle state.")
);

`WithoutState()`: Removing a State

This method stages a state for removal from the FSM definition.

C# Example:

// Remove a state and transition all instances to "InitialState"
FSM_API.Interaction.RemoveStateFromFSM("PlayerFSM", "Dead", null);

Important: When a state is removed, any active FSMHandle instances currently in that state will be immediately transitioned to a specified fallbackStateName. If you pass null or an empty string for the fallback, instances will automatically transition to the FSM's InitialState. The OnExit action of the removed state will be executed for these instances.

`WithTransition()`: Creating a New Path

This method adds a new transition rule between two states. If the transition already exists, the operation is ignored. Use WithModifiedTransition() to change an existing one.

C# Example:

// Add a new transition from "Idle" to "Sleeping"
FSM_API.Interaction.AddTransition(
    "PlayerFSM",
    "Idle",
    "Sleeping",
    ctx => ((PlayerContext)ctx).IsTired() && DateTime.Now.Hour > 21
);

`WithModifiedTransition()`: Updating a Transition

This method updates the condition of an existing transition between two states. If the transition doesn't exist, the operation is ignored.

C# Example:

// Change the condition for the "Damaged" -> "CriticallyInjured" transition
FSM_API.Interaction.ModifyTransition(
    "PlayerFSM",
    "Damaged",
    "CriticallyInjured",
    ctx => ((CharacterContext)ctx).Health <= 10 // Change from 25 to 10
);

`WithoutTransition()`: Blocking a Path

This method removes a specific transition rule. It requires the fromState and toState names to uniquely identify the transition.

C# Example:

// Remove the transition from "Running" to "Jumping"
FSM_API.Interaction.RemoveTransition("PlayerFSM", "Running", "Jumping");

Manipulating Live FSM Instances (FSMHandle)

While FSMModifier changes the FSM blueprint, the FSMHandle provides methods to directly influence individual, live FSMHandle instances at runtime. These operations do not alter the underlying FSM definition.

TransitionTo(): Forces an FSMHandle instance to immediately transition to a specified state, bypassing any conditions. This is useful for debug commands or for recovering from an error state.
ResetFSMInstance(): Resets the FSM instance to its initial state, as defined in its blueprint.
EvaluateConditions(): Manually checks all transition rules from the current state. This is especially useful for FSMs with a ProcessRate of 0, which do not update automatically.
DestroyHandle(): Shuts down this FSM instance, removes it from the API's internal system, and calls the OnExit action of its current state. This is a crucial cleanup step for any live instance that is no longer needed.

Important Considerations and Best Practices

Affects All Instances: Remember that changes made with FSMModifier affect the shared blueprint. All active FSMHandle instances created from that blueprint will immediately use the new states, transitions, and properties on their next update cycle.
Atomicity: The FSMModifier stages changes and applies them all at once when ModifyDefinition() is called. This is a robust design that prevents partial or inconsistent changes from corrupting the FSM blueprint.
State Removal is Handled Gracefully: The API will automatically handle instances in a removed state by transitioning them to a fallback state, ensuring your application doesn't crash or get stuck in an invalid state.

Support Us

If you find this project useful, you can support its development through PayPal.

Donate via PayPal

Useful Links

NuGet Package: TheSingularityWorkshop.FSM_API
GitHub Repository: TrentBest/FSM_API
License: MIT License
Advanced Integration On Unity Asset Store!
Basic Integration is pending updates on Marketing content.

Brought to you by

The Singularity Workshop – Tools for the curious, the bold, and the systemically inclined.

Because state shouldn’t be a mess.

How we recognized the need to pivot from pure ECS to pure FSM

Thu, 09 Oct 2025 22:17:25 +0000

The Architectural Pivot: Why The Singularity Workshop is Building MyVR with the FSM_API, Not a Custom Engine

At The Singularity Workshop, we are charting a course toward MyVR, a vision for a truly sovereign, scalable, and adaptable digital universe. Our initial approach centered on developing a custom-built Entity-Component-System (ECS) engine from scratch. However, to accelerate our mission and ensure the highest standards of architectural integrity, we made a decisive and necessary pivot.

We are now focused on a refined roadmap centered on the FSM_API (Finite State Machine Application Programming Interface), leveraging the robust services of Unity to build faster, stronger, and more clearly defined systems.

The Unavoidable Battle with State

For any ambitious project aiming to handle thousands of entities with complex behaviors—like large-scale RTS simulations or high-fidelity virtual worlds—the greatest obstacle is the inherent, complex "Battle with State."

Traditional object-oriented or even custom ECS systems can often lead to tangled code and systems that are impossible to rigorously test or scale. We realized that true performance and maintainability required isolating and perfecting the single hardest problem in large-scale computation: state management.

The solution was not to build another engine, but to perfect the most foundational architectural tool: the FSM_API. This C# core provides a mathematically provable, high-performance framework for all logic and state transitions, immediately shattering the bottlenecks that plagued our initial custom ECS efforts.

The Architectural Advantage: Modularity and Innovation

The pivot from a custom monolithic engine to an FSM-driven architecture built on Unity has unlocked several massive big-picture implications:

1. Accelerated Development via Unity

Instead of sinking years into rebuilding rendering, physics, and networking, we now leverage the highly optimized services of Unity. This dramatically accelerates our development timeline for the ultimate goal: MyVR.

2. The Free Core, Monetized Layer

Our business model for this new architecture is centered on providing value to the entire development community:

The foundational FSM_API is, and will remain, MIT-licensed and free (available via NuGet and GitHub).
We monetize specialized utility through the FSM_Layer—a library of up to 500 dedicated Unity micro-packages (e.g., Behavior Trees, advanced AI, Networking protocols, etc.). This ensures the core technology is accessible while specialized, high-value tools fund the continuous development of the MyVR universe.

3. AnyApp: The Composable Future

This modularity leads directly to AnyApp, our customizable host application. AnyApp is designed for runtime FSM recomposition, a groundbreaking innovation that allows users with permissions to enter an editor mode and dynamically modify or even mix genres within a live experience. Imagine adding RTS logic to an FPS, or building custom automation into a simulation—all live, without recompilation.

The FSM_API makes this possible, ensuring that even when genres are mixed, the underlying logic remains clear, performant, and robust.

Join the Mission: From API to Universe

Our path is now clear: from the FSM_API to the modular FSM_Layer, into the customizable AnyApp host, and finally into the scalable MyVR digital universe. This is a robust, cleaner, and ultimately faster route to realizing our full vision.

For a complete, in-depth technical breakdown of this strategic pivot, including our monetization plan, the status of our Unity Asset Store submissions, and the current technical challenge we are solving to guarantee full modularity, please read our latest Patreon post:

The Pivot: Reforging Our Path to MyVR with the FSM Architecture

Join The Singularity Workshop on Patreon today to support the development of this foundational architecture and secure your legacy in the future of the digital world.

UUID vs ULID vs Integer IDs: A Technical Guide for Modern Systems

Wed, 06 Aug 2025 20:37:38 +0000

Unique identifiers are the backbone of data management, distributed systems, and secure API design. While UUIDs (UUIDv4) and integer IDs are widely used, ULIDs (Universally Unique Lexicographically Sortable Identifiers) are emerging as a superior choice for modern applications. This article explores their technical differences, focusing on performance in .NET ecosystems and database-level implications.

This article was originally published on the ByteAether Blog. It has been republished here with minor edits for clarity and conciseness.

Identifier Types

Integer IDs

Sequential numeric values managed by databases via auto-increment. Pros: simple, efficient for indexing. Cons: predictable (security risks), centralized generation (not ideal for distributed systems).

UUIDs

128-bit identifiers using randomness (UUIDv4). Pros: globally unique. Cons: lack sortability, cause database fragmentation (random insertion disrupts B+ tree indexes).

ULIDs

128-bit identifiers with a 48-bit timestamp (millisecond precision) and 80 bits of randomness. Pros: lexicographically sortable, compact, URL-safe, chronological insertion (reduces fragmentation).

Performance in .NET Applications

ULID Generation

The ByteAether.Ulid library generates ULIDs with zero heap allocations, leveraging stack-based operations. Key feature: monotonicity (sequential generation within the same millisecond), ensuring logical order in databases.

UUID Limitations

Guid.NewGuid() in .NET is fast but lacks ordering, causing random insertions and fragmentation. ULIDs align with database indexing patterns, improving throughput.

Database Performance: Index Fragmentation

Databases use B+ trees to store records in fixed-size pages. Random identifiers (UUIDs) force page splits, increasing I/O overhead, memory pressure, and write amplification. ULIDs embed timestamps, enabling sequential insertion and minimizing splits.

Implementing ULIDs in .NET

Entity Framework Core

public class Order  
{  
    public Ulid Id { get; set; } // Stored as BINARY(16)  
    public string Product { get; set; }  
}  

public class UlidToBytesConverter : ValueConverter<Ulid, byte[]>  
{  
    public UlidToBytesConverter() : base(
        x => x.ToByteArray(), x => Ulid.New(x)
    ) { }  
}

Dapper

public class UlidTypeHandler : SqlMapper.TypeHandler<Ulid>  
{  
    public override void SetValue(IDbDataParameter parameter, Ulid value)
        => parameter.Value = value.ToByteArray();  
    public override Ulid Parse(object value)
        => Ulid.New((byte[])value);  
}

When to Use ULIDs

Distributed Systems: Decentralized generation.
Time-Series Data: Built-in timestamps simplify queries.
Batch Processing: Monotonicity preserves order.

Why ByteAether.Ulid?

Speed: Faster than other ULID implementations.
Efficiency: Zero heap allocations.
Integration: Works seamlessly with EF Core, Dapper, and JSON serializers.

Conclusion

ULIDs address the limitations of UUIDs and integers, offering sortability, reduced fragmentation, and scalability. For .NET developers, ByteAether.Ulid provides a future-proof solution.

Read the full guide: UUID vs ULID vs Integer IDs: A Technical Guide for Modern Systems

Install the library:

dotnet add package ByteAether.Ulid

By adopting ULIDs, you can achieve faster queries, lower infrastructure costs, and scalable architectures.

This article was originally published on the ByteAether Blog. It has been republished here with minor edits for clarity and conciseness.

ByteAether.Ulid v1.3.0: Enhanced ULID Generation Control and Security

Thu, 31 Jul 2025 12:26:12 +0000

Choosing the right identifier is a critical design decision in any software system, especially when working with distributed architectures. While GUIDs (Globally Unique Identifiers) provide uniqueness and integer IDs offer sortability, neither fully solves the dual challenge of ensuring universal uniqueness and lexicographical sortability simultaneously. This is where ULIDs (Universally Unique Lexicographically Sortable Identifiers) emerge as an increasingly valuable solution.

We're excited to announce the release of ByteAether.Ulid v1.3.0, a significant update to our high-performance .NET ULID implementation. This version focuses on dramatically improving flexibility and security for ULID generation, making it even more suitable for demanding, modern applications.

Granular Control with `GenerationOptions`

In previous versions, ByteAether.Ulid handled monotonic generation through simple boolean flags. With v1.3.0, we're introducing a more sophisticated and powerful approach: the new GenerationOptions configuration object. This object provides granular control over ULID generation through three key parameters: Monotonicity, InitialRandomSource, and IncrementRandomSource.

Understanding `Monotonicity` Options

The Monotonicity setting is crucial for balancing the predictability and uniqueness of your ULIDs. Beyond the straightforward NonMonotonic (fully random) and MonotonicIncrement (strict sequential progression), v1.3.0 introduces a vital security enhancement:

MonotonicRandom1Byte to MonotonicRandom4Byte: These options directly address a well-known concern from the ULID specification (e.g., issue #105) regarding predictable ULIDs within the same millisecond, which could potentially lead to enumeration attacks. By allowing a configurable random increment (ranging from 1-byte to 4-byte range) using the IncrementRandomSource, these options add a crucial layer of randomness. This makes it significantly harder to guess subsequent ULIDs, effectively mitigating enumeration attack vectors while fully preserving the essential lexicographical sortability.

Flexible Randomness with `IRandomProvider`

Both the InitialRandomSource and IncrementRandomSource properties are now defined as IRandomProvider types. This design choice offers unparalleled flexibility, enabling you to implement and supply your own custom random number generators.

CryptographicallySecureRandomProvider (Default for InitialRandomSource): This is the default for initial randomness, utilizing a cryptographically secure random number generator, ensuring high entropy for security-sensitive applications.
PseudoRandomProvider (Default for IncrementRandomSource): This option employs a faster pseudo-random algorithm, making it suitable for scenarios where cryptographic security for the increment value is not the primary concern and performance is prioritized.

Seamless Transition and Backward Compatibility

We've ensured that ByteAether.Ulid v1.3.0 provides a smooth upgrade experience while maintaining backward compatibility. The default settings for GenerationOptions are configured to precisely match the previous monotonic generation behavior:

Ulid.DefaultGenerationOptions = new Ulid.GenerationOptions
{
Monotonicity = MonotonicityOptions.MonotonicIncrement,
InitialRandomSource = new CryptographicallySecureRandomProvider(),
IncrementRandomSource = new PseudoRandomProvider()
}

For existing codebases, public API methods that used the bool? isMonotonic parameter and the Ulid.DefaultIsMonotonic static property are now marked [Obsolete]. We strongly encourage developers to migrate to the more powerful GenerationOptions-based methods to leverage the enhanced control and flexibility. These deprecated elements will be removed in a future version, so updating your code now will ensure future compatibility.

Why ULIDs for Modern Systems?

ULIDs effectively combine the best attributes for modern identifier needs:

Universally Unique: Guarantees global distinctness across diverse systems and environments.
Lexicographically Sortable: This is a game-changer for database performance, enabling efficient time-based sorting, optimized indexing, and rapid chronological data retrieval.
Human-Readable: Generally more manageable and readable compared to traditional GUIDs.

ByteAether.Ulid actively addresses potential issues found in the official ULID specification, such as the "random part overflow" (ULID specification issue #39), by intelligently allowing timestamp increments to ensure unique ULIDs even under extremely high generation rates. Furthermore, our extensive benchmarking against other popular .NET ULID implementations consistently positions ByteAether.Ulid as highly performant and fully compliant with the ULID specification, ensuring dependable generation for your applications.

Deep Dive into the Details

ByteAether.Ulid v1.3.0 represents a significant leap forward in providing secure, flexible, and high-performance identifier generation for the .NET ecosystem. To get all the technical details, including installation instructions, comprehensive usage examples, and its seamless integration with popular .NET libraries and frameworks (like ASP.NET Core, System.Text.Json, EF Core, Dapper, MessagePack, and Newtonsoft.Json), we encourage you to read the full article on our blog.

Read the full article for complete details and code examples!

Unifying Uniqueness and Order: Why ULIDs are the Future of Identifiers

Mon, 14 Jul 2025 11:43:27 +0000

Choosing the right identifier scheme is crucial in the sprawling landscape of software development. It impacts performance, scalability, and reliability, whether you're architecting a database, an API, or a distributed system. While auto-incrementing integers and UUIDs have long been the go-to choices, they each come with their own set of trade-offs. Enter ULIDs (Universally Unique Lexicographically Sortable Identifiers) – a modern alternative that masterfully blends the best of both worlds.

The Identifier Dilemma: Old vs. New

For decades, relational databases have relied on auto-incrementing integers for their simplicity, understandability, and excellent performance in single-node systems. They ensure predictable order, compact storage, and fast operations. However, this simplicity falters in distributed systems due to centralized coordination, scalability challenges, and the risk of collisions.

UUIDs, on the other hand, were designed for the distributed nature of modern systems. They guarantee global uniqueness without central coordination, offering distributed scalability and standardization across many programming languages. But their inherent randomness leads to index fragmentation, poor write performance, and human unreadability. Plus, their lack of temporal ordering complicates time-based queries.

ULIDs: The Best of Both Worlds

ULIDs were born to resolve these limitations by combining a 48-bit timestamp with an 80-bit random component. This innovative structure delivers:

Global Uniqueness: Just like UUIDs, ULIDs are unique across distributed systems.
Temporal Ordering: The timestamp component ensures ULIDs are lexicographically sortable, preserving the chronological order of creation.
Distributed Generation: ULIDs can be generated independently, eliminating the need for centralized coordination.
Human Readability: ULIDs utilize Crockford's Base32 encoding, which avoids ambiguous characters, making them much easier to read and debug.

The official ULID specification on GitHub provides comprehensive guidelines for implementation across various programming languages.

Enhancing Readability with Crockford's Base32 Encoding

A standout feature of ULIDs is their adoption of Crockford's Base32 encoding, specifically designed to boost human readability. This encoding scheme carefully sidesteps visually similar characters (like "I" and "1" or "O" and "0"), drastically reducing transcription errors. Furthermore, Base32-encoded ULIDs are case-insensitive, simplifying their handling in systems that don't preserve case. This thoughtful design bridges the gap between machine efficiency and human usability.

Monotonicity: Preserving Order in High-Throughput Systems

One of ULID's powerful features is its monotonicity, which ensures order even when multiple identifiers are generated within the same millisecond. In high-throughput scenarios, the monotonicity feature guarantees that if multiple ULIDs share the same timestamp, they are incremented to maintain their lexicographical order. This provides:

Consistency: Data remains ordered, even under high-concurrency scenarios.
Query Efficiency: Time-based range queries continue to perform well, regardless of the volume of data generated.
Reliable Sorting: Applications relying on ordered identifiers, such as event streams or analytics platforms, greatly benefit from this feature.

Where ULIDs Shine in Modern Applications

ULIDs are especially well-suited for applications demanding scalability, temporal ordering, and distributed generation. Consider these use cases:

Event Logging: Efficiently store and retrieve time-stamped log entries.
Distributed Databases: Eliminate the need for central coordination while preserving order.
Analytics and Reporting: Facilitate time-based filtering and aggregation of data.
High-Throughput Systems: Maintain performance and order even under heavy write loads.

Integrating ULIDs into Your Projects

A variety of libraries are available across programming languages to help you adopt ULIDs. For .NET developers, the ByteAether's Ulid GitHub repository offers a high-performance C# implementation.

By adhering to the official specification and leveraging well-maintained libraries, integrating ULIDs into your systems can be a seamless process, leading to maximum reliability.

Ready to Modernize Your Identifiers?

ULIDs offer a compelling, modern, and versatile solution to the persistent challenges of identifier generation in software systems. They successfully combine the strengths of auto-incrementing integers and UUIDs while deftly avoiding their weaknesses, providing globally unique, lexicographically sortable, and human-readable identifiers. With features like Crockford's Base32 encoding and monotonicity, ULIDs are perfectly tailored for the demands of today's applications, from distributed systems to time-based analytics.

Whether you're embarking on a new project or optimizing an existing one, ULIDs present a powerful option for identifier management. Their burgeoning ecosystem of libraries and robust community support position them to become a standard choice for developers prioritizing scalability, performance, and simplicity.

Want to dive deeper into the world of ULIDs and explore their practical applications? Read the full article on my blog: An Introduction to ULIDs: A Modern Identifier for Software Systems and discover more valuable insights at ByteAether Blog.

Start integrating ULIDs into your .NET applications today with ByteAether.Ulid. We're eager to hear your thoughts and see what you build!

Ditch Your GUID Frustrations: Introducing ByteAether.Ulid v1.0.0 for .NET!

Wed, 09 Jul 2025 15:09:55 +0000

Are you tired of dealing with GUIDs that are a pain to sort and even harder to read? If you're a .NET developer working with distributed systems or time-sensitive data, you know the struggle is real. While GUIDs offer uniqueness, they fall short when it comes to human readability and, crucially, sortability. That's where ULIDs come in, and we're thrilled to introduce ByteAether.Ulid, a high-performance .NET library designed to make your life a whole lot easier.

We've just launched ByteAether.Ulid, a library specifically crafted to generate and work with ULIDs (Universally Unique Lexicographically Sortable Identifiers). This isn't just another ID generator. It's a solution that brings together the best of uniqueness, readability, and sortability, all while delivering exceptional performance for your modern .NET applications.

Why ULIDs? And Why ByteAether.Ulid?

ULIDs are a game-changer because they offer the best of both worlds:

Globally Unique: You can generate ULIDs across different systems without worrying about collisions.
Sortable: Unlike GUIDs, ULIDs are lexicographically ordered, making them perfect for time-based data. Imagine how much simpler your database queries become!
Human-Readable: Forget those convoluted GUID strings. ULIDs use a base32 encoding that's much easier on the eyes.

While the ULID specification itself is fantastic, ByteAether.Ulid takes it a step further. We've built this library to be not just compliant with the ULID specification, but also robust. We've tackled common issues like random-part overflow, ensuring that your ULID generation is truly error-free and reliable.

Key Features That Make ByteAether.Ulid Stand Out

We've focused on delivering a library that's powerful, efficient, and easy to integrate:

Error-Free ULID Generation: We've implemented graceful handling for edge cases, such as random-part overflow. This means timestamps are incremented automatically to maintain monotonicity, preventing errors and ensuring smooth operation.
High-Performance Design: ByteAether.Ulid is engineered for speed and minimal memory footprint. We're proud to say it outperforms other popular ULID libraries in the .NET ecosystem.
Seamless .NET Integration: Whether you're on .NET Standard 2.0 or the latest .NET 9.0, ByteAether.Ulid has you covered. It includes native support for ASP.NET Core route parameters and is fully compatible with System.Text.Json for hassle-free serialization and deserialization.
Versatile Conversion Methods: Easily convert ULIDs to and from byte arrays, GUIDs, and strings, giving you the flexibility you need.

Getting Started is a Breeze!

Ready to ditch those GUID woes? Getting started with ByteAether.Ulid is incredibly simple. Just install the NuGet package:

dotnet add package ByteAether.Ulid

Once installed, generating and using ULIDs is straightforward:

using System;

class Program
{
    static void Main()
    {
        // Create a new ULID
        var ulid = Ulid.New();

        // Convert to string and back
        string ulidString = ulid.ToString();
        var ulidFromString = Ulid.Parse(ulidString);

        Console.WriteLine($"Generated ULID: {ulid}");
    }
}

For more detailed usage instructions and a complete API reference, be sure to check out our GitHub repository.

Performance You Can Rely On

We understand that performance is crucial for modern applications. ByteAether.Ulid is not only fully compliant with the ULID specification but also designed for speed. We've benchmarked it against other libraries, and ByteAether.Ulid consistently comes out on top in terms of generation speed, while offering graceful error handling. You can find a full breakdown of our benchmarks and testing methodology on our GitHub repository.

Open Source and Community-Driven

ByteAether.Ulid is an open-source project licensed under the MIT License. We believe in the power of community, and we welcome your contributions! Whether you have a bug to report, a feature to suggest, or want to submit a pull request, your input is valuable.

Submit an Issue

Contribute Code

What's Next for ByteAether?

We're just getting started! Stay tuned for more in-depth articles on our main blog, where we'll be exploring:

Why ULIDs are a game-changer for modern databases.
Optimizing performance in distributed systems with ULIDs.
Real-world use cases for ULIDs in .NET applications.

Ready to simplify your .NET projects and experience the difference ULIDs can make? Install ByteAether.Ulid today!

Want to dive deeper into the world of ULIDs and modern .NET development? This is just a snippet! Read the full article and explore more valuable content on my blog: https://byteaether.github.io/2025/announcing-byteaetherulid-v100-a-high-performance-net-ulid-library-for-modern-applications/

Visit my main blog for more insights and updates: https://byteaether.github.io/

Why Most .NET Developers Misuse Records — and What It’s Costing Them

Tue, 08 Jul 2025 07:24:07 +0000

Most .NET devs are misusing records—and it's costing them more than they think. Memory overhead. Identity tracking bugs. EF Core confusion.

I broke it all down in my latest Medium post: Why Most .NET Developers Misuse Records and What It’s Costing Them Read here

Inside:

Why value equality isn't always the win you expect

How EF Core gets tripped up by records

Benchmark graphs showing real clone costs in hot loops

When to ditch the with expression and reach for a constructor

This one's for every architect, lead dev, and performance-obsessed coder who wants to use records right.

️ Read it. Share it. Argue with it. Let’s rethink how we use C# records.

Coder Legion - Recent posts tagged csharp

A JSON-RPC Library With No Method Registration: How Does It Decide What Can Be Called?

1️⃣ What it covers

2️⃣ Getting started

ASP.NET Core server (Minimal API)

Client

3️⃣ With no registration, which methods can be called?

4️⃣ The client

5️⃣ Extension points: filters and interceptors

6️⃣ Encrypted payloads

7️⃣ How it differs from common libraries

8️⃣ Design trade-offs

✅ Wrapping up

Further reading

From Anemic Models to Rich Domain Models, DDD Base Entities, and C# Records

Part 1: The Anti-Pattern (Anemic Models & DTO Misuse)

The Problematic Approach

Why Anemic Models Fail

Part 2: DDD Foundation — Entity Base Class & C# Records

1. DDD Entity Base Class

2. C# Records for Value Objects

Part 3: Combining Interfaces, Abstract Classes, and DDD Entities

Part 4: The Rich Domain Model (Order)

Part 5: Orchestrating with SRP and Dependency Injection

Part 6: Persistence with EF Core (Mapping Records & TPH)

Part 7: Unit Testing with Records & Entities

References & Further Reading

Tuesday Coding Tip 28 — (de)serializing JSON string enum in C#

A Query Window Is Not a Calendar Day

Retrieval and meaning are different jobs

Define “today” in the relevant time zone

Preserve the exception that actually matters

Make wording part of correctness

Test the boundary as a sequence

The engineering trade-off

Practical checklist

Idempotency Should Resume Partial Work, Not Hide It

A checkpoint is not the whole journey

Reconciliation makes partial completion explicit

Ask the external system what its workflow means

Human intent outranks automation

Retry by failure class

Test the half-finished states

The practical rule

An Empty Field Is Still Signed Data

The tidy abstraction that hid a real difference

Empty and absent are different inputs

Share mechanics, not contracts

Test the representation, not your implementation

Exercise the framework pipeline too

Verification is necessary, not complete trust

A practical review checklist

Put the Concurrency Gate Before the Side Effect

Why read-then-check is not ownership

Move the decision forward

The claim is a state, not a boolean trick

A timeout is recovery policy, not exactly once

Test the overlap, not two sequential calls

A compact design checklist

Test the Owner, Not the Teardown

The shape of the failure

Waiting is not the same as proving

Put the assertion at the ownership boundary

Production code still needs lifecycle discipline

Keep two layers of evidence

A practical checklist

Soft Delete Is a Model Contract, Not a Repository Habit

The dangerous partial success

Test the effective predicate

A correct filter changes workflows

Watch required navigations

A practical verification stack

A Passing Test Can Still Prove Nothing

The false-positive shape

Test the claim, not the punctuation

Why mutation testing helped

The trade-off: path awareness without brittleness

A practical review habit

Tuesday Coding Tip 26 — JSON (de)serialization in C#

The Async Result Belongs to the Snapshot That Started It

Part 4: The Rich Domain Model (`Order`)