DEV Community: Remigiusz Zalewski

Stop Using HasData for All Your Data Seeding in .NET

Remigiusz Zalewski — Tue, 10 Nov 2026 16:30:09 +0000

Introduction

A fresh database is useless until something fills it. EF Core gives you three different ways to do that, and most projects pick one and force everything through it. That is how you end up with fake data baked into a migration, or a production table that never got its rows.

The fix is to stop treating seed data as one thing. In this post I build a small .NET 10 expense tracker on EF Core 10 and SQL Server that uses all three approaches side by side: HasData for fixed reference data, UseSeeding / UseAsyncSeeding for default data the app needs, and a custom seeder class with Bogus for local fake data. One fresh database fills itself with all three, and running the app twice doesn't duplicate a single row.

🎬 Watch the full video here:

Three kinds of seed data, three tools

Before any code, sort your data into one of these buckets:

Fixed reference data - currency codes, country lists. The same in every environment, and it only changes when you decide to change it. Use HasData.
Default data the app needs to work, which can grow - the starting categories in an expense tracker. Users add their own next to them, but the defaults must always be there. Use UseSeeding and UseAsyncSeeding.
Fake data for local development - so you aren't staring at empty screens. Use your own seeder class.

One thing worth knowing: the Microsoft docs now call HasData "model managed data" and recommend UseSeeding as the default way to seed. HasData isn't deprecated, but it's no longer the general answer.

The demo app

The app is a .NET 10 Minimal API with three entities - Currency, Category and Expense - and an AppDbContext registered with the SQL Server provider (Microsoft.EntityFrameworkCore.SqlServer, plus Microsoft.EntityFrameworkCore.Design for the tooling):

public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
    public DbSet<Currency> Currencies => Set<Currency>();
    public DbSet<Category> Categories => Set<Category>();
    public DbSet<Expense> Expenses => Set<Expense>();

    // ...
}

Currency uses its three-letter Code as the primary key, Category has an Id and a unique Name, and every Expense points to one of each. In development, Program.cs creates the database and applies pending migrations on startup:

if (app.Environment.IsDevelopment())
{
    await using var scope = app.Services.CreateAsyncScope();
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
    // ...
}

That's fine locally. For applying migrations in a real deployment, see EF Core migration bundles in CI/CD.

Approach 1: HasData for fixed reference data

Currencies are the textbook case: purely static, and they don't depend on anything you'd have to read from the database first. They go straight into OnModelCreating:

modelBuilder.Entity<Currency>(currency =>
{
    currency.HasKey(c => c.Code);
    // ...

    currency.HasData(
        new Currency { Code = "USD", Name = "US Dollar", Symbol = "$" },
        new Currency { Code = "EUR", Name = "Euro", Symbol = "€" },
        new Currency { Code = "GBP", Name = "British Pound", Symbol = "£" });
});

Notice that every row sets the primary key explicitly. Even when the database would generate keys for you, HasData needs them: the model snapshot has to identify each row to work out later whether it was added, changed or removed.

HasData only does anything through migrations, so the next step is to create one:

dotnet tool install --global dotnet-ef
dotnet ef migrations add SeedCurrencies

The generated migration turns the HasData call into an InsertData call, and Down deletes the same rows again by key:

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.InsertData(
        table: "Currencies",
        columns: new[] { "Code", "Name", "Symbol" },
        values: new object[,]
        {
            { "EUR", "Euro", "€" },
            { "GBP", "British Pound", "£" },
            { "USD", "US Dollar", "$" }
        });
}

Now say you want to rename "British Pound" to just "Pound". You change the value in OnModelCreating:

new Currency { Code = "GBP", Name = "Pound", Symbol = "£" });

And you need another migration, because everything about HasData goes through migrations:

dotnet ef migrations add UpdatedCurrencies

EF Core compares the model with the snapshot and generates an update for exactly that one value:

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.UpdateData(
        table: "Currencies",
        keyColumn: "Code",
        keyValue: "GBP",
        column: "Name",
        value: "Pound");
}

Down does the reverse and sets the name back to "British Pound". This is where the explicit primary key pays off: keyValue: "GBP" is how EF Core knows which row to update. After MigrateAsync runs, the __EFMigrationsHistory table lists the applied migrations and the Currencies table has the latest values.

That is the trade-off: data changes are versioned and reviewable, but every edit costs a migration. Fine for currencies, painful for anything that changes often.

Approach 2: UseSeeding for default data that can grow

Categories are different. The app should always start with Food, Transport, Housing and Entertainment, but users can add their own through the API. That's exactly what UseSeeding was added for.

The logic lives in a static CategorySeeder with a synchronous and an asynchronous method:

public static class CategorySeeder
{
    private static readonly string[] Defaults = ["Food", "Transport", "Housing", "Entertainment"];

    public static void Seed(DbContext context)
    {
        // same logic, synchronous calls
    }

