DEV Community: Giannis Georgopoulos

Logging Like a Pro in .NET

Giannis Georgopoulos — Thu, 15 May 2025 16:56:32 +0000

Logs are your primary tool for understanding what your API is doing in production.
Whether it's debugging a bug report, identifying performance issues, or reacting to an incident logs are your first and best signal.

But many developers fall into two extremes:

Too little logging, and you're blind in production.
Too much logging, and you're drowning in noise, cost, or leaked sensitive data.

In this post, we’ll take a smarter approach and cover:

Setting up Serilog for structured logging in .NET
Logging exceptions using source generators
Outputting request payloads as structured JSON
Masking sensitive data to stay compliant (GDPR, etc.)
Enriching logs with contextual information like OrderId

Let’s dive in.

Step 1: Adding serilog to your project

dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.Console

We’ll use the console sink for simplicity because it works out of the box, doesn’t require any extra setup, and still gives us structured log output in your terminal or Docker logs.

Once you're ready for production, you can plug in any of Serilog’s many available sinks, like Seq, Application Insights, etc.

Step 2: Configure Serilog in `Program.cs`

Here’s a simple Serilog setup that logs to the console:


Log.Logger = new LoggerConfiguration()
    .WriteTo
    .Console(outputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3}] [{EventId}:{EventName}] {Message:lj}{NewLine}{Exception}")
    .CreateLogger();

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSerilog();

var app = builder.Build();
// your app setup...
app.Run();

With just a few lines of setup, Serilog is now capturing structured logs to the console.

We will now launch our api and call the /api/v2/Order/{orderId}/shipping endpoint from [[production-ready-api-devex|Part 1]].

If we take a look at the console now we will see the HTTP request being logged.
By default, all incoming HTTP requests will be logged, including successful ones.

While this might seem helpful, it can quickly overwhelm your logs, especially when most requests succeed and add no diagnostic value. Even worse, platforms like Application Insights charge by the volume of logs ingested.

For detailed traces, I recommend using OpenTelemetry with sampling. Logs should be reserved for intentional diagnostics, not every HTTP 200.

To reduce noise, disable default HTTP logs:

.MinimumLevel.Override("Microsoft.AspNetCore.Hosting", LogEventLevel.Warning)
.MinimumLevel.Override("Microsoft.AspNetCore.Mvc", LogEventLevel.Warning)
.MinimumLevel.Override("Microsoft.AspNetCore.Routing", LogEventLevel.Warning)

You could also use appsettings.json for configuring serilog. Read more here

Step 3: Logging our first exception

So if we don't want to log our HTTP requests what do we want to log?

The first thing is exceptions. When something goes wrong in our system, we need visibility.

I’ll cover global exception handling in a later article to keep the scope small.

First, let’s simulate an exception in OrderService.cs:

public async Task SetShippingInfo(Guid id, SetShippingInfoRequest request)  
{  
    throw new Exception("Oops! Failed to set shipping info");  
}

Now update the controller to catch and log the error. Inject ILogger<OrderController> logger and wrap the call:


[ApiController]  
[Route("api/v{v:apiVersion}/[controller]")]  
public class OrderController(OrderService orderService, ILogger<OrderController> logger) : ControllerBase  
{  
....
    /// <summary>  
    /// Sets the shipping address for an order.    /// </summary>    /// <response code="400">    /// Returned when:    /// - 'ZipCode' is missing or invalid    /// - The order cannot be updated due to its current status    /// </response>    [MapToApiVersion("2")]  
    [HttpPatch("{orderId:guid}/shipping")]  
    public async Task<IActionResult> SetShippingInfo(Guid orderId, SetShippingInfoRequest request)  
    {
        try  
        {  
            await orderService.SetShippingInfo(orderId, request);  
        }  
        catch (Exception ex)  
        {  
            logger.LogError(ex, "Failed to set shipping info for request:{Request}", request);  
            return Problem(  
                detail: ex.StackTrace,  
                title: ex.Message);  
    }
        return NoContent();  
    }}

Step 4: Use Source-Generated Logging

The previous approach works but we can do better.

.NET provides high-performance source-generated logging, which avoids boxing, allocations, and improves log searchability via EventId and EventName.

Update the controller to use a static partial log method:

[LoggerMessage(
    EventId = 1,
    EventName = nameof(LogFailedSetShippingInfo),
    Level = LogLevel.Error,
    Message = "Failed to set shipping info for {Request}")]
static partial void LogFailedSetShippingInfo(ILogger logger, Exception exception, SetShippingInfoRequest request);

The event id and name we defined in the LoggerMessage attribute will be extremely useful later on, when we will want to search our logs and add rules for automated alerting.

Step 5: Controlling Log Output for Complex Objects

Let’s tweak our log message to include the actual request payload:

[LoggerMessage(EventId = 1, EventName = nameof(LogFailedSetShippingInfo), Level = LogLevel.Error, Message = "Failed to set shipping info for {@Request}")]
static partial void LogFailedSetShippingInfo(ILogger logger, Exception exception, SetShippingInfoRequest request);

The key difference here is the @ symbol in {@Request}. Without it, your logs will just say:

