
<Sponsorships>

[**dotUltimate**](https://www.jetbrains.com/dotnet/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=dul_promo):
The complete developer toolkit to cover all your .NET and game development needs, supercharged with
[**JetBrains AI**](https://www.jetbrains.com/dotnet/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=dul_promo).
Enjoy access to Rider, ReSharper for Visual Studio and Visual Studio Code, dotTrace, dotMemory, dotCover, dotPeek, JetBrains AI,
and more tools with a single subscription - no need for multiple licenses.
[**Download now**](https://www.jetbrains.com/dotnet/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=dul_promo)

[**Rovo Dev in GA**](https://bit.ly/474NhDY): Meet Atlassian's context-aware AI agent for the entire SDLC.
From code gen and review to docs and maintenance,
[**Rovo Dev helps you automate, write, and accelerate**](https://bit.ly/474NhDY).
Use Rovo Dev in Jira, your IDE, your terminal, and source control (Bitbucket & GitHub) to stay in flow.
[**Explore Rovo Dev**](https://bit.ly/474NhDY).

</Sponsorships>

Have you ever wondered if you could host a tiny .NET API without running servers 24/7?
You can!

AWS Lambda lets you run code on-demand, and with the [Amazon.Lambda.AspNetCoreServer.Hosting](https://www.nuget.org/packages/Amazon.Lambda.AspNetCoreServer.Hosting) library,
you can plug an ASP.NET Core [Minimal APIs](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis) straight into [AWS Lambda](https://aws.amazon.com/lambda/).

In this article we'll set up a minimal API, deploy it, and discuss how it performs.

Don't worry if you're new to serverless, I'll keep everything simple enough to follow along.

## Getting Your Minimal APIs Lambda-Ready

Let's start with the basics. You need just three things to turn your Minimal API into a Lambda function.

First, create your API:

```bash
dotnet new webapi -n MyLambdaApi
cd MyLambdaApi
```

Second, add Amazon's hosting package:

```powershell
Install-Package Amazon.Lambda.AspNetCoreServer.Hosting
```

Third, add one line to your `Program.cs`:

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

// This line does all the Lambda magic
builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi);

var app = builder.Build();

app.MapGet("/", () => "Hello from Lambda!");

app.Run();
```

That's it.
Your API now runs both locally (for testing) and in Lambda (for production).
When you run locally, it uses [Kestrel](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel) like normal.
When you deploy the app to AWS, Lambda takes over.

## Ship It to AWS

You'll need the [Lambda tools](https://github.com/aws/aws-extensions-for-dotnet-cli) installed:

```bash
dotnet tool install -g Amazon.Lambda.Tools
```

Then deploy with one command:

```bash
dotnet lambda deploy-function
```

The tool asks you a few questions (like the function name, which IAM role to use).
Pick the defaults if you're just testing.
In a minute or two, your API is live with a URL like: `https://[abc123xyz].lambda-url.[region-name].on.aws/`.

From the AWS Management Console, you can find your function with its URL and all the other details.

<div class="bordered">
  <Image
    src="blogs/mnw_163/aws_console_lambda_function.png"
    width={1906}
    height={883}
  />
</div>

## Measuring Cold Starts

Here's where things become interesting (and problematic).
Lambda functions "go to sleep" when nobody uses them.
Waking them up takes time, this is the famous **"cold start" problem**.

I ran some simple tests with a basic Minimal API:

- First request (cold): 2,153 ms
- Second request (warm): 154 ms
- Third request (warm): 143 ms
- After 10 minutes idle (cold again): 2,074 ms

As you can see, the first request is slow due to the cold start.
Subsequent requests are much faster, around 150 ms.
After 10 minutes of inactivity, the function goes cold again, and the next request takes over 2 seconds.
There's an optimization feature called [SnapStart](https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html) that can help reduce cold start times,
but it has its own tradeoffs and isn't always suitable for every application.

Another thing to note is that I'm in Europe, and my Lambda function is in the US East (N. Virginia) region.
This adds network latency, so your results may vary based on your location and the region you choose.

Even when warm, the latency is higher than a typical server-hosted API.
This may be acceptable for low-traffic or non-critical endpoints, but it's something to consider.

Let's move beyond a "Hello World" example to something more realistic.

## CRUD Operations Benchmark

To see how a simple API performs in the real world, I built a tiny CRUD app that creates a record, fetches it, updates it and then deletes it.
First I ran each operation once to see the raw latency.
Then I used a load-testing tool with 100 virtual users (VUs) to measure average latency under a bit more stress.

```csharp
// POST /products - Create new product
app.MapPost("/products", async (CreateProductRequest request, NpgsqlDataSource dataSource) =>
{
    const string sql =
        """
        INSERT INTO Products (Name, Description, Price, CreatedAt)
        VALUES (@Name, @Description, @Price, @CreatedAt)
        RETURNING Id, Name, Description, Price, CreatedAt
        """;

    await using var connection = await dataSource.OpenConnectionAsync();
    var product = await connection.QueryFirstAsync<Product>(sql, new
    {
        request.Name,
        request.Description,
        request.Price,
        CreatedAt = DateTime.UtcNow
    });

    return Results.Created(
        $"/products/{product.Id}",
        new ProductResponse(
            product.Id,
            product.Name,
            product.Description,
            product.Price,
            product.CreatedAt));
});
// Other endpoints omitted for brevity:
// - GET /products/{id} - Get product by ID
// - PUT /products/{id} - Update product
// - DELETE /products/{id} - Delete product
```

The application uses .NET 8, [Npgsql](https://www.npgsql.org/) and [Dapper](https://www.learndapper.com/)
to interact with a PostgreSQL database running on [Amazon RDS](https://aws.amazon.com/rds/).
You can find the source code for this example (and the previous one) in [this repository](https://github.com/m-jovanovic/minimal-apis-on-lambda).

Here are the results:

**Single-call latency**

```text
| Operation  | Latency (ms) | Notes                           |
| ---------- | ------------ | ------------------------------- |
| Create     |     537      | Cold start plus object creation |
| Read       |     134      | Simple GET of the new record    |
| Update     |     140      | Changing one property           |
| Delete     |     167      | Removing the record             |
```

The create call took half a second because it included a cold start and initialization overhead.
Once the function was warmed up, the other operations completed in under two hundred milliseconds.

**Load test with 100 virtual users**

During the load test, I simulated 100 clients hitting the API at once.
AWS automatically scaled the Lambda function to handle the traffic, and average latencies dropped because the functions were already warm.
Here are the averages:

- **CREATE avg**: 129 ms
- **READ avg**: 132 ms
- **UPDATE avg**: 152 ms
- **DELETE avg**: 144 ms

These numbers show that once your function is up and running, Lambda can respond quite quickly even when many users are making requests.
Of course, actual times will vary depending on what your API does and how it stores data.

Remember that each of these operations involves network calls to the database, which adds latency.
Overall, I don't find these numbers bad for a serverless setup.

## Summary

Hosting minimal APIs in AWS Lambda is **surprisingly straightforward**.
With one library and a single method call, your ASP.NET Core code can run "without servers".
You pay only for the compute you use.
Also, the AWS Lambda free tier includes one million free requests per month, which is great for testing and light usage.

However, there are tradeoffs.
Because of cold starts and the overhead of starting the .NET runtime, latency isn't as low as hosting on a dedicated server.
If your API is mission-critical or requires sub-100 ms responses at all times, you may need to look at provisioned concurrency, containers, or a traditional host.

Lambda shines for small, [**event-driven**](event-driven-architecture-in-dotnet-with-rabbitmq) or intermittent workloads that don't justify a full-time server.
But it's less suitable for latency-sensitive or heavy, long-running applications.
For occasional or low-traffic API endpoints, though, **Lambda** offers a **cost-effective** and **simple** option.

That's all for today.

See you next week.

---



<Sponsorships>

[**CodeRabbit CLI**](https://bit.ly/4nu0zk2) brings instant (and free) code reviews directly into your terminal,
seamlessly integrating with Codex, Claude Code, Cursor CLI, and other AI coding agents.
While they generate code, [**CodeRabbit**](https://bit.ly/4pLOYyB) ensures it's production-ready - catching bugs, security issues,
and AI hallucinations before they hit your codebase.
[**Install CodeRabbit CLI**](https://bit.ly/4nu0zk2)

[**Free Webinar: Modernizing Legacy Business Apps Without Sacrificing Speed & Quality UX**](https://www.telerik.com/webinars/devcraft/modernizing-legacy-business-apps-without-sacrificing-speed-and-quality-ux-success-stories-from-the-real-world?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_ai_resolut_webinar_WW)\
Whether you're tackling modernization at scale or fine-tuning your design system,
this session shows how to keep speed, stability and UX quality in balance.
In this joint webinar, Resolute and Progress will share real-world success stories from three enterprise modernization projects.
[**Save your seat today**](https://www.telerik.com/webinars/devcraft/modernizing-legacy-business-apps-without-sacrificing-speed-and-quality-ux-success-stories-from-the-real-world?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=dt_ai_resolut_webinar_WW)!

</Sponsorships>

You're building a .NET application with [EF Core](https://learn.microsoft.com/en-us/ef/core/).
Most of your queries work fine with [**LINQ**](why-i-write-tall-linq-queries), but now you're hitting scenarios where you need something more.

Maybe you have a complex report that joins five tables with aggregations and window functions.
Your LINQ query generates SQL that's slower than you'd like, and you know you could write better SQL by hand.

Or maybe you need to update inventory with proper locking to prevent race conditions.
You could manage [**transactions**](working-with-transactions-in-ef-core) and explicit locks in C#, but it feels like you're fighting the framework.

Here's what usually happens: you search for "EF Core stored procedures" and find conflicting advice.
Some articles say avoid raw SQL at all costs.
Others suggest abandoning EF entirely and writing ADO.NET.
Neither feels right.

Actually, **EF Core works great with database functions and procedures**.
You get the database's power for what it does best, and EF's convenience for everything else.
Let me show you how this actually works.

I'll use [PostgreSQL](https://www.postgresql.org/) for examples, but the same principles apply to SQL Server and other relational databases.

## When Should You Even Use Raw SQL?

Let's be honest: most of the time, **LINQ is fine**.
EF Core translates your C# into decent SQL, and you get type safety and refactoring support.

But there are times when raw SQL makes more sense:

**You need performance you can't get from LINQ**.
Complex aggregations with multiple joins, [window functions](https://www.postgresql.org/docs/current/tutorial-window.html), or reporting queries often run faster when written directly in SQL.
You can test and tune the query in your database tool before bringing it into your code.

**You're using database-specific features**.
PostgreSQL has powerful capabilities like [full-text search](https://www.postgresql.org/docs/current/textsearch.html), JSON operators,
and [common table expressions (CTEs)](https://www.postgresql.org/docs/current/queries-with.html) that don't always have clean LINQ equivalents.
Sometimes the straightest path is just writing the SQL.

**You have existing database logic**.
If your database already has stored procedures and functions (maybe from a [**legacy system**](what-rewriting-a-40-year-old-project-taught-me-about-software-development)),
calling them directly beats rewriting everything in C#.

**You need atomic operations with proper locking**.
A stored procedure that coordinates multiple updates with `FOR UPDATE` locks ([**here's a good use case**](scaling-the-outbox-pattern))
is simpler and safer than trying to manage that from application code.

**You want to reduce round trips**.
One function call that aggregates data from five tables is more efficient than five separate LINQ queries.

Now let's see how to actually do this.

## Example 1: Simple Scalar Function

Here's a straightforward function that tells you how many tickets are left:

```sql
CREATE OR REPLACE FUNCTION ticketing.tickets_left(p_ticket_type_id uuid)
RETURNS numeric
LANGUAGE sql
AS $$
  SELECT tt.available_quantity
  FROM ticketing.ticket_types tt
  WHERE tt.id = p_ticket_type_id
$$;
```

Nothing fancy, just a query wrapped in a function.

Calling it from EF Core is straightforward:

```csharp {6}
app.MapGet("ticket-types/{ticketTypeId}/available-quantity",
async (Guid ticketTypeId, EventManagementContext dbContext) =>
{
    var result = await dbContext.Database.SqlQuery<int>(
            $"""
             SELECT ticketing.tickets_left({ticketTypeId}) AS "Value"
             """)
        .FirstAsync();

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

Notice the `AS "Value"` alias.
When EF Core maps to a primitive type, it expects a property named `Value`.
The quotes preserve the exact casing (PostgreSQL lowercases unquoted identifiers by default).

The interpolated string syntax (`$"{ticketTypeId}"`) might look dangerous, but EF Core converts this into a parameterized query automatically.
You're not building SQL strings, you're using C# interpolation as a convenient syntax for parameters.

## Example 2: Table-Valued Function

Functions can return entire result sets, which is where they really shine:

```sql
CREATE OR REPLACE FUNCTION ticketing.customer_order_summary(p_customer_id uuid)
RETURNS TABLE (
    order_id uuid,
    created_at_utc timestamptz,
    total_price numeric,
    currency text,
    item_count numeric
)
LANGUAGE sql
AS $$
SELECT
    o.id,
    o.created_at_utc,
    o.total_price,
    o.currency,
    COALESCE(SUM(oi.quantity), 0) AS item_count
FROM ticketing.orders o
LEFT JOIN ticketing.order_items oi ON oi.order_id = o.id
WHERE o.customer_id = p_customer_id
GROUP BY o.id, o.created_at_utc, o.total_price, o.currency
ORDER BY o.created_at_utc DESC
$$;
```

This function joins orders with their items, aggregates quantities, and returns multiple rows.
You could write this in LINQ, but the SQL is clearer and you can test it directly in your database tool.

To use it from C#, create a DTO that matches the function's output:

```csharp
public class OrderSummaryDto
{
    public Guid OrderId { get; set; }
    public DateTime CreatedAtUtc { get; set; }
    public decimal TotalPrice { get; set; }
    public string Currency { get; set; }
    public int ItemCount { get; set; }
}
```

Then query the function like any other table:

```csharp {13}
app.MapGet("customers/{customerId}/order-summary",
async (Guid customerId, EventManagementContext dbContext) =>
{
    var orders = await dbContext.Database
        .SqlQuery<OrderSummaryDto>(
            $"""
             SELECT
                order_id AS OrderId,
                created_at_utc AS CreatedAtUtc,
                total_price AS TotalPrice,
                currency AS Currency,
                item_count AS ItemCount
             FROM ticketing.customer_order_summary({customerId})
             """)
        .ToListAsync();

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

The key is mapping column names to your DTO properties using aliases.
EF Core handles the rest automatically.

This is a simple case without joins, but you can use this pattern in more complex queries too.
However, you will have to project into DTOs manually since EF Core can't translate joins in raw SQL into entity graphs.
Usually, you'll return a flat structure from functions anyway, and then map to richer models in C# if needed.

## Understanding PostgreSQL Functions vs Procedures

PostgreSQL distinguishes between functions and procedures in important ways:

**Functions** are designed to **return values**.
They can return scalar values, tables, or even complex JSON objects.
You call them with `SELECT` and can use them in queries like any other expression.
Functions run within a transaction and can be used in `WHERE` clauses, joins, and other query contexts.

**Procedures** are designed for **side effects**.
They don't return values directly but can modify data and have `OUT` parameters.
You call them with `CALL` and they're ideal for complex operations that need to manage transactions explicitly or perform multiple related updates.

Think of it this way: use functions when you need data, use procedures when you need to change something.

This distinction matters because it affects how you design your database logic and how you call these routines from C#.

Let's see an example of a procedure.

## Example 3: Stored Procedure with Validation

Here's where procedures really prove their worth.
Let's say you need to adjust ticket inventory, but you want to prevent [**race conditions**](solving-race-conditions-with-ef-core-optimistic-locking) and validate the operation:

```sql
CREATE OR REPLACE PROCEDURE ticketing.adjust_available_quantity(
    p_ticket_type_id uuid,
    p_delta numeric,
    p_reason text DEFAULT 'manual-adjust'
)
LANGUAGE plpgsql
AS $$
DECLARE
    v_qty numeric;
    v_avail numeric;
    v_new_avail numeric;
BEGIN
    SELECT quantity, available_quantity
    INTO v_qty, v_avail
    FROM ticketing.ticket_types
    WHERE id = p_ticket_type_id
    FOR UPDATE;

    IF NOT FOUND THEN
        RAISE EXCEPTION 'ticket_type % not found', p_ticket_type_id;
    END IF;

    v_new_avail := v_avail + p_delta;

    IF v_new_avail < 0 THEN
        RAISE EXCEPTION 'Cannot reduce below zero';
    END IF;

    IF v_new_avail > v_qty THEN
        RAISE EXCEPTION 'Cannot exceed quantity';
    END IF;

    UPDATE ticketing.ticket_types
    SET available_quantity = v_new_avail
    WHERE id = p_ticket_type_id;
END;
$$;
```

This procedure does several important things:

- **Locks the row** with `FOR UPDATE` so no other transaction can modify it until we're done
- **Validates business rules** before making changes
- **Provides clear error messages** when something goes wrong
- **Keeps everything atomic** in a single database round trip

You could do all this in C# with manual transaction management and explicit locking, but it's more complex and error-prone.
Let the database handle what it's good at.

Here's how you call it from EF Core:

```csharp {10}
app.MapPut("ticket-types/{ticketTypeId}/available-quantity", async (
    Guid ticketTypeId,
    int quantity,
    EventManagementContext dbContext) =>
{
    try
    {
        await dbContext.Database.ExecuteSqlAsync(
            $"""
             CALL ticketing.adjust_available_quantity({ticketTypeId},{quantity})
             """);

        return Results.Ok(result);
    }
    catch (Exception e)
    {
        return Results.BadRequest(e.Message);
    }
});
```

The procedure doesn't return a value, but if it raises an exception (with `RAISE EXCEPTION`), PostgreSQL will propagate that to your C# code.
You can catch it and return a proper error response.

## About SQL Injection (Don't Panic)

You might be looking at those interpolated strings and thinking "wait, isn't this [**SQL injection waiting to happen**](ef-core-raw-sql-queries)?"

**It's not**.

When you write:

```csharp
$"SELECT * FROM users WHERE id = {userId}"
```

EF Core doesn't concatenate strings.
It converts this into:

```sql
SELECT * FROM users WHERE id = @p0
```

**The actual value is sent as a parameter**, completely separate from the SQL text.
This works for all the examples in this article.

The interpolation syntax is just a convenient way to write parameterized queries.

The reason why is we're not actually passing in a `string` to the `SqlQuery` method,
but a [`FormattableString`](https://learn.microsoft.com/en-us/dotnet/api/system.formattablestring).
This is a special type that captures the format and arguments separately, allowing EF Core to handle parameters.

Everything in this article works with [SQL Server](https://learn.microsoft.com/en-us/sql/),
[MySQL](https://dev.mysql.com/),
[SQLite](https://www.sqlite.org/index.html), and other databases EF Core supports.
The differences are mostly syntax.

## A Quick Word on Views

Database views are like functions without parameters.
They're saved queries you can reference by name.

You can query them using `SqlQuery<T>` just like functions:

```csharp
var results = await dbContext.Database
    .SqlQuery<ActiveCustomerDto>(
        $"SELECT * FROM ticketing.active_customers")
    .ToListAsync();
```

Or you can map them to entity types in your `DbContext` for full LINQ support.

Views are great for frequently-used queries that don't need parameters.
Functions give you the flexibility of parameterization.

## Wrapping Up

We've covered how to use PostgreSQL functions and procedures with EF Core, from simple scalar functions to complex procedures with validation and locking.

You learned when to use functions (when you need data back) versus procedures (when you need to modify data).
You saw how EF Core's `SqlQuery<T>` and `ExecuteSqlAsync` give you type safety while letting you write the SQL you need.
And you learned when raw SQL makes sense: complex aggregations, database-specific features, atomic operations with locking, and reducing round trips.

**EF Core** doesn't force you to choose between LINQ and raw SQL.
You can use both.

Use functions when you need to return data, procedures when you need to modify data with complex logic,
and raw SQL queries when LINQ doesn't capture your requirements efficiently.
The combination of EF Core's convenience and the database's power gives you the flexibility to choose the right tool for each scenario.

That's all for today. Hope this was helpful.

---



<Sponsorships>

[**Fly.io**](https://bit.ly/4nkdDZc) runs .NET apps where they belong: at the edge, close to users.
Low latency, global reach, and simple setup.
Package your .NET app, deploy with flyctl, and scale worldwide with no ops overhead.
[**Learn how to deploy .NET with Fly.io**](https://bit.ly/4nkdDZc)

[**Smarter Refactoring for .NET Teams**](https://www.augmentcode.com/guides/ai-code-refactoring-tools-tactics-and-best-practices?utm_source=.netweekly&utm_medium=newsletter&utm_campaign=augmentcode-september&utm_term=mjovanovic&utm_content=refactoring-blog)\
Refactoring in .NET means more than cleaning up code — it's breaking down oversized services, updating EF Core migrations,
or modernizing old layers without breaking contracts.
[**Augment Code**](https://www.augmentcode.com/guides/ai-code-refactoring-tools-tactics-and-best-practices?utm_source=.netweekly&utm_medium=newsletter&utm_campaign=augmentcode-september&utm_term=mjovanovic&utm_content=refactoring-blog)
can help: it analyzes your entire solution, tracks dependencies, and applies changes consistently across files and projects.
The result: cleaner architecture, less technical debt, and zero surprises.
👉 [**Read the full guide on AI-assisted refactoring**](https://www.augmentcode.com/guides/ai-code-refactoring-tools-tactics-and-best-practices?utm_source=.netweekly&utm_medium=newsletter&utm_campaign=augmentcode-september&utm_term=mjovanovic&utm_content=refactoring-blog)

</Sponsorships>

Authentication tells you **who** the user is.
Authorization tells you **what** they can do.

Most .NET developers start with simple role-based checks: "Is this user an Admin?"
But as your application grows, you quickly realize that roles alone aren't enough.
You need **granular permissions** that can be combined and assigned flexibly.

That's where **Role-Based Access Control (RBAC)** shines.
Instead of hardcoding role checks everywhere, you define specific permissions and let roles carry those permissions.
A user might be a `Manager` role, but what matters is whether they have the `users:delete` permission.

Let me show you how to build a flexible, **permission-based authorization** system in ASP.NET Core.

## Understanding RBAC Components

[RBAC](https://auth0.com/docs/manage-users/access-control/rbac) has three key components that work together:

**Users** → assigned to → **Roles** → which contain → **Permissions**

Here's how it flows:

- **Users**: Individual people using your system
- **Roles**: Groups of related permissions (Admin, Manager, Editor)
- **Permissions**: Specific actions users can perform (users:read, orders:create, reports:delete)

<Image src="blogs/mnw_161/rbac.png" width={3411} height={1911} />

The beauty is in the flexibility.
You can assign multiple roles to a user, and roles can be modified without touching user assignments.
Need to give all Managers the ability to export reports?
Just add the `reports:export` permission to the `Manager` role.

This is much more maintainable than checking if someone is specifically an `Admin` or `Super Manager` in your code.

It also adds an extra extension point: you can implement custom permissions for some users without creating new roles.

## Building a Custom Authorization Handler

[ASP.NET Core's authorization system](https://learn.microsoft.com/en-us/aspnet/core/security/authorization/introduction) is built around **policies** and **requirements**.
Let's create a custom handler that checks permissions stored in the user's claims:

```csharp {4, 12-14, 18}
public class PermissionAuthorizationRequirement(params string[] allowedPermissions)
    : AuthorizationHandler<PermissionAuthorizationRequirement>, IAuthorizationRequirement
{
    public string[] AllowedPermissions { get; } = allowedPermissions;

    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        PermissionAuthorizationRequirement requirement)
    {
        foreach (var permission in requirement.AllowedPermissions)
        {
            bool found = context.User.FindFirst(c =>
                c.Type == CustomClaimTypes.Permission &&
                c.Value == permission) is not null;

            if (found)
            {
                context.Succeed(requirement);
                break;
            }
        }
        return Task.CompletedTask;
    }
}
```

Here's what's happening under the hood:

The class combines both the **requirement** (what permissions are needed) and the **handler** (how to check them).
This keeps related logic together and reduces boilerplate.

The handler looks through the user's claims for any claim with type `Permission` that matches one of the required permissions.
It's an **OR operation** - the user only needs **one** of the specified permissions to proceed.

If a matching permission is found, we call `context.Succeed(requirement)` and break out early.
No need to check the remaining permissions.

Alternatively, you could implement an **AND operation** if your use case requires all permissions to be present.

You'll need to define your custom claim type:

```csharp
public static class CustomClaimTypes
{
    public const string Permission = "permission";
}
```

And then you'll use this when issuing JWT tokens or setting up user claims.

```csharp {1-7, 14}
var permissions = await (
        from role in dbContext.Roles
        join permission in dbContext.RolePermissions on role.Id equals permission.RoleId
        where roles.Contains(role.Name)
        select permission.Name)
    .Distinct()
    .ToArrayAsync();

List<Claim> claims =
[
    new(JwtRegisteredClaimNames.Sub, user.Id),
    new(JwtRegisteredClaimNames.Email, user.Email!),
    ..roles.Select(r => new Claim(ClaimTypes.Role, r)),
    ..permissions.Select(p => new Claim(CustomClaimTypes.Permission, p))
];

var tokenDescriptor = new SecurityTokenDescriptor
{
    Subject = new ClaimsIdentity(claims),
    Expires = DateTime.UtcNow.AddMinutes(configuration.GetValue<int>("Jwt:ExpirationInMinutes")),
    SigningCredentials = credentials,
    Issuer = configuration["Jwt:Issuer"],
    Audience = configuration["Jwt:Audience"]
};

var tokenHandler = new JsonWebTokenHandler();

string accessToken = tokenHandler.CreateToken(tokenDescriptor);
```

## Creating Clean APIs with Extension Methods

Raw authorization policies work, but they're verbose. Let's create extension methods that make the developer experience much cleaner:

```csharp {7}
public static class PermissionExtensions
{
    public static void RequirePermission(
        this AuthorizationPolicyBuilder builder,
        params string[] allowedPermissions)
    {
        builder.AddRequirements(new PermissionAuthorizationRequirement(allowedPermissions));
    }
}
```

Now you can use this with **Minimal APIs**:

```csharp {24}
public static class Permissions
{
    public const string UsersRead = "users:read";
    public const string UsersUpdate = "users:update";
    public const string UsersDelete = "users:delete";
}

app.MapGet("me", (ApplicationDbContext dbContext) =>
{
    var user = await dbContext.Users
        .AsNoTracking()
        .Where(u => u.Id == int.Parse(User.FindFirstValue(JwtRegisteredClaimNames.Sub)!))
        .Select(u => new UserDto
        {
            u.Id,
            u.Email,
            u.FirstName,
            u.LastName
        })
        .SingleOrDefaultAsync();

    return Results.Ok(user);
})
.RequireAuthorization(policy => policy.RequirePermission(Permissions.UsersRead));
```

For **MVC Controllers**, create an attribute:

```csharp
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class RequirePermissionAttribute(params string[] permissions) : AuthorizeAttribute
{
    public RequirePermissionAttribute(params string[] permissions)
        : base(policy: string.Join(",", permissions))
    {
    }
}
```

Then register the policy in your DI container:

```csharp
builder.Services.AddAuthorizationBuilder()
    .AddPolicy("users:read", policy => policy.RequirePermission(Permissions.UsersRead))
    .AddPolicy("users:update", policy => policy.RequirePermission(Permissions.UsersUpdate));
```

Usage becomes clean:

```csharp {1}
[RequirePermission(Permissions.UsersUpdate)]
public async Task<IActionResult> UpdateUser(int id, UpdateUserRequest request)
{
    // Your logic here
}
```

## Extension Points for Production

The basic implementation works great, but we could improve it further.
Here are two key extension points:

### Type-Safe Permissions with Enums

Instead of magic strings, use enums for compile-time safety:

```csharp
public enum Permission
{
    UsersRead,
    UsersUpdate,
    UsersDelete,
    OrdersCreate,
    ReportsExport
}
```

You'll have to convert these to strings when issuing claims and checking permissions.
And also convert from a string to an enum, when reading from claims and validating the permissions.

### Server-Side Permission Resolution

Rather than storing all permissions in JWT tokens (which can get large), fetch them server-side using `IClaimsTransformation`:

```csharp
public class PermissionClaimsTransformation(IPermissionService permissionService)
    : IClaimsTransformation
{
    public async Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
    {
        if (principal.Identity?.IsAuthenticated != true)
        {
            return principal;
        }

        var userId = principal.FindFirst(ClaimTypes.NameIdentifier)?.Value;
        if (userId == null)
        {
            return principal;
        }

        // Fetch permissions from database, then cache
        // IMPORTANT: Cache these results to avoid DB hits on every request
        var permissions = await permissionService.GetUserPermissionsAsync(userId);

        var claimsIdentity = (ClaimsIdentity)principal.Identity;
        foreach (var permission in permissions)
        {
            claimsIdentity.AddClaim(new Claim(CustomClaimTypes.Permission, permission));
        }

        return principal;
    }
}
```

Register it in your DI container:

```csharp
builder.Services.AddScoped<IClaimsTransformation, PermissionClaimsTransformation>();
```

This approach keeps your JWTs lightweight while still providing fast authorization checks through claims.

You can learn more about claims transformation in my [**previous article**](master-claims-transformation-for-flexible-aspnetcore-authorization).

## Takeaway

**RBAC** transforms authorization from a maintenance headache into a flexible, scalable system.

**Start with permissions**: Define what actions users can perform, not what roles they have.

**Custom authorization handlers** give you complete control over how permissions are validated.

**Extension methods** make the developer experience clean and consistent across your API.

For production systems, consider **type-safe enums** and **server-side permission resolution** to keep your tokens lean and your code maintainable.

The result? Authorization logic that's easy to understand, test, and modify as your application evolves.

---



<Sponsorships>

Diskless 2.0 combines Kafka's Tiered Storage and Diskless Topics into one simpler path with zero-copy
migration. Cut costs, reduce complexity, and run faster, [**cloud-ready Kafka without broker disks**](https://bit.ly/47Rl2KN) for
streamlined performance built for the next decade.
[**Read the full blog here**](https://bit.ly/47Rl2KN).

[**BoldSign API & SDKs for Developers**](https://boldsign.com/esignature-api/?utm_source=milanjovanovic&utm_medium=newsletter_ad&utm_campaign=boldsign) -
Add contract signing to your app in minutes with our .NET SDK.
Fully embed sending and signing, control branding and emails, get transparent pricing, and start testing instantly in our free sandbox.
Trusted by 40K+ businesses and recognized as the
[**#1 developer-choice e-signature API**](https://boldsign.com/esignature-api/?utm_source=milanjovanovic&utm_medium=newsletter_ad&utm_campaign=boldsign).

</Sponsorships>

When you build applications that run across multiple servers or processes, you eventually run into the problem of concurrent access.
Multiple workers try to update the same resource at the same time, and you end up with race conditions, duplicated work, or corrupted data.

.NET provides excellent [**concurrency control primitives**](introduction-to-locking-and-concurrency-control-in-dotnet-6) for single-process scenarios,
like `lock`, `SemaphoreSlim`, and `Mutex`.
But when your application is scaled out across multiple instances, these primitives don't work anymore.

That's where **distributed locking** comes in.

Distributed locking provides a solution by ensuring **only one node** (application instance) can access a critical section at a time,
preventing race conditions and maintaining data consistency **across your distributed system**.

## Why and When You Need Distributed Locking

In a single-process app, you can just use `lock` or the new [Lock class](https://learn.microsoft.com/en-us/dotnet/api/system.threading.lock) in .NET 10.
But once you scale out, that's not enough, because each process has its own memory space.

A few common cases where distributed locks are valuable:

- **Background jobs**: ensuring only one worker processes a particular job or resource at a time.
- **Leader election**: choosing a single process to perform periodic work (like applying async database projections).
- **Avoiding double execution**: ensuring scheduled tasks don't run multiple times when deployed to multiple instances.
- **Coordinating shared resources**: e.g., only one service instance performing a migration or cleanup at a time.
- **Cache stampede prevention**: ensuring only one instance refreshes the cache when a given cache key expires.

The key value: consistency and safety across distributed environments.
Without this, you risk duplicate operations, corrupted state, or unnecessary load.

Now you know why distributed locking is important.

Let's look at some implementation options.

## DIY Distributed Locking with PostgreSQL Advisory Locks

Let's start simple.
PostgreSQL has a feature called [advisory locks](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS) that's perfect for distributed locking.
Unlike table locks, these don't interfere with your data - they're purely for coordination.

Here's an example:

```csharp {10,25}
public class NightlyReportService(NpgsqlDataSource dataSource)
{
    public async Task ProcessNightlyReport()
    {
        await using var connection = dataSource.OpenConnection();

        var key = HashKey("nightly-report");

        var acquired = await connection.ExecuteScalarAsync<bool>(
            "SELECT pg_try_advisory_lock(@key)",
            new { key });

        if (!acquired)
        {
            throw new ConflictException("Another instance is already processing the nightly report");
        }

        try
        {
            await DoWork();
        }
        finally
        {
            await connection.ExecuteAsync(
                "SELECT pg_advisory_unlock(@key)",
                new { key });
        }
    }

    private static long HashKey(string key) =>
        BitConverter.ToInt64(SHA256.HashData(Encoding.UTF8.GetBytes(key)), 0);

    private static Task DoWork() => Task.Delay(5000); // Your actual work here
}
```

Here's what's happening under the hood.

First, we convert our lock name into a number.
PostgreSQL **advisory locks need numeric keys**, so we hash `nightly-report` into a 64-bit integer.
Every node (application instance) must generate the same number for the same string, or this won't work.

Next, `pg_try_advisory_lock()` attempts to grab an exclusive lock on that number.
It returns `true` if successful, `false` if another connection already holds it.
This call doesn't block - it tells you immediately whether you got the lock.

If we get the lock, we do our work.
If not, we return a conflict response and let the other instance handle it.

The `finally` block ensures we always release the lock, even if something goes wrong.
PostgreSQL also **automatically releases advisory locks when connections close**, which is a nice safety net.

SQL Server has a similar feature with [sp_getapplock](https://learn.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-getapplock-transact-sql).

## Exploring the DistributedLock Library

While the DIY approach works, production applications need more sophisticated features.
The [DistributedLock](https://github.com/madelson/DistributedLock) library handles the edge cases and
provides multiple backend options (Postgres, Redis, SqlServer, etc.).
You know I'm a fan of not reinventing the wheel, so this is a great choice.

Install the package:

```powershell
Install-Package DistributedLock
```

I'll use the approach with `IDistributedLockProvider` which works nicely with DI.
You can acquire a lock without having to know anything about the underlying infrastructure.
All you have to do is register a lock provider implementation in your DI container.

For example, using Postgres:

```csharp
// Register the distributed lock provider
builder.Services.AddSingleton<IDistributedLockProvider>(
    (_) =>
    {
        return new PostgresDistributedSynchronizationProvider(
            builder.Configuration.GetConnectionString("distributed-locking")!);
    });
```

Or if you want to use Redis with the [Redlock algorithm](https://redis.io/docs/latest/develop/clients/patterns/distributed-locks/):

```csharp
// Requires StackExchange.Redis
builder.Services.AddSingleton<IConnectionMultiplexer>(
    (_) =>
    {
        return ConnectionMultiplexer.Connect(
            builder.Configuration.GetConnectionString("redis")!);
    });

// Register the distributed lock provider
builder.Services.AddSingleton<IDistributedLockProvider>(
    (sp) =>
    {
        var connectionMultiplexer = sp.GetRequiredService<IConnectionMultiplexer>();

        return new RedisDistributedSynchronizationProvider(connectionMultiplexer.GetDatabase());
    });
```

The usage is straightforward:

```csharp {4}
// You can also pass in a timeout, where the provider will keep retrying to acquire the lock
// until the timeout is reached.
IDistributedSynchronizationHandle? distributedLock = distributedLockProvider
    .TryAcquireLock("nightly-report");

// If we didn't get the lock, the object will be null
if (distributedLock is null)
{
    return Results.Conflict();
}

// It's important to wrap the lock in a using statement to ensure it's released properly
using (distributedLock)
{
    await DoWork();
}
```

The library handles all the tricky parts: timeouts, retries, and ensuring locks are released even in failure scenarios.

It also supports many backends (SQL Server, Azure, ZooKeeper, etc.), making it a solid choice for production workloads.

## Wrapping Up

**Distributed locking** isn't something you need every day.
But when you do, it saves you from subtle, painful bugs that only appear under load or in production.

**Start simple**: if you're already using Postgres, **advisory locks** are a powerful tool.

For a cleaner developer experience, reach for the **DistributedLock library**.

Choose the backend that fits your infrastructure (Postgres, Redis, SQL Server, etc.).

The right lock at the right time ensures your system stays consistent, reliable, and resilient, even across multiple processes and servers.

---



<Sponsorships>

What does context engineering have to do with shipping better code faster?
CodeRabbit explains in [**The art and science of context engineering for AI code reviews**](https://bit.ly/4mEuUMk).
Give it a read or [**try CodeRabbit today**](https://bit.ly/45Moq6W) and cut code review time and bugs in half.

[**You're a developer**](https://bit.ly/4nm76gc), not a Jenkins admin.
Switch to [**Bitbucket Pipelines**](https://bit.ly/4nm76gc): build, test, deploy, and get back to being a dev.

</Sponsorships>

Let's say you need to add an "export user data" **feature** to your .NET application.
Users click a button, your system generates their data export, uploads it to cloud storage, and emails them a secure download link.

In your current **layered architecture** with a **technical folder structure**, you'll probably touch six different folders:
`Controllers`, `Services`, `Models`, `DTOs`, `Repositories`, and `Validators`.
You'll scroll up and down your solution explorer, lose your train of thought,
and wonder why adding one feature requires editing files scattered across your entire codebase.

If this sounds familiar, you're not alone.
Most .NET developers start with the "standard" layered architecture, organizing code by **technical concerns** rather than **business features**.

But there's a better way: [**Vertical Slice Architecture**](vertical-slice-architecture).

## What is Vertical Slice Architecture?

Instead of organizing your code by technical layers (`Controllers`, `Services`, `Repositories`),
**Vertical Slice Architecture** organizes it by **business features**.
Each feature becomes a **self-contained** "slice" that includes **everything needed for that specific functionality**.

Think of it this way: traditional [**layered architecture**](clean-architecture-folder-structure) is like organizing a library by book size or color,
while [**vertical slices**](vertical-slice-architecture-structuring-vertical-slices) are like organizing by subject.
When you want to learn about history, you don't want to hunt through the entire library, you want all the history books in one place.

<div className="centered">
  <Image
    src="blogs/mnw_159/vertical_slice_architecture.png"
    width={1478 * 0.35}
    height={1079 * 0.35}
  />
</div>

Let's look at a practical example.

## The Traditional Approach vs. Vertical Slices

Let's look at our data export example.
Here's how a typical .NET project would structure this feature:

**Traditional Layered Structure:**

```
📁 Controllers/
└── UsersController.cs (export endpoint)
📁 Services/
├── IDataExportService.cs
├── DataExportService.cs
├── ICloudStorageService.cs
├── CloudStorageService.cs
├── IEmailService.cs
└── EmailService.cs
📁 Models/
├── ExportDataRequest.cs
└── ExportDataResponse.cs
📁 Repositories/
├── IUserRepository.cs
└── UserRepository.cs
```

Now here's the same functionality organized as vertical slices:

**Vertical Slice Structure:**

```
📁 Features/
└──📁 Users/
   └──📁 ExportData/
      ├── ExportUserData.cs
      └── ExportUserDataEndpoint.cs
      📁 Create/
      └── CreateUser.cs
      📁 GetById/
      └── GetUserById.cs
```

The `ExportData` folder **contains everything related** to exporting user data: the request, response, business logic, and API endpoint.

Notice I'm still injecting `ICloudStorageClient` and `IEmailSender` rather than putting that logic directly in the handler.
These are genuine **cross-cutting concerns** that **multiple features will use**.
The key is distinguishing between 'shared because it should be' vs 'shared because this pattern told me to'.

## Show Me the Code

I organize by domain first (`Users`), then by feature (`ExportData`).
Some teams prefer `Features/ExportUserData` directly, but I find the domain grouping helps when you have many features.
Related features stay visually grouped.

Here's what our data export **feature slice** looks like using a request, handler, and minimal APIs:

**Features/Users/ExportData/ExportUserData.cs**

```csharp
public static class ExportUserData
{
    public record Request(Guid UserId) : IRequest<Response>;

    public record Response(string DownloadUrl, DateTime ExpiresAt);

    public class Handler(
        AppDbContext dbContext,
        ICloudStorageClient storageClient,
        IEmailSender emailSender)
        : IRequestHandler<Request, Response>
    {
        public async Task<Response> Handle(Request request, CancellationToken ct = default)
        {
            // Get user data
            var user = await dbContext.Users
                .Include(u => u.Orders)
                .Include(u => u.Preferences)
                .FirstOrDefaultAsync(u => u.Id == request.UserId, ct);

            if (user == null)
            {
                throw new NotFoundException($"User {request.UserId} not found");
            }

            // Generate export data
            var exportData = new
            {
                user.Email,
                user.Name,
                user.CreatedAt,
                Orders = user.Orders.Select(o => new { o.Id, o.Total, o.Date }),
                Preferences = user.Preferences
            };

            // Upload to cloud storage
            var fileName = $"user-data-{user.Id}-{DateTime.UtcNow:yyyyMMdd}.json";
            var expiresAtUtc = DateTime.UtcNow.AddDays(7);

            var downloadUrl = await storageClient.UploadAsJsonAsync(
                fileName,
                exportData,
                expiresAtUtc,
                ct);

            // Send email notification
            await emailSender.SendDataExportEmailAsync(user.Email, downloadUrl, ct);

            return new Response(downloadUrl, expiresAtUtc);
        }
    }

    // Simple validation using FluentValidation
    public sealed class Validator : AbstractValidator<Request>
    {
        public Validator()
        {
            RuleFor(r => r.UserId).NotEmpty();
        }
    }
}
```

Everything related to exporting user data is in one place: the database query, validation, business logic, cloud storage integration, and email notification.

The minimal API endpoint is straightforward:

```csharp
public static class ExportUserDataEndpoint
{
    public static void Map(IEndpointRouteBuilder app)
    {
        app.MapPost("/users/{userId}/export", async (
            Guid userId,
            IRequestHandler<ExportUserData.Request, ExportUserData.Response> handler) =>
        {
            var response = await handler.Handle(new ExportUserData.Request(userId));
            return Results.Ok(response);
        });
    }
}
```

We could even define the endpoint inside the `ExportUserData.cs` file if we wanted to keep everything together.
This is more a matter of preference and team conventions.
Either approach works well, from my experience.

## One File vs. Multiple Files: Your Choice

You might have noticed something: I put everything in a single file.
This is a design choice with trade-offs.

**Single File Approach (ExportUserData.cs):**

```csharp
public static class ExportUserData
{
    public record Request(Guid UserId) : IRequest<Response>;
    public record Response(string DownloadUrl, DateTime ExpiresAt);
    public class Handler : IRequestHandler<Request, Response> { /* ... */ }
    public class Validator : AbstractValidator<Request> { /* ... */ }
}
```

**Multiple Files Approach:**

```
📁 ExportData/
├── ExportUserDataCommand.cs
├── ExportUserDataResponse.cs
├── ExportUserDataHandler.cs
├── ExportUserDataValidator.cs
└── ExportUserDataEndpoint.cs
```

**Single file is great when**: the feature is straightforward, you want **maximum locality**, and the file doesn't exceed a few hundred lines of code.

Lines of code isn't a strict rule, but if a file grows beyond 300-400 lines, consider splitting it up for readability.
Again, this is a matter of team preference and not a hard rule I go by.
It's important to trust your instincts and what feels right for your team.

**Multiple files work better when**: you have complex validation logic, multiple response types,
or when the handler grows large enough that you want to focus on one concern at a time.

You can even mix both approaches within the same project.

Both approaches keep related code together.
And this is what matters most in Vertical Slice Architecture.

## Why This Actually Works (And How to Start)

The benefits of vertical slices become obvious once you try it.
Your brain doesn't have to remember which files are related to which features.
Everything lives together.

Need to modify the data export feature?
Everything's in the `ExportData` folder.
No hunting across `Controllers`, `Services`, and `Repositories` layers.
Each slice can evolve independently, so simple CRUD operations stay simple while complex features like data export can use sophisticated approaches.

You don't need to rewrite your entire application overnight.
Start with new features using vertical slices.
As you touch existing code, gradually move related pieces into feature folders.

Good architecture is about making your codebase easier to understand and modify.
When all the code for a feature lives together, you spend less mental energy navigating your solution and more time solving actual problems.

Here are a few resources if you want to learn more:

- [**Clean Architecture: The Missing Chapter**](clean-architecture-the-missing-chapter)
- [**Modular Monolith Architecture**](what-is-a-modular-monolith)
- [**Screaming Architecture**](screaming-architecture)

All of these concepts tie together to help you build maintainable, scalable .NET applications.

---



<Sponsorships>

[**BoldSign API & SDKs for Developers**](https://boldsign.com/esignature-api/?utm_source=milanjovanovic&utm_medium=newsletter_ad&utm_campaign=boldsign) – Add contract signing to your app in minutes with our .NET SDK.
Fully embed sending and signing, control branding and emails, get transparent pricing, and start testing instantly in our free sandbox.
Trusted by 40K+ businesses and recognized as the
[**#1 developer-choice e-signature API**](https://boldsign.com/esignature-api/?utm_source=milanjovanovic&utm_medium=newsletter_ad&utm_campaign=boldsign).

[**MongoDB.local NYC September 17**](https://bit.ly/3HLHfPY).
AI is breaking the old rules. Your database has to keep up.
MongoDB wasn't retrofitted for AI; it was born for it, handling the messy, dynamic data that AI thrives on.
Join MongoDB.local NYC on Sept 17 at the Javits Center for talks, demos, hands-on labs, and networking.
Unlock new possibilities for your data in the age of AI.
[**Register here**](https://bit.ly/3HLHfPY) and use code SOCIAL50 to save 50%.

</Sponsorships>

I implemented [**full-text search**](how-i-implemented-full-text-search-on-my-website) on my static website using Lunr.js.
It works great for exact matches or phrases, but it doesn't understand meaning.
Someone searches for ["modular monolith"](search?q=modular%20monolith) and finds posts that contain these phrases.
But when they search for "database performance issues," they might miss my articles about query optimization and index tuning, even though that's exactly what they need.

[**Amazon S3 is now also a vector database**](https://aws.amazon.com/blogs/aws/introducing-amazon-s3-vectors-first-cloud-storage-with-native-vector-support-at-scale/),
and it's 90% cheaper (according to the announcement) than the alternatives.

For those of us running static sites or simple web apps, it means we can finally add semantic search without the operational overhead of
running a vector database like [Pinecone](https://www.pinecone.io/), [Weaviate](https://weaviate.io/), or [Qdrant](https://qdrant.tech/).

Instead, we can just use S3 buckets that understand vectors.

I'm adding it alongside my existing full-text search implementation, and the whole thing took an afternoon to build.

## How Semantic Search Works

The entire [semantic search](https://cloud.google.com/discover/what-is-semantic-search) flow is straightforward:

<Image
  src="blogs/mnw_158/semantic_search_flow.png"
  width={1585}
  height={977}
  alt="Semantic search flow"
/>

You have to start with some data.
In my case, this data comes from the articles I've written over the years.

Then we need an embedding model.
Amazon Bedrock offers many to choose from.
You use an embedding model to convert text into vectors.
Vectors are numerical representations of your data that capture semantic meaning.

Finally, we store these vectors in an S3 Vector Bucket, a new type of S3 bucket designed specifically for vector storage and search.
When someone searches, we convert their query into a vector and find the closest matches in the bucket.

If you want to understand the fundamentals, I wrote an article explaining what [**vector search**](what-is-vector-search-a-concise-guide) is.

## Generating Embeddings with Semantic Kernel

Microsoft's [Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) makes working with Bedrock surprisingly clean.

We'll need to install a few NuGet packages:

```powershell
# Semantic kernel packages
Install-Package Microsoft.SemanticKernel
Install-Package Microsoft.SemanticKernel.Connectors.Amazon

# AWS SDK for Bedrock
Install-Package AWSSDK.BedrockRuntime
```

We have to configure the embedding generator in our application.
Here we can specify which model to use for generating embeddings.
I'll use the Amazon Titan embedding model (`amazon.titan-embed-text-v2:0`) which produces 1024-dimensional vectors.

```csharp
builder.Services.AddBedrockEmbeddingGenerator("amazon.titan-embed-text-v2:0");

builder.Services.AddTransient(sp =>
{
    return new Kernel(sp);
});
```

And then we can use the `IEmbeddingGenerator` abstraction to generate embeddings:

```csharp {8}
var kernel = app.Services.GetRequiredService<Kernel>();

var embeddingGenerator = kernel.Services
    .GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();

var articleContent = await blogService.GetBlogContentAsync(articleUrl);

Embedding<float> embedding = await embeddingGenerator.GenerateAsync(articleContent);

embeddings.Add((articleUrl, embedding.Vector.ToArray()));
```

The number of dimensions varies depending on the embedding model you choose.
You can find more information about that in the documentation for your specific model.

## Creating Your S3 Vector Bucket

S3 Vectors uses an entirely new bucket type, not a feature you enable on existing buckets.
They're a fundamentally different storage system optimized for vector operations.
Creating one feels familiar if you've used S3 before:

<div className="bordered">
  <Image
    src="blogs/mnw_158/s3_vectors_bucket.png"
    width={1920}
    height={760}
    alt="Creating S3 Vectors bucket"
  />
</div>

Pick a unique name for your vector bucket:

<div className="bordered">
  <Image
    src="blogs/mnw_158/s3_vectors_bucket_create.png"
    width={1450}
    height={885}
    alt="Creating S3 Vectors bucket"
  />
</div>

And finally, you can create a **vector index** for your bucket.
You get to choose the number of dimensions in each vector.
This is dictated by the embedding model you use.
All vectors within a vector index should use the same embedding model.
Otherwise, you won't get the correct results when searching.
You also have to choose the [distance metric](https://en.wikipedia.org/wiki/Metric_space) (e.g., cosine similarity, Euclidean distance) for your vector index.
I went with [cosine similarity](https://en.wikipedia.org/wiki/Cosine_similarity), which is a common choice for text embeddings.
The additional settings let you configure non-filterable metadata.
By default, all metadata is filterable.

<div className="bordered">
  <Image
    src="blogs/mnw_158/s3_vectors_index_create.png"
    width={1920}
    height={950}
    alt="Creating S3 Vectors bucket"
  />
</div>

The UI is not polished at all, and you can't do much else.
I expect this will improve over time, but for now, everything else is done via the SDK or CLI.
There are certain limitations to be aware of, you can check out the docs [here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-limitations.html).

## Storing Vectors with Metadata

Now that we have our vector index, we can start storing vector embeddings with metadata.
Metadata is interesting because it enables filtered searches.
Want to search only recent posts? Posts in a specific category?
The metadata makes it possible.

Here's how you can store vectors:

```csharp
public async Task IndexBlogPost(BlogPost post)
{
    List<float> embedding = await GenerateEmbedding(post.Content);

    await s3VectorsClient.PutVectorsAsync(new PutVectorsRequest
    {
        VectorBucketName = "mjtech-articles-semantic-search",
        IndexName = "mjtech-article-content",
        Vectors = new List<Vector>
        {
            new PutInputVector
            {
                Key = post.Slug,
                Data = new VectorData
                {
                    Float32 = embedding
                },
                Metadata = new Document(new Dictionary<string, Document>
                {
                    ["title"] = post.Title,
                    ["date"] = post.PublishedDate.ToString("yyyy-MM-dd"),
                    ["category"] = post.Category,
                    ["url"] = $"/posts/{post.Slug}"
                })
            }
        }
    });
}
```

But if you're indexing your entire blog archive, doing it one post at a time is costly.
You can batch together multiple posts and index them in a single API call.
The SDK makes it easy to do this by accepting a list of vectors.

## Querying Vector Indexes

When someone searches your site, you convert their query into a vector and find the closest matches.

Here's how you can implement semantic search:

```csharp
public async Task<List<SearchResult>> SemanticSearch(
    string query,
    int topK = 10)
{
    // Convert search query to vector (use same model as vectors!)
    List<float> queryEmbedding = await GenerateEmbedding(query);

    var request = new QueryVectorsRequest
    {
        VectorBucketName = "mjtech-articles-semantic-search",
        IndexName = "mjtech-article-content",
        QueryVector = new VectorData
        {
            Float32 = queryEmbedding
        },
        TopK = topK,
        ReturnMetadata = true,
        ReturnDistance = true
    };

    QueryVectorsResponse response = await s3VectorsClient.QueryVectorsAsync(request);

    return response.Vectors.Select(v => new SearchResult
    {
        Distance = v.Distance,
        Title = v.Metadata.AsDictionary()["title"].ToString(),
        Url = v.Metadata.AsDictionary()["url"].ToString(),
        Category = v.Metadata.AsDictionary()["category"].ToString()
    }).ToList();
}
```

I omitted metadata filtering here, but you can explore the [documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-metadata-filtering.html)
for more details.

## Next Steps

Would I migrate from an existing vector database?
Probably not if everything's working.
The operational overhead would have to justify the switch.

But if you're adding semantic search for the first time, or your vector database bills are getting uncomfortable, S3 Vectors is a viable choice.
The setup takes an afternoon, the ongoing maintenance is zero, and your users get search that actually understands what they're looking for.

Don't forget that S3 Vectors is still in preview, so we can expect some changes before general availability.

Here's what I'm planning to do next:

1. Automatically update the vector index when I publish a new post. I can do this in my CI/CD pipeline, where I can detect new posts and trigger a re-indexing.
2. Expose a search endpoint that uses the new semantic search capabilities. Combine the results with the full-text search results.
3. Make sure everything is performant and cost-effective. Acceptable latency is under 500ms.
4. Share details about the implementation and any challenges faced. Especially around the costs of using an embedding model and vector storage.

That's all for today.

See you next week.

---



<Sponsorships>

[**Meet Auggie CLI**](https://bit.ly/3Vjz14v).
Augment Code is bringing the power of its AI coding agent and context engine right to your terminal.
You can use Auggie in a standalone interactive terminal session alongside your favorite editor or in any part of your software development stack.
[**Auggie CLI is now generally available**](https://bit.ly/3Vjz14v).

[**Build AI Agents with Postman**](https://bit.ly/4fYFJGF).
Design, test, and launch AI agents effortlessly with Postman.
Use trusted APIs and no-code tools to build workflows and transform them into agent-ready code.
Postman gives you everything you need to design, test and launch AI Agents—all in one platform.
[**Start Building**](https://bit.ly/4fYFJGF).

</Sponsorships>

You've built a distributed .NET application.
Multiple services, databases, message queues.
Now something's slow, and you need to figure out why.

**The Aspire Dashboard runs perfectly as a standalone container**,
giving you [**distributed tracing**](introduction-to-distributed-tracing-with-opentelemetry-in-dotnet),
[**structured logs**](5-serilog-best-practices-for-better-structured-logging),
and real-time metrics without the full orchestration framework.

While [**Aspire's orchestration**](dotnet-aspire-a-game-changer-for-cloud-native-development) is incredibly powerful for managing distributed applications,
sometimes you just need the observability piece.
Maybe you're already using [**Docker Compose**](using-dotnet-aspire-with-the-docker-publisher) or [Kubernetes](https://doineedkubernetes.com/).
Maybe you're debugging an existing system.
The standalone dashboard gives you valuable telemetry visualization with minimal setup.

Let's get it running in under 5 minutes.

## Why Run the Aspire Dashboard Standalone?

Most teams already have their deployment story figured out.
Docker Compose, Kubernetes, or some platform-specific orchestration.
You don't want to rewrite everything just to get observability.

The standalone **Aspire Dashboard** hits a sweet spot **for development**:

- **Drop-in observability** - Just add a container to your existing setup
- **Full OpenTelemetry support** - Works with any OTLP-compatible application
- **Developer-friendly** - Designed for local development and debugging
- **Immediate value** - See traces, logs, and metrics within minutes

One caveat: it's **in-memory only**.
Perfect for development and debugging, not for production.
For production, you'll want something like [**Jaeger**](introduction-to-distributed-tracing-with-opentelemetry-in-dotnet),
[Prometheus](https://prometheus.io/), or a commercial APM solution.

But for understanding what your code is doing right now?
It's exactly what you need.

## Step 1: Add the Dashboard Container

Drop this into your `docker-compose.yml`:

```yaml {3}
aspire-dashboard:
  container_name: aspire-dashboard
  image: mcr.microsoft.com/dotnet/aspire-dashboard:9.0
  ports:
    - 18888:18888
```

That's it. The dashboard is running.
Navigate to `http://localhost:18888` and... you'll need a token.

<Image
  src="blogs/mnw_157/aspire_dashboard_login.png"
  width={1920}
  height={1024}
  alt="Aspire Dashboard login screen"
/>

**Check the container logs** for the login link.
The dashboard generates a unique authentication token on startup:

<Image
  src="blogs/mnw_157/aspire_dashboard_login_link.png"
  width={1479}
  height={791}
  alt="Aspire Dashboard login link"
/>

Click that link, and you're in.
Empty for now, but not for long.

## Step 2: Wire Up Your .NET Services

Your services need to know where to send their telemetry.
Add these environment variables to your API containers:

```yaml {10,11}
users.api:
  image: ${DOCKER_REGISTRY-}usersapi
  build:
    context: .
    dockerfile: Users.Api/Dockerfile
  ports:
    - 5100:5100
    - 5101:5101
  environment:
    - OTEL_EXPORTER_OTLP_ENDPOINT=http://aspire-dashboard:18889
    - OTEL_EXPORTER_OTLP_PROTOCOL=grpc
  depends_on:
    - users.database
```

Notice port `18889`?
That's the OTLP ingestion endpoint.
The dashboard listens on `18888` for the UI, `18889` for telemetry data.

## Step 3: Configure OpenTelemetry in Your Code

Install the necessary [OpenTelemetry packages](https://www.nuget.org/packages?q=OpenTelemetry):

```xml
<PackageReference Include="Npgsql.OpenTelemetry" Version="9.0.3" />
<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.12.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.12.0" />
```

Then configure OpenTelemetry in your `Program.cs`:

```csharp
builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService(builder.Environment.ApplicationName))
    .WithTracing(tracing => tracing
        .AddHttpClientInstrumentation()
        .AddAspNetCoreInstrumentation()
        .AddNpgsql())
    .WithMetrics(metrics => metrics
        .AddHttpClientInstrumentation()
        .AddAspNetCoreInstrumentation());

builder.Logging.AddOpenTelemetry(options =>
{
    options.IncludeScopes = true;
    options.IncludeFormattedMessage = true;
});

builder.Services.AddOpenTelemetry().UseOtlpExporter();
```

This configuration:

- **Traces** HTTP calls, ASP.NET Core requests, and database queries
- **Collects metrics** on request duration, response codes, and throughput
- **Structured logging** with full context and formatted messages
- **Exports everything** to the Aspire Dashboard via OTLP

The `UseOtlpExporter()` method automatically picks up the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable you configured earlier.

## What You Get

Start your application and make a few requests.
The dashboard immediately lights up with data.

### Structured Logs

Every log entry includes full context: trace IDs, request paths, user identities.
Click any log to see the complete structured data.

<Image
  src="blogs/mnw_157/structured_logs.png"
  width={1920}
  height={1024}
  alt="Aspire Dashboard structured logs"
/>

### Distributed Traces

See the complete request flow across all your services.
Which database query is slow? Which HTTP call is failing?
The trace view shows you exactly where time is spent.

<Image
  src="blogs/mnw_157/distributed_traces.png"
  width={1920}
  height={1024}
  alt="Aspire Dashboard distributed traces"
/>

You can click into a trace to see the individual spans and any metadata associated with them.

<Image
  src="blogs/mnw_157/distributed_trace_details.png"
  width={1920}
  height={1024}
  alt="Aspire Dashboard distributed trace details"
/>

### Real-Time Metrics

Response times, error rates, throughput, all updating live.
Perfect for load testing or understanding traffic patterns.

<Image
  src="blogs/mnw_157/metrics.png"
  width={1920}
  height={1024}
  alt="Aspire Dashboard metrics"
/>

## Summary

The standalone **Aspire Dashboard** is perfect for local development and debugging.
Spin up your stack, make requests, and instantly see what's happening across all your services.
Find bottlenecks in the trace view, correlate logs with requests, watch metrics update in real-time.

Remember: this is for development only since data is in-memory and disappears on restart.
That last part might be fixed soon, according to the [**Aspire roadmap**](https://youtu.be/zvBu0OOCVos).
For production, you'll want proper solutions like Jaeger for tracing, Prometheus for metrics, or a commercial APM like Application Insights.

But for that immediate "what is my code actually doing?" question during development?
You've got professional observability in under 5 minutes.

Just add the container, configure OpenTelemetry, and start debugging like a pro.

That's all for today.

See you next Saturday.

---



<Sponsorships>

What does context engineering have to do with shipping better code faster?
CodeRabbit explains in [**The art and science of context engineering for AI code reviews**](https://bit.ly/4mEuUMk).
Give it a read or [**try CodeRabbit today**](https://bit.ly/45Moq6W) and cut code review time and bugs in half.

Meet [**Auggie CLI**](https://bit.ly/45C4F1O).
Augment Code is bringing the power of its AI coding agent and industry-leading context engine right to your terminal.
You can use Auggie in a standalone interactive terminal session alongside your favorite editor or in any part of your software development stack.
[**Auggie CLI is in beta...for now**](https://bit.ly/45C4F1O).

</Sponsorships>

As developers, we love abstractions.
Repositories, services, mappers, wrappers.
They make our code look "clean," they promise testability, and they give us the sense that we're building something flexible.

**Every abstraction is a loan.
You pay interest the moment you write it.**

Some abstractions earn their keep by isolating real volatility and protecting your system from change.
Others quietly pile up complexity, slow down onboarding, and hide performance problems behind layers of indirection.

Let's explore when abstractions pay dividends and when they become technical debt.

## When Abstractions Pay Off

The best abstractions **isolate true volatility**, the parts of your system that you genuinely expect to change.

### Example: Payment Processing

Your core business logic shouldn't depend directly on Stripe's SDK.
If you ever switch to Adyen or Braintree, you don't want that decision rippling through every corner of your codebase.
Here, an abstraction makes perfect sense:

```csharp
public interface IPaymentProcessor
{
    Task ProcessAsync(Order order, CancellationToken ct);
}

public class StripePaymentProcessor : IPaymentProcessor
{
    public async Task ProcessAsync(Order order, CancellationToken ct)
    {
        // Stripe-specific implementation
        // Handle webhooks, error codes, etc.
    }
}

public class AdyenPaymentProcessor : IPaymentProcessor
{
    public async Task ProcessAsync(Order order, CancellationToken ct)
    {
        // Adyen-specific implementation
        // Different API, same business outcome
    }
}
```

Now your business logic can stay focused on the domain:

```csharp {4}
public class CheckoutService(IPaymentProcessor processor)
{
    public Task CheckoutAsync(Order order, CancellationToken cancellationToken) =>
        processor.ProcessAsync(order, cancellationToken);
}
```

This abstraction isolates a genuinely unstable dependency (the payment provider) while keeping checkout logic independent.
When Stripe changes their API or you switch providers, only one class needs to change.

**That's a good abstraction**.
It buys you optionality where you actually need it.

## When Abstractions Become Technical Debt

Problems arise when we abstract things that aren't actually volatile.
We end up wrapping stable libraries or creating layers that don't add real value.
The "clean" layer you added today becomes tomorrow's maintenance burden.

### The Repository That Lost Its Way

Most teams start with something reasonable:

```csharp
public interface IUserRepository
{
    Task<IEnumerable<User>> GetAllAsync();
}
```

But as requirements evolve, so does the interface:

```csharp
public interface IUserRepository
{
    Task<IEnumerable<User>> GetAllAsync();
    Task<User?> GetByEmailAsync(string email);
    Task<IEnumerable<User>> GetActiveUsersAsync();
    Task<IEnumerable<User>> GetUsersByRoleAsync(string role);
    Task<IEnumerable<User>> SearchAsync(string keyword, int page, int pageSize);
    Task<IEnumerable<User>> GetUsersWithRecentActivityAsync(DateTime since);
    // ...and it keeps growing
}
```

Suddenly, the repository is leaking **query logic into its interface**.
Every new way of fetching users means another method, and your "abstraction" becomes a grab bag of every possible query.

Meanwhile, Entity Framework already gives you all of this through LINQ: strongly typed queries that map directly to SQL.
Instead of leveraging that power, you've introduced an indirection layer that hides query performance characteristics and often performs worse.
The repository pattern made sense when ORMs were immature.
Today, it's often just ceremony.

I've been guilty of this myself.
But part of maturing as a developer is recognizing when patterns become anti-patterns.
Repositories make sense when they encapsulate complex query logic or provide a unified API over multiple data sources.
But you should strive to keep them focused on domain logic.
As soon as they explode into a myriad of methods for every possible query, it's a sign that the abstraction has failed.

## Service Wrappers: The Good and The Ugly

Not all service wrappers are problematic. Context matters.

**✅ Good Example: External API Integration**

When integrating with external APIs, a wrapper provides genuine value by centralizing concerns:

```csharp
public interface IGitHubClient
{
    Task<UserDto?> GetUserAsync(string username);
    Task<IReadOnlyList<RepoDto>> GetRepositoriesAsync(string username);
}

public class GitHubClient(HttpClient httpClient) : IGitHubClient
{
    public Task<UserDto?> GetUserAsync(string username) =>
        httpClient.GetFromJsonAsync<UserDto>($"/users/{username}");

    public Task<IReadOnlyList<RepoDto>> GetRepositoriesAsync(string username) =>
        httpClient.GetFromJsonAsync<IReadOnlyList<RepoDto>>($"/users/{username}/repos");
}
```

This wrapper isolates GitHub's API details.
When authentication changes or endpoints evolve, you update one place.
Your business logic never needs to know about HTTP headers, base URLs, or JSON serialization.

**❌ Bad Example: Pass-Through Services**

The trouble starts when we wrap our own stable services without adding business value:

```csharp
public class UserService(IUserRepository userRepository)
{
    // Just forwarding calls with no added value
    public Task<User?> GetByIdAsync(Guid id) => userRepository.GetByIdAsync(id);
    public Task<IEnumerable<User>> GetAllAsync() => userRepository.GetAllAsync();
    public Task SaveAsync(User user) => userRepository.SaveAsync(user);
}
```

This `UserService` is pure indirection.
All it does is forward calls to the `IUserRepository`.
It doesn't enforce business rules, add validation, implement caching, or provide any real functionality.
It's a layer that exists only because "services are good architecture."

As these anemic wrappers multiply, your codebase becomes a maze.
Developers waste time navigating layers instead of focusing on where business logic actually lives.

## Making Better Decisions

Here's how to think about when abstractions are worth the investment:

### Abstract Policies, Not Mechanics

- **Policies** are decisions that might change: which payment provider to use, how to handle caching, retry strategies for external calls
- **Mechanics** are stable implementation details: EF Core's LINQ syntax, `HttpClient` configuration, JSON serialization

Abstract policies because they give you flexibility.
Don't abstract mechanics, they're already stable APIs that rarely change in breaking ways.

### Wait for the Second Implementation

If you only have one implementation, resist the interface urge.
A single implementation doesn't justify abstraction, it's premature generalization that adds complexity without benefit.

Consider this evolution:

```csharp
// Step 1: Start concrete
public class EmailNotifier
{
    public async Task SendAsync(string to, string subject, string body)
    {
        // SMTP implementation
    }
}

// Step 2: Need SMS? Now abstract
public interface INotifier
{
    Task SendAsync(string to, string subject, string body);
}

public class EmailNotifier : INotifier { /* ... */ }
public class SmsNotifier : INotifier { /* ... */ }
```

The abstraction emerges naturally when you actually need it.
The interface reveals itself through real requirements, not imaginary ones.

### Keep Implementations Inside, Abstractions at Boundaries

Inside your application, prefer **concrete types**.
Use Entity Framework directly, configure `HttpClient` as typed clients, work with domain entities.
Only introduce abstractions where your system meets the outside world: external APIs, third-party SDKs, infrastructure services.

That's where change is most likely, and where abstractions earn their keep.

## Refactoring Out Bad Abstractions

Regularly review your abstractions with this question: If I removed this abstraction, would the code become simpler or more complex?

If removing an interface or service layer would make the code clearer and more direct,
that abstraction is probably costing more than it's worth.
Don't be afraid to delete unnecessary layers.
Simpler code is often better code.

When you identify problematic abstractions, here's how to safely remove them:

1. **Identify the real consumers**. Who actually needs the abstraction?
2. **Inline the interface**. Replace abstract calls with concrete implementations.
3. **Delete the wrapper**. Remove the unnecessary indirection.
4. **Simplify the calling code**. Take advantage of the concrete API's features.

For example, replacing a repository with direct EF Core usage:

```csharp
// Before: Hidden behind repository
var users = await _userRepo.GetActiveUsersWithRecentOrders();

// After: Direct, optimized query
var users = await _context.Users
    .Where(u => u.IsActive)
    .Where(u => u.Orders.Any(o => o.CreatedAt > DateTime.Now.AddDays(-30)))
    .Include(u => u.Orders.Take(5))
    .ToListAsync();
```

The concrete version is more explicit about what data it fetches and how, making performance characteristics visible and optimization possible.
If you need the same query in multiple places, you could move it into an extension method to make it shareable.

## The Bottom Line

Abstractions are powerful tools for managing complexity and change, but they're not free.
Each one adds indirection, cognitive overhead, and maintenance burden.

The [**cleanest architecture**](/pragmatic-clean-architecture) isn't the one with the most layers.
It's the one where each layer has a clear, justified purpose.

Before adding your next abstraction, ask yourself:

- Am I abstracting a policy or just a mechanic?
- Do I have two implementations, or am I speculating about future needs?
- Will this make my system more adaptable, or just harder to follow?
- If I removed this layer, would the code become simpler?

Remember: abstractions are loans that accrue interest over time.
Make sure you're borrowing for the right reasons, not just out of habit.

The goal is to use abstractions intentionally, where they solve real problems and protect against genuine volatility.
Build abstractions that earn their keep.
Delete the ones that don't.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

Who's lost too much time maintaining Jenkins?🙋
[**Bitbucket Pipelines**](https://fnf.dev/45A17x6) offers cloud-native CI/CD with efficient autoscaling and no installation or plug-ins to manage.
That can translate to a 70% reduction in operational costs, freeing up your team to deliver real value, not endless maintenance.
Supports any language, OS, or architecture.
[**Try it free to level up your workflow today**](https://fnf.dev/45A17x6).

[**Learn how to stand up AI agents in 20 minutes**](https://bit.ly/4mGuPrh) with Postman's AI Agent Playbook webinar series in August and September—
where each 20-minute session walks through real AI agents you can deploy for engineering, support, and sales workflows using your existing APIs and tools.
You'll walk away with usable templates that'll help your team save time on day 1.
[**Register for the series**](https://bit.ly/4mGuPrh).

</Sponsorships>

I wanted to see what the simplest practical AI app I could build was, and this is what I came up with.

Every week, I publish blog posts covering different topics - architecture patterns, cloud services, programming techniques, business insights.
Sometimes I write about DevOps, other times about security.
After years of writing, I realized I had no systematic way to categorize my content.
Sure, I could manually tag each post, but where's the fun in that?

So I built a simple AI-powered blog analyzer.
It fetches any blog post, extracts the content, and uses AI to automatically categorize it.
The entire thing took less than an hour to build thanks to **.NET Aspire 9.4** and it's new **GitHub Models** integration.

What surprised me wasn't just how easy it was to build, but how the integration completely removes the typical AI service complexity.
No juggling API keys in configuration files, no manual HTTP client setup, no wrestling with different SDK patterns for different AI providers.
You declare an AI model in your AppHost just like you would a database, and Aspire handles the rest.

Here's what I learned building this simple app, and how you can use the same patterns to add AI to your applications.

## What are GitHub Models?

[GitHub Models](https://docs.github.com/en/github-models) is a service that provides access to AI models from OpenAI, Microsoft, Meta, and others through a single API.
You get free tier access for prototyping (with rate limits), an interactive playground for testing prompts, and pay-per-use billing when you're ready for production.

The models range from cost-effective options like **GPT-4o-mini** to more advanced models.
Each model has different strengths - some excel at reasoning, others at code generation or creative writing.

When you combine GitHub Models with .NET Aspire's orchestration, you get:

- Automatic API key management via [external parameters](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/external-parameters)
- [**Service discovery**](how-dotnet-aspire-simplifies-service-discovery) between your components
- Built-in [**health checks**](health-checks-in-asp-net-core) and [**telemetry**](introduction-to-distributed-tracing-with-opentelemetry-in-dotnet)
- Consistent configuration patterns

## Setting Up the Integration

The GitHub Models integration splits into two parts: configuring models in your `AppHost` and consuming them in your services.

### AppHost Configuration

In your AppHost project, you define AI models as resources alongside your other services:

```csharp {4,8}
var builder = DistributedApplication.CreateBuilder(args);

var blogService = builder.AddExternalService("dotnet-blog", "https://www.milanjovanovic.tech/blog");
var aiModel = builder.AddGitHubModel("ai-model", "openai/gpt-4o-mini");

builder.AddProject<Projects.GitHub_Models_Demo>("github-models-demo")
    .WithReference(blogService)
    .WithReference(aiModel);
```

Notice how the AI model sits alongside the external blog service.
Both are resources that your main application depends on.
Aspire handles the connection details - you just declare what you need.

Make sure to install the [Aspire.Hosting.GitHub.Models](https://www.nuget.org/packages/Aspire.Hosting.GitHub.Models) NuGet package to enable this integration.

To call the GitHub Models inference API you need a personal access token with the `models:read` permission.
When you call `AddGitHubModel`, Aspire automatically creates a parameter named `{resourceName}-gh-apikey` (for example, `ai-model-gh-apikey`)

You can populate the parameter through user secrets for local development:

```json
{
  "Parameters": {
    "ai-model-gh-apikey": "github_pat_YOUR_PERSONAL_ACCESS_TOKEN"
  }
}
```

If you don't provide this value from configuration, Aspire will prompt you to enter it when you run the application.
You'll have an option to store the access token securely in user secrets.

### Client Setup

In your consuming service, add the Azure AI client (which works with GitHub Models):

```csharp {2}
builder
    .AddAzureChatCompletionsClient("ai-model")
    .AddChatClient();
```

That's it.
No manual HTTP client configuration, no hardcoded endpoints.
The `ai-model` name matches what you defined in the AppHost, and Aspire wires everything together.

You'll need to install the [Aspire.Azure.AI.Inference](https://www.nuget.org/packages/Aspire.Azure.AI.Inference) NuGet package to enable this integration.
It also exposes an integration with [**MEAI**](working-with-llms-in-dotnet-using-microsoft-extensions-ai) using the `AddChatClient` method.
This simplifies the process of interacting with LLMs in your applications.

## Building the Blog Analyzer

Now let's build something useful.
We'll create a service that fetches blog posts and uses AI to categorize them.

### Fetching Blog Content

First, we need to extract readable content from blog posts:

```csharp
public async Task<string> GetBlogContentAsync(string slug)
{
    var response = await httpClient.GetAsync(slug);
    response.EnsureSuccessStatusCode();
    var htmlContent = await response.Content.ReadAsStringAsync();

    return ExtractArticleContent(htmlContent);
}
```

The `ExtractArticleContent` method (not shown) uses [HtmlAgilityPack](https://www.nuget.org/packages/htmlagilitypack/) to pull out the main article text,
stripping away navigation, ads, and other page elements.

### AI-Powered Categorization

Here's where it gets interesting.
We'll use the AI model to analyze the content and assign a category:

```csharp {3-13, 15}
public async Task<string> SummarizeBlogAsync(string blogContent)
{
    var prompt =
        @"""
        You are a blog content assistant. Summarize the following blog post
        as one of the following categories: Technology, Business, Programming,
        Architecture, DevOps, Cloud, Security, General.
        Only those eight values are allowed. Be as concise as possible.
        I want a 1-word response with one of these options: Technology, Business,
        Programming, Architecture, DevOps, Cloud, Security, General.

        The blog content is: {blogContent}
        """;

    var response = await chatClient.GetResponseAsync(prompt);

    if (!response.Messages.Any())
    {
        return "General";
    }

    var category = response.Messages.First().Text switch
    {
        var s when s.Contains("Technology", StringComparison.OrdinalIgnoreCase) => "Technology",
        var s when s.Contains("Business", StringComparison.OrdinalIgnoreCase) => "Business",
        var s when s.Contains("Programming", StringComparison.OrdinalIgnoreCase) => "Programming",
        var s when s.Contains("Architecture", StringComparison.OrdinalIgnoreCase) => "Architecture",
        var s when s.Contains("DevOps", StringComparison.OrdinalIgnoreCase) => "DevOps",
        var s when s.Contains("Cloud", StringComparison.OrdinalIgnoreCase) => "Cloud",
        var s when s.Contains("Security", StringComparison.OrdinalIgnoreCase) => "Security",
        var s when s.Contains("General", StringComparison.OrdinalIgnoreCase) => "General",
        _ => "General"
    };

    return category;
}
```

A few things make this work reliably:

- The prompt is explicit about allowed categories
- We request a single-word response to avoid parsing complex output
- The switch expression handles variations in the AI's response
- There's always a fallback to "General"

### Exposing the API

Finally, we wrap everything in a simple API endpoint:

```csharp {4, 7}
app.MapPost("/summarize-blog", async (
    string slug,
    BlogService blogService,
    BlogSummarizer blogSummarizer) =>
{
    var content = await blogService.GetBlogContentAsync(slug);
    var category = await blogSummarizer.SummarizeBlogAsync(content);

    return Results.Ok(new
    {
        slug,
        category,
        content = $"{content.Substring(0, 50)}..."
    });
});
```

Call this endpoint with a blog post URL slug, and you get back the category and a preview of the content.
The dependency injection handles service resolution, and Aspire manages the AI model connection behind the scenes.

Here's an example response:

```json
{
  "slug": "screaming-architecture", // https://www.milanjovanovic.tech/blog/screaming-architecture
  "category": "Architecture",
  "content": "If you were to glance at the folder structure of y..."
}
```

Here's the distributed trace in Aspire showing the request and response flow.
You can see the request to the blog service and the AI model.

<Image
  src="blogs/mnw_155/distributed_trace.png"
  width={1919}
  height={518}
  alt="Distributed trace in Aspire showing the request and response flow using GitHub Models"
/>

## Wrapping Up

The GitHub Models integration with .NET Aspire removes much of the complexity from adding AI to your applications.
You get:

- Simple configuration through the AppHost pattern
- Automatic service discovery and connection management
- Access to multiple AI models without vendor lock-in
- The same observability and deployment benefits as other Aspire resources

Whether you're [**adding AI to an existing system**](working-with-llms-in-dotnet-using-microsoft-extensions-ai) or building something new, this integration provides the foundation you need.
Start with simple categorization or summarization, then expand as you learn what works for your use case.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**The AI Agent for professional .NET developers**](https://fnf.dev/4lhJzeW)\
You ship to production; vibes won't cut it.
Augment Code's powerful AI coding agent meets professional .NET developers exactly where they are,
delivering deep context into even the gnarliest codebases and learning how you work.
[**Now supporting GPT-5 and Sonnet 4**](https://fnf.dev/4lhJzeW).

[**Get free senior engineer level code reviews**](https://fnf.dev/4mfgcvq) right in your IDE (VS Code, Cursor, Windsurf) with CodeRabbit.
Instantly catches bugs and code smells, suggests refactorings, and delivers context aware feedback for every commit, all without configuration.
Supports all programming languages; trusted on 12M+ PRs across 1M repos and 70K+ OSS projects.
[**Install the extension and start vibe checking your code today**](https://fnf.dev/4mfgcvq).

</Sponsorships>

Bad APIs create friction for developers, increase maintenance costs, and make change risky.
Good API design doesn't mean following every "best practice" blindly.
It means choosing the right trade-offs for your context and sticking to them.

Here are 5 common mistakes I see repeatedly, why they cause problems, and how to avoid them with pragmatic, battle-tested solutions.

## 1. Inconsistent Naming and Structure

Naming is the first thing consumers see.
Inconsistency here leads to constant documentation lookups, broken expectations, and more bugs.

Look, we've all been there.
You successfully call `/users` and `/products`, so naturally you try `/orders`.
But nope, this API uses `/order-list` for some reason.
Now you're back to the docs, breaking your flow, wondering why anyone would do this.
Multiply this friction by dozens of endpoints, and you've built an API that makes developers want to flip tables.

I get it, deep URL hierarchies like `/users/{id}/habits/{habitId}/entries/{entryId}/comments/{commentId}` feel satisfying.
They mirror your beautiful domain model!
But here's the thing: you've just **hardcoded your entire data structure** into your URLs.
When business requirements change (and they will), you can't reorganize without breaking clients.

Plus, what happens when someone only has a comment ID?
They need to somehow figure out the user, habit, and entry IDs just to fetch one comment.
That's ridiculous.

Keep it simple with **plural nouns**: `/users`, `/habits`, `/entries`.
No more guessing if it's `user` or `users`.

**Only nest when something truly belongs to something else.**
User settings belong to and die with the user, so `/users/{id}/settings` makes sense.
Comments can exist independently, so `/users/{id}/posts/{postId}/comments` can be simplified.

Instead, flatten with filters:

```http
# Instead of deep nesting
GET /users/{userId}/habits/{habitId}/entries

# Use filters for flexibility
GET /entries?userId={userId}&habitId={habitId}
GET /entries?habitId={habitId}  # Now you can get entries without knowing the user
```

And please, for the love of all that is holy, wrap your arrays:

```json
{
  "data": [
    {
      "id": "e_8YH",
      "habitId": "code-review",
      "at": "2025-08-08T09:17:34Z",
      "value": 5,
      "unit": "reviews",
      "tags": ["team"]
    },
    {
      "id": "e_8Z2",
      "habitId": "deep-work",
      "at": "2025-08-07T07:00:00Z",
      "value": 2,
      "unit": "pomodoros",
      "note": "EF filters optimized"
    }
  ],
  "total": 42,
  "hasMore": true,
  "nextCursor": "cursor_01J9KaBcd"
}
```

I know it feels like pointless boilerplate now, but trust me, when you need to add pagination info six months from now,
you'll thank yourself for not having to break every client that expects a raw array.

Yeah, the [REST](https://en.wikipedia.org/wiki/REST) purists will complain that filters aren't "RESTful enough."
Let them.
Your API will be flexible, maintainable, and actually pleasant to use.
I'll take that over conceptual purity any day.

## 2. Poor Versioning Strategy

Everyone defaults to [**versioning**](api-versioning-in-aspnetcore) (`/v1/users`) thinking they're being smart about future changes.
Spoiler: they're not. They're creating a maintenance nightmare.

Here's what actually happens when you have v1, v2, and v3 running:

- Every bug needs to be fixed three times
- Every security patch needs three deployments
- Your docs become a choose-your-own-adventure novel
- Support has no idea which version that angry customer is using
- You spend weekends maintaining code you wrote two years ago

But the worst part?
**Versioning makes you lazy**.
Instead of thinking "how can I evolve this without breaking clients?" you just think "eh, I'll bump the version."
Now your clients have to rewrite their entire integration because you wanted to rename a field.

Watch this disaster unfold:

```
v1: GET /users returns {id, name, email}
v2: GET /users returns {id, fullName, emailAddress}  // "looks cleaner!"
v3: GET /users returns {id, firstName, lastName, email}  // "we need split names!"
```

Congrats, you're now maintaining three different response formats for the same damn data.
That v1 client?
They'll never get new features unless they rewrite everything.
Found a critical bug? Hope you enjoy patching it three times!

Here's the **radical idea**: **don't version at all**.
I'm serious.

Add fields, don't replace them:

```json
// What you ship first
{ "id": 1, "name": "John Doe" }

// What you ship later (keeping the old field)
{
  "id": 1,
  "name": "John Doe",  // Still there! Mark it deprecated in docs
  "firstName": "John",
  "lastName": "Doe"
}
```

Need optional features?
Use query parameters:

```http
GET /users/{id}?include=habits,entries
GET /users/{id}?format=detailed
```

If you absolutely must make a breaking change (and really think about this), create a new resource:

```http
# Old faithful, unchanged
GET /users/{id}

# New hotness
GET /userProfiles/{id}
```

When breaking changes are truly unavoidable, at least be a decent human about it.
Give people 6-12 months notice.
Run both versions in parallel.
Write a migration guide that doesn't suck.
And for crying out loud, monitor who's still using the old stuff so you can reach out before pulling the plug.

Yes, this means you need to actually think about your API design upfront.
You can't just YOLO field names and fix them later.
But that constraint will make you design better APIs, and future-you will buy present-you a beer.

If you want to learn more about this, I recommend reading [API Change Management](https://medium.com/good-api/api-change-management-2fe5bba32e9b).

## 3. Ignoring Pagination, Filtering, and Searching

That `GET /entries` endpoint works great with your 10 test records.
Then you launch, get actual users, and suddenly you're returning 100,000 entries in a single response.
Your API times out, your mobile users on crappy connections hate you, and your cloud bill makes you cry.

"We'll add pagination later," you said.
Well, now it's later, and adding pagination means breaking every client that expects an array.
Nice job.

Without filtering, your clients are downloading thousands of records to find the five they actually need.
It's like making someone download all of Wikipedia to read one article.
Your servers are melting, serializing data nobody wants.
Your users are burning through their data plans.
Everyone loses.

**Filtering** is for when you know exactly what you want:

```http
GET /entries?habitId=123&date=2025-08-01&status=completed
```

**Searching** is for when you kinda know what you want:

```http
GET /entries/search?q=morning+run+park
```

Don't try to be clever and combine them.
Filtering uses your database indexes efficiently.
Searching needs full-text magic.
Mix them and you'll end up with something that does neither well.

For pagination, you've got two choices, and they both kinda suck in different ways.

**Offset/limit** is what everyone starts with:

```http
GET /entries?offset=100&limit=50
             # or you can call them skip and take
             # or you can call them page and pageSize
             # use whatever you like best
```

It's dead simple and lets users jump to page 5, but here's the fun part: add or delete an item while someone's paginating, and they'll either skip entries or see duplicates.
Plus, asking for offset=10000 makes your database cry as it counts through all those rows.

[**Cursor-based pagination**](understanding-cursor-pagination-and-why-its-so-fast-deep-dive) is the "proper" solution:

```http
GET /entries?limit=50&cursor=eyJpZCI6MTIzfQ==
```

Rock solid, no skipped items, consistent performance.
But you can't jump to arbitrary pages and cursors can become invalid if underlying data changes significantly.

Yeah, implementing all this is a pain.
You need cursor encoding, parameter validation, query optimization.
But trying to add it after launch?
Wouldn't recommend.
Just build it right the first time.

## 4. Unclear or Inconsistent Error Handling

`{"error": "An error occurred"}` — if you return this, I hate you.

Seriously, when your API spits out these useless errors, here's what happens: I try random stuff hoping something works.
I add defensive code everywhere because I don't trust you.
I flood your support channel asking what's wrong.
Then I complain about your API on social media (any publicity is good publicity, eh?).

A good error tells me three things: **what broke**, **why it broke**, and **how to fix it**.
Is that so hard?

Stop inventing your own janky error format.
Use [**Problem Details**](problem-details-for-aspnetcore-apis) (RFC 9457) like a civilized developer:

```json
{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The request body contains invalid fields",
  "instance": "/habits/123",
  "errors": [
    {
      "field": "name",
      "reason": "Must be between 1 and 100 characters",
      "value": ""
    },
    {
      "field": "frequency",
      "reason": "Must be one of: daily, weekly, monthly",
      "value": "sometimes"
    }
  ]
}
```

See how that actually helps me fix the problem? Revolutionary, I know.

And please use the right status codes. It's not that hard:

- `400 Bad Request`: You sent garbage
- `401 Unauthorized`: Who are you?
- `403 Forbidden`: I know who you are, but no
- `404 Not Found`: That thing doesn't exist
- `409 Conflict`: That conflicts with something
- `422 Unprocessable Entity`: I understand what you want, but it's wrong\
  (_I don't use this personally, and prefer returning 400 for validation failures_)
- `429 Too Many Requests`: Slow down, cowboy
- `500 Internal Server Error`: We screwed up
- `503 Service Unavailable`: We're drowning, try again later

Now, don't go leaking your entire stack trace in production like an amateur.
Give friendly errors to users, detailed errors in dev/staging, and log the gory details server-side where you can actually use them.

## 5. Ignoring Security Until It's Too Late

"We'll add auth in phase 2" — famous last words before your API becomes a data buffet for hackers.
Ask the [Tea app](https://www.teaforwomen.com/cyberincident) how that worked out for them.

Here's what happens when you try to bolt on security later: Every client breaks when you add authentication.
That data you've been leaking? It's probably been scraped already.
Your compliance audit? Failed.
That one security incident? Your users will bring it up for years.

**Authentication** (who are you?) and **Authorization** (what can you do?) are different things.
I've seen so many APIs that check if you're logged in but never check if you should actually access that data.
Don't be that person.

[**Rate limiting**](advanced-rate-limiting-use-cases-in-dotnet) isn't just about stopping abuse, it's about fairness.
Start simple: 1000 requests per hour per API key.
When they hit the limit, return `429` with headers showing when they can try again.
Then get fancy: different limits for different endpoints, higher limits for paying customers,
lower limits for that one client who keeps doing weird stuff.

**HTTPS everywhere**.
Yes, even for your internal "no one will ever find this" API.
It's 2025, not 2005.
[Let's Encrypt](https://letsencrypt.org/) is free.
You have no excuse.

Look, security makes things slower and more complex.
Auth checks on every request, encryption overhead, state management for rate limiting, it all adds up.
But you know what's worse?
Explaining to your users why their data is being sold on the dark web.
Build security in from the start, or prepare for a world of pain.

## Final Thoughts

Good API design isn't about perfection, it's about making intentional, informed decisions.
Every choice is a tradeoff.
Consistency might limit flexibility.
Security will impact performance.
Stability means slower innovation.

Here's what actually matters: **know your tradeoffs and own them**.
Document why you made these choices (future you will thank you).
Stay consistent even when it's tempting not to.
Design for evolution, not some imaginary perfect future.
And listen to your users, but don't turn your API into a frankenstein monster trying to please everyone.

**Your API is a promise to other developers**.
Every time you break that promise (with a breaking change, an inconsistent pattern, or a useless error message) you lose their trust.
And trust me, developers hold grudges.

Build the API you'd want to use.
Your developers will thank you, your support team will thank you, and honestly, you'll thank yourself six months from now when you have to maintain this thing.

Want to dive deeper? Check out my [**Pragmatic REST APIs**](/pragmatic-rest-apis) course where I cover all of this (and more).

P.S. Any sharp language here is just me being snarky for emphasis.
I'm critiquing patterns, not people.
Don't take the strong wording too seriously.

---


Previous issues of The .NET Weekly