    public static async Task SeedAsync(DbContext context, CancellationToken cancellationToken)
    {
        var categories = context.Set<Category>();
        var existing = await categories.Select(c => c.Name).ToHashSetAsync(cancellationToken);

        categories.AddRange(Defaults
            .Where(name => !existing.Contains(name))
            .Select(name => new Category { Name = name }));

        await context.SaveChangesAsync(cancellationToken);
    }
}

A few things to notice:

The parameter is the base DbContext, not AppDbContext. That's what the seeding delegates hand you, so the seeder gets the set with context.Set<Category>().
It loads only the existing names into a HashSet and inserts the defaults that are missing. That makes it safe to run on every startup and every deployment.
Categories added by users are never touched.

Then wire both methods into the DbContext options in Program.cs:

builder.Services.AddDbContext<AppDbContext>(options => options
    .UseSqlServer(builder.Configuration.GetConnectionString("Default"))
    .UseSeeding((context, _) => CategorySeeder.Seed(context))
    .UseAsyncSeeding((context, _, cancellationToken)
        => CategorySeeder.SeedAsync(context, cancellationToken)));

Why you need both

Which delegate runs depends on who triggers the seeding:

UseSeeding runs for dotnet ef database update, Migrate(), EnsureCreated() and migration bundles.
UseAsyncSeeding runs for MigrateAsync() and EnsureCreatedAsync().

Same job, two entry points, so implement both.

In the demo, the first run with MigrateAsync hits SeedAsync with zero existing categories and inserts all four - with no migration created for them. Switching to Migrate() hits the synchronous Seed instead, which finds the four categories already there and adds nothing.

Approach 3: A custom seeder class for fake data

For fake development data, UseSeeding is the wrong tool. Generating realistic data needs more than a DbContext - configuration, logging, maybe other services - and it should only ever run in development. So this one gets its own class, using the Bogus library:

dotnet add package Bogus

The number of expenses comes from configuration through a small options class in the Options folder:

public class SeedOptions
{
    public const string SectionName = "Seed";

    public int ExpenseCount { get; set; } = 25;
}

With a matching section in appsettings.Development.json:

{
  "Seed": {
    "ExpenseCount": 25
  }
}

And the registration in Program.cs:

builder.Services.Configure<SeedOptions>
    (builder.Configuration.GetSection(SeedOptions.SectionName));
builder.Services.AddScoped<DevDataSeeder>();

The seeder itself uses constructor injection, so it can take whatever it needs:

public class DevDataSeeder(
    AppDbContext db,
    IOptions<SeedOptions> options,
    ILogger<DevDataSeeder> logger)
{
    public async Task SeedAsync(CancellationToken cancellationToken = default)
    {
        if (await db.Expenses.AnyAsync(cancellationToken))
        {
            logger.LogInformation("Expenses already exist, skipping dev seed");
            return;
        }

        var categories = await db.Categories.ToListAsync(cancellationToken);
        var currencies = await db.Currencies.ToListAsync(cancellationToken);

        var faker = new Faker<Expense>()
            .UseSeed(42)
            .RuleFor(e => e.Description, f => f.Commerce.ProductName())
            .RuleFor(e => e.Amount, f => f.Finance.Amount(5, 200))
            .RuleFor(e => e.Category, f => categories[f.IndexFaker % categories.Count])
            .RuleFor(e => e.Currency, f => currencies[f.IndexFaker % currencies.Count]);

        db.Expenses.AddRange(faker.Generate(options.Value.ExpenseCount));

        await db.SaveChangesAsync(cancellationToken);
        // ...
    }
}

What matters here:

The guard at the top. If any expenses exist, it does nothing, so a second run adds no rows.
UseSeed(42) makes Bogus generate the same data every time, so everyone on the team gets identical rows on their machine.
Real foreign keys. Categories and currencies are read from the database - the ones the first two approaches just put there - and IndexFaker spreads expenses across them.

Finally, call it right after migrating, inside the same development-only block:

if (app.Environment.IsDevelopment())
{
    await using var scope = app.Services.CreateAsyncScope();
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();

    var seeder = scope.ServiceProvider.GetRequiredService<DevDataSeeder>();
    await seeder.SeedAsync();
}

On the first run the database gets 25 realistic-looking expenses. On the next run the guard kicks in and nothing is added.

Data seeding pitfalls

Dynamic values in HasData - put DateTime.UtcNow or Guid.NewGuid() in there and the model is different every time it's built. dotnet ef database update then fails with a pending model changes error. Use fixed values, or move that data to UseSeeding.
Wiring only UseAsyncSeeding - your app is async, so it runs fine. Then dotnet ef database update applies the migrations and fails because no synchronous seed delegate was provided, leaving the tables created but empty. Always wire both.
Deploying with SQL scripts - this one hurts in production. In the output of dotnet ef migrations script, the currency inserts are there because they live in migrations. The categories aren't, because UseSeeding is code, not SQL, and nothing runs it. If you need seeding in your pipeline, use a migration bundle (which does call UseSeeding) or keep that data in migrations.
Seeding after a downgrade - seeding also runs after dotnet ef database update 0, and the seeder fails with "Invalid object name" because the Categories table is already gone. If you downgrade like this, check that the table exists first.
Secrets in seed code - seed code goes into source control and HasData values end up in your migrations too. If you need an admin account, read the password from configuration, never from a string in code.

