Berk Selvi | Software Developer

From IEnumerable to IAsyncEnumerable: Streaming Large Datasets in .NET Without Killing Memory

Sun, 02 Aug 2026 00:00:00 +0300

A few months ago, one of our nightly export jobs started throwing OutOfMemoryException. Nothing in the code had changed. What had changed was the size of the table it was reading from—it had quietly grown from 200K rows to 4 million. The job was doing exactly what we told it to do: .ToListAsync() the whole thing, then loop over it. It just took the whole database table into RAM first, and RAM lost.

This is a trap almost every .NET developer falls into at some point: reaching for IEnumerable<T> (or its async cousin Task<List<T>>) when what you actually need is IAsyncEnumerable<T> streaming large datasets record by record. IEnumerable<T> and IAsyncEnumerable<T> look similar on the surface, but they solve very different problems, and picking the wrong one is exactly how you end up paging through a 4-million-row table in memory at 2am.

IEnumerable vs IAsyncEnumerable at a Glance

Aspect	`IEnumerable<T>` / `List<T>`	`IAsyncEnumerable<T>`
Materialization	Fully realized before iteration starts	Pulled one item at a time, on demand
Memory footprint	Grows with result set size	Roughly constant, regardless of size
Time to first item	Waits for the entire query/collection	First item available as soon as it’s ready
Cancellation	Only stops your loop; work already done stays done	Can stop the underlying query mid-stream
Iteration	Repeatable, indexable	Forward-only, single-pass
Typical use	Small, bounded collections	Exports, ETL, paginated APIs, log processing

The Old Way: Load Everything, Then Iterate

Here’s the pattern that got us into trouble. A typical .NET service reading orders to export them:


public async Task<List<Order>> GetAllOrdersAsync()
{
 return await _dbContext.Orders
 .AsNoTracking()
 .ToListAsync();
}

public async Task ExportOrdersAsync()
{
 var orders = await GetAllOrdersAsync();

 foreach (var order in orders)
 {
 await _exportWriter.WriteLineAsync(order.ToCsvRow());
 }
}

This looks perfectly reasonable, and for small tables it is. But look closely at what ToListAsync() actually does: it materializes every single row returned by the query into a List<Order> sitting in memory before your code ever touches the first item. If the query returns 4 million rows, you need enough memory to hold 4 million Order objects simultaneously, even though you only ever process one row at a time in the foreach loop.

The symptoms creep up slowly:

Memory spikes: GC pressure increases, the process’s working set balloons, and container memory limits get hit in Kubernetes.
Latency before the first result: The caller waits for the entire query to complete before seeing a single row, even if all they wanted was to stream results to a client.
Wasted work on cancellation: If the caller aborts halfway through, you’ve already paid the full cost of loading everything.
No backpressure: There’s no way to say “slow down, I’m still processing the last batch”—the database just keeps producing rows as fast as the driver can buffer them.

For a background job doing an export, an API endpoint streaming a CSV, or a data migration script, this pattern doesn’t scale. It works in local development with your 50-row seed dataset, and quietly breaks in production.

Why IAsyncEnumerable?

.NET Core 3.0 introduced IAsyncEnumerable<T>, paired with the await foreach syntax, specifically to solve this class of problem. Instead of a method returning a fully realized collection, it returns a sequence that is pulled one item at a time, asynchronously, as the consumer asks for the next element.

The mental model shift is important:

Task<List<T>> means “wait for everything to be ready, then give me the whole thing.”
IAsyncEnumerable<T> means “give me an item whenever I ask for the next one, and let me await if it’s not ready yet.”

This unlocks:

Constant memory usage: Only one item (or a small buffer) needs to be in memory at any given time, regardless of whether the source has 10 rows or 10 million.
Time-to-first-byte improvements: A consumer can start processing (or an HTTP client can start receiving) data as soon as the first row is available, instead of waiting for the full result set.
Natural cancellation support: IAsyncEnumerable<T> composes with CancellationToken via WithCancellation, so aborting a stream actually stops the underlying query instead of just discarding an already-loaded list.
Composability with LINQ: With the System.Linq.Async package, you get Select, Where, and friends over async streams, so you don’t lose the expressiveness you’re used to with IEnumerable<T>.

The trade-off is that you give up random access and the ability to know the count upfront without a separate query—IAsyncEnumerable<T> is forward-only, single-pass, by design. For streaming scenarios, that’s exactly the right constraint.

Producing an IAsyncEnumerable with yield return

The simplest way to produce an IAsyncEnumerable<T> is with yield return inside an async method. Here’s a hand-rolled example that streams numbers with a simulated I/O delay, useful for understanding the mechanics before we bring EF Core into the picture:


