AI has made life easier for us developers. Dozens of AI tools are getting more advanced every day, shortening and speeding up the development cycle. Converting an idea into a concrete MVP is faster than ever before. Intelligent models turn your ideas into a working project with just a few prompts. End users or product owners can see the application, use the beta version, and give feedback on the spot. Designers can visualize and shape the system themselves, while developers can use AI to build features or debug. Whether you are a mobile developer, front-end or back-end engineer, AI may be part of daily tasks, from development to debugging, from understanding a feature to optimizing it. These are the fruits of the 5th Industrial Revolution. However, those quick machine helps are not always reliable and need testing. In today's blog post, I will explore where and why AI-generated code can't be reliable.

AI coding is no longer just a tool but an ecosystem

Modern models offer a variety of ease in the application process.

• Design assistants like Claude Design and Figma Make help you draw interfaces quickly that earlier took hours of work.
• Prompt-to-application workflows turn natural-language descriptions into working apps. Google AI Studio, Lovable, RapidNative, Replit Agent, v0, Bolt, and Base44 are part of this long list.
• AI-enabled coding assistants such as GitHub Copilot, Cursor, JetBrains Junie, Gemini Code Assist, and Amazon Q Developer do much of the job while you write code.
• Independent agents are also part of development, and agents like OpenAI Codex, Devin, Claude Code, and Google Jules need no introduction.

I have listed a handful of names out of hundreds. All of these enable fast-paced development for both experienced and new developers. While AI tools are purpose-built platforms, their operations overlap significantly. A design tool may generate working application code, while a prompt-to-app platform may provision authentication, databases, and hosting.

Why do companies use AI in development?

One big advantage AI brings to organizations is the speed of work. In a traditional setup, teams defined an idea in requirements documents, then refined it in planning meetings. Planning leads to technical requirements, agile sprints, and development. Meanwhile, stakeholders had to wait for a tangible demo and feedback to fall back into the cycle. AI agents allow organizations to make a prototype application in the starting phase and present it to stakeholders. The team can demonstrate a feature, take feedback, and update accordingly on something real rather than just graphs and designs. This cuts down on the process, saving not only time but also the money that each software cycle spends repeating after feedback.

Another major reason corporates opt for AI is human resource efficiency. Modern AI models assist in coding, help with debugging, write boilerplate and repetitive code themselves, and even provide suggestions throughout the process. A developer, with the use of AI, can do the job of multiple developers, which results in a dramatic increase in developers' capability. For the same reason, many development teams are shrinking across organizations.

Why does AI-generated code need tests?

So, coming to our original question, why can't we fully rely on AI-generated code? Let's look at the issues AI may bring with generated code.

AI-Generated code looks more trustworthy than it is

AI-generated code is different from hand-written code. AI tools do not return generic snippets. They compose the snippets shaped by the user prompt, surrounding code, and other contextual formats. The output looks familiar and native to the project, which feels trustworthy. Developers may overlook edge cases and blind spots. If you pass code for debugging, the AI responds with the correct code but sometimes affects other parts of the application that depend on it, and you may not notice.

AI code needs stronger validation

GitClear's 2025 analysis of 150 million lines of code states that code churn has sharply increased in the post-AI era. Much unvalidated code made it to production, then was modified or reverted within 2 weeks, showing how unreliable AI-generated code can be. One HackerRank experiment found that a senior developer who combined a traditional approach with AI produced a better application than a junior developer and a pure vibe coder. Agents don't understand the system's requirements, user context, and business logic but rely on the prompt and surrounding code. AI may write hallucinated logic due to a lack of application and organizational knowledge. When a developer writes code, they understand what a function can and cannot do. They know the organization's requirements better through client interaction, research, and experience. These aspects may be missing from the model's training data. AI doesn't consider edge cases or specific business logic.

Generated code is not a production application

As we know, AI is remarkable at building prototypes and generating snippets faster. You get well-placed buttons, interactive dashboards filled with data, and inputs that take and save data via AI in minutes. That speed can create the impression of real progress and make an application seem nearly finished. But visibility isn't all an application needs. A production-grade application needs tons of bullet points fulfilled, such as:

• How does the authentication work?
• Can a user access information of another user?
• Is there a logging trail of actions for traceability and debugging?
• How does it perform when the user base grows?
• What happens when invalid data is submitted?
• How does a service recover from failure?
• Are its features extendable and loosely coupled?

Unfortunately, our quick solution often lacks several of them. AI gives results within the scope of the prompt asked or the context it can access. It lacks architectural constraints and design consistency across the entire application. AI doesn't know which authentication your application uses. It does not have an idea of how the business will control access to users, how you should validate input, or what clients or end-users said in the meeting. Many people ran into problems when their AI-generated app attracted a bigger user base, because the AI had no idea what future scalability would require. Only a human can plan for these aspects.

AI Can Accelerate Technical Debt

Code generated for a feature today can differ tomorrow for the same query. Now think of other parts that AI gave you, they can drastically differ from your application's standard practices and conventions. Variable names can follow different formats, and architecture can be separated from what other parts do in AI-assisted code. Database queries can be duplicated because AI doesn't know whether a similar query has already been written. Scattered configurations, inefficient API calls, lack of reusability, and unnecessary dependencies are common add-on issues in AI code. If you rely only on the working status, these underlying mismatches can become hurdles during maintenance or when you extend the feature. The same speed of work for which you choose AI can harm the product. You get more code generated than the team can understand. So the bottleneck shifts from writing code to maintenance. Revisiting and modifying can take longer while a production deadline is on your head. The same was found in the code quality analysis discussed above.

Security risks shipped with the code

AI-generated code may do its primary task of a responsive page, authenticating a user or sending emails with Twilio, but it may overlook the security bounds of standard development. Security and data risks such as broken access control, security misconfiguration, insecure design, exposed configuration and API keys are common problems that automated code leaves in the application.

AI agents today are more like coding partners that understand requirements, scan files, connect to databases, create cloud resources, open pull requests, or deploy applications. The more the access array grows, the more likely errors or incorrect instructions become.

Beyond issues with generated code, risks can come from the developer's side as well. During development, developers may share critical code, files, screenshots, database schema, or sensitive information like passwords and API keys.

How to benefit from AI-generated code without compromising your application?

We have seen the issues with the involvement of AI in the modern development cycle. Now, let's move to diagnosing how you can avoid those issues while leveraging AI.

Artificial intelligence is your colleague, not a de facto ruler

Treat AI agents and assistants as a co-developer. More safely, as a junior developer whom you will not give full responsibility to create A-to-Z of your application. You will not ask them to create a feature without prior knowledge of standards, architecture, naming conventions, existing components, approved third-party packages and licenses. Use AI models for coding based on organization-specific and application context, boundaries, acceptance criteria and review. An AI-embedded software process should define:

• How changes should be structured and reviewed, including branching, pull requests, code ownership and approval requirements.
• API and integration conventions, including naming, versioning, error responses, pagination and backward compatibility.
• Database and data-access conventions, including migration practices, transaction handling, query performance and indexing expectations.
• Dependency and package policies, including approved sources, versioning, vulnerability scanning and license requirements.
• Configuration and secrets management, including which values belong in configuration, environment variables or secret stores and which must never be committed.
• Performance and scalability expectations, including response-time targets, resource limits and acceptable database or API usage.
• Observability requirements, including structured logging, metrics, tracing, health checks and what information must not appear in logs.
• Deployment and rollback requirements, including how changes move between environments and how failed releases are reversed.
• Documentation requirements, including which architectural decisions, public APIs and non-obvious business rules must be documented.

A guided input to LLMs will avoid hallucinated logic and bound them within the standardized approach.

Understand the AI service before using it

First, the decision makers need to understand the account type, configuration and contractual terms through which a model is used. Some key considerations are:

• Whether submitted content may be used to train or improve the provider's models.
• How long prompts, source code, generated output and agent sessions are retained.
• Where data is processed and stored, and what data-processing agreements and safeguards apply.
• What security, privacy and data-isolation controls are provided by the selected account or plan.
• Which repositories, files and connected services the AI tool is permitted to access.
• Whether administrators can manage permissions, monitor usage and remove organizational data.
• What happens to the organization's information when the account or service is closed.

Standardized use of AI within the organization

The organization should restrict AI not only in development but also for those who will use it. The new kind of development brought new requirements. Developers should be given clear guidelines for using approved AI products for company tasks, covering at least

• Use only approved AI tools and account types for company work; personal accounts should not be used for organizational data.
• Understand what data can be shared. Source code, credentials, customer information, personal data and confidential business information should only be submitted when explicitly permitted.
• Use the appropriate data classification. Public and synthetic data may have fewer restrictions, while confidential or personal data may require additional controls or may be prohibited entirely.
• Keep secrets out of prompts and repositories. API keys, passwords, tokens, private certificates and other credentials should never be provided to an AI tool.
• Limit agent permissions. Give coding agents access only to the repositories, files, tools and environments required for their task.
• Review generated code before use. Developers remain responsible for checking correctness, security, dependencies, licensing and compliance with project standards.
• Do not blindly execute generated commands. Commands that modify databases, delete files, change infrastructure or access external systems should be reviewed before execution.
• Use isolated environments for experimentation. AI-generated changes should be tested in development or staging environments before reaching production.
• Follow existing development controls. AI-generated changes should go through the same testing, code review, CI/CD and approval processes as manually written code.
• Report suspected data exposure or unsafe output. Developers should know how to report accidental disclosure, insecure generated code, or inappropriate AI behavior.

Developer review - human involvement is necessary

After AI develops a feature, debugs a problem or generates code, you should not merge it into production. We've seen that code isn't fully trustworthy and needs validation. A developer understands what that code should do and what it should not do. You and your team know the organization's requirements better through client interaction, research, documentation and experience. A human review is essential to confirm that AI didn't invent a method that was already defined, write a separate database query you already have, follow security and file standards, and more. Another approach to validate generated code is to cross-validate logic from one model against another. We at elmah.io follow this to ensure the models did the job efficiently according to the guided protocols.

Test AI-generated code with AI-powered tests

It is like checking machine-provided code with your own machine police, so to speak. Traditional testing is not sufficient for the new era's development practices. Your existing test suite reflects the code paths you anticipated before the AI introduced anything new. When AI-generated changes add new branches, error conditions or logic paths, those scenarios may fall outside the existing test coverage. Tests can still pass and the coverage report can still look healthy, while important behavior remains untested. The gap may only become visible when something fails in production. AI-powered tests can catch those gaps and also find hallucinated logic. These tests directly exercise the business rule that serves a filter after human review and before production. Practically, it is not difficult to write that many handwritten tests matching the speed of AI-powered development. Intelligent analysis can catch context loopholes, business-logic misses, and security leaks at the door.

Conclusion

AI-assisted development changes the economics of software development. Teams can explore ideas faster, generate routine code in seconds and make changes across an application with less manual effort. But faster code generation does not remove the engineering work required to determine whether that code is correct, secure, maintainable and appropriate for production.

The important distinction is between generating code and assuring software. AI can produce an implementation, but it does not remove the need to understand the requirements, consider failure modes, test behavior, and review the consequences of a change. We explored different shortcomings in AI-generated code, such as alteration of dependent behavior, hallucinated logic, security leaks and missing organization-specific knowledge. We discussed a few practices to overcome those shortcomings. Developers should set guidelines for AI code and review it after it generates code. Organizations should not treat AI as a replacement for established engineering practices. Instead, AI should operate within them. Give developers approved tools, clear boundaries, appropriate access and well-defined review processes. Use automation to catch predictable problems and human judgment for decisions that require context. AI can make development faster. Engineering discipline determines whether that speed produces software you can trust. Existing tests are valuable, but they only protect the scenarios they cover. When AI introduces new branches, dependencies, or assumptions, the surrounding validation needs to evolve as well.

What happens when your ASP.NET Core API needs to deserialize a JSON payload containing one million objects? The JSON serializer has a lot of work to do, such as building the resulting object graph and managing memory allocation. That can put noticeable pressure on memory and the garbage collector (GC). .NET 10 introduces PipeReader support in System.Text.Json, providing a pipeline-based way to feed JSON data directly into the serializer. It provides an alternative to the traditional stream-based processing.

In this article, I will show the differences between the two approaches and test them against execution time, memory allocation, and GC load.

What is zero-copy?

Zero-copy refers to the technique of processing data across memory spaces without making redundant copies in memory. By avoiding duplicate copies, the program drastically reduces CPU overhead, conserves RAM, and eliminates Garbage Collector (GC) pressure, achieving a remarkable boost in performance.

Analyzing .NET 10 web API JSON improvements

As always, I will keep things simple. I am using a minimal API with a JSON dataset, let's begin.

Step 1: Create project

dotnet new webapi -n ZeroCopyJsonDemo -f net10.0
cd ZeroCopyJsonDemo

Step 2: Create models

Reading model

namespace ZeroCopyJsonDemo.Models;

public class TelemetryReading
{
    public DateTime Timestamp { get; set; }

    public double Temperature { get; set; }

    public double Humidity { get; set; }
}

Model for request

public class TelemetryRequest
{
    public string DeviceId { get; set; } = string.Empty;

    public List<TelemetryReading> Readings { get; set; } = [];
}

Step 3: Create a large JSON file

To simulate a large JSON dataset, I am adding an endpoint that does it

app.MapGet("/create-json", () =>
{
    var payload = new TelemetryRequest
    {
        DeviceId = "device-001",
        Readings = Enumerable.Range(1, 1_000_000)
            .Select(i => new TelemetryReading
            {
                Timestamp = DateTime.UtcNow.AddSeconds(i),
                Temperature = 20 + i % 10,
                Humidity = 40 + i % 20
            })
            .ToList()
    };

    var json = JsonSerializer.SerializeToUtf8Bytes(payload);

    File.WriteAllBytes("large.json", json);

    return Results.Ok(new
    {
        SizeMB = Math.Round(json.Length / 1024d / 1024d, 2)
    });
});

It generates 1 million readings and writes them to a JSON file.

Step 4: Write testing methods

static async Task<object> MeasureNormal()
{
    GC.Collect();
    GC.WaitForPendingFinalizers();
    GC.Collect();

    var allocatedBefore = GC.GetTotalAllocatedBytes(true);

    var gen0Before = GC.CollectionCount(0);
    var gen1Before = GC.CollectionCount(1);
    var gen2Before = GC.CollectionCount(2);

    var stopwatch = Stopwatch.StartNew();

    await using var stream = File.OpenRead("large.json");

    var result =
        await JsonSerializer.DeserializeAsync<TelemetryRequest>(stream);

    stopwatch.Stop();

    var allocatedAfter = GC.GetTotalAllocatedBytes(true);

    return new
    {
        ExecutionTimeMs = stopwatch.Elapsed.TotalMilliseconds,

        AllocatedMemoryMB = Math.Round(
            (allocatedAfter - allocatedBefore) / 1024d / 1024d, 2),

        Gen0Collections = GC.CollectionCount(0) - gen0Before,
        Gen1Collections = GC.CollectionCount(1) - gen1Before,
        Gen2Collections = GC.CollectionCount(2) - gen2Before
    };
}

For a fair benchmark, I enforced garbage collection. It will test a normal traditional approach. Then, recorded memory allocation and time with a stopwatch. The line:

await using var stream = File.OpenRead("large.json");

opens the JSON file as a normal .NET Stream. While, the next line deserializes it using System.Text.Json into TelemetryRequest returning as a result.

Finally, I got the total memory allocation, time elapsed and Garbage collector usage by the differences. The

/ 1024d / 1024d

converts bytes to MB.

static async Task<object> MeasurePipeline()
{
    GC.Collect();
    GC.WaitForPendingFinalizers();
    GC.Collect();

    var allocatedBefore = GC.GetTotalAllocatedBytes(true);

    var gen0Before = GC.CollectionCount(0);
    var gen1Before = GC.CollectionCount(1);
    var gen2Before = GC.CollectionCount(2);

    var stopwatch = Stopwatch.StartNew();

    await using var stream = File.OpenRead("large.json");

    var reader = PipeReader.Create(stream);

    var result =
        await JsonSerializer.DeserializeAsync<TelemetryRequest>(reader);

    await reader.CompleteAsync();

    stopwatch.Stop();

    var allocatedAfter = GC.GetTotalAllocatedBytes(true);

    return new
    {
        ExecutionTimeMs = stopwatch.Elapsed.TotalMilliseconds,

        AllocatedMemoryMB = Math.Round(
            (allocatedAfter - allocatedBefore) / 1024d / 1024d, 2),

        Gen0Collections = GC.CollectionCount(0) - gen0Before,
        Gen1Collections = GC.CollectionCount(1) - gen1Before,
        Gen2Collections = GC.CollectionCount(2) - gen2Before
    };
}

Again, enforcing garbage collection so both tests start from the same state. Now instead of giving the Stream directly to JsonSerializer, we give it the PipeReader. Then System.Text.Json's serializer deserializes directly from the PipeReader. One important part is to complete the pipe reader after we are done with.

await reader.CompleteAsync();

Step 5: Create benchmark endpoint

app.MapGet("/benchmark", async () =>
{
    var normal = await MeasureNormal();
    var pipeline = await MeasurePipeline();

    return Results.Ok(new
    {
        Normal = normal,
        Pipeline = pipeline
    });
});

That is a simple, minimal endpoint to run both measures.

Step 6: Run the project

dotnet run -c Release

For benchmarking, I ran it in Release mode.

Step 7: Prepare the JSON file with the endpoint

The endpoint generated alarge.json file of size 72MB which is not ideal to represent a real large file but is considerable for the demo.

Step 8: Navigate to the benchmarking endpoint

Run /benchmark 5–10 times, ignore the first run because of JIT warm-up, and compare the later results. A single execution is not a reliable performance benchmark.

We're creating a pipeline reader around the file stream. .NET 10 allows System.Text.Json to deserialize JSON directly from a PipeReader. So instead of us doing something like:

var bytes = await ReadEntireRequestBody();

and then passing those bytes to the JSON serializer, we're allowing the serializer to consume the pipeline. So functionally, both endpoints do the same thing. We're not changing the API's behavior. We're changing how the request body is consumed. We utilized the .NET 10 power ofPipeReader that allows System.Text.Json to consume JSON from a pipeline, which can help avoid unnecessary buffering and copying in suitable workloads.

One improvement is in garbage collector usage. During deserialization, .NET has to create a very large object graph that requires allocations. To clean temporary allocations and other working data, GC has to jump in. While the buffering/consumption model of PipeReader can process the input incrementally without creating enough additional GC-triggering pressure during this run. The lower GC pressure resulted in 21% faster results.

Conclusion

We discovered one major .NET 10 improvement in JSON processing. The pipe reader with System.Text.Json changes the game for large dataset parsing. With the example API project, we observed changes in execution time and GC pressure, showing that .NET 10 optimized the job with its zero-copy capabilities. If you're deserializing large JSON payloads or using a high-throughput endpoint, prefer the PipeReader overload. You trade a small amount of extra raw allocation to avoid LOH churn and GC pauses, which is almost always the better trade in a hot request path than its traditional counterpart.

Code: https://github.com/elmahio-blog/ZeroCopyJsonDemo.git

As a .NET developer, I use a growing list of MCP servers every day to give Claude and other AI coding assistants access to real, live data instead of guesses. Some ship from Microsoft, some from the vendor of the tool itself, and a few are community projects that quietly make everything better. In this post, I'll go through 10 that I'd install right now.

Without further ado, let's dig into the list. In no particular order.

NuGet MCP

Let Claude check for the latest version of a package, review known vulnerabilities and supply chain risks before adding a dependency, and even upgrade or fix vulnerable packages directly in your project files. I don't have to guess at a version number or trust stale training data anymore - the assistant can just go look it up.

Example:

> What's the latest version of Serilog.Sinks.Elasticsearch, any known vulnerabilities?

Learn more: https://learn.microsoft.com/en-us/nuget/concepts/nuget-mcp-server

elmah.io MCP

Query your elmah.io error logs, uptime checks, heartbeats, and deployments directly from Claude. Since we build our own error logging and uptime monitoring service, this one's obviously close to home (I even wrote a full post about using it to fix a real production bug). It lets Claude query recent log messages, find the noisiest errors in a log, check uptime and heartbeat status, and pull usage stats - all without me switching over to app.elmah.io. Genuinely one of the tools I reach for the most these days.

Example:

> Get me the details of the latest error in the elmah.io.api log.

Learn more: https://mcp.elmah.io/

GitHub MCP

Gives Claude access to GitHub repositories, issues, pull requests, and workflow runs through the GitHub API. Claude and similar tools can already call this API over plain HTTP requests, but installing the MCP server makes a real difference: it also unlocks private repositories, and returns structured data instead of scraped HTML.

Example:

> List the open pull requests on elmahio/Elmah.Io.AspNetCore that don't have a review yet.

Learn more: https://github.com/github/github-mcp-server

Azure MCP

Pull information from your Azure environment to get information about production deployments and configuration. Make sure to install it with the --read-only flag if you, like me, don't want an AI assistant able to change your cloud infrastructure. If you already have the az CLI installed and authenticated on your machine, Claude will figure out on its own that it can just shell out to az to make changes anyway - read-only mode on the MCP server doesn't stop that 😅. Block usage of the az command too if you actually want that guarantee.

Example:

> What App Service plan is elmah.io.app running on, and what's it costing us this month?

Learn more: https://github.com/Azure/azure-mcp

Azure DevOps MCP

Gives Claude access to Azure DevOps work items, repos, pipelines, and more, directly from your editor or terminal. Microsoft's HTTP-based remote server currently only works from Visual Studio and VS Code, see https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server?view=azure-devops. For anything else - Claude Code included - use the CLI-based version instead until that changes.

Example:

> What tasks are assigned to me in the current sprint?

Learn more: https://github.com/microsoft/azure-devops-mcp

Playwright MCP

Gives Claude control of a real browser - navigating pages, clicking, filling in forms, and reading back what's on screen. It's genuinely a little crazy that Claude can write its own test plan for a change, launch a real browser, click through your app, and verify the result - all on its own. This is the one that turns "I think this works" into "I watched it work."

Example:

> Open the dashboard, log in, and confirm the uptime chart renders without console errors.

Learn more: https://github.com/microsoft/playwright-mcp

Microsoft Learn MCP

For looking up official documentation. It's already built into Visual Studio (and possibly VS Code), but I had to install it manually for other tools like Claude Code.

Example:

> What's the recommended way to configure rate limiting in ASP.NET Core 10?

Learn more: https://learn.microsoft.com/en-us/training/support/mcp

Worth also checking out Context7 for the same kind of up-to-date library documentation lookup, across a much wider set of frameworks and libraries than just Microsoft's own.

Learn more: https://github.com/upstash/context7

Postman MCP