Key Takeaways

Seed data isn't one thing: fixed reference data, default data that can grow and fake development data each need a different tool.
HasData fits fixed reference data that's identical everywhere - set primary keys explicitly and accept one migration per change.
UseSeeding and UseAsyncSeeding fit default data the app needs; wire both and make the seeder idempotent so it's safe on every deployment.
Fake data or anything that needs real services belongs in your own seeder class, kept behind a development check.
If you're not sure, start with UseSeeding - it's what Microsoft recommends and the right default.

Get the Full Source Code

The complete solution - the .NET 10 expense tracker API with the AppDbContext, the HasData currency migrations, the CategorySeeder wired through UseSeeding and UseAsyncSeeding, and the Bogus-based DevDataSeeder with its options - is available to Patreon supporters on Patreon.

Resources

Claude Code Free Setup: OmniRoute + Free LLM APIs (2026)

Remigiusz Zalewski — Wed, 04 Nov 2026 08:03:49 +0000

Introduction

Lots of AI providers give you a free tier, but each one alone is too small for a coding agent. A few requests, you hit the rate limit, and Claude Code stops. In this post you set up OmniRoute as a central hub for free LLMs on your own machine, connect OpenRouter, Nvidia, Mistral and Groq to it, and point Claude Code at the result so that a session costs nothing.

🎬 Watch the full video here:

Why OmniRoute

OmniRoute is an open-source AI gateway under the MIT license, and it runs on your own PC. You connect your providers once, and it gives every tool one endpoint and one API key.

Two features make it work for Claude Code:

Combos - a combo is a set of models you design yourself. If one model is out of quota or failing, OmniRoute moves on to the next one in the background.
API format translation - Claude Code talks to OmniRoute in the Anthropic format, even when the model behind it is something completely different.

Prerequisites

You need two things before setting up OmniRoute. The first is Node.js, which you can check from the command line:

node -v

If that doesn't print a version, download the installer for your operating system from nodejs.org.

The second is Claude Code itself. If you don't have it yet, use the install command from the Claude Code setup page.

Install and run OmniRoute

OmniRoute is an npm package, so installing and starting it takes two commands:

npm install -g omniroute
omniroute

The output confirms that OmniRoute is running and shows the API base URL and the dashboard address. Open the dashboard and sign in. The default password is CHANGEME, which I left in place for this local demo. To set your own, run this and confirm the new password:

omniroute reset-password

The homepage has a quick start guide, a view of your connected providers with their status, and your recent requests with the model, the input and output tokens, and when each one happened.

Choosing free providers

Open Providers in the left-hand menu. There are about 370 AI providers listed, so turn on the free tier filter to avoid models you would pay for.

Based on my experience, these are the ones I can recommend: Antigravity CLI, Cerebras, Groq, Kiro AI, LLM7.io, Mistral, Nvidia and OpenRouter. In this post I connect four of them.

Connect OpenRouter

OpenRouter goes first because it's an aggregator: one API key gives you access to more than one AI provider at once.

Register at openrouter.ai, open the API keys tab and click New key.
Name the key omniroute, then choose an expiration and a credit limit. I used no expiration for the demo and a $50 limit, which never gets touched because only free models are used.
In the OpenRouter section of OmniRoute, click Add connection, paste the key and check that it's valid.
Name the connection, use the option to import only free models, save and enable the connection.
Import the models. I got 17.
Run Test all models.

The last step is the one that matters. An imported model isn't necessarily a working one, and only models with an OK response are usable from Claude Code. In my case, 8 of the 17 worked.

Connect Nvidia, Mistral and Groq

The pattern is the same for every other provider: create an API key on the provider's site, add a connection in OmniRoute, check the key, import only free models, save, enable and test.

Nvidia - register on the Nvidia website and generate a key in its API keys section. I kept the default one-year expiration. 5 of 7 models worked.
Mistral - create the key at admin.mistral.ai, not studio.mistral.ai. Only one model was available for me.
Groq - create the key in the API keys tab of your Groq account. 5 of 5 models worked.

The OmniRoute homepage now shows four connected providers. Experiment with others too: Kiro AI, Antigravity CLI and Cerebras are all very good options.

Create the combo

A combo works like a fallback policy. It uses all the models you configure, and once one of them is out of use, OmniRoute switches to another automatically in the background.

Click Create combo, name it omniroute-combo and choose the free stack quick template. To add a model, select a provider, select one of its models and click Add step.

The model list shows everything that was imported, not what currently works, so run the provider's model test again and pick from those results. I added four OpenRouter models, all five Groq models, the one Mistral model and the working Nvidia models.

The last step is the routing strategy. I use round robin, a circular distribution where each request goes to the next model in rotation, which spreads the load equally across all of them. Priority and the other strategies are there too, each with a description, so pick what suits your use case. Then click through to save.

Now use Test combo. Most of my models came back green, but one OpenRouter model returned a 429 error from the provider. That doesn't break anything: OmniRoute skips that model and doesn't use it.