public async IAsyncEnumerable<int> GenerateNumbersAsync(
 int count,
 [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
 for (int i = 0; i < count; i++)
 {
 cancellationToken.ThrowIfCancellationRequested();

 // Simulate an async I/O operation, e.g. a network call per item
 await Task.Delay(10, cancellationToken);

 yield return i;
 }
}

The [EnumeratorCancellation] attribute is easy to miss but important: without it, a CancellationToken passed to WithCancellation won’t actually flow into the method body, and ThrowIfCancellationRequested becomes a no-op against the caller’s token.

Consuming it looks like this:


await foreach (var number in GenerateNumbersAsync(1000, cts.Token))
{
 Console.WriteLine(number);
}

Notice what’s not happening here: there’s no intermediate List<int> holding all 1000 numbers. Each number is produced, consumed, and can be garbage collected before the next one is even generated.

Real-life Example: Streaming EF Core Query Results

Let’s go back to the export job that paged 4 million Order rows into memory at 2am and fix it properly. Entity Framework Core exposes IAsyncEnumerable<T> directly on DbSet<T> and IQueryable<T> via AsAsyncEnumerable(), so you don’t need to write your own yield return wrapper for database queries:


public IAsyncEnumerable<Order> StreamOrdersAsync(CancellationToken cancellationToken)
{
 return _dbContext.Orders
 .AsNoTracking()
 .OrderBy(o => o.Id)
 .AsAsyncEnumerable();
}

public async Task ExportOrdersAsync(CancellationToken cancellationToken)
{
 await foreach (var order in StreamOrdersAsync(cancellationToken).WithCancellation(cancellationToken))
 {
 await _exportWriter.WriteLineAsync(order.ToCsvRow());
 }
}

The difference is subtle in the code but massive at runtime. Instead of the query executing fully and buffering 4 million Order rows into a List<Order>, EF Core keeps the underlying DbDataReader open and streams rows from the database connection as the await foreach loop asks for them. Memory usage for the query itself stays roughly flat regardless of table size—you’re paying for one row (plus a small internal buffer) at a time, not the whole result set.

Two details matter here that are easy to miss. First, .AsNoTracking() isn’t decorative—without it, EF Core’s change tracker keeps a snapshot of every entity it hands you for the lifetime of the DbContext, which quietly reintroduces the exact memory growth you’re trying to eliminate, even though the query itself is streaming. Second, unlike the hand-rolled yield return example above, AsAsyncEnumerable() doesn’t require you to add [EnumeratorCancellation] anywhere in your own code—EF Core wires the CancellationToken you pass to WithCancellation into its own query pipeline internally. The attribute only matters when you’re writing the async IAsyncEnumerable<T> method yourself.

This also composes cleanly with ASP.NET Core. If you expose this as a minimal API endpoint, the framework will serialize the stream directly to the response body as items become available, instead of buffering the whole JSON array server-side first:


app.MapGet("/orders/stream", (AppDbContext dbContext, CancellationToken cancellationToken) =>
{
 return dbContext.Orders
 .AsNoTracking()
 .OrderBy(o => o.Id)
 .AsAsyncEnumerable();
});

Since .NET 6, ASP.NET Core’s minimal APIs detect the IAsyncEnumerable<T> return type and stream the JSON array chunk by chunk as the underlying enumerable produces items, rather than requiring you to materialize the full list before returning it. One gotcha worth knowing: if response compression middleware sits in front of the endpoint, it can end up buffering the response internally to compress it effectively, quietly defeating the streaming behavior you just wired up—worth checking with a real client and Transfer-Encoding: chunked before assuming it’s working end to end.

A Note on Batching

Streaming one row at a time from EF Core is memory-friendly, but if you’re writing each row to an external system (an HTTP call, a message queue, a second database), doing that per-row can be slow due to per-item overhead. A common middle ground is to batch the stream into chunks:


public static async IAsyncEnumerable<List<T>> ChunkAsync<T>(
 this IAsyncEnumerable<T> source,
 int chunkSize,
 [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
 var buffer = new List<T>(chunkSize);

 await foreach (var item in source.WithCancellation(cancellationToken))
 {
 buffer.Add(item);

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

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

Used like this:


await foreach (var batch in StreamOrdersAsync(cancellationToken).ChunkAsync(500, cancellationToken))
{
 await _messageBus.PublishBatchAsync(batch);
}

You still keep memory bounded—only 500 orders in flight at a time instead of 4 million—while amortizing the per-call overhead of the downstream system across a batch.

When IAsyncEnumerable Isn’t the Right Tool

IAsyncEnumerable<T> isn’t a universal replacement for List<T> or IEnumerable<T>. It’s the wrong choice when:

You need the count, need to sort after loading, or need random access (e.g., orders[42])—those require materializing the data anyway.
The dataset is genuinely small and bounded (a dropdown list of 20 categories doesn’t need streaming semantics).
You need to iterate the same sequence multiple times—IAsyncEnumerable<T> is single-pass by convention; re-enumerating typically re-runs the underlying query.
You’re doing in-memory transformations that need the whole collection anyway (e.g., computing a median), in which case streaming just adds await overhead without reducing memory.

Use it specifically when the shape of the problem is “process a potentially large sequence, one item (or small batch) at a time, without needing to hold it all at once.” Exports, ETL pipelines, paginated API results, log processing, and large report generation are the classic cases.

Summary

The OutOfMemoryException that started this whole investigation for us wasn’t a bug in the traditional sense—the code was doing exactly what ToListAsync() promises to do. The real fix wasn’t a smarter allocation strategy or a bigger container memory limit; it was recognizing that the job never needed a List<Order> sitting in memory in the first place. It needed a stream. Once we swapped ToListAsync() for AsAsyncEnumerable() on that export job, the same 4-million-row table processed with flat, predictable memory usage, and the OutOfMemoryException never came back.

Streaming large datasets with IAsyncEnumerable<T> won’t make every query faster, and it does add complexity—cancellation tokens, [EnumeratorCancellation], and the loss of random access and repeatable iteration aren’t free. But when your problem is genuinely “read a lot of data and process it sequentially,” IAsyncEnumerable<T> turns an unbounded memory problem into a constant one. The next time you write .ToListAsync() out of habit on a query that could return more rows than you expect, it’s worth pausing and asking whether you actually need the list, or whether you just need the next item.

Conclusion

Thanks for reading! 🎉 To not miss my research in software development, you can follow me at @berkslv.

The Idempotency Key Pattern in .NET: What Happens When Your Payment API Gets Called Twice

Wed, 22 Jul 2026 00:00:00 +0300

A customer clicks “Pay Now.” The request hits your API, your payment provider charges the card, and then… the response times out. The mobile app doesn’t know if the payment succeeded, so it does the only thing it knows how to do: it retries. Now you have two successful charges for one order, an angry customer, and a support ticket that starts with “I was charged twice.”

If you’ve built anything that touches money, queues, or third-party APIs, you already know this scenario isn’t hypothetical. Network blips, client timeouts, and load balancer retries are a fact of life in distributed systems. The idempotency key pattern is how production-grade payment APIs guarantee that the same logical request, no matter how many times it’s retried, only ever gets applied once. In this post, I’ll walk through why this matters, what typically goes wrong without it, and how to implement it properly in a .NET API.

The Problem: “At-Least-Once” Delivery Is the Default

Here’s an uncomfortable truth: over an unreliable network, you cannot guarantee “exactly-once” delivery of a request. TCP connections drop mid-response, HTTP clients time out, and load balancers or mobile apps retry on 5xx errors and timeouts. The best you can realistically build for is at-least-once delivery, meaning your endpoint might receive the exact same logical request two, three, or ten times.

For a GET /orders/123 request, that’s harmless. Reading data twice changes nothing. But for POST /payments/charge, every one of those retries can trigger a brand-new charge, because from the server’s point of view, it just looks like a new, unrelated request.

The Old Way: No Protection Against Duplicate Requests

Most teams start without any protection at all. A typical naive payment endpoint looks something like this:


[HttpPost("charge")]
public async Task<IActionResult> ChargeCard([FromBody] ChargeRequest request)
{
 var result = await _paymentGateway.ChargeAsync(request.CardToken, request.Amount);

 await _orderRepository.MarkAsPaidAsync(request.OrderId, result.TransactionId);

 return Ok(result);
}

This works fine in the happy path. But walk through what happens when the client times out waiting for a response that was actually about to succeed:

Client sends POST /payments/charge for order #4711.
Server calls the payment gateway, the card is charged successfully.
Before the server can respond, the client’s HTTP timeout fires.
The client, following standard retry logic, sends the exact same request again.
The server has no memory of the first attempt, so it charges the card a second time.

No amount of “just don’t time out” fixes this, because timeouts, dropped connections, and process crashes are a normal part of operating a networked service in microservices and other distributed systems. The fix isn’t to prevent retries; it’s to make retries safe with a properly designed idempotent API.

Why Idempotency Keys?

An idempotency key is a unique identifier, usually a client-generated UUID, that the caller attaches to a request. It tells your API: “this specific attempt represents one logical operation, no matter how many times you see it.” The server’s job is to:

Store the result of the first successful request against that key.
On any duplicate request carrying the same key, return the stored result instead of re-executing the operation.
Reject requests that reuse a key with a different payload (a sign the client is misusing the key).

What Makes an API Truly Idempotent

Turning a regular endpoint into an idempotent API means the endpoint has to satisfy three properties, regardless of how many times a client calls it with the same key:

Single execution of side effects: the payment gateway, inventory system, or database write only happens once.
Consistent response: every retry gets back the exact same response body and status code as the original attempt.
Bounded lifetime: the key eventually expires, so the store doesn’t grow forever and legitimate new requests aren’t blocked by a key some client reused by mistake.

Stripe, one of the most heavily retried APIs on the planet, documents this exact pattern and requires an Idempotency-Key header on all state-changing requests. It’s not a nice-to-have; it’s the foundation that makes their retry-heavy SDKs safe to use against a payments API.

Designing the Idempotency Store

Before writing any middleware, you need a place to persist idempotency records. A simple relational table works well:


CREATE TABLE IdempotencyKeys (
 Key VARCHAR(64) NOT NULL PRIMARY KEY,
 RequestHash VARCHAR(64) NOT NULL,
 ResponseStatus INT NULL,
 ResponseBody TEXT NULL,
 Status VARCHAR(20) NOT NULL, -- 'Processing' | 'Completed'
 CreatedAt TIMESTAMP NOT NULL,
 ExpiresAt TIMESTAMP NOT NULL
);

A few design decisions matter here:

RequestHash: a hash of the request body, so you can detect if a client reuses the same key for a different payload (that’s a client bug, and you should return a 422 instead of silently returning the wrong stored response).
Status: you need a “Processing” state, not just “Completed,” so a second concurrent request can tell that the first one is still in flight. The actual guarantee against double-charging comes from the database’s unique constraint on Key rejecting the second insert, not from the Status column alone — you’ll see this in the store implementation below.
ExpiresAt: idempotency keys shouldn’t live forever. Stripe expires them after 24 hours; pick a window that matches how long your clients realistically retry, and run a background cleanup job that deletes rows past ExpiresAt so the table doesn’t grow unbounded.

Note this schema uses Postgres-flavored SQL (ON CONFLICT). If you’re on SQL Server, the equivalent is MERGE or an IF NOT EXISTS guard combined with a unique index on Key — the concurrency-safety principle is the same, only the syntax differs.

Implementing It in .NET

Let’s build this as an ActionFilter, so it can be applied declaratively to any endpoint that needs idempotency protection, without polluting the business logic.

1. The Idempotency Store

This example uses Dapper for the raw SQL access, so add it first:


dotnet add package Dapper


public interface IIdempotencyStore
{
 Task<IdempotencyRecord?> GetAsync(string key, CancellationToken ct);
 Task<bool> TryStartProcessingAsync(string key, string requestHash, CancellationToken ct);
 Task CompleteAsync(string key, int statusCode, string responseBody, CancellationToken ct);
}

public record IdempotencyRecord(string RequestHash, string Status, int? ResponseStatus, string? ResponseBody);

The TryStartProcessingAsync method is the critical piece. It must be an atomic “insert if not exists” operation, otherwise two concurrent requests with the same key can both pass the check and both proceed to charge the card:


public class SqlIdempotencyStore : IIdempotencyStore
{
 private readonly IDbConnection _db;

 public SqlIdempotencyStore(IDbConnection db) => _db = db;

 public async Task<bool> TryStartProcessingAsync(string key, string requestHash, CancellationToken ct)
 {
 // Relies on the PRIMARY KEY constraint on `Key` to fail on duplicates
 const string sql = @"
 INSERT INTO IdempotencyKeys (Key, RequestHash, Status, CreatedAt, ExpiresAt)
 VALUES (@Key, @RequestHash, 'Processing', @Now, @Expires)
 ON CONFLICT (Key) DO NOTHING
 RETURNING Key;";

 var inserted = await _db.QueryFirstOrDefaultAsync<string>(sql, new
 {
 Key = key,
 RequestHash = requestHash,
 Now = DateTime.UtcNow,
 Expires = DateTime.UtcNow.AddHours(24)
 });

 return inserted != null;
 }

 public async Task<IdempotencyRecord?> GetAsync(string key, CancellationToken ct)
 {
 const string sql = "SELECT RequestHash, Status, ResponseStatus, ResponseBody FROM IdempotencyKeys WHERE Key = @Key";
 return await _db.QueryFirstOrDefaultAsync<IdempotencyRecord>(sql, new { Key = key });
 }

 public async Task CompleteAsync(string key, int statusCode, string responseBody, CancellationToken ct)
 {
 const string sql = @"
 UPDATE IdempotencyKeys
 SET Status = 'Completed', ResponseStatus = @Status, ResponseBody = @Body
 WHERE Key = @Key";

 await _db.ExecuteAsync(sql, new { Key = key, Status = statusCode, Body = responseBody });
 }
}

The ON CONFLICT (Key) DO NOTHING ... RETURNING Key trick lets the database’s unique constraint do the concurrency control for you, so you don’t need application-level locks.

2. The Action Filter


public class IdempotentAttribute : Attribute, IAsyncActionFilter
{
 public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
 {
 var httpContext = context.HttpContext;

 // Let model validation fail first - an invalid request should never consume a key.
 if (!context.ModelState.IsValid)
 {
 await next();
 return;
 }

 if (!httpContext.Request.Headers.TryGetValue("Idempotency-Key", out var keyHeader) ||
 string.IsNullOrWhiteSpace(keyHeader) || keyHeader.ToString().Length > 64)
 {
 context.Result = new BadRequestObjectResult("A valid Idempotency-Key header (max 64 chars) is required.");
 return;
 }

 var store = httpContext.RequestServices.GetRequiredService<IIdempotencyStore>();
 var key = keyHeader.ToString();
 var requestHash = await ComputeRequestHashAsync(httpContext.Request);

 var existing = await store.GetAsync(key, httpContext.RequestAborted);

 if (existing is not null)
 {
 if (existing.RequestHash != requestHash)
 {
 context.Result = new UnprocessableEntityObjectResult(
 "Idempotency-Key was reused with a different request payload.");
 return;
 }

 if (existing.Status == "Completed")
 {
 context.Result = new ContentResult
 {
 StatusCode = existing.ResponseStatus,
 Content = existing.ResponseBody,
 ContentType = "application/json"
 };
 return;
 }

 // Still processing - a concurrent duplicate arrived while the first one is in flight.
 context.Result = new ConflictObjectResult("Request with this Idempotency-Key is already being processed.");
 return;
 }

 var acquired = await store.TryStartProcessingAsync(key, requestHash, httpContext.RequestAborted);
 if (!acquired)
 {
 // Lost the race to a concurrent request that inserted first.
 context.Result = new ConflictObjectResult("Request with this Idempotency-Key is already being processed.");
 return;
 }

 var executedContext = await next();

 // Persist whatever the action produced so retries get an identical replay.
 // Anything other than ObjectResult (exceptions, StatusCodeResult, etc.) should
 // still release the key - otherwise it stays stuck in "Processing" until it expires.
 if (executedContext.Result is ObjectResult objectResult)
 {
 var statusCode = objectResult.StatusCode ?? 200;
 var body = JsonSerializer.Serialize(objectResult.Value, httpContext.RequestServices
 .GetRequiredService<IOptions<JsonOptions>>().Value.JsonSerializerOptions);
 await store.CompleteAsync(key, statusCode, body, httpContext.RequestAborted);
 }
 else
 {
 var statusCode = executedContext.Exception is not null ? 500 : (httpContext.Response.StatusCode);
 await store.CompleteAsync(key, statusCode, string.Empty, httpContext.RequestAborted);
 }
 }

 private static async Task<string> ComputeRequestHashAsync(HttpRequest request)
 {
 request.EnableBuffering();
 using var reader = new StreamReader(request.Body, leaveOpen: true);
 var body = await reader.ReadToEndAsync();
 request.Body.Position = 0;

 var bytes = Encoding.UTF8.GetBytes(body);
 var hash = SHA256.HashData(bytes);
 return Convert.ToHexString(hash);
 }
}

Two details worth calling out: the JsonSerializerOptions is pulled from the app’s actual AddJsonOptions configuration via IOptions<JsonOptions>, so the replayed body matches the casing and converters the client already expects — reusing the default serializer here would silently produce a different payload than the original response. And every code path, including failures, now calls CompleteAsync so a key never gets permanently stuck in "Processing"; combine this with the ExpiresAt cleanup job so any record that somehow still gets stuck is reclaimed automatically.

3. Applying the Idempotent API to the Endpoint


[HttpPost("charge")]
[Idempotent]
public async Task<IActionResult> ChargeCard([FromBody] ChargeRequest request)
{
 var result = await _paymentGateway.ChargeAsync(request.CardToken, request.Amount);
 await _orderRepository.MarkAsPaidAsync(request.OrderId, result.TransactionId);

 return Ok(result);
}

Now the client is responsible for generating a UUID per logical payment attempt and sending it as the Idempotency-Key header on every retry of that same attempt:


$ curl -X POST https://api.example.com/payments/charge \
 -H "Idempotency-Key: 8f14e45f-ceea-467e-bb9d-8f7c1a1c1b1a" \
 -H "Content-Type: application/json" \
 -d '{"orderId":"4711","cardToken":"tok_visa","amount":4999}'

If the network drops before the response arrives and the client retries with the exact same header, the second request returns the stored result from the first attempt, without ever touching the payment gateway again.

What This Doesn’t Solve

Idempotency keys are not a silver bullet, and it’s worth being explicit about their limits:

They don’t replace the outbox pattern. If your charge handler also needs to publish an OrderPaidEvent, you still need transactional guarantees for that event to avoid the classic dual-write problem.
They require client cooperation. If your mobile client generates a new UUID on every retry instead of reusing the same one, the whole pattern is defeated. Document this clearly in your API contract, and consider generating the key client-side at the moment the user taps “Pay,” not per HTTP attempt.
They add a write on every request. For extremely high-throughput, low-value endpoints, the extra database round-trip might not be worth it. Reserve this pattern for operations where duplication is actually expensive: payments, order creation, and anything that moves money or inventory.
Expiration is a trade-off. Too short, and legitimate slow retries fall outside the window and double-charge anyway. Too long, and you accumulate an ever-growing table of dead records. A background cleanup job that purges expired keys is worth building from day one.

Summary

Retries are not an edge case in distributed systems; they’re the normal operating condition for microservices talking to payment gateways, webhooks, and each other. The idempotency key pattern doesn’t try to prevent retries, it makes them harmless by turning “did this get charged?” into a lookup instead of a guess. Remember that customer from the opening story, stuck wondering if they’d been billed twice? With an idempotent API in place, that retry would have silently returned the exact same success response, and they’d never have known there was a network hiccup at all. If you’re building a payment API, a webhook receiver, or anything else where duplicate execution has a real cost, treat idempotency keys as a first-class requirement, not an afterthought you bolt on after the first double-charge incident.

Conclusion

Thanks for reading! 🎉 To not miss my research in software development, you can follow me at @berkslv.

Events vs Commands in Software Architecture: A Complete .NET Guide

Mon, 22 Jun 2026 14:55:00 +0300

Demystifying Events vs Commands in Software Architecture: A Complete .NET Guide

In the modern landscape of software engineering, shifting from monolithic systems to distributed microservices is a common evolutionary path. As systems grow in complexity, the way different components, modules, and services communicate becomes the critical factor in defining the system’s resilience, scalability, and maintainability. If you are building robust, cloud-native applications, you inevitably encounter the need to decouple your components.

At the heart of this decoupling and communication strategy lie two fundamental messaging patterns: Commands and Events.

While they might seem similar at first glance—both are essentially messages containing data sent from one part of a system to another—their intent, handling, and architectural implications are vastly different. Misunderstanding the distinction between events vs commands in software architecture is one of the most common pitfalls when designing an Event-Driven Architecture (EDA) or implementing Command Query Responsibility Segregation (CQRS).

In this comprehensive guide, we will explore the theoretical differences between events and commands, analyze when to use which, and walk through a practical storytelling implementation using .NET and C#.

The Core Communication Problem in Distributed Systems

Before we dive into the definitions, let’s understand the problem we are trying to solve.

Imagine an e-commerce application. A user clicks the “Checkout” button. In a traditional, tightly coupled monolithic architecture, the system might sequentially execute the following steps within a single synchronous flow:

Validate the cart.
Deduct inventory.
Process the payment.
Generate an invoice.
Send a confirmation email.

If the email server is down, the entire checkout process might fail, rolling back the payment and frustrating the user. This tight coupling creates brittle systems.

To solve this, architects introduce asynchronous messaging. Instead of calling methods directly, services send messages to each other through a mediator or a message broker (like RabbitMQ, Apache Kafka, or cloud-native solutions on AWS and Google Cloud). But how should these messages be structured? Should the checkout service tell the email service to send an email, or should it simply state that an order was placed?

This is where the distinction between Commands and Events becomes crucial.

What is a Command?

A Command is an expression of intent. It is a request for the system to perform a specific action or change its state.

Think of a command as an imperative instruction. You are telling the system exactly what you want it to do. Because it is a request, a command can be rejected. The system might validate the command and decide that it cannot be executed due to business rules, permissions, or invalid data.

Key Characteristics of a Command:

Imperative Naming: Commands are named with verbs in the imperative mood (e.g., PlaceOrderCommand, CreateUserCommand, ProcessPaymentCommand).
Targeted: A command is routed to exactly one handler. You do not broadcast a command to the entire system; you send it to the specific component responsible for that action.
Can Fail: Because it is a request to change state, the receiving handler can (and often will) reject it if validation fails, returning an error or an exception to the sender.
High Coupling (Behavioral): The sender of the command needs to know what action needs to happen, implying a tighter behavioral coupling than events, though the physical coupling might still be abstracted via a message bus.

What is an Event?

An Event, on the other hand, is a statement of fact. It is an announcement that something has already happened in the past.

You cannot reject an event because you cannot change the past. If an event is published, the state change has already occurred. Components in the system listen to events to react and trigger their own subsequent processes.

Key Characteristics of an Event:

Past-Tense Naming: Events are named using verbs in the past tense (e.g., OrderPlacedEvent, UserCreatedEvent, PaymentProcessedEvent).
Broadcasted (Publish/Subscribe): An event is published to an event bus or message broker. It can have zero, one, or multiple handlers. The publisher does not know or care who is listening.
Cannot Be Rejected: The fact has occurred. Subscribers must process it. If a subscriber fails to process an event, it must handle its own retry logic; it cannot tell the publisher to “undo” the fact.
Loose Coupling: The sender (publisher) is entirely decoupled from the receivers (subscribers). The publisher simply announces a state change, making it incredibly easy to add new functionality without touching existing code.

Key Differences: Events vs Commands

To solidify the concepts, let’s look at a side-by-side comparison.

Feature	Command	Event
Definition	A request to perform an action.	A notification that something happened.
Naming Convention	Imperative (e.g., `ShipOrder`)	Past Tense (e.g., `OrderShipped`)
Routing / Handlers	Exactly one handler (1:1).	Zero to many handlers (1:N).
Direction	Point-to-point. Sender targets a receiver.	Publish-Subscribe. Sender broadcasts.
Failure Handling	Can be rejected (validation error).	Cannot be rejected. Past facts are immutable.
Sender’s Knowledge	Knows what needs to happen.	Does not know who cares about the event.

The .NET Implementation Story: Bringing it to Life

Let’s tell a story using .NET to illustrate how these concepts flow together in a real-world application. We will use the highly popular MediatR library, which is the standard implementation for in-memory messaging and CQRS patterns in the .NET ecosystem.

Imagine we are building an Order Management microservice.

Step 1: Defining the Command

The journey begins when a user submits their cart. The API controller receives the HTTP request and creates a command. Notice the imperative naming. We use C# records because messages should be immutable.

using MediatR;

namespace ECommerce.Domain.Commands;

// The Command: A request that returns a strongly typed result
public record PlaceOrderCommand(
 Guid CustomerId,
 List<CartItem> Items,
 string ShippingAddress
) : IRequest<OrderResult>;

public record CartItem(Guid ProductId, int Quantity, decimal Price);

public record OrderResult(bool IsSuccess, string Message, Guid? OrderId = null);

Step 2: Handling the Command

The command is routed to exactly one handler. This handler contains the core business logic. It validates the request, modifies the database state, and if successful, generates an Event.

using MediatR;

namespace ECommerce.Application.Handlers.Commands;

public class PlaceOrderCommandHandler : IRequestHandler<PlaceOrderCommand, OrderResult>
{
 private readonly IOrderRepository _repository;
 private readonly IMediator _mediator;

 public PlaceOrderCommandHandler(IOrderRepository repository, IMediator mediator)
 {
 _repository = repository;
 _mediator = mediator;
 }

 public async Task<OrderResult> Handle(PlaceOrderCommand request, CancellationToken cancellationToken)
 {
 // 1. Validation (The command can be rejected!)
 if (request.Items == null || !request.Items.Any())
 {
 return new OrderResult(false, "Cart cannot be empty.");
 }

 // 2. State Change
 var totalAmount = request.Items.Sum(i => i.Price * i.Quantity);
 var order = new Order(Guid.NewGuid(), request.CustomerId, totalAmount, request.ShippingAddress);

 await _repository.SaveAsync(order);

 // 3. Announcing the Fact (The Event)
 var orderPlacedEvent = new OrderPlacedEvent(order.Id, request.CustomerId, totalAmount);

 // Notice we are Publishing the event, not Sending a command.
 await _mediator.Publish(orderPlacedEvent, cancellationToken);

 return new OrderResult(true, "Order successfully placed.", order.Id);
 }
}

Step 3: Defining the Event

The state has changed. The order is securely stored in the database. Now, the system simply announces this fact to the rest of the application. Notice the past-tense naming.

using MediatR;

namespace ECommerce.Domain.Events;

// The Event: A notification that something happened. Does not return a response.
public record OrderPlacedEvent(
 Guid OrderId,
 Guid CustomerId,
 decimal TotalAmount
) : INotification;

Step 4: Reacting to the Event (Multiple Handlers)

This is where the magic of Event-Driven Architecture shines. Because we published an event, we can have multiple independent handlers react to it without modifying our core PlaceOrderCommandHandler.

Let’s say the marketing team wants to send a “Thank You” email, and the logistics team needs to reserve the inventory. We simply create two separate event handlers.

Handler A: The Email Service

using MediatR;

namespace ECommerce.Application.Handlers.Events;

public class SendOrderConfirmationEmailHandler : INotificationHandler<OrderPlacedEvent>
{
 private readonly IEmailService _emailService;

 public SendOrderConfirmationEmailHandler(IEmailService emailService)
 {
 _emailService = emailService;
 }

 public async Task Handle(OrderPlacedEvent notification, CancellationToken cancellationToken)
 {
 // React to the fact
 await _emailService.SendEmailAsync(
 notification.CustomerId,
 $"Thank you for your order! Your total is ${notification.TotalAmount}."
 );
 }
}

Handler B: The Inventory Service

using MediatR;

namespace ECommerce.Application.Handlers.Events;

public class ReserveInventoryHandler : INotificationHandler<OrderPlacedEvent>
{
 private readonly IInventoryService _inventoryService;

 public ReserveInventoryHandler(IInventoryService inventoryService)
 {
 _inventoryService = inventoryService;
 }

 public async Task Handle(OrderPlacedEvent notification, CancellationToken cancellationToken)
 {
 // React to the same fact independently
 await _inventoryService.ReserveItemsForOrderAsync(notification.OrderId);
 }
}

By structuring our .NET code this way, we have achieved a beautifully loosely coupled system. If tomorrow the analytics team wants to track sales, we don’t touch the PlaceOrderCommandHandler. We just add a TrackSalesAnalyticsHandler that listens to the OrderPlacedEvent.

Advanced Architectural Considerations

While the MediatR example perfectly illustrates the in-memory concepts, moving these patterns out of memory and into a distributed cloud environment introduces complex challenges. When utilizing cloud platforms like Google Cloud, AWS, or Azure to run microservices, messaging becomes distributed.

Here are three advanced patterns you must consider when scaling Events vs Commands:

1. The Outbox Pattern (Guaranteed Delivery)

In our C# example, we saved the order to the database and then published the event to MediatR. But what if the database save succeeds, but the application crashes exactly one millisecond before the await _mediator.Publish() line is executed?

The state changed, but the event was never fired. The customer’s card was charged, but the warehouse never got the memo. This is a catastrophic failure in distributed systems known as the “Dual Write Problem.”

To solve this, architects use the Transactional Outbox Pattern. Instead of publishing the event directly, the command handler writes the OrderPlacedEvent into an “Outbox” table in the same database transaction as the order itself. A separate background worker process (like a .NET BackgroundService) constantly reads this Outbox table and publishes the messages to your external broker (e.g., RabbitMQ or Google Cloud Pub/Sub). This guarantees at-least-once delivery of your events.

2. Idempotency (Handling Duplicate Events)

Because distributed messaging systems usually guarantee “at-least-once” delivery, your event handlers might receive the same OrderPlacedEvent twice.

If the SendOrderConfirmationEmailHandler is not designed carefully, the customer might receive two emails. Worse, if an event triggers a payment capture, they might be charged twice.

Event handlers must be idempotent. This means that applying the same event multiple times has the same effect as applying it once. In .NET, this is often implemented by maintaining a table of processed EventIds. Before a handler processes an event, it checks: “Have I seen this Event ID before?” If yes, it safely ignores it and returns a success response.

3. Event Sourcing vs Event-Driven Architecture

It is important not to confuse an Event-Driven Architecture (EDA) with Event Sourcing.

EDA uses events to communicate between services (like our example above). State is still saved in a traditional database table (e.g., an Orders table with a Status column).
Event Sourcing is a much more complex paradigm where the events are the database. Instead of saving the current state of an order, you save an append-only log of events: OrderCreated, AddressUpdated, ItemAdded, OrderCheckedOut. To figure out the current state, the system replays the events from the beginning of time. While powerful for audit trails, it introduces massive complexity and should be reserved for specific domains that require strict historical accuracy (like financial ledgers).

When to Use Which?

The beauty of software design is choosing the right tool for the job. Here is a quick cheat sheet for when to deploy Commands vs Events in your .NET applications:

Use a Command when:

You need the system to perform a specific action and you know exactly which component should handle it.
You need to validate user input and potentially reject the request.
You expect a result back (success, failure, or the ID of a newly created entity).

Use an Event when:

A significant state change has occurred, and you want to notify other parts of the system.
You want to allow multiple, disparate modules to react to a single action without creating tight coupling.
You are integrating across microservice boundaries and want to ensure services remain autonomous.

Summary

Mastering the difference between events vs commands in software architecture is a milestone in a developer’s journey toward system design excellence. Commands drive the intent and guard the business rules of your application, ensuring state changes only happen when valid. Events act as the nervous system, broadcasting facts and enabling a highly scalable, loosely coupled ecosystem of microservices.

By leveraging powerful libraries like MediatR in .NET, and understanding the nuances of asynchronous communication, you can build systems that not only handle the complexities of today’s business logic but are also resilient and flexible enough to adapt to the requirements of tomorrow. Remember to name your commands imperatively, treat your events as immutable facts of the past, and embrace the power of decoupling.

Conclusion

Thanks for reading! 🎉 To not miss my research in software development, you can follow me at @berkslv.

June 2026 AI Economy: LLM Price and Performance Comparison

Fri, 19 Jun 2026 10:38:00 +0300

The artificial intelligence (AI) industry is experiencing one of the fastest evolutions in tech history, and as of June 2026, the balance of power in this ecosystem has been completely reshaped. In this comprehensive guide, we will deeply analyze the current state of the market based on the “AI Economy in June 2026: LLM Price and Performance Comparison” data.

For companies and developers shaping AI strategies, we have three main focus areas: recognizing the Large Language Model (LLM) providers dominating the market, benchmarking the price/performance of the highest capacity “Frontier” models, and finally exploring how to protect our wallets—that is, how to optimize costs in this massive data economy.

Western “Frontier” Leaders Shaping the Market

The giant companies referred to as “Western Frontier Leaders” in the industry continue to push the boundaries with massive investments and proprietary systems. The current strategies of these major market players are as follows:

OpenAI: Sparking the AI revolution, OpenAI continues to lead technological leaps with its GPT-5+ series. Backed by Microsoft’s massive investments, the organization proceeds with a capped-profit company structure.
Google: Shows up in the market with the Gemini series, powered by its proprietary TPU (Tensor Processing Unit) hardware. Google’s biggest advantage is its ability to entirely self-fund this massive operation through Alphabet’s vast ecosystem.
Anthropic: Centering the concept of safety, the company differentiates itself from competitors with its “Constitutional AI” vision. Heavily funded by Amazon and Google, Anthropic is the creator of the famous Claude family, possessing top-tier capabilities.
Microsoft: While maintaining its strategic partnership with OpenAI seamlessly, it also takes specific steps for corporate needs. It creates diversity by introducing its internal MAI series to the market, specifically optimized for enterprise reasoning and software tasks.

Global Open-Weight Competitors and Disruptive Innovation

Against the high-cost and controlled ecosystems offered by closed systems, the open-source (Open-Weight) world is creating a serious disruptive effect in the market.

DeepSeek: Drawing attention with its architectural innovations, the company uses a highly cost-effective “Mixture of Experts” (MoE) infrastructure. DeepSeek is disrupting Western markets with these state-of-the-art open models.
Alibaba: The China-based giant is present in the market with the Qwen series. Self-funded through the Alibaba Cloud infrastructure, the company particularly focuses on multi-agent optimization.
Z.AI: Born from academic roots as a Tsinghua University spin-off, Z.AI develops the GLM series. The company is the market leader in efficient open-source agent-based models and multi-step reasoning algorithms.
xAI: The innovation company led by Elon Musk utilizes the Colossus supercluster, which possesses massive computing power. Furthermore, by processing real-time data flowing from the X platform, it trains dynamic models with a highly natural conversational tone.

Hardware & Specialized Hubs

Hardware manufacturers, the driving force behind the models, are also directly involved in AI production.

NVIDIA: The undisputed hardware giant doesn’t just produce chips. The company is developing its own “Nemotron” open-weight models, leveraging its internal superclusters and synthetic data compilation pools.
Moonshot AI: Particularly known as the visionary team behind the popular Kimi chatbot, Moonshot AI focuses on long-context understanding—one of the most challenging areas of AI—and autonomous agentic reasoning at scale.
MiniMax: Powering interactive consumer AI applications, the company also produces versatile multimodal models that form the foundation of audio and video platforms like Hailuo.

Detailed Frontier Model Rankings: June 2026 Data

There are massive gaps between the overall intelligence scores of AI models and the input/output costs they demand per 1 million tokens. As of June 2026, the detailed performance and price table of the market’s leading models is as follows:

Rank	Model Name	Creator	Overall Score (0-100)	Input Cost (1M Tokens)	Output Cost (1M Tokens)
1	Claude Mythos 5	Anthropic	99	$10.0	$50.0
3	GLM-5.2	Z.AI	94	$1.4	$4.4
5	Gemini 3.1 Pro	Google	91	$2.0	$12.0
6	Qwen3.7 Max	Alibaba	90	$1.25	$3.75
7	GPT-5.4 Pro	OpenAI	90	$30.0	$180.0
15	DeepSeek V4 Pro (Max)	DeepSeek	86	$1.74	$3.48
21	Kimi K2.6	Moonshot AI	81	$0.95	$4.0
23	MiniMax M3	MiniMax	79	$0.3	$1.2

Efficiency Analysis and the Dramatic Cost Gap

When we examine the ranking table and efficiency analysis graphs, it is striking that while the performance bars are very close to each other, there are incredible differences in the price bars. When the price bars are scaled according to the massive total cost of OpenAI’s flagship GPT-5.4 Pro at $210 ($30 input + $180 output), it is clearly noticeable that the costs of other models remain almost invisibly thin on the graph.

The Shift at the Extremes: GPT-5.4 Pro offers extraordinary depth and analysis capability with an overall score of 90. However, it demands $180 for 1 million output tokens. In contrast, the 1 million output token cost of the MiniMax M3 model, which has a score of 79, is only around $1.20. The fact that MiniMax M3 offers a 99.3% cheaper option in terms of cost causes a massive paradigm shift in the AI strategies of companies and developers.
Realistic Price Gap: Alongside extreme examples, there are also significant price advantages in heavily preferred models in the mid-tier that perform closely to one another. The 1 million output cost of the Claude Sonnet 4.6 model, which has a performance score of 82, is $15. Yet, when you use the open-weight DeepSeek V4 Pro model, which has a higher score of 86, your cost drops to $3.48. In other words, simply by choosing the right model, it is possible to gain a direct price advantage of 76.8% by increasing quality rather than compromising it.

Mid-Tier & Value-Efficiency Market

The competition in the mid-tier, which is the real driving force of the market, is driving costs even lower.

OpenAI’s GPT-5.1 model has a score of 77 but incurs a cost of $10.00 per 1 million outputs.

DeepSeek V4 Flash, despite achieving a score of 74, pushes the limits in the speed-to-cost balance and demands only 28 cents ($0.28) for 1 million output tokens.
Notably, open models like Alibaba’s Qwen3.6-27B (72 score) and NVIDIA’s Nemotron 3 Ultra (68 score) reach significant ranks on the scoreboards with a $0.00 (zero cost) per token cost, excluding hosting expenses.
xAI’s Grok 4.1 Fast model, with a score of 68, has a cost of only $0.50 per 1 million outputs.

Economic Impact: Choosing the Right Source Type

At the end of the day, organizations must make a fundamental choice when determining their AI strategies:

Proprietary Models: These models offered by giants like Anthropic or Google provide top-tier engineering support, a closed and secure ecosystem, guaranteed Service Level Agreements (SLA), and strong compliance guardrails. However, in return for all these corporate advantages, much higher, premium prices must be paid.
Open-Weight Models: These models, on the other hand, offer developers extraordinary, extreme cost savings (often with $0 per token hosting), full data privacy control, and full ownership. Furthermore, as clearly seen in the DeepSeek and Qwen examples, the performance of these models has now reached the scores of top-tier frontier models.

How Will We Protect Our Wallets? (Practical Developer Solutions)

This dizzying gap between performance and price makes “protecting the wallet” a necessity in the tech world. For developers, the practical technological answer to this problem lies in moving beyond traditional boundaries, namely GitHub Copilot.

Modern software development processes require Universal Access to models like GLM, DeepSeek, and Kimi, which are not available in the limited pool of traditional tools like Copilot and are unsupported by closed systems. The revolutionary infrastructures that stand out at this point are:

OpenCode Go: This is an advanced subscription system that provides open-source model optimization, bypassing all restrictions to make agent-based coding accessible to everyone. It allows users to connect to any model they want, including Claude, GPT, or Gemini from any provider.
OpenRouter Routing: Eliminating the risks and costs of being tied to a single provider, this unified API is a dynamic routing system that instantly switches to a backup model (fallback) in the event of a failure or crash, and ensures you reach the most cost-effective option at any moment with its price balancing features.

In conclusion, remaining competitive in the 2026 AI economy is not just about choosing the most popular option; it is about strategically establishing flexible APIs and open-source infrastructures that can melt intelligence capacity, data privacy, and price advantage into the same melting pot.

Conclusion

Thanks for reading! 🎉 To not miss my research in software development, you can follow me at @berkslv.

Refactoring from an Anemic to a Rich Domain Model in .NET

Tue, 16 Jun 2026 00:00:00 +0300

If you have spent any significant amount of time building enterprise applications in .NET, you have likely encountered the concept of Domain-Driven Design (DDD). DDD promises a way to tackle software complexity by aligning your code with the real-world business domain it represents. However, one of the most common pitfalls developers fall into when adopting DDD—or even just basic Object-Oriented Programming (OOP)—is the creation of an Anemic Domain Model.

In many .NET architectures, you will see a familiar pattern: “entities” that are nothing more than bags of public getters and setters, accompanied by massive “service” classes that contain all the business rules, validation, and state manipulation logic. While this structure might feel comfortable, especially for those coming from a database-centric background, it actively works against the principles of object-oriented design and encapsulation.

In this comprehensive guide, we will explore exactly what an Anemic Domain Model is, why industry experts consider it an anti-pattern, and how you can refactor your C# applications toward a Rich Domain Model. We will look at practical code examples, discuss how to handle persistence with Entity Framework Core (EF Core), and see how moving logic into your entities makes unit testing a breeze.

1. The Trap of the Anemic Domain Model

What is an Anemic Domain Model?

The term “Anemic Domain Model” was famously coined by Martin Fowler back in 2003. He described it as an anti-pattern where objects look like real domain entities (often named after nouns in the business space, like Customer, Order, or Invoice) but possess virtually no behavior. Instead, they are simply data containers—C# classes filled with public properties.

Let’s look at a classic example of an anemic entity in C#:

public class Order
{
 public Guid Id { get; set; }
 public Guid CustomerId { get; set; }
 public DateTime OrderDate { get; set; }
 public OrderStatus Status { get; set; }
 public decimal TotalAmount { get; set; }
 public List<OrderItem> Items { get; set; } = new List<OrderItem>();
 public string ShippingAddress { get; set; }
}

public enum OrderStatus
{
 Pending,
 Paid,
 Shipped,
 Cancelled
}

At first glance, this might look completely normal. This is how the vast majority of Entity Framework tutorials teach you to build classes. However, this class is entirely devoid of behavior. It is a “dumb” object.

Because Order cannot protect its own state, any part of the application can modify it directly:

var order = new Order();
// Wait, an order with no customer, no items, and it's already marked as shipped?
order.Status = OrderStatus.Shipped;
order.TotalAmount = -500m; // Negative amount? Sure, why not!

The “Service” Layer Bloat

Because the entity has no logic, the business rules must live somewhere else. This leads to the creation of “God classes” or massive service layers, often referred to as Transaction Scripts.

Here is what an OrderService looks like when dealing with an anemic model:

public class OrderService
{
 public void AddItemToOrder(Guid orderId, OrderItem item)
 {
 var order = _repository.Get(orderId);

 if (order == null) throw new Exception("Order not found");

 if (order.Status == OrderStatus.Shipped || order.Status == OrderStatus.Cancelled)
 {
 throw new InvalidOperationException("Cannot modify a shipped or cancelled order.");
 }

 order.Items.Add(item);

 // Recalculate total
 order.TotalAmount = order.Items.Sum(i => i.Price * i.Quantity);

 _repository.Save(order);
 }
}

While this code works, it represents procedural programming disguised as object-oriented programming. The logic concerning what makes an Order valid is pulled out of the Order and dumped into the OrderService.

The Costs of Anemia

When your domain model is anemic, you encounter several significant architectural costs:

Lack of Encapsulation: Any code anywhere can change the state of an entity. It is impossible to guarantee that an Order is in a valid state.
Duplicated Logic: If you need to recalculate the total amount of an order in a different use case (e.g., applying a discount), you will likely duplicate the recalculation logic in another service.
Low Cohesion: The data (Order) and the behavior that operates on that data (OrderService) are separated. You have to navigate through multiple layers to understand the lifecycle of an order.
Fragility: As the application grows, complex business logic becomes scattered across dozens of services, making it incredibly difficult to track down bugs or refactor the system.

2. The Cure: Introducing the Rich Domain Model

A Rich Domain Model flips this paradigm on its head. In a rich model, entities are intelligent objects. They encapsulate both their data (state) and the business rules (behavior) that govern how that data can be mutated.

A rich domain model is built on three core pillars:

Always-Valid State (Invariants): An entity should never exist in an invalid state. Its creation and mutation are strictly controlled.
Encapsulation: Properties cannot be arbitrarily changed from the outside. State mutations happen exclusively through clearly named methods.
Behavior-Driven: Instead of asking an object for its data and making decisions on its behalf, you tell the object what to do (the Tell, Don’t Ask principle).

Let’s begin the process of refactoring our anemic Order entity into a behavior-driven, rich domain entity in C#.

3. Step-by-Step Refactoring to a Rich Domain Model in C#

Step 1: Lock Down the State (Private Setters)

The very first step to curing an anemic model is to stop the bleeding. We must prevent external code from arbitrarily changing properties. We achieve this by making all property setters private or protected.

public class Order
{
 public Guid Id { get; private set; }
 public Guid CustomerId { get; private set; }
 public DateTime OrderDate { get; private set; }
 public OrderStatus Status { get; private set; }
 public decimal TotalAmount { get; private set; }
 public string ShippingAddress { get; private set; }

 // We don't want external code adding to the list directly
 private readonly List<OrderItem> _items = new List<OrderItem>();
 public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly();
}

Notice what happened here:

The set accessors are now private. You can read the state of the order, but you cannot change it directly.
The Items collection is now exposed as an IReadOnlyCollection<OrderItem>. The actual list is hidden behind a private readonly backing field. This prevents someone from calling order.Items.Add(...) from the outside.

Step 2: Meaningful Constructors

If setters are private, how do we create an object? We use a parameterized constructor that requires all the necessary information to create a valid entity from the very start.

public class Order
{
 // ... properties ...

 public Order(Guid id, Guid customerId, string shippingAddress)
 {
 if (id == Guid.Empty) throw new ArgumentException("Order ID cannot be empty.");
 if (customerId == Guid.Empty) throw new ArgumentException("Customer ID cannot be empty.");
 if (string.IsNullOrWhiteSpace(shippingAddress)) throw new ArgumentException("Shipping address is required.");

 Id = id;
 CustomerId = customerId;
 ShippingAddress = shippingAddress;

 // Initial defaults
 OrderDate = DateTime.UtcNow;
 Status = OrderStatus.Pending;
 TotalAmount = 0m;
 }
}

Now, it is literally impossible to create an Order without a Customer ID or a Shipping Address. The compiler enforces your business rules.

Step 3: Introduce Domain Methods (Behavior)

Now that the state is protected, we need to introduce explicit, intention-revealing methods to allow state mutations. This is where we move the logic out of the OrderService and into the Order entity.

Let’s implement the logic for adding an item and marking the order as shipped.

public class Order
{
 // ... constructor and properties ...

 public void AddItem(Product product, int quantity)
 {
 if (Status != OrderStatus.Pending)
 {
 throw new InvalidOperationException("Can only add items to a pending order.");
 }

 if (quantity <= 0)
 {
 throw new ArgumentException("Quantity must be greater than zero.");
 }

 var existingItem = _items.SingleOrDefault(i => i.ProductId == product.Id);
 if (existingItem != null)
 {
 existingItem.IncreaseQuantity(quantity);
 }
 else
 {
 _items.Add(new OrderItem(product.Id, product.Price, quantity));
 }

 RecalculateTotal();
 }

 public void Ship()
 {
 if (Status != OrderStatus.Paid)
 {
 throw new InvalidOperationException("Cannot ship an order that has not been paid.");
 }

 if (!_items.Any())
 {
 throw new InvalidOperationException("Cannot ship an empty order.");
 }

 Status = OrderStatus.Shipped;
 }

 private void RecalculateTotal()
 {
 TotalAmount = _items.Sum(item => item.Price * item.Quantity);
 }
}

The Resulting Application Layer

Let’s look at what our OrderService (now often called a Command Handler or Application Service in Clean Architecture) looks like after this refactoring:

public class OrderService
{
 public void AddItemToOrder(Guid orderId, Product product, int quantity)
 {
 var order = _repository.Get(orderId);
 if (order == null) throw new Exception("Order not found");

 // The logic is no longer here! We simply delegate to the domain.
 order.AddItem(product, quantity);

 _repository.Save(order);
 }
}

The Application Service is now thin and acts purely as an orchestrator. It fetches the entity from the database, invokes the behavior on the entity, and saves the new state back to the database. All the heavy lifting, business rules, and invariants are neatly encapsulated inside the Order class. This perfectly aligns with Domain-Driven Design principles.

4. Entity Framework Core: Mapping Rich Models to the Database

A major historical reason developers stuck with Anemic Domain Models was because Object-Relational Mappers (ORMs) required them. Early versions of Entity Framework demanded public setters, public parameterless constructors, and public collections to map tables to objects.

Thankfully, modern Entity Framework Core (EF Core) is incredibly powerful and actively supports Domain-Driven Design patterns. You can maintain a completely encapsulated Rich Domain Model without leaking persistence concerns into your domain.

Here are the key EF Core features you need to persist Rich Domain Models:

1. Parameterless Constructors for EF Core

When EF Core reads data from the database, it needs a way to instantiate your objects before setting their properties. You don’t want a public parameterless constructor because that breaks encapsulation. Instead, you can provide a private parameterless constructor specifically for EF Core.

public class Order
{
 // Public constructor for your application code
 public Order(Guid id, Guid customerId, string shippingAddress) { ... }

 // Private constructor for EF Core
 private Order() { }
}

EF Core uses reflection to instantiate the object, so a private constructor works perfectly while keeping your API safe from other developers.

2. Mapping Private Backing Fields

EF Core is smart enough to find and bind to private backing fields automatically. If you have an IReadOnlyCollection<OrderItem> Items property and a _items backing field, EF Core will map the relationships directly to the _items field when materializing data from the database.

If your naming convention differs, you can configure it explicitly in the OnModelCreating method or your IEntityTypeConfiguration:

public class OrderConfiguration : IEntityTypeConfiguration<Order>
{
 public void Configure(EntityTypeBuilder<Order> builder)
 {
 builder.HasKey(o => o.Id);

 // Tell EF Core to use the private backing field for the collection
 builder.Metadata.FindNavigation(nameof(Order.Items))
 .SetPropertyAccessMode(PropertyAccessMode.Field);
 }
}

3. Value Objects via Owned Entities

In a Rich Domain Model, you often want to group related properties into Value Objects. For example, instead of storing Currency and Amount separately on an entity, you can create a Money value object.

EF Core supports this through Owned Types (OwnsOne):

// The Value Object
public class Money
{
 public string Currency { get; private set; }
 public decimal Amount { get; private set; }

 public Money(string currency, decimal amount)
 {
 Currency = currency;
 Amount = amount;
 }

 private Money() { } // For EF Core
}

// Inside your Entity Configuration:
builder.OwnsOne(o => o.Price, priceBuilder =>
{
 priceBuilder.Property(p => p.Currency).HasColumnName("PriceCurrency");
 priceBuilder.Property(p => p.Amount).HasColumnName("PriceAmount");
});

This allows you to maintain a highly expressive, object-oriented domain model while neatly flattening the data into a single SQL table.

5. The Magic of Unit Testing Rich Domain Models

One of the most profound benefits of moving logic into your entities is how much easier your unit testing becomes.

When your logic lives in a massive OrderService, writing a unit test is painful. You have to mock the IOrderRepository, mock the IProductRepository, mock the logging service, arrange the database state, and finally test the logic. The test setup is often larger than the test itself.

But when you use a Rich Domain Model, the business logic relies purely on the state of the entity. There are no external dependencies, no databases, and no APIs inside your Order class. It is pure C# code.

Testing the domain logic becomes incredibly straightforward and lightning-fast:

public class OrderTests
{
 [Fact]
 public void AddItem_Should_ThrowException_When_OrderIsNotPending()
 {
 // Arrange
 var order = new Order(Guid.NewGuid(), Guid.NewGuid(), "123 Main St");

 // Use reflection or a test-specific setup to transition state to Shipped 
 // (Assuming we have a Pay() then Ship() method)
 order.Pay();
 order.Ship();

 var product = new Product(Guid.NewGuid(), "Laptop", 1000m);

 // Act & Assert
 var exception = Assert.Throws<InvalidOperationException>(() =>
 order.AddItem(product, 1));

 Assert.Equal("Can only add items to a pending order.", exception.Message);
 }

 [Fact]
 public void AddItem_Should_IncreaseTotalAmount()
 {
 // Arrange
 var order = new Order(Guid.NewGuid(), Guid.NewGuid(), "123 Main St");
 var product = new Product(Guid.NewGuid(), "Laptop", 1000m);

 // Act
 order.AddItem(product, 2);

 // Assert
 Assert.Equal(2000m, order.TotalAmount);
 Assert.Single(order.Items);
 }
}

Notice how there are zero mocks in this test? Because a Rich Domain Model isolates the business logic from infrastructure concerns, your domain layer achieves high testability. You can cover thousands of complex business permutations in milliseconds because you are only executing in-memory C# classes.

Summary

Refactoring from an Anemic Domain Model to a Rich Domain Model requires a shift in mindset. You must move away from viewing your entities as mere reflections of database tables (data structures) and start viewing them as living business concepts with explicit behavior.

By applying principles like private setters, meaningful constructors, explicit domain methods, and adhering to the Tell, Don’t Ask rule, you can centralize your business logic exactly where it belongs: inside the entity.

While transitioning requires a learning curve, the integration of EF Core’s advanced mapping capabilities—like private backing fields and owned entities—means you no longer have to compromise your object-oriented design for the sake of your database. The long-term rewards are undeniable: a highly cohesive, deeply encapsulated, and easily testable codebase that actively resists bugs and technical debt.

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

Legacy WCF/SOAP to Modern .NET: Migration Without Compromise

Fri, 12 Dec 2025 00:00:00 +0300

Legacy WCF/SOAP to Modern .NET: Migration Without Compromise

You’ve just scoped out the perfect migration plan. The roadmap looks beautiful: you are going to take that aging, monolith .NET Framework 4.8 WCF application and strangle it. You’ll extract the business logic, rewrite the interface as a sleek, stateless REST API on .NET 10, and finally shut down the old IIS server.

You present the plan to the stakeholders. The internal teams are cheering. The DevOps guys are already writing the Dockerfiles. Everyone is very excited.

And then, the email arrives.

It’s from the “Legacy Integrations” team at a major partner, or perhaps a vendor managing a hardware device that hasn’t had a firmware update since 2014. Their message is polite but firm:

“We cannot consume a REST API. Our systems require a SOAP envelope. We need the WSDL to remain exactly as it is. If you change the contract, we break.”

Suddenly, your migration plan hits a brick wall. You are faced with two bad choices:

Abort the migration: Keep the entire project on .NET Framework just to satisfy one interface.
The “Sidecar” Nightmare: Build the new system in .NET Core, but keep a zombie .NET Framework server running just to proxy SOAP requests to the new API.

But there is a third option. A bridge.

CoreWCF.

CoreWCF allows us to keep the external contract (SOAP) identical to the legacy system, while completely rewriting the hosting model, dependency injection, and performance characteristics using modern .NET.

In this post, we are going to migrate a InvoiceService step-by-step. We will start with a raw endpoint, secure it with modern authorization, and finally implement sophisticated error handling that bridges the gap between RESTful ProblemDetails and SOAP Faults.

Step 1: The “Hello World” of Migration

Our first goal is simply to get the lights on. We want to prove that we can serve the IInvoiceService contract using the Kestrel web server instead of IIS.

We aren’t worrying about security or error handling yet. We just want to see XML flowing.

The Contract and Service

We keep our Service Contract almost exactly as it was in the old system. The only difference is that we are embracing Task<T> for true asynchronous processing—a massive performance win over the old WCF implementation. Additionally, we have slightly renamed the existing request and response models to better adhere to the Mediator pattern.

// Sample.API.WCF/IInvoiceService.cs
using CoreWCF;
using Sample.Business.Features.Invoices.CreateInvoice;

namespace Sample.API.WCF;

[ServiceContract]
public interface IInvoiceService
{
 [OperationContract]
 Task<CreateInvoiceCommandResponse> CreateInvoice(CreateInvoiceCommand command);
}

// Notice: No attributes here yet, just pure logic.
public class InvoiceService(ISender mediator) : IInvoiceService
{
 public async Task<CreateInvoiceCommandResponse> CreateInvoice(CreateInvoiceCommand command)
 {
 return await mediator.Send(command);
 }
}

The Configuration (Step 1)

Here is the Program.cs for the most basic setup. We strip away everything unnecessary.

// Program.cs - Step 1: Basic WCF Hosting
using CoreWCF;
using CoreWCF.Configuration;
using CoreWCF.Description;
using Sample.API.WCF;
using CoreWCF.Description;

var builder = WebApplication.CreateBuilder(args);

// 1. Add CoreWCF basics to the DI container
builder.Services.AddTransient<InvoiceService>();
builder.Services.AddServiceModelServices();
builder.Services.AddServiceModelMetadata();
services.AddSingleton<IServiceBehavior, UseRequestHeadersForMetadataAddressBehavior>();

// 2. Register our MediatR and Service
builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

var app = builder.Build();

// 3. Configure the CoreWCF Middleware
app.UseServiceModel(serviceBuilder =>
{
 serviceBuilder.AddService<InvoiceService>()
 .AddServiceEndpoint<InvoiceService, IInvoiceService>(
 new BasicHttpBinding(), "/Services/InvoiceService.svc" // The endpoint URL
 );

 // Enable WSDL generation so the stubborn client can update their reference if needed
 var serviceMetadataBehavior = app.Services.GetRequiredService<ServiceMetadataBehavior>();
 serviceMetadataBehavior.HttpGetEnabled = true;
});

app.Run();

At this point, we have achieved victory on the transport layer. The integrator can hit /Services/InvoiceService.svc, send an XML envelope, and our modern MediatR handlers process the logic.

Step 2: Adding Authorization

The “Plain” service works, but it’s dangerous. In the old WCF days, many times developers did not add any authorization support to endpoints and configuring security meant dealing with security certificates.

In CoreWCF, security is just ASP.NET Core security.

If your REST API uses JWT Bearer tokens or Cookie Auth, your CoreWCF endpoints can use them too. We don’t need to reinvent the wheel. We simply decorate our service with [Authorize].

The Updated Service

We add [Authorize] and inject IHttpContextAccessor to prove we can access the user context.

using CoreWCF;
using MediatR;
using Microsoft.AspNetCore.Authorization;
using Sample.Shared.Services.Interfaces;

namespace Sample.API.WCF;

[Authorize] // <--- The magic keyword. This is standard ASP.NET Core auth.
public class InvoiceService(ISender mediator, IHttpContextAccessor httpContextAccessor) : IInvoiceService
{
 public async Task<Response> CreateInvoice(CreateInvoiceCommand command)
 {
 var context = httpContextAccessor.HttpContext;
 Console.WriteLine(context?.User.Identity?.Name);

 return await mediator.Send(command);
 }
}

The Configuration (Step 2)

We need to layer the ASP.NET Core Auth middleware before the CoreWCF middleware.

// Program.cs - Step 2: Adding Authorization
using CoreWCF.Configuration;
using CoreWCF.Description;
using Sample.API.WCF;
using Microsoft.AspNetCore.Authentication.JwtBearer; // Assuming JWT

var builder = WebApplication.CreateBuilder(args);

// 1. Standard ASP.NET Core Authentication Setup
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
 .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
 {
 options.MapInboundClaims = false;
 options.TokenValidationParameters = new TokenValidationParameters
 {
 ValidateIssuer = true,
 ValidateAudience = true,
 ValidateLifetime = true,
 ValidateIssuerSigningKey = true,
 ValidIssuer = configuration["Jwt:Issuer"],
 ValidAudience = configuration["Jwt:Audience"],
 IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(configuration["Jwt:SecretKey"]!))
 };
 });

builder.Services.AddAuthorization(options =>
{
 options.DefaultPolicy = new AuthorizationPolicyBuilder(JwtBearerDefaults.AuthenticationScheme)
 .RequireAuthenticatedUser()
 .Build();
});

builder.Services.AddTransient<InvoiceService>();
builder.Services.AddServiceModelServices();
builder.Services.AddServiceModelMetadata();
services.AddSingleton<IServiceBehavior, UseRequestHeadersForMetadataAddressBehavior>();

builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

var app = builder.Build();

// 2. IMPORTANT: Auth middleware must run before WCF middleware
app.UseAuthentication();

app.UseAuthorization();

app.UseServiceModel(serviceBuilder =>
{
 serviceBuilder.AddService<InvoiceService>()
 .AddServiceEndpoint<InvoiceService, IInvoiceService>(
 new BasicHttpBinding(), "/Services/InvoiceService.svc"
 );

 var serviceMetadataBehavior = app.Services.GetRequiredService<ServiceMetadataBehavior>();
 serviceMetadataBehavior.HttpGetEnabled = true;
});

app.Run();

Now, if the integrator sends a request without a valid standard HTTP Authorization: Bearer header, CoreWCF will reject it with a 401 before it even reaches our code. Of course our customer needs to implement additional step before making a request but without authn & authz any app will be prone to attacks.

Step 3: The Universal Translator (Unified Error Handling)

This is the hardest part of the story.

In a modern REST API, when something goes wrong (e.g., “Invoice not found”), we throw a custom BadRequestException and return a JSON ProblemDetails (RFC 7807) response.

In WCF, we are expected to return a FaultException wrapped in XML.

If we don’t handle this, our nice ValidationException will crash the service and return a generic, ugly “Internal Server Error” to the client. We need a translator that catches our modern Exceptions and translates them into SOAP Faults that still contain all the rich data (like validation error fields).

using System.Diagnostics;
using System.Xml.Linq;
using CoreWCF;
using CoreWCF.Channels;
using CoreWCF.Dispatcher;
using Sample.Domain.Constants;
using Sample.Domain.Exceptions;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Localization;

namespace Sample.API.Filters;

/// <summary>
/// CoreWCF Error Handler that catches exceptions and returns ProblemDetails as SOAP Fault.
/// This acts as a bridge between modern Exception definitions and legacy SOAP faults.
/// </summary>
public class ExceptionHandlerErrorHandler : IErrorHandler
{
 private const string HttpRfcBadRequest = "https://tools.ietf.org/html/rfc7231#section-6.5.1";
 private const string ProblemDetailsNamespace = "urn:ietf:rfc:7807";

 private readonly ILogger<ExceptionHandlerErrorHandler> _logger;
 private readonly IHttpContextAccessor _httpContextAccessor;
 private readonly IStringLocalizer<ExceptionHandleMiddleware> _localizer;
 private readonly Dictionary<Type, Func<Exception, ProblemDetails>> _exceptionHandlers;

 public ExceptionHandlerErrorHandler(
 ILogger<ExceptionHandlerErrorHandler> logger,
 IHttpContextAccessor httpContextAccessor,
 IStringLocalizer<ExceptionHandleMiddleware> localizer)
 {
 _logger = logger;
 _httpContextAccessor = httpContextAccessor;
 _localizer = localizer;

 // Map domain exceptions to specific ProblemDetails handlers
 _exceptionHandlers = new()
 {
 { typeof(BadRequestException), HandleBadRequestException },
 // Add as many as you like
 };
 }

 public bool HandleError(Exception error)
 {
 // Return true to indicate we handled the error and the session is not faulted
 return true;
 }

 public void ProvideFault(Exception error, MessageVersion version, ref Message fault)
 {
 // 1. Convert Exception to ProblemDetails
 var problemDetails = CreateProblemDetails(error);

 // 2. Transform ProblemDetails to XML Element for the SOAP Body
 var problemDetailsElement = TransformToXml(problemDetails);

 // 3. Create a FaultException with the problem details as detail
 var faultException = new FaultException<XElement>(
 problemDetailsElement,
 new FaultReason(problemDetails.Title ?? "An error occurred"),
 new FaultCode(GetFaultCodeFromStatus(problemDetails.Status ?? 500)),
 "ProblemDetails");

 var messageFault = faultException.CreateMessageFault();
 fault = Message.CreateMessage(version, messageFault, faultException.Action);

 // 4. Set the underlying HTTP status code (important for monitoring/observability)
 SetHttpStatusCode(problemDetails.Status ?? StatusCodes.Status500InternalServerError);
 }

 private ProblemDetails CreateProblemDetails(Exception exception)
 {
 var exceptionType = exception.GetType();

 if (_exceptionHandlers.TryGetValue(exceptionType, out var handler))
 {
 _logger.LogWarning("Handled Exception {ExceptionMessage}: Time {Time}", exception.Message, DateTime.UtcNow);
 var pd = handler(exception);
 EnrichProblemDetails(pd);
 return pd;
 }

 _logger.LogError(exception, "Unhandled Exception: Time {Time}", DateTime.UtcNow);
 var unknownPd = HandleUnknownException(exception);
 EnrichProblemDetails(unknownPd);
 return unknownPd;
 }

 // --- Specific Exception Handlers ---
 private ProblemDetails HandleBadRequestException(Exception ex)
 {
 var exception = (BadRequestException)ex;
 return new ProblemDetails
 {
 Status = StatusCodes.Status400BadRequest,
 Type = HttpRfcBadRequest,
 Title = _localizer[Localized.BadRequestExceptionTitle],
 Detail = _localizer[exception.LocalizedMessage, exception.Arguments]
 };
 }

 private ProblemDetails HandleValidationException(Exception ex)
 {
 var exception = (ValidationException)ex;
 return new ValidationProblemDetails(exception.Errors)
 {
 Status = StatusCodes.Status400BadRequest,
 Type = HttpRfcBadRequest,
 Title = _localizer[Localized.ValidationExceptionTitle]
 };
 }

 private static ProblemDetails HandleUnknownException(Exception ex)
 {
 return new ProblemDetails
 {
 Status = StatusCodes.Status500InternalServerError,
 Type = HttpRfcInternalError,
 Title = "An unexpected error occurred",
 Detail = ex.Message
 };
 }

 // --- Helpers ---

 private static void EnrichProblemDetails(ProblemDetails result)
 {
 // Add distributed tracing IDs to the error so clients can report them back to us
 var correlation = AsyncStorage<Correlation>.Retrieve();
 if (correlation is not null)
 {
 result.Extensions.Add("correlationId", correlation.Id);
 }

 var traceId = Activity.Current?.Id;
 if (traceId is not null)
 {
 result.Extensions.Add(nameof(traceId), traceId);
 }
 }

 private static XElement TransformToXml(ProblemDetails problemDetails)
 {
 var ns = XNamespace.Get(ProblemDetailsNamespace);

 var element = new XElement(ns + "problem",
 new XElement(ns + "type", problemDetails.Type),
 new XElement(ns + "title", problemDetails.Title),
 new XElement(ns + "status", problemDetails.Status),
 new XElement(ns + "detail", problemDetails.Detail ?? string.Empty));

 foreach (var extension in problemDetails.Extensions)
 {
 element.Add(new XElement(ns + extension.Key, extension.Value?.ToString() ?? string.Empty));
 }

 if (problemDetails is ValidationProblemDetails validationProblemDetails &&
 validationProblemDetails.Errors.Count > 0)
 {
 var errorsElement = new XElement(ns + "errors");
 foreach (var error in validationProblemDetails.Errors)
 {
 var errorElement = new XElement(ns + "error", new XAttribute("field", error.Key));
 foreach (var message in error.Value)
 {
 errorElement.Add(new XElement(ns + "message", message));
 }
 errorsElement.Add(errorElement);
 }
 element.Add(errorsElement);
 }

 return element;
 }

 private static string GetFaultCodeFromStatus(int status)
 {
 return status switch
 {
 400 => "BadRequest",
 401 => "Unauthorized",
 403 => "Forbidden",
 404 => "NotFound",
 _ => "InternalServerError"
 };
 }

 private void SetHttpStatusCode(int statusCode)
 {
 var httpContext = _httpContextAccessor.HttpContext;
 if (httpContext is not null)
 {
 httpContext.Response.StatusCode = statusCode;
 }
 }
}

The Configuration (Step 3)

We have to wire up this error handler as an IServiceBehavior. This ensures it applies to every single call made to the service.


// Program.cs - Step 3: Production Ready with Error Handling
using CoreWCF;
using CoreWCF.Channels;
using CoreWCF.Configuration;
using CoreWCF.Description;
using CoreWCF.Dispatcher;
using Sample.API.Filters; // Where our ErrorHandler lives
using Sample.API.WCF;
using Microsoft.Extensions.DependencyInjection.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
 .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
 {
 options.MapInboundClaims = false;
 options.TokenValidationParameters = new TokenValidationParameters
 {
 ValidateIssuer = true,
 ValidateAudience = true,
 ValidateLifetime = true,
 ValidateIssuerSigningKey = true,
 ValidIssuer = configuration["Jwt:Issuer"],
 ValidAudience = configuration["Jwt:Audience"],
 IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(configuration["Jwt:SecretKey"]!))
 };
 });