Failed to set shipping info for SetShippingInfoRequest

But with @, Serilog serializes the entire object as structured JSON and includes all public properties of SetShippingInfoRequest in your logs. This makes it much easier to understand what actually went wrong.

However, this technique comes with an important caveat.

When logging full objects, you risk unintentionally including sensitive data like full recipient names, emails, phone numbers, or tokens. This can quickly lead to GDPR violations or internal policy breaches, especially if logs are forwarded to external systems like Application Insights or Seq.

Step 6: Redacting Sensitive Data

To avoid leaking sensitive data, we’ll use the Serilog.Enrichers.Sensitive package, which allows you to redact specific properties automatically.

Install the package:

dotnet add package Serilog.Enrichers.Sensitive

Then, in your Program.cs, configure Serilog to redact sensitive properties:

Log.Logger = new LoggerConfiguration()  
    .MinimumLevel.Override("Microsoft.AspNetCore.Hosting", LogEventLevel.Warning)  
    .MinimumLevel.Override("Microsoft.AspNetCore.Mvc", LogEventLevel.Warning)  
    .MinimumLevel.Override("Microsoft.AspNetCore.Routing", LogEventLevel.Warning)  
    .Enrich.WithSensitiveDataMasking(options => 
    {  
        options.MaskProperties.Add("RecipientName");  
    })    .WriteTo  
    .Console(outputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3}] [{EventId}:{EventName}] {Message:lj}{NewLine}{Exception}")  
    .CreateLogger();

Now the RecipientName property will be automatically be masked in the logs, so running our example will give us this:

[22:09:28 ERR] [{ Id: 1, Name: "LogFailedSetShippingInfo" }:]
Failed to set shipping info for {"RecipientName": "***MASKED***", "Street": "123 Main St", "City": "New York", "State": "NY", "ZipCode": "10001", "Country": "USA"}
System.Exception: OOPS Failed to set shipping info
   at BloggingExamples.OrderService.SetShippingInfo(Guid id, SetShippingInfoRequest request) in /.../BloggingExamples/OrderService.cs:line 12
   at BloggingExamples.OrderController.SetShippingInfo(Guid orderId, SetShippingInfoRequest request) in /.../BloggingExamples/OrderController.cs:line 42

You can mask by property name, regex pattern, or type name. This makes it easy to comply with GDPR and protect your users.

Step 6: Add Contextual Properties Using `LogContext`

Sometimes you want to include additional information (like the current order ID, tenant ID, or user ID) in every log line within a given scope. You can do this using LogContext.

In the controller, push the orderId into the log context:

using Serilog.Context;

...

    [HttpPatch("{orderId:guid}/shipping")]
    public async Task<IActionResult> SetShippingInfo(Guid orderId, SetShippingInfoRequest request)
    {
        using var logContext = LogContext.PushProperty("orderId", orderId);
        try
        {
            await orderService.SetShippingInfo(orderId, request);
        }
        catch (Exception ex)
        {
            LogFailedSetShippingInfo(logger, ex, request);
            return Problem(
                detail: ex.StackTrace, // Don't return the stacktrace in production
                title: ex.Message);
        }

        return NoContent();

    }

Every log within that scope, including the one from LogFailedSetShippingInfo, will now automatically include the OrderId property in its structured output.

This is incredibly useful for filtering logs by entity, user, or request—without cluttering every log call manually.

We haven’t set up user or tenant context here, but in a real app, the most common pattern is to push those values into the log context from middleware.

With this setup, you’re no longer logging blindly, you’re logging with purpose, clarity, and safety.

If you enjoyed this post visit my blog for more.

A Professional Looking API

Giannis Georgopoulos — Thu, 15 May 2025 16:47:51 +0000

Your OpenAPI spec is the contract that defines how consumers interact with your API. It powers visual tools that help developers understand, test, and integrate with your endpoints.

This spec powers visual tools that help developers understand, test, and integrate with your API. While Swagger UI has been the go-to for years, modern alternatives like Scalar are raising the bar with cleaner UX, better search, and more intuitive navigation. For this post, we’ll be using Scalar to showcase how a well-designed OpenAPI spec gives your API a professional, developer-friendly front.

💡 Hint: Starting in .NET 9, there’s a built-in way to generate the OpenAPI spec using builder.Services.AddOpenApi(). However, as of now, it does not support XML comments, which are essential for rich and descriptive documentation. This makes it a no-go for production APIs that prioritize clarity. It is supported however in .NET 10 and you can see an example here.

In Part 1, we cleaned up a flawed UpdateOrder endpoint and replaced it with clear, task-based actions like SetShippingInfo. Now in Part 2, we’ll visualize the impact of those changes in our OpenAPI docs. You’ll see how thoughtful design decisions translate into:

Cleaner, more understandable docs
Easier client integration
Fewer support questions
And a stronger impression of your API as production-grade

Let’s make your OpenAPI spec do more than just validate — let’s make it teach, guide, and inspire confidence.

Visualizing the Difference: v1 vs v2

Let’s bring our changes to life by exposing two versions of the same endpoint:

Version 1 (v1) shows the original, flawed UpdateOrder design
Version 2 (v2) presents the refactored, task-based SetShippingInfo approach

This not only helps us compare the before/after in Swagger/Scalar — it also gives us a chance to introduce API versioning, a crucial concept for long-term maintainability.

Setting Up Versioning and Swagger

We’ll use URL-based versioning (/api/v1/..., /api/v2/...) since it’s the most straightforward to demonstrate in OpenAPI docs and widely supported by tools like Scalar.

First, install the necessary NuGet packages:

# API versioning for controllers
dotnet add package Asp.Versioning.Mvc 

# Adds support for exposing versioned API docs
dotnet add package Asp.Versioning.Mvc.ApiExplorer 

# Swagger/OpenAPI generation
dotnet add package Swashbuckle.AspNetCore

# Adds support for example responses in Swagger, we will use it to provide examples for `ProblemDetails` responses
dotnet add package Swashbuckle.AspNetCore.Filters

# Optional: Use Scalar instead of Swagger UI for a better experience
dotnet add package Scalar.AspNetCore

In your Program.cs:

using Asp.Versioning;  
using BloggingExamples;  
using Scalar.AspNetCore;  
using Swashbuckle.AspNetCore.Filters;  

var builder = WebApplication.CreateBuilder(args);  

builder.Services  
    .AddSwaggerGen()  
    .ConfigureOptions<ConfigureSwaggerOptions>();  

builder.Services.AddSwaggerExamplesFromAssemblyOf<NotFoundProblemDetailsExample>();  

builder.Services.AddApiVersioning(options => // adds api versioning and configures the strategy  
    {  
        options.DefaultApiVersion = new ApiVersion(1, 0);  
        options.ReportApiVersions = true;  
        options.ApiVersionReader = new UrlSegmentApiVersionReader();  
    })    .AddMvc() // add support for versioning controllers   
.AddApiExplorer(options =>  
    {  
        options.GroupNameFormat = "'v'VVV"; // e.g., v1  
        options.SubstituteApiVersionInUrl = true;  
    });  
builder.Services.AddControllers();  

var app = builder.Build();  

app.UseSwagger();  

app.MapControllers();  
app.MapScalarApiReference(x =>  
{  
        x.OpenApiRoutePattern = "/swagger/{documentName}/swagger.json";  
    x.AddDocument("v1");  
    x.AddDocument("v2");  
});  

await app.RunAsync();

In OrderController.cs:

[ApiVersion("1")]  
[ApiVersion("2")]  
[ApiController]  
[Route("api/v{v:apiVersion}/[controller]")]  
public class OrderController(OrderService orderService) : ControllerBase  
{  
    [MapToApiVersion("1")]  
    [HttpPost("updateOrder")]  
    public async Task<IActionResult> UpdateOrder([FromBody] OrderDto order)  
    {        var updatedOrder = await orderService.Update(order);  

        return Ok(updatedOrder);  
    }


    [MapToApiVersion("2")]  
    [HttpPatch("{orderId}/shipping")]  
    [ProducesResponseType(StatusCodes.Status204NoContent)]  
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]  
    [ProducesResponseType(StatusCodes.Status404NotFound)]  
    public async Task<IActionResult> SetShippingInfo(Guid orderId, SetShippingInfoRequest request)  
    {        await orderService.SetShippingInfo(orderId, request);  
        return NoContent();  
    }}

Now, if you launch your API and visit /swagger, you’ll see both v1 and v2 grouped cleanly — and instantly appreciate the differences:

Let's take a look at v1 first.

This is functional, but far from intuitive:

No example values provided, everything is nullable abd you’re left guessing how to structure your request
Errors like 400 Bad Request aren’t documented, leaving you blind to what might go wrong
No clear separation between request and response — just a generic 200 OK
It works, but it feels unpolished and leaves the developer with more questions than answers

Now lets take a look at v2 and compare them:

In v2 we can see:

Ready-to-run example values make it easy to try out the endpoint without guesswork
All possible status codes are clearly documented, along with explanations
A structured ProblemDetails schema shows exactly how errors are returned
Clear separation between request and response models
The UI communicates confidence — this feels like a production-grade API

Wrapping Up

Improving your OpenAPI spec isn’t just about aesthetics — it’s about creating a developer experience that feels reliable, guided, and easy to integrate with.

By versioning your API and refining your endpoints, you instantly elevate the quality of your documentation. It becomes easier to test, easier to onboard new consumers, and easier to maintain over time.

In this post, we saw how small changes — like switching from a vague UpdateOrder to a specific SetShippingInfo — dramatically improve how your API looks and feels in tools like Scalar.

If you enjoyed this article visit my blog for more.

Design Clean and Intuitive APIs

Giannis Georgopoulos — Sat, 10 May 2025 16:50:22 +0000

Let’s say you join a new team and find this in one of the core API controllers:

[HttpPost("updateOrder")]
public async Task<IActionResult> UpdateOrder([FromBody] OrderDto order)
{
    var updatedOrder = await _orderService.Update(order);

    return Ok(updatedOrder);
}

At first glance, it seems reasonable. It compiles. It works. It even passes QA.