Point Claude Code at OmniRoute

Claude Code needs its own key, so create one in the API Keys section of OmniRoute. I named mine after Claude Code. Copy the value, then open your project. I used the MCP server project from Build Your First MCP Server in .NET, the same one that I used in Run Claude Code for FREE with Ollama.

In the root of the project, create a .claude folder with a settings.local.json file inside it. This makes Claude Code use OmniRoute in this project instead of your Claude subscription:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your-omniroute-api-key>",
    "ANTHROPIC_MODEL": "omniroute-combo",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "omniroute-combo",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "omniroute-combo",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "omniroute-combo"
  }
}

The base URL is your local OmniRoute, and the auth token is the key you just created. All four model values are your combo name, so whichever model Claude Code asks for, the request goes through the combo.

Save the file, open a terminal in the project and start Claude Code:

claude

The startup screen shows omniroute-combo as the model, which confirms that the setup works.

Testing it on real tasks

The first test was on the existing codebase: generate a Markdown file with documentation based on the code. The result had an architecture diagram, the project structure and the data models, and it looks very decent.

The second test was to build something new: a tic-tac-toe game in pure HTML. One prompt and a few seconds later there was a .html file that runs in any modern browser. I opened it in the browser built into VS Code and played a round. It detects when someone wins, and undo and restart work as well. It's impressive what these free models can do through Claude Code.

Check what it cost

OmniRoute has an analytics section with the total tokens used, input tokens, output tokens and the estimated cost, along with highlights, performance and infrastructure data. For this whole experiment the estimated cost was 0.

OmniRoute pitfalls

Imported doesn't mean working - about half of my OpenRouter models failed the test. Always run Test all models before relying on a model.
The combo's model list isn't filtered - it shows every imported model, so retest the provider right before you add steps instead of picking by name.
Looking for the Mistral key in the wrong place - API keys are created at admin.mistral.ai, not studio.mistral.ai.
Using a different name in the settings file - the model values must match your combo name exactly, so check it in OmniRoute before pasting.
Worrying about a 429 in the combo test - one failing model doesn't break the combo, because OmniRoute skips it and uses the others.

Key Takeaways

A single free tier is too small for a coding agent, but OmniRoute puts many free providers behind one local endpoint and one API key.
A combo combines models from different providers, and when one is out of quota or failing, OmniRoute moves to another automatically.
Test models after importing them and before adding them to a combo, because many imported free models don't respond.
A .claude/settings.local.json file with the base URL, the API key and your combo name is all it takes to point a project's Claude Code at OmniRoute.
The analytics section lets you confirm the result: the estimated cost of my session was 0.

Resources

Run Claude Code for FREE with Ollama

Remigiusz Zalewski — Mon, 02 Nov 2026 07:42:51 +0000

Introduction

Claude Code can run against a local AI model on your own computer - free, private, and it even works offline. Your code never leaves your machine and there are no tokens to pay for.

🎬 Watch the full video here:

Why this works

Claude Code talks to its model through the Anthropic API, and Ollama speaks that same API. So you point Claude Code at Ollama on your machine instead of the cloud, and that's it: no tokens to pay for, and your code never leaves your computer.

Step 1: Install Ollama

On the ollama.com downloads page there are install commands for the three operating systems. On Windows, copy the command, paste it into PowerShell and run it. Once installed, open the Ollama app - it has three tabs: applications, chat and settings.

Step 2: Pick the right model for your hardware

Know your hardware first. What matters is the VRAM of your GPU, or the unified memory on a Mac. If you have no GPU (or an old Mac), the model falls back to CPU and RAM, which is much slower and will quickly become frustrating.

Match parameters to memory. As a rough guide from the video: with 8 GB of VRAM or unified memory you can usually handle 3-9 billion parameter chat models at Q4; with 16 GB, around 20-27 billion parameters.

Check benchmarks for your exact setup. You can search ollama.com blindly, or use a "can I run AI" style website where you enter your GPU, VRAM and RAM and get benchmarks for local models by use case (coding, image and so on). The useful part is how much of your GPU or unified memory a model uses. If it shows something like 102% of VRAM, the remaining work is offloaded to CPU and RAM, and you'll feel the slowdown. (This isn't a sponsored recommendation - it was just handy for comparing models against your hardware.)

Leave room for context. The VRAM figure in those benchmarks does not include the context, which is how much the model can process and remember during a session. That's a real trade-off: one model may reason better but leave little memory for context, while a smaller one with, say, 69% of VRAM free can run a much larger context. In the video the choice was GPT-OSS with 20 billion parameters with roughly a 32K token context.

Step 3: Download the model

The model's page on ollama.com shows the command. For GPT-OSS 20B:

ollama run gpt-oss:20b

Step 4: Set the context length

Before using it, change the context size. You can set the environment variable yourself, but the easiest way is the UI: open Ollama's Settings, find Context length and set it to 32K, based on what your hardware allows.

Then try the model in Ollama's chat window. Asking it to explain RAG returns an answer almost immediately - a good sign before connecting it to Claude Code.