builder.Services.AddAuthorization(options =>
{
 options.DefaultPolicy = new AuthorizationPolicyBuilder(JwtBearerDefaults.AuthenticationScheme)
 .RequireAuthenticatedUser()
 .Build();
});

builder.Services.AddTransient<InvoiceService>();
builder.Services.AddServiceModelServices();
builder.Services.AddServiceModelMetadata();
builder.Services.AddSingleton<IServiceBehavior, UseRequestHeadersForMetadataAddressBehavior>();
builder.Services.AddSingleton<IErrorHandler, ExceptionHandlerErrorHandler>(); // these lines
builder.Services.AddSingleton<IServiceBehavior, ExceptionHandlerServiceBehaviour>(); // should be added.

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.UseServiceModel(serviceBuilder =>
{
 serviceBuilder.AddService<InvoiceService>()
 .AddServiceEndpoint<InvoiceService, IInvoiceService>(
 new BasicHttpBinding(), "/Services/InvoiceService.svc"
 );

 var serviceMetadataBehavior = app.Services.GetRequiredService<ServiceMetadataBehavior>();
 serviceMetadataBehavior.HttpGetEnabled = true;
});

app.Run();

The Happy Ending

By Step 3, we have achieved something remarkable:

The Integrator is happy because they are still sending SOAP requests to /Services/InvoiceService.svc. They didn’t have to change their integration pattern.
The Developer is happy because the InvoiceService is clean. It uses MediatR. It doesn’t have try/catch blocks cluttering the business logic. It relies on [Authorize] for security.
The Operations Team is happy because the logs show consistent ProblemDetails structures regardless of whether the request came from a REST client or a SOAP client.

We didn’t just “port” the code; we modernized the ecosystem around it, leaving the WCF interface as a compatibility layer rather than a shackle.

gRPC in .NET Microservices: Comparison with REST

Wed, 08 Oct 2025 00:00:00 +0300

When .NET microservices need to communcate synchronously with each other, two main options usually come up: REST API and gRPC API.

REST works with JSON over the HTTP/1.1 protocol; it’s easy to read, supported by all browsers, and simple to debug. However, compared to gRPC, REST API payloads are larger, and each request opens its own TCP connection. gRPC, on the other hand, compresses data transmission with Protocol Buffers and carries all traffic over a single HTTP/2 connection, minimizing latency. In this post, we’ll look at how both REST and gRPC work, compare them with examples on .NET 9, and examine which solution is more advantageous in which scenarios. Let’s get started.

What is this RPC?

If you’ve been developing in the .NET ecosystem for a long time, this is probably not your first encounter with the concept of RPC. In the .NET Framework days, service-to-service communication was also done using SOAP-based WCF services running on IIS. However, with that framework you could end up wrestling with XML-based messages and staying locked into the .NET ecosystem.

Instead, gRPC—which runs over HTTP/2 and can operate much more efficiently, cross-platform, and cross-language—has become the most sensible RPC framework to choose for new projects.

Differences between REST and gRPC

In a microservices architecture, RPC is not the only option for service-to-service communication. The REST API approach also enables services to communicate easily and widely with each other. However, there are notable differences between REST and gRPC in both architectural design and technical implementation. Let’s examine these differences under design philosophy and technical differences.

1. Design Philosophy

REST and gRPC take different perspectives in API design. In REST, the main approach is to see everything as a resource and operate on those resources. HTTP methods (GET, POST, PUT, DELETE) represent the operation being performed, while the URL indicates the resource being acted upon. For example, /api/books is a books resource. If you have an endpoint like this, you can more or less guess the operations you can do on it:

GET /api/books returns the list of books,
POST /api/books adds a new book.

In gRPC, the perspective is more action/method oriented. Each operation is defined like a function call. In gRPC, you directly specify which operation you want to perform and you don’t stick to URL design or HTTP methods.

For example,

BookService.GetBooks() lists the books,
BookService.CreateBook() adds a new book.

While it’s technically possible to define action-style endpoints in REST, this generally doesn’t align with best practices or the standard REST philosophy.

2. Technical Differences

REST and gRPC differ across many technical areas—from transport to data format, connection management to error handling. Below are the key topics and differences summarized:

Transport Layer

REST uses HTTP/1.1. A separate TCP/TLS connection is established for each REST API request. Especially at high request volumes, this can lead to performance bottlenecks such as head-of-line blocking (one slow request affects the others). Also, in cases requiring continuous bidirectional communication (e.g., live data streams or real-time notifications), you need additional protocols such as WebSocket or Server-Sent Events. In other words, REST is fundamentally based on the request-response model and does not have native streaming support.

gRPC works with the modern HTTP/2 protocol. Thanks to HTTP/2’s multiplexing feature, many concurrent requests and responses can be carried over a single TCP connection. This provides high performance and low latency. With HTTP/2’s native streaming and header compression, gRPC makes real-time and bidirectional communication much easier and more efficient.

gRPC typically defines service interfaces and message structures with Protocol Buffers (Protobuf). The service definition explicitly specifies the remotely callable methods and message schemas.

Here’s an example:

service HelloService {
 rpc SayHello (HelloRequest) returns (HelloResponse);
}

message HelloRequest {
 string greeting = 1;
}

message HelloResponse {
 string reply = 1;
}

gRPC supports four different communication (RPC) patterns:

Unary

The classic pattern: the client sends one request, the server returns one response. Similar to REST’s request-response model. It can be defined as follows.

rpc SayHello(HelloRequest) returns (HelloResponse);

Server Streaming

The client sends a single request, and the server can return a stream of multiple response messages. The client reads the server’s data stream one by one.

rpc LotsOfReplies(HelloRequest) returns (stream HelloResponse);

Client Streaming

The client sends multiple messages (a stream) to the server. After sending all messages, it receives a single response from the server. Useful for large uploads or batch updates.

rpc LotsOfGreetings(stream HelloRequest) returns (HelloResponse);

Bidirectional Streaming RPC

Both client and server can independently send data streams to each other at the same time. The streams operate independently; ordering is preserved within each stream. Suitable for real-time chat applications or live data transfer.

rpc BidiHello(stream HelloRequest) returns (stream HelloResponse);

Data

REST: Messages are typically carried in human-readable JSON format. JSON is readable and flexible, but results in larger payload sizes and higher parsing cost. A strict schema is not required. Documentation is often added via OpenAPI/Swagger, but you can run into type mismatches at runtime.
gRPC: Uses a binary and compressed format called Protocol Buffers (Protobuf). Protobuf messages are small and fast, reducing network and CPU cost. All data types and methods are defined in a .proto file. Server and client code is generated automatically, providing strong type safety.

Performance and Efficiency

REST: Due to JSON’s larger size and the limitations of HTTP/1.1, latency and resource consumption increase under high traffic.
gRPC: Thanks to small packet sizes and multiple requests over a single connection via HTTP/2, it provides lower latency, higher RPS (requests per second), and more efficient network usage.

Browser and Platform Compatibility

REST: Can be called directly from the browser and easily integrated with fetch/AJAX.
gRPC: Cannot be used directly from the browser; it requires extra layers such as gRPC-Web or JSON Transcoding, so it’s not preferred in scenarios that include the browser.

Which scenarios call for REST or gRPC?

When choosing between REST and gRPC, looking only at technical details may not be sufficient; business needs, target users, and integration requirements are at least as important as performance. Here are some typical scenarios and suggestions:

When should you use REST?

Browser or third-party integration: If your API will be consumed directly by web browsers or external applications, REST provides a more common and accessible solution.
Public APIs: Thanks to JSON’s readability and the widespread support for HTTP/1.1, REST-based APIs are easy for developers to test and document.
Simple CRUD operations: For resource-oriented operations (e.g., products, orders) and classic GET/POST/PUT/DELETE flows, REST is simple and clear.
Caching/Proxy needs: If you need to do caching or routing via CDN or reverse proxy, REST is more advantageous because it aligns fully with the HTTP standard.

When should you use gRPC?

Microservice-to-microservice communication: For high-volume, low-latency service-to-service traffic within the same infrastructure, gRPC provides serious advantages.
Mobile and IoT devices: The binary format and small message sizes reduce data consumption.
Real-time streaming requirements: For applications like chat, live scores, or notifications where server-to-client or bidirectional streaming is needed, gRPC offers native streaming support.
Language independence: If you want strongly typed communication across multiple programming languages, Protobuf makes compatibility easy.
Stronger type safety: With compiled contracts and code generation, the error rate in API consumption drops.

Comprehensive .NET example: Books service

Let’s build a book management service using both REST and gRPC. In this example, we’ll also see the different streaming modes gRPC offers.

Project setup

First, add the required packages:

dotnet new web -n BookService
cd BookService
dotnet add package Grpc.AspNetCore
dotnet add package Grpc.AspNetCore.Server.Reflection
dotnet add package Grpc.Tools

REST API implementation

// Models/Book.cs
namespace BookService.Models;

public class Book
{
 public int Id { get; set; }
 public string Title { get; set; } = string.Empty;
 public string Author { get; set; } = string.Empty;
 public int Year { get; set; }
 public decimal Price { get; set; }
}

// Controllers/BooksController.cs
using Microsoft.AspNetCore.Mvc;
using BookService.Models;

namespace BookService.Controllers;

[ApiController]
[Route("api/books")]
public class BooksController : ControllerBase
{
 private static readonly List<Book> Books = Book.GenerateBooks();

 [HttpGet]
 public IActionResult GetBooks()
 {
 return Ok(Books);
 }

 [HttpGet("{id}")]
 public IActionResult GetBook(int id)
 {
 var book = Books.FirstOrDefault(b => b.Id == id);
 if (book == null)
 return NotFound();

 return Ok(book);
 }

 [HttpPost]
 public IActionResult CreateBook([FromBody] Book book)
 {
 book.Id = Books.Max(b => b.Id) + 1;
 Books.Add(book);
 return CreatedAtAction(nameof(GetBook), new { id = book.Id }, book);
 }
}

gRPC service — Protobuf definitions

// Protos/books.proto
syntax = "proto3";

option csharp_namespace = "BookService.Grpc";

package books;

// Main service definition
service BookService {
 // Unary RPC - Get all books
 rpc GetBooks (GetBooksRequest) returns (BookList);

 // Server Streaming - Stream books one by one
 rpc StreamBooks (StreamBooksRequest) returns (stream Book);

 // Client Streaming - Bulk add books
 rpc AddBooksStream (stream Book) returns (AddBooksResponse);

 // Bidirectional Streaming - Real-time book search
 rpc SearchBooksStream (stream SearchRequest) returns (stream Book);
}

message Book {
 int32 id = 1;
 string title = 2;
 string author = 3;
 int32 year = 4;
 double price = 5;
}

message GetBooksRequest {
 // Empty request message
}

message BookList {
 repeated Book books = 1;
}

message StreamBooksRequest {
 int32 delay_ms = 1; // Delay between each book (ms)
}

message AddBooksResponse {
 int32 count = 1;
 string message = 2;
}

message SearchRequest {
 string query = 1;
}

gRPC service — Implementation

// Services/GrpcBookService.cs
using Grpc.Core;
using BookService.Grpc;

namespace BookService.Services;

public class GrpcBookService : Grpc.BookService.BookServiceBase
{
 private static readonly List<BookService.Grpc.Book> Books = BookService.Models.Book.GenerateBooks()
 .Select(b => new BookService.Grpc.Book { Id = b.Id, Title = b.Title, Author = b.Author, Year = b.Year, Price = (double)b.Price })
 .ToList();

 // Unary RPC - Classic request-response
 public override Task<BookList> GetBooks(GetBooksRequest request, ServerCallContext context)
 {
 var response = new BookList();
 response.Books.AddRange(Books);

 return Task.FromResult(response);
 }

 // Server Streaming - Server streams books one by one
 public override async Task StreamBooks(StreamBooksRequest request,
 IServerStreamWriter<BookService.Grpc.Book> responseStream,
 ServerCallContext context)
 {
 foreach (var book in Books)
 {
 // Cancellation check
 if (context.CancellationToken.IsCancellationRequested)
 {
 break;
 }

 await responseStream.WriteAsync(book);

 // Wait for the specified duration (to demonstrate streaming)
 if (request.DelayMs > 0)
 {
 await Task.Delay(request.DelayMs);
 }
 }
 }

 // Client Streaming - Client sends multiple books
 public override async Task<AddBooksResponse> AddBooksStream(
 IAsyncStreamReader<BookService.Grpc.Book> requestStream,
 ServerCallContext context)
 {
 int count = 0;
 int maxId = Books.Any() ? Books.Max(b => b.Id) : 0;

 await foreach (var book in requestStream.ReadAllAsync())
 {
 book.Id = ++maxId;
 Books.Add(book);
 count++;
 }

 return new AddBooksResponse
 {
 Count = count,
 Message = $"Successfully added {count} books"
 };
 }

 // Bidirectional Streaming - Real-time two-way search
 public override async Task SearchBooksStream(
 IAsyncStreamReader<SearchRequest> requestStream,
 IServerStreamWriter<BookService.Grpc.Book> responseStream,
 ServerCallContext context)
 {
 await foreach (var searchRequest in requestStream.ReadAllAsync())
 {
 var results = Books.Where(b =>
 b.Title.Contains(searchRequest.Query, StringComparison.OrdinalIgnoreCase) ||
 b.Author.Contains(searchRequest.Query, StringComparison.OrdinalIgnoreCase)
 ).ToList();

 foreach (var book in results)
 {
 await responseStream.WriteAsync(book);
 }
 }
 }
}

Program.cs configuration

// Program.cs
using BookService.Services;

var builder = WebApplication.CreateBuilder(args);

// REST API services
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// gRPC services
builder.Services.AddGrpc();

var app = builder.Build();

// Swagger (for REST)
if (app.Environment.IsDevelopment())
{
 app.UseSwagger();
 app.UseSwaggerUI();

 // gRPC reflection (for development)
 app.MapGrpcReflectionService();
}

// REST endpoints
app.MapControllers();

// gRPC endpoints
app.MapGrpcService<GrpcBookService>();

app.Run();

.csproj file

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

 <PropertyGroup>
 <TargetFramework>net9.0</TargetFramework>
 <Nullable>enable</Nullable>
 <ImplicitUsings>enable</ImplicitUsings>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="Grpc.AspNetCore" Version="2.60.0" />
 <PackageReference Include="Grpc.AspNetCore.Server.Reflection" Version="2.60.0" />
 <PackageReference Include="Grpc.Tools" Version="2.60.0">
 <PrivateAssets>all</PrivateAssets>
 <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 </PackageReference>
 <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
 </ItemGroup>

 <ItemGroup>
 <Protobuf Include="Protos\\books.proto" />
 </ItemGroup>

</Project>

Also, if your locally running app won’t run over HTTPS, you need to open a separate port for HTTP/2 apart from the HTTP/1 port. To do this, add the following definition in appsettings.json to open the relevant ports:

 "Kestrel": {
 "Endpoints": {
 "Http": {
 "Protocols": "Http1",
 "Url": "http://*:5000"
 },
 "gRPC": {
 "Protocols": "Http2",
 "Url": "http://*:5001"
 }
 }
 },

gRPC client examples

Now let’s look at client examples using different streaming modes:

// Client/GrpcClientExamples.cs
using Grpc.Net.Client;
using BookService.Grpc;

namespace BookService.Client;

