
<Sponsorships>

Today's issue is sponsored by [**Localizely**](https://localizely.com/?utm_source=milanjovanovic.tech&utm_medium=email&utm_campaign=website),
the translation management platform that helps you translate texts in your app for
[**targeting multilingual markets.**](https://localizely.com/?utm_source=milanjovanovic.tech&utm_medium=email&utm_campaign=website)

And by [**Hasura**](https://hasura.io/graphql/database/sql-server/?utm_source=newsletter&utm_medium=email&utm_campaign=milan-dotnet-weekly),
an open-source engine that gives
[**instant GraphQL and REST APIs**](https://hasura.io/graphql/database/sql-server/?utm_source=newsletter&utm_medium=email&utm_campaign=milan-dotnet-weekly)
on new or existing SQL Server, enabling teams to ship apps faster.

</Sponsorships>

Although **C#** is an **object-oriented programming** language, it received many new functional features in recent versions.

To mention just a few of these features:

- Pattern matching
- Switch expressions
- Records

You're probably already doing **functional programming** without even knowing it.

Do you use LINQ?
If you do, then you're doing functional programming.
Because LINQ is a functional .NET library.

In today's issue, I will show you how to **refactor** some **imperative code** with **functional programming**.

Let's dive in.

## Benefits Of Functional Programming

Before we take a look at some code, let's see what are the **benefits** of using **functional programming**:

- Emphasis on immutability
- Emphasis on function purity
- Code is easier to reason about
- Less prone to bugs and errors
- Ability to compose functions and create higher-order functions
- Easier to test and debug

From my experience, I think functional programming is more enjoyable once you get used to it.
Starting out, it feels strange because your old object-oriented programming habits will kick in.
But after a while, **functional programming** feels easier to work with than imperative code.

## Starting With Imperative Code

**Imperative programming** is the most basic programming approach.
We describe a step-by-step process to execute a program.
It's easier for beginners to reason with imperative code by following along with the steps in the process.

Here's an example of an `EmailValidator` class written with imperative code:

```csharp
public class EmailValidator
{
    private const int MaxLength = 255;

    public (bool IsValid, string? Error) Validate(string email)
    {
        if (string.IsNullOrEmpty(email))
        {
            return (false, "Email is empty");
        }

        if (email.Length > MaxLength)
        {
            return (false, "Email is too long");
        }

        if (email.Split('@').Length != 2)
        {
            return (false, "Email format is invalid");
        }

        if (Uri.CheckHostName(email.Split('@')[1]) == UriHostNameType.Unknown)
        {
            return (false, "Email domain is invalid");
        }

        return (true, null);
    }
}
```

You can clearly see the distinct steps:

- Check if email is null or empty
- Check if email is not too long
- Check if email format is valid
- Check if email domain is valid

Let's see how we can refactor this using **functional programming**.

## Applying Functional Programming

The basic building block in **functional programming** is - **a function**.
And programs are written by composing function calls.
There are a few other things you need to keep in mind, like keeping your functions pure.
A function is pure if it always returns the same output for the same input.

We can capture each step from the imperative version of `EmailValidator` with a `Func` delegate.
To also capture the respective error message together with the validation check, we can use a tuple.
And since we know all of our validation steps, we can create an array of `Func` delegates to store all of the individual **functions**.

```csharp
public class EmailValidator
{
    const int MaxLength = 255;

    static readonly Func<string, (bool IsValid, string? Error)>[] _validations =
    {
        email => (!string.IsNullOrEmpty(email), "Email is empty"),
        email => (email.Length <= MaxLength, "Email is too long"),
        email => (email.Split('@').Length == 2, "Email format is invalid"),
        email => (
            Uri.CheckHostName(email.Split('@')[1]) != UriHostNameType.Unknown,
            "Email domain is invalid")
    };

    static readonly (bool IsValid, string? Error) _successResult = (true, null);

    public (bool IsValid, string? Error) Validate(string email)
    {
        var validationResult = _validations
            .Select(func => func(email))
            .FirstOrDefault(func => !func.IsValid);

        return validationResult is { IsValid: false, Error: { Length: >0 } } ?
            validationResult : _successResult;
    }
}
```

Notice that this allows us to do all sorts of interesting things with the `_validations` array.
How hard would it be to modify this function to return _all of the errors_ instead of just the first one?

If you're thinking we can use LINQ's `Select` method somehow, you're thinking in the right direction.

## Further Reading

We only scratched the surface of what functional programming is, and what you can do with it.
If you want to learn more, here are some learning materials:

- [Functional Programming in C#, by Enrico Buonanno](https://www.manning.com/books/functional-programming-in-c-sharp)
- [Functional Programming With C# Using Railway-Oriented Programming](https://youtu.be/dDasAmowFts)
- [How Function Composition Can Make Your Code Better](https://youtu.be/zuy2j8vxgYc)
- [Make Your ASP.NET Core API Controllers Incredibly Simple With Functional Programming](https://youtu.be/AVA2mKG4WOc)

Thank you for reading, and have a wonderful Saturday.

---



<Sponsorships>

[**Localizely**](https://localizely.com/?utm_source=milanjovanovic.tech&utm_medium=email&utm_campaign=website) is a translation management platform that
helps you translate texts in your app for targeting multilingual markets.

</Sponsorships>

Working with **Microservices**, or any distributed system for that matter, is difficult.
In a distributed system many things can go wrong, and there are even research papers about this.
If you want to explore this topic further, I suggest that you read about the [fallacies of distributed computing](https://www.se.rit.edu/~se442/doc/fallacies.pdf).

Reducing the surface area for things to go wrong should be one of your goals, as an engineer.
In this week's newsletter, we'll try to achieve exactly that using the **Outbox pattern**.

How can you implement reliable communication between components in a distributed system?

The **Outbox pattern** is an elegant solution to this problem, allowing you to achieve transactional
guarantees in a single service and at-least-once message delivery to external systems.

Let's see how the **Outbox pattern** solves this and how can we implement it.

## What Problem Does The Outbox Pattern Solve?

To understand what problem the **Outbox pattern** solves, first we need a problem, of course.

Here's an example of a user registration flow.
There are a few things going on here:

- Saving the `User` to the database
- Sending a welcome email to the `User`
- Publishing a `UserRegisteredEvent` to a message bus

```csharp
public async Task RegisterUserAsync(User user, CancellationToken token)
{
    _userRepository.Insert(user);

    await _unitOfWork.SaveChangesAsync(token);

    await _emailService.SendWelcomeEmailAsync(user, token);

    await _eventBus.PublishAsync(new UserRegisteredEvent(user.Id), token);
}
```

In the happy path, all of the operations complete without any issues and all is well.

But what happens if any one of these operations fail?

- The database is unavailable, and saving the `User` fails
- The email service is down and sending an email crashes
- Publishing an event to the service bus doesn't succeed

Also, imagine a situation where you manage to save a `User` to the database,
send him a welcome email, but fail to publish the `UserRegisteredEvent` to notify other services.
How are you going to recover from this scenario?

The **Outbox pattern** allows you to **atommically** update the database and send messages to the message bus.

## Implementing The Outbox Pattern

The first step is to introduce a table in your database to represent the **Outbox**.
We can call this table `OutboxMessages`, and it's intended to store all messages that need to be delivered.
Now instead of directly making requests to external services, we simply store a message as a new row in the **Outbox** table.
The messages are usually stored as JSON in the database.

The second step is to introduce a **background process** that will periodically poll the `OutboxMessages` table.
If the worker process finds a row with an unprocessed message, it's going to publish that message and mark it as sent.
If publishing the message fails for some reason, the work process can **retry** in the next execution.

Notice that with retries, you now have **at-least-once message delivery** implemented.
The message will be published exactly once for the happy path, and more than one time in case or retries.

We can rewrite the `RegisterUserAsync` method from the previous example, now using an **Outbox**:

```csharp
public async Task RegisterUserAsync(User user, CancellationToken token)
{
    _userRepository.Insert(user);

    _outbox.Insert(new UserRegisteredEvent(user.Id));

    await _unitOfWork.SaveChangesAsync(token);
}
```

The **Outbox** is part of the same transaction as our unit of work, so we can atomically save the `User` to the database
and also persist the `OutboxMessage`.
If saving to the database fails, the entire transaction is rolled back and no messages are sent to the message bus.

And since we now moved the publishing of the `UserRegisteredEvent` to the worker process, we need to add a handler
so that we can send the welcome email to the user.
Here's an example of that in the `SendWelcomeEmailHandler` class:

```csharp
public class SendWelcomeEmailHandler : IHandle<UserRegisteredEvent>
{
    private readonly IUserRepository _userRepository;
    private readonly IEmailService _emailService;

    public SendWelcomeEmailHandler(
        IUserRepository userRepository,
        IEmailService emailService)
    {
        _userRepository = userRepository;
        _emailService = emailService;
    }

    public async Task Handle(UserRegisteredEvent message)
    {
        var user = await _userRepository.GetByIdAsync(message.UserId);

        await _emailService.SendWelcomeEmailAsync(user);
    }
}
```

## Architecture Diagram With Outbox

Here's a high level overview of the system architecture with the **Outbox** introduced to the system.
You can see the `Outbox` table in the database.
What changes now is that you store messages to the `Outbox` table in the same transaction along with your entities.

<Image src="blogs/mnw_026/outbox.png" width={1801} height={989} />

## Further Reading

After reading this newsletter you should have a pretty good understanding of what the **Outbox pattern** is
and what problems it solves.
If you need to implement reliable messaging in a distributed system, it's a great solution for your problem.

What's missing is more details about how to implement the **Outbox pattern**, so here are a few videos you can watch:

- [How to use the Domain Events pattern](https://youtu.be/BimfDeDV4yU)
- [How to implement the Outbox pattern](https://youtu.be/XALvnX7MPeo)
- [How to add retries to the Outbox with Polly](https://youtu.be/xajVttkZntU)

Thanks for reading, and have an amazing Saturday.

---



<Sponsorships>

[**QuadSpinner Highlighter**](https://github.com/QuadSpinner/Highlighter) is an open-source
Visual Studio extension that lets you highlight important objects and arbitrary texts
to help you navigate your code more easily.

</Sponsorships>

**Structured logging** is a practice where you apply the same message format to all of your
application logs.
The end result is that all your logs will have a similar structure, allowing them to be
easily searched and analyzed.

[Serilog](https://serilog.net/) is a popular logging library in .NET, packed with many features.
It provides logging to files, logging to the console, and elsewhere.

However, **Serilog** is unique because it comes with support for **structured logging** out of the box.

Let's see how we can install **Serilog** and configure it an **ASP.NET Core** application.

## Installing Serilog

To install **Serilog** in **ASP.NET Core** you can add the following NuGet package:

```powershell
Install-Package Serilog.AspNetCore
```

This NuGet packages comes with a simple API to integrate **Serilog** into your application.
You can call the `UseSerilog` method on the `HostBuilder` instance to provide a lambda
method to configure **Serilog**.

I think the most flexible way to configure Serilog is through application settings,
which is achieved by calling `ReadFrom.Configuration()`.

You can also call the `UseSerilogRequestLogging()` method to introduce automatic HTTP request logging
in your API.

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Host.UseSerilog((context, configuration) =>
    configuration.ReadFrom.Configuration(context.Configuration));

var app = builder.Build();

app.UseSerilogRequestLogging();

app.Run();
```

The next question is how do you provide the actual configuration values to **Serilog**?

## Configuring Serilog With `appsettings.json`

You need to add a `Serilog` section in your `appsettings.json` file.

Here you can configure, among other things:

- Which **sinks** to use with **Serilog**
- Override default and minimum log levels
- Configure file logging arguments

In this example, we're adding the `Console` and `File` sinks to **Serilog**.
And we're adding some additional configuration for the `File` sink in the `Serilog.WriteTo` configuration section.
We can configure the output path for the log files, the naming format, which formatter to use for the logs and so on.

```json
"Serilog": {
  "Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ],
  "MinimumLevel": {
    "Default": "Information",
    "Override": {
      "Microsoft": "Warning",
      "System": "Warning"
    }
  },
  "WriteTo": [
    { "Name": "Console" },
    {
      "Name": "File",
      "Args": {
        "path": "/logs/log-.txt",
        "rollingInterval": "Day",
        "rollOnFileSizeLimit": true,
        "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"
      }
    }
  ],
  "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ]
}
```

You can get a more detailed overview of what's supported with the `Serilog.Configuration` library in the
[documentation](https://github.com/serilog/serilog-settings-configuration).

## Using Serilog In ASP.NET Core

We managed to successfully install and configure **Serilog**.
But how do we actually use it?

**Serilog** integrates with the `ILogger` interaface coming from the `Microsoft.Extensions.Logging` namespace.
If you're already using `ILogger` for logging, everything will continue working correctly.

Here's a simple example of logging inside of a Minimal API endpoint:

```csharp
app.MapGet("/serilog-is-cool", (ILogger logger) =>
{
    logger.LogInformation("This is a log inside of the Minimal API endpoint.");

    return Results.Ok(new { Message = "success" });
});
```

You just inject an `ILogger` or `ILogger<T>` instance and Serilog will provide its own implementation at runtime.

## Structured Logging Syntax

The idea behind **structured logging** is that you can introduce additional contextual information inside
of your logs.
**Serilog** does this using a message template syntax, where you can specify named parameters and then
pass in their values separately.

Here's an example of what this message template would look like.
You specify parameters inside of curly bracers and provide a name, for example `{NamedParameter}`.
The value provided for the parameter will be serialized as a property inside of the corresponding
structured log.

```csharp
var book = new { Author = "Domain-Driven Design", Title = "Eric Evans" };
var orderNumber = 1;

log.LogInformation(
    "Processing book {@Book}, order number = {@OrderNumber}",
    book,
    orderNumber);
```

There are a few things to unpack here:

- `{@Book}` parameter which accepts an object
- `{OrderNumber}` parameter which accepts a scalar value

The `@` operator in front of `Book` tells Serilog to serialize the object passed in, instead of converting
it using `ToString()`.

## Benefits Of Structured Logging

Lastly, I want to highlight what are some of the benefits of **structured logging** and why you should be using it.

As I said at the beginning, the main idea with **structured logging** is that all log message follow the same
structure.
This structure can be a JSON document for example, or a row in a relational table.
Since structured logs are in a machine-readable format, it's much easier to search through them for
specific information.

When an error occurs, structured logs can provide more context and details about the error, making it easier to
identify the root cause and fix the problem.

It's very easy to start doing structured logging with **Serilog**, and I hope you'll give it a try.

See you next week, and have an excellent Saturday.

---



If you're working in a **distributed system**, you need to be able to communicate between
multiple services.
There are a few ways that you can implement this.
Depending on your chosen approach, you can either introduce tight coupling between your
services or stay **loosely coupled**.

**Loose coupling** is an important quality in distributed systems.
It allows you to evolve your services independently.
So how do you implement loosely coupled **communication between services**?

You need a **messaging system**.

And [Azure Service Bus](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview)
is an excellent choice.

In this week's newsletter, I'll show you how to create an **Azure Service Bus** instance,
and how to implement messaging over a **queue**.

Let's dive in.

## Creating An Azure Service Bus Instance

You can create a new **Azure Service Bus** instance from the **Azure** portal.

I won't go into detail on that, since I find the **Azure** UI pretty intuitive.

<Image src="blogs/mnw_024/service_bus.png" width={898} height={695} />

After creating your **Azure Service Bus** instance, you'll need to do two more things:

- Create a new **queue**
- Find the **connection string**

After that you can proceed with implementing the pub-sub pattern over a queue.
And you'll use the connection string from the Azure portal for connecting to the Azure Service Bus instance.

## Publishing Messages To The Azure Service Bus Queue

The first thing we need to do is to create the publishing side of our system, and then
we'll see how we can process messages.
We're going to use the `Azure.Messaging.ServiceBus` library to connect to the queue
running in Azure Service Bus.

You can install the NuGet package by running the following command:

```powershell
Install-Package Azure.Messaging.ServiceBus
```

And now, let's write the code for publishing a message to an Azure Service Bus queue.

To work with the Azure Service Bus instance, you will use the [`ServiceBusClient`](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusclient?view=azure-dotnet)
class.
It requires a connection string to be able to connect to the Azure Service Bus instance.

The `ServiceBusClient` is safe to cache and reuse in the application, so it can be registered
as a service with the singleton lifetime.

With the `ServiceBusClient` you can create a [`ServiceBusSender`](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebussender?view=azure-dotnet)
instance, which is responsible
for sending the actual messages.
You also need to specify which queue it will be sending messages to.
This can also be the name of a topic, if you are publishing to a topic instead.

```csharp
using Azure.Messaging.ServiceBus;

await using var client = new ServiceBusClient(ConnectionString);

await using ServiceBusSender sender = client.CreateSender(QueueName);

// This will be the payload for the message ✉️
var productCreated = new ProductCreatedEvent(
    eventId: Guid.NewGuid(),
    product.Id,
    product.Name);

string json = JsonSerializer.Serialize(productCreated);

var message = new ServiceBusMessage(json);

await sender.SendMessageAsync(message);
```

As you can see, publishing a message to the queue is relatively simple.

We're creating a new instance of `ProductCreatedEvent`, which represents our message payload.
The payload itself is serialized into a `JSON` string, wrapped inside a `ServiceBusMessage`.

For publishing messages to Azure Service Bus, you simply call the `SendMessageAsync` method.

## Receiving Messages From The Azure Service Bus Queue

Publishing messages to a queue is only half of the job.
You also need to be able to receive messages from the queue.
However, you'll see that this is very similar to the publishing side.

On the receiving side, you'll also need to create a `ServiceBusClient`.
And then use it to create an instance of [`ServiceBusProcessor`](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusprocessor?view=azure-dotnet),
which is used for consuming messages.
You need to tell the `ServiceBusProcessor` which queue it will subscribe to.

The `ServiceBusProcessor` exposes two events, which represent callbacks for when a message is received.
These events are [`ProcessMessageAsync`](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusprocessor.processmessageasync?view=azure-dotnet)
and [`ProcessErrorAsync`](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusprocessor.processerrorasync?view=azure-dotnet).

You need to provide a handler for these two events, to properly consume messages from the queue.
In the example below, we're using the `HandleMessageAsync` and `HandleErrorAsync` local functions.

```csharp
using Azure.Messaging.ServiceBus;

await using var client = new ServiceBusClient(ConnectionString);

await using ServiceBusProcessor processor  = client.CreateProcessor(QueueName);

processor.ProcessMessageAsync += HandleMessageAsync;

processor.ProcessErrorAsync += HandleErrorAsync;

await processor.StartProcessingAsync();

async Task HandleMessageAsync(ProcessMessageEventArgs args)
{
    string json = args.Message.Body.ToString();

    var productCreated = JsonSerializer.Deserialize<ProductCreatedEvent>(json);

    Console.WriteLine(productCreated);

    await args.CompleteMessageAsync(args.Message);
}

Task HandleErrorAsync(ProcessErrorEventArgs args)
{
    var exception = args.Exception;

    Console.WriteLine(exception.ToString());

    return Task.CompletedTask;
}
```

The `ServiceBusProcessor` begins listening to messages coming from the queue after calling the `StartProcessingAsync` method.

Notice that the success and error event handlers need to accept the
[`ProcessMessageEventArgs`](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.processmessageeventargs?view=azure-dotnet)
and [`ProcessErrorEventArgs`](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.processerroreventargs?view=azure-dotnet),
respectively.

From the `ProcessMessageEventArgs` you can access the `Message.Body` which contains the mesage payload.

## Further Reading

**Azure Service Bus** is a very feature rich service cloud.
I showed you how to work with **queues**, which are great if you only have one publisher and one subscriber.
However, if you need the ability to have multiple subscribers to a single message, you can't achieve
this with queues.

You will have to use [topics](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions),
and I invite you to research this _topic_ further (pun intended).

**Azure Functions** have excellent support for integrating with **Azure Service Bus**.
You can define a `QueueTrigger` that will run your **Azure Function** when you receive a message to an Azure Service Bus **queue**.

I also released a video showing how to [publish and consume messages using RabbitMQ](https://youtu.be/CTKWFMZVIWA),
and I think you might enjoy it after reading this newsletter.

Have an excellent weekend, and stay awesome!

---



<Sponsorships>

[**Ultimate ASP.NET Core Web API - Second Edition**](https://code-maze.lemonsqueezy.com/checkout/buy/b0e9ff04-cb9f-4bc2-a69b-d434fad56790)
is a step-by-step and easy-to-digest guide to creating scalable, robust, and high-performance Web APIs.

[**QuadSpinner Highlighter**](https://github.com/QuadSpinner/Highlighter) is an open-source
Visual Studio extension that lets you highlight important objects and arbitrary texts
to help you navigate your code more easily.

</Sponsorships>

Every software engineer working with **SQL databases** needs to know about **transactions**.
And since most of the time the **SQL database** will be abstracted by an ORM like **EF Core**,
it's important to understand how you can work with **transactions** using the available
abstractions.

So today, I'll show you how to work with **transactions** in **EF Core**.

Here's what we will cover:

- Default transaction behavior
- Creating transactions
- Using existing transactions

Let's dive in.

## Default Transaction Behavior

What is the **default** EF Core **transaction behavior**?

By default, all changes made in a single call to `SaveChanges` are applied in a
transaction. If any of the changes fail, the entire transaction is rolled back
and no changes are applied to the database. Only if all changes are successfully
persisted to the database, the call to `SaveChanges` can complete.

This is a wonderful feature of **SQL databases** and it saves us many headaches.
We don't have to think about the databases remaining in an inconsistent state,
because database **transactions** can do the work for us.

Let's take a look at an example.

```csharp
using var context = new ShoppingContext();

context.LineItems.Add(new LineItem
{
    ProductId = productId,
    Quantity = quantity
});

var stock = context.Stock.FirstOrDefault(s => s.ProductId == productId);

stock.Quantity -= quantity;

context.SaveChanges();
```

Because we are adding a `LineItem`, and in the same scope reducing the `Stock`
quantity, the call to `SaveChanges` will apply both changes inside of a transaction.
We can guarantee that the database will remain in a **consistent state**.

## Creating Transactions With EF Core

What if you want to have more control over **transactions** when working with **EF Core**?

You can manually create a transaction by accessing the `Database` facade available
on a `DbContext` instance and calling `BeginTransaction`.

Here's an example where we have multiple calls to `SaveChanges`. In the default
scenario, both calls would run in their own transaction. This leaves the possibility
of the second call to `SaveChanges` failing, and leaving the database in an
inconsistent state.

```csharp
using var context = new ShoppingContext();
using var transaction  = context.Database.BeginTransaction();

try
{
    context.LineItems.Add(new LineItem
    {
        ProductId = productId,
        Quantity = quantity
    });

    context.SaveChanges();

    var stock = context.Stock.FirstOrDefault(s => s.ProductId == productId);

    stock.Quantity -= quantity;

    context.SaveChanges();

    // When we commit the changes, they will be applied to the databases.
    // The transaction will auto-rollback when it is disposed,
    // if any command fails.
    transaction.Commit();
}
catch (Exception)
{
    transaction.Rollback();
}
```

We call `BeginTransaction` to manually start a new **database transaction**.
This will create a new transaction and return it, so that we can `Commit` the
transaction when we want to complete the operation. You also want to add a
`try-catch` block around your code, so that you can `Rollback` the transaction
if there are any exceptions.

## Using Existing Transactions With EF Core

Creating a transaction using the EF Core `DbContext` isn't the only option.
You can create a `SqlTransaction` instance and pass it to **EF Core**, so that
the changes applied with EF Core can be committed inside the same **transaction**.

Here's what I mean:

```csharp
using var sqlConnection = new SqlTransaction(connectionString);
sqlConnection.Open();

using var transaction = sqlConnection.BeginTransaction();

try
{
    using var context = new ShoppingContext();

    // Tell EF Core to use an existing transaction.
    context.UseTransaction(transaction);

    context.LineItems.Add(new LineItem
    {
        ProductId = productId,
        Quantity = quantity
    });

    context.SaveChanges();

    var stock = context.Stock.FirstOrDefault(s => s.ProductId == productId);

    stock.Quantity -= quantity;

    context.SaveChanges();

    transaction.Commit();
}
catch (Exception)
{
    transaction.Rollback();
}
```

## In Summary

**EF Core** has excellent support for **transactions** and it's very easy to work with.

You have three options available:

- Rely on the default transaction behavior
- Create a new transaction
- Use an existing transaction

Most of the time, you want to rely on the default behavior and not have to
think about it.

As soon as you need to perform multiple `SaveChanges` calls, you should manually
create a transaction, and manage the transaction yourself.

See you next week, and have an excellent Saturday.

---



In this week's newsletter I want to show you how to implement **API Key authentication**
in **ASP.NET Core**. This authentication approach uses an **API Key** to authenticate the
client of an API. You can pass the **API Key** to the API in a few ways, such as through
the query string or a request header.

I will show you how to implement **API Key authentication** where the **API key** is passed
in a request header. But the implementation would be similar if we were to use any
other approach.

When would you want to use **API Key authentication**? This kind of authentication
mechanism is common in **Server-to-Server (S2S)** communication. When your API serves
request for other server-side applications to consume and integrate with. It's
less common in client-server communication scenarios.

Let's see how we can implement **API Key authentication** in ASP.NET Core!

## Implementing API Key Authentication

We will start off by creating an attribute that we can place on endpoints
where we want to apply **API Key authentication**. It won't be any kind of
attribute, because we will use a `ServiceFilterAttribute`.

What a `ServiceFilterAttribute` allows us to do is specify a type for the
filter that will be created for that attribute.
This means we can implement our authentication logic in an `IAuthorizationFilter`.
With a `ServiceFilterAttribute` we also have support for dependency injection
in our `IAuthorizationFilter` implementation.

Let's first define the `ApiKeyAttribute` class:

```csharp
public class ApiKeyAttribute : ServiceFilterAttribute
{
    public ApiKeyAttribute()
        : base(typeof(ApiKeyAuthorizationFilter))
    {
    }
}
```

In the `ApiKeyAttribute` we specify `ApiKeyAuthorizationFilter` class as the
filter that will be resolved from the DI container. Here's what it looks like:

```csharp
public class ApiKeyAuthorizationFilter : IAuthorizationFilter
{
    private const string ApiKeyHeaderName = "X-API-Key";

    private readonly IApiKeyValidator _apiKeyValidator;

    public ApiKeyAuthorizationFilter(IApiKeyValidator apiKeyValidator)
    {
        _apiKeyValidator = apiKeyValidator;
    }

    public void OnAuthorization(AuthorizationFilterContext context)
    {
        string apiKey = context.HttpContext.Request.Headers[ApiKeyHeaderName];

        if (!_apiKeyValidator.IsValid(apiKey))
        {
            context.Result = new UnauthorizedResult();
        }
    }
}
```

The implementation comes down to validating the **API Key** obtained from
the header of the current request. If we determine that the **API Key**
is not valid, we set the value of `AuthorizationFilterContext.Result`
to a new instance of an `UnauthorizedResult`.

And lastly, all that's left for us to do is implement our custom
validation logic for the **API Key** inside of `ApiKeyValidator`:

```csharp
public class ApiKeyValidator : IApiKeyValidator
{
    public bool IsValid(string apiKey)
    {
        // Implement logic for validating the API key.
    }
}

public interface IApiKeyValidator
{
    bool IsValid(string apiKey);
}
```

The actual implementation for validating the **API Key** will vary based
on your use case, and where you are storing the API keys.
For example, if you store the API keys in the database you would check
if the provided **API Key** exists in the database.
If it exists, then validation passes.
If it doesn't exist, then validation fails and we return an
`UnauthorizedResult`.

## Registering Services With Dependency Injection

We have to make sure to register our `ApiKeyAuthorizationFilter` and
`ApiKeyValidator` services with the dependency injection container.

```csharp
builder.Services.AddSingleton<ApiKeyAuthorizationFilter>();

builder.Services.AddSingleton<IApiKeyValidator, ApiKeyValidator>();
```

This will register them as singleton services in our application.
You can use a different service scope such as `Transient` or `Scoped`
if you need to.

## Applying API Key Authentication To Endpoints

Finally, with our **API Key authentication** in place, we can apply the
`ApiKeyAttribute` attribute to our endpoints:

```csharp
public class NewslettersController : ControllerBase
{
    [ApiKey]
    [HttpGet]
    public IActionResult Get()
    {
        // ...
    }
}
```

In this case I'm applying the `ApiKeyAttribute` to an endpoint, but
you can also apply it on the `NewslettersController` and it will add
authentication to all the endpoints for that controller.

## Next Steps

Now that you know how to implement **API Key authentication**, I think you
should also learn how to implement **JWT authentication**. And while you're
at it, why not throw **authorization** into the mix.

I made a few videos about **JWT authentication** and **permission authorization**
that you should take a look at next:

- [Token Authentication In ASP.NET Core 7 With JWT](https://youtu.be/4cFhYUK8wnc)
- [Introduction To Permission Authorization In ASP.NET Core 7](https://youtu.be/PlbAuNvR16s)
- [Managing Permissions With EF Core Migrations](https://youtu.be/v4vXDRJ9_sg)
- [Implementing A Custom Authorization Handler In ASP.NET Core](https://youtu.be/SZtZuvcMBA0)
- [Using Custom JWT Claims For Authorization In ASP.NET Core](https://youtu.be/SUyFPp6BPV0)

---



<Sponsorships>

[**Dotnetjobs**](https://dotnet-jobs.com/) is a reverse job board that empowers .NET developers available for their next job.
Stop scouring traditional job boards and [**sit back as companies reach out to you first**](https://dotnet-jobs.com/).

</Sponsorships>

In this week's newsletter I want to talk about the `yield` keyword in **C#**.
I think it's a powerful **C#** feature and I wanted to highlight the benefits.

The `yield` keyword tells the compiler that the method in which it appears
is an **iterator block**. An iterator block, or method, returns an `IEnumerable`
as the result. And the `yield` keyword is used to return the values for the
`IEnumerable`.

An interesting thing aboug `IEnumerable` is that it is lazily evaluted.
Calling a method with an iterator block doesn't run any code. It's only
when the `IEnumerable` is iterated over, or enumerated, that we get
the actual values. I'll talk about this more later.

Let's see how we can start using the `yield` keyword!

## How To Use The Yield Keyword

The `yield` keyword on it's own doesn't do anything, you have to combine
it with the `return` or `break` statement:

- `yield return` - provides the next value of the iterator
- `yield-break` - signals the end of iteration

In every project I worked on, there's a piece of code similar to the
following. You create a list to hold the results, add elements to the
list, and return the list in the end.

```csharp
var engineers = GetSoftwareEngineers();

public IEnumerable<SoftwareEngineer> GetSoftwareEngineers()
{
    var result = new List<SoftwareEngineer>();

    for(var i = 0; i < 10; i++)
    {
        result.Add(new SoftwareEngineer
        {
            Id = i
        });
    }

    return result;
}
```

You can simplify the method using the `yield return` statement, and
completely remove the intermediate list required to hold the results.

```csharp
var engineers = GetSoftwareEngineers();

public IEnumerable<SoftwareEngineer> GetSoftwareEngineers()
{
    for(var i = 0; i < 10; i++)
    {
        yield return new SoftwareEngineer
        {
            Id = i
        };
    }
}
```

However, it's important to note these two implementation are fundamentally
different from each other. In the first example, the entire list is
populated and materialized. In the second example, the `IEnumerable`
returned will not be materialized and you have to either iterate over
it inside a `foreach` loop or call `ToList()`.

## Stopping Iteration With Yield Break

You can use the `yield break` statement to stop iteration and exit
the iterator block. Typically you would do this when a certain
condition is met, or you only want to return a specific set of values
from the iterator block.

Here's an example where this would be useful:

```csharp
Console.WriteLine(string.Join(", ", TakeWhilePositive(new[] { 1, 2, -3, 4 })));
// Output: 1, 2

public IEnumerable<int> TakeWhilePositive(IEnumerable<int> numbers)
{
    foreach(int num in numbers)
    {
        if (num > 0)
        {
            yield return num;
        }
        else
        {
            yield break;
        }
    }
}
```

## Working With IAsyncEnumerable

In **C# 8** we got the `IAsyncEnumerable` type which allows us to
iterate over a collection asynchronously with the `yield` statement.

For example, this can be useful when you want to call a thid-party
API multiple times to fetch some data. A common situation is when
you get a list of users from the database, and then have to call
an external storage service to get profile picture information.

Without `IAsyncEnumerable` you would have to do something like this:

```csharp
public async Task<IEnumerable<User>> GetUsersAsync()
{
    var users = await GetUsersFromDbAsync();

    foreach(var user in users)
    {
        user.ProfileImage = await GetProfileImageAsync(user.Id);
    }

    return users;
}

// And you would call the method like this.
var users = await GetUsersAsync();

foreach(var user in users)
{
    Console.WriteLine(user);
}
```

Now, consider this same example with the use of `IAsyncEnumerable`:

```csharp
public async IAsyncEnumerable<User> GetUsersAsync()
{
    var users = await GetUsersFromDbAsync();

    foreach(var user in users)
    {
        user.ProfileImage = await GetProfileImageAsync(user.Id);

        yield return user;
    }
}

// And you would call the method like this.
await foreach(var user in GetUsersAsync())
{
    Console.WriteLine(user);
}
```

The second implementation will iterate over the users returned from
the database when they are yielded by the `IAsyncEnumerable`.

## When Should I Use Yield?

I've found a few interesting practical applications for the `yield` keyword.
One example is when implementing Domain-Driven Design value objects.

Value objects need to support structural equality. They need to implement
a method that returns all of the equality components. Here's an example of
that using the `yield return` statement:

```csharp
public class Address
{
    public string City { get; init; }

    public string Street { get; init; }

    public string Zip { get; init; }

    public string Country { get; init; }

    public IEnumerable<object> GetEqualityComponents()
    {
        yield return City;
        yield return Street;
        yield return Zip;
        yield return Country;
    }
}
```

---



<Sponsorships>

Have some [**C# and .NET experience**](https://packt.link/PJqza), and want to get started building apps?
Get introduced to the most common technologies like gRPC, Blazor, GraphQL, Cosmos DB, SignalR, .NET MAUI, and more in
[**Apps and Services with .NET 7**](https://packt.link/PJqza).

[**QuadSpinner Highlighter**](https://github.com/QuadSpinner/Highlighter) is an open-source
Visual Studio extension that lets you highlight important objects and arbitrary texts
to help you navigate your code more easily.

</Sponsorships>

In this week's newsletter I want to introduce you to an interesting feature
in **EF Core** called **Compiled Queries**.

If you have queries that you execute frequently in your application with a
different set of parameters, it can be helpful to explicitly compile the
query and reuse it throughout the lifetime of your application.

**Compiled Queries** are more performant than standard EF queries, because they
can take advantage of some additional optimizations.

Let me show you how to use **Compiled Queries**, and how much performance
improvement to expect!

## How To Create Compiled Queries

Lets define a simple class that will represent out data model that we will
use for writing **EF** queries:

```csharp
public class Newsletter
{
    public long Id { get; init; }

    public string Title { get; init; }

    public int ReadTimeInMinutes { get; init; }
}
```

How would we write a simple query to fetch a `Newsletter` by the `Id`?
I think you can do this in your sleep.

```csharp
using var dbContext = new AppDbContext();

var newsletter = dbContext.Set<Newsletter>().FirstOrDefault(n => n.Id == id);
```

Now, how do we convert this query into a **Complied Query**?

There are a few steps involved:

- Create a **Compiled Query** by calling `EF.CompileQuery`
- Store the **Compiled Query** in a static field, so that it can be reused
- Execute the database query using the **Compiled Query**

You can define the **Compiled Query** in a static field inside of the `AppDbContext`.
And then expose a method that will accept an argument, and pass it to the
**Compiled Query** to invoke it.

```csharp
using Microsoft.EntityFrameworkCore;

public class AppDbContext
{
    private static Func<AppDbContext, long, Newsletter?> GetNewsletter =
        EF.CompileQuery(
            (dbContext, id) =>
                dbContext.Set<Newsletter>().FirstOrDefault(n => n.Id == id));

    public Newsletter? GetNewsletter(long id)
    {
        return GetNewsletter(this, id);
    }
}
```

This is how we would call the method which invokes the **Compiled Query**:

```csharp
using var dbContext = new AppDbContext();

var newsletter = dbContext.GetNewsletter(id);
```

I ran some benchmarks, with the following setup:

- **EF Core 7**
- **SQL Server 2022**
- Table with 10,000 records

The **Compiled Query** was consistently around **10% faster**.

I also tried running a no-tracking query by calling `AsNoTracking()` and
observed similar results.

## Why Are Compiled Queries Faster?

So we can conclude that **Compiled Queries** are faster. But why is that?

Let's examine what happens when we execute an **EF** LINQ query. Before **EF**
can convert the query into valid SQL that can be executed in the database,
it needs to compile the query. The compiled query is cached and **EF** will be
able to reuse that cached query. In some situations the query needs to be
recompiled, introducing additional performance costs.

When we explicitly compile the query by calling `EF.CompileQuery`, we
can utilize some optimization techniques that aren't available at runtime.

Note that **Compiled Queries** only improve the performance of the in-memory
portion of executing an EF query. The round trip time and materializing
results from the database remain unaffected.

## Can We Make Compiled Queries Asynchronous?

I showed you how to write a synchronous **Compiled Query**. But due to
performance considerations we almost always want to execute database
queries asynchronously.

Here's how we can create an asynchronous **Compiled Query**:

```csharp
using Microsoft.EntityFrameworkCore;

public class AppDbContext
{
    private static Func<AppDbContext, string, Task<Newsletter?>> GetByTitle =
        EF.CompileAsyncQuery(
            (AppDbContext context, string title) =>
                context.Set<Newsletter>().FirstOrDefault(c => c.Title == title));

    public async Task<Newsletter?> GetNewsletterByTitleAsync(string title)
    {
        return await GetByTitle(this, title);
    }
}
```

It's interesting that we aren't writing an asynchronous query in the expression
passed to `EF.CompileAsyncQuery`. It will be converted to an asynchronous query
during compilation.

## Compiled Queries Aren't a Silver Bullet

You might be tempted to go and convert all of your **EF** queries into
**Compiled Queries**, to squeeze out that last little bit of performance.
I urge you not do it. **Compiled Queries** are a useful tool, but they
aren't the solution to all your problems.

Instead, I think we should use **Compiled Queries** sparingly, only in
situations where we really need to do these kinds of micro-optimizations.

Although **Compiled Queries** seem great, we can't deny they increase
the complexity of our code considerably. If you think the slight
performance improvement gained from using **Compiled Queries** justifies
the increase in complexity, then by all means, you should use them.
Otherwise, I would look for other ways to improve performance.

---



<Sponsorships>

[**Dotnetjobs**](https://dotnet-jobs.com/) is a reverse job board that empowers .NET developers available for their next job.
Stop scouring traditional job boards and [**sit back as companies reach out to you first**](https://dotnet-jobs.com/).

</Sponsorships>

In this week's newsletter I will show you how to easily add **validation**
to the strongly typed configuration objects injected with `IOptions`.

The **Options pattern** allows us to use classes to provide strongly typed
configuration values in our application at runtime.

But you have no guarantee that the configuration values injected with
`IOptions` will be correctly read from the application settings.

Let's see how we can introduce validation for `IOptions`, and make sure the application settings are correct.

## Strongly Typed Configuration

I first want to define a simple class that will represent our strongly
typed configuration. Let's say we want to integrate with the **GitHub API**,
so we create a `GitHubSettings` class to hold our configuration:

```csharp
public class GitHubSettings
{
    public string AccessToken { get; init; }

    public string RepositoryName { get; init; }
}
```

Inside of our `appsettings.json` file we need to create a section to
hold our configuration values:

```json
"GitHubSettings": {
    "AccessToken": "access-token-value",
    "RepositoryName": "youtube-projects"
}
```

And with this in place, we can configure our `GitHubSettings`:

```csharp
builder.Services.Configure<GitHubSettings>(
    builder.Configuration.GetSection("GitHubSettings"));
```

Finally, our `GitHubSettings` is properly configured and we can inject
it with `IOptions<GitHubSettings>`.

## What Could Go Wrong?

If we leave the implementation like this, we're moving the responsibility
for providing the correct configuration values to the developer. I'm not
saying we are the problem, but I've forgotten to add application settings
a few times. I'm sure this happened to you also.

Here are just a few things that can go wrong:

- Passing an incorrect section name to `IConfiguration.GetSection`
- Forgetting to add the settings values in `appsettings.json`
- Typo in a property name in the class or in the configuration
- Unbindale properties without a setter
- Data type mismatch resulting in incompatible values

Depending on which one of these mistakes is made, the application will
behave differently at runtime.

The best case scenario is that the incorrect application settings cause
a runtime exception, and you realize you have a problem and fix it.

The worst case scenario, and this happens more often than you may think,
is that the application silently fails. The application settings aren't
correctly set on the value provided by `IOptions`, but you don't get a
runtime exception. The problem may go undetected for some time.

How do we solve this?

## Validation For The Options Pattern

There is a simple way to introduce **validation** to the settings class
using **data annotations**. We just add the validation attributes that
we need to the properties of the settings class.

For example, we can add the `Required` attribute to the `GitHubSettings`
properties:

```csharp
public class GitHubSettings
{
    [Required]
    public string AccessToken { get; init; }

    [Required]
    public string RepositoryName { get; init; }
}
```

We have to slightly change how we configure the `GitHubSettings`:

```csharp
builder.Services
    .AddOptions<GitHubSettings>()
    .BindConfiguration("GitHubSettings")
    .ValidateDataAnnotations();
```

A few things to note here:

- `AddOptions` - returns an `OptionsBuilder<TOptions>` that binds to
  the `GitHubSettings` class
- `BindConfiguration` - binds the values from the configuration section
- `ValidateDataAnnotations` - enables **validation** using **data annotations**

With this in place, if we try to inject `GitHubSettings` with any of
the properties missing a value, we will get a runtime exception.

You can also define a **custom delegate** for the **validation** logic, instead
of using data annotations:

```csharp
builder.Services
    .AddOptions<GitHubSettings>()
    .BindConfiguration("GitHubSettings")
    .Validate(gitHubSettings =>
    {
        if (string.IsNullOrEmpty(gitHubSettings.AccessToken))
        {
            return false;
        }

        return true;
    });
```

## Running Validation At Application Start

It would be great if we could run **validation** on the configuration values
when our application is starting, instead of at runtime.

We can do that by calling `ValidateOnStart` method when configuring
our settings class:

```csharp
builder.Services
    .AddOptions<GitHubSettings>()
    .BindConfiguration("GitHubSettings")
    .ValidateDataAnnotations()
    .ValidateOnStart(); // 👈 the magic happens here
```

When we start the application, the validation will run on `GitHubSettings`
and an exception is thrown if validation fails. The validation exception
will look something like this:

```yaml
Unhandled exception. Microsoft.Extensions.Options.OptionsValidationException:
  DataAnnotation validation failed for 'GitHubSettings' members:
```

This shortens the feedback loop, and you will know right away that you have
a problem. This is much better than finding out that you have a problem at
runtime, like in the previous examples.

## Closing Thoughts

The **Options pattern** is very flexible and allows us to use strongly typed
settings in ASP.NET Core.

If you want to see how to implement the [**Options pattern**](https://youtu.be/wxYt0motww0),
I made a [**video about it where I go into the details.**](https://youtu.be/wxYt0motww0)
I covered the differences between `IOptions`, `IOptionsSnapshot` and `IOptionsMonitor`.

And now you know how to use the `ValidateOnStart` method, which was introduced
in **.NET 6**, to validate your application settings on app start up. This allows
you to learn about configuration issues as soon as possible, instead of at runtime.

I also made a video showing how to add [validation to the Option pattern](https://youtu.be/qRruEdjNVNE).

---



In this week's newsletter I will share 5 simple tips on how
you can be a better software engineer in 2023.

I find it a little amusing that the last newsletter of the year
and is also coming out on the last day of the year.

Here are 5 tips for being a better software engineer in 2023:

- [Keep learning and acquiring new skills](#1-keep-learning-and-acquiring-new-skills)
- [Invest in code quality](#2-invest-in-code-quality)
- [Work on complex systems](#3-work-on-complex-systems)
- [Be comfortable in the cloud](#4-be-comfortable-in-the-cloud)
- [Take care of yourself](#5-take-care-of-yourself)

I'm confident that you will become a better software engineer if you apply one of these, but I challenge you to work on all of them in the coming year.

Let's dive in.

## 1. Keep Learning And Acquiring New Skills

The field of software engineering is constantly evolving, so it's
important to stay up-to-date with [**new technologies**](https://youtu.be/dDasAmowFts)
and best practices.

We have a new .NET release every year, and it's easy to get lost
with the latest news. How I stay up to date is through online courses,
attending conferences and meetups, or working on [**personal projects**](https://youtu.be/Ru6_b50wdfo).

Personal projects transition best to my day job, and I don't shy away
from exploring new topics. I shared many of my personal projects on [**GitHub**](https://github.com/m-jovanovic),
maybe you can find some inspiration over there.

## 2. Invest In Code Quality

In addition to writing clean and readable code, it's important to also
consider the overall quality of your code.

This includes things like performance, security, and maintainability.
By writing high-quality code, you'll be able to build systems that are
more reliable, scalable, and easier to maintain over time.

One way to write clean and quality code is [**with the help of static code analysis**](https://youtu.be/0nVT1gM4vPg).

Investing in code quality will pay dividends in the later stages of any project.

## 3. Work On Complex Systems

If you aspire to be senior engineer or software architect, you have to
work on complex systems. You need to be in a position to solve the toughest problems.

What do I consider to be a [**complex system**](https://youtu.be/Ru6_b50wdfo)?

That's difficult to say, but here are some rough guidelines:

- Microservices
- Event-driven systems
- High performance systems

Of course, you don't need a [**fancy architecture**](https://youtu.be/Ru6_b50wdfo) to work in a complex system.

If you are working in a business domain with many domain rules,
I consider that a complex system also.

You should strive to always be in a position to work on a challenging project,
this will help you grow.

## 4. Be Comfortable In The Cloud

The cloud is here to stay, and you should be familiar with at least one
of the major cloud providers:

- Microsoft Azure
- Amazon Web Services
- Google Cloud Platform

Most of them give you free credits to get started and explore the services they offer.

I stayed away from [**cloud development**](https://youtu.be/QP0pi7xe24s) for too long in my career, and now I wish I started sooner.

You want to be [**comfortable in the cloud**](https://youtu.be/QP0pi7xe24s) to be a better software engineer.

## 5. Take Care Of Yourself

Being a software engineer is mentally and physically demanding, and it's
important to take care of yourself in order to maintain a healthy work-life balance.

This includes getting enough sleep, eating well, and taking breaks when needed.

Taking care of yourself can also help you stay focused and productive in your work.

I like to take short breaks every hour or so, and not think about work for a few minutes.
This helps me replenish my energy, and allows me to continue to operate on a high level.

## What I'm Doing To Make 2023 Amazing

What I'm Doing To Make 2023 Amazing
Making New Year's resolutions is popular at the start of the year. The problem is most people get too excited about it, but then proceed to not accomplish anything in a few months.

I've found the simplest rule to always make progress is taking action. I try to make a small step forward every day. And when I look back on the year, I realize I made a lot of progress.

Again, my 5 tips so you can be a better software engineer in 2023 are:

- [Keep learning and acquiring new skills](#1-keep-learning-and-acquiring-new-skills)
- [Invest in code quality](#2-invest-in-code-quality)
- [Work on complex systems](#3-work-on-complex-systems)
- [Be comfortable in the cloud](#4-be-comfortable-in-the-cloud)
- [Take care of yourself](#5-take-care-of-yourself)

Where I failed most in 2022 was taking care of myself, and this will be one of my main improvement points.

I also want to learn many new things, so I can share them with you in this newsletter and on my social media channels.

I wish you a very happy and prosperous New Year.
Write lots of code, squash many bugs,
and may you have green unit tests year round.

Stay awesome! 🎁\
Milan

---


Previous issues of The .NET Weekly