Step 5: Connect it to Claude Code

First install Claude Code by copying the install command from its documentation. Then launch it through Ollama:

ollama launch claude

Ollama lists a few recommended models, plus the one you downloaded earlier - select GPT-OSS 20B and press Enter. You'll see a notice that the model isn't recognized. That doesn't mean it's broken: it simply isn't an official Claude model, so Claude Code flags the custom one.

Why the context size matters

The video demonstrates the failure mode. When the context is too small, the model can forget what you asked during its thinking phase - ask "what is C#?" and you might get the weather in some city instead. With the context set properly, the same question returns a correct answer about the programming language, with no hallucinated detour.

A real task: generate documentation from a codebase

To test it on real work, open a terminal in the folder of the MCP server project from Build Your First MCP Server in .NET, run ollama launch claude with the same model, and ask it to generate a Markdown documentation file based on the code. The result is a README.md built from the codebase: the database and connection strings, example requests and responses, and the available tools. For a free model running entirely on your own machine, the output is very good.

Key Takeaways

Claude Code can run against a local model through Ollama (ollama launch claude) - free, private and offline, because Ollama speaks the Anthropic API.
Pick a model by VRAM or unified memory, and keep headroom for context; set Ollama's context length (32K in the demo) or the model can lose track of your request.

This Pattern Cleaned Up My EF Core Queries

Remigiusz Zalewski — Fri, 16 Oct 2026 07:03:00 +0000

Introduction

Take a look at a repository interface that has been in production for a few months:

public interface IOrderRepository
{
    Task<List<Order>> GetStalePendingAsync(DateTime placedBefore, CancellationToken ct = default);
    Task<int> CountStalePendingAsync(DateTime placedBefore, CancellationToken ct = default);
    Task<List<Order>> GetShippingToAsync(string city, CancellationToken ct = default);
    Task<List<Order>> GetLargeAsync(decimal minimumTotal, CancellationToken ct = default);
}

Four methods, four copies of the same Where, Include, OrderBy dance - and the rule for what makes an order "stale" is already written twice, once for the list and once for the count. The day someone decides cancelled orders shouldn't count, one of them gets fixed and the other doesn't. And every new screen adds a fifth method, then a sixth.

The Specification pattern fixes this. By the end, that interface has two methods - ListAsync(spec) and CountAsync(spec) - that never need to change again. Same endpoints, same JSON, and the same SQL going to the database. The refactoring changes where the query lives, not what it sends. In this video we build it from scratch on .NET 10 and EF Core 10, so you understand every line before you decide whether to pull in a library.

Subscribe to my .NET Newsletter:

Remigiusz Zalewski | Become A Better .NET Software Engineer

Blog about .NET/C#/Angular/React/Azure

remigiuszzalewski.com

What a specification actually is

A specification is a small class that describes one query in business terms: which rows you want, and how to load them - the related data and the sort order. The repository gets one method that can run any specification. So a new query means a new, named class, not another repository method and another change to the interface.

The idea goes back to Eric Evans and Martin Fowler in the Domain-Driven Design days. The flavour most .NET teams use with EF Core - and the one the popular Ardalis.Specification library is built around - carries includes and sorting along with the filter. That's the version built in the video.

The demo is an ASP.NET Core Minimal API with an Order entity, its OrderItems, a status, a shipping city and a created date, seeded with 40 orders on SQL Server LocalDB. Every SQL command is logged to the console - that's the proof, at every step, that nothing changes on the database side.

The base class: one filter, optional includes and sorting

The whole pattern rests on a small abstract Specification<TEntity> base class with four things on it:

Criteria - the filter. It comes in through the primary constructor, so every specification must have one. You can't forget it.
Includes - a read-only list of related data to load.
OrderBy / OrderByDescending - an optional sort key.

Includes and sorting are set through protected helpers (AddInclude, ApplyOrderBy, ApplyOrderByDescending) that a specification calls from its own constructor, only when it needs them. Nobody outside can change them afterwards.

The one detail that makes or breaks the pattern with EF Core is the type of the criteria:

public Expression<Func<TEntity, bool>> Criteria { get; }

Not Func<TEntity, bool> - an Expression. A Func is compiled code, a black box. An Expression is data: a tree that describes the lambda ("property Status, equals, Pending, and property CreatedAt, less than, this value"). EF Core can walk that tree and turn it into a SQL WHERE clause. Getting this wrong doesn't throw - it just quietly gets slow. More on that in the pitfalls.

Your first specification reads like the business talks

With the base class in place, the first query moves out of the repository and into its own class, StalePendingOrders. The filter (pending, and created before a cut-off date) goes to the base constructor; the include of Items and the oldest-first sort are set in the constructor body.

Read it out loud: stale pending orders, with their items, oldest first. That's how the business talks about it, and now that's what the code is called. It's the same three pieces that lived in GetStalePendingAsync - just with a name.

The endpoint then becomes a one-liner that builds the spec and hands it over:

var stale = await orders.ListAsync(new StalePendingOrders(placedBefore), ct);

The evaluator: write it once, reuse it in every repository