But if this looks fine to you — keep reading.

This kind of code is deceptively simple. In fact, it’s a perfect example of how bad design doesn’t look broken, until it is. Under the surface, this endpoint is full of subtle flaws that will confuse consumers, pollute your Swagger docs, and slow your team down over time.

Let’s unpack what’s wrong, and more importantly, how to fix it.

What’s Wrong With This Endpoint?

Let’s break it down:

1. Misused HTTP Verb

You're updating an existing resource, not creating a new one. This should be a PUT or PATCH.

The verb might feel like a minor detail, but it shapes how clients understand and interact with your API. Misusing it breaks expectations and undermines REST semantics.

2. CRUD Smell: The “updateEverything” Trap

This is the biggest red flag. You're trying to model everything through CRUD. That seems simple at first, but it becomes unmaintainable fast.

Over time, you'll bolt on more logic:

Don’t allow canceling if already shipped.
Don’t allow address changes if invoiced.
Add this flag, but ignore it depending on status...

You’ve now got a monster method trying to cover every edge case.

Instead, shift toward task-based endpoints that represent real user intent:

SetShippingAddress
CancelOrder
MarkOrderAsPaid

Each task has clear rules, clear inputs, and a clear domain boundary.

Highly recommended: Decomposing CRUD to a Task Based UI by CodeOpinion.

It’s one of the best resources out there for understanding task-based API design and how to get out of the CRUD mindset.

3. IActionResult: Flexibility That Hurts

Returning IActionResult may seem convenient, but it leads to vague Swagger documentation. Clients won’t know what to expect.

Use ActionResult<T> to explicitly define your response types — it improves both clarity and tooling support.

4. Overloaded, Generic `OrderDto`

What is OrderDto? For whom is it meant? the database? The client? The update request?
If it’s used for both input and output, it’ll end up looking something like this, in order to accommodate all use cases and request/responses:


public record OrderDto  
{  
    public string? OrderId { get; init; }  

    public string? Status { get; init; }  

    public AddressInfoDto? AddressInfo { get; init; }  

    public OrderSummaryDto? OrderSummary { get; init; }  

    public OrderLine[] OrderLines { get; init; } = [];  

    public DateTime? CreatedAt { get; init; }  

    public DateTime? UpdatedAt { get; init; }  
}  

public record OrderLine  
{  
    public string? LineId { get; init; }  
    public int Quantity { get; init; }  
    public decimal Price { get; init; }  
}  

public record AddressInfoDto  
{  
    public string? RecipientName { get; set; }  


    public string? Street { get; set; }  


    public string? City { get; set; }  


    public string? State { get; set; }  


    public string? ZipCode { get; set; }  


    public string? Country { get; set; }  
}  

public record OrderSummaryDto  
{  
    public decimal? TotalAmount { get; init; }  

    public decimal? Vat { get; init; }  
}

Should the client send this? Ignore it? What about status, or totalAmount?

This leads to guessing, confusion, and coupling between internal models and external contracts.

Define separate models for:

Request payloads (e.g. SetShippingInfoRequest)
Responses (e.g. ShippingInfoResponse)

5. No Error Modeling

What happens if the update fails? Say the order is already shipped and can’t be changed?

Right now, you might return a plain 400 Bad Request — but that’s meaningless without context.

Clients will ask: “What did I do wrong?”

You must do two things:

Return a structured, predictable error response.
Document why a 400 might happen.

[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]

Here are some valid 400 scenarios you should document:

The address fields are missing or invalid (e.g. empty ZipCode).
The order has already been shipped and address changes are forbidden.
The order has been cancelled and is no longer editable.
The country specified is unsupported.
Business rules prevent shipping updates once payment is finalized.

This way, clients know what to expect and how to recover.

You can reflect this using the standard ValidationProblemDetails:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "ZipCode": ["Zip code is required."],
    "Order": ["Shipping information cannot be changed after shipment."]
  }
}

6. Swagger Docs Will Be Garbage

Without XML comments and meaningful examples, Swagger will generate things like:

{
  "address": "string"
}

That tells consumers nothing. Which fields are required? What does a valid address look like?

This is why we need:

XML comments
Swagger examples
Concrete request/response types

A Better Design: Task-Based `SetShippingInfo`

Let’s redesign this endpoint with all the above in mind.

SetShippingInfo Endpoint

/// <summary>  
/// Sets the shipping address for an order.  
/// </summary>  
/// <response code="400">  
/// Returned when:  
/// - 'ZipCode' is missing or invalid  
/// - The order cannot be updated due to its current status  
/// </response>  
[MapToApiVersion("2")]  
[HttpPatch("{orderId}/shipping")]  
[ProducesResponseType(StatusCodes.Status204NoContent)]  
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]  
[ProducesResponseType(StatusCodes.Status404NotFound)]  
[SwaggerResponseExample(StatusCodes.Status400BadRequest, typeof(ZipCodeExample))]  
[SwaggerResponseExample(StatusCodes.Status404NotFound,typeof(NotFoundProblemDetailsExample))]  
public async Task<IActionResult> SetShippingInfo(Guid orderId, SetShippingInfoRequest request)  
{  
    await orderService.SetShippingInfo(orderId, request);  
    return NoContent();  
}