Gives Claude direct access to your Postman collections and API specs - creating and managing collections, running existing tests, editing environment variables, and generating client code straight from an API definition. I haven't put this one through its paces myself yet, but it ships with a few tiers of tools (Minimal, Code, Full, Learn) so you can pick how much access to hand over.

Example:

> Run the 'Create log message' request from my elmah.io collection against the staging environment.

Learn more: https://www.postman.com/product/mcp-server/

dotnetmetadatamcpserver

A community project that uses reflection to expose the actual type metadata of your .NET project and its NuGet dependencies - assemblies, namespaces, types, methods, properties, constructors, all of it - plus NuGet package search and version/dependency lookups. It solves a real problem: instead of hallucinating a method signature from a package it's never seen, Claude can just ask.

Example:

> What overloads does AddHttpClient have in this project's referenced Microsoft.Extensions.Http?

Learn more: https://github.com/v0v1kkk/dotnetmetadatamcpserver

Cloudflare MCP

Gives Claude access to the full Cloudflare API (WAF, DNS, Workers, and more). No built-in read-only mode, though. Everything is gated by whatever credential you connect with. For read-only, skip the OAuth login and create a Cloudflare API token scoped to only Read permission groups (no Edit). Watch out for this open bug: https://github.com/cloudflare/mcp/issues/95 - Claude Code (and other MCP clients) do OAuth discovery before sending custom headers, so a bearer token never actually reaches the server, and it silently falls back to a full-access OAuth login instead. Took me a minute to figure out why my read-only token kept getting ignored 🤦🏻‍♂️

A safer alternative until that's fixed could be to skip the MCP server for read-only use cases and call the Cloudflare API directly with the scoped token. The read-only restriction is then enforced by Cloudflare on the token itself, not by trusting the MCP client - which is what I ended up doing.

Example:

> List the DNS records for the elmah.io zone.

Learn more: https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/

That's the list for now. If you're running a favorite MCP server as a .NET developer that didn't make the cut, let me know. I'm always looking for the next one to add to the rotation.

For years, APIs have had one primary audience: applications. A frontend calls an endpoint, receives a response, and the developer handles whatever happens next. All of it was from a human user. Now, we have a new player: AI. Instead of simply following predefined application logic, an agent can decide which endpoints to call, determine the order of operations, retry failed requests, and carry out multi-step tasks based on a user's goal. Your API is no longer just serving an application, it may be serving an AI system capable of taking action. Companies like Stripe, Twilio, and Shopify have already launched dedicated Model Context Protocol servers to capture agent-driven traffic.

In this article, I will share practical patterns that can make an ASP.NET Core API easier for AI agents to discover, understand, and use safely. This isn't a complete guide, but a checklist you can follow to make APIs AI-compatible.

Design an ASP .NET Core API for AI agents

Let's incorporate the necessary points into an API.

Step 1: Create project

dotnet new webapi -n AgentReadyApi
cd AgentReadyApi

Step 2: Install the required packages

dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL        
dotnet add package Microsoft.EntityFrameworkCore                
dotnet add package Scalar.AspNetCore

A notable NuGet package is Scalar.AspNetCore apart from those that provide EF Core and the database. I will use Scalar UI with the OpenAPI document to display and test endpoints.

Step 3: Create models and enum

For our database tables, add an Invoice table.

public class Invoice
{
    public Guid Id { get; set; }

    public string CustomerId { get; set; } = null!;

    public decimal Amount { get; set; }

    public string Currency { get; set; } = "USD";

    public InvoiceStatus Status { get; set; }

    public string ClientReference { get; set; } = null!;

    public DateTime CreatedAt { get; set; }

    public DateTime? UpdatedAt { get; set; }
}

Make sure to create the Status enum.

public enum InvoiceStatus
{
    Draft = 1,
    Finalized = 2,
    Paid = 3,
    Cancelled = 4
}

Status is necessary to restrict input to fixed values rather than an open-ended string.

Step 4: Set up DbContext

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options)
        : base(options)
    {
    }
    
    public DbSet<IdempotencyRecord> IdempotencyRecords => Set<IdempotencyRecord>();
    public DbSet<Invoice> Invoices => Set<Invoice>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Invoice>(entity =>
        {
            entity.HasKey(x => x.Id);

            entity.Property(x => x.CustomerId)
                .IsRequired()
                .HasMaxLength(100);

            entity.Property(x => x.Currency)
                .IsRequired()
                .HasMaxLength(3);

            entity.Property(x => x.Amount)
                .HasPrecision(18, 2);

            entity.Property(x => x.Status)
                .HasConversion<string>();

            entity.Property(x => x.CreatedAt)
                .IsRequired();
        });
    }
}

Well, I have used the fluent API to configure the necessary model. Alternatively, you can use attributes as well.

Create strong Data Transfer Objects (DTOs)

Don't let an AI agent discover your database model. Introduce DTOs for the input.

public class CreateInvoiceRequest
{
    /// <summary>
    /// Customer that owns the invoice.
    /// </summary>
    [Required]
    public string CustomerId { get; init; } = null!;

    /// <summary>
    /// Invoice amount. Must be greater than zero.
    /// </summary>
    [Range(0.01, 999999999)]
    public decimal Amount { get; init; }

    /// <summary>
    /// Three-letter ISO currency code.
    /// </summary>
    [Required]
    [StringLength(3, MinimumLength = 3)]
    public string Currency { get; init; } = "USD";

    /// <summary>
    /// Unique client-side reference used for reconciliation.
    /// </summary>
    [Required]
    public string ClientReference { get; init; } = null!;
}

Also, for operations like update and cancel, we need separate DTOs.

public class CancelInvoiceRequest
{
    /// <summary>
    /// The unique identifier of the cancellation intent previously created for the invoice.
    /// </summary>
    public Guid IntentId { get; init; }

    /// <summary>
    /// The unique identifier of the invoice to cancel.
    /// </summary>
    public Guid InvoiceId { get; init; }

    /// <summary>
    /// The date and time when the cancellation intent expires.
    /// </summary>
    public DateTime ExpiresAt { get; init; }
}

Enrich OpenAPI documentation

Give a summary of each property so the machine user can connect the dots predictively. Use attributes like [Required] and [StringLength] to enrich the document with data validation so AI knows the data limits. Sometimes you need to define an attribute for your business logic.

Write machine-readable error responses

Standard HTTP status codes are insufficient for AI agents. We need proper responses for both successful and error cases.

Invoice response class.

public class InvoiceResponse
{
    public Guid Id {get; set; }
    public string CustomerId {get; set; }
    public decimal Amount {get; set; }

    public string Currency {get; set; }
    public string Status {get; set; }

    public DateTime CreatedAt {get; set; }
    public string ClientReference { get; set; } = null!;
}

Paginated response.

public record PaginatedResponse<T>(
    IReadOnlyList<T> Items,
    string? NextCursor
);

For consistency and reusability, I added a generic response class.

Step 5: Create Services

public interface IInvoiceService
{
    Task<PaginatedResponse<InvoiceResponse>> GetInvoicesAsync(
        string? status,
        int limit,
        string? cursor,
        CancellationToken cancellationToken);

    Task<InvoiceResponse> CreateAsync(
        CreateInvoiceRequest request,
        string idempotencyKey,
        CancellationToken cancellationToken);

    Task<InvoiceResponse> GetByIdAsync(
        Guid id,
        CancellationToken cancellationToken);

    Task<InvoiceResponse> FinalizeAsync(
        Guid id,
        CancellationToken cancellationToken);

    Task<CancelInvoiceRequest> CreateCancellationIntentAsync(
        Guid id,
        CancellationToken cancellationToken);

    Task<InvoiceResponse> CancelAsync(
        CancelInvoiceRequest input,
        CancellationToken cancellationToken);
}

The implementation.

public sealed class InvoiceService : IInvoiceService
{
    private readonly AppDbContext _db;

    public InvoiceService(AppDbContext db)
    {
        _db = db;
    }
    
    public async Task<PaginatedResponse<InvoiceResponse>> GetInvoicesAsync(
        string? status,
        int limit,
        string? cursor,
        CancellationToken cancellationToken)
    {
        if (limit <= 0)
        {
            throw new ApiException(
                StatusCodes.Status400BadRequest,
                "INVALID_LIMIT",
                "Limit must be greater than zero.");
        }
    
        if (limit > 100)
        {
            throw new ApiException(
                StatusCodes.Status400BadRequest,
                "LIMIT_TOO_LARGE",
                "Limit cannot be greater than 100.");
        }
    
        var query = _db.Invoices
            .AsNoTracking()
            .AsQueryable();
    
        // Optional status filter
        if (!string.IsNullOrWhiteSpace(status))
        {
            if (!Enum.TryParse<InvoiceStatus>(
                    status,
                    ignoreCase: true,
                    out var invoiceStatus))
            {
                throw new ApiException(
                    StatusCodes.Status400BadRequest,
                    "INVALID_STATUS",
                    $"Invalid invoice status '{status}'.");
            }
    
            query = query.Where(x => x.Status == invoiceStatus);
        }
    
        // Cursor pagination
        if (!string.IsNullOrWhiteSpace(cursor))
        {
            if (!Guid.TryParse(cursor, out var cursorId))
            {
                throw new ApiException(
                    StatusCodes.Status400BadRequest,
                    "INVALID_CURSOR",
                    "The supplied cursor is invalid.");
            }
    
            query = query.Where(x => x.Id > cursorId);
        }
    
        var invoices = await query
            .OrderBy(x => x.Id)
            .Take(limit + 1)
            .ToListAsync(cancellationToken);
    
        var hasMore = invoices.Count > limit;
    
        if (hasMore)
        {
            invoices = invoices.Take(limit).ToList();
        }
    
        var items = invoices
            .Select(MapToResponse)
            .ToList();
    
        string? nextCursor = null;
    
        if (hasMore && invoices.Count > 0)
        {
            nextCursor = invoices[^1].Id.ToString();
        }
    
        return new PaginatedResponse<InvoiceResponse>(
            items,
            nextCursor);
    }
    
    public async Task<InvoiceResponse> CreateAsync(
        CreateInvoiceRequest request,
        string idempotencyKey,
        CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(idempotencyKey))
        {
            throw new ApiException(
                StatusCodes.Status400BadRequest,
                "IDEMPOTENCY_KEY_REQUIRED",
                "Idempotency-Key header is required.");
        }

        var existing = await _db.Invoices
            .AsNoTracking()
            .FirstOrDefaultAsync(
                x => x.ClientReference == request.ClientReference,
                cancellationToken);

        if (existing is not null)
        {
            return MapToResponse(existing);
        }

        var invoice = new Invoice
        {
            Id = Guid.NewGuid(),
            CustomerId = request.CustomerId,
            Amount = request.Amount,
            Currency = request.Currency.ToUpperInvariant(),
            ClientReference = request.ClientReference,
            Status = InvoiceStatus.Draft,
            CreatedAt = DateTime.UtcNow
        };

        _db.Invoices.Add(invoice);

        await _db.SaveChangesAsync(cancellationToken);

        return MapToResponse(invoice);
    }

    public async Task<InvoiceResponse> GetByIdAsync(
        Guid id,
        CancellationToken cancellationToken)
    {
        var invoice = await _db.Invoices
            .AsNoTracking()
            .FirstOrDefaultAsync(
                x => x.Id == id,
                cancellationToken);

        if (invoice is null)
        {
            throw new ApiException(
                StatusCodes.Status404NotFound,
                "INVOICE_NOT_FOUND",
                "The requested invoice was not found.");
        }

        return MapToResponse(invoice);
    }

    public async Task<InvoiceResponse> FinalizeAsync(
        Guid id,
        CancellationToken cancellationToken)
    {
        var invoice = await _db.Invoices
            .FirstOrDefaultAsync(
                x => x.Id == id,
                cancellationToken);

        if (invoice is null)
        {
            throw new ApiException(
                StatusCodes.Status404NotFound,
                "INVOICE_NOT_FOUND",
                "The requested invoice was not found.");
        }

        if (invoice.Status != InvoiceStatus.Draft)
        {
            throw new ApiException(
                StatusCodes.Status409Conflict,
                "INVALID_INVOICE_STATE",
                "Only draft invoices can be finalized.");
        }

        invoice.Status = InvoiceStatus.Finalized;
        invoice.UpdatedAt = DateTime.UtcNow;

        await _db.SaveChangesAsync(cancellationToken);

        return MapToResponse(invoice);
    }

    public async Task<CancelInvoiceRequest>
        CreateCancellationIntentAsync(
            Guid id,
            CancellationToken cancellationToken)
    {
        var invoice = await _db.Invoices
            .AsNoTracking()
            .FirstOrDefaultAsync(
                x => x.Id == id,
                cancellationToken);

        if (invoice is null)
        {
            throw new ApiException(
                StatusCodes.Status404NotFound,
                "INVOICE_NOT_FOUND",
                "The requested invoice was not found.");
        }

        if (invoice.Status == InvoiceStatus.Paid)
        {
            throw new ApiException(
                StatusCodes.Status409Conflict,
                "INVOICE_ALREADY_PAID",
                "A paid invoice cannot be cancelled.");
        }

        if (invoice.Status == InvoiceStatus.Cancelled)
        {
            throw new ApiException(
                StatusCodes.Status409Conflict,
                "INVOICE_ALREADY_CANCELLED",
                "The invoice is already cancelled.");
        }

        return new CancelInvoiceRequest
        {
            IntentId = Guid.NewGuid(),
            InvoiceId = invoice.Id,
            ExpiresAt = DateTime.UtcNow.AddMinutes(5)
        };
    }

    public async Task<InvoiceResponse> CancelAsync(
        CancelInvoiceRequest input,
        CancellationToken cancellationToken)
    {
        if (input.IntentId == Guid.Empty)
        {
            throw new ApiException(
                StatusCodes.Status400BadRequest,
                "INVALID_INTENT",
                "A valid cancellation intent is required.");
        }

        var invoice = await _db.Invoices
            .FirstOrDefaultAsync(
                x => x.Id == input.InvoiceId,
                cancellationToken);

        if (invoice is null)
        {
            throw new ApiException(
                StatusCodes.Status404NotFound,
                "INVOICE_NOT_FOUND",
                "The requested invoice was not found.");
        }

        if (invoice.Status == InvoiceStatus.Paid)
        {
            throw new ApiException(
                StatusCodes.Status409Conflict,
                "INVOICE_ALREADY_PAID",
                "A paid invoice cannot be cancelled.");
        }

        if (invoice.Status == InvoiceStatus.Cancelled)
        {
            throw new ApiException(
                StatusCodes.Status409Conflict,
                "INVOICE_ALREADY_CANCELLED",
                "The invoice is already cancelled.");
        }

        invoice.Status = InvoiceStatus.Cancelled;
        invoice.UpdatedAt = DateTime.UtcNow;

        await _db.SaveChangesAsync(cancellationToken);

        return MapToResponse(invoice);
    }

    private static InvoiceResponse MapToResponse(
        Invoice invoice)
    {
        return new InvoiceResponse
        {
            Id = invoice.Id,
            CustomerId = invoice.CustomerId,
            Amount = invoice.Amount,
            Currency = invoice.Currency,
            Status = invoice.Status.ToString().ToLowerInvariant(),
            ClientReference = invoice.ClientReference,
            CreatedAt = invoice.CreatedAt
        };
    }
}

Add pagination and limits

Prevent agents from fetching thousands of records and burning the context by limiting record access. In the implementation above, I allowed 1 to 100 records to be fetched at a time, which is practical for a single fetch. Notice this part.

if (limit <= 0)
{
    throw new ApiException(
        StatusCodes.Status400BadRequest,
        "INVALID_LIMIT",
        "Limit must be greater than zero.");
}

if (limit > 100)
{
    throw new ApiException(
        StatusCodes.Status400BadRequest,
        "LIMIT_TOO_LARGE",
        "Limit cannot be greater than 100.");
}

Here I throw exceptions with meaningful, contextual error messages when the input is out of limits. Next, while fetching, I get the paginated data.

.OrderBy(x => x.Id)
.Take(limit + 1)

The cursor represents the position in the dataset, rather than a page number in traditional pagination. It is an opaque continuation token that tells the API where to resume retrieving a collection. Instead of asking an agent to calculate page numbers, the API returns a cursor with each response, and the agent sends that cursor back to retrieve the next batch. For operations that require bulk data, add a dedicated endpoint, but that rarely happens, and we usually don't transmit hundreds of rows over the network.

Designing for Probabilistic Agent Behaviour

Because LLMs are probabilistic, agents can behave unpredictably, particularly in complex or long-running workflows. Clear empty-response semantics help agents distinguish between “no data exists” and “an error occurred.” Including links to related actions can further guide agents by exposing the possible next steps.

Define a custom exception

public class ApiException : Exception
{
    public int StatusCode { get; }
    public string ErrorCode { get; }

    public ApiException(
        int statusCode,
        string errorCode,
        string message)
        : base(message)
    {
        StatusCode = statusCode;
        ErrorCode = errorCode;
    }
}

Create the exception handler.

using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;

namespace AgentReadyApi.Exceptions;
public sealed class GlobalExceptionHandler : IExceptionHandler
{
    private readonly IProblemDetailsService _problemDetailsService;

    public GlobalExceptionHandler(
        IProblemDetailsService problemDetailsService)
    {
        _problemDetailsService = problemDetailsService;
    }
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        var statusCode = exception is ApiException apiException
            ? apiException.StatusCode
            : StatusCodes.Status500InternalServerError;

        var errorCode = exception is ApiException apiEx
            ? apiEx.ErrorCode
            : "INTERNAL_SERVER_ERROR";

        httpContext.Response.StatusCode = statusCode;

        var problem = new ProblemDetails
        {
            Status = statusCode,

            Title = exception is ApiException
                ? exception.Message
                : "An unexpected error occurred.",

            Detail = exception is ApiException
                ? exception.Message
                : "An unexpected error occurred.",

            Type = $"https://api.invoice.com/problems/{errorCode}"
        };

        problem.Extensions["errorCode"] = errorCode;

        await _problemDetailsService.WriteAsync(
            new ProblemDetailsContext
            {
                HttpContext = httpContext,
                ProblemDetails = problem
            });

        return true;
    }
}

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

Add the middleware.

app.UseExceptionHandler();

Now ASP.NET Core can produce RFC 7807-style responses.

{
  "type": "https://api.example.com/problems/invalid-invoice-state",
  "title": "Invalid invoice state",
  "status": 409,
  "detail": "A paid invoice cannot be cancelled.",
  "errorCode": "INVALID_INVOICE_STATE"
}

Which is much better than sending "something went wrong".

Add correlation IDs

Agents can make multiple requests and retries. You need to know which requests belong together.

public class CorrelationIdMiddleware
{
    private const string HeaderName = "X-Correlation-ID";

    private readonly RequestDelegate _next;

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

    public async Task InvokeAsync(HttpContext context)
    {
        var correlationId =
            context.Request.Headers[HeaderName].FirstOrDefault()
            ?? Guid.NewGuid().ToString();

        context.Response.Headers[HeaderName] = correlationId;

        context.Items[HeaderName] = correlationId;

        await _next(context);
    }
}

Inject the middleware.

app.UseMiddleware<CorrelationIdMiddleware>();

Add Idempotency

This is one of the most important parts for agents.

Suppose the agent sends:

POST /api/invoices

Idempotency-Key: abc-123

The network times out.

The agent doesn't know whether the invoice was created.

So it retries:

POST /api/invoices

Idempotency-Key: abc-123

Without idempotency:

Invoice #1 created
Invoice #2 created

which is bad.

With idempotency:

Request 1 → Invoice #1 created
Request 2 → Existing Invoice #1 returned

Use idempotency keys for operations that create irreversible side effects.

Create the IdempotencyRecord for the database table.

public class IdempotencyRecord
{
    [Key]
    public Guid Id { get; set; }

    public string Key { get; set; } = null!;

    public string RequestHash { get; set; } = null!;

    public int StatusCode { get; set; }

    public string ResponseBody { get; set; } = null!;

    public DateTime CreatedAt { get; set; }
}

Add it in the DbContext

public DbSet<IdempotencyRecord> IdempotencyRecords => Set<IdempotencyRecord>();

Add a unique index:

modelBuilder.Entity<IdempotencyRecord>()
    .HasIndex(x => x.Key)
    .IsUnique();

Create Controller

using AgentReadyApi.Data.Services;
using AgentReadyApi.Models.Dtos;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.RateLimiting;

namespace AgentReadyApi.Controllers;
[ApiController]
[Route("api/invoice")]
public class InvoiceController : ControllerBase
{
    private readonly IInvoiceService _service;

    public InvoiceController(IInvoiceService service)
    {
        _service = service;
    }

    /// <summary>
    /// Lists invoices for the authenticated merchant.
    /// </summary>
    [HttpGet]
    public async Task<IActionResult> GetInvoicesAsync(
        [FromQuery] string? status,
        [FromQuery] int limit = 20,
        [FromQuery] string? cursor = null,
        CancellationToken cancellationToken = default)
    {
        var result = await _service.GetInvoicesAsync(
            status,
            limit,
            cursor,
            cancellationToken);

        return Ok(result);
    }

    /// <summary>
    /// Creates a draft invoice.
    /// </summary>
    [HttpPost]
    public async Task<IActionResult> CreateInvoiceAsync(
        [FromHeader(Name = "Idempotency-Key")]
        string idempotencyKey,
        CreateInvoiceRequest request,
        CancellationToken cancellationToken)
    {
        var result = await _service.CreateAsync(
            request,
            idempotencyKey,
            cancellationToken);

        return CreatedAtAction(
            nameof(GetInvoice),
            new { id = result.Id },
            new
            {
                result.Id,
                result.Status
            });
    }

    /// <summary>
    /// Gets an invoice by ID.
    /// </summary>
    [HttpGet("{id:guid}")]
    public async Task<IActionResult> GetInvoice(
        Guid id,
        CancellationToken cancellationToken)
    {
        var invoice = await _service.GetByIdAsync(
            id,
            cancellationToken);

        return Ok(invoice);
    }

    /// <summary>
    /// Finalizes a draft invoice.
    /// </summary>
    [HttpPost("{id:guid}/finalize")]
    public async Task<IActionResult> FinalizeAsync(
        Guid id,
        CancellationToken cancellationToken)
    {
        var result = await _service.FinalizeAsync(
            id,
            cancellationToken);

        return Ok(result);
    }

    /// <summary>
    /// Creates a cancellation intent.
    /// </summary>
    [HttpPost("{id:guid}/cancellation-intent")]
    public async Task<IActionResult> CreateCancellationIntentAsync(
        Guid id,
        CancellationToken cancellationToken)
    {
        var intent = await _service.CreateCancellationIntentAsync(
            id,
            cancellationToken);

        return Ok(intent);
    }