Something has to turn a specification into an actual query. You could write that as a private method inside OrderRepository - but look at what it needs: the Criteria, the Includes, the sort. All of that lives on Specification<TEntity>. None of it is about orders. The only order-specific thing is where the query starts - dbContext.Orders.

So the video puts it in a generic SpecificationEvaluator instead: take any starting IQueryable, add the Where, add each Include, then apply the sort. The day you add a CustomerRepository, it uses the exact same class. It carries the same where TEntity : class constraint EF Core itself puts on DbSet<TEntity> and Include.

Crucially, it returns an IQueryable - nothing has hit the database yet. Each call just adds another node to the expression tree. Nothing runs until the repository calls ToListAsync, which is when EF Core translates the whole tree into one SQL statement.

That split is deliberate:

The evaluator builds the query. It's generic and shared by every repository.
The repository decides where the query starts and when it runs. It stays specific to its entity, and it's the natural place for read-side options - pass dbContext.Orders.AsNoTracking() as the starting point and the evaluator doesn't change at all.

Naming note: in eShopOnWeb and Ardalis.Specification this class is also called a SpecificationEvaluator. Those tutorials also show a SpecificationBuilder - that's a different thing. It's the fluent API you use inside a specification (Query.Where(...).Include(...)) to replace the protected helpers. The builder describes a query; the evaluator runs it against EF Core.

Run the endpoint and the console shows exactly what the old method sent: a SELECT from Orders with a LEFT JOIN to OrderItems, a WHERE on status and date, and an ORDER BY CreatedAt. EF Core also appends the order's Id to the ORDER BY - you never asked for it, but it needs each order's joined rows next to each other to group items back under the right Order object. The old method got exactly the same thing. And placedBefore shows up as a SQL parameter, not a hard-coded date, because the lambda captured it - same SQL text for any value, so SQL Server reuses the cached plan.

The payoff: list and count share one rule

Now the duplicated rule. CountAsync takes the very same StalePendingOrders the list endpoint uses. The "what counts as stale" rule exists exactly once - change it in the class and both endpoints change together.

CountAsync deliberately applies only Criteria. Joining order items and sorting rows you're only going to count is wasted work, and the console confirms it: a plain SELECT COUNT(*) with the same WHERE.

Descending sorts and computed totals

Two more specifications round out the API:

OrdersShippingTo - orders for one city, newest first. It exercises the OrderByDescending branch of the evaluator, and since city is captured, it goes to SQL as a parameter: no string concatenation, no SQL injection.
LargeOrders - orders worth at least a minimum total, biggest first. This is the interesting one. Both the filter and the sort are on a computed total - the sum of quantity × unit price across the items. There's no Total column.

: base(o => o.Items.Sum(i => i.Quantity * i.UnitPrice) >= minimumTotal)

Because it's all expressions, EF Core translates that Sum into a correlated subquery and uses it in both the WHERE and the ORDER BY. You get a computed filter and sort without loading a single order into memory first.

Delete the old methods

The satisfying part: delete GetStalePendingAsync, CountStalePendingAsync, GetShippingToAsync and GetLargeAsync. What's left:

public interface IOrderRepository
{
    Task<List<Order>> ListAsync(Specification<Order> specification, CancellationToken ct = default);
    Task<int> CountAsync(Specification<Order> specification, CancellationToken ct = default);
}

The next query your team needs is a new class in the Specifications folder. The interface doesn't change, the repository doesn't change, and in code review you're looking at one small, named file instead of a diff scattered across an interface and an implementation. Run all four requests again: same responses, and side by side, the same SQL.

Key Takeaways

A specification is one named class that describes one query in business terms: the filter, the related data to load, and the sort order.
A minimal Specification<TEntity> base class takes Criteria through its constructor and exposes Includes, OrderBy and OrderByDescending, set via protected helpers.
A generic SpecificationEvaluator turns any specification into an IQueryable - written once, shared by every repository. The repository only decides where the query starts and when it runs.
The criteria must be Expression<Func<TEntity, bool>>. A Func silently turns a SQL WHERE into a full table load filtered in memory.
Reusing one specification for both the list and the count means a business rule like "stale pending order" lives in exactly one place - and the count applies only the criteria.
The refactoring changes where the query lives, not what it sends: same JSON, same SQL, same parameterised plans.
Don't use it everywhere: one-off queries are simpler as repository methods, and combinable search filters are better as chained Where calls.

Get the Full Source Code

The complete runnable solution - both the Before and After versions of the Orders API, the Specification<TEntity> base class, the evaluator, all three specifications, the seeded LocalDB database and the .http file to compare the SQL yourself - is available to Patreon supporters. If you'd rather run it and watch the console than rebuild it from the walkthrough above, you can find it on Patreon.

EF Core 10 Is INSANE - Overview of Game Changer features

Remigiusz Zalewski — Sat, 03 Oct 2026 11:59:56 +0000

Introduction

Most EF Core releases are a bag of small quality-of-life fixes. EF Core 10 has a few of those too, but it also lands several changes that remove long-standing workarounds: you no longer hand-write a GroupJoin plus SelectMany plus DefaultIfEmpty to get a left join, you no longer have one all-or-nothing global query filter, and you can now do vector similarity search against SQL Server without a bolt-on.