public class GrpcClientExamples
{
 private readonly GrpcChannel _channel;
 private readonly Grpc.BookService.BookServiceClient _client;

 public GrpcClientExamples(string serverAddress = "http://localhost:5001")
 {
 _channel = GrpcChannel .ForAddress(serverAddress, new GrpcChannelOptions
 {
 // Disable HTTPS validation. Use carefully in production.
 HttpHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
 }
 });
 _client = new Grpc.BookService.BookServiceClient(_channel);
 }

 // Unary RPC example
 public async Task UnaryCallExample()
 {
 Console.WriteLine("=== Unary Call Example ===");
 var request = new GetBooksRequest();
 var response = await _client.GetBooksAsync(request);

 Console.WriteLine($"Received {response.Books.Count} books:");
 foreach (var book in response.Books)
 {
 Console.WriteLine($"- {book.Title} by {book.Author} ({book.Year})");
 }
 }

 // Server streaming example
 public async Task ServerStreamingExample()
 {
 Console.WriteLine("\\n=== Server Streaming Example ===");
 var request = new StreamBooksRequest { DelayMs = 500 };

 using var call = _client.StreamBooks(request);

 await foreach (var book in call.ResponseStream.ReadAllAsync())
 {
 Console.WriteLine($"Received: {book.Title} - ${book.Price}");
 }

 Console.WriteLine("Streaming completed");
 }

 // Client streaming example
 public async Task ClientStreamingExample()
 {
 Console.WriteLine("\\n=== Client Streaming Example ===");

 using var call = _client.AddBooksStream();

 var booksToAdd = new[]
 {
 new Book { Title = "Design Patterns", Author = "Gang of Four", Year = 1994, Price = 59.99 },
 new Book { Title = "Head First Design Patterns", Author = "Eric Freeman", Year = 2004, Price = 44.99 },
 new Book { Title = "Microservices Patterns", Author = "Chris Richardson", Year = 2018, Price = 49.99 }
 };

 foreach (var book in booksToAdd)
 {
 await call.RequestStream.WriteAsync(book);
 Console.WriteLine($"Sent: {book.Title}");
 await Task.Delay(300); // Simulated delay
 }

 await call.RequestStream.CompleteAsync();
 var response = await call;

 Console.WriteLine($"Result: {response.Message}");
 }

 // Bidirectional streaming example
 public async Task BidirectionalStreamingExample()
 {
 Console.WriteLine("\\n=== Bidirectional Streaming Example ===");

 using var call = _client.SearchBooksStream();

 // Read results in the background
 var readTask = Task.Run(async () =>
 {
 await foreach (var book in call.ResponseStream.ReadAllAsync())
 {
 Console.WriteLine($"Found: {book.Title} by {book.Author}");
 }
 });

 // Send search queries
 var queries = new[] { "Clean", "Design", "Refactoring", "Domain" };

 foreach (var query in queries)
 {
 Console.WriteLine($"Searching for: {query}");
 await call.RequestStream.WriteAsync(new SearchRequest { Query = query });
 await Task.Delay(1000); // Wait after each search
 }

 await call.RequestStream.CompleteAsync();
 await readTask;

 Console.WriteLine("Bidirectional streaming completed");
 }

 public async ValueTask DisposeAsync()
 {
 await _channel.ShutdownAsync();
 _channel.Dispose();
 }
}

// Usage example
public class Program
{
 public static async Task Main(string[] args)
 {
 await using var client = new GrpcClientExamples();

 await client.UnaryCallExample();
 await client.ServerStreamingExample();
 await client.ClientStreamingExample();
 await client.BidirectionalStreamingExample();
 }
}

Testing with grpcurl

grpcurl is a curl-like command-line tool for gRPC services. Let’s test our service:

Installing grpcurl

# macOS (Homebrew)
brew install grpcurl

# Linux
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# Windows (Chocolatey)
choco install grpcurl

grpcurl usage examples

# 1. What services exist on the server? (Requires reflection)
grpcurl -plaintext localhost:5001 list

# Output:
# books.BookService
# grpc.reflection.v1alpha.ServerReflection

# 2. List the methods of BookService
grpcurl -plaintext localhost:5001 list books.BookService

# Output:
# books.BookService.AddBooksStream
# books.BookService.GetBooks
# books.BookService.SearchBooksStream
# books.BookService.StreamBooks

# 3. Unary RPC call - Get all books
grpcurl -plaintext localhost:5001 books.BookService/GetBooks

# Output:
# {
# "books": [
# {
# "id": 1,
# "title": "Dune",
# "author": "Frank Herbert",
# "year": 1965,
# "price": 29.99
# },
# ...
# ]
# }

Performance comparison: REST vs gRPC benchmark

It’s nice to see the theoretical advantages, but let’s run a comprehensive benchmark to measure the real performance difference. Using BenchmarkDotNet, we’ll compare REST and gRPC across different scenarios.

Benchmark setup

// BookService.Benchmark/BookServiceBenchmark.cs
using BenchmarkDotNet.Attributes;
using Grpc.Net.Client;
using BookService.Grpc;
using System.Net.Http.Json;

namespace BookService.Benchmark;

[MemoryDiagnoser]
[SimpleJob(warmupCount: 3, iterationCount: 10)]
public class BookServiceBenchmark
{
 private HttpClient? _httpClient;
 private GrpcChannel? _grpcChannel;
 private Grpc.BookService.BookServiceClient? _grpcClient;

 private const string RestUrl = "http://localhost:5000";
 private const string GrpcUrl = "http://localhost:5001";

 [GlobalSetup]
 public void Setup()
 {
 // REST client setup
 _httpClient = new HttpClient { BaseAddress = new Uri(RestUrl) };

 // gRPC client setup - with HTTP/2 optimizations
 _grpcChannel = GrpcChannel.ForAddress(GrpcUrl, new GrpcChannelOptions
 {
 MaxReceiveMessageSize = 4 * 1024 * 1024, // 4MB
 MaxSendMessageSize = 4 * 1024 * 1024, // 4MB
 });
 _grpcClient = new Grpc.BookService.BookServiceClient(_grpcChannel);
 }

 [Benchmark(Baseline = true)]
 public async Task<int> REST_GetAllBooks()
 {
 var books = await _httpClient!.GetFromJsonAsync<List<BookDto>>("/api/books");
 return books?.Count ?? 0;
 }

 [Benchmark]
 public async Task<int> gRPC_GetAllBooks()
 {
 var response = await _grpcClient!.GetBooksAsync(new GetBooksRequest());
 return response.Books.Count;
 }

 [Benchmark]
 public async Task<int> REST_GetAllBooks_10Times()
 {
 int totalCount = 0;
 for (int i = 0; i < 10; i++)
 {
 var books = await _httpClient!.GetFromJsonAsync<List<BookDto>>("/api/books");
 totalCount += books?.Count ?? 0;
 }
 return totalCount;
 }

 [Benchmark]
 public async Task<int> gRPC_GetAllBooks_10Times()
 {
 int totalCount = 0;
 for (int i = 0; i < 10; i++)
 {
 var response = await _grpcClient!.GetBooksAsync(new GetBooksRequest());
 totalCount += response.Books.Count;
 }
 return totalCount;
 }

 [GlobalCleanup]
 public async Task Cleanup()
 {
 _httpClient?.Dispose();
 if (_grpcChannel != null)
 {
 await _grpcChannel.ShutdownAsync();
 _grpcChannel.Dispose();
 }
 }
}

Benchmark results

Actual performance results obtained after optimizations:

Method	Mean	Error	StdDev	Ratio	RatioSD	Allocated	Alloc Ratio
REST_GetAllBooks	332.3 μs	42.42 μs	28.06 μs	1.00	0.00	22.91 KB	1.00
gRPC_GetAllBooks	296.9 μs	18.10 μs	10.77 μs	0.90	0.06	25.66 KB	1.12
REST_GetAllBooks_10Times	3,257.1 μs	364.16 μs	240.87 μs	9.85	0.99	227.61 KB	9.94
gRPC_GetAllBooks_10Times	2,883.9 μs	338.63 μs	223.99 μs	8.74	1.05	255.17 KB	11.14

Analysis of the results

For single-request performance, gRPC runs about 10% faster than REST (296.9 μs vs 332.3 μs). This advantage stems from Protocol Buffers’ binary serialization format compared to JSON. In multiple-request scenarios, gRPC’s performance advantage becomes more pronounced, rising to about 11.5% (2,883.9 μs vs 3,257.1 μs). This increase can be explained by HTTP/2’s connection reuse.

In terms of memory usage, gRPC consumes about 12% more memory compared to REST (25.66 KB vs 22.91 KB). This extra memory usage is due to the overhead required for HTTP/2 connection management. However, given the performance improvements, this memory increase can be considered an acceptable trade-off.

Summary

This article compares REST and gRPC for synchronous inter-service communication in the .NET 9 ecosystem across architectural approach, technical underpinnings, and performance. REST, with JSON over HTTP/1.1, offers easy accessibility, browser compatibility, and caching/proxy advantages; gRPC provides lower latency and stronger type safety thanks to HTTP/2’s multiplexing and native streaming capabilities plus Protobuf. The post includes both a REST controller and a gRPC service (unary, server/client/bidirectional streaming) in the same “Books” domain, along with grpcurl test steps. BenchmarkDotNet results show that gRPC is roughly 10% faster on single calls and around 11% faster on consecutive calls than REST, at the cost of a small increase in memory usage.

If you’d like access to the source code, you can find the entire project on my GitHub:

GitHub - berkslv/lecture-grpc

Conclusion

Thanks for reading! 🎉 To keep up with my research in software development, follow @berkslv.

Enforce Code Quality in .NET: .editorconfig & Analyzers & Pre-Commit Hooks

Thu, 24 Jul 2025 00:00:00 +0300

I believe that maintaining and improving code quality is a responsibility we owe both to ourselves and to our teammates with every line of code we write. However, in practice, we sometimes overlook best practices due to hastily written code or tight deadlines. Additionally, we often face challenges when trying to spread these practices across our teams.

To overcome such problems and to make code quality a requirement, rather than something left to individual developer discretion, I’d like to share a multi-step approach, proven by experience in a project with 20+ developers and 10+ services.

First, we’ll use the TreatWarningsAsErrors flag to prevent the project from being released to production with 1000+ warnings.

Then, with .editorconfig files, the conventions that .NET provides by default (e.g., property naming conventions) will become not just a guideline, but a rule applied across the team.

We’ll further strengthen these rules using packages like SonarAnalyzer and Roslynator, allowing us to resolve issues before even running sonar scans, leading to more performant and secure code.

Finally, with a pre-commit hook, we’ll catch unbuildable projects and failing tests before they even reach CI/CD pipelines, allowing us to see and fix these issues before committing. Let’s get started.

Warning-Free Project with TreatWarningsAsErrors

When developing a project with .NET, the most common warning is “Possible null reference.” Of course, there can be many other warnings in our project. If we ignore them, it’s only natural to encounter NullReferenceExceptions everywhere at runtime.

To resolve such errors before they even surface, we can treat warnings as errors and prevent the project from building if they exist. To do this, simply add the following flag to your .csproj file:

<PropertyGroup>
 <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
 <!-- Only if absolutely necessary -->
 <WarningsNotAsErrors>CS0108;NU1901;NU1902;NU1903;NU1904;NU1701</WarningsNotAsErrors>
</PropertyGroup>

However, since this flag treats all warnings from the .NET platform as errors, some warnings, like those from Nuget packages that you can’t resolve yourself, can become a real headache. To address such issues, you can use the WarningsNotAsErrors flag, but only for errors you truly cannot fix.

Set Project Rules with .editorconfig

EditorConfig helps developers working on the same project maintain consistent coding styles across different IDEs. It’s not exclusive to .NET projects, it’s language-agnostic and includes both general and language-specific rules.

With this, you can set project-level rules such as classes following PascalCase, variables using camelCase, and constants in LOWER_CASE all based on .NET’s standard guidelines.

In addition, using SonarAnalyzer, you can catch problematic code like name == "" (a disaster in code!) before it ever reaches a sonar scan, and get an instant suggestion (e.g., use string.IsNullOrEmpty(name)) with Alt+Enter in Visual Studio. This way, your code will enter the CI/CD sonar scan step with far fewer issues.

Another great code analyzer library, Roslynator, lets you enforce more specific rules in your project, like requiring a blank line between class properties, which boosts code readability.

Instead of adding these third-party analyzer packages to each project individually, you can create a Directory.Build.Props file in your repo’s root directory with the following content. This will automatically include the packages in all projects during the build step:

<Project>
 <ItemGroup>
 <PackageReference
 Include="Roslynator.Analyzers"
 Version="4.12.4"
 PrivateAssets="all"
 Condition="$(MSBuildProjectExtension) == '.csproj'"
 />
 <PackageReference
 Include="Roslynator.Formatting.Analyzers"
 Version="4.12.4"
 PrivateAssets="all"
 Condition="$(MSBuildProjectExtension) == '.csproj'"
 />
 <PackageReference
 Include="SonarAnalyzer.CSharp"
 Version="9.32.0.97167"
 PrivateAssets="all"
 Condition="$(MSBuildProjectExtension) == '.csproj'"
 />
 </ItemGroup>
</Project>

Here’s a sample .editorconfig file. The rules defined by the IDE are standard .NET rules; those starting with rcs come from Roslynator; those starting with S are Sonar rules. These rules can be defined as suggestion, warning, or error, and can be customized for each project.

# top-most EditorConfig file
root = true

# Don't use tabs for indentation.
[*]
indent_style = space
# (Please don't specify an indent_size here; that has too many unintended consequences.)
spelling_exclusion_path = SpellingExclusions.dic

# Code files
[*.{cs,csx,vb,vbx}]
indent_size = 4
insert_final_newline = true
charset = utf-8-bom

# XML project files
[*.{csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj}]
indent_size = 2

# XML config files
[*.{props,targets,ruleset,config,nuspec,resx,vsixmanifest,vsct}]
indent_size = 2

# JSON files
[*.json]
indent_size = 2

# Powershell files
[*.ps1]
indent_size = 2

# Shell script files
[*.sh]
end_of_line = lf
indent_size = 2

# Dotnet code style settings:
[*.{cs,vb}]

# Sort using and Import directives with System.* appearing first
dotnet_sort_system_directives_first = true
dotnet_separate_import_directive_groups = false

# IDE0005: Remove unnecessary using directives
dotnet_diagnostic.IDE0005.severity = warning

# IDE0010: Add missing cases to switch statement
dotnet_diagnostic.IDE0010.severity = warning

# Add blank line after using directive list
dotnet_diagnostic.rcs0003.severity = error

# Place new line after/before '?:' operator
dotnet_diagnostic.rcs0028.severity = error

# Track uses of "TODO" tags
dotnet_diagnostic.S1135.severity = suggestion

Finally, with these practices, we can make our code more consistent and readable by getting a suggestion like the one below.

csharp_prefer_braces = true:suggestion

// Good:
if (isActive)
{
 DoSomething();
}

// Bad:
if (isActive)
 DoSomething();

You can also find references to .editorconfig in GitHub’s well-starred repos, such as dotnet/roslyn and christianhelle/refitter.

Catch Issues Locally with pre-commit Hooks

Pre-commit hooks are scripts that Git runs before every commit. They’re great for checks like code formatting, linting, or running tests, and they prevent problematic code from being committed. Blocking commits that fail tests can be annoying in the short term, but it’s crucial for keeping your tests reliable in the long run. If you have a test step in your CI/CD pipeline, this lets you see and fix issues locally before they ever reach that step.

In .NET projects, you can set up these pre-commit hooks with helper packages, or you can ask every developer to run git config core.hooksPath ./.git-hooks manually. Here, we’ll leverage .NET’s built-in capabilities without relying on extra packages.

Add a simple MSBuild target like the one below to your .csproj file. This ensures that your Git hook directory is set up during every dotnet restore (and thus build) step, so anyone working on your project gets the pre-commit hook set up automatically. We skip this step in Production to avoid unnecessary installs in CI/CD or production environments.

<Target Name="register git hooks" BeforeTargets="Restore;CollectPackageReferences" Condition="'$(ASPNETCORE_ENVIRONMENT)' != 'Production'">
 <Exec Command="git config core.hooksPath ./.git-hooks" StandardOutputImportance="Low" StandardErrorImportance="High" />
</Target>

Create a folder called .git-hooks in your project’s root directory. Inside, create a file named pre-commit:

./git-hooks/pre-commit

#!/bin/sh
echo Running tests...
dotnet format
dotnet test

Don’t forget to make your file executable:

chmod +x .git-hooks/pre-commit

With this setup, you won’t be able to commit if your tests fail:

$ git commit -m 'failed commit'
Running tests...
 Determining projects to restore...
 All projects are up-to-date for restore.
 Committer.API -> C:\Projects\Personal\lecture-net-pre-commit\src\Committer.API\bin\Debug\net9.0\Committer.API.dll
 Committer.Tests -> C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\bin\Debug\net9.0\Committer.Tests.dll
Test run for C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\bin\Debug\net9.0\Committer.Tests.dll (.NETCoreApp,Version=v9.0)
VSTest version 17.14.0 (x64)

Starting test execution, please wait...
A total of 1 test files matched the specified pattern.
[xUnit.net 00:00:00.14] Committer.Tests.Services.CalculatorServiceTests.Add_ShouldReturnCorrectSum(a: 5, b: 3, expected: 7) [FAIL]
 Failed Committer.Tests.Services.CalculatorServiceTests.Add_ShouldReturnCorrectSum(a: 5, b: 3, expected: 7) [1 ms]
 Error Message:
 Assert.Equal() Failure: Values differ