    /// <summary>
    /// Cancels an invoice using a previously created intent.
    /// </summary>
    [HttpPost("cancel")]
    public async Task<IActionResult> CancelAsync(
        [FromBody] CancelInvoiceRequest request,
        CancellationToken cancellationToken)
    {
        var result = await _service.CancelAsync(
            request,
            cancellationToken);

        return Ok(result);
    }
}

With the create endpoint, we have [FromHeader(Name = "Idempotency-Key")] string idempotency key to implement idempotency. Cancellation intent is the alternative to delete because an AI agent could accidentally delete something.

Define each endpoint with a clear name and precise intent, rather than vague verbs.

Name everything consistently

Maintain a consistent naming convention across the application. Inconsistent names can confuse the agent. If you use userId at one place, then don't do user_id or userID elsewhere, but stick to one rule.

Add async processing

Make all operations that may wait asynchronous. Don't let agents wait 30 seconds by stopping the thread, although this is generally recommended for a human audience too.

LLM-Optimized Metadata

Another popular piece of information for AI agents is LLM-optimized metadata in the llms.txt file. The text file resides in the project's root directory and works as an index or guide for OpenAPI. Hundreds of organizations including Anthropic, Perplexity and Cursor, have adopted llms.txt.

Create a llms.txt file in the wwwroot directory. Put the metadata inside the file.

# My API

> REST API for managing customers, invoices, payments and orders.

## API Documentation

- OpenAPI specification: /openapi/v1.json
- Interactive documentation: /swagger

## Main API Areas

- Customers: /api/customers
- Invoices: /api/invoices
- Payments: /api/payments
- Orders: /api/orders

## Authentication

OAuth 2.0 / OpenID Connect.

## Agent Guidance

- Use the OpenAPI specification for the complete list of operations.
- Respect required permissions and scopes.
- Use Idempotency-Key for state-changing operations where required.
- Errors are returned using RFC 7807 Problem Details.

Although we only created the invoice controller here, a real project usually has many more namespaces and controllers, like customers, payments, etc.

Allow static files in Progam.cs

app.UseStaticFiles();

llms.txt is a discovery document for the agents, while OpenAPI is a machine-readable contract of your API. I can access the text file.

Run and test APIs

Create endpoint.

Call it.

Where I used an idempotency key

Check GET methods for getting records

So we can access our new record

Similarly, we have other endpoints.

Add authentication for Non-Human Consumers

Authentication is already recommended for any project, however, in an AI-ready app, it becomes a necessity. You have to secure your API because AI should be authenticated to access the app's internal data.

Standard OAuth 2.0 and OpenID Connect flows work here, as agents work best with established standards.

builder.Services
    .AddAuthentication("Bearer")
    .AddJwtBearer("Bearer", options =>
    {
        options.Authority =
            "https://auth.example.com";

        options.Audience =
            "agent-api";

        options.RequireHttpsMetadata = true;
    });

Similarly, use the middleware

app.UseAuthentication();

Define fine-grained permissions for agents

Mostly, agents should not be given full API access. Use role-based access control (RBAC) to distinguish between agent types, where a read-only information retriever needs a different set of permissions while a planning agent needs broader write access. Adding an authorization policy with fine-grained permission scoping prevents overprivileged agents.

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy(
        "InvoicesRead",
        policy => policy.RequireClaim(
            "scope",
            "invoices:read"));

    options.AddPolicy(
        "InvoicesWrite",
        policy => policy.RequireClaim(
            "scope",
            "invoices:write"));
});

For the invoices, I have added two explicit permissions: read and write. Well, you may not hardcode them for a scalable application, there you need more customization and dynamism. Add to the pipeline.

app.UseAuthorization();

Decorate the endpoints.

[Authorize(Policy = "InvoicesRead")]
[HttpGet]
public async Task<IActionResult> GetInvoicesAsync(
	[FromQuery] string? status,
	[FromQuery] int limit = 20,
	[FromQuery] string? cursor = null,
	CancellationToken cancellationToken = default) ...

[Authorize(Policy = "InvoicesWrite")]
[HttpPost]
public async Task<IActionResult> CreateInvoiceAsync(
	[FromHeader(Name = "Idempotency-Key")]
	string idempotencyKey,
	CreateInvoiceRequest request,
	CancellationToken cancellationToken) ...

[Authorize(Policy = "InvoicesRead")]
[HttpGet("{id:guid}")]
public async Task<IActionResult> GetInvoice(
	Guid id,
	CancellationToken cancellationToken) ...

[Authorize(Policy = "InvoicesWrite")]
[HttpPost("{id:guid}/finalize")]
public async Task<IActionResult> FinalizeAsync(
	Guid id,
	CancellationToken cancellationToken) ...
	
[Authorize(Policy = "InvoicesWrite")]
[HttpPost("{id:guid}/cancellation-intent")]
public async Task<IActionResult> CreateCancellationIntentAsync(
	Guid id,
	CancellationToken cancellationToken) ...

[Authorize(Policy = "InvoicesWrite")]
[HttpPost("cancel")]
public async Task<IActionResult> CancelAsync(
	[FromBody] CancelInvoiceRequest request,
	CancellationToken cancellationToken) ...

Architectural Considerations for AI Agent Integration

AI agents introduce a different set of requirements than traditional API consumers. They can generate unpredictable traffic, execute multi-step workflows, consume large amounts of data, and operate with a degree of autonomy. Designing APIs for these workloads therefore requires consideration of scalability, resilience, security, and how agents discover and interact with available capabilities.

Keep human approval involved

Along with authentication and authorization, the system should have human verification involved for any operation that updates sensitive or critical data or has an irreversible impact, keep human approval in the loop and don't let the agent execute the full workflow autonomously. We restrict agents with authorization as a low-privileged user, so similar to a low-privileged user, you usually add approvals from a higher authority.

Managing Bursty Agent Traffic

A particularly important aspect in AI-friendly APIs is that agentic traffic can be bursty and difficult to predict. An AI agent may call several endpoints to complete one task, such as fetching data, validating it, and then updating it, while a human user would do the same thing in fewer calls through the UI. Dynamic rate limiting, concurrency limits, and tiered quotas can help prevent agent traffic from overwhelming infrastructure or affecting human users. Bulk-operation endpoints can further reduce unnecessary requests by allowing agents to process multiple items within a single operation rather than repeatedly calling individual endpoints. Comprehensive logging and monitoring of agent interactions also helps identify unusual patterns and potential abuse early.

Ethical Data Handling for AI Agents

Machines are intelligent but do not always follow ethical guidelines like us humans. For an application, it is increasingly important that agents collect only the data they need. Decision-makers should minimize how long sensitive information is retained, and anonymize data when long-term storage is required. Data-handling practices should also be clearly documented to define clear boundaries for access. As agents use API data more for reasoning and decision-making, transparency around data sources, privacy, and potential bias becomes an important part of API design rather than merely a compliance requirement.

Model Context Protocol (MCP)

With the inception of AI, another API layer is introduced: MCP. MCP standardizes communication between AI clients and applications, safely abstracting the API to AI agents. ModelContextProtocol.AspNetCore package provides easy creation of MCP or you can use a reliable provider to make your project AI-ready.

Infrastructure for Agent-Driven Scale

Keep in mind that, unlike human users, a single agent can make hundreds of requests in a short period during a multi-step task. Try horizontal scaling, intelligent load balancing, caching strategies, and queue-based processing in the backend before traffic spikes degrade the experience for human consumers.

Building Agent-Friendly Abstractions

An API should not change so dramatically that AI finds it difficult to evolve and understand. Plugin architectures and function-oriented interfaces are good choices, letting you add new capabilities without disrupting existing workflows. More importantly, these abstractions should represent meaningful business capabilities rather than exposing low-level technical operations. Agents generally reason in terms of goals and actions, not database tables or internal implementation details.

Conclusion

The way software interacts with APIs is evolving. Traditionally, developers wrote the logic that determined which endpoint to call, when to call it, and how to handle the response. AI agents can increasingly make those decisions themselves. Agents like coding agents, booking agents, business agents, and application bots complete tasks on behalf of the user. Your API project should catch this train. Making an API agent-ready isn't about adding an AI endpoint. It's about making the existing API predictable, discoverable, secure, and understandable to machines. I dug into some important foundations that make your backend agent-friendly.

Code: https://github.com/elmahio-blog/AgentReadyApi.git

Swagger UI used to come bundled with every new ASP.NET Core Web API project. Recent .NET versions replaced it with a bare OpenAPI document, leaving you to pick your own documentation UI, and Scalar has become one of the most popular choices. This post compares Swagger and Scalar, and walks through setting up each one in .NET 10.

You should test APIs before giving them to the frontend team. API testing and documenting them together is a tedious task, especially if the application is large enough. Many people prefer Postman documentation. However, there are graphical representations too that require a little less effort than documenting and testing your APIs. Swagger has been a long-time partner in interactive API documentation. The .NET 8 API template included Swashbuckle by default to provide both the OpenAPI JSON and the Swagger UI. However, later versions have brought novelty. The API template now has a default OpenAPI document, which developers typically pair with modern UI tools like Scalar.

Difference between Swagger and Swagger UI

There is a lot of confusion about the exact separation, even though I myself used to think they are the same. Swagger is an open-source ecosystem of tools developed by SmartBear. It provides tools for designing, building, and testing APIs using the OpenAPI specification.

• Swagger UI: A web-based interface consuming the OpenAPI document. It allows developers to visualize and test endpoints.
• Swagger Editor: A visual OpenAPI editor that allows writing and editing in YAML or JSON formats in a user-friendly manner.
• Swagger Codegen: An engine to generate server stubs and client SDKs in 40+ languages directly from OpenAPI definitions.
• SwaggerHub: A commercial platform for API design, collaboration, and governance of enterprise-grade API lifecycle management.

Why did Microsoft remove Swashbuckle from its default template?

Swashbuckle was a long-time companion of the ASP.NET Core standard and Microsoft's default for OpenAPI documentation. However, declining maintenance and departing contributors led to issues, and it had poor .NET 8 support. Microsoft removed it from default templates in .NET 9. In .NET 10, the third-party UI is no longer bundled by default in new Web API templates. Hence, .NET prioritizes developer experience and modernity by removing Swagger UI by default and allowing developers to opt for any other library that supports an OpenAPI document. Note that Scalar didn't replace OpenAPI; it provides a modern documentation UI for visualizing and interacting with your OpenAPI description.

Implementing Swagger UI and Scalar in ASP.NET Core API

Here's how each one is implemented in ASP.NET Core.

Step 1: Create project

dotnet new webapi SwaggerVsScalar
cd SwaggerVsScalar

As I am working on .NET 10, the default Program.cs will look.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
    {
        var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                (
                    DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    Random.Shared.Next(-20, 55),
                    summaries[Random.Shared.Next(summaries.Length)]
                ))
            .ToArray();
        return forecast;
    })
    .WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

As you can see, OpenAPI support is built in by default.

Add Swagger UI

As we already have an endpoint, we can display it in Swagger.

Step 2: Add the package

dotnet add package Swashbuckle.AspNetCore

Step 3: Configure Program.cs

using Microsoft.OpenApi;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();


builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Swagger Demo API",
        Version = "v1",
        Description = "Demo API for comparing Swagger and Scalar"
    });
});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwagger();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger Demo API v1");
    });
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
    {
        var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                (
                    DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    Random.Shared.Next(-20, 55),
                    summaries[Random.Shared.Next(summaries.Length)]
                ))
            .ToArray();
        return forecast;
    })
    .WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Swashbuckle.AspNetCore provides AddSwaggerGen() to register a service in the generation of the OpenAPI document, while SwaggerDoc specifies that an OpenAPI document called v1 should be generated using this metadata.

app.UseSwagger() makes the generated OpenAPI document available through HTTP and accessible at /swagger/v1/swagger.json.

The app.UseSwaggerUI is the actual Swagger UI and creates a web interface reading the document via the given path /swagger/v1/swagger.json. Finally, it displays it as an interactive API documentation page.

Step 4: Run the project

dotnet run

The Swagger UI is visible.

Add Scalar UI

Step 2: Add the package

dotnet add package Scalar.AspNetCore

Step 3: Configure program file

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
    {
        var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                (
                    DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    Random.Shared.Next(-20, 55),
                    summaries[Random.Shared.Next(summaries.Length)]
                ))
            .ToArray();
        return forecast;
    })
    .WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

app.MapScalarApiReference() registers Scalar's API documentation UI as an endpoint in the ASP.NET Core application. Navigating to /scalar will open the Scalar interface by reading the document exposed by app.MapOpenApi().

Step 4: Run the project

dotnet run

Now, the UI is accessible.

In the top-left corner is the menu that displays all endpoints using the OpenAPI document.

Scroll down to where the endpoints are displayed so we can test one.

Let's test by clicking the Test Request button.

Here's the response I got.

Attach OpenAPI metadata to the endpoint

You can add more details to the endpoint for the OpenAPI document.

app
    .MapGet("/weatherforecast", () =>
    {
        var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                (
                    DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    Random.Shared.Next(-20, 55),
                    summaries[Random.Shared.Next(summaries.Length)]
                ))
            .ToArray();
        return forecast;
    })
    .WithName("GetWeatherForecast")
    .WithSummary("weather data for the state")
    .WithDescription("This endpoint returns weather report for different counties.")
    .WithTags("My place")
    .Produces(200, typeof(object))
    .Produces(400)
    .ProducesProblem(500)
    .RequireAuthorization();

WithSummary provides a short summary for the endpoint, while WithDescription adds a longer description. WithTags categorizes endpoints, while the Produces fluent methods define successful and failure responses.

Import the Specification into Postman

The raw specification will be accessible at /openapi/v1.json, which is http://localhost:5282/openapi/v1.json in our case.

Postman can automatically build request collections from this native endpoint using the following steps:

1. Open Postman and select the Import button in the top-left sidebar.
2. Either import via Link: Choose the Link tab and paste the local URL.
3. Or via File: Save the JSON from the browser, then drag the file into the Postman import window.

Our API document is imported.

Add a descriptive document with API controller

Now, we've seen how the minimal API looks with Scalar. Although for Swagger, you may already know what it looks like with controllers. I will show how Scalar works with the API.

Step 1: Create model

namespace SwaggerVsScalar.Models;

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
}

Step 2: Add controller

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using SwaggerVsScalar.Models;

[ApiController]
[Route("api/[controller]")]
[Tags("Products")]
public class ProductsController : ControllerBase
{
    private readonly List<Product> _products;

    public ProductsController()
    {
        _products = new List<Product>
        {
            new Product { Id = 1, Name = "Matcha" },
            new Product { Id = 2, Name = "Cappuccino" }
        };
    }