This video runs through the headline features against a small blog/book/author model on .NET 10 and SQL Server. Here is what each one is and when you would reach for it.

🎬 Watch the full video here:

LeftJoin and RightJoin as real operators

Before EF Core 10, a left join in LINQ-to-Entities was the incantation everyone had to look up: GroupJoin, then SelectMany, then DefaultIfEmpty. It worked, it translated fine, and nobody remembered the shape.

EF Core 10 adds LeftJoin and RightJoin as first-class query operators:

await context.Authors
    .LeftJoin(context.Books,
        author => author.Id,
        book => book.AuthorId,
        (author, book) => new { author.Name, book.Title })
    .ToListAsync();

Same generated SQL as the old pattern, a fraction of the code, and it reads like the join you meant. This is the change you will use most often.

Named query filters

Global query filters (soft delete, multi-tenancy, "only verified rows") have always had one painful limitation: one filter per entity, and IgnoreQueryFilters() turned off all of them. If you had soft-delete and tenant filtering on the same entity, you could not disable one without disabling the other.

EF Core 10 lets you name filters and toggle them individually:

modelBuilder.Entity<Author>()
    .HasQueryFilter("SoftDeletionFilter", a => !a.IsDeleted)
    .HasQueryFilter("VerifiedFilter", a => a.IsVerified);

// disable just one, keep the rest
await context.Authors
    .IgnoreQueryFilters(["SoftDeletionFilter"])
    .ToListAsync();

An admin screen that needs to see soft-deleted rows but must still respect tenant isolation is now a one-liner instead of a manual re-implementation of the other filter.

Complex types mapped to JSON

EF Core 10 lets a complex type be stored as a JSON document in a column:

modelBuilder.Entity<Book>()
    .ComplexProperty(x => x.Attributes, x => x.ToJson());

BookAttributes (genre, page count, language, a string[] of tags) lives in one nvarchar column as JSON, and you can still query into it in LINQ:

await context.Books
    .Where(b => b.Attributes.Pages > 300)
    .ToListAsync();

EF Core translates the predicate to SQL JSON path access. This is the pragmatic middle ground between a rigid column-per-field schema and an untyped blob - useful for attribute bags that vary and are not worth their own table.

Vector search for RAG, built in

This is the flashiest one. SQL Server 2025 has a native vector type, and EF Core 10 can map to it and translate distance functions:

[Column(TypeName = "vector(1536)")]
public SqlVector<float> Vector { get; set; }

await context.BlogPosts
    .OrderBy(p => EF.Functions.VectorDistance("cosine", p.Vector, queryVector))
    .Take(3)
    .ToListAsync();

Combined with Microsoft.Extensions.AI to generate embeddings (the demo uses an Azure OpenAI embedding model), you get the retrieval half of a RAG pipeline - "find the three most semantically similar posts to this text" - as an ordinary EF Core query, with no separate vector database.

Also worth knowing

ExecuteUpdateAsync continues to expand what it can express, including updates driven by other columns, so more bulk updates avoid loading entities.
Various LINQ translation gaps closed, and better SQL for existing queries - the kind of thing you get for free by upgrading.

Common pitfalls

Vector search needs the right SQL Server. The native vector type is SQL Server 2025 / recent Azure SQL. Older targets do not have it.
Named filters are opt-in by name. If you migrate existing single filters, give them names and update every IgnoreQueryFilters() call site, or behavior shifts.
JSON-mapped complex types query well but index differently. Filtering b.Attributes.Pages > 300 works, but performance depends on JSON indexing support in your database - do not assume it is free on a large table.
LeftJoin result selectors can yield nulls. The right-side entity is null when there is no match; project defensively.

Key Takeaways

LeftJoin / RightJoin are now first-class operators - retire the GroupJoin + SelectMany + DefaultIfEmpty pattern.
Query filters can be named and disabled individually with IgnoreQueryFilters(["Name"]), fixing the all-or-nothing problem for soft delete plus multi-tenancy.
Complex types can be stored as JSON in a single column and still be queried in LINQ.
SQL Server's native vector type plus EF.Functions.VectorDistance gives you similarity search - the retrieval side of RAG - without a dedicated vector store.
Upgrading also brings a batch of translation improvements you do not have to ask for.

Get the Full Source Code

The complete runnable solution - the blog/book/author model, the named query filters, the JSON complex type, and the vector-search endpoints wired to an embedding generator - is available to Patreon supporters. If you want to run the RAG query against real embeddings instead of rebuilding it from the walkthrough above, you can find it on Patreon.

Resources

Api Key Authentication in ASP .NET Core

Remigiusz Zalewski — Sat, 12 Sep 2026 16:08:34 +0000

Introduction

Not every API needs users, tokens, and a login flow. An internal service that another service calls, a webhook receiver, a partner integration - these often just need "prove you are an allowed caller", and an API key in a header does that with almost no ceremony. The client sends a secret string, the server checks it, done.

