
<Sponsorships>

Coordinating deployments across 37,000 stores and 500,000 database
instances for 6+ years with zero incidents? Impossible! But it's
the reality for one Fortune 100 fast-food empire who chose a NoSQL
point-of-sale database designed to smartly scale.
[**Learn how RavenDB excels as a point-of-sale DB**](https://ravendb.net/whitepapers/ravendb-point-of-sale-database/?utm_campaign=mnw_newsletter_17&utm_medium=blog_ad&utm_source=milan_jovanovic_sponsorship&utm_term=variation_whitepaper&utm_content=ad_link).

</Sponsorships>

In the world of software development, there are countless approaches
and methodologies to choose from. It's easy to get swayed with the
latest trends, and loose sight of architectural principles that really matter.

One of the more popular ones is **Clean Architecture**, a design approach
that prioritizes maintainability, scalability, flexibility, and productivity.

In this week's newsletter, we will explore the key benefits of using
**Clean Architecture** and how it can help your team build better software.

Let's dive in.

## What Is Clean Architecture?

**Clean Architecture**, also known as "The Onion Architecture," was first
introduced by Robert C. Martin (aka "Uncle Bob") in his book
"Clean Architecture: A Craftsman's Guide to Software Structure and Design".

At its core, **Clean Architecture** is a way of organizing a software system
in a way that separates the concerns of the various components,
making it easier to understand and maintain.

In **Clean Architecture**, the core of the system is the **"inner circle"**,
which contains the business rules and logic.

Surrounding this **inner circle** are layers of abstraction,
each one representing a different concern.

<Image src="blogs/mnw_017/clean_architecture.png" width={1920} height={1080} />

The typical outer layers are **Infrastructure** and **Presentation** layers.
The **Infrastructure** layer handles external concerns such as APIs and databases.
While the **Presentation** layer exposes an interface for clients to interact with
the application.

The key principle of **Clean Architecture** is that the **inner circle**
should not depend on the outer layers. Instead, the outer layers should
depend on the **inner circle**. This helps to ensure that the **core** of the
system is flexible and easy to modify, without worrying about the impact
on other parts of the system.

## Benefits Of Using Clean Architecture

I want to highlight some of the key benefits of using **Clean Architecture**.

### Improved Maintainability

One of the primary benefits of using **Clean Architecture** is improved **maintainability**.
By separating the concerns of the various components and enforcing the dependency rule,
it becomes much easier to understand and modify the code.
Depending on abstractions allows you to design your business logic in a flexible way,
without having to know the implementation details.

### Modularity and Separation of Concerns

**Clean Architecture** helps to create a clear **separation of concerns**
within the codebase. Each layer has a specific purpose and is decoupled
from the others, making it easier to understand and modify individual
components without affecting the rest of the system. This modularity
also makes it easier to reuse components in other projects.

### Testability

**Clean Architecture** also makes it **easier to test** and debug the code.
Because the inner circle is independent of the outer layers,
it's easier to write unit tests that focus specifically on the business
rules. This can help to catch errors early on in the development
process and reduce the overall testing effort.

### Loose Coupling of Components

**Clean Architecture** also promotes **loose coupling** between the various
components of the system. This means that it's easier to swap out
external dependencies or make other modifications without affecting
the core business logic. This can be especially useful when it comes
to upgrading or replacing technology.

### Increased Flexibility

Another key benefit of **Clean Architecture** is increased **flexibility**.
By separating the concerns of the various components, it's easier
to modify and adapt the code to changing requirements. This can be
especially useful in fast-paced environments where requirements
are constantly evolving.

### Improved Team Productivity

**Clean Architecture** can help to improve team **productivity**.
By establishing clear separation of responsibilities and well-defined
boundaries, it's easier for team members to understand their roles
and responsibilities. This can improve communication and collaboration,
leading to more efficient and effective work.

## Clean Architecture In The Real World

This all sounds nice in theory, but how does **Clean Architecture**
perform in the real world?

I have used **Clean Architecture** on roughly 10 projects in the
last 5 years, and I've had a lot of success with it. It was
easy to add new features, and scale the applications when
necessary. **Clean Architecture** can easily be broken down
into multiple modules or services, if performance is suffering
and there is a need to scale out.

One problem with the **Clean Architecture** is that it is **easy to overengineer**.

Dogmatism is a real issue, as I see many people with strong
opinions of what **Clean Architecture** should be.
I've been guilty of this myself in the past.

Recently, I try to be more **pragmatic** when using **Clean Architecture**.
I apply what I like, and give myself the flexibility of **"breaking"**
**Clean Architecture** if I think it will simplify things in the long run.

## Closing Thoughts

By following the principles of **Clean Architecture**, you can create a flexible
and maintainable codebase that is well-suited to evolving requirements and technology.

However, it's important to be **pragmatic** with **Clean Architecture** and
allow yourself to be flexible in the design, in order to simplify things in the long run.

If you want to see how to apply **Clean Architecture** in practice,
I have a
[**playlist with more than 20 videos on Clean Architecture**](https://youtu.be/tLk4pZZtiDY?list=PLYpjLpq5ZDGstQ5afRz-34o_0dexr1RGa).

---



<Sponsorships>

New to C# and .NET, or want a refresher on modern .NET?\
[**C# 11 and .NET 7 - Modern Cross-Platform Development Fundamentals**](https://packt.link/402oY)
is a concise, beginner-friendly introduction to the C# language,
.NET libraries, and ASP.NET Core.

[**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>

Did you know you can turn **PostgreSQL** into a fully-fledged **Document database**?

**Marten** is a **.NET** library that allows developers to use the **PostgreSQL**
database as both a **document database** and a fully-featured **event store**.

You don't need to install anything else to be able to use **PostgreSQL**
as a **document database**, outside of the Nuget package. **Marten** relies
on the **JSONB** support available since **PostgreSQL** 9.4.

In this week's newsletter, I want to introduce you to the basics of working
with **Marten** and show you how easy it is to get started.

Let's dive in.

## Installing And Configuring Marten

What are you going to need to start using **PostgreSQL** as a **Document datbase**?

Other than a running instance of **PostgreSQL**, of course, you will need
to install the **Marten** Nuget package:

```csharp
dotnet add package Marten
```

**Marten** can build the required database schema and necessary tables on the fly,
and I suggest using this approach in development.
For a production environment, you definitely want to apply schema
changes on your own with migration scripts.

To register **Marten** with dependency injection, you need to call the `AddMarten`
method.

Here's an example **Marten** configuration inside of a **.NET 7** application:

```csharp
builder.Services.AddMarten(options =>
{
    options.Connection(builder.Configuration.GetConnectionString("Marten"));
});
```

This will register a few services with dependency injection:

- `IDocumentStore` - used to create sessions, generate schema migrations, and do bulk inserts
- `IDocumentSession` - used for read and write operations
- `IQuerySession` - used for read operations

Let's see how we can work with documents using **Marten**.

## Storing Documents With Marten

Storing documents in the database is very straightforward. You need to create
a new `DocumentStore` instance, and open an `IDocumentSession` which exposes
methods for storing and persisting documents.

Let's see how we can store a `Product` document:

```csharp
var store = DocumentStore.For("Connection string to PostgreSQL");

using var session = store.OpenSession();

var product = new Product
{
    Name = "C# 11 and .NET 7 - Modern Cross-Platform Fundamentals",
    Price = 46.87
};

session.Store(product);

await session.SaveChangesAsync();
```

We're creating a new `DocumentStore` instance which we use to open
a session to **PostgreSQL**. And then we just call `Store` and pass in
the `Product` instance. Note that **Marten** will populate the
`Product.Id` at this point. **Marten** can populate keys of `Guid`,
`int`, `long`, and other data types. It uses the HiLo algorithm
for numeric keys. Finally, when we call `SaveChangesAsync` the
`Product` is serialized into **JSON** and persisted as a document.

An important thing to be aware of is that the `IDocumentSession`
created by `OpenSession` doesn't track changes on the entities automatically.
You need to create a session with dirty checking enabled by
calling `DirtyTrackedSession` on the `DocumentStore` to enable
automatic change detection.

## Querying Documents With Marten

**Marten** has rich support for querying documents in the database.
You can write and execute queries using **LINQ**, which you are
familiar with if you worked with **EF Core**. And you can also
write and execute **SQL** queries, because it's still a **PostgreSQL**
database underneath.

Here's an example query to return products that have a higher price
than the one which is specified:

```csharp
var store = DocumentStore.For("Connection string to PostgreSQL");

using var session = store.QuerySession();

var products = session.Query<Product>().Where(p => p.Price > 9.99).ToList();
```

**Marten** also has support for:

- Including related documents
- Batched queries
- Paging
- Full text search

## Advanced Options With Marten

**Marten** can utilize the full capabilities **PostgreSQL** has to offer,
notably transactions and indexing. **Marten** sessions are transactional
by default, either all of the documents are persisted together or
none of them are. And you can configure indexes on your documents
for faster queries.

**Marten** isn't just a **document database** on top of **PostgreSQL**!

You have fully-fledged support for **event sourcing** with **Marten**,
as well as projections. This makes it a perfect choice for
implementing **CQRS**. But this is a topic for a separate newsletter.

## Closing Thoughts

I'm absolutely amazed with [Marten](https://martendb.io/) and what it has to offer.
And **PostgreSQL** is also my favorite database, so it's like a match
made in heaven. I don't get too excited about learning new
technologies, but **Marten** has been an endless source
of joy this past week.

I still need to explore a few more topics before I can consider it
for production use:

- Schema migrations
- Relationships and foreign keys
- Advanced configuration options

Considering that **PostgreSQL** is cheaper than most **document databases**,
I think using **Marten** is an interesting alternative. And if you are
familiar with **SQL** databases, you can still use all of that knowledge.

---



<Sponsorships>

Keeping your business logic and data in-sync doesn't have to be a drag.
Database configuration-as-code and auto-indexes mean your logic is always
querying against what you expect after every release.
[**Take off with RavenDB today**](https://ravendb.net/learn/bootcamp/?utm_campaign=mnw_newsletter_15&utm_medium=blog_ad&utm_source=milan_jovanovic_sponsorship&utm_term=variation_bootcamp&utm_content=ad_link)
and fly faster tomorrow.

</Sponsorships>

In this week's newsletter we are going to explore **Minimal APIs**,
which were introduced in **.NET 6**.

**Minimal APIs** were introduced to remove some of the ceremony
of creating traditional APIs with controllers.
To define an endpoint, you can use the new extension
methods, such as `MapGet` to define a **GET** endpoint.

I see one big issue with **Minimal APIs**, and that is the lack
of clear guidance around how to structure applications
built with **Minimal APIs**.

In this newsletter, I want to offer a few solutions for that problem.

Let's dive in.

## How To Create Minimal APIs?

Let's define a simple **Minimal API** application with two endpoints.
We're going to create one `GET` endpoint for getting a list of products.
And one `POST` endpoint for saving a product to the database.

We're using the powerful **DI** feature that allows us to inject services
as expression arguments, which you can see in the two expressions below
where we are injecting the `AppDbContext`.

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

// Configure EF and other services...

var app = builder.Build();

app.MapGet("/products", async (AppDbContext dbContext) =>
{
    return Results.Ok(await dbContext.Products.ToListAsync());
});

app.MapPost("/products", async (Product product, AppDbContext dbContext) =>
{
    dbContext.Products.Add(product);

    await dbContext.SaveChangesAsync();

    return Results.Ok(product);
});

app.Run();
```

And with this we have a functioning **Minimal API** that we can develop further
as we continue to add more endpoints.

## The Problem With Maintaining Minimal APIs

There is one potential problem with structuring our **Minimal APIs** like
in the previous example. If we keep adding the **Minimal API** endpoints
in the same file, our API will become hard to maintain as it grows
in complexity. How can we solve the maintance problem with **Minimal APIs**?

One solution can be to use extension methods to encapsulate the
definiton of the **Minimal API** endpoints.

Here's an example of that:

```csharp
public static class ProductsModule
{
    public static void RegisterProductsEndpoints(this IEndpointRouteBuilder  endpoints)
    {
        endpoints.MapGet("/products", async (AppDbContext dbContext) =>
        {
            return Results.Ok(await dbContext.Products.ToListAsync());
        });

        endpoints.MapPost("/products", async (Product product, AppDbContext dbContext) =>
        {
            dbContext.Products.Add(product);

            await dbContext.SaveChangesAsync();

            return Results.Ok(product);
        });
    }
}
```

And then inside of `Program` we need to register the endpoints:

```csharp
app.RegisterProductsEndpoints();
```

You can see that this simplifies our **Minimal API** definition,
and we also have our endpoints grouped by feature in one place.
I think this improve the maintainability of **Minimal APIs**,
but it comes at a cost. And that cost is having to define
extension methods for each group of endpoints you want to encapsulate,
and then you have to remember to call that extensions method in `Program`.

Can we do better?

## Structuring Minimal API Projects With Modules

I want to introduce you to an interesting open source library
called [Carter](https://github.com/CarterCommunity/Carter),
which has a concept of modules that we can use to group endpoints.

Here's how we can define our `ProductsModule` with **Carter**:

```csharp
public class ProductsModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapGet("/products", async (AppDbContext dbContext) =>
        {
            return Results.Ok(await dbContext.Products.ToListAsync());
        });

        app.MapPost("/products", async (Product product, AppDbContext dbContext) =>
        {
            dbContext.Products.Add(product);

            await dbContext.SaveChangesAsync();

            return Results.Ok(product);
        });
    }
}
```

This takes care of configuring our **Minimal API** endpoints, but we still
need to tell the framework to use these endpoints. We have to slightly
modify the `Program` to register the required **Carter** services by
calling `AddCarter`, and also map our endpoints by calling `MapCarter`.

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

// Configure EF and other services...

builder.Services.AddCarter();

var app = builder.Build();

app.MapCarter();

app.Run();
```

When we want to define additional **Minimal API** endpoints we just need to
implement a new `ICarterModule`, and register our endpoints. **Carter** will
automatically take care of registering the new endpoints after that.

## Would I Use Minimal APIs In a Real Project?

I think **Minimal APIs** have evolved nicely since they were first introduced
in **.NET 6**. I would be careful with using them in very large applications,
but I'm definitely going to explore options for using them on smaller projects.

A good use case can be for building a microservice that has a limited
number of endpoints.

---



<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.

Sick of staying up late firefighting deployments?
Reclaim your nights with a database that keeps your app up even when things go sideways.
[**Outsource hosting to the experts with RavenDB Cloud today**](https://cloud.ravendb.net/?utm_campaign=mnw_newsletter_14&utm_medium=blog_ad&utm_source=milan_jovanovic_sponsorship&utm_term=variation_cloud&utm_content=ad_link)
so you can sleep well tomorrow.

</Sponsorships>

In this week's newsletter we will talk about running **background tasks** in **ASP.NET Core**.
After reading this newsletter, you will be able to set up a **background task**
and have it up and running within minutes.

**Background tasks** are used to offload some work in your application to the background,
outside of the normal application flow. A typical example can be asynchronously
processing messages from a queue.

I will show you how to create a simple **background task** that runs once and completes.

And you will also see how to configure a continuous **background task**, that repeats after a specific period.

Let's dive in.

## Background Tasks With IHostedService

You can define a **background task** by implementing the `IHostedService` interface.
It has only two methods.

Here's what the `IHostedService` interface looks like:

```csharp
public interface IHostedService
{
    Task StartAsync(CancellationToken cancellationToken);

    Task StopAsync(CancellationToken cancellationToken);
}
```

All you have to do is implement the `StartAsync` and `StopAsync` methods.

Inside of `StartAsync` you would usually perform the background processing.
And inside of `StopAsync` you would perform any cleanup that is necessary,
such as disposing of resources.

To configure the **background task** you have to call the `AddHostedService` method:

```csharp
builder.Services.AddHostedService<MyBackgroundTask>();
```

Calling `AddHostedService` will configure the **background task**
as a **singleton** service.

So does dependency injection still work in `IHostedService` implementations?\
Yes, but you can only inject **transient** or **singleton** services.

However, I don't like to implement the `IHostedService` interface myself.
I prefer using the `BackgroundService` class instead.

## Background Tasks With BackgroundService

The `BackgroundService` class already implements the `IHostedService` interface,
and it has an `abstract` method that you need to override - `ExecuteAsync`.
When you are using the `BackgroundService` class, you only have to think about
the operation you want to implement.

Here's an example **background task** that runs **EF** migrations:

```csharp
public class RunEfMigrationsBackgroundTask : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;

    public RunEfMigrationsBackgroundTask(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using IServiceScope scope = _serviceProvider.CreateScope();

        await using AppDbContext dbContext =
            scope.ServiceProvider.GetRequiredService<AppDbContext>();

        await dbContext.Database.MigrateAsync(stoppingToken);
    }
}
```

The **EF** `DbContext` is a **scoped** service, which we can't inject directly
inside of `RunEfMigrationsBackgroundTask`. We have to inject an instance of
`IServiceProvider` which we can use to create a custom service scope,
so that we can resolve the scoped `AppDbContext`.

I would _not recommend_ running the `RunEfMigrationsBackgroundTask` in production.
**EF** migrations can easily fail and you'll run into problems.
However, I think it's perfectly fine for local development.

## Periodic Background Tasks

Sometimes we want run a **background task** continuously, and have it
perform some operation on repeat. For example, we want consume messages
from a queue every ten seconds. How do we build this?

Here's an example `PeriodicBackgroundTask` to get you started:

```csharp
public class PeriodicBackgroundTask : BackgroundService
{
    private readonly TimeSpan _period = TimeSpan.FromSeconds(5);
    private readonly ILogger<PeriodicBackgroundTask> _logger;

    public PeriodicBackgroundTask(ILogger<PeriodicBackgroundTask> logger)
    {
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using PeriodicTimer timer = new PeriodicTimer(_period);

        while (!stoppingToken.IsCancellationRequested &&
               await timer.WaitForNextTickAsync(stoppingToken))
        {
            _logger.LogInformation("Executing PeriodicBackgroundTask");
        }
    }
}
```

We're using a [PeriodicTimer](https://learn.microsoft.com/en-us/dotnet/api/system.threading.periodictimer?view=net-6.0)
to asynchronously wait for a given period, before executing our **background task**.

## What If You Need A More Robust Solution?

It should be obvious by now that `IHostedService` is useful when you need
simple **background tasks** that are running while your application is running.

What if you want to have a scheduled **background task** that runs at 2AM every day?

You can probably build something like this yourself, but there are existing solutions
that you should consider first.

Here are two popular solutions for running **background tasks** that I worked with before:

- [Quartz](https://www.quartz-scheduler.net/)
- [Hangfire](https://www.hangfire.io/)

I also have an example of [using Quartz for processing Outbox messages](https://youtu.be/XALvnX7MPeo)
on my YouTube channel that you can take a look at.

---



<Sponsorships>

Sick of staying up late firefighting deployments?
Reclaim your nights with a database that keeps your app up even when things go sideways.
[**Outsource hosting to the experts with RavenDB Cloud today**](https://cloud.ravendb.net/?utm_campaign=mnw_newsletter_13&utm_medium=blog_ad&utm_source=milan_jovanovic_sponsorship&utm_term=variation_cloud&utm_content=ad_link)
so you can sleep well tomorrow.

</Sponsorships>

In this week's newsletter, we're going to explore the new
`ExecuteUpdate` and `ExecuteDelete` methods that were released with **EF7**.

`ExecuteUpdate` allows us to write a query and run a bulk update
operation on the entities matching that query.

Similarly, `ExecuteDelete` allows us to write a query and delete
the entities matching that query.

We can significantly improve performance using the new methods in some scenarios, and I'm going to show you what those scenarios are.

Let's dive in.

## Updating And Deleting Entities Before EF Core 7

If you want to update a collection of entities before **EF7**,
you need to load the entities into memory using the `DatabaseContext`.

The **EF ChangeTracker** will then track any changes made to these entities.
When you are ready to commit the changes to the database,
you simply call the `SaveChanges` method.

Here's an example where we load a few notifications,
and we want to snooze them so they aren't sent:

```csharp
var notifications = dbContext
    .Notifications
    .Where(n => !n.Snoozed)
    .ToList();

foreach(var notification in notifications)
{
    notification.Snoozed = true;
}

dbContext.SaveChanges();
```

**EF7** will generate the following **SQL** statement to update the records in the database:

```sql
UPDATE [Notifications] n
SET n.[Snoozed] = TRUE
WHERE n.[Id] = @notificationId_1;

...

UPDATE [Notifications] n
SET n.[Snoozed] = TRUE
WHERE n.[Id] = @notificationId_N;
```

Notice that for every notification we end up with one **SQL UPDATE** statement.
This won't scale well as the number of notifications increases.

## Updating Entities With ExecuteUpdate

With **EF7**, we now have access to the new `ExecuteUdpate` method.
It also has an asynchronous version - `ExecuteUpdateAsync`.

How do you use it?

You need to write a query that will select the records you want to update,
and then call the `ExecuteUpdate` method on the resulting `IQueryable`.

Let's rewrite the previous example using the new approach:

```csharp
dbContext
    .Notifications
    .Where(n => !n.Snoozed)
    .ExecuteUpdate(s => s.SetProperty(
        n => n.Snoozed,
        n => true));
```

In the call to `ExecuteUpdate` we call the `SetProperty` method to specify
which properties we want to update, and what values we want to set.
The `SetProperty` method can be called multiple times, if you need to update more than one property.

In this case, **EF7** will generate the following **SQL** query:

```sql
UPDATE n
SET n.[Snoozed] = TRUE
FROM [Notifications] AS n
WHERE n.[Snoozed] = FALSE;
```

Notice that this time we only have one **SQL** query being sent to the database.
This is a major performance improvement. It can be as much as 10x faster
than the old version, from my testing.

## Deleting Entities With ExecuteDelete

Let's also see how we can do bulk deletes using the `ExecuteDelete` and `ExecuteDeleteAsync` methods.

Again, you have to write a query that will select the records you want to delete,
and then call the `ExecuteDelete` method on the resulting `IQueryable`.

If you want to delete all snoozed notifications:

```csharp
dbContext
    .Notifications
    .Where(n => n.Snoozed)
    .ExecuteDelete();
```

And **EF7** will generate the following **SQL** query:

```sql
DELETE FROM n
FROM [Notifications] AS n
WHERE n.[Snoozed] = TRUE;
```

I think this will be incredibly useful when you want to
delete records in the database based on a specific condition.

## Transactions, Change Tracking And Query Filters With Bulk Methods

You need to be aware how transactions and change tracking
work with the new bulk methods. `ExecuteUpdate` and `ExecuteDelete` will
immediately go to database, and run the **SQL** query.

**What does this mean for transactions?**

If you want to run a bulk method together with other updates
applied with `SaveChanges`, by default they won't run in the same transaction.
You need to open an explicit **transaction** using the `DatabaseContext` to keep everything consistent.

**What does this mean for change tracking?**

`ExecuteUpdate` and `ExecuteDelete` run directly on the database, without loading any entities into memory.
**EF7** will not track these entities in the `ChangeTracker`.

If you have any database interceptors defined, they won't execute
after calling one of the bulk update methods.
This also means that if you override `SaveChanges`
to add custom behavior, it won't be called.

**Do Query Filters still work?**

Yes, **query filters** will be **correctly applied** when calling `ExecuteUpdate` or `ExecuteDelete`.

## When Should You Use The New Bulk Methods?

I think this is an excellent new addition to **EF7**,
and it solves a real problem when you need to run
a typical **UPDATE** or **DELETE** query with a
**WHERE** statement applied.

Previously, you had to write raw **SQL** and execute it using something like **Dapper**.

I will likely use this approach when it applies to my projects.

---



<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>

In this week's newsletter I want to show you how you can use
the powerful **options pattern** in **ASP.NET Core 7**.

The **options pattern** uses classes to provide **strongly typed settings**
in your application at runtime.

The values for the **options** instance can come from multiple sources.
The typical use case is to provide the settings from application configuration.

You can configure the **options pattern** in a few different ways in **ASP.NET Core**.
I want to discuss some of the approaches and their potential benefits.

Let's dive in.

## Creating The Options Class

I want to set the stage first, by creating the **options** class and
explaining what settings we want to bind to it.

We want to configure JWT Authentication for our application,
so we decided to create the `JwtOptions` class to hold that configuration:

```csharp
public class JwtOptions
{
    public string Issuer { get; init; }
    public string Audience { get; init; }
    public string SecretKey { get; init; }
}
```

And let's imagine that inside of our `appsettings.json` file
we have the following configuration values:

```json
"Jwt": {
    "Issuer": "Gatherly",
    "Audience": "Gatherly",
    "SecretKey": "dont-tell-anyone!"
}
```

Alright, that's looking good. Now I want to show you a few ways to bind
the values from JSON to our `JwtOptions` class.

## Setting Up Options Pattern Using IConfiguration

The most straightforward approach is to use the `IConfiguration` instance
that we can access while registering services.

We need to call the `IServiceCollection.Configure<TOptions>` method,
and specify the `JwtOptions` as the generic argument:

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

It doesn't get simpler than this, does it?

The only downside is that we are limited to the configuration
values provided through application configuration.

This can be extended to include environment variables and user secrets also.

## Setting Up Options Pattern Using IConfigureOptions

If you want a more robust approach, I have you covered.
We're going to use the `IConfigureOptions` interface to define a class
to configure our **strongly typed options**.

There are two steps that we need to follow in this case:

- Create the `IConfigureOptions` implementation
- Call `IServiceCollection.ConfigureOptions<TOptions>` with our `IConfigureOptions`
  implementation as the generic argument

To start off, we will create the `JwtOptionsSetup` class:

```csharp
public class JwtOptionsSetup : IConfigureOptions<JwtOptions>
{
    private const string SectionName = "Jwt";
    private readonly IConfiguration _configuration;

    public JwtOptionsSetup(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public void Configure(JwtOptions options)
    {
        _configuration
            .GetSection(SectionName)
            .Bind(options);
    }
}
```

We wrote more code, to achieve the same thing. Was it worth it?

Perhaps, if you consider that we now have access to **dependency injection** in the `JwtOptionsSetup` class.
This means that we can resolve other services that we can use to get the configuration values.

We also need to tell the application to use the `JwtOptionsSetup` class:

```csharp
builder.Services.ConfigureOptions<JwtOptionsSetup>();
```

When we try to inject our `JwtOptions` somewhere, the `JwtOptionsSetup.Configure`
method will be called first the calculate the correct values.

## Injecting Options With IOptions

We've seen a few examples for how to configure the **options pattern** with the `JwtOptions` class.

But how do we actually use the **options pattern**?

Easy, you just need to inject `IOptions<JwtOptions>` from the constructor.

I'll just show the `JwtProvider` constructor here, for brevity.

```csharp
public JwtProvider(IOptions<JwtOptions> options)
{
    _options = options.Value;
}
```

The actual `JwtOptions` instance is available on the `IOptions<JwtOptions>.Value` property.

The `IOptions` instance that we injected here is configured
as a **Singleton** in dependency injection. This is very important to be aware of.

## What About IOptionsSnapshot and IOptionsMonitor?

If you want to use the latest configuration values every time
you inject an **options** class, then injecting `IOptions` won't work.

However, you can use the `IOptionsSnapshot` interface instead:

- It provides the latest configuration snapshot (cached per request)
- It is registered as a **Scoped** service
- It detects configuration changes after application start

You can also use the `IOptionsMonitor` which retrieves the current
option values at any time, and it's a **Singleton** service.

## Wrapping up

The **options pattern** gives us a way to use strongly typed configuration classes in our application.

We can configure the options class in a simple way with [`IConfiguration`](#setting-up-options-pattern-using-iconfiguration),
or we can create an [`IConfigureOptions`](#setting-up-options-pattern-using-iconfigureoptions)
implementation if we need something more powerful.

When it comes to using the **options pattern**, we have three approaches:

- [`IOptions`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.options.ioptions-1?view=dotnet-plat-ext-7.0)
- [`IOptionsSnapshot`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.options.ioptionssnapshot-1?view=dotnet-plat-ext-7.0)
- [`IOptionsMonitor`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.options.ioptionsmonitor-1?view=dotnet-plat-ext-7.0)

Deciding which of them to use in your application depends on what kind of behavior you want.
If you don't need to support refreshing configuration values
after application start, [`IOptions`](#injecting-options-with-ioptions) is a perfect solution.

---



<Sponsorships>

Wish you could calculate prices of your 2.68MM online products 3,000X faster without a batch job?
By ditching their 12-JOIN SQL incantations, the “Amazon of medical supplies”
went from pricing items in 3,000 milliseconds to 1 millisecond - all from within the database.
[**Learn how RavenDB revolutionized the world's largest online medical supply store.**](https://ravendb.net/articles/3000x-faster-database-transactions-for-the-worlds-largest-medical-supplier?utm_campaign=mnw_newsletter_11&utm_medium=blog_ad&utm_source=milan_jovanovic_sponsorship&utm_term=variation_use_case&utm_content=ad_link)

</Sponsorships>

In this week's newsletter I want to highlight a few interesting things
that are now available with the release of **C# 11** and **.NET 7**.

In case you missed it, **.NET 7** was released November 8th.

There are many new features, and you can be sure I had a hard time choosing which ones to highlight.

Here's what we are going to cover:

- [Required members](#required-members)
- [Generic attributes](#generic-attributes)
- [Static abstract members in interfaces](#static-abstract-members-in-interfaces)
- [`file` keyword](#file-keyword)
- [LINQ Order and OrderDescending](#linq-order-and-orderdescending)

Let's see what the new features look like!

## Required Members

We can now define a class member as required by using the `required` keyword.
It can be applied to a _field_ or _property_ and it tells the compiler
these members must be initialized by all constructors or by the object initializer.

Why is this useful?

Before **C# 11**, the only way to enforce a property being set was through a constructor.
If you used an object initializer you could bypass the constructor and not initialize some properties.

Here's how you can say that a property is required:

```csharp
public class ContentCreator
{
    public required string Firstname { get; init; }
    public string? MiddleName { get; init; }
    public required string LastName { get; init; }
}
```

If you try to create a new `ContentCreator` instance without initializing
the `required` properties you get a compile error:

```csharp
var creator = new ContentCreator
{
    FirstName = "Milan" // Error: No LastName
}
```

## Generic Attributes

You can now declare a _generic_ class whose base class is `Attribute`.

Before **C# 11**, if you wanted to pass in a type as a parameter
to an `Attribute` you would need to pass it through the constructor:

```csharp
public class TypedAttribute : Attribute
{
    public TypedAttribute(Type t) => Param = t;

    public Type Param { get; }
}
```

And here's how you would use it with the `typeof` operator:

```csharp
[TypedAttribute(typeof(int))]
public int Method() => default;
```

Using the generic attributes feature, you can now define it like this:

```csharp
public class TypedAttribute<T> : Attribute { ... }
```

Now, we can specify the type parameter as a generic argument:

```csharp
[TypedAttribute<int>()]
public int Method() => default;
```

## Static Abstract Members in Interfaces

This is a very interesting feature that allows abstracting of static operations.
An example of this would be operators.

```csharp
public interface IMonoid<TSelf> where TSelf : IMonoid<TSelf>
{
    public static abstract TSelf operator +(TSelf a, TSelf b);

    public static abstract TSelf Zero { get; }
}
```

How can we use the `IMonoid` interface?

It may be confusing at first, since the members are virtual
and there is no instance to call the virtual members on.
The solution is to use generics and let the compiler infer the rest.

Here's a simple example:

```csharp
T AddAll<T>(params T[] elements) where T : IMonoid<T>
{
    T result = T.Zero;

    foreach (var element in elements)
    {
         result += element;
    }

    return result;
}
```

If you want to learn more, check out the docs on
[static abstract interface methods](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/tutorials/static-virtual-interface-members#static-abstract-interface-methods)
and [generic math](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/tutorials/static-virtual-interface-members#generic-math).

## File Keyword

With the new `file` keyword you can define a type whose scope and visibility
is restricted to the file in which it is declared.

```csharp
file class HiddenClass
{
}
```

This feature is practical when used inside of source generators, to avoid collisions when naming generated types.

But you may be able to find a use for it in your application.

## LINQ Order and OrderDescending

The new `Order` and `OrderDescending` methods allow us to sort an
`IEnumerable`, which simplifies the code for sorting.

Here's an example of ordering an array:

```csharp
var array = new[] { 19, 91, 21 };

var arrayAsc = array.Order();

var arrayDesc = array.OrderDescending();
```

I want to highlight that `IQueryable` also supports the new methods.

## Will You Upgrade to .NET 7?

**.NET 7** is not an LTS (Long Term Support) release,
and will be in support until May 2024,
with **.NET 8** releasing in November 2023.

Here are a few reasons why you should consider upgrading:

- Major performance improvements
- New features in **.NET 7**
- New features in **EF Core 7**
- Easier migration to **.NET 8**

I will be moving some of my new projects from **.NET 6** to **.NET 7**.

And I will also upgrade all of my YouTube content to **.NET 7**.

---



<Sponsorships>

[**QuadSpinner Highlighter**](https://github.com/QuadSpinner/Highlighter) is an open-source
[**Visual Studio extension**](https://github.com/QuadSpinner/Highlighter) that lets you highlight
important objects and arbitrary texts to help you navigate your code more easily.

</Sponsorships>

In this week's newsletter, we will take a look at five different ways to check if a collection **contains duplicates**.

I'm going to explain the idea behind each **algorithm**, discuss the **algorithm complexity** (Big O Notation), and at the end, we'll look at some **benchmark results**.

The five approaches for finding a duplicate will use the:

- [`foreach`](#check-for-duplicates-with-foreach-loop) loop
- LINQ [`Any`](#check-for-duplicates-with-linq-any) method
- LINQ [`All`](#check-for-duplicates-with-linq-all) method
- LINQ [`Distinct`](#check-for-duplicates-with-linq-distinct) method
- LINQ [`ToHashSet`](#check-for-duplicates-with-linq-tohashset) method

Let's see how we can implement each approach!

## Check For Duplicates With ForEach Loop

The first implementation will use the `foreach` loop and the `HashSet` data structure.

Here's the code for the `ContainsDuplicates` method:

```csharp
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)
{
   HashSet<T> set = new();

   foreach(var element in enumerable)
   {
      if (!set.Add(element))
      {
         return true;
      }
   }

   return false;
}
```

The idea is simple:

- Loop through the collection
- Add each element to the `HashSet`
- When `HashSet.Add` returns false we found a duplicate
- If we loop through the entire collection there are no duplicates

In terms of **algorithm complexity**, this would be **O(n)** or linear complexity.
This is because there's only one iteration through the collection.

Adding an element to a `HashSet` is a constant operation - **O(1)**.
So it doesn't affect the overall complexity.

## Check For Duplicates With LINQ Any

We'll combine the idea from the previous implementation of
using the `HashSet` and pair it with the LINQ `Any`
method to iterate over the collection.

Here's the implementation for the `ContainsDuplicates` method:

```csharp
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)
{
   HashSet<T> set = new();

   return enumerable.Any(element => !set.Add(element));
}
```

You can see this implementation is significantly shorter.
But it works the same as the one with the `foreach` loop.

If any element in the collection satisfies the specified expression,
`Any` will _short-circuit_ and return `true`.
Otherwise, it will iterate over the entire collection and return `false`.

We're still looking at linear complexity here, **O(n)**.

## Check For Duplicates With LINQ All

For our third implementation, we will use the opposite
of the LINQ `Any` method - the LINQ `All` method.

Here's the implementation with LINQ `All`:

```csharp
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)
{
   HashSet<T> set = new();

   return !enumerable.All(set.Add);
}
```

The idea here is a little different than in the previous implementation.

`All` will return `true` if all elements in a collection
satisfy the specified expression.

If at least one element doesn't satisfy the condition -
in our case when a **duplicate** is found - it will _short-circuit_ and return `false`.

This is still linear complexity, **O(n)**.

## Check For Duplicates With LINQ Distinct

So far, we've seen a few implementations using the `HashSet` data structure.
Now let's consider a different approach.

We can use the LINQ `Distinct` method to check for duplicates.

Here's the code for the `ContainsDuplicates` method:

```csharp
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)
{
   return enumerable.Distinct().Count() != enumerable.Count();
}
```

The idea is first find the `Distinct` elements and `Count` them,
and then compare that to the number of all elements.

If the number of distinct elements is not equal to
the number of all elements, we have a **duplicate** value.

In terms of **algorithm complexity**, this is still linear complexity.

But we have at least two iterations through the collection
or three in the worst-case scenario.

We have one iteration for `Distinct` and one more
iteration for the call to `Count` right after that.
The last call to `Count` can return in constant time,
if the collection is an `array` or `List`.

## Check For Duplicates With LINQ ToHashSet

For the last implementation we will use the LINQ `ToHashSet` method.

It takes a collection and creates a `HashSet` instance from it.

Here's what the `ContainsDuplicates` implementation looks like:

```csharp
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)
{
   return enumerable.ToHashSet().Count != enumerable.Count();
}
```

We compare the number of elements in the `HashSet` to the number of elements in the collection.

If they are different, we have a **duplicate** value.

This is also linear complexity, **O(n)**.

## Benchmark Results

Now that we've seen our implementations let's put them to the test.

I ran the benchmark for collections of varying sizes:

- 100
- 1,000
- 10,000

Each collection contains exactly one duplicate value located somewhere around the middle of the collection.

Here are the results:

<Image src="blogs/mnw_010/benchmark.png" width={1339} height={627} />

The approach using the `foreach` loop comes out as the clear winner in terms of performance.

However, I would lean towards using the implementations with LINQ `Any` or `All` because of their simplicity.

You can find the [source code for the benchmark](https://github.com/m-jovanovic/find-duplicates-benchmark)
on my GitHub. Feel free to submit a PR with a faster implementation if you can think of one.

---



<Sponsorships>

Delivered straight to your inbox every week,
[**Microns.io**](https://www.microns.io/) is a newsletter that helps you discover the best micro-startups for sale.
Join 3,500+ entrepreneurs and investors looking for their next micro-startup
acquisition opportunity and, along the way, learn about how great deals are done.

[**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'll show you how you can remove repetitive conditions in **EF Core** database queries.

Which kinds of queries fit this description?

An example would be when you implement **soft-delete**, and have to check if a record was **soft-deleted** or not in every query.

Also, it's practical if you're working in a multi-tenant system and need to specify a `tenantId` on every query.

**EF Core** has a powerful feature that can help you remove repetitive conditions from your code.

I'm talking about [Query Filters](https://learn.microsoft.com/en-us/ef/core/querying/filters).

Let's see how we can implement it.

## How To Apply Query Filters

Before introducing **Query Filters**, we will see how the standard approach looks.
We have an `Orders` table that supports **soft-deleting**.
And we never want to return **soft-deleted** orders.

We'll start with an `Order` entity that has an `IsDeleted` property.

```csharp
public class Order
{
   public int Id { get; set; }
   public bool IsDeleted { get; set; }
}
```

And we have a business requirement that we can only query orders that are not deleted.

Here's what an **EF** query to get a single `Order` might look like:

```csharp
dbContext
   .Orders
   .Where(order => !order.IsDeleted)
   .Where(order => order.Id == orderId)
   .FirstOrDefault();
```

This works perfectly for what we need to do.

However, we need to remember to apply this condition every time we want to query the `Order` entity.

Now, let's see how we can define a **Query Filter** on the `Order` entity to
apply this check when querying the database.

Inside of the `OnModelCreating` method on the database context, we need to
call the `HasQueryFilter` method and specify the expression we want:

```csharp
modelBuilder
   .Entity<Order>()
   .HasQueryFilter(order => !order.IsDeleted);
```

Now we can omit the **soft-delete** check from the previous **LINQ** expression:

```csharp
dbContext
   .Orders
   .Where(order => order.Id == orderId)
   .FirstOrDefault();
```

And this is the **SQL** that **EF** will generate with the **Query Filter**:

```sql
SELECT o.*
FROM Orders o
WHERE o.IsDeleted = FALSE AND o.Id = @orderId
```

## Disabling Query Filters

You may run into a situation where you need to disable **Query Filters** for a specific query.
Luckily, there is an easy way to do this.

In your **LINQ** expression, you need to call the `IgnoreQueryFilters` method,
and all the **Query Filters** configured for this entity will be disabled:

```csharp
dbContext
   .Orders
   .IgnoreQueryFilters()
   .Where(order => order.Id == orderId)
   .FirstOrDefault();
```

Be careful when doing this, as you can easily introduce unwanted behavior in your application.

## Good Things To Know Before Using Query Filters

Here are a few more details that you should know about **Query Filters** before using them.
Hopefully, this will save you some trouble if you decide to use them in your application.

**Configuring multiple Query Filters**

Configuring multiple **Query Filters** on the same entity will only apply the last one.
If you need more than one condition, you can do that with the logical `AND` operator (&&).

**Ignoring specific Query Filters**

If you need to ignore a specific expression in a **Query Filter** and leave the rest in place,
unfortunately, you can't do that. Only one **Query Filter** is allowed per entity type.

One solution is calling `IgnoreQueryFilters`, which will remove the configured **Query Filter**
for that entity type. And then manually apply the condition that you need for that specific query.

---



<Sponsorships>

This week's issue is sponsored by [**QuadSpinner**](https://quadspinner.com/).

</Sponsorships>

In this week's newsletter, we'll see how we can work with **locking** in **.NET 6**.

We won't talk about how the lock is actually implemented at the operating system level.
Instead, I will focus on application-level **locking** mechanisms.

**Locking** allows us to control how many **threads** can access some piece of code.
Why would you want to do this?

Usually because you want to protect access to **expensive resources**,
and you need the **concurrency control** that locking enables.

We will use a simple `BankAccount` class with a `Deposit` method
to illustrate how to implement locking.

## The C# Lock Statement

The C# language supports locking with the [`lock` statement](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/statements/lock).
You can use the `lock` statement to define a code block that only one thread can access.

The `lock` statement acquires a mutual-exclusion lock (mutex) for a given object,
executes the statement block, and releases the lock.

```csharp
lock(_lock)
{
   // Your code...
}
```

Here `_lock` is a reference type, usually an `object` instance.

Let's see how we can implement the `BankAccount` class using the `lock` statement:

```csharp
public class BankAccount
{
   private static readonly object _lock = new();
   private decimal _balance;

   public void Deposit(decimal amount)
   {
      lock(_lock)
      {
         _balance += amount;
      }
   }
}
```

The first thread to reach and execute the `lock` statement will be allowed to update
the `_balance`. Any other threads will block until the lock is released.

## Locking With Semaphore

The [`Semaphore`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.semaphore?view=net-6.0)
class is another option we can use to achieve the same effect.

We'll use the `Semaphore` constructor to set the `initialCount` to 1,
which means that the `Semaphore` is open at the start.
And we will also set the `maximumCount` to 1,
which means that only one thread is allowed to enter the `Semaphore`.

Let's see how we can implement the `BankAccount` class using the `Semaphore`:

```csharp
public class BankAccount
{
   private static readonly Semaphore _semaphore = new(
      initialCount: 1,
      maximumCount: 1);

   private decimal _balance;

   public void Deposit(decimal amount)
   {
      _semaphore.WaitOne();

      _balance += amount;

      _semaphore.Release();
   }
}
```

To enter the `Semaphore`, we have to call the `WaitOne` method.

If no thread was previously inside, our thread is allowed
to enter the `Semaphore` and update the balance.

After updating the balance, we call the `Release` method to
release the `Semaphore` for other threads that might be waiting.

## Asynchronous Locking With SemaphoreSlim

What if we wanted to call an asynchronous method in a locked context?

We can't use the `lock` statement as it doesn't support asynchronous calls.
Awaiting an asynchronous call inside a `lock` statement will cause a compilation error.

The `Semaphore` class can solve this problem.

But I want to show you another option that we have, [`SemaphoreSlim`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.semaphoreslim?view=net-6.0).
It's a lightweight alternative to the `Semaphore` class and has `async` methods.

Let's see how we can implement the `BankAccount` class using `SemaphoreSlim`:

```csharp
public class BankAccount
{
   private static readonly SemaphoreSlim _semaphore = new(
      initialCount: 1,
      maximumCount: 1);

   private decimal _balance;

   public async Task Deposit(decimal amount)
   {
      await _semaphore.WaitAsync();

      _balance += amount;

      _semaphore.Release();
   }
}
```

Notice that I updated the `Deposit` method to return a `Task`.

This time, we're calling `WaitAsync` to block the current
thread until it can enter the semaphore.

After updating the balance, we call the `Release` method
to release the `SemaphoreSlim` like in the previous example.

## Are There Other Options For Locking in .NET?

So far I mentioned three options to implement locking:

- [`lock` statement](#the-c-lock-statement)
- [`Semaphore`](#locking-with-semaphore)
- [`SemaphoreSlim`](#asynchronous-locking-with-semaphoreslim)

However, **.NET** has other classes for **concurrency control** that you can
explore like
[`Monitor`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.monitor?view=net-6.0),
[`Mutex`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.mutex?view=net-6.0),
[`ReaderWriterLock`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.readerwriterlock?view=net-6.0)
and many more.

I hope you enjoyed this brief introduction to a very complex topic.

---


Previous issues of The .NET Weekly