    [HttpPost]
    [EndpointName("CreateProduct")]
    [EndpointSummary("Creates a new product")]
    [EndpointDescription("This endpoint creates a new product and returns the created product.")]
    [ProducesResponseType(typeof(Product), StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public IActionResult CreateProduct(Product input)
    {
        _products.Add(input);

        return CreatedAtAction(
            nameof(GetProduct),
            new { id = input.Id },
            input);
    }

    [HttpGet]
    [EndpointName("GetProducts")]
    [EndpointSummary("Gets all products")]
    [EndpointDescription("This endpoint returns all available products.")]
    [ProducesResponseType(typeof(IEnumerable<Product>), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public IActionResult GetProducts()
    {
        return Ok(_products);
    }

    [HttpGet("{id}")]
    [EndpointName("GetProduct")]
    [EndpointSummary("Gets a product by ID")]
    [EndpointDescription("This endpoint returns a product matching the specified ID.")]
    [ProducesResponseType(typeof(Product), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public IActionResult GetProduct(int id)
    {
        var result = _products.FirstOrDefault(x => x.Id == id);

        if (result is null)
            return NotFound();

        return Ok(result);
    }
}

Here, we have a controller with some in-memory values. A noticeable addition is the description attributes [EndpointName], [EndpointSummary], [EndpointDescription], and [ProducesResponseType], which are alternatives to the fluent API methods we used with the minimal API.

Step 3: Configure Program.cs

There won't be much change from our previous setup. We just need to inject controllers so the API controllers get mapped. The final file looks like this:

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.UseHttpsRedirection();

app.Run();

After running the project, we get the following result.

Each endpoint looks like this.

Get All.

GetById method.

Finally, we can see the model.

When to pick Swagger and when to pick Scalar?

We have to peel back the main discussion point: if Swagger is legendary and Scalar is modern, when to choose which? Scalar offers a modern developer experience with its search-oriented interface. Scalar specifically highlights responsive UI, dark mode, navigation, and improved handling of large APIs. Its built-in sidebar navigation for instant search is an advantage over the standard Swagger UI experience. Moreover, Scalar maintains request history, environment variables, code snippets and an advanced request configuration. You can customize themes with a wide range of options available by default. Such features make it a competitive choice for modern applications, a choice earlier competitors lacked.

Swagger is a mature and trusted option used by legacy systems. It has been powering APIs since 2011 and has earned developers' familiarity. It is simple and ideal for users who want to "Try it out". For a small and simple API project, Swagger suits better without adding a new tool to navigate and learn. Besides, an existing system that already uses Swagger shouldn't rush to switch to a new option, where the team may get tangled with learning another tool.

Conclusion

Scalar is a transformation in API documentation. For a long time, Swagger has been the default option for ASP.NET Core APIs that were developed using the template. However, in recent versions, Microsoft has removed the default Swagger and provided an OpenAPI document by default. The NuGet store offers several options for consuming the document, among which Scalar has emerged as a futuristic solution. Its features range from customized UI themes to search-friendly navigation. In this post, we discussed in depth the differences between Swagger and Scalar. We implemented each of them in .NET 10 to see the actual visual differences between them.

Code: https://github.com/elmahio-blog/SwaggerVsScalar

Think of your application's configuration as the control panel of an aircraft. Every switch, dial, and indicator influences how the system operates. A single incorrect setting can change the application's behavior in unexpected ways. In this post, I will build configuration models that are safer, cleaner, and easier to maintain using modern C# features.

The first choice that comes to mind is mutable POCO (Plain Old CLR Object) classes for configuration. That intuition does the job, but its values can be changed unexpectedly or accept invalid values. With records, you can create configuration models that behave more like a protected cockpit. C# records enable configuration values to be validated and immutable, designed to prevent mistakes before takeoff.

Why do traditional configuration classes become a problem?

A typical configuration class often looks like this:

public class DatabaseSettings 
{ 
  public string ConnectionString { get; set; } 
  public int CommandTimeout { get; set; } 
  public bool EnableRetry { get; set; } 
}

Although it looks simple, this design has several drawbacks.

Properties can be modified anywhere, leading to object inconsistency. No validation exists, and invalid values are accepted. It has no computed properties for a custom representation of the values. For any invalid value, the application will continue until it encounters the problem caused by the value.

Records are data models which by nature are immutable, making them ideal for configuration values. That is a big win for records, as we can only copy a record using the with keyword, but the original object remains untouched. Also, records can validate themselves, preventing invalid inputs while keeping the options pattern alive. Such validations not only keep technical blunders away, but implement business logic as well. They also work beautifully with pattern matching, so we can compare values cleanly. For all these reasons, I have called it smart records.

Using smart records for appsettings configuration in ASP.NET Core

Step 1: Create Api project.

dotnet new webapi -n SmartRecordApi

Step 2: Add Configuration

In appsettings.json add the following configuration:

"WeatherSettings": {
  "City": "Karachi",
  "TemperatureUnit": "Celsius",
  "RefreshInterval": 30,
  "EnableForecast": true
}

Step 3: Create a smart record

Create a new file named Configuration/WeatherSettings.cs:

namespace SmartRecordDemo.Configuration;

public record WeatherSettings
{
    public required string City { get; init; }
    public required string TemperatureUnit { get; init; }
    public int RefreshInterval { get; init; }
    public bool EnableForecast { get; init; }
}

public static class WeatherSettingsExtensions
{
    extension(WeatherSettings settings)
    {
        public void Validate()
        {
            if (string.IsNullOrWhiteSpace(settings.City))
                throw new ArgumentException("City is required.");

            if (settings.RefreshInterval <= 0)
                throw new ArgumentException(
                    "RefreshInterval must be greater than zero.");

            if (settings.TemperatureUnit is not ("Celsius" or "Fahrenheit"))
                throw new ArgumentException(
                    "TemperatureUnit must be Celsius or Fahrenheit.");
        }

        public string DisplayName =>
            $"{settings.City} ({settings.TemperatureUnit})";
    }
}

C#14 brought a new syntax for extension methods. Inside, DisplayName is a computed property for display, while Validate is a helper Property. The Validate method includes different checks to ensure self-data validity.

Step 4: Register the options pattern

In Program.cs include the following code:

using SmartRecordApi.Configurations;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

builder.Services
    .AddOptions<WeatherSettings>()
    .Bind(builder.Configuration.GetSection("WeatherSettings"))
    .PostConfigure(settings => settings.Validate());

builder.Services.AddControllers();

var app = builder.Build();

app.MapControllers();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.Run();

Bind() reads from appsettings.json while PostConfigure() validates the settings after binding. Here, I called the Validate method at registration. As I will declare a new controller and will not use minimal API, I had to add builder.Services.AddControllers and app.MapControllers.

Step 5: Add a controller

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using SmartRecordApi.Configurations;

namespace SmartRecordApi.Controllers;

[ApiController]
[Route("api/weather")]
public class WeatherController : ControllerBase
{
    private readonly WeatherSettings _settings;

    public WeatherController(IOptions<WeatherSettings> options)
    {
        _settings = options.Value;
    }

    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new
        {
            _settings.City,
            _settings.TemperatureUnit,
            _settings.RefreshInterval,
            _settings.EnableForecast,
            _settings.DisplayName
        });
    }
}

Here, WeatherSettings is injected using the options pattern.

Step 6: Run the project.

dotnet run

Let's check validity. I have kept the city empty fow now:

"WeatherSettings": {
  "City": "",
  "TemperatureUnit": "Celsius",
  "RefreshInterval": 30,
  "EnableForecast": true
}

A traditional way to define the records is:

public record WeatherSettings
{
    public required string City { get; init; }
    public required string TemperatureUnit { get; init; }
    public int RefreshInterval { get; init; }
    public bool EnableForecast { get; init; }

    // Computed Property
    public string DisplayName =>
        $"{City} ({TemperatureUnit})";

    // Helper Property
    public bool IsAutoRefreshEnabled =>
        RefreshInterval > 0;

    public void Validate()
    {
        if (string.IsNullOrWhiteSpace(City))
            throw new InvalidOperationException("City is required.");

        if (RefreshInterval <= 0)
            throw new InvalidOperationException("RefreshInterval must be greater than zero.");

        if (TemperatureUnit is not ("Celsius" or "Fahrenheit"))
            throw new InvalidOperationException("TemperatureUnit must be Celsius or Fahrenheit.");
    }
}

Here DisplayName is a computed property for display, IsAutoRefreshEnabled is a helper for RefreshInterval validation. While all other checks are in the Validate method. Although that works, it is from prior C# versions.

Best Practices

• Write validations in the extension method for business requirements and data validity and use them in creation or startup.
• Use computed properties instead of repeating calculations.
• Group related settings into nested records.
• Keep helper methods focused on configuration-related behavior.
• Avoid putting unrelated business logic into configuration models.
• Use the with expression when creating modified copies.
• Combine records with the Options pattern for clean dependency injection.

Conclusion

Configuration models shouldn't just store data, they should protect it. Records are suited for such cases, i.e., making configuration objects immutable, self-validating, expressive, and easier to maintain. C# 14 puts the cherry on top with new extension method declarations. Instead of relying on mutable classes with scattered validation, records allow you to centralize rules, reduce bugs, and write cleaner ASP.NET Core applications. As modern C# evolves, embracing records for configuration is a simple yet powerful step toward building more reliable and maintainable software.

Code: https://github.com/elmahio-blog/SmartRecordApi

Nowadays, everyone talks about AI. Building with AI, integrating AI into your application, and similar topics are hot topics. In today's post, I'll step into the .NET AI world by building a very simple Retrieval-Augmented Generation (RAG) implementation.

As it is our baby step, I intentionally designed a beginner-friendly introduction rather than a production-ready RAG implementation. We won't build a vector database or use embeddings yet. Instead, we'll use simple keyword matching to simulate the retrieval process and focus on understanding how the pieces of a RAG system fit together.

In future posts, we will climb the Everest of .NET AI, but for today sticking to the baby steps. Our idea is that instead of asking an AI model to answer a question using only what it already knows, we first retrieve relevant information from our own knowledge base and provide that information to the model as context.

What is Retrieval-Augmented Generation (RAG)?

RAG is an architecture for optimizing the performance of an artificial intelligence (AI) model by integrating it with external knowledge bases. RAG allows AI models to combine their powerful capabilities with a specific domain's or an organization's internal knowledge base to generate more relevant and accurate responses.

No matter how great an interior designer is, he cannot give you great design by just looking from the outside and not getting information about your home from inside. He needs to know what rooms look like and how they are placed. If you do not give him this information, he will make assumptions or give a very generic solution that sometimes proves wrong. A Large Language Model (LLM) works the same way, no matter how powerful Claude, ChatGPT, or any other model is, if you want it to work on your project, it needs its information. RAG basically combines AI's power with the organization's internal data to utilize it properly. Without the context, an AI model may rely on assumptions and generate information that may look credible but is not supported by your data. This is commonly known as an AI hallucination.

RAG helps AI propose concrete answers based on the data, otherwise, it can fall into guessing and lead to hallucinations.

So RAG works in 3 steps: Retrieve ➡️ Augment ➡️ Generate

We retrieve relevant information from our knowledge base, add it to the AI prompt as context, and then let the AI model generate an answer based on that information.

Starting with RAG in an ASP.NET Core API

To take our first baby step, let's design an API with a simple RAG architecture.

Step 1: Create Api project

dotnet new webapi -n RAGPlayground

Step 2: Create an input model

namespace RAGPlayground.Models;

public class QueryInp
{
    public string Question { get; set; } = string.Empty;
}

Step 3: Add a document store

The document store will represent our knowledge base, exposing a method called Search.

public interface IDocumentStore
{
    List<string> Search(string query);
}

Its implementation is as follows:

public class DocumentStore : IDocumentStore
{
    private readonly List<string> _documents =
    [
        "Minimal APIs simplify endpoint development in ASP.NET Core.",
        "Entity Framework Core streamlines database operations.",
        "Background services process long-running tasks efficiently.",
        "Dependency injection improves application maintainability."
    ];

    public List<string> Search(string query)
    {
        return _documents
            .Select(doc => new
            {
                Document = doc,
                Score = CalculateScore(doc, query)
            })
            .OrderByDescending(x => x.Score)
            .Where(x => x.Score > 0)
            .Take(3)
            .Select(x => x.Document)
            .ToList();
    }

    private int CalculateScore(string doc, string query)
    {
        var score = 0;

        var queryWords = query
            .ToLower()
            .Split(' ', StringSplitOptions.RemoveEmptyEntries);

        foreach (var word in queryWords)
        {
            if (doc.ToLower().Contains(word))
            {
                score++;
            }
        }

        return score;
    }
}

DocumentStore is a simple in-memory document repository that simulates the retrieval part of a RAG system. It stores a collection of documents and returns the most relevant ones based on keyword matching.

The _documents list contains the collection on which search is performed. Search involves four steps:

• Calculate a relevance score for every document.
• Sort documents from highest score to lowest.
• Remove documents with a score of zero.
• Return the top three matching documents.

The CalculateScore method converts the query string to lowercase before splitting it into individual words. Then it checks if each word appears in the document. The more query words found in the document, the higher the score becomes for that document.

Step 4: Create RAG layer

public interface IRagService
{
    Task<string> AskAsync(string question);
}

The service implementation.

using RAGPlayground.Contracts;

namespace RAGPlayground.Services;

public class RagService: IRagService
{
    private readonly IDocumentStore _documentStore;

    public RagService(IDocumentStore documentStore)
    {
        _documentStore = documentStore;
    }

    public async Task<string> AskAsync(string question)
    {
        var context = _documentStore.Search(question);

        if (context is null || !context.Any())
        {
            return "No relevant information found.";
        }
        var prompt = $"""
                      Based only on the context below, answer the user's question.

                      If the answer cannot be found in the context, say:
                      "I don't have enough information."

                      Context:
                      {context.First()}

                      Question:
                      {question}
                      """;

        return await Task.FromResult(prompt);
    }
}

The service layer is much simpler. It calls the underlying document store layer and returns the document with the highest score. The prompt variable concatenates context and question, mimicking the augmentation step of the RAG.

Step 5: Add a controller

using Microsoft.AspNetCore.Mvc;
using RAGPlayground.Contracts;
using RAGPlayground.Models;

namespace RAGPlayground.Controllers;

[ApiController]
[Route("api/[controller]")]
public class RagController : ControllerBase
{
    private readonly IRagService _ragService;

    public RagController(IRagService ragService)
    {
        _ragService = ragService;
    }

    [HttpPost("ask")]
    public async Task<IActionResult> Ask([FromBody] QueryInp input)
    {
        var answer = await _ragService.AskAsync(input.Question);
        return Ok(new { answer });
    }
}

Now, I am exposing everything to the user via an ask endpoint.

Step 6: Run the project

dotnet run

In Postman, we can test the ask endpoint:

If a word is not found, a fitting answer is provided:

Step 7: Use simulation with an AI model

In production, you will use an AI such as OpenAI, Grok, Azure OpenAI, etc. In that case, the service layer method will include a contextual prompt. The AI client service is

public interface IAiClient
{
    Task<string> GenerateAsync(string prompt);
}

Its implementation is as follows:

public class AiClient : IAiClient
{
    public Task<string> GenerateAsync(string prompt)
    {
        // Call your actual AI provider here.
        // For example: OpenAI, Azure OpenAI, Claude, Grok, etc.

        throw new NotImplementedException(
            "Connect an AI provider here.");
    }
}

Dependency injection registration:

builder.Services.AddScoped<IAiClient, AiClient>();

The updated RagService will look like:

public class RagService: IRagService
{
    private readonly IDocumentStore _documentStore;
    private readonly IAiClient _aiClient;
    
    public RagService(IDocumentStore documentStore, IAiClient aiClient)
    {
        _documentStore = documentStore;
        _aiClient = aiClient;
    }

    public async Task<string> AskAsync(string question)
    {
        var context = _documentStore.Search(question);

        if (context is null || !context.Any())
        {
            return "No relevant information found.";
        }
        var prompt = $"""
                      Based only on the context below, answer the user's question.

                      If the answer cannot be found in the context, say:
                      "I don't have enough information."

                      Context:
                      {context.First()}

                      Question:
                      {question}
                      """;
        var answer = await _aiClient.GenerateAsync(prompt);

        return answer;
    }
}

The answer will be fetched via the AI client you are using. Finally, the answer is generated by an AI client, which we have abstracted for this article; in future posts, we will use a real AI client to go one step further. That last stage represents the generation part of the RAG.

What to consider while choosing RAG?

While RAG enhances the accuracy of AI models, you need to keep in mind a few points before going forward:

• If the information your AI needs is very small and rarely changes, you can include it directly in the AI's system prompt instead of building a document search pipeline. Information like FAQs and product features is usually small enough to fit a few hundred tokens and send with every request. You don't need a RAG pipeline in such cases.
• Structured questions such as how many customers onboarded last year or how much revenue our company generated are database queries rather than AI prompts. Consider function calling that lets the model query your APIs instead.
• RAG is not good at answering questions that require analyzing an entire dataset, because RAG is designed to retrieve only the most relevant pieces, not every document. Don't use RAG for aggregation problems like finding this month's shopping trends or counting complaint categories.
• A recommended approach to designing a RAG application is a layered approach, with prompt building, retrieval logic, and LLM integration residing in separate services.
• To improve retrieval in a production-grade application, use embeddings instead of word matching. Once documents become embeddings, you need a vector database to store them.
• Secure your API with JWT authentication and authorization to avoid information leaking to unauthorized users. Role-based Access Control (RBAC) is useful for restricting access to the application.
• For a SaaS application, isolate tenants to better track and limit prompts for each client.

Conclusion

RAG empowers AI's accuracy by connecting it with system-specific knowledge. We saw how to use RAG architecture in an ASP.NET Core API using a basic knowledge base. For a real AI LLM integration, we will continue from here by implementing the AiClient class. Later, we list best practices to consider to use it effectively.

Code: https://github.com/elmahio-blog/RAGPlayground.git

Artificial Intelligence is no longer limited to answering questions. It can now interact with applications, retrieve data, and perform real tasks. In fact, tons of applications are already doing this. But for AI assistants to communicate with your software, they need a common language. The standard communication is Model Context Protocol (MCP). As the name suggests, it allows AI clients, such as ChatGPT, Claude, and Visual Studio Code, to discover and invoke tools exposed by your application. Instead of building custom integrations for every AI platform, you expose your application's capabilities once, and any MCP-compatible client can use them. In today's post, I will share how to build our first MCP server in ASP.NET Core, create a small book catalog, expose several MCP tools, and test them.

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open standard created by Anthropic that provides a standard way for AI models to communicate with external tools and applications. MCP standardizes communication between AI clients and applications. Every MCP-compatible client speaks the same protocol. You implement your tools once, and any MCP client can discover and use them. Without MCP, each model can have different request formats, authentication methods, and tool descriptions.

Designing an MCP server in ASP.NET Core API

Let's jump right in and create our first MCP server.

Step 1: Create project

dotnet new webapi -n MCPPlayground

Step 2: Install MCP package

dotnet add package ModelContextProtocol.AspNetCore

The package enables the project to act as an MCP server.

Step 3: Create model

namespace MCPPlayground.Models;
public record Book(
    int Id,
    string Title,
    string Author,
    int Year,
    bool IsAvailable
);

To keep it simple, I am using a value-type record. But for a production-grade application, know your requirements.

Step 4: Add a repository

Let's add a repository with in-memory data.

using MCPPlayground.Models;

namespace MCPPlayground.Data;

public class BookRepo
{
    private readonly List<Book> _books =
    [
        new(1, "Clean Code", "Robert C. Martin", 2008, true),
        new(2, "The Pragmatic Programmer", "Andrew Hunt", 1999, false),
        new(3, "Design Patterns", "Erich Gamma", 1994, true),
        new(4, "Domain-Driven Design", "Eric Evans", 2003, true),
        new(5, "Refactoring", "Martin Fowler", 2018, false)
    ];

    public List<Book> GetAll() => _books;

    public Book? GetById(int id)
        => _books.FirstOrDefault(x => x.Id == id);

    public List<Book> Search(string keyword)
        => _books
            .Where(x =>
                x.Title.Contains(keyword, StringComparison.OrdinalIgnoreCase)
                    || x.Author.Contains(keyword, StringComparison.OrdinalIgnoreCase))
            .ToList();
}

I am exposing 3 methods from the repo. Don't forget to add dependency injection in Program.cs:

builder.Services.AddSingleton<BookRepo>();

Step 5: Create MCP tools

using MCPPlayground.Data;
using MCPPlayground.Models;
using ModelContextProtocol.Server;

namespace MCPPlayground.Tools;

[McpServerToolType]
public class BookTools(BookRepo repository)
{
    [McpServerTool]
    public IEnumerable<Book> GetAllBooks()
    {
        return repository.GetAll();
    }

    [McpServerTool]
    public Book? GetBookById(int id)
    {
        return repository.GetById(id);
    }

    [McpServerTool]
    public IEnumerable<Book> SearchBooks(string keyword)
    {
        return repository.Search(keyword);
    }
}

[McpServerToolType] marks the class as containing MCP tools. While [McpServerTool] marks a method that AI clients can invoke. Any method parameters automatically become tool inputs. C# method names are converted to MCP names like get_all_books if no custom name is specified for [McpServerTool].

Step 6: Setup MCP server configuration

Add MCP configuration in Program.cs:

builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();

Use the MapMcp method to map the /mcp URL which is the endpoint the AI clients are going to communicate with:

app.MapMcp("/mcp");

The final look of the file is;

using MCPPlayground.Data;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();

builder.Services.AddOpenApi();

builder.Services.AddSingleton<BookRepo>();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();
app.MapMcp("/mcp");
app.Run();

Step 7: Run the project

dotnet run

The project is running and listening at http://localhost:5082/mcp

Unlike APIs, where you manually call REST endpoints, the MCP server allows AI models to discover and call the tools. I will use the MCP Inspector to test, which will automatically discover available tools from the server. Simply select a tool, provide its arguments, and execute it. This mirrors how AI assistants such as Cursor or Claude discover and invoke an application's capabilities through Model Context Protocol.

Step 8: Install MCP inspector

For the MCP inspector, you need to have Node.js. Check if node and npm is installed by running:

node -v
npm -v

If not already installed, go to the official website: https://nodejs.org. Download the LTS (Long Term Support) version. Once the download completes:

• Run the installer.
• Click Next until installation completes.
• Keep "Add to PATH" checked (default).
• Finish the installation.

Verify the installation:

node -v
npm -v

Then run the following in a new terminal:

npx @modelcontextprotocol/inspector@latest

This will install and run the latest version of the inspector:

When the inspector is running, the browser opens up the UI:

Step 9: Test the MCP server

Add a new server for our application:

You can use the following configuration for the server:

Make sure to turn the connected toggle button on:

All the tools I designed will be visible in the tools window:

Calling the get_all_books tool:

Will show the in-memory data from the repository:

Another tool get_book_by_id:

Will show a single book from the repository:

We can also search book sby the keyword parameter:

The data is fetched successfully:

Step 10: Add descriptions to the tools

To better define each tool for AI model integration, it is recommended to add descriptions:

using System.ComponentModel;
using MCPPlayground.Data;
using MCPPlayground.Models;
using ModelContextProtocol.Server;

namespace MCPPlayground.Tools;

[McpServerToolType]
public class BookTools(BookRepo repository)
{
    [McpServerTool]
    [Description("Returns all books available in the library.")]
    public IEnumerable<Book> GetAllBooks()
    {
        return repository.GetAll();
    }

    [McpServerTool]
    [Description("Returns a single book by its unique identifier.")]
    public Book? GetBookById(
        [Description("The unique ID of the book.")] int id)
    {
        return repository.GetById(id);
    }

    [McpServerTool]
    [Description("Searches books by title or author.")]
    public IEnumerable<Book> SearchBooks(
        [Description("A keyword to search in the book title or author name.")] string keyword)
    {
        return repository.Search(keyword);
    }
}

The descriptions are visible in the inspector:

That's it. We have now developed our first MCP server using ASP.NET Core and the ModelContextProtocol.AspNetCore NuGet package. In this post, I focused on testing the tools through the inspector. But in real life, your tools will be called from an AI client. How you set up an MCP server in your favorite client depends on what client you use. As an example, you would use the following command for Claude:

claude mcp add --transport http book-mcp http://localhost:5082/mcp

Conclusion

As AI assistants become part of everyday development, one challenge quickly appears: how should an AI securely and consistently interact with your applications? In this post, I tackled this question by guiding you on how to design an MCP server in ASP.NET Core, which is surprisingly straightforward. With just a few configuration lines and a couple of attributes, you can expose your application's capabilities as AI-callable tools.

As applications adopt more AI, learning how to build MCP servers will become an increasingly valuable skill for .NET developers. Whether you're integrating AI into internal business systems or creating intelligent developer tools, MCP serves as a standardized and extensible foundation for connecting language models to real-world functionality. Something we are already fully utilizing on elmah.io's MCP server.

Code: https://github.com/elmahio-blog/MCPPlayground.git

We are all using async-await in our applications. But one thing that bothers me every time is how it is different from sync and how it actually works. In today's post, I will clear up the confusion for you and me.

Synchronous programming

Synchronous programming is a sequential way of executing code, where each line runs one by one. The next line does not start until the previous one completes, leaving the whole application on hold.

Asynchronous programming

Asynchronous programming is a non-blocking approach to code execution that does not execute in sequence. It allows long-running tasks, such as fetching from the database or reading content from files, to run without stalling the whole application. It initiates those delaying tasks and continues running other code while waiting for the result. The async/await keywords help define asynchronous programming. async is used with a method that runs asynchronously, and await pauses execution until the task completes. Note: In UI apps, a SynchronizationContext ensures code resumes back on the UI thread, whereas in console apps or ASP.NET Core, it resumes on any free ThreadPool thread.

Why do we need asynchronous programming?

Each .NET application runs on a main thread or request thread that starts your work.

• In a console app, it's the Main method.
• In ASP.NET Core, it's the thread handling the incoming HTTP request.
• In UI apps, it's the UI thread that displays the screen.

It performs the big responsibility of staying responsive and keeping the application moving. If this thread gets blocked, the application stops receiving HTTP requests, the UI freezes, and the application slows or breaks. So protecting this thread is critically important. Therefore, we go with asynchronous.

A brief peek at async/await execution

public async Task<int> GetDataCountAsync()
{
    Console.WriteLine("Before await");

    var response = await httpClient.GetAsync("/users");
    var count = await response.Content.ReadAsAsync<int>();
    Console.WriteLine("After await");

    return count;
}

The method runs synchronously until it reaches the first await.

When the compiler notices async/await code, it generates a state machine. More precisely, it generates a struct (or class, depending on optimization) implementing IAsyncStateMachine. The state machine stores the current state of the asynchronous method, from which it resumes execution later.

private struct GetDataCountAsyncStateMachine : IAsyncStateMachine
{
    public int state;
    public AsyncTaskMethodBuilder<int> builder;
    private HttpClient httpClient;
    private TaskAwaiter<HttpResponseMessage> awaiter1;
    private TaskAwaiter<int> awaiter2;

    void MoveNext()
    {
        switch (state)
        {
            case 0: /* first await segment */
            case 1: /* second await segment */
            // ...
        }
    }
}

The method pauses, runs in the background, and frees the main thread. The caller can continue doing other work, but any code that depends on the awaited result, cannot run until the await completes.

So, can we say that if I have 2 awaits, the state machine divides the method into 3 segments: before the 1st await, between the 1st and 2nd await, and after the 2nd await? When an await point is reached, the state machine yields control back to the caller and frees the thread. Once the underlying asynchronous operation completes, the runtime invokes MoveNext() again to execute the next segment.

Suspension: Where the Magic Actually Happens

If the awaited task is not yet complete, the state machine calls:

awaiter.OnCompleted(stateMachine.MoveNext);

This registers a continuation telling "call MoveNext() again when this task finishes" and then returns control to the caller. The calling thread is now free to do other work. This is the entire point of async/await: releasing the thread during the wait instead of blocking it.

At this point, GetDataCountAsync() returns an incomplete Task<int> to its caller, backed by the AsyncTaskMethodBuilder.

For network or disk I/O, no thread is actively running during the wait. The runtime hands the operation off to the OS and network hardware (via mechanisms like I/O Completion Ports). When the hardware receives the data, the OS signals the runtime, which queues the state machine to resume on an available ThreadPool thread.

Now, understand with an analogy. You have a few household chores, such as washing and drying clothes, cleaning the house, and cooking. If you proceed sequentially, each task will start only after the previous one is completed. Hence, the entire window will be occupied by a single task. However, that is time-consuming and inefficient. Here comes asynchronous tasking (async/await in programming terms), where you will leave time-consuming tasks on an automated thread and free yourself (the main thread) for other tasks in parallel. Once the delayed task is completed, you can get its results.

using System;
using System.Threading;
using System.Threading.Tasks;

public class HelloWorld
{
    static async Task WashAndDryClothes()
    {
        Log("WashAndDryClothes Started");

        string clothes = await WashClothes();

        Log($"Got result from WashClothes: {clothes}");

        await DryClothes(clothes);

        Log("WashAndDryClothes Finished");
    }

    static async Task<string> WashClothes()
    {
        Log("Washing clothes...");

        await Task.Delay(3000);

        Log("Washing completed");

        return "Clean Clothes";
    }

    static async Task DryClothes(string clothes)
    {
        Log($"Drying {clothes}...");

        await Task.Delay(2000);

        Log("Drying completed");
    }

    static async Task CleanHouse()
    {
        Log("Cleaning house...");

        await Task.Delay(4000);

        Log("Cleaning completed");
    }

    static async Task CookFood()
    {
        Log("Cooking food...");

        await Task.Delay(5000);

        Log("Cooking completed");
    }

    static void Log(string message)
    {
        Console.WriteLine(
            $"{DateTime.Now:HH:mm:ss.fff} | Thread {Thread.CurrentThread.ManagedThreadId} | {message}");
    }
    public static async Task  Main(string[] args)
    {
         Log("Main Started");

        Task task1 = WashAndDryClothes();
        Task task2 = CleanHouse();
        Task task3 = CookFood();

        Log("All tasks started");

        await Task.WhenAll(task1, task2, task3);

        Log("All tasks completed");
    }
}

Each method represents a chore, and to mimic the time of the chore, I added Task.Delay. The result is:

So Thread 1 just starts and goes to WashClothes which is called from WashAndDryClothes. The .NET ThreadPool already exists before the application starts. It has many worker threads, such as Thread 1, Thread 5, and Thread 6. At this moment, Thread 1 is executingMain(), while the other threads are simply idle, waiting for work. After logging WashAndDryClothes Started and Washing clothes... it finds that the method will take 3 seconds. Now, the thread does not wait, realizing that this operation will not finish immediately. Instead of waiting for 3 seconds, it does three things:

1. It registers a 3 second callback in .NET's internal timer queue (which doesn't hold or block a thread while waiting).
2. It saves the current state of the WashClothes state machine (state = 0) along with everything needed to continue later.
3. It registers a continuation that says:

When this 3-second delay completes, call WashClothes.MoveNext().

Thread 1 then immediately returns from WashClothes(), then returns from WashAndDryClothes(), and starts executing the later part of the in Main(). When it meets CleanHouse();, it logs Cleaning house... and sees a 4000 ms delay. The same three things happen:

• A 4-second timer is created.
• The CleanHouse state machine saves its current state.
• It registers:

"When the 4-second delay completes, call CleanHouse.MoveNext()."

Thread 1 returns to the Main method again to handle other tasks. Now it goes toCookFood(), where it waits 5 seconds.

• An OS-managed 5-second timer is created.
• The CookFood state machine saves its state (state = 0).
• It registers:

"When the 5-second delay completes, call CookFood.MoveNext()."

Now all three tasks have been started.

Thread 1 executes.

await Task.WhenAll(task1, task2, task3);

Since none of the three tasks have finished yet, the Main state machine also saves its state and registers:

"When all three tasks complete, call Main.MoveNext()."

Now Thread 1 has nothing left to do, so it joins the other idle threads in the ThreadPool and becomes idle.

Well, after 3 seconds. The 3-second timer expires.

The OS/.NET timer system tells the Task.Delay object:

"Your delay has finished."

The Task.Delay completes, which queues the registered continuation:

WashClothes.MoveNext()

The ThreadPool now looks for any available worker thread. It finds that Thread 5 is available. It assigns the continuation to Thread 5.

Hence, Thread 5 executes:

WashClothes.MoveNext()

WashClothes continues after the await, logs:

Washing completed

returns "Clean Clothes", and completes. Because WashAndDryClothes was waiting for that result, its continuation is immediately ready too:

WashAndDryClothes.MoveNext()

Since Thread 5 is already running, it simply continues on the same thread. It executes:

string clothes = awaiter.GetResult();

Logs:

Got result from WashClothes: Clean Clothes

Then starts:

await DryClothes(clothes);

It reaches another Task.Delay(2000), saves its state, registers another continuation, and Thread 5 becomes idle again.

After 4 seconds, the 4-second timer expires. The continuation.

CleanHouse.MoveNext()

is queued. The ThreadPool looks for a free worker and finds Thread 6 is idle.

Thread 6 executes.

CleanHouse.MoveNext()

It logs.

Cleaning completed

and finishes.

Now 5 seconds have passed. The two timers are now completing almost together. First, the DryClothes delay finishes. The ThreadPool looks for a free worker.

As Thread 5 was done with WashAndDryClothes and is free again.

It executes:

DryClothes.MoveNext()

Logs:

Drying completed

DryClothes finishes, which immediately allows WashAndDryClothes to continue. Since Thread 5 is already executing, it continues directly into:

WashAndDryClothes.MoveNext()

and logs:

WashAndDryClothes Finished

Almost at the same time, the 5-second timer for CookFood expires. The continuation:

CookFood.MoveNext()

is queued.

Till now, Thread 6 is available and executes:

Cooking completed

Now all three tasks have completed. Task.WhenAll also becomes complete. Its registered continuation is:

Main.MoveNext()

Since Thread 6 is already executing, it continues directly into Main.MoveNext() and logs.

All tasks completed

The application is now finished.

What are the benefits of asynchronous programming?

Because of its miraculous non-blocking nature, asynchronous programming offers key benefits for modern applications.

Better CPU utilization

In sequential execution, a thread is doing absolutely nothing while waiting for a resource, such as data or file content. Instead of wasting a thread, the thread becomes available for other requests.

Scalability

Another big benefit is the potential to scale your application. Imagine your API takes hundreds of milliseconds to process while different users access it at once. The non-blocking nature will allow all requests without stalling the server on a long-running database hit.

Better responsiveness

Definitely, this one is the key reason modern developers use async/await. UI thread remains free, and users can interact with the application without spoiling their experience.

Higher server throughput

Imagine a server with 10 ThreadPool threads. Each request waits 2 seconds for SQL. In the synchronous world, each of them will occupy one thread, and the 11th thread has to wait. In the asynchronous world, a thread becomes available immediately without depending on others, and the thread pool assigns the next task to it without leaving any threads idle.

Efficient memory usage

Blocking a thread ties up its ~1 MB stack allocation doing nothing. Under high load, this forces the ThreadPool to spin up hundreds of threads, consuming gigabytes of memory. Async frees the thread immediately, keeping memory usage limited to a small heap-allocated state machine until the task completes.

Cleaner code than callbacks

Without it, you had to make callbacks for dependent calls like

GetData(result =>
{
    Save(result, x =>
    {
        SendEmail(x, y =>
        {
            Console.WriteLine(y);
        });
    });
});

async/await will let you do this with

var data = await GetData();

var saved = await Save(data);

await SendEmail(saved);

When should you use async?

Asynchronous programming's non-blocking approach is strongly recommended for tasks such as database calls, file I/O, HTTP calls, network operations, and Cloud APIs. However, for any complex calculations, it does not help, like if the CPU is calculating something on the already-fetched data, because in any case the CPU has to perform the calculations.

Conclusion

Async/await is a cornerstone in modern applications. Any task that delays is awaited, and that is the only recommended way to handle such tasks. We peeked inside async/await with analogous examples of how it worked. Apart from keeping the UI responsive, it pays off in CPU, memory, and scalability too.

I spend most of my day in Claude Code these days. Most of my development processes changed after having access to my own personal assistant. In this post, I'll show you a real-life example of how bug fixes are often done on elmah.io now. I hope it will inspire someone to optimize their workflow and get even more out of their elmah.io subscription.

Monitoring elmah.io itself and fixing bugs when errors occur are a large part of keeping elmah.io's quality high. We use various ways to monitor that everything is working as intended, the big one being elmah.io itself. We receive new errors from the various websites and services through elmah.io and a shared Slack channel. In the old days, fixing errors was mostly a manual task, where only the build and publish part were fully automated. We would look up the error manually through the elmah.io UI and inspect the various pieces of information, trying to understand what was going wrong. Alongside the Source Code window in elmah.io, we would have Visual Studio open with the solution containing the failing code.

With the release of the elmah.io MCP server, this changed towards a much more automated approach. If you haven't run into MCP yet, the short version is that it's a protocol that lets AI tools like Claude Code call out to external services in a structured, secure way. Instead of me copy-pasting a stack trace into a chat window and asking "what does this mean", Claude Code can now go and look at the actual error itself, plus the uptime checks, heartbeats, and deployments around it. It's less "ask an AI about your errors" and more "give your AI tool the same access to elmah.io that you have". Let's try to set it up.

Connecting Claude Code to elmah.io

You'll need Claude Code installed and an elmah.io account, and everything happens from the terminal, so there's no config file to hand-edit and no API key to generate and paste in somewhere. API keys are also supported on the MCP server, but for this post, we'll use the UI to sign in.

First, register the MCP server:

This just tells Claude Code that a server called elmahio exists and where to find it. It doesn't authenticate anything yet. To do that, launch Claude Code and run /mcp:

You'll see a list of configured MCP servers, and elmahio should show up with a status of "needs authentication". Select it and click Authenticate, which opens a browser window with a normal OAuth login screen:

Sign in with your elmah.io account like you would on app.elmah.io, approve the request, and you're done. Claude Code doesn't see your password, just a token scoped to your account.

To make sure it actually worked, run /mcp list inside Claude Code:

Check that elmahio shows up as "connected". If it doesn't, the most common issue in my experience is that the OAuth flow got closed before finishing. Running /mcp again and re-authenticating should fix it.

If you'd rather not write your own prompts and just want a working setup out of the box, there's also an AI Plugin that installs the MCP server together with a handful of ready-made skills and a background monitoring agent. I'll stick to the raw MCP setup here, since that's what most of the examples below build on.

What a real fix looks like end to end

Rather than list out the individual things you can ask, let's stick to the scenario specified in the beginning: receiving a new error notification. It usually starts with a Slack message or an email from elmah.io saying a new error was just logged in production. Instead of opening a browser tab, I switch to Claude Code, which already has the MCP server connected. I'll open Claude Code in the base directory containing subfolders for all of elmah.io's sites and services. Then ask it to fetch the error details:

The first time you do this, Claude Code will ask the elmah.io MCP for a list of logs you have access to, to try and find the right log. After running through this workflow for each individual project and log, Claude will remember which log belongs to which project. You can also tell Claude the mapping between folders and log IDs up front and have it save it to memory.

Claude goes and fetches the actual message, stack trace, URL, and whatever custom data got attached. The same thing I'd otherwise be looking at on app.elmah.io.

From there I'll usually just ask it to try and fix the error:

Because Claude Code already has the codebase open, it has both the error and the code that caused it in the same context. It can go find the line the stack trace points to, work out why it's throwing, and make the change. This is the part that still feels a little unreal to type out, but it's genuinely how it goes most of the time now. I'm reading a diff instead of writing one.

Once I'm happy with the fix, I'll have it commit and push, the same way I would with any other change it makes for me. No copy-pasting a stack trace into a chat window, no switching context to go write the fix myself. The whole loop from "here's an error" to "here's a pushed commit" happens in one conversation. I always do a code review of the changes and often still launch the project locally to check that everything is working as expected. In many cases, testing on our staging environment is just as good. Claude also extends or writes a new unit test to verify the fix when it makes sense. And using the Playwright MCP server, I often let it take the application for a spin in the browser.

The part I think people skip when they talk about AI fixing bugs is what happens after it's live. That's where I use elmah.io's MCP server just as much. Once the fix has deployed, I'll go back to the same Claude Code session and ask it to monitor if new errors are being logged:

If it's a web app, I'll also ask it to check the uptime checks for that service:

This is to make sure the deploy itself didn't break anything unrelated. If it's a background service instead, like a scheduled job, Azure Function, or something without a URL to ping, I'll ask about heartbeats instead, since that's how we track whether those are still checking in on schedule:

That follow-up step is a small thing, but it's the one that made this feel trustworthy enough to actually use for real fixes.

Conclusion

We build the range of dashboards on app.elmah.io because sometimes, that's the right interface for looking at errors. But the better AI clients are becoming, a good chunk of the time I actually want to look at an error, I'm already in Claude Code doing something else. Switching tools costs more than the two seconds it sounds like. Having elmah.io reachable from the same place I'm already working is a small thing, but it's the kind of small thing that changes how often you actually check on your errors instead of waiting for them to page you.

In this post, I showed a simple example where Claude Code was able to fix everything from just looking at the error and the codebase. Of course, in real life, it's a cooperation between me as the developer who knows a lot of details about the elmah.io code base and the AI. Simple bugs can be fixed fast by the AI, while more complex issues require more input from me.

If you want to try it yourself, the docs page has the same setup steps in reference form, along with the equivalent instructions for Claude Desktop and other MCP-compatible tools.

As much as the web is evolving, cyber threats are also growing. Securing user details with a single password may not be enough to stop bad guys. Modern applications require stronger authentication. Two-factor authentication (2FA) and passkeys are two effective ways to apply efficient login. In today's post, I will walk you through how to implement 2FA and passkeys in an ASP.NET Core API. Well, that is going to be a long ride, so stay with me.

What is Two-Factor Authentication (2FA)?

Two-Factor Authentication is a security method that requires a user to provide two forms of identity verification. Unlike the traditional password login, 2FA requires users to confirm their identity using two distinct factors. Its 2-step authentication prevents unauthorized access even if the password is compromised.

What is Passkey?

A passkey is a highly secure, passwordless authentication method that provides a simple and secure way to sign in to applications. Instead of password authentication, it uses public-key cryptography. The private key stays securely on the user's device and is unlocked using biometrics (Face ID, fingerprint) or device PIN. Passkeys are based on the WebAuthn (Web Authentication API) standard and follow the FIDO2 specification.

Implementing 2FA and Passkey in ASP.NET Core .NET 10 API

I will go with the same project to implement both authentication methods. The following steps are shared between both types.

Step 1: Create a project

dotnet new web -n TwoFaNET10

Step 2: Add Swagger

.NET 10 does not contain Swagger by default. However, I will use it for testing the API.

dotnet add package Swashbuckle.AspNetCore 

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });
}