This video implements API key authentication in ASP.NET Core on .NET 9 three different ways, because where you put the check matters: middleware for the whole app, an MVC authorization filter for controllers, and an endpoint filter for minimal API routes. All three read the header name and expected key from configuration through the Options pattern.

🎬 Watch the full video here:

https://youtu.be/RPd1md_9oRM

Where the key and header name live

Both values come from appsettings.json, bound to a typed options class rather than read as loose strings:

public class ApiKeyOptions
{
    public const string AuthenticationApiKey = "Authentication:ApiKey";
    public required string HeaderName { get; set; }
    public required string Key { get; set; }
}

builder.Services.Configure<ApiKeyOptions>(
    builder.Configuration.GetSection(ApiKeyOptions.AuthenticationApiKey));

Every enforcement approach below injects IOptions<ApiKeyOptions>. In production the actual key value belongs in a secret store (user secrets locally, Key Vault or environment variables in the cloud), never committed in appsettings.json.

Approach 1: middleware

Middleware runs for every request in the pipeline. It reads the configured header, compares it to the configured key, and short-circuits with 401 if it does not match:

if (!context.Request.Headers.TryGetValue(_options.HeaderName, out var extractedApiKey)
    || extractedApiKey != _options.Key)
{
    context.Response.StatusCode = StatusCodes.Status401Unauthorized;
    await context.Response.WriteAsync("Api Key is invalid");
    return;
}

await _next(context);

Use middleware when the entire API is key-protected and there are no public endpoints. It is the bluntest instrument - there is no per-route opt-out without adding path checks inside it, which gets ugly fast.

Approach 2: MVC authorization filter

For controllers, an IAuthorizationFilter runs as part of MVC's filter pipeline and can be applied exactly where you want it:

public class ApiKeyAuthFilter : IAuthorizationFilter
{
    public void OnAuthorization(AuthorizationFilterContext context)
    {
        if (/* header missing or wrong */)
            context.Result = new UnauthorizedObjectResult("Api Key is invalid");
    }
}

Because it has a constructor dependency (IOptions<ApiKeyOptions>), register it in DI and apply it with [ServiceFilter(typeof(ApiKeyAuthFilter))] on a controller or action. Now [AllowAnonymous]-style selectivity is trivial: put the attribute on the controllers that need it and leave the rest open.

Approach 3: minimal API endpoint filter

Minimal APIs have their own filter abstraction, IEndpointFilter, added per route or per route group:

app.MapGet("/weatherforecastminimal", () => /* ... */)
   .AddEndpointFilter<ApiKeyEndpointFilter>();

The filter's InvokeAsync checks the header and either writes a 401 or calls next(context) to continue. Apply it to a MapGroup and every route in that group is protected in one line. This is the idiomatic choice for a minimal API codebase.

A real gotcha in the demo

The endpoint filter in the video checks the key, writes the 401 body on failure, but then still calls await next(context). To actually short-circuit, it needs to return immediately after writing the unauthorized response instead of falling through to the next delegate. It is a one-word fix and a good reminder that with filters, not calling next is how you stop the pipeline.

Constant-time comparison

extractedApiKey != _options.Key is a normal string comparison, which can leak timing information to an attacker probing the key byte by byte. For a real deployment, compare with a fixed-time method (CryptographicOperations.FixedTimeEquals over the UTF-8 bytes) so every comparison takes the same time regardless of how many characters match.

When API keys are the wrong tool

You need to know which user is acting, not just which application. Use real user auth.
Keys are going to end up in browser code. A key in client-side JavaScript is public - anyone can read it.
You need granular, revocable, per-scope permissions. That is OAuth's job.

API keys shine for trusted server-to-server calls where the client can keep a secret.

Common pitfalls

Committing the key. Treat it like a password: secret store, not source control.
No revocation story. A single hardcoded key means a leak forces a redeploy. Real systems store hashed keys in a database so individual keys can be rotated and revoked.
Forgetting to short-circuit. Writing a 401 body but still invoking the rest of the pipeline runs the endpoint anyway.
Plain == comparison. Use a fixed-time comparison.
Mixing approaches. Pick one enforcement point for a given surface; stacking middleware and a filter doing the same check is just confusing.

Key Takeaways

API key auth is a good fit for server-to-server APIs where OAuth is overkill and you only need to identify the calling application.
Bind the header name and key to a typed ApiKeyOptions via the Options pattern; keep the real value in a secret store.
Middleware protects the whole app; an MVC IAuthorizationFilter (via [ServiceFilter]) protects chosen controllers; an IEndpointFilter protects chosen minimal API routes or groups.
To short-circuit a filter, write the response and return - do not call next.
Compare keys in constant time and design for rotation and revocation from the start.
Never ship an API key in client-side code.

Get the Full Source Code

The complete runnable solution - all three enforcement approaches, the options binding, and both controller and minimal API endpoints to test against - is available to Patreon supporters. If you want to try each approach with a real header instead of rebuilding it from the walkthrough above, you can find it on Patreon.

Originally published at remigiuszzalewski.com