SetShippingInfoRequest

/// <summary>
/// Represents the request to set shipping information for an order.
/// </summary>
public class SetShippingInfoRequest
{
    /// <example>John Smith</example>
    public string RecipientName { get; set; }

    /// <example>123 Main St</example>
    public string Street { get; set; }

    /// <example>New York</example>
    public string City { get; set; }

    /// <example>NY</example>
    public string State { get; set; }

    /// <example>10001</example>
    public string ZipCode { get; set; }

    /// <example>USA</example>
    public string Country { get; set; }
}

ShippingInfoResponse

/// <summary>
/// The response returned after successfully setting the shipping info.
/// </summary>
public class ShippingInfoResponse
{
    public Guid OrderId { get; set; }

    public string RecipientName { get; set; }

    public DateTime UpdatedAt { get; set; }

    // any other fields that could be needed for the response
    // ...

}

You might use this model if you want to immediately return the updated shipping information after the operation. This can be useful if the client needs confirmation of what’s now stored on the server.

But ask yourself: Is this really needed?

Since this is a PATCH, and the client likely already knows what it sent, returning the entire updated model may be wasteful, especially if the response adds no new value.

In many cases, a better choice is to return 204 No Content, which tells the client:

The operation succeeded
There’s nothing more to say

If you choose that route, the controller action can be simplified:

[HttpPatch("orders/{orderId}/shipping")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(typeof(ValidationErrorResponse), StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> SetShippingInfo(
    [FromRoute] Guid orderId,
    [FromBody] SetShippingInfoRequest request)
{
    await _orderService.SetShippingInfo(orderId, request);

    return NoContent();
}

Final Takeaways

Just because an API “works” doesn’t mean it’s well-designed.
CRUD endpoints invite technical debt; use task-based designs to model intent.
Use precise verbs, structured models, and document your failure scenarios.
Swagger is not just for machines; make it a first-class developer experience.
Know when to return a rich response, and when to just say 204.

If you enjoyed this article visit my blog for more

Safe Refactoring in .NET with Light/Dark Mode and Feature Flags

Giannis Georgopoulos — Tue, 06 May 2025 16:16:27 +0000

You’ve been forced to maintain a poorly written legacy app. Spaghetti code, no tests, and every new feature breaks two existing ones.

Team morale is at rock bottom. New features take forever to ship. Regression bugs are constant.

You gather your arguments and head to management.

You: We need time to refactor.

Management: What are you talking about?

You: Let us refactor. We’ll ship faster, with fewer bugs, and engineers won’t want to quit. I can do it.

Management: ...Okay.

Now comes the hard part.

Are you going to deliver on your promises? Or end up behind schedule and still stuck with a spaghetti codebase?

While large-scale refactoring depends on many factors like team alignment, technical constraints, and timing; there’s one powerful technique I’ve used successfully in production to de-risk the process: Light/Dark Mode refactoring.

I first learned this technique in the book Refactoring at Scale, and I’ve since applied it many times in real systems to refactor code safely and confidently.

In this post, I’ll show you how to implement it in .NET using feature flags, and how it can help you refactor without fear.

What Is Light/Dark Mode Refactoring?

Light/Dark Mode is a technique that lets you safely refactor code by running both the existing implementation ("light") and the new refactored implementation ("dark") side by side without exposing users to any risk.

You run the light implementation as usual, return its result to the user, but also execute the dark version in the background and compare the two outputs. If they match, you know your refactor is likely safe. If they don’t, you’ve caught a mismatch before it hits production.

This lets you:

Ship the refactor behind a feature flag
Gain confidence in correctness by comparing real-world results
Gradually roll out the new implementation without surprises

Eventually, when you're confident, you flip a flag and start returning the dark version to users.

It’s a low-risk, high-safety way to refactor logic, especially queries, where the same inputs should lead to the same outputs.

In the next section, I’ll show you how we applied this technique in a .NET application.

Let’s take an example of a service that performs a moderately complex operation like calculating the final price of a product, taking into account discounts, tax rules, currency rounding, and maybe even user-specific pricing logic.

Here’s how the legacy version might look:

public async Task<decimal> CalculateFinalPrice(Guid productId, Guid userId)
{
    var product = await _productRepo.GetById(productId);
    var basePrice = product.BasePrice;

    if (_userService.IsSpecialUser(userId))
    {
        basePrice *= 0.85m;
    }

    // Loyalty tier discount logic
    var user = await _userRepo.GetById(userId);
    var discount = 0m;

    if (user.LoyaltyTier == "Gold")
    {
        discount = basePrice * 0.10m;
    }
    else if (user.LoyaltyTier == "Silver")
    {
        discount = basePrice * 0.05m;
    }

    // Regional tax policy (duplicated logic scattered in multiple places)
    decimal tax = 0m;
    if (user.Region == "EU")
    {
        tax = (basePrice - discount) * 0.20m;
    }
    else if (user.Region == "US")
    {
        tax = 5.00m; // flat tax for some reason
    }

    // Random price adjustment based on product tags
    if (product.Tags.Contains("Clearance"))
    {
        discount += 3.00m;
    }

    // Last-minute adjustment for legacy reasons
    if (product.IsSubscription && user.Region == "EU")
    {
        tax *= 0.90m;
    }

    var finalPrice = basePrice - discount + tax;

    // Round to two decimals in a questionable way
    return Math.Round(finalPrice, 2, MidpointRounding.ToEven);
}

This is the kind of logic that:

Spreads business rules across services and layers
Has inconsistent handling (some percentage-based, some fixed)
Includes hardcoded exceptions and tribal knowledge
Is hard to test and reason about

And it is not mildly as complex as to what can be found in legacy apps.

Now imagine you want to replace this with a cleaner, rules-driven PricingEngine that encapsulates all this behavior in a composable, maintainable way.

You can’t afford to flip the switch and hope it works.

That’s where ExecuteLightDark comes in. Let’s see how to use it.

The `ExecuteLightDark` Helper

Let’s start with the core idea: run both the legacy and the refactored implementations, compare their results, and return the trusted one.

Here’s the simplest version of ExecuteLightDark:

public async Task<T> ExecuteLightDark<T>(
    Func<Task<T>> light,
    Func<Task<T>> dark,
    [CallerMemberName] string callingFunc = "")
{
    var lightResult = await light();
    var darkResult = lightResult; // default in case dark fails

    try
    {
        darkResult = await dark();

        var lightSerialized = JsonConvert.SerializeObject(lightResult);
        var darkSerialized = JsonConvert.SerializeObject(darkResult);

        if (lightSerialized == darkSerialized)
        {
            logger.LogInformation("Light/dark results match for {func}", callingFunc);
        }
        else
        {
            logger.LogError("Mismatch in light/dark results \nLight: {light}\nDark: {dark}", lightSerialized, darkSerialized);
        }
    }
    catch (Exception ex)
    {
        logger.LogError(ex, "Dark execution failed");
    }

    return lightResult;
}

That’s a solid start for internal testing environments but it’s not good enough for production.

In production, we need more control.

What we really want is to first release the refactor in observation mode: we return the light result and only log the comparison. Then, without redeploying the app, we want the ability to:

Enable Light/Dark execution dynamically for a subset of users whether that’s a percentage, a specific user group, or internal beta testers.
Gradually ramp up the dark execution as we build confidence, while still falling back to the light result.
Control performance impact by only executing the dark logic some percentage of the time (since running both can be expensive or slow).

To accomplish all of this, we need to bring in feature flags—specifically, something like Azure App Configuration with Feature Management if you’re on Azure.

Let’s look at how we extended our ExecuteLightDark method to support those production-grade capabilities.

Making It Production-Ready with Feature Flags

To use Light/Dark Mode safely in production, we wrapped it with feature flags. This lets us:

Turn Light/Dark Mode on or off without redeploying
Decide whether to return the light or dark result
Only run the dark logic some percentage of the time (to reduce performance impact)

Here’s our final ExecuteLightDark implementation:

public async Task<T> ExecuteLightDark<T>(
    Func<Task<T>> light,
    Func<Task<T>> dark,
    [CallerMemberName] string callingFunc = "")
{
    // Check if we should run both implementations
    var shouldRunDark = await featureManager.IsEnabledAsync(FeatureFlags.UseLightDarkMode);

    Task<T> lightTask = light();
    Task<T>? darkTask = null;

    if (shouldRunDark)
    {
        darkTask = dark();
        logger.LogInformation("Running light/dark comparison for {func}", callingFunc);
    }

    T lightResult = await lightTask;

    if (darkTask == null)
    {
        return lightResult;
    }

    T darkResult = lightResult;

    try
    {
        darkResult = await darkTask;

        var lightSerialized = JsonConvert.SerializeObject(lightResult);
        var darkSerialized = JsonConvert.SerializeObject(darkResult);

        if (lightSerialized == darkSerialized)
        {
            logger.LogInformation("Results match for {func}", callingFunc);
        }
        else
        {
            logger.LogError("Mismatch in light/dark results for {func}\nLight: {light}\nDark: {dark}",
                callingFunc, lightSerialized, darkSerialized);
        }
    }
    catch (Exception ex)
    {
        logger.LogError(ex, "Dark execution failed for {func}", callingFunc);
    }

    var returnDark = await featureManager.IsEnabledAsync(FeatureFlags.ReturnDarkResult);
    return returnDark ? darkResult : lightResult;
}

This version offloads all the logic like sampling, targeting, gradual rollout to your feature management system, which can be configured to:

Target internal users, specific companies, or beta testers
Enable for X% of users
Use filters like country, environment, user ID, etc.

Final Result: Your `PricingService` After Refactoring

With ExecuteLightDark in place, here’s what your PricingService might look like after adopting the pattern:

public class PricingService(
    IProductRepository productRepo,
    IDiscountService discountService,
    ITaxCalculator taxCalculator,
    IPricingEngine newPricingEngine,
    ILogger<PricingService> logger,
    IFeatureManager featureManager)
{
    public Task<decimal> CalculateFinalPrice(Guid productId, Guid userId)
    {
        return ExecuteLightDark(
            () => CalculateOldPrice(productId, userId),
            () => CalculateNewPrice(productId, userId));
    }

    private async Task<decimal> CalculateOldPrice(Guid productId, Guid userId)
    {
        var product = await productRepo.GetById(productId);
        var basePrice = product.BasePrice;

        if (userId == Guid.Parse("4b2f58d0-a738-4f96-b9a3-f3f4f0c9515d"))
            basePrice *= 0.85m;

        var user = await discountService.GetUser(userId);
        var discount = user.LoyaltyTier switch
        {
            "Gold" => basePrice * 0.10m,
            "Silver" => basePrice * 0.05m,
            _ => 0m
        };

        if (product.Tags.Contains("Clearance"))
            discount += 3.00m;

        var tax = user.Region switch
        {
            "EU" => (basePrice - discount) * 0.20m,
            "US" => 5.00m,
            _ => 0m
        };

        if (product.IsSubscription && user.Region == "EU")
            tax *= 0.90m;

        return Math.Round(basePrice - discount + tax, 2, MidpointRounding.ToEven);
    }

    private async Task<decimal> CalculateNewPrice(Guid productId, Guid userId)
    {
        var context = new PricingContext(productId, userId);
        return await newPricingEngine.CalculateFinalPrice(context);
    }
}

Benefits and Caveats

Like any tool, Light/Dark Mode refactoring comes with trade-offs. But in the right context it’s incredibly powerful.

Benefits

Confidence through real data
You’re testing the new logic against real production inputs, not just unit tests or pre-seeded environments.
Zero-risk rollouts
You can ship and monitor the refactor without ever returning the dark result until you’re ready.
Gradual, flexible rollout
Feature flags let you enable dark execution for internal users, specific companies, or small percentages of traffic.
Easy reversion
If something goes wrong, just toggle the flag off, no rollback or hotfix needed.

Caveats
Performance cost
You’re potentially doubling the work by running two implementations. This is especially relevant if queries are heavy or slow.
Comparison accuracy
Serializing and comparing objects can fail due to field order, time precision, or non-deterministic values. Consider using custom comparers or domain-specific checks if needed.
Log noise
If your dark implementation is still evolving, early mismatches may flood your logs. You may want to filter, throttle, or alert only on critical deltas.
Not great for writes
This pattern doesn’t apply cleanly to commands or state changes, where running two implementations could mutate data differently.

TL;DR

Use Light/Dark Mode for complex refactors of query logic, especially when the stakes are high and confidence is low. It gives you a way to ship change safely, with real-time validation and full control over risk.

This post was originally posted at my blog, visit for more technical posts around .NET.

Level Up Your Integration Tests in .NET: Record, Replay, Relax

Giannis Georgopoulos — Mon, 05 May 2025 07:04:41 +0000

Sick of flaky integration tests?

You run your tests once — they pass. Run them again — they fail. Maybe the third-party API timed out. Or the response changed. Or your internet blinked. Integration tests should give you confidence, not stress.

That’s where deterministic integration testing comes in. Imagine recording your API interactions once and replaying them forever. Offline, fast, and predictable.

No network. No surprises.

That’s exactly what Vcr.HttpRecorder does.

It’s inspired by the original Ruby VCR gem, revived for .NET and brought back to life with new features and bug fixes in my fork.

What Is Deterministic Integration Testing?

In traditional integration tests, you call real services. Maybe a payment gateway, an external API, or even another microservice. But real services are unpredictable:

They might be slow or down.
Their responses might change.
They could rate-limit you.

This makes your tests flaky and slow. Worse, you can’t run them offline, and reproducing issues becomes a headache.

Deterministic integration testing solves this by recording the HTTP interactions during a real test run, just once, and saving them. On subsequent runs, instead of hitting the real service, it replays the recorded response. This means:

Your tests always get the same response.
They run faster.
You can run them offline.
They’re finally reliable.

Think of it like:

One real run to record

All future runs are just playback

This gives you the confidence of integration testing with much more speed and reliability, though not quite as fast as unit tests, it’s a massive improvement.

Why Not Just Use WireMock?

If you've done any HTTP-based integration testing in .NET, you've probably run into tools like:

WireMock.Net
MockHttpMessageHandler
TestServers and custom in-memory APIs

They’re powerful but often overkill. You have to:

Define expected requests manually
Mock responses yourself
Keep your mocks in sync with reality

It's easy to end up testing your mocks instead of the real integration.

Vcr.HttpRecorder flips this around.

You run the test once, and it records the actual request and response.
No need to handcraft mocks or fake responses.
Next runs just replay that real interaction. Safely and deterministically.

You can plug it into a specific HttpClient with a simple handler — or skip the plumbing entirely and have it automatically intercept all HTTP clients in your test environment.

Getting Started (The Easy Way)

The easiest way to use Vcr.HttpRecorder is to wrap your test in a recording context and let it automatically intercept all HTTP clients in your test environment. No manual plumbing, no special HttpClient setup.

using var context = new HttpRecorderContext((_, _) => new HttpRecorderConfiguration
{
    Mode = HttpRecorderMode.Auto, // Automatically records or replays
});

var client = webAppFactory.WithWebHostBuilder(builder =>
{
    builder.ConfigureTestServices(services =>
    {
        services.AddHttpRecorderContextSupport();
    });
}).CreateClient();

That’s it:

On the first run, it records real HTTP interactions into cassette files.
On subsequent runs, it replays them. Fast and offline.

Cassette files(.har) are stored next to your tests by default and can be versioned with your repo. Want to update them? Just delete and re-record.

Prefer to wire it up manually? You can still use HttpRecorderHandler directly with specific clients, but most of the time, the automatic context is all you need.

What’s New in My Fork

The original Vcr.HttpRecorder was a solid idea, but it hadn’t been maintained and i got no responses from maintainers. I forked it to fix bugs, modernize it, and make it practical for real-world integration testing.

Here’s what I’ve added so far:

Concurrent context support

You can now run tests in parallel using HttpRecorderConcurrentContext, and each test will get its own isolated recording scope.

.NET 6/7/8 compatibility

Fixed support for newer .NET APIs like HttpClient.PostAsJsonAsync, GetFromJsonAsync, and others that were previously breaking the recorder.

Support for non-UTF8 responses

The original version assumed all responses were UTF-8, which caused crashes for binary or other encoded payloads. That’s now fixed.

Coming Soon

**Cassette diffing* to understand what changed between recordings
Optional assertions on captured requests/responses

I’m building this based on actual needs from real-world projects. If you’ve got an idea or run into an edge case, open an issue or let’s talk!

Check out the repo

Give it a star if it helped !

This post was originally posted at my blog, visit for more technical posts around .NET.

Building "Production-Grade" APIs in .NET

Giannis Georgopoulos — Sun, 04 May 2025 10:49:26 +0000

Many engineers build and deploy APIs into production.

So we have an API running in production. Does that mean it’s truly production-grade?

More often than not, the answer is no.

We write the code, test it locally (usually alone, on one machine, with one user), and proudly tell the business, "Hey, it’s ready!"

Maybe there’s even a QA environment where someone from product gives it a quick click-through and confirms, "Looks good to me!"

And then... reality checks in.

You get a call on the weekend:

“Users can’t log in.”

Or worse:

“A customer placed an order, and it’s gone.”

Now you're scrambling, thinking:

“I wish I’d added logs there.”

“Why didn’t we catch this earlier?”

“How are we supposed to debug this in production?”

If that scenario feels familiar, this post is for you.

Let’s walk through what I consider the minimum bar for an API to be truly production-grade, and how to build one in .NET.

What Qualifies as “Production-Grade”?

Most APIs “work” during development. But production-grade APIs are designed to behave predictably under pressure; when traffic spikes, something fails, or a customer is relying on your system to do its job.

For me, production-grade doesn’t mean “it passes QA”, it means the system is built in a way that makes life easier for engineers and consumers alike.

It means:

The API is intuitive to use. Consumers don’t have to ask how it works. They don’t open tickets asking why they got a 500. It’s predictable, self-documenting, and consistent.
It’s observable. You can tell what the system is doing, when it fails, and why. You find out something’s wrong before your customers do; no surprise calls at 10 PM.
It’s resilient. Every API that handles load will eventually fail; so you build in circuit breakers, retries, and rate limits before you need them.
It’s secure by default. If your API is public, someone will try to break it. Don’t assume good will from your users. Protect your business. Especially in B2B software where one leak or exploit can damage your reputation permanently.
It’s safe for your users. No user data in logs. No stack traces exposed. If you break that trust, users will hate you, and you may land in legal trouble, too.
It’s automated and testable. You don’t publish from your machine. Deployment should be a repeatable, automated pipeline with proper testing. Even if your business doesn’t release multiple times per day (like in medical or aerospace), you still benefit from CI/CD; because you always have a shippable, tested build and fast feedback loops.

A "Production-Ready" Framework to Follow

This mindset can be distilled into five key areas. Not as a checklist, but as a framework for designing APIs that last beyond dev and QA.

That’s why I break it down into five core areas. A framework I use every time I design an API I expect to survive real-world use.

1. Developer Experience & Documentation

Even the most reliable API will fail if it’s confusing to consume. Clean routes, consistent behavior, meaningful errors, versioning, and good documentation are essential.

2. Observability & Diagnostics

Structured logging, traces, metrics, and health checks let you understand what’s happening in production, and debug issues when they inevitably arise.

3. Resilience & Stability

Your API must handle real-world failures: retries, circuit breakers, timeouts, fallback strategies, and rate limiting help it stay functional under stress.

4.Security & Safety

Authentication, authorization, input validation, exception handling, and proper error reporting. All critical to protect user data and prevent abuse.

5. Deployment & Automation

CI/CD pipelines, infrastructure as code, testing pyramid, smoke and load testing, and safe deployment practices (e.g., blue/green, canary). These ensure your API can be updated often without fear.

This post is part of my blog series: Building Production-Grade APIs in .NET.