Two-factor authentication in .NET 10

Step 1: Install required packages

dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore
dotnet add package Microsoft.AspNetCore.Identity.UI
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

Step 2: Create models

using Microsoft.AspNetCore.Identity;

namespace TwoFaNET10.Models;

public class ApplicationUser : IdentityUser
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }

    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;

    public string FullName =>
        $"{FirstName} {LastName}".Trim();
}

IdentityUser is provided by AspNetCore's Identity namespace. Here I am creating the sub-class ApplicationUser with IdentityUser as its parent. It is a built-in user model containing necessary fields such as Email and UserName. With Microsoft's own user class, I don't have to implement password hashing, login, registration, or other authentication operations.

DTO for registering a user

public class RegisterDtoInp
{
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public string Password { get; set; } = string.Empty;
}

Login model

public class LoginDtoInp
{
    public string Email { get; set; } = string.Empty;
    public string Password { get; set; } = string.Empty;
    public bool RememberMe { get; set; } 
}

TwoFactorLoginDtoInp

public class TwoFactorLoginDtoInp
{
    public string TwoFactorCode { get; set; } = string.Empty;
    public bool RememberMe { get; set; }
    public bool RememberMachine { get; set; } 
}

Model for recovery of 2FA.

public class RecoveryCodeLoginDtoInp
{
    public string RecoveryCode { get; set; } = string.Empty;
}

Step 3: Create the Data context

using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;
using TwoFaNET10.Models;

namespace TwoFaNET10.Data;

public class ApplicationDbContext: IdentityDbContext<ApplicationUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        base.OnModelCreating(builder);
    }
}

By inheriting from IdentityDbContext<ApplicationUser>, I am leveraging the Identity namespace again to manage Identity tables using ApplicationUser.

Step 4: Add Database connection details

In appsettings.json add:

"ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=TwoFaDb;Username=postgres;Password=pass"
},

In Program.cs:

builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(connectionString));

Step 5: Define Controller for the 2FA endpoints

We injected Identity's classes SignInManager and UserManager into the controller. As their names indicate, the former handles authentication operations, while the latter abstracts away users' methods.

[HttpPost("register")]
public async Task<IActionResult> Register([FromBody] RegisterDtoInp model)
{
    if (!ModelState.IsValid)
        return ValidationProblem(ModelState);

    var user = new ApplicationUser
    {
        UserName = model.Email,
        Email = model.Email,
        FirstName = model.FirstName,
        LastName = model.LastName,
        CreatedAt = DateTime.UtcNow
    };

    var result = await userManager.CreateAsync(user, model.Password);

    if (result.Succeeded)
    {
        logger.LogInformation("New user registered: {Email}", model.Email);

        return Ok(new
        {
            Success = true,
            Email = model.Email,
            Message = "User registered successfully."
        });
    }

    return BadRequest(result.Errors.Select(x => x.Description));
}

userManager's CreateAsync method handles all the user creation abstraction itself. Registration includes validating and hashing the password and saving the user, all within a single method.

[HttpPost("login")]
public async Task<IActionResult> Login([FromBody] LoginDtoInp model)
{
    if (!ModelState.IsValid)
        return ValidationProblem(ModelState);

    var result = await signInManager.PasswordSignInAsync(
        model.Email,
        model.Password,
        model.RememberMe,
        lockoutOnFailure: true);

    if (result.Succeeded)
    {
        logger.LogInformation("User {Email} logged in.", model.Email);

        return Ok(new
        {
            Success = true,
            Message = "Login successful."
        });
    }

    if (result.RequiresTwoFactor)
    {
        return Ok(new
        {
            RequiresTwoFactor = true,
            RememberMe = model.RememberMe
        });
    }

    if (result.IsLockedOut)
    {
        return BadRequest(new
        {
            Message = "Account locked out due to multiple failed attempts. Try again later."
        });
    }

    return Unauthorized(new
    {
        Message = "Invalid email or password."
    });
}

Again, we don't need to peek inside the PasswordSignInAsync. Surprisingly, it will handle login regardless of whether 2FA is enabled. If 5 login attempts go wrong, Identity will lock the account for 5 minutes.

[Authorize]
[HttpGet("2fa/setup-uri")]
public async Task<IActionResult> Get2FaUri()
{
    var user = await userManager.GetUserAsync(User);

    if (user == null)
        return Unauthorized();

    var key = await userManager.GetAuthenticatorKeyAsync(user);

    if (string.IsNullOrEmpty(key))
    {
        await userManager.ResetAuthenticatorKeyAsync(user);
        key = await userManager.GetAuthenticatorKeyAsync(user);
    }

    var email = user.Email;

    var uri = $"otpauth://totp/TwoFaNET10:{email}?secret={key}&issuer=TwoFaNET10&digits=6";

    return Ok(new
    {
        qrUri = uri,
        secret = key
    });
}

This endpoint generates the secret key and QR Code URI that the user scans in their authenticator app. The action is authorized, and the user must be logged in to use this endpoint. First, await userManager.GetUserAsync(User) gets the current user. Again, using userManager to get the user authenticator secret from GetAuthenticatorKeyAsync. If the user does not have one, then ResetAuthenticatorKeyAsync creates a new one. Next, you get a URI:

$"otpauth://totp/TwoFaNET10:{email}secret{key}&issuer=TwoFaNET10
&digits=6";

This qrUri can be used by a library or any other QR code generator to create a QR code.

[Authorize]
[HttpPost("2fa/enable")]
public async Task<IActionResult> Enable2FA([FromBody] string code)
{
    var user = await userManager.GetUserAsync(User);

    if (user == null)
        return Unauthorized();

    var result = await userManager.VerifyTwoFactorTokenAsync(
        user,
        TokenOptions.DefaultAuthenticatorProvider,
        code);

    if (!result)
        return BadRequest("Invalid code");

    await userManager.SetTwoFactorEnabledAsync(user, true);

    return Ok(new
    {
        Success = true,
        Message = "2FA enabled"
    });
}

The enable endpoint is responsible for verifying the QR code. After the user scans the QR code, it will take the 6-digit code you got from the authenticator app. VerifyTwoFactorTokenAsync will check that the code is valid, while the SetTwoFactorEnabledAsync method will enable it for the user. Hence, 2FA is now enabled, and on your next login, ASP.NET Core Identity will prompt you for the code.

[HttpPost("2fa/login")]
public async Task<IActionResult> TwoFactorLogin([FromBody] TwoFactorLoginDtoInp model)
{
    if (!ModelState.IsValid)
        return ValidationProblem(ModelState);

    var user = await signInManager.GetTwoFactorAuthenticationUserAsync();

    if (user is null)
        return Unauthorized(new
        {
            Message = "2FA session expired."
        });

    var code = model.TwoFactorCode
        .Replace(" ", "")
        .Replace("-", "");

    var result = await signInManager.TwoFactorAuthenticatorSignInAsync(
        code,
        model.RememberMe,
        model.RememberMachine);

    if (result.Succeeded)
    {
        logger.LogInformation("User {Id} logged in with 2FA.", user.Id);

        return Ok(new
        {
            Success = true,
            Message = "2FA login successful."
        });
    }

    if (result.IsLockedOut)
    {
        return BadRequest(new
        {
            Message = "Account locked out."
        });
    }

    return Unauthorized(new
    {
        Message = "Invalid authenticator code."
    });
}

In the chronology, next is the login method. GetTwoFactorAuthenticationUserAsync will keep the user after verifying the password while waiting for the one-time password (OTP). I kept the OTP code flexible by allowing spaces or '-' before verifying it with TwoFactorAuthenticatorSignInAsync. Identity will verify the incoming code against the stored secret to authenticate the sign-in. The field RememberMe extends the login session, while RememberMachine prevents the need to enter an OTP on the same device next time.

[HttpPost("2fa/recovery-code")]
public async Task<IActionResult> LoginWithRecoveryCode(
    [FromBody] RecoveryCodeLoginDtoInp model)
{
    if (!ModelState.IsValid)
        return ValidationProblem(ModelState);

    var user = await signInManager.GetTwoFactorAuthenticationUserAsync();

    if (user is null)
        return Unauthorized(new
        {
            Message = "2FA session expired."
        });

    var recoveryCode = model.RecoveryCode.Replace(" ", "");

    var result =
        await signInManager.TwoFactorRecoveryCodeSignInAsync(recoveryCode);

    if (result.Succeeded)
    {
        logger.LogInformation(
            "User {Id} logged in with a recovery code.",
            user.Id);

        return Ok(new
        {
            Success = true,
            Message = "Recovery code login successful."
        });
    }

    if (result.IsLockedOut)
    {
        return BadRequest(new
        {
            Message = "Account locked out."
        });
    }

    return Unauthorized(new
    {
        Message = "Invalid recovery code."
    });
}

The final endpoint is an emergency button. It uses a recovery code generated earlier to set up 2FA again in case the authenticator app is unavailable, or the mobile is lost. TwoFactorRecoveryCodeSignInAsync checks whether the recovery code is unused, since it is a one-time recovery option.

Step 6: Inject Identity into the dependencies

In Program.cs add the following code:

builder.Services.AddIdentity<ApplicationUser, IdentityRole>()
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddDefaultTokenProviders();

Step 7: Run migrations

dotnet ef migrations add Initial

To reflect the migration.

dotnet ef database update

Step 8: Run the project

dotnet run

Our Swagger UI is ready.

First, register a user.

Now log in.

If the credentials are wrong.

On multiple invalid attempts, we get.

Two-factor authentication URI.

Still, my user is already logged in. The endpoint is decorated with [Authorize]. I am using an external website to generate the QR code. You can use the QRCoder package in .NET as well, but now let's keep things simple.

I scanned the code in my Microsoft Authenticator app, and the account was added. The one-time password code is visible to me, and I can enable 2FA through the API.

2FA is now enabled. Let's log in again.

You can see the difference: earlier, login was direct without 2FA and immediately returned.

But now we have to use 2FA login.

Passkey authentication in .NET 10

.NET allows passkey implementation for WebAuthn/FIDO compliance. Let's go through it step by step.

Step 1: Install packages

dotnet add package Fido2
dotnet add package Microsoft.AspNetCore.Session

The Fido2 package handles passkey tasks of enabling passkey, Windows Hello, Face ID, and passwordless authentication. While AspNetCore.Session provides session storage for Fido2 challengers.

Step 2: Create models

StoredCredential

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace TwoFaNET10.Models;

public class StoredCredential
{
    public int Id { get; set; }

    [Required]
    public string UserId { get; set; } = string.Empty;