Expected: 7
Actual: 8
 Stack Trace:
 at Committer.Tests.Services.CalculatorServiceTests.Add_ShouldReturnCorrectSum(Double a, Double b, Double expected) in C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\Services\CalculatorServiceTests.cs:line 25
 at InvokeStub_CalculatorServiceTests.Add_ShouldReturnCorrectSum(Object, Span`1)
 at System.Reflection.MethodBaseInvoker.InvokeWithFewArgs(Object obj, BindingFlags invokeAttr, Binder binder, Object[] parameters, CultureInfo culture)

Failed! - Failed: 1, Passed: 18, Skipped: 0, Total: 19, Duration: 39 ms - Committer.Tests.dll (net9.0)

$ git log --oneline
9a89b16 (HEAD -> main, origin/main) test commit
10367df README.md added
0051724 Inital commit

If your tests pass, the commit will go through:

$ git commit -m 'succeded commit'
Running tests...
 Determining projects to restore...
 All projects are up-to-date for restore.
 Committer.API -> C:\Projects\Personal\lecture-net-pre-commit\src\Committer.API\bin\Debug\net9.0\Committer.API.dll
 Committer.Tests -> C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\bin\Debug\net9.0\Committer.Tests.dll
Test run for C:\Projects\Personal\lecture-net-pre-commit\tests\Committer.Tests\bin\Debug\net9.0\Committer.Tests.dll (.NETCoreApp,Version=v9.0)
VSTest version 17.14.0 (x64)

Starting test execution, please wait...
A total of 1 test files matched the specified pattern.

Passed! - Failed: 0, Passed: 19, Skipped: 0, Total: 19, Duration: 31 ms - Committer.Tests.dll (net9.0)
[main 0d9f3cf] succeded commit
 1 file changed, 1 insertion(+), 1 deletion(-)

$ git log --oneline
0d9f3cf (HEAD -> main) succeded commit
9a89b16 (origin/main) test commit
10367df README.md added
0051724 Inital commit

Summary

In summary, we’ve looked at practices for making code quality a team-wide requirement in .NET projects, rather than leaving it to individual developer initiative. With TreatWarningsAsErrors, .editorconfig rules, and advanced analyzer packages, we increased both the readability and security of our code. Pre-commit hooks allowed us to block problematic or failing code from ever entering the repo. With these approaches, we established a sustainable, high-quality software development culture within the team.

If you’d like access to the source code, you can find the full project on my GitHub:

github.com/berkslv/lecture-net-pre-commit

Conclusion

Thank you for reading! 🎉 To stay updated with my research in software development, you can follow me at @berkslv.

Feature Flagging in .NET with OpenFeature and flagd

Tue, 08 Jul 2025 00:00:00 +0300

Feature flagging has become a cornerstone of modern software delivery. If you’re deploying frequently, testing features with specific users, want safer releases, or need targeted rollouts, feature flags should be in your toolbox. In this post, I’ll introduce OpenFeature, a vendor-neutral feature flag standard, and show you how to integrate it in a .NET project with flagd as your backend.

What is Feature Flagging?

Feature flags (a.k.a. feature toggles) let you turn features on or off at runtime, without deploying new code. You can even segment by user, environment, or any attribute you want to serve a feature. This unlocks:

Progressive delivery (gradual rollouts)
A/B testing and experimentation
Instant kill switches for broken features
Reduced risk during deployments

But the core value? Control. Suddenly, you can ship code that’s dark-launched, only visible to your team, or tested by a handful of beta users. If a problem occurs, you don’t scramble for a rollback; you just flip a flag.

The Old Way: Environment Variables

Before I dive into OpenFeature and flagd, I want to share a bit of real-world pain. Like many teams, I started with environment variables (appsettings.json configs) to manage features. Maybe you recognize this pattern:


{
 "EnableNewDashboard": true
}

Then, inside your code:


if (Configuration["EnableNewDashboard"] == "true")
{
 // Show the shiny new dashboard
}

It works—until it doesn’t. Here’s what usually goes wrong:

No targeting: It’s all or nothing. Want to enable it just for internal users? Too bad.
No runtime change: Changing an ENV variable often means redeploying or restarting.
Growth of config sprawl: You end up with a dozen flags, all mixed in with unrelated config.
No auditing or history: Who changed what, and when?
No standardization: Every app/team does it differently.

As teams scale, this approach becomes brittle. Progressive delivery, canary releases, and A/B tests all need dynamic control. This is the gap where feature flag platforms—and standards like OpenFeature—shine.

Why OpenFeature?

Most feature flag solutions (LaunchDarkly, Unleash, etc.) lock you into their SDKs and APIs. That’s where OpenFeature comes in:

Vendor agnostic: Switch providers without rewriting your code.
Standardized API: Use the same approach across languages and stacks.
Extensible: Add hooks for logging, telemetry, and more.
Cloud-native ready: Built for modern architectures.

With OpenFeature, your app code only depends on the OpenFeature SDK—not on a specific vendor or backend. If you ever outgrow your current provider or want to migrate to a managed service, it’s as simple as swapping the provider.

Why flagd?

flagd is an open-source, lightweight feature flag backend. It’s designed to work out-of-the-box with OpenFeature and can serve flags from files, HTTP endpoints, or via gRPC to any application you need. But unfortunately there is no official UI to flagd right now, instead of the UI, flags managed with GitOps practices. flagd is ideal if you want a self-hosted, cloud-native flag backend with zero vendor lock-in.

Real-life Example: From ENV to Feature Flags

Let’s say you’re running a .NET web API. You’re launching a new feature, but want to enable it only for internal users before rolling it out to everyone. Rather than creating an environment variable and binding that to some variable like isInternalUser, which needs re-deploying your code for every change, you want to change features in runtime, for specific segments you like.

In a feature flag system that managed with the environment variable, if the Product Manager wants to A/B test a feature with 10% of the users, custom code and redeployment will be required.

Feature flags flip this model:

Toggle the feature for specific users/groups instantly.
Roll out to everyone when ready—no deployment needed.
If something breaks, instantly turn it off.

This is how modern product teams iterate quickly, reduce risk, and deliver value continuously.

Integrating OpenFeature and flagd in .NET

Let’s see how to wire this up.

1. Add NuGet Packages


dotnet add package OpenFeature
dotnet add package OpenFeature.Contrib.Providers.Flagd

2. Run flagd with docker-compose


services:
 flagd:
 image: ghcr.io/open-feature/flagd:latest
 volumes:
 - ./flags:/etc/flagd
 command: [
 'start',
 '--uri',
 'file:/etc/flagd/flags.json',
 '--debug'
 ]
 ports:
 - '8013:8013'

Sample flags.json:


{
 "$schema": "https://flagd.dev/schema/v0/flags.json",
 "flags": {
 "new-greeting": {
 "state": "ENABLED",
 "variants": {
 "on": true,
 "off": false
 },
 "defaultVariant": "off",
 "targeting": {
 "if": [
 {
 "$ref": "userAgentIsFirefox"
 },
 "on",
 null
 ]
 }
 }
 },
 "$evaluators": {
 "userAgentIsFirefox": {
 "in": [
 "firefox",
 {
 "var": [
 "userAgent"
 ]
 }
 ]
 }
 }
}

3. Configure OpenFeature in Your .NET App


using OpenFeature.Contrib.Providers.Flagd;
using OpenFeature.Model;

var builder = WebApplication.CreateBuilder(args);

await OpenFeature.Api.Instance.SetProviderAsync(new FlagdProvider(new Uri("http://localhost:8013")));

var app = builder.Build();

app.MapGet("/greet", async context =>
{
 var client = OpenFeature.Api.Instance.GetClient();
 // Get User-Agent header
 var userAgent = context.Request.Headers["User-Agent"].FirstOrDefault() ?? "";
 var evalContext = EvaluationContext.Builder().Set("userAgent", userAgent).Build();

 var useNewGreeting = await client.GetBooleanValueAsync("new-greeting", false, evalContext);

 string greeting = useNewGreeting
 ? "Hey there! Welcome to the new greeting experience! 🎉"
 : "Hello, World!";

 await context.Response.WriteAsync(greeting);
});

app.Run();

4. Test

Change the flag in your flags.json file. Your .NET application will instantly detect the change. When we test the API endpoint, we’ll see results like the following:


$ curl http://localhost:5050/greet
Hello, World!

$ curl http://localhost:5050/greet -H 'User-Agent: firefox'
Hey there! Welcome to the new greeting experience! 🎉

If you want to send a direct request to the flagd backend and see the status of the flag, you can query it as shown below:


$ curl -X POST "http://localhost:8013/flagd.evaluation.v1.Service/ResolveBoolean" -d '{"flagKey":"new-greeting","context":{}}' -H "Content-Type: application/json"
{"value":false, "reason":"DEFAULT", "variant":"off", "metadata":{}}

$ curl -X POST "http://localhost:8013/flagd.evaluation.v1.Service/ResolveBoolean" -d '{"flagKey":"new-greeting","context":{"userAgent": "firefox"}}' -H "Content-Type: application/json"
{"value":true, "reason":"TARGETING_MATCH", "variant":"on", "metadata":{}}

Summary

Feature flags reduce risk, enable faster delivery, and improve user targeting. OpenFeature gives you a standardized, future-proof API for flag management in .NET. flagd is a solid, open-source backend, great for self-hosting and Kubernetes.

If you’re still managing features with environment variables or configuration files, give OpenFeature and flagd a shot. Your future self will thank you, especially the next time you need to shut off a feature on Friday at 5pm.

If you want to access the source code, you can find the whole project on my GitHub account:

https://github.com/berkslv/lecture-net-openfeature

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

Real-Time Communication with SignalR: A Deep Dive

Fri, 29 Nov 2024 00:00:00 +0300

In today’s world where data is moving very quickly, real-time communication is a must for modern applications to give users smooth experiences. SignalR is an essential library when you want to create .NET application that communicates in real-time with others. When using SignalR, all communication and network requirements are abstracted by the library and you only need to call the method like in the RPC. By leveraging SignalR, you can easily create live dashboards, chat applications, or simple notification features that many web applications need. Let’s get started.

Why SignalR?

Traditional models of client-server communication revolve around the request-response model, which is considered less efficient and limited for high interaction needs, and requires the client to making a request when data is needed. SignalR is designed to eliminate these challenges by keeping the same connection alive from the client to the server.

Key Advantages of SignalR:

Real-Time Communication: Clients receive the updates as soon as possible without necessarily making new requests.
Cross-Platform Support: SignalR now has a full range of functionality independent of any platform and browsers.
Abstraction of Complex Protocols: SignalR has the ability to use WebSocket, Server-Sent Events and Long Polling protocols, which provide a better relationship between the client and the server and allow them to choose the most efficient protocol. If the WebSocket protocol is not available by the client, SignalR tries to use other methods by selecting them according to its internal algorithm. (https://learn.microsoft.com/en-us/aspnet/signalr/overview/getting-started/introduction-to-signalr#transport-selection-process)
Integration with .NET apps: Effective incorporation of .NET successfully guarantees the smooth through incorporation to modern .NET applications.

Getting Started with SignalR

To implement SignalR in your .NET project, you can follow these steps:

1. SignalR NuGet Package

SignalR comes with .NET system libraries therefore you don’t need to install any additional packages. However if Visual Studio goes crazy you may want to try install the Microsoft.AspNetCore.SignalR package.

2. Create a Hub Class

The Hub acts as the central component that manages connections and sends messages to clients. You can compare this class to Controllers where you accept HTTP requests, except here we can accept requests or make a request directly to the client. Here’s a simple example, clients invoke SendNotification(string content) method to make a call to server and server send a message to all or specific clients with Clients.All.SendAsync("ReceiveNotification", content) method:


using Microsoft.AspNetCore.SignalR;

public class NotificationsHub : Hub
{
 public async Task SendNotification(string content)
 {
 await Clients.All.SendAsync("ReceiveNotification", content);
 }
}

3. Configure the Hub in `Program.cs`

Just register SignalR services and map the hub endpoint as follows:


var builder = WebApplication.CreateBuilder(args);

//...

builder.Services.AddSignalR();

var app = builder.Build();

//...

app.MapHub<NotificationsHub>("hubs/notification");

app.Run();

4. SignalR Client

SignalR supports various client platforms, including Javascript, .NET, and Java. If you don’t want to implement SignalR library in that platforms, you can simply use Postman to test your endpoint. But you must insert 0x1E character at the end of the json. This is a requirement of the SignalR internal protocol. If you use Javascript library to implement SignalR you don’t need to deal with this kind of details.


{
 "protocol": "json",
 "version": 1
}

After specifying the protocol, you can send and receive message from SignalR Hub as follows:


{
 "arguments" : ["hello world"],
 "target" : "SendNotification",
 "type" : 1
}

Here is a quick demo:

SignalR and Postman demo

Advanced Features

1. Strongly Typed Hubs

For better maintainability, use strongly typed hubs to specify interface of the hub:


public interface INotificationsClient
{
 Task ReceiveNotification(string content);
}

public class NotificationsHub : Hub<INotificationsClient>
{
 public async Task SendNotification(string content)
 {
 await Clients.All.ReceiveNotification(content);
 }
}

2. Targeting Specific Clients

SignalR enables sending messages to specific users or groups. You can use this feature to send notification to only related ones, just add user to group using their userId or groupName, then send a notification to this userId:


await Clients.User(userId).ReceiveNotification("Hello, User!");
await Clients.Group(groupName).ReceiveNotification("Hello, Group!");

If you want to target specific clients with SignalR using userId, you have to implement IUserIdProvider that coming from SignalR package like that:


public class UserIdProvider : IUserIdProvider
{
 public string GetUserId(HubConnectionContext connection)
 {
 return connection.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
 }
}


// Program.cs
services.AddSingleton<IUserIdProvider, CustomUserIdProvider>();

3. Using `IHubContext` to access the hub from outside the hub

You can send message to clients in outside of the hub as follows. Just Inject the IHubContext of type, and send a message to them.

You can trigger the hub when some event is occured in your system with this greate feature. For example, when a long running batch job is completed you can notify your users about the result.

Just a quick note, your code can be much cleaner if you abstract this IHubContext interface with another interface like INotificationDispatcher


public class NotificationDispatcher(IHubContext<NotificationsHub> hubContext) : INotificationDispatcher
{
 public async Task SendNotification(string content)
 {
 await hubContext.Clients.All.SendAsync("ReceiveNotification", content);
 }

 public async Task SendNotificationToUser(string userId, string content)
 {
 await hubContext.Clients.User(userId).SendAsync("ReceiveNotification", content);
 }

 public async Task SendNotificationToGroup(string groupName, string content)
 {
 await hubContext.Clients.Group(groupName).SendAsync("ReceiveNotification", content);
 }
}

4. Securing SignalR

By default, SignalR hubs can be accessed by any client. To restrict access, use the classic [Authorize] attribute. Ensure that users authenticate using mechanisms like JWT, which SignalR leverages to identify connected users:


[Authorize]
public class NotificationsHub : Hub
{
 // Hub methods
}

5. Scaling SignalR with Redis backplane

Scaling SignalR across multiple servers ensures reliable real-time communication for high-demand applications that running in multiple instances. A Redis backplane synchronizes messages between SignalR servers, ensuring clients connected to different servers receive messages seamlessly. Here is a quote from microsoft docs:

The SignalR Redis backplane uses the pub/sub feature to forward messages to other servers. When a client makes a connection, the connection information is passed to the backplane. When a server wants to send a message to all clients, it sends to the backplane. The backplane knows all connected clients and which servers they’re on. It sends the message to all clients via their respective servers.


dotnet add package Microsoft.AspNetCore.SignalR.StackExchangeRedis


// Program.cs

builder.Services.AddSignalR()
 .AddStackExchangeRedis("localhost:6379", options =>
 {
 options.Configuration.ChannelPrefix = "SignalR";
 });

If you don’t belive me, you can try to run your signalr app in more than one instance in the local testing enviroment with docker compose:


services:
 signalr:
 image: your-app
 ports:
 - "5000:5000"
 depends_on:
 - redis
 redis:
 image: redis:latest
 ports:
 - "6379:6379"


docker-compose up --scale signalr=3

SignalR Communication Models

SignalR abstracts multiple transport methods to ensure compatibility and performance:

WebSocket (`webSockets`):

WebSockets is the most efficient and preferred transport for real-time, bi-directional communication in SignalR. It establishes a persistent, full-duplex connection over a single TCP channel, allowing simultaneous message exchange between the client and server. This makes it ideal for applications that require low-latency, high-throughput interactions, such as live chats, collaborative editing tools, online gaming, and financial tickers.

WebSockets transitions to its own lightweight protocol (ws:// or wss://) after an initial HTTP handshake, reducing the overhead associated with traditional HTTP-based communication. However, scaling WebSockets requires specialized infrastructure, such as WebSocket-aware load balancers and sticky sessions, to maintain connection affinity. SignalR simplifies these complexities, managing connection persistence, automatic reconnections, and fallback to alternative protocols when WebSockets are unavailable.

Server-Sent Events (`serverSentEvents`):

SSE provides a lightweight, HTTP-based mechanism for one-way communication, where the server streams real-time updates to the client over a long-lived connection. It uses the standardized EventSource API and transmits data formatted as text/event-stream. This makes SSE simple to implement and efficient for use cases like live dashboards, notifications, and news feeds, where only server-to-client communication is needed.

Because it operates over standard HTTP, SSE integrates easily with existing HTTP infrastructure and does not require specialized proxies or load balancers, making it easier to scale compared to WebSockets. However, it lacks support for Internet Explorer and does not natively allow client-to-server communication, which must be handled through separate HTTP requests. SignalR automatically leverages SSE when WebSockets is unavailable, providing a seamless fallback for environments with restricted capabilities.

Long Polling (`longPolling`):

Long Polling emulates real-time communication by continuously opening and closing HTTP connections. The client sends a request to the server and keeps it open until the server has data to send. Once the data is delivered, the client immediately establishes a new request. This approach minimizes latency between updates and creates the appearance of a push-based connection.

While Long Polling works with all browsers and is easy to implement, it incurs more overhead due to frequent HTTP requests and responses. It is less efficient compared to persistent connections like WebSockets or SSE, especially for high-frequency updates. In SignalR, Long Polling serves as a fallback when neither WebSockets nor SSE is supported, ensuring compatibility across legacy systems and restricted environments.

Forever Frame (`foreverFrame`):

Forever Frame is a legacy protocol specific to older versions of Internet Explorer, designed to enable real-time, one-way communication. It operates by embedding a hidden iframe in the client’s browser that maintains an open connection to the server. The server continuously streams executable scripts to the iframe, which are executed by the client to process incoming data.

While functional for its time, Forever Frame has significant limitations, including high overhead and lack of bi-directional communication. Any client-to-server interaction requires separate standard HTTP requests, making it less efficient and cumbersome to implement. SignalR includes Forever Frame for backward compatibility but uses it only as a last-resort fallback in environments restricted to legacy Internet Explorer browsers.

Websockets vs Server-Sent Events

WebSockets and Server-Sent Events (SSE) cater to different real-time communication needs. WebSockets enable full-duplex, low-latency communication, ideal for chat, gaming, and collaborative tools. In contrast, SSE provides lightweight, one-way updates, perfect for live dashboards or notifications.

WebSockets use a custom protocol (ws:// or wss://) for efficient two-way messaging but require WebSocket-aware infrastructure for scaling. SSE operates over standard HTTP (text/event-stream), making it easier to scale with traditional HTTP tools, though it only supports server-to-client communication and lacks Internet Explorer support.

SignalR abstracts these differences, automatically prioritizing WebSockets for performance and falling back to SSE or other methods to ensure seamless real-time functionality across varied environments.

Specifiying the protocol

SignalR allows you to explicitly specify the transport protocol to be used for real-time communication. By default, SignalR automatically selects the best available transport with its internal algorithm, but you can customize this behavior based on your application’s needs.

You can choose WebSockets for its efficiency and fall back to Long Polling when WebSockets are unavailable with that code in Program.cs:


app.MapHub<NotificationsHub>("/hubs/notification", opt =>
{
 opt.Transports = HttpTransportType.WebSockets | HttpTransportType.LongPolling;
});

Or in the client side with JavaScript:


let connection = new signalR.HubConnectionBuilder()
 .withUrl("/hubs/notification", {
 transport: signalR.HttpTransportType.WebSockets
 | signalR.HttpTransportType.LongPolling })
 .build();

Summary

SignalR makes adding real-time features to .NET applications simple and efficient. It abstracts complex networking protocols, letting you focus on building live dashboards, chat apps, or notifications without worrying about the underlying transport. With support for WebSockets, Server-Sent Events (SSE), and Long Polling, SignalR automatically picks the best protocol for your environment.

If you want to access the source code, you can find the whole project on my GitHub account:

GitHub - berkslv/lecture-signalr-deep-dive

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

Event-Driven Architecture: Do you need other service’s data in microservice architecture

Sat, 07 Sep 2024 00:00:00 +0300

In applications developed with microservice architecture, domains are generally tried to be strictly separated from each other. In the example we will examine, all logic and data related to the product are located in the product service, while the organization service that manages the sales consultants who can create orders with this product also hosts its own logic and data.

However, the createUnit() request we will make to create a sales consultant in the organization service will need the data of the product service for validation reasons. Shouldn’t the unit be given the permission to create a product that doesn’t exist? In this case, the organization service will need the data of the product service, which is not in its domain and is not under its responsibility.

We can access this data either synchronously or asynchronously. First, we’ll look at accessing it synchronously and the problems we may encounter, then we’ll address the potential issues with using the asynchronous method. Let’s begin.

Synchronous communication

With the request we will send to our organization service via REST, we will trigger the createUnit() method and create a unit. However, since this service will need product data for validation purposes, it will need to retrieve this data synchronously through an HTTP REST getProduct() request.

During runtime, for the createUnit() method to be processed, both the organization service and the product service need to be up and accessible, and there must be no issues with the network connection between them. If the product service is not operational, the organization service will also not function. Even when both services are up and accessible, if the product service is slow, the synchronous request flow will be blocked, causing the organization service to slow down as well. To overcome this issue, the organization service will need to scale during periods of high demand. However, since the product service has a runtime dependency, it will also need to be scaled in the same way to handle the large number of requests coming from the organization. If we apply this practice to all services, all services will need to scale together. As a result, the organization service will be highly dependent on the product service, and they will have to continue operating together rather than independently. If all the services in our microservice architecture become dependent on each other in this way, the inaccessibility of a single service could lead to all other services becoming inaccessible as well.

During design time, if a change is made to the getProduct() API in the product service, the developers of the organization service would also need to update their HTTP client integrations accordingly. This change would likely require modifying the organization service’s codebase as well.

In conclusion, since coupling will occur both at runtime and design time, the two services will be tightly coupled, leading to what Jonathan Tower calls a distributed monolith. Any change in one service will directly affect the other, making it difficult to quickly respond to constantly changing business requirements. Any improvements made to the getProduct() method in the product service would also need to be implemented by the other services that consume it. After completing these updates, all services connected synchronously must be accessible for end-users to use the application.

Synchronous communication

In a scenario where we want to guarantee an SLA to our customer, if we optimistically offer a 99.5% uptime guarantee for both the product and organization services, we are accepting that there could be up to 43 hours of downtime annually. In a scenario where the product and organization services are dependent on each other during runtime, using the calculation $0.995 * 0.995 = 0.990$, the dependency created by synchronous communication results in our services offering twice the downtime guarantee, potentially leading to 87 hours of downtime annually.

	Product	Organization	Product & Organization
Uptime percentage	99.5	99.5	99.0
Month	716	716	712
Downtime in month	4	4	7
Year	8716	8716	8672
Downtime in year	43	43	87

So, how do we avoid this method, which can cause so many headaches? Let’s look at another solution for communication between services.

Asynchronous communication

If we don’t want to choose synchronous communication, which increases inter-service dependency in every possible direction, we can proceed with the alternative: asynchronous communication. By reversing the arrows with this method, the product service publishes a domain event called ProductCreatedEvent whenever there is an update in the product table. All services listening to this event update their own local products tables.

When the organization service needs product data, it reads from its own products table. This table is unaffected by the organization’s workflows and is only read from. This way, in the createUnit() method, we query the product data from the same database where we save the unit data.

Asynchronous communication

With this method, we access the product data from the organization’s database in the createUnit() flow, eliminating runtime dependency on the product service.

By eliminating runtime dependency, we stop making synchronous queries to the product service’s getProduct() endpoint. At design time, the dependency we faced while developing is also removed. After making a change in the getProduct() method of the product service, the team managing the organization service no longer needs to make any changes.

During design time, we only have an asynchronous dependency, and we only need to make changes when necessary. If a new column is added to the product domain model, it can be added directly to the event as a new field. If a column is removed from the product table, it can be sent with default values without being removed from the event type and marked as obsolete. Services can respond to these added or removed columns as needed or continue without making any changes.

The product service does not need to care about who is processing the published event. Anyone who needs this data can consume the event, maintain their own copy of the product data, and carry on their work without having to synchronize communication with the product service. This leads to more scalable and accessible applications since they can now operate independently without depending on other services.

If we worry that our tables will mix domains, we can keep tables from different domains in a separate database schema as shown in the example below.

Asynchronous communication 2

Eventual consistency

The biggest issue that may arise from this method is eventual consistency. The update of the relevant table in the organization service may not reflect at the exact same moment a product is added to the product service. Depending on the availability of the message broker, there could be a delay of a few milliseconds or seconds.

We can also explain this situation with CAP theory. If we keep the Partition tolerance leg, which is one of the 3 legs of CAP theory, constant, one of the Consistency and Availability legs will increase while the other will decrease. Therefore, we will not be able to provide these three options at the same time. Here, we need to decide according to the workflow we are working with.

For example, in an e-commerce system, the “add to cart” feature might need to be highly available. If the “add to cart” feature isn’t working, receiving an error message like “please try again later” might cause customers to switch to a competitor’s site. However, if we see 2 instead of 1 of the same item in our cart, we can simply adjust our cart and continue the payment process.

However, the same approach may not work for hotel reservations. In contrast to the cart example, consistency is probably more critical. Returning an error message like “please try again later” is much more logical than renting out the same room to multiple customers.

In conclusion, synchronous communication is suitable for workflows that need immediate consistency, while asynchronous communication is better for workflows that require high availability. Typically, in microservice architecture, high availability is preferred, as synchronous communication tightly couples all services together.

High availability vs Immediate consistency

Edge cases in asynchronous communication

If you have decided to proceed with event-driven architecture in the communication between your services, you will need to do something to ensure data consistency in the system. If a create request comes to one of our services and we publish CreatedEvent, we first update the database and then publish the event, if the transaction we execute in the database results in an error, and we publish the event without following it, or if the transaction we execute in the database results in success but the event bus cannot be accessed afterwards, the data that is distributed in our applications may fall into an inconsistent state. In order to prevent this situation, while the product service updates the product data in its own database, it also adds the relevant event to the outbox table in the same database, and then a different thread continuously scans this table and publishes the new events. Since the record we make to the database will be processed atomically, it is guaranteed that the event data will be created in the outbox table while the product data is being created. However, in an application that works as multiple instances, situations such as an event reading from the same outbox table twice and publishing it twice may be encountered. In this case, the idempotency problem already arises.

If the result of a method being called once is the same as the result of multiple calls, then this is an idempotent method. In order to prevent an event from being processed multiple times due to different reasons and thus disrupting data consistency in the system, we will need to save the unique message id values of the events to the database after they are consumed, and continue processing if the message id value is not in the database when a new event is to be consumed. Chris Richardson (microservices.io) also touches on this issue in his article Pattern: Idempotent Consumer.

Without Outbox & Idempotency

Outbox & Idempotency

As a result, as with most solutions to problems in the field of Computer Science, we do not have a silver bullet. After considering the advantages and disadvantages of both methods in detail and in the domain we are working in, we can continue with the method we want. However, my suggestion would be to eliminate the dependency between services by using asynchronous communication whenever possible.

You can access the .NET project I developed to simulate situations that may occur while working with asynchronous and synchronous data communication from the github repo below. In the example, the infrastructure provided by MassTransit was used for the outbox structure, and no special development was made for this feature.

GitHub - berkslv/lecture-fetch-other-service-data-with-event-driven-architecture

Resources

Don’t Build a Distributed Monolith - Jonathan “J.” Tower - NDC London 2023

The Many Meanings of Event-Driven Architecture • Martin Fowler • GOTO 2017

Solving distributed data problems in a microservice architecture | Microservices.io

You Keep Using That Word • Sam Newman • GOTO 2023

Microservices Pattern: Pattern: Idempotent Consumer

The Reactive Manifesto

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

CorrelationId Tracing in .NET Microservices with HTTP and MassTransit

Sun, 14 Jul 2024 00:00:00 +0300

CorrelationId has a very important place under the title of Distributed Tracing in order to be able to trace the ongoing process during the communication between applications running distributed in the microservice architecture and to understand which steps came to this point if there is a performance-related or flow problem in a service.

CorrelationId must be carried throughout the entire lifecycle of a request, ensuring the correlation between different services. In this article, we will examine how to navigate the CorrelationId value using HTTP and RabbitMQ requests in a .NET based microservice architecture. This solution was designed to be a clear answer to our problem, but it is open to any comments and improvements, if you have a better solution in mind, please contact me.

Big picture

We will manipulate the CorrelationId value between services by manipulating the header values by intervening in incoming and outgoing requests with Middleware and Filter structures during communication between services using HTTP and MassTransit. During this travel between services, we will use the LogContext class provided by Serilog to log the contexts initiated by incoming requests with the given CorrelationId value. You can access all examples from the repo below.

GitHub - berkslv/lecture-correlation-id-microservices

We can use our Correlation class, which we could define as Scoped, to send the CorrelationId value we receive in incoming requests to our service in outgoing requests. However, in this way, our state value, which we move between classes with Dependency Injection methods, becomes inaccessible in a special case in our request that proceeds asynchronously: Since our CorrelationHeaderHandler class, which will intervene in the requests we make with the HttpClient using the DelegatingHandler class, will work in a separate DI scope from our application, the value of our Correlation class, which we could define as Scoped, becomes inaccessible in a this special case. This issue is also explained in Microsoft’s own documentation as follows:

When IHttpClientFactory creates a new delegating handler, it uses DI to fulfill the handler’s constructor parameters. IHttpClientFactory creates a separate DI scope for each handler, which can lead to surprising behavior when a handler consumes a scoped service.

As a solution to this problem, we will create a class called AsyncStorage and use the AsyncLocal class provided by Microsoft to create a structure that we can access at any time within the same thread in our async request to set the CorrelationId value:


namespace Order.API.Filters.Correlation;

/// <summary>
/// Stores and retrieves values in an async context.
/// </summary>
/// <typeparam name="T">What should be stored</typeparam>
public static class AsyncStorage<T> where T : new()
{
 private static readonly AsyncLocal<T> _asyncLocal = new AsyncLocal<T>();

 public static T Store(T val)
 {
 _asyncLocal.Value = val;
 return _asyncLocal.Value;
 }

 public static T? Retrieve()
 {
 return _asyncLocal.Value;
 }
}

We will define the Correlation class, which we will provide as a type to the AsyncStorage class, as shown below. The Id property will contain the CorrelationId value.


namespace Order.API.Filters.Correlation;

/// <summary>
/// It holds the CorrelationId value that comes with HTTP requests and events handled via MassTransit.
/// </summary>
public class Correlation
{
 public Guid Id { get; init; }
}

Since we are storing the CorrelationId value in a location that is accessible throughout the request, let’s now intercept incoming requests and extract the CorrelationId value from the headers. In microservice architecture, applications communicate between services not only via HTTP but also through event-based methods. However, in such initiated requests, we will carry the CorrelationId value in the headers provided by MassTransit, not in the HTTP headers.

Filters for CorrelationId

CorrelationMiddleware

We define our CorrelationMiddleware class, which will intercept incoming HTTP requests and get the value from the CorrelationId HTTP header, as follows. If there is a value in the header, we first enrich it by putting this value as a separate field in the LogContext class provided by Serilog. Then, we store the CorrelationId value by giving the Correlation class to our AsyncStorage class. In this way, we will be able to get the CorrelationId value in incoming requests and use this value in outgoing requests.


namespace Order.API.Filters.Correlation;

/// <summary>
/// When the Http request is made, it takes the CorrelationId value from the HttpContext Header and sets the Correlation.Id value.
/// </summary>
public class CorrelationMiddleware
{
 private readonly RequestDelegate _next;

 public CorrelationMiddleware(RequestDelegate next)
 {
 _next = next;
 }

 public async Task InvokeAsync(HttpContext context, Correlation correlation)
 {
 var correlationIdHeader = context.Request.Headers["CorrelationId"];

 if (!string.IsNullOrWhiteSpace(correlationIdHeader))
 {
 var correlationId = Guid.Parse(correlationIdHeader.ToString());

 LogContext.PushProperty("CorrelationId", new ScalarValue(correlationId));

 AsyncStorage<Correlation>.Store(new Correlation
 {
 Id = correlationId
 });
 }

 await _next(context);
 }
}

To add this middleware to our application, we edit Program.cs as follows.


var builder = WebApplication.CreateBuilder(args);

//...

var app = builder.Build();

app.UseMiddleware<CorrelationMiddleware>();

//...

app.Run();

CorrelationConsumeFilter

If the request coming to our service is not HTTP, but a request triggered by an event, there will not be an HTTP header. For this reason, we define our CorrelationConsumeFilter class as follows to get the CorrelationId value from the header values provided by MassTransit. In this class, before consuming the classes signed with IConsumer, we intercept the incoming events and get the CorrelationId value and add it to LogContext and AsyncStorage<Correlation>.


namespace Order.API.Filters.Correlation;

/// <summary>
/// It is triggered when there is an event consumed by MassTransit and sets the CorrelationId value to the Correlation class.
/// </summary>
public class CorrelationConsumeFilter<T> : IFilter<ConsumeContext<T>> where T : class
{
 public Task Send(ConsumeContext<T> context, IPipe<ConsumeContext<T>> next)
 {
 var correlationIdHeader = context.CorrelationId;

 if (correlationIdHeader.HasValue)
 {
 var correlationId = correlationIdHeader.Value;

 LogContext.PushProperty("CorrelationId", new ScalarValue(correlationId));

 AsyncStorage<Correlation>.Store(new Correlation
 {
 Id = correlationId
 });
 }

 return next.Send(context);
 }

 public void Probe(ProbeContext context)
 {
 }
}

Let’s examine what we can do to add the Correlation value, which we store in AsyncStorage<Correlation>, to the relevant header fields in the event requests.

CorrelationPublishFilter

We define our CorrelationPublishFilter class, which will intercept events published with MassTransit’s IPublishEndpoint, as follows. This class intercepts published events, retrieves the CorrelationId value from AsyncStorage<Correlation>, and adds it to MassTransit’s CorrelationId header.


namespace Order.API.Filters.Correlation;

/// <summary>
/// Sets the CorrelationId value of events published via MassTransit.
/// </summary>
public class CorrelationPublishFilter<T> : IFilter<PublishContext<T>> where T : class
{

 public Task Send(PublishContext<T> context, IPipe<PublishContext<T>> next)
 {
 var correlation = AsyncStorage<Correlation>.Retrieve();

 if (correlation is not null)
 {
 context.CorrelationId = Guid.Parse(correlation.Id.ToString()!);
 }

 return next.Send(context);
 }

 public void Probe(ProbeContext context)
 {
 }
}

CorrelationSendFilter

If the event sent to MassTransit is not published and is sent using IRequestClient<T> with the request/response pattern, our CorrelationSendFilter class will intervene, not CorrelationPublishFilter. In this class, we intervene in the sent events, get the CorrelationId value from AsyncStorage<Correlation> and add it to the CorrelationId header value of MassTransit.


namespace Order.API.Filters.Correlation;

/// <summary>
/// Sets the CorrelationId value of events sent via MassTransit.
/// </summary>
public class CorrelationSendFilter<T> : IFilter<SendContext<T>> where T : class
{
 public Task Send(SendContext<T> context, IPipe<SendContext<T>> next)
 {
 var correlation = AsyncStorage<Correlation>.Retrieve();

 if (correlation is not null)
 {
 context.CorrelationId = Guid.Parse(correlation.Id.ToString());
 }

 return next.Send(context);
 }

 public void Probe(ProbeContext context)
 {
 }
}

To add our CorrelationConsumeFilter, CorrelationPublishFilter and CorrelationSendFilter classes to our application, we define our ConfigureServices class as follows and use this method in Program.cs.


public static class ConfigureServices
{
 public static WebApplicationBuilder AddMassTransit(this WebApplicationBuilder builder, IConfiguration configuration)
 {
 var messageBroker = builder.Configuration.GetSection("MessageBroker");
 builder.Services.AddMassTransit(cfg =>
 {
 cfg.SetKebabCaseEndpointNameFormatter();

 cfg.AddConsumers(Assembly.GetExecutingAssembly());

 cfg.UsingRabbitMq((context, config) =>
 {
 config.UseSendFilter(typeof(CorrelationSendFilter<>), context);
 config.UsePublishFilter(typeof(CorrelationPublishFilter<>), context);
 config.UseConsumeFilter(typeof(CorrelationConsumeFilter<>), context);

 config.Host(messageBroker["Host"], messageBroker["VirtualHost"], h =>
 {
 h.Username(messageBroker["Username"]!);
 h.Password(messageBroker["Password"]!);
 });

 config.ConfigureEndpoints(context);
 });
 });

 return builder;
 }
}


var builder = WebApplication.CreateBuilder(args);

builder.AddMassTransit(builder.Configuration);

// ...

var app = builder.Build();

// ...

app.Run();

CorrelationHeaderHandler

If the request made from our service is an HTTP request, not an event, we define our CorrelationHeaderHandler class, which will intervene in the requests we make from our HttpClient class, which we will create with IHttpClientFactory, as follows. In this class, we intervene in HTTP requests made from our application, get the CorrelationId value from AsyncStorage<Correlation> and add it as a HTTP header.


/// <summary>
/// Middleware to be used in requests made with HttpClient. Adds the CorrelationId header to the requests made.
/// </summary>
public class CorrelationHeaderHandler : DelegatingHandler
{
 protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
 {
 var correlation = AsyncStorage<Correlation>.Retrieve();

 if (correlation is not null)
 {
 request.Headers.Add("CorrelationId", correlation.Id.ToString());
 }

 return await base.SendAsync(request, cancellationToken);
 }
}

To add this middleware to our application, we define Named Http Client in Progam.cs as follows and add the middleware that will intervene in requests made with AddHttpMessageHandler.


var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTransient<CorrelationHeaderHandler>();

builder.Services.AddHttpClient("Inventory", c =>
 {
 c.BaseAddress = new Uri("http://localhost:5053");
 })
 .AddHttpMessageHandler<CorrelationHeaderHandler>();;

// ...

var app = builder.Build();

// ...

app.Run();

We use the Named Http Client we created as follows. If the requests we make here are not asynchronous, the middleware cannot intervene.


public class InventoryService : IInventoryService
{
 private readonly IHttpClientFactory _httpClientFactory;

 public InventoryService(IHttpClientFactory httpClientFactory)
 {
 _httpClientFactory = httpClientFactory;
 }

 public async Task RemoveStockAsync(string productId, int quantity)
 {
 var httpClient = _httpClientFactory.CreateClient("Inventory");

 var response = await httpClient.PostAsync($"remove-stock/{productId}/{quantity}", null);

 response.EnsureSuccessStatusCode();
 }
}

In this article, we explored how to effectively use CorrelationId to enhance distributed traceability in a .NET microservice architecture using HTTP and RabbitMQ. By leveraging Middleware and Filter structures, we were able to manipulate header values and propagate the CorrelationId across different services, ensuring comprehensive logging and monitoring with Serilog’s LogContext framework.

We demonstrated how to handle CorrelationId in both HTTP requests and event-driven communication facilitated by MassTransit. By implementing CorrelationMiddleware and CorrelationHeaderHandler for HTTP; CorrelationConsumeFilter, CorrelationPublishFilter, and CorrelationSendFilter for event-driven communication. We ensured that the CorrelationId is consistently carried through the entire lifecycle of a request, providing a clear trace of the process flow and helping to identify performance or flow issues.

The use of AsyncStorage<Correlation> with the AsyncLocal class provided a reliable way to store and retrieve the CorrelationId value across different scopes, addressing challenges related to Dependency Injection and asynchronous processing.

I hope this guide helps you implement a robust distributed tracing solution in your own microservice architecture. For more detailed examples, you can check out the complete code repository on GitHub:

GitHub - berkslv/lecture-correlation-id-microservices

Resources

The source I used for the correct use of the AsyncLocal class:

https://medium.com/@mbearz/how-to-log-everything-using-middleware-and-httpclient-handler-42b8f628fe84

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

API Gateway Alternatives from a .NET Developer's Perspective: YARP, Ocelot, Kong, APISIX, and KrakenD

Mon, 20 May 2024 00:00:00 +0300

We can use API Gateway services as an intermediary layer while exposing our services to the outside world in microservice architecture. In this article, we will briefly discuss what an API Gateway is and then talk about .NET, OpenResty, and Go-based API Gateway alternatives along with performance tests.

What is an API Gateway?

An API Gateway provides an entry point to our systems as shown below, isolating them from the outside world. It solves common issues such as authorization, logging, and rate limiting with a single service that would otherwise need to be implemented repeatedly in each sub-service.

They can apply transformations to URLs, body information, and even protocols while routing requests. For example, an HTTP request can be transmitted to sub-services using the gRPC protocol for better performance. They can use flat files or databases to find the addresses of the services they will route incoming requests to.

What are the alternatives?

When evaluating API Gateway alternatives that we can use in our systems, we need to consider the required customization, performance, suitability for distributed architecture, and the ability to update route information via an admin panel. Unfortunately, there is no single gateway product that meets all these features and solves all our needs at once. We need to make these evaluations based on the specific needs of our system.

First, we will examine the .NET-based YARP and Ocelot API gateway products, which can be customized with C#, then talk about Kong and Apache APISIX, which use the OpenResty (nginx and lua) combination. Finally, we will look at KrakenD, which is frequently used in cloud-native environments and developed with Go. All these options can be used open source for free, but we can get enterprise support for Kong, Apache APISIX, and KrakenD if needed.

Before evaluating our options, I developed a very simple .NET API service that simulates database queries by waiting for 1 second. After putting this service behind the API Gateway, we will try to route requests and perform performance tests using the Apache Benchmark tool. To examine resource consumption more closely, we will run this application with other gateways using docker compose and receive responses from the service at service:8080.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
 app.UseSwagger();
 app.UseSwaggerUI();
}

app.MapGet("/weather", () =>
{
 Task.Delay(1000).Wait();

 return "Weather is OK!";
})
.WithName("GetWeather")
.WithOpenApi();

app.Run();

.NET Based

As .NET developers, we can start by examining the YARP and Ocelot API Gateway products that can be developed with .NET technologies, which usually come to mind first. While these options can compete with other competitors in very simple scenarios in terms of performance, they cannot respond to complex needs such as minimal resource consumption and admin dashboard.

YARP

Microsoft’s YARP (Yet Another Reverse Proxy) stands out as a reverse proxy product and can also be used as an API Gateway. It caught my attention because it is used as an API Gateway in the eShop example microservice projects published by Microsoft on GitHub. YARP provides load balancing support and can route requests to services using algorithms like round robin by obtaining the addresses of these services through service discovery methods. Since it is .NET-based, processes such as authorization, rate limiting, distributed tracing, and logging that can be used in standard .NET API projects can also be easily implemented with familiar methods. Additionally, customizations can be made by adding middleware, and HTTP requests can be converted to gRPC requests.

To create a YARP project, after creating a .NET web API project, you include the Yarp.ReverseProxy package in the application and configure it to start routing requests.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddReverseProxy()
 .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.MapReverseProxy();
app.Run();

// appsettings.json
{
 "ReverseProxy": {
 "Routes": {
 "weather_route": {
 "ClusterId": "weather_api",
 "Match": {
 "Path": "/weather"
 }
 }
 },
 "Clusters": {
 "weather_api": {
 "Destinations": {
 "destination1": {
 "Address": "http://service:8080"
 }
 }
 }
 }
 },
 "Logging": {
 "LogLevel": {
 "Default": "Information",
 "Microsoft.AspNetCore": "Warning"
 }
 },
 "AllowedHosts": "*"
}

Ocelot

Ocelot is an API Gateway solution that shares many common features with YARP. All features that can be used in .NET API projects can also be used here. It is developed as an independent open source project. Unlike YARP, it positions itself directly as an API Gateway product. However, it does not have gRPC support but offers features such as request aggregation, which can be preferred in backend-for-frontend structures.

To create an Ocelot application, similarly, a .NET API project is created and the configurations in the Program.cs file are set up to read service configurations from a separate ocelot.json file instead of appsettings.json. When defining routes with Ocelot, we need to repeatedly provide the service addresses, whereas with YARP, we only need to give the service information in one place and specify it in the router. Request aggregation can be done in the aggregates section after defining routes, and for more complex needs, custom aggregates can be defined using the IDefinedAggregator interface.

// Program.cs
using Ocelot.DependencyInjection;
using Ocelot.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile("ocelot.json", optional: false, reloadOnChange: true);

builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

await app.UseOcelot();
await app.RunAsync();

// ocelot.json
{
 "Routes": [
 {
 "DownstreamPathTemplate": "/weather",
 "DownstreamScheme": "http",
 "DownstreamHostAndPorts": [
 {
 "Host": "service",
 "Port": 8080
 }
 ],
 "UpstreamPathTemplate": "/weather",
 "UpstreamHttpMethod": [ "Get" ]
 }
 ],
 "GlobalConfiguration": {
 "BaseUrl": "https://service:8080"
 }
}

YARP vs Ocelot

As you can see in the comparison table I prepared for YARP and Ocelot technologies, they share most features. Our preference between these two technologies can depend on the supported features, community support, and the structure of the configuration file.

Feature	YARP	Ocelot
Routing & Request mapping	Yes	Yes
Authn & Authz	Yes	Yes
Rate limiting	Yes	Yes
Load balancing	Yes	Yes
gRPC	Yes	No, old packages available
Request aggregation	No, custom development required	Yes, can be done with configuration
Distributed tracing	Yes	Yes

On a Mac M1 with 8GB of RAM, running in a Docker environment with a very simple scenario where there is only one endpoint, I sent 10,000 requests with 50 concurrent channels using the Apache Benchmark tool for our performance tests. Ocelot returned an average response time of 1030 ms, and YARP returned an average response time of 1029 ms, yielding almost the same result. The memory consumption started at 20MB and rose to a maximum of 100MB when requests started coming in, and the CPU usage varied between 10% and 20%. These rates are almost the same for YARP and Ocelot. The commands I used for the tests are as follows:

# YARP
# 100 MB RAM | 10% - 20% CPU

ab -k -n 10000 -c 50 http://localhost:9090/weather

Server Software: Kestrel
Server Hostname: localhost
Server Port: 9090

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 207.561 seconds
Complete requests: 10000
Failed requests: 0
Keep-Alive requests: 0
Total transferred: 1470000 bytes
HTML transferred: 140000 bytes
Requests per second: 48.18 [#/sec] (mean)
Time per request: 1037.804 [ms] (mean)
Time per request: 20.756 [ms] (mean, across all concurrent requests)
Transfer rate: 6.92 [Kbytes/sec] received

Connection Times

 (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.1 0 2
Processing: 1002 1029 122.9 1015 2961
Waiting: 1002 1028 122.9 1015 2961
Total: 1002 1029 123.0 1016 2962

Percentage of the requests served within a certain time (ms)
 50% 1016
 66% 1019
 75% 1021
 80% 1023
 90% 1028
 95% 1033
 98% 1052
 99% 1517
 100% 2962 (longest request)

# Ocelot
# 100 MB RAM | 10% - 20% CPU

ab -k -n 10000 -c 50 http://localhost:9090/weather

Server Software: Kestrel
Server Hostname: localhost
Server Port: 9090

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 207.739 seconds
Complete requests: 10000
Failed requests: 0
Keep-Alive requests: 0
Total transferred: 1470000 bytes
HTML transferred: 140000 bytes
Requests per second: 48.14 [#/sec] (mean)
Time per request: 1038.695 [ms] (mean)
Time per request: 20.774 [ms] (mean, across all concurrent requests)
Transfer rate: 6.91 [Kbytes/sec] received

Connection Times (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.1 0 2
Processing: 1001 1030 120.0 1016 3347
Waiting: 1001 1030 119.9 1016 3347
Total: 1001 1030 120.0 1016 3349

Percentage of the requests served within a certain time (ms)
 50% 1016
 66% 1020
 75% 1023
 80% 1025
 90% 1032
 95% 1040
 98% 1061
 99% 1359
 100% 3349 (longest request)

OpenResty Based

Using nginx, which is known for its high performance, along with LuaJIT provides a flexible development environment with the Lua scripting language and JIT support, which supports hot reload without needing to restart. The Lua language, in many scenarios, offers performance as high as C due to its C API while providing higher-level programming with a more developer-friendly structure. It is possible to call Lua code from C code or vice versa. This results in a nice pair that can be used together. In fact, the C and Lua combination is a stack used in Cloudflare’s own tools and is frequently used in networking applications.

We will talk about two OpenResty-based gateways that are frequently preferred in the industry: Kong, which has made a name for itself, and Apache APISIX, which has succeeded in distinguishing itself with a few nice features. We will continue with Go-based gateways afterwards.

Kong

Kong stands out among API gateway solutions. In addition to containing all the features found in tools like Ocelot and YARP, it offers additional features with over 60 plugin supports. You can also develop your own plugins with Lua or other programming languages. The enterprise version provides extra features such as GraphQL support, request validation, body update, and secret manager.

Kong includes most of the features expected from an API gateway, such as authorization, logging, request transformation, and rate limiting. However, additional development is required for some features, such as the request aggregation pattern (combining the response from multiple services with a single request). While Lua, which can be used natively, works better than other alternatives, we can also develop using Go, JavaScript, or Python with IPC (Inter-Process Communication) support, although with lower performance. Moreover, thanks to WebAssembly support, we can create high-performance plugins with familiar languages like Go and Rust without needing IPC methods.

Unlike .NET-based gateways like Ocelot and YARP, Kong offers different deployment options. With “DB-less” mode, management can be done through configuration files. This mode is very useful in CI/CD-based deployment scenarios and prevents issues that may arise from state differences.

Kong can also be configured using the traditional method by using a database. In this method, databases such as PostgreSQL, Cassandra, Redis, InfluxDB, and Kafka can be used. Route and service information can be modified via the admin API. However, this scenario creates an additional dependency on the database and is more vulnerable to attacks since the control plane and data plane work on the same instance.

By applying the deployment scenario we can use with the Konnect service, we achieve a more secure structure by separating the data plane and control plane parts from each other. Konnect is offered as software as a service by Kong and does not require an additional database dependency for state management.

If we do not want to use a product managed by Kong and want the entire process to be done within our internal network, we can deploy the control plane and database to a different location in our system where they can communicate with each other using the method called Hybrid mode, and use the control plane to control the data plane.

For local development, you can work with PostgreSQL using the Docker Compose file provided by Kong and read from this file at the first run. If you are working in DB-less mode, you need to define all your routes in a configuration file. After defining the configuration as below, we start our gateway with the Docker Compose file.

# a very minimal declarative config file
_format_version: "2.1"
_transform: true

services:
 - name: weather-service
 url: http://host.docker.internal:8080
 routes:
 - name: get-weather
 paths:
 - /weather

# docker-compose.yml
 # ...
 kong:
 image: "${KONG_DOCKER_TAG:-kong:latest}"
 user: "${KONG_USER:-kong}"
 environment:
 <<: *kong-env
 KONG_ADMIN_ACCESS_LOG: /dev/stdout
 KONG_ADMIN_ERROR_LOG: /dev/stderr
 KONG_PROXY_LISTEN: "${KONG_PROXY_LISTEN:-0.0.0.0:8000}"
 KONG_ADMIN_LISTEN: "${KONG_ADMIN_LISTEN:-0.0.0.0:8001}"
 KONG_ADMIN_GUI_LISTEN: "${KONG_ADMIN_GUI_LISTEN:-0.0.0.0:8002}"
 KONG_PROXY_ACCESS_LOG: /dev/stdout
 KONG_PROXY_ERROR_LOG: /dev/stderr
 KONG_PREFIX: ${KONG_PREFIX:-/var/run/kong}
 KONG_DECLARATIVE_CONFIG: "/opt/kong/kong.yaml"
 secrets:
 - kong_postgres_password
 networks:
 - kong-net
 ports:
 # The following two environment variables default to an insecure value (0.0.0.0)
 # according to the CIS Security test.
 - "${KONG_INBOUND_PROXY_LISTEN:-0.0.0.0}:8000:8000/tcp"
 - "${KONG_INBOUND_SSL_PROXY_LISTEN:-0.0.0.0}:8443:8443/tcp"
 # Making them mandatory but undefined, like so would be backwards-breaking:
 # - "${KONG_INBOUND_PROXY_LISTEN?Missing inbound proxy host}:8000:8000/tcp"
 # - "${KONG_INBOUND_SSL_PROXY_LISTEN?Missing inbound proxy ssl host}:8443:8443/tcp"
 # Alternative is deactivating check 5.13 in the security bench, if we consider Kong's own config to be enough security here

 - "127.0.0.1:8001:8001/tcp"
 - "127.0.0.1:8444:8444/tcp"
 - "127.0.0.1:8002:8002/tcp"
 healthcheck:
 test: [ "CMD", "kong", "health" ]
 interval: 10s
 timeout: 10s
 retries: 10
 restart: on-failure:5
 read_only: true
 volumes:
 - kong_prefix_vol:${KONG_PREFIX:-/var/run/kong}
 - kong_tmp_vol:/tmp
 - ./config:/opt/kong
 security_opt:
 - no-new-privileges
 # ...


KONG_DATABASE=postgres docker compose --profile database up -d

After a successful deployment with Kong, requests made to the specified route and service information are routed. If you deploy using the traditional or hybrid mode, you can manage your service and endpoint information via an admin interface.

Apache APISIX

Apache APISIX is a gateway product developed on OpenResty like Kong. However, it stands out by offering features that are only available in the enterprise version of Kong as open source. These features include GraphQL, Canary release, and secret management.

APISIX provides higher performance compared to Kong in systems with a high number of routes. While Kong uses a traversal search algorithm among routes, APISIX performs searches with the radixtree algorithm and provides 140% higher performance when no plugin is used. Additionally, APISIX uses the etcd database to store configurations. This database can run cloud-native and is widely used in Kubernetes environments.

APISIX offers three different deployment scenarios:

Traditional Method: Control plane and data plane are deployed within the same instance dependent on the database.
Decoupled Method: Control plane and data plane are deployed with different instances, and only the control plane is dependent on the database.
Standalone Method: Works by reading from a configuration file without using a database.

In my local tests, I performed the deployment process using the traditional method with the etcd database through Docker Compose. I made minor changes to the Docker Compose file found in the APISIX Docker repository. We can make requests to the Admin API using admin keys. If I were to deploy using the standalone method, I would need to define routes in a yaml file.

If enterprise support is required, it can be obtained through API7, managed by the APISIX development team.

I will share the Docker Compose files and the code I used at the end of the blog post so you can quickly experience it on your own local environment.

In performance tests, APISIX showed better performance than Kong with an average response time of 1025 milliseconds compared to Kong’s 1032 milliseconds. In terms of consumption, Kong consumes around 280MB of memory upon startup, while APISIX uses around 100MB. Both gateways have a CPU consumption rate that varies between 5% and 10%.

# Kong
# 280MB RAM | 5% - 10% CPU
ab -k -n 10000 -c 50 http://localhost:8000/weather

Server Software: Kestrel
Server Hostname: localhost
Server Port: 8000

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 207.499 seconds
Complete requests: 10000
Failed requests: 0
Keep-Alive requests: 0
Total transferred: 2730028 bytes
HTML transferred: 140000 bytes
Requests per second: 48.19 [#/sec] (mean)
Time per request: 1037.494 [ms] (mean)
Time per request: 20.750 [ms] (mean, across all concurrent requests)
Transfer rate: 12.85 [Kbytes/sec] received

Connection Times (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.2 0 4
Processing: 1002 1032 120.5 1018 3369
Waiting: 1002 1031 120.5 1018 3369
Total: 1002 1032 120.7 1019 3373

Percentage of the requests served within a certain time (ms)
 50% 1019
 66% 1023
 75% 1026
 80% 1028
 90% 1034
 95% 1043
 98% 1066
 99% 1326
 100% 3373 (longest request)

# APISIX
# 100MB RAM | 5% - 10% CPU
ab -k -n 10000 -c 50 http://localhost:9080/weather

Server Software: APISIX/3.9.0
Server Hostname: localhost
Server Port: 9090

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 206.130 seconds
Complete requests: 10000
Failed requests: 0
Keep-Alive requests: 0
Total transferred: 1520000 bytes
HTML transferred: 140000 bytes
Requests per second: 48.51 [#/sec] (mean)
Time per request: 1030.650 [ms] (mean)
Time per request: 20.613 [ms] (mean, across all concurrent requests)
Transfer rate: 7.20 [Kbytes/sec] received

Connection Times (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.2 0 7
Processing: 921 1025 126.2 1012 3376
Waiting: 921 1024 126.2 1011 3375
Total: 921 1025 126.3 1012 3378

Percentage of the requests served within a certain time (ms)
 50% 1012
 66% 1015
 75% 1017
 80% 1018
 90% 1023
 95% 1029
 98% 1047
 99% 1327
 100% 3378 (longest request)

Go Based alternatives

As a Go-based API Gateway alternative, we will discuss KrakenD, the most prominent option. However, Tyk or Traefik API Gateway can also be preferred as secondary alternatives with Go, but they are not included in this narrative as I could not try them since they are paid.

KrakenD

KrakenD is an API gateway product developed with Go and has both community and enterprise versions. It runs on the Lura engine, which was donated to the Linux Foundation in 2021. Compared to other API gateway products, it offers a powerful aggregation system. You can perform all aggregation operations using only configuration files without writing any code.

Since KrakenD does not use a database, it does not create confusion when deciding on deployment options. We can perform our operations using only configuration files. However, it does not have an admin panel due to the lack of a database. The absence of a database eliminates additional error sources and provides easier scalability.

All configurations are managed through a configuration file that can be tracked via version control systems such as Git. It supports different file formats like JSON, YAML, and TOML. We can quickly create configurations using the interface on KrakenD’s website. In a local development environment, you can quickly start and make requests to your service, as it only works through the configuration file. With the hot reload feature, you can update the configuration file with a short downtime. However, this method is not recommended for production environments; using GitOps methods to create a new release is advised. The enterprise version includes additional features such as OpenAPI importer and exporter, gzip compression, and response validation.

KrakenD has a much simpler Docker Compose content compared to Kong and APISIX, as it does not have any additional dependencies. You only need to provide the path to the configuration file as a volume. For example, I added the weather service to Docker Compose and quickly started the service by creating the krakend.json file. It gave very good results in the performance test.

{
 "$schema": "https://www.krakend.io/schema/krakend.json",
 "version": 3,
 "name": "KrakenD - API Gateway",
 "timeout": "3000ms",
 "cache_ttl": "300s",
 "output_encoding": "json",
 "port": 9090,
 "endpoints": [
 {
 "endpoint": "/weather",
 "method": "GET",
 "output_encoding": "string",
 "backend": [
 {
 "url_pattern": "/weather",
 "encoding": "string",
 "sd": "static",
 "method": "GET",
 "host": [
 "http://service:8080"
 ],
 "disable_host_sanitize": false
 }
 ]
 }
 ]
}

version: '3'
services:
 krakend:
 image: devopsfaith/krakend
 ports:
 - 9090:9090
 volumes:
 - ./krakend.json:/etc/krakend/krakend.json
 networks:
 - krakend-net

 weather-service:
 container_name: service
 build: ../service/Service.API
 networks:
 - krakend-net
 ports:
 - "8080:8080"

networks:
 krakend-net:
 external: false

As KrakenD’s website also states, it works faster than Kong and APISIX. In similar test results, Kong responds with an average response time of 1032 milliseconds, APISIX with 1025 milliseconds, while KrakenD provides the best performance with 1024 milliseconds. The CPU consumption remains stable between 4% and 6%, with a maximum memory consumption of 30MB. These results show that KrakenD consumes fewer resources while being faster than its competitors.

# KrakenD
# 30MB RAM | 4% - 6% CPU
ab -k -n 10000 -c 50 http://localhost:9090/weather

Server Software:
Server Hostname: localhost
Server Port: 9090

Document Path: /weather
Document Length: 14 bytes

Concurrency Level: 50
Time taken for tests: 206.359 seconds
Complete requests: 10000
Failed requests: 9
 (Connect: 0, Receive: 0, Length: 9, Exceptions: 0)
Non-2xx responses: 9
Keep-Alive requests: 10000
Total transferred: 2439352 bytes
HTML transferred: 139874 bytes
Requests per second: 48.46 [#/sec] (mean)
Time per request: 1031.795 [ms] (mean)
Time per request: 20.636 [ms] (mean, across all concurrent requests)
Transfer rate: 11.54 [Kbytes/sec] received

Connection Times (ms)
 min mean[+/-sd] median max
Connect: 0 0 0.1 0 3
Processing: 1000 1024 122.7 1010 3021
Waiting: 1000 1024 122.7 1010 3021
Total: 1000 1024 122.8 1010 3023

Percentage of the requests served within a certain time (ms)
 50% 1010
 66% 1012
 75% 1013
 80% 1015
 90% 1018
 95% 1023
 98% 1037
 99% 1520
 100% 3023 (longest request)

Conclusion

To compare the five API gateway products we examined, I prepared a table as shown below. This table summarizes the content of the presentation and I would like to emphasize a few important points based on my research.

Kong and APISIX

If different teams are sharing a single API gateway to expose their projects to the internet and a live-updatable admin interface is needed, Kong or APISIX can be preferred. Both gateways have strong features and stand out with their extensible structures. Additionally, with the admin interface, it is possible to manage configurations and make updates live.

KrakenD

If the API gateway project is a shared responsibility among teams and developers can update the configuration file and run the pipeline, KrakenD can be a good choice in cases where high performance and low resource consumption are targeted. KrakenD, developed with Go, offers a powerful aggregation system and is easier to scale due to not using a database.

Ocelot and YARP

If performance and resource consumption are not critical and a familiar technology is sufficient, we can continue with Ocelot or YARP, the .NET-based tools. These tools support similar features in different ways and are easy to integrate into the .NET ecosystem.

Other Criteria

Deployment Methods: The way the gateway is deployed, the structure and editability of the configuration files are important.
Community and Enterprise Support: It is also important to consider how large the user base of the gateway is and whether there are sources of support.

Unfortunately, there is no single product that offers a perfect solution to all our needs. Therefore, we should evaluate our own needs and decide based on the features supported by the tool we choose. Choosing the right API gateway is a critical step for the success of your project and it is always best to choose the one that best meets your needs.

Feature	YARP	Ocelot	Kong	APISIX	KrakenD
Request aggregation	NO	Simple, can be done with configuration	NO	YES	Powerful,, can be done with configuration
OAuth & OpenID	YES	YES	YES	YES	YES
Request validation	Needs custom logic	Needs custom logic	Comes with enterprise	YES	YES
HTTP to gRPC	YES	NO	YES	YES	YES
Websocket	YES	YES	?	YES	Comes with enterprise
State	File	File	File, PostgreSQL, Cassandra, Redis, InfluxDB, Kafka	File, etcd	File
Plugin	C#	C#	Native: Lua & IPC: Go, Javascript, Python & WASM: Go, Rust vs.	Native: Lua & IPC: Go, Javascript, Python & WASM: Go, Rust vs.	Go & Lua
Performance	Mean response: 1029ms, Memory: 100MB, CPU: %10 - %20	Mean response: 1030ms, Memory: 100MB, CPU: %10 - %20	Mean response: 1035ms, Memory: 280MB, CPU: %5 - %10	Mean response: 1025ms, Memory: 100MB CPU: %5 - %10	Mean response: 1024ms, Memory: 30MB, CPU: %4 - %6

If you want to access the source code, you can find the whole project on my GitHub account:

GitHub - berkslv/lecture-api-gateway-comparison

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

How to Use RSA for Encryption in JavaScript and Decryption in .NET

Thu, 07 Mar 2024 00:00:00 +0300

In the digital world, securing communication between different systems is paramount. RSA encryption is an asymmetric encryption algorithm and provides a robust way to achieve this by using a pair of keys: one for encryption and one for decryption. On the other hand, symmetric encryption algorithms, such as AES, use a single key for encryption and decryption. For these reasons, asymmetric encryption algorithms may be preferred in order to use the key publicly and avoid problems even if it falls into the hands of an attacker.

In this blog post I will guide you through implementing RSA key generation with OpenSSL, encryption in JavaScript and decryption in .NET, ensuring secure data exchange between a frontend application and a backend service.

Understanding RSA Encryption

RSA (Rivest-Shamir-Adleman) is one of the first public-key cryptosystems and is widely used for secure data transmission. It involves two keys: a public key, which can be shared openly, for encrypting messages, and a private key, must be kept secret, for decrypting them. The strength of RSA lies in the difficulty of factoring the product of two large prime numbers, which underpins its security.

Generation of Public/Private key pairs with OpenSSL

One of the foundational steps in implementing RSA encryption and decryption is the generation of public and private key pairs. OpenSSL, a robust open-source tool for cryptography, offers a straightforward way to generate these keys. However, this step is optional. .NET libraries successfully generate RSA keys. However, using open source tools like this allows us to be ensure of the standards. This section will guide you through the process of generating an RSA public/private key pair using OpenSSL.

We can start with generation of private key as follows:

$ openssl genrsa -out privatekey.pem 2048

$ cat privatekey.pem
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDuOitcIPd5UpGN
/4GEwNhc4fAmGP6fREJJk/byRgiLiWcyXwdoPwXdXjKSjkSIcETdz/hLAlb6+zNY
Gi4Ap0S5flZSRiKh60xWRA4vZVgsLqhEi2IsclSlWu3R7KD5dkBGsyf5xlCfNSs4
DbYYMgrXXZxXQ0c4qCikpnEB6OpqSzm19Cwrdq9GwophoAPxnf00d7S+y5QpRa+l
Ca70xQ42FxBpMuK76a1g6i+JtmPgTYqXZ0FCMnUEzBq+u3N8LKoNzcSNdrLgvmHQ
oOLFA/9BPe34YgLxoCUi+HhEiLSnvgz/Kn1yprvsz37baYizU/YWFG8s80SPmFsY
JARxvZiJAgMBAAECggEAEboc42Jln+7Lu34NmIAUKZc7fE5EVjwpVZnP2Lfq510+
Y2JsZe64pEAf8cVp5qA6E6pn3scKC2uZZr8t+Kj5xXbX/A/RgGyGte2jA5ZeQQ1o
wo7/q3CHiXVyeHpMATwyLMCkoyLFeY9mi6mDiRniMiP6YAj22gmzWoszIhH/rZCO
NjdpWRsIkFp8jIiyRhhoaBoJtZ1qV3twk8HH590rgjS7QUGJWK9uUsi5SDh69MsR
r/SJ00gTMYFozFd6dB29aKj/p8fSk6qzh2noxU37AuiVc1A2H8Z6SAfRUDSvPkxA
FdqVr62iLWmypBX2VYQ2p1pH1N0v8oG7NTxtrxgRTQKBgQD3YdxKNT0dWZJRGPFC
DIRZVn86UgDAHRw29aToLARnepE5XOrLSmlGMqbK8vzRyUnlctJyG7x5ure2BMp4
gKSLuhz48n7ZvpHyCVnNsqqkc21iM/whL/yKiI11Jz5koXmRDltz9IioQH/PwXvD
RJbjxISHjG5YEKlVmztWtTup/QKBgQD2hqouE8JLePAUzK3SlfgVTlmaHDUeJev4
u95RWPnMNOOwLUWbGYiKBoJ8uc2nSHmxIvEvEPGNwafR6etf0YocpwDfF5pnPDjk
yA4hOdZrCyYa/UDqkB5pHTOZj5iVct1hBNbiANz6kL7Pl+H221U+HxD9rhaDPDez
gdYPhLF4fQKBgQCdi2QomlkufOHS5eiXoLMU1iI2eQzjTGawlaYM+iNf503fU05w
YxZCT3WroC3kSKXYC1T8uK9CcugWclyje4HPPpq+7GhesZ/unYfkmRlVm/EYbnTu
icnyS96Ssohou/FYsOULJrt1M4ZyQA1aoS7bJUclsAiB6zJ8Q1z57ndt3QKBgEwa
9p6S6wBxrWw+Y8sHETdCoNa6rotIGbkIBnIGjddE3KWe1EY1c7lomQ/4LEzgSvEs
YFivWmLwzeY32LoT7hc6V0KH/tqv9MBsIjCPsmoJXxIl7Mx9AWZh5XQaqHg6pa01
2UCcE5wm40EjGlcjDwXGgXBPNhP9mxSHmJXh2QfhAoGANouUrF3qv8ofb1HGrUXx
DO/WkGMzwbkNmwwdgcGYVsGr3Dv/zx1y3TJEvqNh0ViVgmfdYveCo3VrSawq890U
GJZXld2KFE1icEJpNoURkM9okZMzTDIMs+r4vq5Or2jB04mMuoCbG6rjfqUMtkll
oAIFOSKH+F3TrXjNgy4/juo=
-----END PRIVATE KEY-----

After we have successfully created the private key, we can create the public key with the private key we created.

$ openssl rsa -in privatekey.pem -outform PEM -pubout -out publickey.pem

$ cat privatekey.pem
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7jorXCD3eVKRjf+BhMDY
XOHwJhj+n0RCSZP28kYIi4lnMl8HaD8F3V4yko5EiHBE3c/4SwJW+vszWBouAKdE
uX5WUkYioetMVkQOL2VYLC6oRItiLHJUpVrt0eyg+XZARrMn+cZQnzUrOA22GDIK
112cV0NHOKgopKZxAejqaks5tfQsK3avRsKKYaAD8Z39NHe0vsuUKUWvpQmu9MUO
NhcQaTLiu+mtYOovibZj4E2Kl2dBQjJ1BMwavrtzfCyqDc3EjXay4L5h0KDixQP/
QT3t+GIC8aAlIvh4RIi0p74M/yp9cqa77M9+22mIs1P2FhRvLPNEj5hbGCQEcb2Y
iQIDAQAB
-----END PUBLIC KEY-----

Setting Up the Environment for .NET RSA Decryption

For .NET decryption I will use .NET 8 and use the System.Security.Cryptography namespace. We don’t need any other nuget package for RSA decryption. For RSA Decryption I created a Helper class like this.

We read RsaKey from appsettings.json. You should add \n for newlines in RsaKey field. We put this key in appsettings.json because we want to use same keys in every request. But If you leave it to the responsibility of the .NET library, in every startup there will be newly generated key.

// appsettings.json
{
 "Logging": {
 "LogLevel": {
 "Default": "Information",
 "Microsoft.AspNetCore": "Warning"
 }
 },
 "AllowedHosts": "*",
 "RsaKey": "-----BEGIN PRIVATE KEY-----\nMIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCuan+y++Eqc2Vx3QIt9gv0r6rzfcxpsBRubcWCmI+8tqb40oflv5dViPSiCSWNgg5xKk7K8WTeEQQ6NDg1IJ2OwoQ2dfzat5qlpfV9EeF3u8iTY/hyQaaYFwB77cV9t5Czb8oG/+IIOByorJVds9tAoKjssKUZ3W9IU7ffElZjZrbjoiy/H4z8u9fOq8IL9Zf3pHgzv2FxF4BPJamqr4s1VtMqGJ5g18wV1OD9gcz9pJOHHUVieZ0+xP4WD4+1wCv/uwEgIcqmEs0os6birHZL1X/CSqBSPc8e/+kkZyyzoF+MBWPzvAwmW32alIxz2ZV0Z+jJtoOrh/qVqbrGAf+RAgMBAAECggEAEWYu4IJHg0ZZOZtgRwj7RtjKXzluraFi3GRHdoB1IFCBRiOsamMrO91qeAqdDCmL+saLbyvXEd8VMqA4djZPeWkWqt8ozwHPY9RzMZuZyCm7t9Zad71sWtI6mmJNF/46qWfOudWHbSX51+rFiMAzMFaGm3wAsFyaaBbv6gkohIhVrrMvpIuV8X8JNI8/VNlOR6vExHd/3uWKi8vPrFEFTNQ1UE+WJDkVojcmx0t63jlP8C/O4ofaJeCYRkAaM9+FXnM+jVNf0qZU+3JGYmy1R/B7L+LyrbG2uYTaBa1Ba9zGsXD1HQ4dctK+MltBd4p+MWgHAQV+xuVmGGDkylpb8QKBgQDP9zY4UzLmnt0werJF9SGmAJU51Y/+gannUC/+XYqnK/NA5iUDR86rlYCJbqQCceyMYJSYuePumygWOVL9rHnu1/fTMG/sXnRktmTSFemgeCYfPyn8/KeZKn6E5xw8GbtfLJLA8uM4DakDf9vSpilKDYT4UbZyKgq7/yodPXbgCQKBgQDWs4gL4yOtDLAY/OQKZvoyXClapldkVFRzf97pBJQGLYfdTzkVFviWsgI/yrA+t5tlzaWtZieuv2KsSmazVyO2W5ei9HILx4yRFK7K56OM5o7wqjN62ZmF0R+422YNaAyqYAd9nhLjgdsrmZ9FTxhQ91asBSH1AO3j6xaZUvh1SQKBgAZuo/ur/xgI89hrAxaM1WSYAgWO6Gw7wHCKF2HrrL0s69InDCAE2YyPDDGz/ViiA2n4FsB+h2E65UuCrGFyMzdC8MRUbDHIXhs7VPT2fopbDPrMblUHz3s6SD1+FG57cUMpUsSq/oIeUgrsqnTidMZ4kpNHm7f+OuTDqJ7M5t9ZAoGAAfm2570YR/BU8nXpNztJVAtLCh17sl2gRUvI5kX3grMKi/u9n7cNZH2Qzbt0sa8Iy///ZUAKX249Xy50EXRczMG8/G/ZWMhmP7N8BDvrYlGAwTAftyKnafbJnu7N2pO5ghvOFdbNf7BjLtyD/aRDqgMMlhqZ/GIczjsMgy6jQJkCgYATxkjdW/mnWLDDZAYm1V10Gnm7YDMwX3gKdhpoYleeeapZiDlurkR3YAEvQezcnhv3NpjaKQtF1/3Q0fZJ0wBc5FflaevHRjHTa0IrU5QIa48dLDx+jxn+cUCFx9kirkb7JcfJLZWtToPMLfCZt324P2ogZgWBwweVPiz1/voEXw==\n-----END PRIVATE KEY-----"
}

// Helpers/RsaEncryptionHelper.cs 
public class RsaEncryptionHelper
{
 private readonly RSA _rsa = RSA.Create();

 public RsaEncryptionHelper(IConfiguration configuration)
 {
 var privateKeyPem = configuration["RsaKey"];
 if (string.IsNullOrEmpty(privateKeyPem)) throw new ArgumentNullException(nameof(privateKeyPem));
 ImportKey(privateKeyPem);
 }


 public void ImportKey(string privateKey)
 {
 _rsa.ImportFromPem(privateKey.ToCharArray());
 }

 public string GetPublicKey()
 {
 var publicKey = _rsa.ExportSubjectPublicKeyInfoPem();
 return publicKey;
 }

 public string GetPrivateKey()
 {
 var privateKey = _rsa.ExportPkcs8PrivateKeyPem();
 return privateKey;
 }

 public string Encrypt(string data)
 {
 var dataBytes = Encoding.UTF8.GetBytes(data);
 var encryptedData = _rsa.Encrypt(dataBytes, RSAEncryptionPadding.OaepSHA256);
 return Convert.ToBase64String(encryptedData);
 }

 public string Decrypt(string data)
 {
 var dataBytes = Convert.FromBase64String(data);
 var decryptedData = _rsa.Decrypt(dataBytes, RSAEncryptionPadding.OaepSHA256);
 return Encoding.UTF8.GetString(decryptedData);
 }
}

And use this helper class inside of EncryptionController to use helper class’s methods. In production enviroments You should not be expose PrivateKey to anyone. This should be kept secret.

// Controllers/EncryptionController.cs 
[ApiController]
[Route("api/[controller]")]
public class EncryptionController : ControllerBase
{
 private readonly RsaEncryptionHelper _rsaEncryptionHelper;

 public EncryptionController(RsaEncryptionHelper rsaEncryptionHelper)
 {
 _rsaEncryptionHelper = rsaEncryptionHelper;
 }

 [HttpPost("Encrypt")]
 public string Encrypt([FromBody] EncryptionRequest request)
 {
 return _rsaEncryptionHelper.Encrypt(request.Data);
 }

 [HttpPost("Decrypt")]
 public string Decrypt([FromBody] EncryptionRequest request)
 {
 return _rsaEncryptionHelper.Decrypt(request.Data);
 }

 [HttpGet("PublicKey")]
 public string PublicKey()
 {
 return _rsaEncryptionHelper.GetPublicKey();
 }

 [HttpGet("PrivateKey")]
 public string PrivateKey()
 {
 return _rsaEncryptionHelper.GetPrivateKey();
 }

 [HttpPost("ImportKey")]
 public void ImportKey([FromBody] ImportKeyRequest request)
 {
 _rsaEncryptionHelper.ImportKey(request.PrivateKey);
 }

}

public record ImportKeyRequest
{
 public string PrivateKey { get; init; } = null!;
}

public record EncryptionRequest
{
 public string Data { get; init; } = null!;
}

After this development we made in the backend side we can continue to JavaScript side. Thanks to all we’ve done we share our public key from endpoint with client, then clients could use this public key to encrypt their data for secure transmission between sides.

Setting Up the Development environment for JavaScript RSA Encryption

Before diving into the code, ensure your environment is set up for JavaScript development. For this example, we’ll use the Web Crypto API, which is built into modern browsers and provides cryptographic operations including RSA encryption. Therefore you don’t need to download any npm packages.

If I am going to develop a browser application with JavaScript, I usually start with Vite. To do this, we can start a project using vanilla js or React by entering the following command. I will develop a small React project for demonstration purposes, but it will be enough even if you stick with vanilla js.

npm create vite@latest

After that I will create a src/utils/RsaEncryptionHelper.js file and fill that file as follows. With this file’s methods you can encrypt and decrypt with RSA algorithm but usually decryption is a resposibility of backend side because decryption requires private key and javascript client’s should not be store or access private keys publicly because of security reasons. But I am sharing this in case anyone wants to try something similar to two-way key encryption like in the SSL.

// src/utils/RsaEncryptionHelper.js
const encryptAlgorithm = {
 name: "RSA-OAEP",
 modulusLength: 2048,
 publicExponent: new Uint8Array([1, 0, 1]),
 extractable: true,
 hash: {
 name: "SHA-256",
 },
};

function arrayBufferToBase64(arrayBuffer) {
 const byteArray = new Uint8Array(arrayBuffer);
 let byteString = "";
 for (let i = 0; i < byteArray.byteLength; i++) {
 byteString += String.fromCharCode(byteArray[i]);
 }
 const b64 = window.btoa(byteString);
 return b64;
}

function base64StringToArrayBuffer(b64str) {
 const byteStr = atob(b64str);
 const bytes = new Uint8Array(byteStr.length);
 for (let i = 0; i < byteStr.length; i++) {
 bytes[i] = byteStr.charCodeAt(i);
 }
 return bytes.buffer;
}

function convertPemToArrayBuffer(pem) {
 const lines = pem.split("\n");
 let encoded = "";
 for (let i = 0; i < lines.length; i++) {
 if (
 lines[i].trim().length > 0 &&
 lines[i].indexOf("-----BEGIN RSA PRIVATE KEY-----") < 0 &&
 lines[i].indexOf("-----BEGIN PRIVATE KEY-----") < 0 &&
 lines[i].indexOf("-----BEGIN PUBLIC KEY-----") < 0 &&
 lines[i].indexOf("-----END RSA PRIVATE KEY-----") < 0 &&
 lines[i].indexOf("-----END PRIVATE KEY-----") < 0 &&
 lines[i].indexOf("-----END PUBLIC KEY-----") < 0
 ) {
 encoded += lines[i].trim();
 }
 }
 return base64StringToArrayBuffer(encoded);
}

export const encryptRsa = async (str, pemString) => {
 try {
 // convert string into ArrayBuffer
 const encodedPlaintext = new TextEncoder().encode(str).buffer;
 const keyArrayBuffer = convertPemToArrayBuffer(pemString);
 // import public key
 const secretKey = await crypto.subtle.importKey(
 "spki",
 keyArrayBuffer,
 encryptAlgorithm,
 true,
 ["encrypt"]
 );
 // encrypt the text with the public key
 const encrypted = await crypto.subtle.encrypt(
 {
 name: "RSA-OAEP",
 },
 secretKey,
 encodedPlaintext
 );
 // store data into base64 string
 return arrayBufferToBase64(encrypted);
 } catch (error) {
 console.error("Encryption Error:", error);
 }
};

export const decryptRsa = async (str, pemString) => {
 try {
 // convert base64 encoded input string into ArrayBuffer
 const encodedPlaintext = base64StringToArrayBuffer(str);
 const keyArrayBuffer = convertPemToArrayBuffer(pemString);
 // import private key
 const secretKey = await crypto.subtle.importKey(
 "pkcs8",
 keyArrayBuffer,
 encryptAlgorithm,
 true,
 ["decrypt"]
 );
 // decrypt the text with the public key
 const decrypted = await crypto.subtle.decrypt(
 {
 name: "RSA-OAEP",
 },
 secretKey,
 encodedPlaintext
 );
 // decode the decrypted ArrayBuffer output
 const uint8Array = new Uint8Array(decrypted);
 const textDecoder = new TextDecoder();
 const decodedString = textDecoder.decode(uint8Array);
 return decodedString;
 } catch (error) {
 console.error("Decryption Error:", error);
 }
};

I developed a small React project using this helper methods. You can use your public and private keys that will be shared from .NET API to encrypt and decrypt data, but keep in mind decryption should be doing in backend side with private key that kept secret.

RSA Encryption (lecture-rsa-dotnet-javascript.vercel.app)

If you want to access the source code, you can find the whole project on my GitHub account:

GitHub - berkslv/lecture-rsa-dotnet-javascript

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

How to use Ocelot and Keycloak together to secure Microservices from API Gateway

Tue, 30 Jan 2024 00:00:00 +0300

In the dynamic landscape of microservices architecture, the need for robust security has become much more important. As organizations break down their applications into smaller, independently deployable services, ensuring the integrity and confidentiality of data exchanged between these services becomes a critical concern.

In this blog post, we will explore a comprehensive solution for securing microservices using Ocelot, an API Gateway with Keycloak, a powerful open-source identity and access management solution. By placing Keycloak behind the API Gateway, we’ll delve into how this integration safeguards resources, authenticates requests to other services, and authorizes access using claims, offering a seamless and secure communication framework for your microservices ecosystem. Let’s get started.

Create Keycloak instance

Running keycloak within Docker is very easy. Just place this Dockerfile in /Identity directory in your project. You can find all of the codes in my repository from end of the post.

FROM quay.io/keycloak/keycloak:latest as builder 
 
# Enable health and metrics support 
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true

# Configure a database vendor 
ENV KC_DB=postgres

WORKDIR /opt/keycloak 
# for demonstration purposes only, please make sure to use proper certificates in production instead 
RUN keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore 
RUN /opt/keycloak/bin/kc.sh build 
 
FROM quay.io/keycloak/keycloak:latest 
COPY --from=builder /opt/keycloak/ /opt/keycloak/ 
 
# change these values to point to a running postgres instance 
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

And create docker-compose.yml file that access /Identity/Dockerfile and builds image from it. We can use base image rather than custom Dockerfile but with this approach you can customize much more features of Keycloak like frontend theme and secret keys.

version: "3"

services:
 # PostgreSQL for keycloak 
 secured-identity-db:
 container_name: secured-identity-db 
 image: postgres:16-alpine 
 ports:
 - 6063:5432
 expose:
 - 6063
 volumes:
 - ./data/secured-identity-db:/var/lib/postgresql/data 
 restart: always 
 environment:
 - POSTGRES_PASSWORD=myStrongPassword123 
 - POSTGRES_USER=keycloak 
 - POSTGRES_DB=keycloak 
 networks:
 - secured-network 

 # Keycloak 
 secured-identity:
 container_name: secured-identity 
 build: ./Keycloak 
 command: ["start-dev"]
 ports:
 - 5053:8080
 expose:
 - 5053
 environment:
 - KEYCLOAK_ADMIN=admin 
 - KEYCLOAK_ADMIN_PASSWORD=admin 
 - KC_HOSTNAME_URL=http://localhost:5050/identity 
 - KC_DB=postgres 
 - KC_DB_USERNAME=keycloak 
 - KC_DB_PASSWORD=myStrongPassword123 
 - KC_DB_URL=jdbc:postgresql://secured-identity-db:5432/keycloak 
 depends_on:
 - secured-identity-db 
 networks:
 - secured-network 

networks:
 secured-network:
 driver: bridge 

volumes:
 secured-data:
 driver: local

And we just need to run docker from this docker-compose.yml file.

docker compose build
docker compose up -d

Put keycloak behind Ocelot API Gateway to protect resources

Microservice architecture with Ocelot and Keycloak

It is important to secure your identity service (keycloak) and reduce the attack vector by limiting the endpoints that can receive requests like other services. Keycloak admin panel should not be accessed from an external network, only people on this network can access this feature. For further readings consider visit Keycloak documentation about Using a reverse proxy.

Exposed path recommendations

First, let’s create Ocelot project. I use Dotnet 8

dotnet new sln -n Secured
dotnet new webapi -o Secured.ApiGateway
cd Secured.ApiGateway/
dotnet add package Ocelot --version 22.0.1

After we successfully created the project, modify Program.cs as follows and create ocelot.json file in root directory.

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile("ocelot.json", optional: false, reloadOnChange: true);

builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

await app.UseOcelot();
await app.RunAsync();

After that, we can use this ocelot.json file to limit access to our keycloak application running on localhost:5053.

{
 "Routes": [
 {
 "DownstreamPathTemplate": "/realms/{everything}",
 "DownstreamScheme": "http",
 "DownstreamHostAndPorts": [
 {
 "Host": "localhost",
 "Port": 5053
 }
 ],
 "UpstreamPathTemplate": "/identity/realms/{everything}",
 "UpstreamHttpMethod": [ "Get", "Post", "Put", "Delete" ]
 },
 {
 "DownstreamPathTemplate": "/resources/{everything}",
 "DownstreamScheme": "http",
 "DownstreamHostAndPorts": [
 {
 "Host": "localhost",
 "Port": 5053
 }
 ],
 "UpstreamPathTemplate": "/identity/resources/{everything}",
 "UpstreamHttpMethod": [ "Get" ]
 },
 {
 "DownstreamPathTemplate": "/js/{everything}",
 "DownstreamScheme": "http",
 "DownstreamHostAndPorts": [
 {
 "Host": "localhost",
 "Port": 5053
 }
 ],
 "UpstreamPathTemplate": "/identity/js/{everything}",
 "UpstreamHttpMethod": [ "Get" ]
 }
 ],
 "GlobalConfiguration": {
 "BaseUrl": "https://localhost:5050"
 }
}

After this configurations you can access keycloak from localhost:5050 that is the API Gateway’s address. After these configurations, you can access keycloak from localhost:5050, which is the address of the API Gateway, but you will not be able to access the Keycloak admin panel through this address because we have limited access.

For making our Keycloak configurations, we can log in to the admin panel at the keycloak address that is still accessible locally, that is, localhost:5053. Note that in the deployment scenario, we will ensure that only Ocelot has access to the external internet.

In localhost:5053 we can enter admin for username and admin for password. We can change this credentials from docker-compose.yml file.

After logged in we create new realm for managing users and client for our application from this dropdown menu. After clicking the Create realm button, simply enter the secured as the realm name and leave everything as is.

In clients tab click Create client. name Client ID as postman and valid redirect uri as https://oauth.pstmn.io/v1/callback. leave other things as is.

In the users tab, add users to log in to Keycloak.

After these steps we can login to our keycloak with newly created user to get access token. For accessing API gateway I use Postman. In postman you can logged in with Keycloak. In Authorization section select OAuth 2.0 and configure as follows and click Get New Access Token. Postman will open browser window and redirect you to Keycloak login page, enter credentials for your new user. Don’t enter admin credentials, this credentials only valid in master realm.

Grant type: Authorization code
Auth URL: http://localhost:5050/identity/realms/secured/protocol/openid-connect/auth
Access Token URL: http://localhost:5050/identity/realms/secured/protocol/openid-connect/token
Client ID: postman
Scope: openid profile roles

If you did everything right, you have successfully authenticated using Postaman with Keycloak behind the API Gateway 🎉

Authenticate requests to other services

If you want to authenticate a request in Ocelot, make the following updates to Program.cs and ocelot.json. MetadataAddress gets the keys required for JWT validation. However, if you want to avoid extra network calls, you can place the keys in the appsettings.json file and use them.

Authentication completed with AuthenticationOptions in ocelot.json file, here we say that we will send our JWT token along with the Bearer prefix and JWT token validation done with configuration from Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services
 .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
 .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, o =>
 {
 o.MetadataAddress = "http://localhost:5050/identity/realms/secured/.well-known/openid-configuration";
 o.RequireHttpsMetadata = false;
 o.Authority = "http://localhost:5050/realms/secured";
 o.Audience = "account";
 });

builder.Configuration.AddJsonFile("ocelot.json", optional: false, reloadOnChange: true);


builder.Services.AddOcelot(builder.Configuration);

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

await app.UseOcelot();
await app.RunAsync();

{
 "Routes": [
 {
 "DownstreamPathTemplate": "/get",
 "DownstreamScheme": "https",
 "DownstreamHostAndPorts": [
 {
 "Host": "httpbin.org",
 "Port": 443
 }
 ],
 "UpstreamPathTemplate": "/test",
 "UpstreamHttpMethod": [ "Get" ],
 "AuthenticationOptions": {
 "AuthenticationProviderKey": "Bearer"
 }
 },

//...

Authorize requests to other services

Authorization is slightly more difficult and requires additional work because Keycloak place user roles in nested form in JWT payload. It is something like following. As you can see roles field is placed under realm_access field. This creates confusion in Ocelot, because Ocelot reads claims as string or object values and does not evaluate nested fields. To avoid this problem we configure Keycloak token mapper and don’t use nested form.

{
 //...
 "exp": 1706600524,
 "realm_access": {
 "roles": [
 "offline_access",
 "default-roles-microcommerce",
 "uma_authorization",
 "customer"
 ]
 },
 "resource_access": {
 "account": {
 "roles": [
 "manage-account",
 "manage-account-links",
 "view-profile"
 ]
 }
 },
 "scope": "openid email profile",
 "preferred_username": "berkslv",
}

For this custom mapping, click Client scopes from left menu and select roles.

Under the roles, select Mappers section and then click realm roles.

In the menu that opens, realm_access.roles is entered in the Token Claim Name option. We update this to realm_roles.

After making these configurations, we update our token by logging in again via Postman. We make the following update in the ocelot.json file so that the requests we make with the updated token are subject to claim control by Ocelot. If we don’t have customer role in our user we get 403 response. You can create and assing your custom roles in Keycloak admin panel.

{
 "Routes": [
 {
 "DownstreamPathTemplate": "/get",
 "DownstreamScheme": "https",
 "DownstreamHostAndPorts": [
 {
 "Host": "httpbin.org",
 "Port": 443
 }
 ],
 "UpstreamPathTemplate": "/test",
 "UpstreamHttpMethod": [ "Get" ],
 "AuthenticationOptions": {
 "AuthenticationProviderKey": "Bearer"
 },
 "RouteClaimsRequirement": {
 "realm_roles": "customer"
 }
 },

//...

If you want to access the source code, you can find the whole project on my GitHub account:

GitHub - berkslv/lecture-ocelot-and-keycloak

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

Achieving Zero Downtime: Azure App Service Deployment using Azure DevOps and Deployment Slots

Tue, 21 Nov 2023 00:00:00 +0300

Hello! When deploying our application, which runs as a single instance in Azure App Service, using Azure DevOps pipelines, there will most likely be a few seconds of downtime. Because the application running as a single instance will need to be restarted to update it with a new version. In a worst case scenario, if an error occurs in the transition of our application versions, downtime will be extended due to rollback.

We can use the deployment slots feature to solve this problem specifically for the app service. With this feature, 2 different instances, usually staging and production applications, are running in a single app service plan as a separate instances, and when switching to production, the swap operation is managed by the app service and no downtime is experienced.

In this post, we will create a very simple Dotnet Web API project, host it in the Azure DevOps repository, deploy it to Azure App Service by creating a CI/CD pipeline with the Azure DevOps pipeline, and perform zero downtime deployment with the deployment slots feature. We will complete the entire process in 5 steps as follows. Let’s begin.

Creating the application
Azure DevOps Repo
Azure DevOps build pipeline
Azure App service
Zero downtime testing

## Creating the application

We create a simple Dotnet Web API project to deploy. To do this, we create our project with the following commands.

mkdir backend
cd ./backend
dotnet new sln -n Slot
dotnet new webapi -n Slot.API
dotnet sln add ./Slot.API/

We update the profiles.http property in the properties/launchSetting.json file as follows. Here we only updated the applicationUrl and launchBrowser properties.

// ...
 "profiles": {
 "http": {
 "commandName": "Project",
 "dotnetRunMessages": true,
 "launchBrowser": false,
 "launchUrl": "swagger",
 "applicationUrl": "http://localhost:5050",
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 },
// ...

By making the following update on Program.cs, we will test that the application is accessible and can meet the requests made to the /health endpoint. If you are using a database in your application, you can also test whether there is a problem accessing the database with AddDbContextCheck method.

var builder = WebApplication.CreateBuilder(args);

// ... 

builder.Services.AddHealthChecks();

var app = builder.Build();

// ... 

// app.UseHttpsRedirection(); 

app.MapControllers();

app.UseHealthChecks("/health");

app.Run();

That’s it for our application! Now we can access the localhost:5050/health endpoint by running

cd ./Slot.API
dotnet run
curl -4 http://localhost:5050/health
# Healthy

Later, we will use Docker to deploy our application, so we put our Dockerfile file in the same directory as our sln file.

# Build Stage 
FROM mcr.microsoft.com/dotnet/aspnet:7.0-alpine AS base 
WORKDIR /app 
EXPOSE 8080 
 
 
# Publish Stage 
FROM mcr.microsoft.com/dotnet/sdk:7.0-alpine AS build 
COPY ["Slot.API/Slot.API.csproj", "Slot.API/"] 
RUN dotnet restore "Slot.API/Slot.API.csproj" 
COPY . . 
WORKDIR "/Slot.API" 
RUN dotnet build "Slot.API.csproj" -c Release -o /app/build 
 
FROM build AS publish 
RUN dotnet publish "Slot.API.csproj" -c Release -o /app/publish /p:UseAppHost=false 
 
FROM base AS final 
WORKDIR /app 
COPY --from=publish /app/publish . 
ENV ASPNETCORE_URLS=http://*:8080 
ENV ASPNETCORE_ENVIRONMENT=Production
ENTRYPOINT ["dotnet", "Slot.API.dll"]

We can use the following two commands to ensure that we can successfully build the image and run the container.

docker build -t deployment-slots-demo .
docker run -it -p 80:8080 deployment-slots-demo -n deployment-slots-demo-container

Verify that the application is up

After creating our application with the health check feature in the previous step, we can verify that the application is accessible by making a request to this endpoint every second. This way, we will verify that it is accessible when deployed to Azure.

In this section, we will write a simple Node.js script to verify that the application can be accessed by making requests every second. We use the following commands for this.

mkdir health-check
npm init -y
touch index.js
npm install node-fetch

We add the following script to the package.json file.

// ...
"scripts": {
 "start": "node index.js"
},
"type": "module",
// ...

We can create our index.js file as follows. With this code, we will make a request to the given url every 50 milisecond and write the response to the console.

import fetch from "node-fetch";

const check = async (url) => {
 try {
 const response = await fetch(url, {
 method: "GET",
 });
 const result = await response.text();

 if (result !== "Healthy") {
 console.log(`${new Date().toISOString()}, ${url} result is not OK`);
 }
 } catch (error) {
 console.log(`${new Date().toISOString()}, ${url} error is ${error.message}`);
 }
};

(() => {
 setInterval(() => {
 check("http://localhost:5050/health");
 }, 50);
 setInterval(() => {
 check("http://localhost:5050/health");
 }, 50);
})();

If you do not turn off the UseHttpsRedirection middleware in our API project, you may receive an invalid SSL certificate error. You can fix this as follows.

import fetch from "node-fetch";
import https from "https";

const httpsAgent = new https.Agent({
 rejectUnauthorized: false,
});

const check = async (url) => {
 try {
 const response = await fetch(url, {
 method: "GET",
 agent: httpsAgent,
 });
 const result = await response.text();

 if (result !== "Healthy") {
 console.log(`${new Date().toISOString()}, ${url} result is not OK`);
 }
 } catch (error) {
 console.log(`${new Date().toISOString()}, ${url} error is ${error.message}`);
 }
};

(() => {
 setInterval(() => {
 check("https://localhost:5051/health");
 }, 50);
 setInterval(() => {
 check("https://localhost:5051/health");
 }, 50);
})();

Azure DevOps Repo

We log into our Azure DevOps account and create a new repo as follows.

We will clone this repo to our computer, move the code that we write into this repo folder and push the codes to origin.

git add .
git commit -m "inital commit"
git push origin

Azure DevOps build pipeline

On the Pipeline screen, we click on the New pipeline button from the top right. Then, we build the docker file and push it to Azure Container Registry by following the steps below.

Now we check that our image deployment in Azure Container Registry is successful.

As we can see, when the pipeline is run, the docker image has been successfully created in the Azure Container Registry and is waiting to be used. After these settings, a new docker image will be created by triggering every change made in the /backend directory on the main branch.

Azure App service

Azure App service allows us to deploy web applications with security, load balancing, autoscaling managed by Azure itself. We can create a new app service via the Azure app services screen as follows.

After creating the app service, you may need to update the Container Registry password from the configuration tab.

## Azure DevOps release pipeline

With the release pipeline, we deploy to the App service using the Docker image produced by the build pipeline and publish our application.

By going into staging deployment, we get deployment for our staging version and restart our app service to ensure that the docker image change we made goes live.

In our production step, we do not take a deployment to the app service, instead we perform the swap operation with staging and in this way, we start running our application running in staging in production without experiencing any downtime.

From now on, any changes made to the main branch will first run the build pipeline (CI), then the deployment pipeline (CD), and deployment will be made to the staging environment. If you want to switch to Production, Production deployment must be triggered manually from the release screen.

Zero downtime testing

We have successfully created a pipeline for our application, from now on we will need to test whether there is any downtime during deployment. For this, I update our health-check/index.js file as follows and run the application with the npm run start command and trigger the pipeline. And then I complete the deployment process without receiving any error messages on the console, that is, without any downtime!

import fetch from "node-fetch";

const check = async (url) => {
 try {
 const response = await fetch(url, {
 method: "GET",
 });
 const result = await response.text();

 if (result !== "Healthy") {
 console.log(`${new Date().toISOString()}, ${url} result is not OK`);
 }
 } catch (error) {
 console.log(`${new Date().toISOString()}, ${url} error is ${error.message}`);
 }
};

(() => {
 setInterval(() => {
 check("https://deployment-slot-demo.azurewebsites.net/health");
 }, 50);
 setInterval(() => {
 check("https://deployment-slot-demo-staging.azurewebsites.net/health");
 }, 50);
})();

If we try a similar process in an app service deployment that does not implement deployment slots, we will receive an error as follows.

2023-11-14T12:28:39.506Z, [some-url]/health error is request to [some-url]/health failed, reason: connect ETIMEDOUT 100.100.100.100:443

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

Background jobs and Hangfire in .NET

Sun, 17 Sep 2023 00:00:00 +0300

When developing an application in the .Net ecosystem, when things get complicated, we may need some of our methods to go to multiple services, evaluate their responses, and report these results to different services and this takes long time! We do not want to waste resources by placing such long-running methods behind an endpoint and keeping our TCP connection open for the response from that HTTP request. We can call this usage on demand job because it will run when a request is made. We may also want it to run automatically at certain times of the day or week, without putting it behind an endpoint; in this case, we can call it a recurring job. In such cases, we use “background job” by starting our work on a different thread other than the main thread where the application runs.

There are many different methods of managing background jobs in .Net. This will be a blog post where I will talk about them step by step, how they solve problems and what problems they cause us, and give in-depth usage examples in Hangfire, which is the package I like the most when dealing with background jobs. You can also access all the codes from the repo:

GitHub - berkslv/lecture-dotnet-background-jobs

Task.Run()

We can create a new thread and run a method on it with the Task.Run() method, which is the first solution that comes to my mind when I need a background job. I have a method that has dependencies on many external services that can take up to 5 minutes to complete, and I was calling this method with an HTTP request through a controller that I created, but answering this request was problematic because it is required a TCP connection to remain open for 5 minutes, so instead when I called the method, If started successfully, I had to notify the client that the process was started successfully with a 200 status code.

// TestService.cs 

public class TestService : ITestService
{
 private readonly ILogger<TestService> _logger;
 public TestService(ILogger<TestService> logger)
 {
 _logger = logger;
 }

 public bool RunTests()
 {
 _logger.LogInformation($"{DateTime.Now} RunTests is started");

 // ... 
 Thread.Sleep(5000);
 // ... 

 _logger.LogInformation($"{DateTime.Now} RunTests is finished");
 return true;
 }
}

// Program.cs 

// ... 

builder.Services.AddTransient<ITestService, TestService>();

// ...

If I do not make the execution by calling with the Task.Run(), the request to my /job endpoint will be loading for 3 seconds in browser for this example.

// JobController.cs 

[ApiController]
[Route("[controller]")]
public class JobController : ControllerBase
{
 private readonly ITestService _testService;
 public JobController(ITestService testService)
 {
 _testService = testService;
 }

 [HttpGet]
 public IActionResult Get()
 {
 _testService.RunTests();

 return Ok("Ok");
 }
}

If I use Task.Run instead as below, the controller will respond ok and my RunTests method will continue to run in the background.

[HttpGet]
public IActionResult Get()
{
 Task.Run(() => {
 _testService.RunTests();
 });

 return Ok("Ok");
}

Pros

We can run a process in the background on demand.
Does not require an additional package.

Cons

It does not support recurring in its current state, a special system must be developed.
When Dependency Injection is used, since the injected interfaces will remain on the main thread, we may need to re-generate the required interface through the Service scope.
What happens if an error is throwed while running the Method?

Hosted Service

We had to develop our own system to manage recurring jobs, which we could not implement in our previous example, but with the Hosted service, we do not need to develop this management ourselves, instead we call our AddHostedService method in Program.cs as follows and inherit our TestService class from the BackgroundService class. In this example, our RunTests method will run every 10 seconds. This time interval is set from the ExecuteAsync method inherited from BackgroundService abstract class.

// Program.cs 

// ... 

builder.Services.AddHostedService<TestService>();

// ...

// TestService.cs 


public class TestService : BackgroundService, ITestService
{
 private readonly ILogger<TestService> _logger;
 public TestService(ILogger<TestService> logger)
 {
 _logger = logger;
 }

 public bool RunTests(TestType testType)
 {
 var type = Enum.GetName(typeof(TestType), testType);

 _logger.LogInformation($"{DateTime.Now} {type} RunTests is started");

 // ... 
 Thread.Sleep(5000);
 // ... 

 _logger.LogInformation($"{DateTime.Now} {type} RunTests is finished");

 return true;
 }

 protected override async Task ExecuteAsync(CancellationToken stoppingToken)
 {
 var timer = new PeriodicTimer(TimeSpan.FromSeconds(10));
 while (await timer.WaitForNextTickAsync(stoppingToken))
 {
 RunTests(TestType.Recurring);
 }
 }
}

However, if we want to run our method on demand, we work on a new thread with the help of the Task.Run() method, so we do not need to make any changes to JobController.cs.

Pros

Provides recurring job management
No need to install additional packages

Cons

It does not have a system for on demand operation.
What happens if an error is received while running the Method?

Hangfire

Hangfire makes our job much easier to manage on demand and recurring jobs through a single system. With the Job Storage system, which is not available in the other two methods, if the application is not running at that moment but the cron job has expired, it automatically runs the relevant job. We can run specific jobs and delete that job with the ID information provided during job creation. Additionally, we can monitor currently running jobs via a dashboard at /hangfire.

Hangfire dashboard

Hangfire officially supports the Sql Server database, but with an open source extension, frequently preferred databases such as Sqlite and Postgresql can also be used. In addition, Hangfire, with its paid version, also meets enterprise needs such as Redis database support and running batch jobs.

Hangfire – Background Jobs for .NET and .NET Core

After this brief introduction to Hangfire, let’s briefly talk about how we can use Hangfire in our application and its capabilities. In our example, we will use Postgresql as Job storage, but you can choose any database you want from the link above. After installing the following packages in our application and setting up a Postgre SQL database with docker, let’s move on to our code.

dotnet add package Hangfire
dotnet add package Hangfire.Core
dotnet add package Hangfire.PostgreSql
dotnet add package TimeZoneConverter

docker run -d --name postgres_db -e POSTGRES_USER="root" -e POSTGRES_PASSWORD="1234" -e POSTGRES_DB="postgres" -v postgres_data:/var/lib/postgresql/data -p 5432:5432 postgres

First, we provide the connection string information for Postgresql in appsettings.json as follows.

"ConnectionStrings": {
 "HangfireConnection": "Host=localhost;Port=5432;Password=1234;Username=root;Database=postgres;Pooling=true;Integrated Security=true;"
}

We make the relevant configurations in Program.cs as follows.

With TZConvert.GetTimeZoneInfo method you get the neccessary time zone information from OS. This line of code is neccessary because your local machine, frontend application and Cloud machine may have different time zones.

var builder = WebApplication.CreateBuilder(args);

// ... 

builder.Services.AddHangfire(config => {
 config
 .UseSimpleAssemblyNameTypeSerializer()
 .UseRecommendedSerializerSettings()
 .UsePostgreSqlStorage(builder.Configuration.GetConnectionString("HangfireConnection"));

 var cronEveryMinute = "*/1 * * * *";
 var recurringJobOptions = new RecurringJobOptions
 {
 TimeZone = TZConvert.GetTimeZoneInfo("Etc/GMT+3")
 };
 RecurringJob.AddOrUpdate<ITestService>("id-run-and-wait", x => x.RunTests(Guid.NewGuid(), TestType.Recurring, CancellationToken.None), cronEveryMinute, recurringJobOptions);
});

builder.Services.AddHangfireServer();

var app = builder.Build();

// ... 

app.UseHangfireDashboard();
app.MapHangfireDashboard();

app.Run();

To showcase Hangfire’s capabilities, we add a few more endpoints to our controller class.

/run, we can start a job and that method returns us a job id

/stop, we can stop the job related to the job id given to us by Hangfire.

/continue, if many different jobs are to be run but they are dependent on each other, another job can be run after the parent job is finished with the given job id.

/reschedule, the job’s working intervals can be dynamically adjusted by cron or TimeSpan.

/deschedule, recurring jobs can be deleted by their unique id.

/trigger, we can manually trigger a recurring job.

// JobController.cs 


[ApiController]
[Route("[controller]")]
public class JobController : ControllerBase
{
 [HttpGet("/run")]
 public IActionResult Run()
 {
 var jobId = BackgroundJob.Enqueue<ITestService>(x => x.RunTests(Guid.NewGuid(), TestType.OnDemand, CancellationToken.None));

 return Ok(jobId);
 }

 [HttpGet("/stop")]
 public IActionResult Stop(string jobId)
 {
 BackgroundJob.Delete(jobId);

 return Ok("Stopped");
 }

 [HttpGet("/continue")]
 public IActionResult Continue(string jobId)
 {
 BackgroundJob.ContinueJobWith<ITestService>(jobId, x => x.RunTests(Guid.NewGuid(), TestType.OnDemand, CancellationToken.None));

 return Ok("Continued");
 }

 [HttpGet("/reschedule")]
 public IActionResult Reschedule(string cron)
 {
 var recurringJobOptions = new RecurringJobOptions
 {
 TimeZone = TZConvert.GetTimeZoneInfo("Etc/GMT+3")
 };
 RecurringJob.AddOrUpdate<ITestService>("id-run-and-wait", x => x.RunTests(Guid.NewGuid(), TestType.Recurring, CancellationToken.None), cron, recurringJobOptions);
 return Ok("Rescheduled");
 }

 [HttpGet("/deschedule")]
 public IActionResult Deschedule(string id)
 {
 if (String.IsNullOrEmpty(id))
 {
 id = "id-run-and-wait";
 }

 RecurringJob.RemoveIfExists(id);
 return Ok("Descheduled");
 }

 [HttpGet("/trigger")]
 public IActionResult Trigger(string id)
 {
 if (String.IsNullOrEmpty(id))
 {
 id = "id-run-and-wait";
 }

 RecurringJob.TriggerJob(id);
 return Ok("Triggered");
 }
}

Finally, error management, which is not in our toolkit previously with Task.Run() and Hosted service but with Hangfire if an error occurs while running a method, Hangfire runs that method 10 more times with the same parameters at certain time intervals. As an example, we add a method called ThrowRandomly to our TestService class. With this method, we simply add a system that will throw an exception from the method that works with probability 1/2, but Hangfire will try to get successful results by re-running the methods that get errors for us. But errors that catches successfully cannot trigger the retry system. Therefore in the end of catch block we throw again.

// TestService.cs 


public class TestService : ITestService
{
 private readonly ILogger<TestService> _logger;
 public TestService(ILogger<TestService> logger)
 {
 _logger = logger;
 }

 public bool RunTests(Guid id, TestType testType, CancellationToken cancellationToken)
 {
 var type = Enum.GetName(typeof(TestType), testType);

 try
 {
 _logger.LogInformation($"{DateTime.Now} {type} RunTests is started. Id: {id}");

 cancellationToken.ThrowIfCancellationRequested();
 // ... 
 Thread.Sleep(5000);
 ThrowRandomly();
 // ... 

 _logger.LogInformation($"{DateTime.Now} {type} RunTests is finished. Id: {id}");
 return true;
 }
 catch (OperationCanceledException exception)
 {
 _logger.LogError($"{DateTime.Now} {type} RunTests is failed. Exception: {exception.Message} Id: {id}");
 throw;
 }
 catch(Exception exception)
 {
 _logger.LogError($"{DateTime.Now} {type} RunTests is failed. Exception: {exception.Message} Id: {id}");
 throw;
 }
 }

 private void ThrowRandomly()
 {
 var random = new Random();
 var number = random.Next(1, 3);

 if (number == 2)
 {
 throw new Exception("Error is throwed!");
 }
 }
}

Also Hangfire runs on a seperate service, this can be good or bad depending on your needs. When you need scaling you may seperate the application and hangfire servers and place them to different machines.

Pros

Can manage on demand and recurring jobs together with a powerful abstraction
We can adjust cron job timing dynamically and its timing is very precise.
We can monitor our employee and cron jobs with Dashborad.
There is no imposed interface implementation or any other special implementation, we can only manage our jobs by using the methods provided by Hangfire.

Cons

External storage is required, works with SQL Server by default.

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

How to Secure Dotnet & Vue.js Application with Keycloak

Mon, 21 Aug 2023 00:00:00 +0300

In this post, I will talk about how we can secure our dotnet and vue applications using keycloak.

First, we run our keycloak application using docker, if you publish this application using Azure or a similar cloud provider, you can easily use it in your production applications.

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:22.0.1 start-dev

After Keycloak is running, we create realm for our application from the left side after logging in from localhost:8080/admin with username: admin and password: admin. Since master realm is assigned to keycloak’s own use, we need to work on another realm.

Create realm

Create realm confirmation

After creating the realm, we create a client called vue from the client section. Our redirect urls are the url of our Vue app. You may need to make additional updates for production.

We can create users under dotnet-vue realm from the Users menu to be used in our vue application.

If we want to create a user for our application, we can enable our users to register with keycloak by turning on this option in realm settings.

Vue

After completing these configurations, we are done with the keycloak admin panel, when an unauthorized request comes to our vue application, we have to redirect it to our keycloak login page. For this, we use the medium article Secure Vue.js app with Keycloak

We can create our Vue application using vite as follows, you can choose Vue and Javascript from the questions asked and continue.

npm create vite@latest vue
cd vue
npm install
npm run dev

Then we update the main.js content as follows. This script simply redirects the unauthorized requests to login and updates the token with the refresh token if the token expires with onTokenExpired. After this process, if we run the application with npm run dev and go to http://localhost:5173, the keycloak login url will be redirected. If we log in with the user information we have created, we will be logged into our system.


import { createApp } from "vue";
import "./style.css";
import App from "./App.vue";
import Keycloak from "keycloak-js";

let initOptions = {
 url: "http://localhost:8080",
 realm: "dotnet-vue",
 clientId: "vue",
 onLoad: "login-required",
};

let keycloak = new Keycloak(initOptions);

keycloak
 .init({ onLoad: initOptions.onLoad })
 .then((auth) => {
 if (!auth) {
 window.location.reload();
 } else {
 console.log("Authenticated");
 }

 createApp(App).mount("#app");
 })
 .catch((error) => {
 console.log(error);
 console.error("Authenticated Failed");
 });

keycloak.onTokenExpired = () => {
 console.log("Token expired");

 keycloak
 .updateToken(30 * 60)
 .then(() => {
 console.log("Token renewed");
 })
 .catch(() => {
 keycloak.login()
 })
}

export default keycloak;

Dotnet

We can create a webapi project using Dotnet 6 as follows.

cd dotnet
dotnet new sln -n Secured
dotnet new webapi -o Secured.API
cd Secured.API
dotnet watch run

Thanks to the standards supported by Keycloak and Dotnet, we can only authorize with the configurations we will make in Program.cs without writing a special code. In this code, we verify where the token came from with the issuer, and thanks to IssuerSigningKey, we can verify the generated token without going to the keycloak.

RequireHttpsMetadata should only be used for development enviroment, if you have an application running in production enviroment you can delete this line and its value will evaluate to true.

builder.Services.AddSwaggerGen();

// ... 

var issuer = builder.Configuration["Jwt:Issuer"];
var key = builder.Configuration["Jwt:Key"];
builder.Services.AddAuthentication(options =>
 {
 options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
 options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
 })
 .AddJwtBearer(o =>
 {
 o.Authority = issuer;
 o.RequireHttpsMetadata = false;
 o.TokenValidationParameters = new Microsoft.IdentityModel.Tokens.TokenValidationParameters
 {
 ValidateIssuer = true,
 ValidateAudience = false,
 ValidateLifetime = true,
 ValidateIssuerSigningKey = true,
 ValidIssuer = issuer,
 IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(key))
 };
 });

// ... 

var app = builder.Build();

// ... 

app.UseAuthentication();
app.UseAuthorization();

// ... 

app.Run();

We can access it at builder.Configuration by keeping the data as below in the appsettings.json file. You can access the RSA256 key from the RSA256 Kid value in the Keys tab in the Realm settings menu under the relevant realm in the keycloak admin panel.

"Jwt": {
 "Issuer": "https://localhost:8080/realms/dotnet-vue",
 "Key": "secret-rsa-key"
},

Consuming Dotnet API from Vue app

First we add CORS settings and Authorize attributes in our dotnet project. For this, we edit Program.cs as follows.


// ... 

builder.Services.AddCors(options =>
{
 options.AddDefaultPolicy(
 policy => policy.WithOrigins("http://localhost:5137")
 .AllowAnyHeader()
 .AllowAnyMethod()
 .AllowAnyOrigin()
 );
});

// ... 

var app = builder.Build();

// app.UseHttpsRedirection(); 

app.UseCors();

The WeatherForecastController.cs file provides security with the following attribute.

// ... 

[Authorize]
public class WeatherForecastController : ControllerBase

// ...

Then, we install the axios library in our vue application with the following command.

npm install axios

After installation, we create a folder named services and make axios configurations in our file named base.api.js.


import axios from "axios";
import keycloak from "../main"

const http = axios.create({
 baseURL: "http://localhost:5050",
 headers: {
 "Content-Type": "application/json",
 },
});

http.interceptors.request.use(
 async (config) => {
 const token = localStorage.getItem("vue-token");
 config.headers = {
 Authorization: `Bearer ${keycloak.token}`,
 Accept: "application/json",
 };
 return config;
 },
 (error) => {
 Promise.reject(error);
 }
);

export default http;

To use the WeatherForecast endpoint, which is an example endpoint, we create the weather.api.js file in the same directory.


import axios from "./base.api";

export const getWeather = async () => {
 const response = await axios.get(`/WeatherForecast`);
 return response.data;
}

We display the data by making our API request in App.vue, here we can log out with the logout method.


<script>
import Keycloak from './main';
import { getWeather } from './service/weather.api';

export default {
 name: 'App',
 data() {
 return {
 weathers: []
 }
 },
 async mounted() {
 this.weathers = await getWeather();
 },
 methods: {
 logout() {
 Keycloak.logout();
 }
 },
}

</script>

<template>
 <button @click="logout" style="margin-bottom: 30px;">Logout</button>
 <table>
 <tr>
 <th>Date</th>
 <th>Summary</th>
 </tr>
 <tr v-for="weather in weathers">
 <td>{{ weather.date }}</td>
 <td>{{ weather.summary }}</td>
 </tr>
 </table>
</template>

If you want to access the source code, you can find the whole project on my GitHub account:

GitHub - berkslv/lecture-dotnet-vue-keycloak

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

How to Deploy a React App with Nginx using Docker with react-router-dom

Sat, 21 Jan 2023 00:00:00 +0300

If you’re looking to deploy a React app, there are several options available, including deploying it to a web server or using a containerization tool like Docker. In this tutorial, we’ll show you how to deploy a React app with Nginx using Docker. Nginx is a popular open-source web server that is known for its high performance and low resource usage. We’ll create a Dockerfile for our React app that uses Nginx to serve the app, and we’ll also create an Nginx configuration file to tell Nginx how to serve the app. Finally, we’ll build a Docker image of our app and run a Docker container to deploy the app.

Prerequisites:

A basic understanding of Docker
A React app to deploy

Step 1: Create a Dockerfile

The first step is to create a Dockerfile for our React app. This file will contain instructions on how to build a Docker image of our app. Here is an example Dockerfile for a React app with Nginx:

# Use an official Node runtime as a parent image
FROM node:19-alpine as build

# Set the working directory to /app
WORKDIR /app

# Copy the package.json and package-lock.json to the container
COPY package*.json ./

# Install dependencies
RUN npm install

# Copy the rest of the application code to the container
COPY . .

# Build the React app
RUN npm run build

# Use an official Nginx runtime as a parent image
FROM nginx:1.21.0-alpine

# Copy the ngnix.conf to the container
COPY ngnix.conf /etc/nginx/conf.d/default.conf

# Copy the React app build files to the container
COPY --from=build /app/build /usr/share/nginx/html

# Expose port 80 for Nginx
EXPOSE 80

# Start Nginx when the container starts
CMD ["nginx", "-g", "daemon off;"]

This Dockerfile uses the official Node runtime as the parent image to install and build the React app. It then uses the official Nginx runtime as the parent image to serve the React app.

Step 2: Create an Nginx configuration file

Next, we need to create an Nginx configuration file to tell Nginx how to serve our React app. Here is an example configuration file:

server {
listen 80;
server_name example.com;
root /usr/share/nginx/html;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}

You must create this nginx.conf file in the same directory with Dockerfile. This configuration file sets up Nginx to listen on port 80 and serve the React app. The try_files directive tells Nginx to try serving the requested file, then the directory containing the file, and finally fall back to serving the index.html file if the requested file or directory doesn’t exist.

Step 3: Build the Docker image

With the Dockerfile and Nginx configuration file created, we can now build the Docker image. Navigate to the directory containing the Dockerfile and run the following command:

docker build -t my-react-app .

This command tells Docker to build an image using the Dockerfile in the current directory and tag it with the name my-react-app. The . at the end of the command tells Docker to use the current directory as the build context.

Step 4: Run the Docker container

With the Docker image built, we can now run a container using the following command:

docker run -p 80:80 my-react-app

This command creates a container from the my-react-app Docker image and maps port 80 in the container to port 80 on the host machine. You can then access your React app by navigating to http://localhost in your web browser.

Congratulations, you have successfully deployed a React app with Nginx using Docker! You can now use this method to easily deploy your React apps to any server or hosting platform that supports Docker.

Step 5: Use Docker Compose to deploy the app

If you prefer a more streamlined approach to deploying your app, you can use Docker Compose to manage your containers. Docker Compose is a tool that allows you to define and run multi-container Docker applications.

To use Docker Compose, you’ll need to create a docker-compose.yml file in the root directory of your project. Here’s an example docker-compose.yml file that you can use with the Dockerfile provided earlier:

version: '3'

services:
 my-react-app:
 build:
 context: .
 dockerfile: Dockerfile
 ports:
 - "80:80"
 volumes:
 - ./ngnix.conf:/etc/nginx/conf.d/default.conf

In this docker-compose.yml file, we define a single service named my-react-app. We specify the build context as the current directory (.), and the name of the Dockerfile as Dockerfile. We also map port 80 in the container to port 80 on the host machine using the ports configuration.

Finally, we mount a volume that maps the ngnix.conf file on the host machine to the default.conf file in the container’s Nginx configuration directory. This allows us to customize the Nginx configuration without having to rebuild the Docker image.

To use this docker-compose.yml file, simply navigate to the directory containing the file and run the following command:


docker-compose up -d

This command tells Docker Compose to build the my-react-app service using the Dockerfile and run a container. The -d flag runs the container in detached mode, which means that it runs in the background. You can then access your React app by navigating to http://localhost in your web browser.

Congratulations! You have successfully deployed a React app with Nginx using Docker and Docker Compose. You can now easily deploy your React apps to any server or hosting platform that supports Docker.

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

How to learn something very well

Wed, 09 Mar 2022 10:01:10 +0300

When you learn how to learn, you unlock almost all the possibilities in the world with knowledge. Some of you can think practice more important than knowledge, but trust me, if you don’t know something about your working area, you won’t get practice, and if you can, it won’t work, because you don’t know the underlying processes.

This guide is simple and results oriented, you can learn more about it with this great book.

Before the learning

Mind is not fixed and can be developed, not only mind and IQ, intellectual skills also be developed with working. First of all you must have iron-strong self discipline, this can be earned in different ways, but you must find and follow your own path. If you wish, you can follow the military discipline methods, or you can stay loyal to the Far East philosophies. It’s entirely up to you.

And remember, valuable things like money accumulate. This includes knowledge, and the more you learn new things, the easier it is to learn and make sense of new things.

Not the learning

Studying the same subject over and over, reading the same things over and over can create a sense of learning, but this is most likely a wrong feeling. sense of learning and fluency can easily be confused with each other.

Don’t go ahead without testing yourself, you might think you learned that way, but most likely it also will be a false feeling.

Things to do

Recalling from memory is a much more wonderful method compared to methods such as repeated reading. When reading articles, pause at the beginning of sentences or paragraphs and ask, “What is the main idea? What is the message you want to give?” asking questions like this is a great practice for our callback method. In this way, mental connections related to the subjects learned will be strengthened.

End-of-chapter questions and self-created questions are great learning methods. It can be used here in quizzes and exams, Using Quizzes as a learning tool may be unorthodox in terms of danger, but works very well for recall and your answers to the questions are important. You can reveal your shortcomings in this way and completing these areas will move you forward.

These two methods are all about callback. The final word on the recall is that the more challenging, the more permanent its effects will be.

Instead of using the short-term benefits of block work, approaching the subject with intermittent work will make the knowledge more permanent. The required range depends on the subject and person being studied. Like 1 day, 1 week, 1 month. Trying to remember a subject periodically makes it permanent in the memory and now it becomes like a reflex.

Solving similar questions on a math topic one after another creates a feeling of familiarity, but it does not help you see the differences and similarities with other questions on the same topic at the time of practice. If you notice that you are repeating questions while solving questions, immediately switch to different types of questions.

Adding new layers of meaning to the subject you are learning is elaboration. An example of this is expressing a topic in your own words while taking notes and examining its relationship with real life. Examining the relationship of the newly learned subject with what you have learned before increases learning. Relate the topic to yourself and your life.

Produce before learning. Trying to solve a math question with what you know before the answer is given makes it easier for you to grasp and remember the solution after the solution is explained.

Blend recall and detailing. After a topic or class, ask yourself, “How did it go? Could it be better? Does this remind you of something from the past?” Asking questions like these helps learning, and this is called reflection.

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.

5 Core Philosophies That Every Developer Should Have

Sun, 26 Sep 2021 00:00:00 +0300

I myself think that software is a philosophy of life before it is a job, and I take great pleasure in approaching most of the problems in my life as a software developer and solving them that way. In this article, I will talk about the cornerstones of this philosophy.

Be a responsible person
Don’t ruin anything in your code
Don’t be a perfectionist
Your asset is your knowledge
Develop your community!

Be a responsible person

As a programmer, if there is an error in the JavaScript code you write, you cannot say that the reason for this error is C++ compiler. This may sound a nonsense, but consider adapting this situation to yourself!

Before you take a job, plan the requirements of that job well because that doesn’t happen when you’ve come a long way in the project and when you go to a client or your boss they ask you a valid question, “why didn’t you think of this before” If there’s a mistake and you’re going to explain it, be prepared for any questions It would be good because it can help you get out of such situations. But the answer you give should definitely not be something “that is impossible to do!”. You should try to offer different solution alternatives suitable for that problem.

Don’t ruin anything in your code

Think of software like a building, if a window in an apartment is broken and not repaired, if another window is broken and no one cares, this will continue and eventually graffiti will appear on the walls and the building will start to go completely disorganized. Later; never live with a broken glass. This example of broken glass for software can be bad design, and a poor code that can lead to future bugs.

Actually this situation is quite scientific, if you think about entropy in physics, disorder always wants to increase. It is up to you to not allow this. If there is a bug in the software, focus on fixing it before adding a new feature and keep going.Don’t say you can’t do it, say you did.

Don’t be a perfectionist

If you have a great idea, after a year or two of working on it and publishing it, it can be incredibly disappointing to learn from the feedback that it’s a really worthless idea. Before making flawless progress on any project, it makes much more sense to have an MVP with the core features of that project and release it, evaluate the feedback, and if all is well, keep moving forward.

In short, perfectionism usually doesn’t work for software. It’s a better idea to be sure of the product first and then perfect it. As a result, the world is changing every day and new technologies and products are emerging every minute!

Your asset is your knowledge

Your knowledge and experience is your most important asset. But these assets may be out of date, especially in the world of technology, everything is changing very quickly. The valuable assets you owned 1 year ago may now be worthless. That’s why you should focus on staying up to date.

Managing a portfolio of knowledge and experience is like managing financial assets and has certain requirements;

Serious investors invest regularly as a habit: if you invest regularly, whether you make a little or a lot, you will get a huge profit in total in return.
Diversification is the key to long-term success: The more technology you are comfortable with, the better you can adapt to change.
Smart investors balance their portfolios between low risk, low return and high risk, high return investments: Investing your entire asset (time and effort) in a high return asset that you think will be valuable in the future. Instead, branch your entity into secure branches and don’t put your entire entity in the same box.
Investors try to buy low and sell high for maximum returns: investing in assets that you think will appreciate in the future can yield big returns.
Portfolios should be reviewed and rebalanced periodically: We do business in a highly volatile industry, so you should regularly review your investments and watch out for depreciating assets.

But the most important and indispensable of all these goals is to invest regularly. If you don’t invest, it doesn’t make any sense where you invest. Here are a few tools you can use as a tool to achieve these goals.

Learn at least one new language every year. Different languages solve the same problems in different ways. Learning a few different approaches can help broaden your thinking and avoid getting stuck in a routine.
Read a technical book every quarter. Once you get used to it, read a book a month. Once you’ve mastered the technologies you’re currently using, branch out and work on some unrelated branches.
Read in non-technical books either. Computers are for humans, and if you can understand humans better, you can approach their solutions much better.
Join local user groups. Don’t just go and listen, participate actively. Isolation can be fatal to your career.

It doesn’t matter if you’ve used any of the technologies you’ll learn about in a project or even put it on your resume. Learning these will increase your learning ability and contribute to your problem solving ability.

When you encounter a problem and you don’t know the answer to it, choose it as a goal and try to learn it. Ask a guru, if he isn’t around, find one online. This will both answer the problem and expand its network. Keep learning constantly. Carry and evaluate something to read in dead moments like traveling on the bus.

Just as the product that a bookstore is marketing to you is not the best product it has, but a product it is only trying to sell, don’t rely on the content that comes first in search engines, think about its accuracy. and weigh it in your mind and never accept it without question.

Develop your community!

A good idea is an orphan when you don’t have effective communication. As developers, we use our communication skills when communicating with end users or creating documentation, communicating with our bosses or superiors. Here are a few ways to strengthen your communication skills;

Your job as a programmer is not to play word games, but to convey the information you want accurately and clearly. Plan what you want to say. Write a draft. Then ask yourself, “Does this encompass everything I’m trying to say?” Repeat until you meet this requirement. Make this plan not just when writing a document, but before meetings and speeches, even before meeting with clients you care about.
If you can convey information, you can ensure correct communication. Therefore, you need to determine the level of knowledge that the other person can meet.
There are various ways of communication. Some customers may want to be informed by e-mail, while others may want to be called by phone.
If you want to be listened to by people, the first thing you will do is listen to them. If you can turn a meeting into a dialogue, there’s no better than you.
Don’t make people wait by saying I will get back to you, I will answer as soon as possible.

Conclusion

Thank you for reading! 🎉 In order not to miss my research in the field of software development, you can follow me at @berkslv.