    [Required]
    public byte[] CredentialId { get; set; } = Array.Empty<byte>();

    [Required]
    public byte[] PublicKey { get; set; } = Array.Empty<byte>();

    public uint SignatureCounter { get; set; }

    public string CredType { get; set; } = string.Empty;

    public DateTime RegDate { get; set; } = DateTime.UtcNow;

    public Guid AaGuid { get; set; }

    public byte[] UserHandle { get; set; } = Array.Empty<byte>();

    public string? FriendlyName { get; set; }

    [ForeignKey(nameof(UserId))]
    public ApplicationUser User { get; set; } = null!;
}

It stores a user's passkey information. CredentialId is a unique identifier of the passkey. When a user logs in, the server looks up the incoming credential ID. The Publickey is saved on the server that verifies using the private key saved on the user's device. CredentialType is another important field specifying the type of WebAuthn credential, in our case, it is PublicKey.

CompletePasskeyRegistrationDtoInp

using Fido2NetLib;

namespace TwoFaNET10.Models.Dtos;

public class CompletePasskeyRegistrationDtoInp
{
    public AuthenticatorAttestationRawResponse AttestationResponse { get; set; } = null!;
    public string? FriendlyName { get; set; }
}

PasskeyAssertionRequest

namespace TwoFaNET10.Models.Dtos;

public record PasskeyAssertionRequest(string? Username);

A simple value type was enough here, so I used a record.

Step 3: Add a new table to the context

public DbSet<StoredCredential> StoredCredentials => Set<StoredCredential>();

Step 4: Add Fido2 configurations

Add the following object to appsettings.json.

"Fido2": {
  "ServerDomain": "localhost",
  "ServerName": "TwoFaNET10",
  "Origins": [
    "http://localhost:5220"
  ]
},

And, in Program.cs add the following code.

builder.Services.AddFido2(options =>
{
    options.ServerDomain = builder.Configuration["Fido2:ServerDomain"] ?? "localhost";
    options.ServerName = builder.Configuration["Fido2:ServerName"] ?? "TwoFactorAuth";
    options.Origins = builder.Configuration.GetSection("Fido2:Origins").Get<HashSet<string>>()
                      ?? [];
    options.TimestampDriftTolerance = builder.Configuration.GetValue<int>("Fido2:TimestampDriftTolerance", 300000);
});

Step 5: Add Distributed cache

Passkeys are set in the session cache, so injecting the cache in Program.cs. For production APIs, use an in-memory cache or Redis.

builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
builder.Services.AddHttpContextAccessor();

app.UseSession();

The HTTP context is needed to fetch the logged-in user's session.

Step 6: Define Passkey service

Service interface

using Fido2NetLib;
using TwoFaNET10.Models;

namespace TwoFaNET10.Services;

public interface IPasskeyService
{
    Task<CredentialCreateOptions> GetAttestationOptionsAsync(ApplicationUser user);

    Task<(bool Success, string Error)> MakeCredentialAsync(
        AuthenticatorAttestationRawResponse attestationResponse,
        ApplicationUser user,
        string? friendlyName);

    Task<AssertionOptions> GetAssertionOptionsAsync(string? username);

    Task<(bool Success, string UserId, string Error)> MakeAssertionAsync(
        AuthenticatorAssertionRawResponse assertionResponse);
}

Implementation

using System.Text;
using Fido2NetLib;
using Fido2NetLib.Objects;
using Microsoft.EntityFrameworkCore;
using TwoFaNET10.Data;
using TwoFaNET10.Models;

namespace TwoFaNET10.Services;

public class PasskeyService(
    IFido2 fido2,
    ApplicationDbContext db,
    IHttpContextAccessor httpContextAccessor,
    ILogger<PasskeyService> logger) : IPasskeyService
{
    private const string AttestationKey = "fido2.attestationOptions";
    private const string AssertionKey = "fido2.assertionOptions";
    public async Task<CredentialCreateOptions> GetAttestationOptionsAsync(ApplicationUser user)
    {
        var existingCredentials = await db.StoredCredentials
            .Where(c => c.UserId == user.Id)
            .ToListAsync();

        var excludeCredentials = existingCredentials
            .Select(c => new PublicKeyCredentialDescriptor(c.CredentialId))
            .ToList();

        var fido2User = new Fido2User
        {
            Id = Encoding.UTF8.GetBytes(user.Id),
            Name = user.Email!,
            DisplayName = user.FullName
        };

        var authenticatorSelection = new AuthenticatorSelection
        {
            UserVerification = UserVerificationRequirement.Required,
            ResidentKey = ResidentKeyRequirement.Required,
            RequireResidentKey = true
        };

        var options = fido2.RequestNewCredential(new RequestNewCredentialParams
        {
            User = fido2User,
            AuthenticatorSelection = authenticatorSelection,
            ExcludeCredentials = excludeCredentials,
            AttestationPreference = AttestationConveyancePreference.None
        });

        // DO NOT rely on session in production (still ok for dev)
        Session.SetString(AttestationKey, options.ToJson());

        return options;
    }
    
    public async Task<(bool Success, string Error)> MakeCredentialAsync(
        AuthenticatorAttestationRawResponse attestationResponse,
        ApplicationUser user,
        string? friendlyName)
    {
        try
        {
            var json = Session.GetString(AttestationKey);
            if (string.IsNullOrEmpty(json))
                return (false, "Session expired. Please try again.");

            var options = CredentialCreateOptions.FromJson(json);

            var existingCredIds = await db.StoredCredentials
                .Select(x => x.CredentialId)
                .ToListAsync();

            var credential = await fido2.MakeNewCredentialAsync(new MakeNewCredentialParams
            {
                AttestationResponse = attestationResponse,
                OriginalOptions = options,

                IsCredentialIdUniqueToUserCallback = (args, ct) =>
                {
                    return Task.FromResult(
                        !existingCredIds.Any(id => id.SequenceEqual(args.CredentialId))
                    );
                }
            });

            db.StoredCredentials.Add(new StoredCredential
            {
                UserId = user.Id,
                CredentialId = credential.Id,
                PublicKey = credential.PublicKey,
                SignatureCounter = credential.SignCount,
                CredType = credential.Type.ToString(),
                RegDate = DateTime.UtcNow,
                AaGuid = credential.AaGuid,
                UserHandle = credential.User.Id,
                FriendlyName = string.IsNullOrWhiteSpace(friendlyName)
                    ? "My Passkey"
                    : friendlyName
            });

            await db.SaveChangesAsync();

            return (true, string.Empty);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Error making credential for user {UserId}", user.Id);
            return (false, ex.Message);
        }
    }
    
    public async Task<AssertionOptions> GetAssertionOptionsAsync(string? username)
    {
        var allowedCredentials = new List<PublicKeyCredentialDescriptor>();

        if (!string.IsNullOrWhiteSpace(username))
        {
            var user = await db.Users.FirstOrDefaultAsync(u => u.Email == username);
            if (user is not null)
            {
                var userCredentials = await db.StoredCredentials
                    .Where(c => c.UserId == user.Id)
                    .ToListAsync();

                allowedCredentials = userCredentials
                    .Select(c => new PublicKeyCredentialDescriptor(c.CredentialId))
                    .ToList();
            }
        }
        var assertionOpt = new GetAssertionOptionsParams
        {
            AllowedCredentials = allowedCredentials,
            UserVerification = UserVerificationRequirement.Preferred
        };
        var options = fido2.GetAssertionOptions(assertionOpt);

        Session.SetString(AssertionKey, options.ToJson());
        return options;
    }
    
    public async Task<(bool Success, string UserId, string Error)> MakeAssertionAsync(
        AuthenticatorAssertionRawResponse assertionResponse)
    {
        try
        {
            var json = Session.GetString(AssertionKey);
            if (string.IsNullOrEmpty(json))
                return (false, string.Empty, "Session expired. Please try again.");

            var options = AssertionOptions.FromJson(json);

            var storedCred = await db.StoredCredentials
                .FirstOrDefaultAsync(c => c.CredentialId == assertionResponse.RawId);

            if (storedCred is null)
                return (false, string.Empty, "Passkey not found.");

            var result = await fido2.MakeAssertionAsync(new MakeAssertionParams
            {
                AssertionResponse = assertionResponse,
                OriginalOptions = options,
                StoredPublicKey = storedCred.PublicKey,
                StoredSignatureCounter = storedCred.SignatureCounter,

                IsUserHandleOwnerOfCredentialIdCallback = (args, ct) =>
                {
                    return Task.FromResult(
                        storedCred.UserHandle.SequenceEqual(args.UserHandle)
                    );
                }
            });

            storedCred.SignatureCounter = result.SignCount;
            await db.SaveChangesAsync();

            return (true, storedCred.UserId, string.Empty);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Error verifying passkey assertion");
            return (false, string.Empty, ex.Message);
        }
    }
    
    private ISession Session =>
        httpContextAccessor.HttpContext?.Session
        ?? throw new InvalidOperationException("HttpContext session is not available.");
}

GetAttestationOptionsAsync generates the WebAuthn registration challenge for a logged-in user. The method converts their credential IDs into excludeCredentials after fetching the user's existing passkeys. Then it builds Fido2User from user ID, email, and display name into the format Fido2NetLib needs. Setting UserVerification and ResidentKey to Required will enforce a biometric PIN and enable passwordless login later. fido2.RequestNewCredential builds an CredentialCreateOptions object that is saved in the session and also returned to the API response. The response object contains the Fido user, challenge, timeout milliseconds, and other fields.

MakeCredentialAsync verifies and stores a newly created passkey. First, it gets CredentialCreateOptions from the session. Now it loads all the credential IDs from the database for a uniqueness check. fido2.MakeNewCredentialAsync validates challenges. origin matches, public key, and verifies CredentialId's uniqueness. IsCredentialIdUniqueToUserCallback ensures the credential isn't already registered, though it is very unlikely, Fido2NetLib requires its implementation. Upon success, passkey details such as credential ID, public key, initial sign counter, and AAGUID (which identifies the authenticator model) are saved in the database.

GetAssertionOptionsAsync starts the login process by generating a WebAuthn challenge. If a username is provided, we first retrieve the user's details and allowed credentials. Then the server sends the list of allowed credentials to the browser, which it uses for authentication. If there is no username, the list will be empty, and we will move towards passwordless login. With a username, the server tells the authenticator which credential(s) to use. Without a username, the authenticator lets the user choose a passkey for the website and signs the server's challenge. The server then verifies the signed response using the stored public key.

MakeAssertionAsync verifies the login attempt and identifies the user. It retrieves AssertionOptions from the session and looks up the StoredCredential row by matching CredentialId == assertionResponse.RawId. If no matching credential exists, login fails immediately. fido2.MakeAssertionAsync validates the challenge and origin, verifies the signature using the stored public key, and checks the sign counter for clone detection. IsUserHandleOwnerOfCredentialIdCallback verifies if the credentials belong to the correct user. Finally, after updating the SignatureCounter, I save the changes to the database.

A lambda expression is setting the session from the HTTP context.

Step 7: Add Controller methods

[Authorize]
[HttpPost("passkey/attestation-options")]
public async Task<IActionResult> GetPasskeyAttestationOptions()
{
    var user = await userManager.GetUserAsync(User);

    if (user is null)
        return Unauthorized(new { Success = false, Error = "User not found." });

    var options = await passkeyService.GetAttestationOptionsAsync(user);

    return Ok(options);
}

[Authorize]
[HttpPost("passkey/attestation-verify")]
public async Task<IActionResult> VerifyPasskeyAttestation(
    [FromBody] CompletePasskeyRegistrationDtoInp request)
{
    var user = await userManager.GetUserAsync(User);

    if (user is null)
        return Unauthorized(new { Success = false, Error = "User not found." });

    var (success, error) = await passkeyService.MakeCredentialAsync(
        request.AttestationResponse,
        user,
        request.FriendlyName);

    if (!success)
        return BadRequest(new { Success = false, Error = error });

    return Ok(new
    {
        Success = true,
        Message = "Passkey registered successfully."
    });
}

[HttpPost("passkey/assertion-options")]
public async Task<IActionResult> GetPasskeyAssertionOptions(
    [FromBody] PasskeyAssertionRequest request)
{
    var options = await passkeyService.GetAssertionOptionsAsync(request.Username);
    return Ok(options);
}

[HttpPost("passkey/assertion-verify")]
public async Task<IActionResult> PasskeyAssertionVerify(
    [FromBody] AuthenticatorAssertionRawResponse assertionResponse)
{
    var (success, userId, error) =
        await passkeyService.MakeAssertionAsync(assertionResponse);

    if (!success)
        return BadRequest(new { Success = false, Error = error });

    var user = await userManager.FindByIdAsync(userId);

    if (user is null)
        return NotFound(new { Success = false, Error = "User not found." });

    await signInManager.SignInAsync(user, false);

    return Ok(new { Success = true });
}

attestation-options starts passkey registration. It is an authenticated endpoint. Registering a passkey is an account management action, user must login before adding a new credential to that account. Calls GetAttestationOptionsAsync and returns the options JSON directly to the browser, which feeds it into navigator.credentials.create().

attestation-verify ties the new credential to the currently logged-in user. It calls MakeCredentialAsync with the browser's attestation response, the current user, and an optional friendly name (e.g. "My Phone"). Validates credentials with Fido2, saves it in the database, and returns success or failure. As a result, the passkey is now registered for the user and stored in the database. The device also stores the private key.

assertion-options is the actual passkey login endpoint. The user logs in here; hence, it is unauthenticated. It calls the underlying GetAssertionOptionsAsync method and returns the challenge options to the browser for navigator.credentials.get().

assertion-verify is the final step in the login process. It relies on the service's MakeAssertionAsync method to retrieve the userId and success. After confirming the success in the service layer, it fetches the user and signs them in.

Step 8: Run migrations

dotnet ef migrations add PasskeyInitial

To reflect the migration.

dotnet ef database update

A glance at the database schema.

Step 9: Run the project

dotnet run

Let's run the project again and be unauthorized.

Now the passkey.

navigator.credentials.create() and navigator.credentials.get() are browser WebAuthn APIs, not HTTP calls. Swagger can hit your attestation-options/assertion-options endpoints fine as they're just JSON, but the actual "talk to the authenticator/fingerprint/phone/security key" step only exists in a browser's JS engine, and you cannot trigger that from Swagger's UI or curl.

Run the following in the browser console.

function base64UrlToBase64(input) {
  input = input.replace(/-/g, '+').replace(/_/g, '/');
  const pad = input.length % 4;
  if (pad) input += '='.repeat(4 - pad);
  return input;
}

function bufferToBase64url(buffer) {
  const bytes = new Uint8Array(buffer);
  let str = '';
  for (const b of bytes) str += String.fromCharCode(b);
  return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

// 1. Get attestation options (must be logged in via session/cookie)
const options = await fetch("/api/Account/passkey/attestation-options", {
  method: "POST",
  headers: { "Content-Type": "application/json" }
}).then(r => r.json());

// 2. Convert challenge and user.id to ArrayBuffer
options.challenge = Uint8Array.from(
  atob(base64UrlToBase64(options.challenge)),
  c => c.charCodeAt(0)
);
options.user.id = Uint8Array.from(
  atob(base64UrlToBase64(options.user.id)),
  c => c.charCodeAt(0)
);

if (options.excludeCredentials) {
  options.excludeCredentials = options.excludeCredentials.map(c => ({
    ...c,
    id: Uint8Array.from(atob(base64UrlToBase64(c.id)), c => c.charCodeAt(0))
  }));
}

// 3. Create credential - THIS is what triggers the "create a passkey" prompt
const credential = await navigator.credentials.create({ publicKey: options });

// 4. Build payload and send to attestation-verify
const attestationResponse = {
  id: credential.id,
  rawId: bufferToBase64url(credential.rawId),
  type: credential.type,
  clientExtensionResults: credential.getClientExtensionResults(),
  response: {
    clientDataJSON: bufferToBase64url(credential.response.clientDataJSON),
    attestationObject: bufferToBase64url(credential.response.attestationObject),
    transports: credential.response.getTransports ? credential.response.getTransports() : []
  }
};

const verifyResult = await fetch("/api/Account/passkey/attestation-verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    attestationResponse: attestationResponse,
    friendlyName: "My Phone"
  })
}).then(r => r.json());

console.log(verifyResult);

The script first calls attestation-options with the logged-in user and gets the user details and challenge. The server has stored the challenge and sent it to the browser. For further use, convert the received Base64Url strings to Uint8Array, as WebAuthn APIs expect ArrayBuffer. navigator.credentials.create() cannot work with strings, so we had to go the extra mile. In the said function, the browser inputs the options containing challenge, user, and RP information. The browser calls Windows Hello or Face ID (Windows Hello in our case) to prompt for a passkey. It stores the private key safely and returns a credential object to the browser. Then I created attestationResponse by converting the binary credential data into JSON using bufferToBase64url before sending it to attestation-verify. The server will validate the challenge and return a success or failure message. The user's passkey is registered now.

A Window Hello appeared where I added my passkey.

Now the passkey is saved, and the browser console shows.

Now assertion.

const options = await fetch("/api/Account/passkey/assertion-options", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: "ali@gmaail.com" })
}).then(r => r.json());

options.challenge = Uint8Array.from(atob(base64UrlToBase64(options.challenge)), c => c.charCodeAt(0));
options.allowCredentials = options.allowCredentials.map(c => ({
  ...c,
  id: Uint8Array.from(atob(base64UrlToBase64(c.id)), c => c.charCodeAt(0))
}));

const assertion = await navigator.credentials.get({ publicKey: options });

const assertionResponse = {
  id: assertion.id,
  rawId: bufferToBase64url(assertion.rawId),
  type: assertion.type,
  clientExtensionResults: assertion.getClientExtensionResults(),
  response: {
    clientDataJSON: bufferToBase64url(assertion.response.clientDataJSON),
    authenticatorData: bufferToBase64url(assertion.response.authenticatorData),
    signature: bufferToBase64url(assertion.response.signature),
    userHandle: assertion.response.userHandle ? bufferToBase64url(assertion.response.userHandle) : null
  }
};

const verifyResult = await fetch("/api/Account/passkey/assertion-verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(assertionResponse)
}).then(r => r.json());

console.log(verifyResult);

assertion-options will do its job of loading the user's passkeys from StoredCredentials and stores a newly generated challenge in the session. The browser gets an object containing the challenge and allowed credentials. Similar to the earlier script, convert the received data into binary in the input of navigator.credentials.get that is responsible for getting PIN, passkey, or touch finger sensor from user prompt. Windows Hello finds the credential specified in allowCredentials verifies user input, retrieves the private key, and signs the challenge. Note that the private key never leaves Windows Hello and is used to sign the challenge. assertionResponse is prepared and passed as a parameter in assertion-verify by which the server verifies the signature using the public key and user data. Finally, it creates an authentication cookie, and the user is now logged in.

Once the passkey was inserted, the follow appeared in the console.

Now our authorized endpoint will reply with a success.

Conclusion

The advent of 2FA and passkeys significantly improves both security and user experience. Both play a brilliant role in reducing password vulnerabilities in modern applications. .NET provides extensive support for integrating these security measures into projects. In this post, I discussed 2FA and passkeys, followed by a step-by-step implementation in an ASP.NET Core API.

Code: https://github.com/elmahio-blog/TwoFaNET10

Imagine a bug suddenly arises in the frontend from an endpoint. The endpoint has multiple layers and involves dozens of files. Now, you are tasked to resolve that bug, those piles of code make it difficult to pinpoint the cause of the error. Some exceptions, like 'Object reference not set to an instance of an object" are vague and hard to detect. You need a detailed log of API operations to identify the exact code and reason for the error. Serilog is one fine choice for logging that we will use to implement file logging in ASP .NET Core API.

Why use Serilog?

Serilog is a powerful logging library for .NET applications. It generates structured logs that are both human- and machine-readable, and you can easily filter and query them. Besides, it provides an array of sink options, including Console, File, SQL, Elasticsearch, and elmah.io.

Implementing Serilog file logging in ASP .NET Core API

I will start with a basic ASP.NET 10 API with simple logging code. Later, I will try to cover important use cases for real-world applications.

Step 1: Create an API project

dotnet new web -n SerilogFileLog 

Step 2: Install required packages

dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.File

They are Serilog packages, and later on, logs will be written to files.

I am fond of Swagger, but .NET 10 does not provide Swagger Ui by default, hence I am using the package. To keep the work similar to the readers, I will use Swagger, as most developers are already familiar with it.

dotnet add package Swashbuckle.AspNetCore 

Step 3: Define Controller

using Microsoft.AspNetCore.Mvc;

namespace SerilogFileLog.Controllers;

[ApiController]
[Route("api/[controller]")]
public class WeatherController : ControllerBase
{
    private readonly ILogger<WeatherController> _logger;

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

    [HttpGet]
    public IActionResult Get()
    {
        _logger.LogInformation("Weather endpoint called");

        return Ok("Hello Serilog");
    }
}

The controller is simple, so we can focus on our main topic for now. ILogger object _logger is responsible for writing messages to logs. A naive way would be Log.Information("Weather endpoint called");using Serilog's global logger, which does not require injection. However, it does not give the context of the class where the error originates. Injecting a logger in classes is recommended for production environments.

Step 4: Configure Program.cs

using Serilog;
var builder = WebApplication.CreateBuilder(args);

Log.Logger = new LoggerConfiguration()
    .WriteTo.File("logs/log.txt")
    .CreateLogger();

builder.Host.UseSerilog();

builder.Services.AddOpenApi();

// Services
builder.Services.AddControllers();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUI(options =>
        {
            options.SwaggerEndpoint("/openapi/v1.json", "v1");
        }
    );
}

app.UseHttpsRedirection();

app.MapControllers();
app.Run();

So, I am adding a file logs/log.txt for the log, followed by builder.Host.UseSerilog(); injecting Serilog. I used app.UseSwaggerUI for Swagger UI here.

Step 5: run the project

dotnet run

Result

A new log is created in the solution explorer.

Rolling day logs

A good practice in logging is to keep daily logs in a separate file. Serilog allows us to do so. Just change the logging snippet.

Log.Logger = new LoggerConfiguration()
    .WriteTo.File(
        "logs/log-.txt",
        rollingInterval: RollingInterval.Day
        )
    .CreateLogger();

A new daily file will be created.

Logging configurations from appsettings.json

Let's move to a production-level example. I will add the log details in appsettings.

{
  "Serilog": {
    "MinimumLevel": "Information",
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "logs/log-.log",
          "rollingInterval": "Day"
        }
      }
    ]
  },
 //Other appsetting fields
}

MinimumLevel controls the lowest log level that will be written. Also, I moved the rolling interval here. Other options for rolling are

• Minute
• Hour
• Day 
• Month
• Year
• Infinite

and a slight change in the code.

Log.Logger = new LoggerConfiguration()
    .ReadFrom.Configuration(builder.Configuration)
    .CreateLogger();

Levels of Serilog logs

Serilog defines logs in different severity levels as follows, from lowest to highest

Verbose: Detailed diagnostic logs
Debug: Developer troubleshooting information
Information: Normal application events
Warning: Potential issue detected
Error: Operation failed unexpectedly
Fatal: Application cannot continue

By setting MinimalLevel to Information, we will ignore Verbose and Debug messages and will keep the higher ones.

Our new log file is.

And its content.

Why .log is recommended over .txt?

Log is an industry standard for application logs, and it is easy to identify log files. Many log viewers and monitoring tools automatically recognize .log.

Logging on Errors

Now, define a method in the controller that may throw an error.

[HttpGet("GetDivision")]
    public IActionResult GetDivision(int number)
    {
        try
        {
            _logger.LogInformation("GetDivision endpoint called with number: {Number}", number);

            int result = 10 / number;

            _logger.LogInformation(
                "Division completed successfully. Result: {Result}",
                result);

            return Ok(new
            {
                Success = true,
                Result = result
            });
        }
        catch (Exception ex)
        {
            _logger.LogError(
                ex,
                "An error occurred in GetDivision. Input Number: {Number}",
                number);

            return StatusCode(StatusCodes.Status500InternalServerError, new
            {
                Success = false,
                Message = ex.Message
            });
        }
    }

LogError in the catch block will write as an error message.

Erroneous condition.

Well, let's check the logs now.

Or the complete message is.

2026-06-06 18:30:39.729 +05:00 [ERR] An error occurred in GetDivision. Input Number: 0
System.DivideByZeroException: Attempted to divide by zero.
   at SerilogFileLog.Controllers.WeatherController.GetDivision(Int32 number) in D:\Elmah.io\SerilogFileLog\SerilogFileLog\Controllers\WeatherController.cs:line 30

We can get the exact line number along with the error description.

Add Enrichers and Output templates.

Serilog allows capturing metadata, such as the requester's device and username. For that, use the package.

dotnet add package Serilog.Enrichers.Environment                                    

There are two ways to include metadata in the logs, Either you can define in the appsettings.json will include an Enrich object and a template that defines the log message.

{
  "Serilog": {
    "MinimumLevel": "Information",
    "Enrich": [
      "WithMachineName",
      "WithEnvironmentUserName",
      "FromLogContext"
    ],
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "logs/log-.log",
          "outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {MachineName} {EnvironmentUserName} {Message:lj}{NewLine}{Exception}",
          "rollingInterval": "Day"
        }
      }
    ]
  },
  //Other
}

Or allowing the enrichment in the code.

Log.Logger = new LoggerConfiguration()
    .ReadFrom.Configuration(builder.Configuration)
    .Enrich.WithMachineName()
    .Enrich.WithEnvironmentUserName()
    .Enrich.FromLogContext()
        .CreateLogger();

Finally, it looks like.

My PC and user name are added to the logs.

Logging Application Startup Events

Apart from operations errors, you can leverage Serilog's static methods to log errors that arise during startup. As there is no dependency when the application starts, you may not get the idea what happened, then comes the following.

using Serilog;

var builder = WebApplication.CreateBuilder(args);

// Configure and Enrich
Log.Logger = new LoggerConfiguration()
    .ReadFrom.Configuration(builder.Configuration)
    .Enrich.WithMachineName()
    .Enrich.WithEnvironmentUserName()
    .Enrich.FromLogContext()
        .CreateLogger();

try
{
    Log.Information("Starting up!");
    
    builder.Host.UseSerilog();
    
    builder.Services.AddOpenApi();
    
    // Services
    builder.Services.AddControllers();
    
    var app = builder.Build();
    
    // Configure the HTTP request pipeline.
    if (app.Environment.IsDevelopment())
    {
        app.MapOpenApi();
        app.UseSwaggerUI(options =>
            {
                options.SwaggerEndpoint("/openapi/v1.json", "v1");
            }
        );
    }
    
    app.UseHttpsRedirection();
    throw new Exception("a startup error");
    app.MapControllers();
    app.Run();
    Log.Information("Stopped cleanly");
    return 0;
}
catch (Exception ex)
{
    Log.Fatal(ex, "An unhandled exception occurred during startup");
    return 1;
}
finally
{
    Log.CloseAndFlush();
}

The CloseAndFlush method writes any pending log entries and releases resources by the Serilog. It is recommended to use the method to not to loose last logs before the application shuts down or crashes. I manually threw an error in between.

Conclusion

Logging is important for debugging an application and ensuring a seamless experience. Also, you can use logs to make critical business decisions. Today, I shared how to use Serilog file logging in .NET APIs. I began with basic file logging, progressed to scenarios of real applications, including daily rolling logs, and moved all configuration to appsettings.json standard practices. Additionally, I highlighted enrichers like WithMachineName() and WithEnvironmentUserName() to automatically attach valuable metadata to every log entry.

While file logging is perfect for testing Serilog locally, text files often aren't ideal in production. For live apps, streaming Serilog events to a cloud-based system like elmah.io centralizes your logs and provides real-time alerts before bugs impact your users.

Code: https://github.com/elmahio-blog/SerilogFileLog.git

EF Core (Entity Framework Core) is a fast ORM. However, once dataset entries increase by another 0, things start to break down. Fetching and filtering of data adds to processing time. Looking at this pitfall, I came up with a few EF Core methods that are specifically designed to work with bulk data. With 5 extension methods in EF Core, I will show how novelty can meet performance and clean code goals.

Why use other methods than EF Core's .Contains?

EF Core provides .Contains a method for filtering and retrieval. However, it brings some issues. Firstly, only 2,100 parameters can be passed. What to do when you need to filter a large number of parameters? Splitting the query is one option here, but splitting queries into batches in SQL can be problematic in some complex situations. Also, it is not recommended to filter a single table with multiple database round-trips, as it consumes more memory and keeps database connections open longer. Hence, you will need a single way to fulfil the task. All the methods we will discuss today were aimed at solving these shortcomings.

Implementation of EF Core methods for large data retrieval

To showcase each method, I will use a console application that connects to a PostgreSQL database containing up to 1 million records. Each method is suitable in its own arena.

Step 1: Create the project

dotnet new console -n EfCoreBulkFetchBenchmark
cd EfCoreBulkFetchBenchmark

Step 2: Install required packages

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Z.EntityFramework.Extensions.EFCore
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Json

All the 5 methods are extensions of EF Core provided by the library Z.EntityFramework.Extensions.EFCore.

Step 3: Create appsettings.json

Adding appsettings.json with a database connection string.

{
  "ConnectionStrings": {
    "PostgresConnection": "Host=localhost;Port=5432;Database=shopDb;Username=postgres;Password=1234"
  }
}

To add appsettings.json to the project, we need to specify it in .proj

<ItemGroup>
    <None Update="appsettings.json">
        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
</ItemGroup>

Step 4: Create models

Customer

namespace EfCoreBulkFetchBenchmark.Models;

public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Country { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
    public ICollection<Order> Orders {get;set;} = null!;
}

Order

namespace EfCoreBulkFetchBenchmark.Models;

public class Order
{
    public int Id { get; set; }
    public int? CustomerId { get; set; }
    public decimal Amount { get; set; }
    public string Status { get; set; }
    public DateTime CreatedAt { get; set; }
    public Customer Customer { get; set; }
}

Step 5: Configure ApplicationDbContext

using EfCoreBulkFetchBenchmark.Models;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;

namespace EfCoreBulkFetchBenchmark.Data;

public class ApplicationDbContext: DbContext
{
    public DbSet<Order> Orders => Set<Order>();
    public DbSet<Customer> Customers => Set<Customer>();

    private readonly string _connectionString;

    public ApplicationDbContext()
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json")
            .Build();

        _connectionString = config.GetConnectionString("PostgresConnection");
    }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseNpgsql(_connectionString);
    }
}

Here, I am getting the connection string from the appsettings.json

Step 6: Run migrations

dotnet ef migrations add InitialCreate

To reflect the migration

dotnet ef database update

Step 7: Seed data

In a separate file, I have added code to insert a considerable amount of data

using EfCoreBulkFetchBenchmark.Models;

namespace EfCoreBulkFetchBenchmark.Data;

public class SeedData
{
    public static async Task Initialize(ApplicationDbContext context)
    {
        if (context.Orders.Any()) return;

        var random = new Random();
        var countries = new[] { "USA", "UK", "France", "Germany", "Pakistan" };
    
        var customers = Enumerable.Range(1, 100000)
            .Select(i => new Customer
            {
                Name = $"Customer {i}",
                Country = countries[random.Next(countries.Length)],
                CreatedAt = DateTime.UtcNow.AddDays(-random.Next(365)) // Added random creation date
            }).ToList();

        context.Customers.AddRange(customers);
        await context.SaveChangesAsync();

        var orders = new List<Order>();
        var rand = new Random();

        for (int i = 1; i <= 1_000_000; i++)
        {
            orders.Add(new Order
            {
                CustomerId = customers[rand.Next(customers.Count)].Id,
                Amount = rand.Next(100, 10000),
                Status = i % 2 == 0 ? "Completed" : "Pending",
                CreatedAt = DateTime.UtcNow.AddDays(-rand.Next(100))
            });
        }

        context.Orders.AddRange(orders);
        await context.SaveChangesAsync();
    }
}

In Program.cs

using EfCoreBulkFetchBenchmark.Data;
using EfCoreBulkFetchBenchmark.Models;
using Microsoft.EntityFrameworkCore;

var context = new ApplicationDbContext();

await context.Database.EnsureCreatedAsync();

await SeedData.Initialize(context);

Step 8: Implement advanced EF Core methods

Our database and code are ready, now we can see 5 ways to fetch data with a large dataset.

var orderIds = await context.Orders
    .OrderBy(x => x.Id)
    .Take(50000)
    .Select(x => x.Id)
    .ToListAsync();

// SMALL list for naive test (safe)
var smallOrderIds = await context.Orders
    .OrderBy(x => x.Id)
    .Take(2000)
    .Select(x => x.Id)
    .ToListAsync();

To filter, I initialized some IDs. The first sample is large, while the smallOrderIds will be used in a naive approach where EF Core does not allow a large number of parameters.

The naive way using .Contains will be

var result = await context.Orders
    .Where(x => smallOrderIds.Contains(x.Id))
    .ToListAsync();

Console.WriteLine($"Total records : {result.Count}");

WhereBulkContains

var result2 = await context.Orders
    .WhereBulkContains(orderIds, x => x.Id)
    .ToListAsync();

Console.WriteLine($"Total records : {result2.Count}");

WhereBulkContains takes a list as a parameter and filters records based on all items in the input list.

The first parameter is the collection of values to filter, and the second parameter is a lambda expression that specifies the property to match. In our case, it is the ID of the orders as specified in the lambda expression.

We can do the same thing without a lambda expression. The method will by default filter over the primary key field

result2 = await context.Orders
    .WhereBulkContains(orderIds)
    .ToListAsync();

You can filter in a one-to-one relationship with .Include as well like this

result2 = await context.Orders
.Include(x => x.Customer)
    .WhereBulkContains(x=>
        x.Customer,  
        new List<string>()
        {
            "Pakistan",
            "France"
        },
        x => x.Name
    )
    .ToListAsync();

The filter now populates customers' data along with the orders. However, all orders are fetched, as there is no filter on orders, while only customers' data will be included whose countries match the given list.

For a one-to-many relation

var customers = await context.Customers
    .Include(x => x.Orders)
    .WhereBulkContains(x=>
            x.Orders,  
        smallOrderIds,
        x => x.Id
    )
    .ToListAsync();

WhereBulkContains returns IQueryable<T>, which can be further chained with LINQ methods like Where and Select, or materialized with ToListAsync. Best suited for filtering by multiple values.

WhereBulkContains supports basic types like int, string or guid not complex or composite types as the list parameters.

WhereBulkNotContains 

var result3 = await context.Orders
    .WhereBulkNotContains(orderIds, x => x.Id)
    .ToListAsync();

Console.WriteLine($"Total records : {result3.Count}");

You can think of an inverted method of WhereBulkContains. WhereBulkNotContains filters data that excludes the parameter list.

The result excluded all 2000 records that matched the input list. The same thing can be achieved by

result3 = await context.Orders
    .WhereBulkNotContains(orderIds)
    .ToListAsync();

Unlike its inverse partner, input params allows any list type, including basic, entity, anonymous, and expando types. Also, it allows a one-to-many relation

result3 = await context.Orders
    .Include(x => x.Customer)
    .WhereBulkNotContains(x=>
            x.Customer,  
        new List<string>()
        {
            "Pakistan",
            "France"
        },
        x => x.Name
    )
    .ToListAsync();

While for one-to-many

var customers = await context.Customers
    .Include(x => x.Orders)
    .WhereBulkNotContains(x=>
            x.Orders,  
        smallOrderIds,
        x => x.Id
    )
    .ToListAsync();

BulkRead 

var inputOrders = orderIds
    .Select(id => new Order { Id = id }).ToList();
    
var result4 = await context.Orders
    .BulkReadAsync(inputOrders, x=>x.Id);

Console.WriteLine($"Total records : {result4.Count}");

BulkRead returns data that matches the given list. You can pass a list of any type as input and specify the column for filtering as a lambda expression. The final result is immediately returned. Think of it as WhereBulkContains but with immediate execution internally using  ToList or ToListAsync method.

Similarly, we can take the default behaviour of using the primary key for filtering

var result4 = await context.Orders
    .BulkReadAsync(inputOrders);

WhereBulkContainsFilterList 

var result5 = context.Orders
    .WhereBulkContainsFilterList(smallOrderIds, x => x.Id)
    .ToList();
    
Console.WriteLine($"Total records : {result5.Count}");

It returns items from the list that already exist in the database. It filters just like WhereBulkContains, but it filters out items in the input list rather than the database.

We filtered over 2000 IDs, and they are available in the database, so it simply returned all of them

result5 = context.Orders
    .WhereBulkContainsFilterList(smallOrderIds)
    .ToList();

A useful application of this method is when we need to filter an input list while updating.

WhereBulkNotContainsFilterList 

var result6 = context.Orders
    .WhereBulkNotContainsFilterList(
            new List<int>()
            {
                10000,
                100000,
                1000001,
                1000002,
                1000003
            }
        , x => x.Id)
    .ToList();
Console.WriteLine($"Total records : {result6.Count}");

WhereBulkNotContainsFilterList is the inverse of WhereBulkContainsFilterList, which returns items of the input list that do not exist in the table.

The table contains 1 million data and 3 items in the input Ids list did not match any of those IDs. A concise version using ids by default is

result6 = context.Orders
    .WhereBulkNotContainsFilterList(
        new List<int>()
        {
            10000,
            100000,
            1000001,
            1000002,
            1000003
        }
        )
    .ToList();

WhereBulkNotContainsFilterList has a key difference with WhereBulkNotContains where the prior one returns a filtered record from the input list, while the latter one returns filtered records from the database. While for the input list parameter, all types are allowed.

Conclusion

We discovered 5 EF Core methods for data retrieval with their implementation on a real dataset. WhereBulkContains, WhereBulkNotContains BulkRead, WhereBulkContainsFilterList, WhereBulkNotContainsFilterList each are designed to handle fetching and filtering large data. Their generated queries perform the job efficiently, while spanning a few readable lines, making the efficiency easy to read. Z.EntityFramework.Extensions.EFCore offers a trial version for a limited time that can be extended with their plans.

Code: https://github.com/elmahio-blog/EfCoreBulkFetchBenchmark

Scaling horizontally is great… until the bill comes. Hence, as a startup or a big firm, you always need to be careful about billing while maintaining competitiveness. Every user who lands on your application needs high throughput. In today's post, I will share ways to revolutionize the performance of your .NET application. We will observe the benchmark after applying those techniques to the response time.

High-throughput .NET API implementation

For the rest of this post, I'll use an ASP.NET Core Minimal API and measure performance using BenchmarkDotNet. Let's get started.

Step 1: Create the solution

dotnet new sln -n OrdersPerformanceDemo
cd OrdersPerformanceDemo

Step 2: Add projects to the solution

dotnet new web -n Orders.Api
dotnet new console -n Orders.Benchmark

dotnet sln add Orders.Api
dotnet sln add Orders.Benchmark

Step 3: Install packages

cd Orders.Api

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add package Dapper
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Microsoft.Extensions.Configuration.FileExtensions

Also, in the benchmark project, we will add the required packages:

cd ../Orders.Benchmark

dotnet add package BenchmarkDotNet
dotnet add package Npgsql
dotnet add package Dapper
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

Step 4: Add Appsettings

In the appsettings.json file add a connection string:

"ConnectionStrings": {
  "PostgresConnection": "Host=localhost;Port=5433;Database=shopDb;Username=postgres;Password=1234"
}

And similarly, in Program.cs of the API project, include the following code:

var connectionString = builder.Configuration.GetConnectionString("PostgresConnection");

builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(connectionString));

builder.Services.AddScoped<NpgsqlConnection>(_ =>
    new NpgsqlConnection(connectionString));

Step 5: Add models

Customer model.

namespace Orders.Api.Models;

public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Country { get; set; }
}

Order model.

namespace Orders.Api.Models;

public class Order
{
    public int Id { get; set; }
    public int? CustomerId { get; set; }
    public decimal Amount { get; set; }
    public string Status { get; set; }
    public DateTime CreatedAt { get; set; }

    public Customer Customer { get; set; }
}

Step 6: Set up the DB context

using Microsoft.EntityFrameworkCore;
using Orders.Api.Models;

namespace Orders.Api.Data;

public class ApplicationDbContext: DbContext
{
    public DbSet<Order> Orders => Set<Order>();
    public DbSet<Customer> Customers => Set<Customer>();

    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options) { }
}

Step 7: Run migrations

dotnet ef migrations add InitialCreate

And reflect on it.

dotnet ef database update

I already seeded a few thousand rows of data in the table.

Step 8: Add naive API

app.MapGet("/orders/naive", async (ApplicationDbContext db) =>
{
    var data = await db.Orders
        .Include(o => o.Customer)
        .Take(50000)
        .ToListAsync();

    return Results.Ok(data);
});

This is one of the simplest and least efficient ways of fetching data as a worst-case threshold. Well, to save the huge pressure of a million records on the system and to save time, I took 50000 records.

Step 9: Create a dapper endpoint

app.MapGet("/orders/dapper", async (
    int? customerId,
    int page,
    int pageSize,
    NpgsqlConnection conn) =>
{
    var sql = @"
        SELECT o.""Id"", o.""Amount"", o.""CreatedAt"", c.""Name""
        FROM ""Orders"" o
        JOIN ""Customers"" c ON o.""CustomerId"" = c.""Id""
        WHERE o.""Status"" = 'Completed'
        AND (@customerId IS NULL OR o.""CustomerId"" = @customerId)
        ORDER BY o.""CreatedAt"" DESC
        LIMIT @pageSize OFFSET @offset";

    var result = await conn.QueryAsync(sql, new
    {
        customerId,
        pageSize,
        offset = (page - 1) * pageSize
    });

    return Results.Ok(result);
});

Now, we are ready to start implementing optimizations.

Database indexing

CREATE INDEX IF NOT EXISTS idx_completed_orders
    ON public."Orders" USING btree
    ("CustomerId" ASC NULLS LAST)
    TABLESPACE pg_default
    WHERE "Status" = 'Completed'::text;

At the time of fetching, use the index to filter fast.

var query = db.Orders
    .AsNoTracking() 
    .Where(o => o.Status == "Completed");

Use pagination

Pagination is a win-win situation in database fetching. In most cases, APIs do not need to return large amounts of data in the response. Rather, there is a limit, usually 20 to 100, that mobile and web applications can display at once. Leverage this fact and add pagination to the fetches, significantly reducing the performance penalties. You only get what you need and do not burden yourself with extra.

var result = await query
    .OrderByDescending(o => o.CreatedAt)
    .Skip((page - 1) * pageSize)
    .Take(pageSize)
    .Select(o => new 
    {
        o.Id,
        o.Amount,
        o.CreatedAt,
        CustomerName = o.Customer.Name
    })
    .ToListAsync();

Add Pagination Limits

To prevent users from fetching large amounts of data at once, add a pagesize limit. When you are sure about the API's use cases.

pageSize = Math.Min(pageSize, 100);

Use Dapper for Hot Endpoints Only

app.MapGet("/orders/dapper", async (
    int? customerId,
    int page,
    int pageSize,
    NpgsqlConnection conn) =>
{
    var sql = @"
        SELECT o.""Id"", o.""Amount"", o.""CreatedAt"", c.""Name""
        FROM ""Orders"" o
        JOIN ""Customers"" c ON o.""CustomerId"" = c.""Id""
        WHERE o.""Status"" = 'Completed'
        AND (@customerId IS NULL OR o.""CustomerId"" = @customerId)
        ORDER BY o.""CreatedAt"" DESC
        LIMIT @pageSize OFFSET @offset";

    var result = await conn.QueryAsync(sql, new
    {
        customerId,
        pageSize,
        offset = (page - 1) * pageSize
    });

    return Results.Ok(result);
});

Dapper uses a query that is less abstracted than EF Core. This offers a performance edge, and you can use Dapper for high traffic operations.

Response Compression

builder.Services.AddResponseCompression();

app.UseResponseCompression();

It compresses server responses before sending them to clients, reducing bandwidth usage and improving load times.

Avoid Over-Fetching

EF Core entities contain several navigation properties to other entities. In real cases, a single entity has a cluster of dependent entities, such as a User that has navigation with userRoles, languages, and approvals. Loading all of them can be a serious drain on memory and processing power. We have customers and an order table. However, if we need order data, then no need to involve other tables with code like this: .Include(o => o.Customer). If you need to send OrderId and Status over the API, then avoid including the customer unnecessarily.

No tracking for faster reads with EF Core

var query = db.Orders
    .AsNoTracking() 
    .Where(o => o.Status == "Completed");

EF Core tracks fetched data for change tracking. To remove this behavior, use AsNoTracking when you only fetch data and don't need to modify it.

Projection to reduce response fields

Reduce the fetched field to only the required ones. Fetching and sending unnecessary fields costs CPU time and network bandwidth. Use projection to get what you need.

var result = await query
    .OrderByDescending(o => o.CreatedAt) 
    .Skip((page - 1) * pageSize)
    .Take(pageSize)
    .Select(o => new 
    {
        o.Id,
        o.Amount,
        o.CreatedAt,
        CustomerName = o.Customer.Name
    })
    .ToListAsync();

Cache for frequently accessed data

Cache is another breakthrough in our journey. Caching frequently accessed data in memory reduces database round-trip. I will show two types of caching.

Output Cache

Output caching stores the whole web response in memory, the serialized JSON, headers, and status code next time you request the route with the same parameters. AddOutputCache registers output caching services in the DI container. UseOutputCache inserts the output-caching middleware into the request-processing pipeline. When a request comes in, this middleware intercepts it, checks if a valid cached response exists, and if so, returns it immediately. That way, the output caching reduces the whole cycle of hitting the database and serializing the response. In the program.cs inject the service.

builder.Services.AddOutputCache();

app.UseOutputCache();

The endpoint now looks like this:

app.MapGet("/orders/optimized_output", async (
    int? customerId,
    int page,
    int pageSize,
    ApplicationDbContext db,
    IMemoryCache cache) =>
{
    // Technique: Limit page size (protect API)
    pageSize = Math.Min(pageSize, 100);

    var query = db.Orders
        .AsNoTracking() // Technique: No tracking (faster reads)
        .Where(o => o.Status == "Completed"); //Technique: Uses partial index

    if (customerId.HasValue)
        query = query.Where(o => o.CustomerId == customerId); // Technique: Uses index

    var result = await query
        .OrderByDescending(o => o.CreatedAt) //Technique: Sorting (optimize via index)
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .Select(o => new // Technique: Projection (avoid over-fetching)
        {
            o.Id,
            o.Amount,
            o.CreatedAt,
            CustomerName = o.Customer.Name
        })
        .ToListAsync();

    return Results.Ok(result);
})
.CacheOutput(p => 
    p.Expire(TimeSpan.FromSeconds(600))); // Technique: Output caching

.CacheOutput contains a lambda expression that specifies the time to retain cached data.

In-memory cache

In most cases, output caching should be sufficient. But sometimes, you may want to look into creating manual, private caches in your code.

To start creating a cache, import the following namespace in the Program.cs file:

using Microsoft.Extensions.Caching.Memory;

Inject caching:

builder.Services.AddMemoryCache();

In our endpoint method, you inject a IMemoryCache object and set the cache key:

var cacheKey = $"orders:{customerId}:{page}:{pageSize}";

upon every request. First, we check if the required data is in the in-memory cache. If found, we return it without going to the database.

if (cache.TryGetValue(cacheKey, out List<object> cached))
    return Results.Ok(cached);

Otherwise, set the fetched result in cache.

cache.Set(cacheKey, result, TimeSpan.FromSeconds(30));

The endpoint now looks like this:

app.MapGet("/orders/optimized_inmemory", async (
    int? customerId,
    int page,
    int pageSize,
    ApplicationDbContext db,
    IMemoryCache cache) =>
{
    // Technique: Limit page size (protect API)
    pageSize = Math.Min(pageSize, 100);

    // Technique: Cache key
    var cacheKey = $"orders:{customerId}:{page}:{pageSize}";

    // Technique: Memory cache (ultra fast)
    if (cache.TryGetValue(cacheKey, out List<object> cached))
        return Results.Ok(cached);

    var query = db.Orders
        .AsNoTracking() // Technique: No tracking (faster reads)
        .Where(o => o.Status == "Completed"); //Technique: Uses partial index

    if (customerId.HasValue)
        query = query.Where(o => o.CustomerId == customerId); //Technique: Uses index

    var result = await query
        .OrderByDescending(o => o.CreatedAt) //Technique: Sorting (optimize via index)
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .Select(o => new // Technique: Projection (avoid over-fetching)
        {
            o.Id,
            o.Amount,
            o.CreatedAt,
            CustomerName = o.Customer.Name
        })
        .ToListAsync();

    // Technique : Cache result
    cache.Set(cacheKey, result, TimeSpan.FromSeconds(600));

    return Results.Ok(result);
});

Although I have used both output and memory caches in the app, the output cache is better suited to APIs, dashboards, and repetitive data. In-memory is optimal for expensive calculations, permissions, and non-HTTP scenarios.

Know the caching strategy in detail to better utilize it according to your application.

Step 10: Set up code in the Benchmark project

using BenchmarkDotNet.Attributes;
using Microsoft.EntityFrameworkCore;
using Dapper;
using Microsoft.Extensions.Configuration;
using Npgsql;
using Orders.Api.Data;
using Orders.Benchmark.Config;

namespace Orders.Benchmark;

[MemoryDiagnoser]
public class OrdersBenchmark
{
    private HttpClient _client;
    private string _baseUrl;

    [GlobalSetup]
    public void Setup()
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json")
            .Build();

        _baseUrl = "http://localhost:5102";

        _client = new HttpClient
        {
            BaseAddress = new Uri(_baseUrl)
        };
    }

    [Benchmark]
    public async Task Naive()
    {
        var response = await _client.GetAsync("/orders/naive");
        response.EnsureSuccessStatusCode();

        var data = await response.Content.ReadAsStringAsync();
    }

    [Benchmark]
    public async Task OptimizedInmemory()
    {
        var response = await _client.GetAsync("/orders/optimized_inmemory?page=1&pageSize=50&customerId=223");
        response.EnsureSuccessStatusCode();

        var data = await response.Content.ReadAsStringAsync();
    }

    [Benchmark]
    public async Task OptimizedOutput()
    {
        var response = await _client.GetAsync("/orders/optimized_output?page=1&pageSize=50&customerId=223");
        response.EnsureSuccessStatusCode();

        var data = await response.Content.ReadAsStringAsync();
    }

    [Benchmark]
    public async Task Dapper()
    {
        var response = await _client.GetAsync("/orders/dapper?page=1&pageSize=50");
        response.EnsureSuccessStatusCode();

        var data = await response.Content.ReadAsStringAsync();
    }
}

We are setting up the client for the API project. Later, defined methods for each API endpoint.

Step 11: Call the benchmark in the Program.cs

using BenchmarkDotNet.Running;
using Orders.Benchmark;

BenchmarkRunner.Run<OrdersBenchmark>();

Step 12: Run and test

One by one, running the project in different terminals.

cd Orders.Api
dotnet run

And the benchmark in the release mode.

cd Orders.Benchmark
dotnet run -c Release

Result

Running again to check caching.

The results speak about output caching performance in both cases. After accessing cached data, the results are even faster.

External factors to achieve High-Throughput API

The greatest soldier with a weak sword cannot stand in the battle. Similarly, a very good code cannot perform well if it is not hosted properly. To achieve high throughput, you need to take care of the following external factors.

Choosing the Right infrastructure and hosting

When hosting your application, choose the right server with a few things in mind. Go with an option that offers more parallel request handling, high-performing RAM, and a location close to your users' geographic area. If your code takes 30 ms for the job but the server responds in 200 ms due to the user's geographic distance, it will be counted as slow. Besides, SSDs are faster than HDDs, so choose accordingly. High-speed storage has a significant impact on the request-response cycle.

Using a reverse Proxy / Load balancer

Load balancing is necessary for scalable systems. Never expose the API directly; instead, use HAProxy and NGINX for load balancing, SSL termination, and request buffering.

Background Processing

Tasks such as analytics, email, and logging should be separate from main API calls to avoid blocking the request-response pipeline.

Rate limit API

Rate limiting is a performance and precautionary measure that limits a single user or tenant from overusing or abusing the application. Overuse can spike the server, slowing APIs for other users. With .NET 10, rate limiting is even improved.

Conclusion

Every system needs to achieve optimal performance. In this regard, I shared a few important techniques that a .NET API can use to achieve high throughput. However, testing with 1 million requests is difficult on a personal computer. However, we observed remarkable success with all the tactics, and you can improve the application by following them as well. I also discuss external factors that contribute to user experience and system response time.

Code: https://github.com/elmahio-blog/OrdersPerformanceDemo.git

Files are an integrated part of an application. From a social app to an ERP, some form of media exists in the ecosystem. .NET Core APIs provide built-in support for uploading and fetching documents. In today's post, I will show you how to cleanly and efficiently use .NET Core's file system classes to receive file uploads.

Uploading files in ASP.NET Core API

I am creating an API with .NET 10 to accomplish our goal.

Step 1: Create a project

dotnet new webapi -n fileUploadDemo
cd fileUploadDemo

Step 2: Create a controller

using Microsoft.AspNetCore.Mvc;

namespace fileUploadDemo.Controllers;

[ApiController]
[Route("api/[controller]")]
public class FileController: ControllerBase
{
    [HttpPost("upload")]
    public async Task<IActionResult> Upload(IFormFile file)
    {
        if (file == null || file.Length == 0)
            return BadRequest("No file uploaded.");
    
        var uploadsFolder = Path.Combine(Directory.GetCurrentDirectory(), "Uploads");
    
        if (!Directory.Exists(uploadsFolder))
            Directory.CreateDirectory(uploadsFolder);
    
        var filePath = Path.Combine(uploadsFolder, file.FileName);
    
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            await file.CopyToAsync(stream);
        }
    
        return Ok(new { file.FileName, file.Length });
    }
}

The endpoint upload will save the file to the "Uploads" directory and return the filename and length.

Step 3: Configure Program.cs

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

var app = builder.Build();

app.UseStaticFiles();
app.MapControllers();

app.UseHttpsRedirection();

app.Run();

app.UseStaticFiles(); enables the app to serve static files directly over HTTP

Make sure your Uploads folder is accessible.

Step 4: Run and test

dotnet run

Hence, our file is saved:

So far, we have seen a naive, minimal approach to saving a file in an ASP.NET Core API. However, in real applications, you may split it up into layers, services, or however you prefer to structure applications.

Adding OpenApi/Swagger documentation

.NET 10 does not create OpenAPI (formerly Swagger) documentation like previous versions. So we have to add them. First, install the NuGet package:

dotnet add package Swashbuckle.AspNetCore

Next, change Program.cs:

using Microsoft.AspNetCore.Http.Features;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Upload V1");
});

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseStaticFiles();
app.MapControllers();
app.UseHttpsRedirection();

app.Run();

The AddOpenApi() method registers with the OpenAPI document generation services. Then AddEndpointsApiExplorer() adds an API explorer service that discovers endpoints and provides metadata about routes, parameters, and return types. Without this, Swagger would show no APIs. AddSwaggerGen() configures Swashbuckle (Swagger for .NET) and generates a Swagger document. Besides, it adds schema generation for your DTOs. UseSwagger() registers middleware to serve the Swagger JSON document. You must register middleware before using SwaggerUI. The UseSwaggerUI configures the Swagger UI web interface and navigates the UI to the JSON document. It basically adds UI elements, such as the page and Try out buttons.

Result

Restrict the file size limit

It is recommended to set a maximum file size limit for uploaded files:

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<FormOptions>(options =>
{
    options.MultipartBodyLengthLimit = 104857600; 
});

With the property MultipartBodyLengthLimit, I set the maximum size of the multipart body to 100 MBs.

Allowing formats for different file types

Each document type has a set of extensions: images are usually in JPG or PNG, and documents are usually in PDF or docx. For different purposes, we should validate the input. Like for a profile picture, users may not upload a docx or a PDF, while for a report, they should avoid JPG. To enforce it in our API, I will separate the image and document endpoints.

UploadImage specified for uploading image files:

[HttpPost("UploadImage")]
public async Task<IActionResult> UploadImageAsync(IFormFile file)
{
    if (file == null || file.Length == 0)
        return BadRequest("No file uploaded.");

    var allowedExtensions = new[] { ".jpg", ".png" };
    var extension = Path.GetExtension(file.FileName);
    
    if (!allowedExtensions.Contains(extension))
    {
        var extensionsWithoutDots = allowedExtensions.Select(ext => ext.TrimStart('.'));
        return BadRequest($"Invalid file type. Allowed types are: {string.Join(", ", extensionsWithoutDots)}");
    }
    
    var uploadsFolder = Path.Combine(Directory.GetCurrentDirectory(), "Uploads");

    if (!Directory.Exists(uploadsFolder))
        Directory.CreateDirectory(uploadsFolder);

    var filePath = Path.Combine(uploadsFolder, file.FileName);

    using (var stream = new FileStream(filePath, FileMode.Create))
    {
        await file.CopyToAsync(stream);
    }

    return Ok(new { file.FileName, file.Length });
}

UploadDocument method for uploading document files:

    [HttpPost("UploadDocument")]
    public async Task<IActionResult> UploadDocumentAsync(IFormFile file)
    {
        if (file == null || file.Length == 0)
            return BadRequest("No file uploaded.");

        var allowedExtensions = new[] { ".pdf", ".txt" };
        var extension = Path.GetExtension(file.FileName);
        
        if (!allowedExtensions.Contains(extension))
        {
            var extensionsWithoutDots = allowedExtensions.Select(ext => ext.TrimStart('.'));
            return BadRequest($"Invalid file type. Allowed types are: {string.Join(", ", extensionsWithoutDots)}");
        }
        
        var uploadsFolder = Path.Combine(Directory.GetCurrentDirectory(), "Uploads");
    
        if (!Directory.Exists(uploadsFolder))
            Directory.CreateDirectory(uploadsFolder);
    
        var filePath = Path.Combine(uploadsFolder, file.FileName);
    
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            await file.CopyToAsync(stream);
        }
    
        return Ok(new { file.FileName, file.Length });
    }

The prior method only supports JPG and PNG, while the latter supports PDF and TXT. Lets test it from SwaggerUI:

On a correct input:

If we inspect the Uploads folder, we can see the uploaded file:

While the other method:

And for the allowed document:

Renaming the file to standard naming

We have now successfully uploaded files. However, there is a problem: you may notice that file names are arbitrary and random.

For real applications, we often want to control the names of the files to avoid someone uploading a Snapchat image of themselves with a weird-looking filename. Let's fix that.

Step 1: Add model

First, introduce a model to input images. It will contain a type specifying what the file is for.

Add File type enum:

namespace fileUploadDemo.Models.Enums;

public enum FileTypeEnum
{
    ProfilePicture = 1,
    PostImage = 2,
    Resume = 3
}

File input:

using fileUploadDemo.Models.Enums;

namespace fileUploadDemo.Models.Dtos;

public class FileDtoInp
{
    public FileTypeEnum Type { get; set; }
    public IFormFile File { get; set; }
}

To return, we will use a model instead of an anonymous object:

namespace fileUploadDemo.Models.Dtos;

public class FileDto
{
    public string FileName { get; set; } = string.Empty;
    public long Length { get; set; } 
}

Step 2: Add service layer

So far, I have added everything to the controller, which is a bad practice. I'll add a service layer, but this can be implemented in whatever way you prefer.

Add a IFileService interface:

using fileUploadDemo.Models.Dtos;

namespace fileUploadDemo.Services.IServices;

public interface IFileService
{
    Task<FileDto> UploadImageAsync(FileDtoInp input);
    Task<FileDto> UploadDocumentAsync(FileDtoInp input);
}

And a FileService implementation:

using fileUploadDemo.Models.Dtos;
using fileUploadDemo.Models.Enums;
using fileUploadDemo.Services.IServices;

namespace fileUploadDemo.Services;

public class FileService: IFileService
{
    private readonly string _uploadsFolder;

    public FileService(IWebHostEnvironment env)
    {
        _uploadsFolder = Path.Combine(env.ContentRootPath, "Uploads");
    }
    public async Task<FileDto> UploadImageAsync(FileDtoInp input)
    {
        if (input.File == null || input.File.Length == 0)
            throw new Exception("No file uploaded.");
        
        var allowedExtensions = new[] { ".jpg", ".png" };
        var extension = Path.GetExtension(input.File.FileName);
        
        if (!allowedExtensions.Contains(extension))
        {
            var extensionsWithoutDots = allowedExtensions.Select(ext => ext.TrimStart('.'));
            throw new Exception($"Invalid file type. Allowed types are: {string.Join(", ", extensionsWithoutDots)}");
        }
        
        if (!Directory.Exists(_uploadsFolder))
            Directory.CreateDirectory(_uploadsFolder);

        var fileName = $"{ GetFileName(input.Type) }{extension}";
        
        var filePath = Path.Combine(_uploadsFolder, fileName);
    
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            await input.File.CopyToAsync(stream);
        }

        return new 
            FileDto()
            {
                FileName = fileName, 
                Length = input.File.Length
            };
    }

    public async Task<FileDto> UploadDocumentAsync(FileDtoInp input)
    {
        if (input.File == null || input.File.Length == 0)
            throw new Exception("No file uploaded.");

        var allowedExtensions = new[] { ".pdf", ".txt" };
        var extension = Path.GetExtension(input.File.FileName);
        
        if (!allowedExtensions.Contains(extension))
        {
            var extensionsWithoutDots = allowedExtensions.Select(ext => ext.TrimStart('.'));
            throw new Exception($"Invalid file type. Allowed types are: {string.Join(", ", extensionsWithoutDots)}");
        }
        
        if (!Directory.Exists(_uploadsFolder))
            Directory.CreateDirectory(_uploadsFolder);
    
        var fileName = $"{ GetFileName(input.Type) }{extension}";
        var filePath = Path.Combine(_uploadsFolder, fileName);
    
        using (var stream = new FileStream(filePath, FileMode.Create))
        {
            await input.File.CopyToAsync(stream);
        }

        return new 
            FileDto()
            {
                FileName = fileName, 
                Length = input.File.Length
            };
    }
    
    private string GetFileName(FileTypeEnum input)
        => input switch
        {
            FileTypeEnum.ProfilePicture => $"PRF-{DateTime.UtcNow:yyMMddHHmmss}",
            FileTypeEnum.PostImage => $"PST-{DateTime.UtcNow:yyMMddHHmmss}",
            FileTypeEnum.Resume => $"RSM-{DateTime.UtcNow:yyMMddHHmmss}",
            _ => throw new ArgumentOutOfRangeException(nameof(input), input, null)
        };
}

Let's understand what is happening here. We have methods for uploading images and documents, which first validate the file types. They actually abstracted the logic from the earlier upgrade of our application from controllers to services, which is always recommended. The main update here is the GetFileName method that returns a standardized name for each type. To make it collision-proof, I concatenated the current datetime into the name. Besides, the upload directory address is initialized in the constructor and used throughout the service. An even better way is to use it in appsettings.json and use the option pattern. Lets keep it simple for now. At last, I returned the FileDto model as output. You may also want to switch to not using exceptions for input validation, but I will leave that part up to you.

Step 3: Register the new service

builder.Services.AddScoped<IFileService, FileService>();

In Program.csI have registered the service dependency.

Step 4: Update controller

Now, the controller will inject and use the IFileService we just created:

using fileUploadDemo.Models.Dtos;
using fileUploadDemo.Services.IServices;
using Microsoft.AspNetCore.Mvc;

namespace fileUploadDemo.Controllers;

[ApiController]
[Route("api/[controller]")]
public class FileController: ControllerBase
{
    private readonly IFileService _fileService;

    public FileController(IFileService fileService)
    {
        _fileService = fileService;
    }
    
    [HttpPost("UploadImage")]
    public async Task<IActionResult> UploadImageAsync([FromForm] FileDtoInp input)
    {
        var result = await _fileService.UploadImageAsync(input);
        return Ok(result);
    }
    
    [HttpPost("UploadDocument")]
    public async Task<IActionResult> UploadDocumentAsync([FromForm] FileDtoInp input)
    {
        var result = await _fileService.UploadDocumentAsync(input);
        return Ok(result);
    }
}

[FromForm] specifies the input as form-data, not a JSON body, ensuring the endpoint receives files.

Step 4: Run and test

dotnet run

Ensure the file is named according to our standard, regardless of its original name.

The same happens with the documents:

Apart from naming files with date and time, using a unique GUID or the username is also a common practice. Consider the following ways:

var fileName = $"{ Guid.NewGuid().ToString() }{extension}";

or:

var fileName = $"{ _userContext.Username }{extension}";

Creating a GET endpoint to fetch a file

We have covered several ways to upload a file in an ASP.NET Core API. Next requirement naturally arises: how to fetch the saved file? Let's design an endpoint for it.

A new model to return the file from the service to the controller could be implemented like this:

namespace fileUploadDemo.Models.Dtos;

public class FileResultDto
{
    public byte[] Content { get; set; } = default!;
    public string ContentType { get; set; } = string.Empty;
    public string FileName { get; set; } = string.Empty;
}

Our service implementation should include a new method for fetching a file:

public async Task<FileResultDto?> GetFileAsync(string key)
{
    if (string.IsNullOrWhiteSpace(key) || key.Contains(".."))
        return null;

    var filePath = Path.Combine(_uploadsFolder, key);

    if (!System.IO.File.Exists(filePath))
        return null;

    var extension = Path.GetExtension(filePath).ToLower();

    var contentType = extension switch
    {
        ".jpg" or ".jpeg" => "image/jpeg",
        ".png" => "image/png",
        ".pdf" => "application/pdf",
        _ => "application/octet-stream"
    };

    var bytes = await System.IO.File.ReadAllBytesAsync(filePath);

    return new FileResultDto
    {
        Content = bytes,
        ContentType = contentType,
        FileName = key
    };
}

After some initial string checks and combining the filename with the directory, we check whether the file exists. In the latter part, we convert the file into a MIME type based on the extension. var bytes = await System.IO.File.ReadAllBytesAsync(filePath); loads the entire file into memory and returns byte[]. If large files are uploaded, consider streaming instead. Finally, it packs the content and metadata into the response model and returns it.

Use it in the controller:

[HttpGet("GetFile")]
public async Task<IActionResult> GetFileAsync([FromQuery] string key)
{
    var result = await _fileService.GetFileAsync(key);

    if (result == null)
        return NotFound("File not found");

    return File(result.Content, result.ContentType, result.FileName);
}

[FromQuery] will prompt for the filename as a key param and pass it to the service. Once the data is received, the endpoint will return the actual file.

Test

Simply, the user can download the file.

Tips for using file uploading in ASP.NET Core

For production environments and scalable systems, consider the following aspects.

• For the production environment, use a cloud service such as Azure Blob or AWS S3 to save files for better reliability and speed.
• Use the path in appsettings for security and good design.
• Organize upload paths into separate directories for document- and module-wise uploads. Even separating directories for users is also a common practice, such as "images/Profile", "images/Posts", "documents/Resumes" or "images/john/".
• Store metadata in a database for referencing and persistence. Creating an image-and-document table with a Type key is a great way to reference files to corresponding entities, such as User and Building, via ImageId and DocumentId. The tables can store other important information, such as file size, creation date, uploader user, file name, etc.
• If your system requires a very large file upload, use chunk uploading.
• Use file streaming for large file instead of buffer that can result in high RAM usage.
• Enable progress tracking via SignalR.

Conclusion

The long story comes to an end, and we learned how to handle files in ASP.NET Core APIs. We started with minimal code and applied best practices when using images and documents. By following these tips, you can design a file structure securely and efficiently in a production-grade system.