DEV Community: Elvin Suleymanov

Modernizing .NET Architectures for AI-Native Workloads

Elvin Suleymanov — Sat, 04 Apr 2026 12:38:01 +0000

For the past decade, .NET architects have been perfecting a craft. Clean separation of concerns. Domain-driven design. Event-driven microservices. CQRS. Hexagonal architecture. The patterns are mature, battle-tested, and well-understood. Teams have learned how to build systems that are reliable, maintainable, and scalable.

Then AI arrived - not as a feature, but as an expectation.

Not the AI of a sentiment analysis endpoint bolted onto the side of an API. Not a classification model embedded in a background job. The new expectation is AI that reasons across your entire domain, remembers context across sessions, orchestrates multi-step workflows autonomously, and integrates with every surface of your product simultaneously.

This is what it means to be AI-native. And it does not fit cleanly into the architectures most .NET teams built over the last decade.

This article is a practical guide to bridging that gap. We will examine how to evolve a modern .NET architecture to support AI-native workloads - without discarding everything you have built and without compromising the engineering discipline that makes .NET systems trustworthy.

Who is this for? Senior .NET engineers, architects, and tech leads who are integrating AI deeply into production systems and need a structural framework for doing it correctly.

What AI-Native Actually Means
Why Traditional .NET Architectures Struggle with AI
The AI-Native Architecture Stack
Semantic Kernel as the AI Orchestration Layer
Designing AI-Aware Domain Models
Vector Storage and Semantic Memory in .NET
The Agent Pattern: Autonomous AI in Your Domain
Streaming AI Responses with ASP.NET Core
Observability for AI Workloads
Guardrails: Safety, Cost Control, and Responsible AI
Real-World Walkthrough: AI-Native CRM Feature
Migration Path: Evolving an Existing .NET System

1. What AI-Native Actually Means

The term AI-native is used loosely in the industry, so let us define it precisely for the context of .NET architecture.

An AI-native system is one in which the AI capability is structurally integrated into the architecture - not added as a feature on top of it. The difference matters enormously in practice.

Consider two approaches to adding a "smart contract summarization" feature to a legal SaaS product.

The first approach creates a new API endpoint, calls an LLM from inside a service method, returns the result. The AI is a black box embedded in a single method in a single service. It has no awareness of the domain model, no memory of previous interactions, no ability to take follow-up actions, and no path for the engineering team to reason about what the AI actually did or why.

The second approach models the AI capability as a first-class architectural concern. The AI orchestrator knows the domain. It has access to the company's private knowledge base via semantic search. It can take actions in the system - drafting a document, flagging a clause, notifying a reviewer - via well-defined tool interfaces. Every AI interaction is observable, traceable, and auditable. The LLM provider is an infrastructure dependency, not a hardcoded implementation detail.

The second approach is AI-native. It is also significantly harder to build. This article gives you the framework to do it correctly.

2. Why Traditional .NET Architectures Struggle with AI

The Clean Architecture and Domain-Driven Design patterns that .NET teams have embraced are fundamentally synchronous, deterministic, and stateless between requests. A command handler receives input, applies business rules, persists state, and returns. The output is predictable given the input. The execution time is bounded and measurable.

AI workloads break every one of these assumptions.

LLM calls are slow. A single inference call to GPT-4o or Claude 3.7 takes anywhere from 500ms to 30 seconds depending on the prompt length and output complexity. An application command handler that takes 15 seconds to complete will time out, exhaust thread pool resources, and generate a torrent of support tickets.

LLM outputs are non-deterministic. Two identical prompts with the same model can produce subtly different outputs. Unit tests that assert on exact string output will fail randomly. Deterministic business logic cannot assume deterministic AI output.

AI workflows are long-running and stateful. An agent that researches a topic, drafts a document, asks the user for clarification, incorporates the feedback, and then publishes the result is not a request-response operation. It is a workflow that spans multiple turns, potentially across multiple sessions. The request-scoped dependency injection lifetime and the stateless HTTP handler model do not accommodate this naturally.

AI introduces external costs per call. Every LLM call costs money in API tokens. Traditional architectures have no concept of per-call economic cost - there is no mechanism to budget, throttle, or optimize LLM usage without building it explicitly.

The context window is a shared resource. An LLM call is not just "pass input, get output." The entire conversation history, retrieved documents, tool definitions, and system prompt all compete for space inside a fixed context window. Managing this window is a first-class engineering problem that has no analog in traditional CRUD architecture.

These are not minor inconveniences. They are fundamental mismatches between the assumptions embedded in traditional .NET architecture and the requirements of AI-native workloads. Addressing them requires structural changes, not just new NuGet packages.

3. The AI-Native Architecture Stack

Before writing any code, it helps to visualize how an AI-native .NET system is layered. The following stack extends the familiar Clean Architecture layers with the AI-specific concerns that sit between the application layer and the external AI infrastructure.

┌──────────────────────────────────────────────────────────────────┐
│                        Presentation Layer                        │
│          ASP.NET Core Minimal APIs   Blazor   gRPC               │
│          Streaming responses    WebSockets    SignalR             │
├──────────────────────────────────────────────────────────────────┤
│                      AI Orchestration Layer          ← NEW       │
│          Semantic Kernel Kernel      Agent runtime               │
│          Planner    Memory manager   Plugin registry             │
│          Prompt template engine      Token budget manager        │
├──────────────────────────────────────────────────────────────────┤
│                       Application Layer                          │
│          Command / Query handlers    Domain services             │
│          AI Tool implementations    Workflow coordinators        │
├──────────────────────────────────────────────────────────────────┤
│                        Domain Layer                              │
│          Entities    Value objects    Domain events              │
│          AI-aware aggregates         Semantic metadata           │
├──────────────────────────────────────────────────────────────────┤
│                     Infrastructure Layer                         │
│          PostgreSQL    Redis    Blob storage                      │
│          Vector DB (pgvector / Qdrant / Azure AI Search)         │
│          LLM providers (OpenAI / Azure OpenAI / Anthropic)       │
│          Embedding providers    Observability (OTEL)             │
└──────────────────────────────────────────────────────────────────┘

The AI Orchestration Layer is the critical addition. It is not part of the domain - it does not contain business rules. It is not part of the infrastructure - it is not a database driver or an HTTP client. It is the translation layer between your domain logic and the probabilistic, non-deterministic, token-consuming world of large language models. Keeping it as a distinct layer is what makes the rest of the architecture testable, maintainable, and provider-agnostic.

4. Semantic Kernel as the AI Orchestration Layer

Microsoft's Semantic Kernel is the .NET ecosystem's answer to the AI orchestration problem. It provides the abstractions that allow you to build the AI Orchestration Layer without coupling your application to a specific LLM provider, embedding model, or vector store.

The core concept in Semantic Kernel is the Kernel - a dependency injection container for AI services and plugins. Everything flows through it.

// Program.cs - register Semantic Kernel with all AI services
builder.Services.AddKernel()
    .AddAzureOpenAIChatCompletion(
        deploymentName: config["AzureOpenAI:DeploymentName"]!,
        endpoint: config["AzureOpenAI:Endpoint"]!,
        apiKey: config["AzureOpenAI:ApiKey"]!)
    .AddAzureOpenAITextEmbeddingGeneration(
        deploymentName: config["AzureOpenAI:EmbeddingDeployment"]!,
        endpoint: config["AzureOpenAI:Endpoint"]!,
        apiKey: config["AzureOpenAI:ApiKey"]!)
    .Plugins
        .AddFromType<CustomerPlugin>()
        .AddFromType<ContractPlugin>()
        .AddFromType<NotificationPlugin>();

// Register vector memory store
builder.Services.AddSingleton<IVectorStore>(sp =>
    new QdrantVectorStore(new QdrantClient("localhost")));

Plugins as domain capability exposure

The Plugin system is how you expose your domain to the AI. A plugin is a C# class whose public methods are decorated with [KernelFunction] and natural-language descriptions. The AI reads these descriptions and decides which functions to call and in what order based on the user's intent.

public sealed class CustomerPlugin
{
    private readonly ICustomerRepository _customers;
    private readonly IOrderRepository    _orders;

    public CustomerPlugin(
        ICustomerRepository customers,
        IOrderRepository orders)
    {
        _customers = customers;
        _orders    = orders;
    }

    [KernelFunction]
    [Description("Retrieve a customer profile including contact details, " +
                 "subscription plan, and account status.")]
    public async Task<CustomerDto> GetCustomerProfileAsync(
        [Description("The unique customer identifier (UUID)")]
        string customerId,
        CancellationToken cancellationToken = default)
    {
        var customer = await _customers.GetByIdAsync(
            Guid.Parse(customerId), cancellationToken);

        return customer is null
            ? throw new CustomerNotFoundException(customerId)
            : CustomerDto.FromDomain(customer);
    }

    [KernelFunction]
    [Description("List the most recent orders for a customer, " +
                 "sorted newest first. Returns order status, total, and items.")]
    public async Task<IReadOnlyList<OrderSummaryDto>> GetRecentOrdersAsync(
        [Description("The unique customer identifier (UUID)")]
        string customerId,
        [Description("Maximum number of orders to return. Default is 10.")]
        int limit = 10,
        CancellationToken cancellationToken = default)
    {
        var orders = await _orders.GetRecentByCustomerAsync(
            Guid.Parse(customerId), limit, cancellationToken);

        return orders.Select(OrderSummaryDto.FromDomain).ToList();
    }

    [KernelFunction]
    [Description("Update the subscription plan for a customer. " +
                 "Valid plans are: starter, professional, enterprise.")]
    public async Task<string> UpdateSubscriptionPlanAsync(
        [Description("The unique customer identifier (UUID)")]
        string customerId,
        [Description("The new subscription plan name")]
        string planName,
        CancellationToken cancellationToken = default)
    {
        await _customers.UpdatePlanAsync(
            Guid.Parse(customerId), planName, cancellationToken);

        return $"Successfully updated customer {customerId} to {planName} plan.";
    }
}

The descriptions you write on [KernelFunction] and each parameter are not comments - they are the interface between your code and the language model. The quality of your function descriptions directly determines the reliability of the AI's decisions about when and how to call them. This is description engineering, and it is one of the most underappreciated skills in AI-native .NET development.

5. Designing AI-Aware Domain Models

A traditional domain entity is designed to support business rules enforced by application code. An AI-aware domain entity also needs to support semantic understanding - the ability for an AI to reason about what the entity means, not just what fields it has.

This is a subtle but important distinction. Consider a Contract entity in a legal SaaS:

// Traditional domain entity
public sealed class Contract
{
    public Guid   Id            { get; private set; }
    public string Title         { get; private set; }
    public string FullText      { get; private set; }
    public ContractStatus Status { get; private set; }
    public DateTimeOffset EffectiveDate { get; private set; }
    public DateTimeOffset ExpiryDate    { get; private set; }

    // Business rules enforced in domain
    public void Approve(UserId approver)
    {
        if (Status != ContractStatus.PendingReview)
            throw new DomainException("Only contracts pending review can be approved.");

        Status = ContractStatus.Approved;
        AddDomainEvent(new ContractApprovedEvent(Id, approver));
    }
}

// AI-aware domain entity adds semantic metadata
public sealed class Contract
{
    public Guid   Id            { get; private set; }
    public string Title         { get; private set; }
    public string FullText      { get; private set; }
    public ContractStatus Status { get; private set; }
    public DateTimeOffset EffectiveDate { get; private set; }
    public DateTimeOffset ExpiryDate    { get; private set; }

    // Semantic metadata - generated asynchronously after entity creation
    public string?          AiSummary       { get; private set; }
    public IReadOnlyList<string> KeyClauses { get; private set; } = [];
    public IReadOnlyList<string> RiskFlags  { get; private set; } = [];
    public float[]?         EmbeddingVector { get; private set; }
    public DateTimeOffset?  LastIndexedAt   { get; private set; }

    public void ApplySemanticAnalysis(
        string summary,
        IReadOnlyList<string> clauses,
        IReadOnlyList<string> risks,
        float[] embedding)
    {
        AiSummary       = summary;
        KeyClauses      = clauses;
        RiskFlags       = risks;
        EmbeddingVector = embedding;
        LastIndexedAt   = DateTimeOffset.UtcNow;

        AddDomainEvent(new ContractIndexedEvent(Id));
    }

    // Business rules unchanged - domain integrity is not AI's responsibility
    public void Approve(UserId approver)
    {
        if (Status != ContractStatus.PendingReview)
            throw new DomainException("Only contracts pending review can be approved.");

        Status = ContractStatus.Approved;
        AddDomainEvent(new ContractApprovedEvent(Id, approver));
    }
}

The semantic metadata lives in the domain entity, but it is never set by the AI directly. The domain event pipeline triggers an asynchronous background job that calls the AI, generates the semantic analysis, and then calls ApplySemanticAnalysis through a proper command. The domain's integrity is preserved. The AI capability is additive, not structural.

6. Vector Storage and Semantic Memory in .NET

Vector storage is the persistence layer of AI-native systems. It stores embedding vectors alongside their source content and metadata, enabling semantic search - finding documents that are meaningfully similar to a query rather than just lexically matching keywords.

In a .NET system, the vector store is infrastructure. It belongs in the Infrastructure layer and is accessed through an interface defined in the Domain or Application layer.

// Application layer interface - no vector store dependency
public interface IContractSemanticSearch
{
    Task<IReadOnlyList<ContractSearchResult>> SearchAsync(
        string query,
        int maxResults = 10,
        float minSimilarity = 0.7f,
        CancellationToken ct = default);

    Task IndexContractAsync(
        Guid contractId,
        string content,
        ContractMetadata metadata,
        CancellationToken ct = default);
}

// Infrastructure implementation - Qdrant vector store
public sealed class QdrantContractSemanticSearch : IContractSemanticSearch
{
    private const string CollectionName = "contracts";

    private readonly QdrantClient                   _qdrant;
    private readonly ITextEmbeddingGenerationService _embeddings;

    public QdrantContractSemanticSearch(
        QdrantClient qdrant,
        ITextEmbeddingGenerationService embeddings)
    {
        _qdrant     = qdrant;
        _embeddings = embeddings;
    }

    public async Task<IReadOnlyList<ContractSearchResult>> SearchAsync(
        string query,
        int maxResults = 10,
        float minSimilarity = 0.7f,
        CancellationToken ct = default)
    {
        // Generate embedding for the search query
        var queryEmbedding = await _embeddings.GenerateEmbeddingAsync(query, ct);

        // Vector similarity search in Qdrant
        var results = await _qdrant.SearchAsync(
            collectionName: CollectionName,
            vector: queryEmbedding.ToArray(),
            limit: (ulong)maxResults,
            scoreThreshold: minSimilarity,
            cancellationToken: ct);

        return results
            .Select(r => new ContractSearchResult(
                ContractId: Guid.Parse(r.Payload["contract_id"].StringValue),
                Title:       r.Payload["title"].StringValue,
                Summary:     r.Payload["summary"].StringValue,
                Similarity:  r.Score))
            .ToList();
    }

    public async Task IndexContractAsync(
        Guid contractId,
        string content,
        ContractMetadata metadata,
        CancellationToken ct = default)
    {
        // Chunk large contracts into overlapping segments
        var chunks = ChunkText(content, chunkSize: 512, overlap: 64);

        var points = new List<PointStruct>();

        foreach (var (chunk, index) in chunks.Select((c, i) => (c, i)))
        {
            var embedding = await _embeddings.GenerateEmbeddingAsync(chunk, ct);

            points.Add(new PointStruct
            {
                Id     = new PointId { Uuid = Guid.NewGuid().ToString() },
                Vectors = new Vectors { Vector = new Vector { Data = { embedding } } },
                Payload =
                {
                    ["contract_id"]  = contractId.ToString(),
                    ["title"]        = metadata.Title,
                    ["summary"]      = metadata.AiSummary ?? "",
                    ["chunk_index"]  = index,
                    ["effective_date"] = metadata.EffectiveDate.ToString("O"),
                }
            });
        }

        await _qdrant.UpsertAsync(CollectionName, points, cancellationToken: ct);
    }

    private static IReadOnlyList<string> ChunkText(
        string text, int chunkSize, int overlap)
    {
        var words  = text.Split(' ', StringSplitOptions.RemoveEmptyEntries);
        var chunks = new List<string>();

        for (int i = 0; i < words.Length; i += chunkSize - overlap)
        {
            var chunk = string.Join(' ', words.Skip(i).Take(chunkSize));
            if (!string.IsNullOrWhiteSpace(chunk))
                chunks.Add(chunk);

            if (i + chunkSize >= words.Length)
                break;
        }

        return chunks;
    }
}

Choosing your vector store

pgvector is the pragmatic choice for teams already running PostgreSQL. It adds vector similarity search as a PostgreSQL extension, keeping your operational footprint minimal. It handles tens of millions of vectors efficiently and supports HNSW indexing for fast approximate nearest-neighbor search.

Qdrant is purpose-built for vector search at scale. It supports filtering on payload metadata alongside vector similarity, which is essential for multi-tenant systems where you need to restrict search results by tenant before computing similarity.

Azure AI Search is the managed option for teams on Azure. It combines traditional keyword search with vector search in a single index, handles chunking and embedding generation natively, and integrates directly with Azure OpenAI.

7. The Agent Pattern: Autonomous AI in Your Domain

An agent is an AI component that can reason about a goal, decide what tools to use, call those tools in sequence, observe the results, adjust its plan, and iterate until the goal is achieved or it determines it cannot proceed further.

In .NET terms, an agent is a Semantic Kernel feature that combines a chat model with a set of plugins and a planning strategy. The agent pattern is powerful and genuinely dangerous if implemented naively - an autonomous component that can call your domain methods without human approval is a significant risk surface.

// Define an agent scoped to a specific workflow
public sealed class ContractReviewAgent
{
    private readonly Kernel              _kernel;
    private readonly IAgentAuditLogger  _audit;
    private readonly ITokenBudgetService _budget;

    public ContractReviewAgent(
        Kernel kernel,
        IAgentAuditLogger audit,
        ITokenBudgetService budget)
    {
        _kernel = kernel;
        _audit  = audit;
        _budget = budget;
    }

    public async IAsyncEnumerable<AgentUpdate> ReviewContractAsync(
        Guid contractId,
        string userInstruction,
        AgentRunContext context,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        // Enforce token budget before starting
        var remainingBudget = await _budget.GetRemainingAsync(context.TenantId, ct);
        if (remainingBudget < 5_000)
        {
            yield return AgentUpdate.Error("Insufficient token budget for this operation.");
            yield break;
        }

        // Build agent with only the plugins relevant to contract review
        // Principle of least privilege: do not give the agent tools it does not need
        var agent = new ChatCompletionAgent
        {
            Name = "ContractReviewAgent",
            Kernel = _kernel.Clone(),
            Instructions = """
                You are a contract review assistant. Your job is to analyze the
                specified contract and provide a structured review covering:

                1. A plain-English summary of what the contract covers.
                2. Key obligations for each party.
                3. Any unusual or high-risk clauses that should be flagged for
                   human legal review.
                4. Recommended questions the reviewer should clarify before signing.

                Always retrieve the full contract text before writing your review.
                Do not make assumptions about contract content you have not retrieved.
                """,
            Arguments = new KernelArguments(
                new OpenAIPromptExecutionSettings
                {
                    ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions,
                    MaxTokens        = Math.Min(remainingBudget, 4_096),
                    Temperature      = 0.1  // Low temperature for analytical tasks
                })
        };

        // Scoped plugins - only what this agent needs
        agent.Kernel.Plugins.AddFromType<ContractPlugin>();
        agent.Kernel.Plugins.AddFromType<LegalReferencePlugin>();

        var history = new ChatHistory();
        history.AddUserMessage(
            $"Please review contract {contractId}. Additional context: {userInstruction}");

        // Stream agent responses and intermediate steps
        await foreach (var message in agent.InvokeStreamingAsync(history, ct))
        {
            // Log every tool call for audit trail
            if (message.Content?.Contains("tool_call") == true)
                await _audit.LogToolCallAsync(context, message.Content, ct);

            // Deduct token usage from budget
            if (message.Metadata?.TryGetValue("usage", out var usage) == true)
                await _budget.DeductAsync(context.TenantId, usage, ct);

            yield return AgentUpdate.Progress(message.Content ?? "");
        }
    }
}

The principle of least privilege for agents

The single most important safety rule for agent design is to give each agent only the tools it needs for its specific task. A ContractReviewAgent should not have access to the NotificationPlugin or the BillingPlugin. A CustomerSupportAgent should be able to read customer data but not write it without a human approval step in the loop.

Model this exactly like you model authorization in the rest of your system - with explicit, minimal, audited grants rather than broad access.

8. Streaming AI Responses with ASP.NET Core

LLM inference is slow. Waiting for a full response before returning anything to the client produces an experience that feels broken - the UI freezes, the user wonders if something went wrong, and the HTTP request may time out entirely on long outputs.

Streaming solves all three problems simultaneously. ASP.NET Core's IAsyncEnumerable<T> support makes streaming AI responses to clients a first-class, clean pattern.

// Minimal API endpoint - streams AI response tokens as server-sent events
app.MapPost("/api/contracts/{contractId}/review", async (
    Guid contractId,
    ReviewContractRequest request,
    ContractReviewAgent agent,
    ITokenBudgetService budget,
    ClaimsPrincipal user,
    CancellationToken ct) =>
{
    var tenantId = user.GetTenantId();

    var context = new AgentRunContext(
        TenantId:    tenantId,
        UserId:      user.GetUserId(),
        OperationId: Guid.NewGuid());

    // Return streaming response - ASP.NET Core handles chunked transfer
    return Results.Ok(StreamReviewAsync(contractId, request.Instruction, agent, context, ct));
})
.WithName("ReviewContract")
.WithOpenApi()
.RequireAuthorization("ContractReview")
.RequireRateLimiting("ai-operations");

// Local function returns IAsyncEnumerable for streaming
static async IAsyncEnumerable<ReviewChunk> StreamReviewAsync(
    Guid contractId,
    string instruction,
    ContractReviewAgent agent,
    AgentRunContext context,
    [EnumeratorCancellation] CancellationToken ct)
{
    await foreach (var update in agent.ReviewContractAsync(contractId, instruction, context, ct))
    {
        yield return new ReviewChunk(
            Type:    update.Type.ToString(),
            Content: update.Content,
            At:      DateTimeOffset.UtcNow);
    }
}

public record ReviewChunk(string Type, string Content, DateTimeOffset At);

On the client side, whether you are using Blazor, React, or a mobile application, the experience is a smooth token-by-token stream of text appearing in real time - the same experience users have come to expect from ChatGPT and Claude.

@* Blazor component - consuming the streaming review endpoint *@
@code {
    private readonly StringBuilder _reviewBuffer = new();
    private bool _isStreaming;

    private async Task StartReviewAsync()
    {
        _isStreaming = true;
        _reviewBuffer.Clear();

        using var response = await Http.PostAsJsonAsync(
            $"/api/contracts/{ContractId}/review",
            new { Instruction = UserInstruction });

        response.EnsureSuccessStatusCode();

        await foreach (var chunk in response.Content
            .ReadFromJsonAsAsyncEnumerable<ReviewChunk>())
        {
            if (chunk is null) continue;

            _reviewBuffer.Append(chunk.Content);
            StateHasChanged();   // Re-render as each chunk arrives
        }

        _isStreaming = false;
        StateHasChanged();
    }
}

9. Observability for AI Workloads

AI workloads introduce observability challenges that traditional APM tools are not equipped to handle out of the box. Latency, token consumption, prompt content, model version, temperature setting, and tool call sequences all need to be captured to diagnose problems and control costs.

Semantic Kernel ships with OpenTelemetry support built in. The following setup captures the metrics and traces that matter most in production.

// Program.cs - OpenTelemetry for AI workloads
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource("Microsoft.SemanticKernel")
        .AddSource("MyApp.AI")
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddOtlpExporter())
    .WithMetrics(metrics => metrics
        .AddMeter("Microsoft.SemanticKernel")
        .AddMeter("MyApp.AI.Tokens")
        .AddMeter("MyApp.AI.Latency")
        .AddAspNetCoreInstrumentation()
        .AddOtlpExporter());

// Custom activity source for AI-specific spans
public static class AiTelemetry
{
    public static readonly ActivitySource Source = new("MyApp.AI");

    public static Activity? StartAgentRun(
        string agentName,
        string tenantId,
        string operationId)
    {
        var activity = Source.StartActivity(
            $"agent.{agentName}",
            ActivityKind.Internal);

        activity?.SetTag("ai.agent.name",     agentName);
        activity?.SetTag("ai.tenant.id",      tenantId);
        activity?.SetTag("ai.operation.id",   operationId);
        activity?.SetTag("ai.model",          "gpt-4o");

        return activity;
    }

    public static void RecordTokenUsage(
        string tenantId,
        string operation,
        int promptTokens,
        int completionTokens)
    {
        TokenUsageCounter.Add(
            promptTokens + completionTokens,
            new TagList
            {
                { "tenant.id",  tenantId },
                { "operation",  operation },
                { "token.type", "total" }
            });
    }

    private static readonly Counter<int> TokenUsageCounter =
        new Meter("MyApp.AI.Tokens")
            .CreateCounter<int>(
                "ai.tokens.used",
                unit: "{tokens}",
                description: "Total tokens consumed per operation");
}

The AI observability checklist

Every AI operation in production should produce traces that capture the agent or chain name, the model used and its version, the number of prompt tokens and completion tokens consumed, the total wall-clock latency, every tool call made and its result, whether the operation succeeded or was cut short by a guardrail, and the tenant ID for multi-tenant systems.

Without this data, debugging a misbehaving agent is guesswork. With it, you can answer the questions that matter: why did the agent call the wrong tool, where is the latency spike coming from, which tenant is consuming 40% of our token budget, and is the model performing worse on inputs with certain characteristics.

10. Guardrails: Safety, Cost Control, and Responsible AI

Guardrails are the engineering controls you put in place to ensure AI workloads behave within defined boundaries - for safety, cost, performance, and regulatory compliance. They are not optional. They are the difference between a feature that delights users and one that causes a production incident at 2am.

Token budget enforcement

public interface ITokenBudgetService
{
    Task<int>  GetRemainingAsync(Guid tenantId, CancellationToken ct);
    Task       DeductAsync(Guid tenantId, object usage, CancellationToken ct);
    Task<bool> TryReserveAsync(Guid tenantId, int estimatedTokens, CancellationToken ct);
}

// Infrastructure implementation backed by Redis
public sealed class RedisTokenBudgetService : ITokenBudgetService
{
    private readonly IDatabase _redis;

    public RedisTokenBudgetService(IConnectionMultiplexer redis)
        => _redis = redis.GetDatabase();

    public async Task<int> GetRemainingAsync(Guid tenantId, CancellationToken ct)
    {
        var key   = $"token_budget:{tenantId}:{GetCurrentMonth()}";
        var value = await _redis.StringGetAsync(key);
        return value.HasValue ? (int)value : GetDefaultMonthlyBudget(tenantId);
    }

    public async Task<bool> TryReserveAsync(
        Guid tenantId, int estimatedTokens, CancellationToken ct)
    {
        var remaining = await GetRemainingAsync(tenantId, ct);
        return remaining >= estimatedTokens;
    }

    private static string GetCurrentMonth()
        => DateTimeOffset.UtcNow.ToString("yyyy-MM");

    private static int GetDefaultMonthlyBudget(Guid tenantId)
        => 500_000; // 500K tokens per tenant per month on starter plan
}

Input and output validation

Every prompt sent to an LLM should be validated before dispatch, and every response received should be validated before being shown to a user or used to trigger a domain action. This is especially important in multi-tenant systems where user-supplied content could contain prompt injection attempts.

public sealed class PromptSafetyMiddleware
{
    private static readonly string[] ForbiddenPatterns =
    [
        "ignore previous instructions",
        "you are now",
        "disregard your",
        "act as if",
        "pretend you are"
    ];

    public static bool IsSafeInput(string userInput)
    {
        var normalized = userInput.ToLowerInvariant();

        return !ForbiddenPatterns.Any(pattern =>
            normalized.Contains(pattern, StringComparison.OrdinalIgnoreCase));
    }

    public static bool IsStructuredOutputValid<T>(string llmOutput)
    {
        try
        {
            var result = JsonSerializer.Deserialize<T>(llmOutput);
            return result is not null;
        }
        catch
        {
            return false;
        }
    }
}

The human-in-the-loop pattern

For any AI action that has irreversible consequences - sending an email, updating a contract status, charging a payment method, deleting records - require explicit human approval before execution. The agent can prepare the action and present it for review. The human approves or rejects. Only then does the domain command execute.

public sealed class PendingAiAction
{
    public Guid              Id          { get; init; } = Guid.NewGuid();
    public string            Description { get; init; } = "";
    public string            CommandJson  { get; init; } = "";
    public string            CommandType  { get; init; } = "";
    public PendingActionStatus Status    { get; private set; } = PendingActionStatus.AwaitingApproval;
    public DateTimeOffset    ExpiresAt   { get; init; } = DateTimeOffset.UtcNow.AddHours(24);

    public void Approve(UserId approver)
    {
        if (Status != PendingActionStatus.AwaitingApproval)
            throw new DomainException("This action has already been resolved.");
        if (DateTimeOffset.UtcNow > ExpiresAt)
            throw new DomainException("This action request has expired.");

        Status = PendingActionStatus.Approved;
    }

    public void Reject(UserId rejector, string reason)
    {
        Status = PendingActionStatus.Rejected;
    }
}

11. Real-World Walkthrough: AI-Native CRM Feature

Let us put the entire architecture together by designing one cohesive AI-native feature: a customer health score assistant for a B2B SaaS CRM. The assistant analyzes a customer's usage data, support history, payment history, and NPS responses, and generates a health score with a plain-English explanation and recommended actions for the account manager.

The feature requirements

The assistant must read customer data across four domains: product usage metrics, support ticket history, billing and payment records, and NPS survey responses. It must produce a structured health score from 0 to 100, a one-paragraph plain-English explanation, and up to three prioritized recommended actions. It must stream the response in real time. It must log every inference for audit. It must respect a per-tenant token budget.

The architecture

Account Manager clicks "Analyze Health"
          │
          ▼
POST /api/customers/{id}/health-analysis
          │
          ▼
HealthAnalysisEndpoint
  → Validates token budget
  → Creates AgentRunContext
  → Streams CustomerHealthAgent.AnalyzeAsync()
          │
          ▼
CustomerHealthAgent (Semantic Kernel ChatCompletionAgent)
  → Plugins: UsagePlugin, SupportPlugin, BillingPlugin, NpsPlugin
  → Strategy: Auto function calling
  → Temperature: 0.15 (analytical, low creativity)
          │
     ┌────┴────────────────────────────────────┐
     │ Tool calls (in whatever order the       │
     │ model determines is logical)            │
     ├─────────────────────────────────────────┤
     │ UsagePlugin.GetUsageMetricsAsync()      │
     │   → PostgreSQL (metrics schema)         │
     │ SupportPlugin.GetTicketHistoryAsync()   │
     │   → PostgreSQL (support schema)         │
     │ BillingPlugin.GetPaymentHistoryAsync()  │
     │   → PostgreSQL (billing schema)         │
     │ NpsPlugin.GetNpsResponsesAsync()        │
     │   → PostgreSQL (survey schema)          │
     └────┬────────────────────────────────────┘
          │
          ▼
Structured output: HealthAnalysisResult
{
  "score": 74,
  "trend": "declining",
  "explanation": "...",
  "recommended_actions": [...]
}
          │
          ▼
  → Streamed to client as JSON chunks
  → Persisted to customer record (async)
  → Logged to audit trail
  → Token usage deducted from budget

The output schema

// Force the model to return structured output
public sealed record HealthAnalysisResult
{
    [JsonPropertyName("score")]
    [JsonDescription("Health score from 0 (critical) to 100 (excellent)")]
    public int Score { get; init; }

    [JsonPropertyName("trend")]
    [JsonDescription("Score trend: improving, stable, or declining")]
    public string Trend { get; init; } = "";

    [JsonPropertyName("explanation")]
    [JsonDescription("One paragraph plain-English explanation for the account manager")]
    public string Explanation { get; init; } = "";

    [JsonPropertyName("recommended_actions")]
    [JsonDescription("Up to 3 prioritized actions the account manager should take")]
    public IReadOnlyList<RecommendedAction> RecommendedActions { get; init; } = [];
}

public sealed record RecommendedAction(
    [property: JsonPropertyName("priority")]   int    Priority,
    [property: JsonPropertyName("action")]     string Action,
    [property: JsonPropertyName("rationale")]  string Rationale
);

This walkthrough covers roughly 20% of the full implementation, but it demonstrates the key structural principle: the AI is a coordinator that uses your existing domain repositories through the plugin interface. The repositories do not know they are being called by an AI. The domain does not change. Only the orchestration layer is new.

12. Migration Path: Evolving an Existing .NET System

Adopting an AI-native architecture does not require a rewrite. The most effective migration path is incremental and additive - you add the AI Orchestration Layer on top of your existing Clean Architecture without disturbing the layers beneath it.

Phase 1 - Add the AI infrastructure (Week 1-2)

Install Semantic Kernel, configure your LLM provider and embedding model, and add your vector store of choice. Write the ITokenBudgetService, IAgentAuditLogger, and IContractSemanticSearch interfaces. Implement them in the Infrastructure layer. Register everything in DI. No existing code changes.

Phase 2 - Build the first plugin from an existing service (Week 2-3)

Take one existing domain service - the simplest one whose data would be useful to an AI - and wrap it in a [KernelFunction] plugin. Write clear, natural-language descriptions on every method and parameter. Write integration tests that verify the plugin calls the underlying service correctly.

Phase 3 - Build a single AI endpoint with full observability (Week 3-4)

Build one streaming AI endpoint end to end, with token budget enforcement, audit logging, OpenTelemetry traces, and a rate limiting policy specific to AI operations. This is your reference implementation - every subsequent AI feature follows the same pattern.

Phase 4 - Add semantic indexing to existing entities (Week 4-6)

Identify the entities that would most benefit from semantic search. Add the semantic metadata fields to those entities (AI summary, embedding vector, last indexed at). Build the background indexing job that populates them asynchronously via domain commands. This phase does not change any existing read or write paths.

Phase 5 - Expand plugins and agents gradually (Ongoing)

Add plugins for additional domain areas one at a time. Build agents that combine multiple plugins into coherent workflows. Each agent should be narrowly scoped, fully logged, and subject to the human-in-the-loop pattern for any irreversible actions.

Current state:
  Clean Architecture with DDD + CQRS
  PostgreSQL, Redis, blob storage
  ASP.NET Core Minimal APIs

After Phase 1:
  + Semantic Kernel registered in DI
  + LLM and embedding provider configured
  + Vector store added (pgvector or Qdrant)
  + Token budget service operational
  + Audit logger operational
  + Full OTEL tracing for AI spans

After Phase 2-3:
  + First plugin wrapping existing domain service
  + First streaming AI endpoint live
  + Rate limiting on AI operations
  + Reference implementation established

After Phase 4-6:
  + Key entities semantically indexed
  + Multiple plugins across domain areas
  + Scoped agents for key workflows
  + Human-in-the-loop for irreversible actions
  + AI-native architecture fully operational

Wrapping Up

Modernizing a .NET architecture for AI-native workloads is not a replacement project - it is an evolution. The Clean Architecture principles, domain-driven design, and engineering discipline that make .NET systems reliable and maintainable are exactly the foundation you need to build AI capabilities that are trustworthy in production.

The key insight is that the AI Orchestration Layer is a new architectural concern that sits between your application layer and your AI infrastructure. It does not replace your domain model - it enriches it. It does not replace your repositories - it calls them through plugins. It does not replace your observability stack - it extends it with AI-specific metrics and traces.

The patterns covered in this article - semantic plugins, vector memory, the agent pattern, streaming responses, token budget guardrails, and the human-in-the-loop - are not theoretical. They are the patterns that production AI-native .NET systems are built on today. Each one maps cleanly to the Clean Architecture and DDD vocabulary that .NET engineers already know.

The migration path is incremental. The risk is manageable. The opportunity is extraordinary.

Start with one plugin. Ship one streaming endpoint. Build from there.

Have you already integrated Semantic Kernel or another AI framework into a .NET production system? Share your experience in the comments - the patterns the community is developing in the real world are ahead of any single article.

Resources

Semantic Kernel Documentation · Semantic Kernel GitHub · pgvector for PostgreSQL · Qdrant Vector Database · Azure AI Search Hybrid Search · OpenTelemetry .NET · ASP.NET Core Streaming with IAsyncEnumerable · Microsoft Responsible AI Principles

Modern Storage Design: How Engineers Should Think Before Writing a Single Line of Code

Elvin Suleymanov — Mon, 30 Mar 2026 18:39:17 +0000

Here is the uncomfortable truth most developers learn the hard way: storage decisions are the hardest thing to change in any system. You can refactor business logic in a sprint. You can swap a frontend framework in a week. But migrating 500 million rows from a relational database to a document store while keeping production alive? That is a multi-month ordeal that scares entire engineering teams.

Yet most storage decisions are still made casually - often in the first hour of a project, by whoever opens their laptop first and types CREATE TABLE or mongoose.connect(...).

This article changes that. We will walk through a structured, proven mental model for designing storage from scratch - before writing a single line of application code. The goal is not to pick the "best" database. The goal is to ask the right questions in the right order so you end up with a storage architecture that scales with your product, not against it.

Who is this for? Software engineers, tech leads, and architects who want a repeatable decision framework for storage design - applicable to greenfield projects, startup MVPs, and enterprise system rebuilds alike.

1. Why Storage Decisions Outlive Everything Else

Software has layers. The presentation layer is the most flexible - you can redesign a UI with a designer and a weekend. The application layer is moderately flexible - microservices, hexagonal architecture, and dependency injection all exist specifically to make business logic swappable. But the data layer is load-bearing. It holds state. Real state: user accounts, financial transactions, medical records, audit logs.

Changing it requires schema migrations that must run safely on live data, data transformation scripts with zero tolerance for bugs, coordination across every service that touches that data, and rollback plans that are often impossible to execute cleanly.

The cost of a wrong storage decision compounds over time. A startup that chooses MongoDB for a financial ledger because "it's flexible" will spend months retrofitting transactional guarantees that PostgreSQL offers for free. An enterprise that stores all events in a relational database will hit I/O walls the moment event volume spikes.

The engineers who avoid these traps share one habit: they treat storage design as a first-class design discipline, not an afterthought that happens during sprint one.

2. The Five Questions You Must Answer Before Choosing Anything

Before opening a database comparison chart, sit down and answer these five questions with your team. Write the answers down - they will drive every decision that follows.

What is the shape of your data? Is it tabular with a fixed, well-known schema? Hierarchical and document-like with optional fields? A graph of interconnected entities? Time-stamped measurements? Blobs like images, videos, and PDFs? Different shapes have different optimal engines, and forcing the wrong shape into the wrong engine is where most storage pain originates.

How will the data be accessed? List every query your system will run - not just the ones you know about on day one, but the ones your product roadmap implies. Will you look up individual records by primary key? Scan ranges? Full-text search? Aggregate across millions of rows? Traverse relationships? The access pattern list is more important than the data model.

What are your consistency requirements? If two users simultaneously update the same record, what should happen? If a payment is debited but the confirmation email fails, should the debit roll back? If you write data in one region, how quickly must it be visible in another? Different parts of the same system often have different answers to these questions.

What scale are you designing for? Not aspirationally - realistically. How many records in year one? Year three? What is the peak write rate, the peak read rate, the data retention requirement? Scale estimates let you calculate storage costs, identify partition boundaries, and decide whether you need a distributed system at all.

What are the operational constraints? What is your team's operational expertise? Who will manage the database in production? What is your disaster recovery SLA? What is your budget for managed services versus self-hosted? A technically superior storage engine that nobody on the team knows how to operate under pressure is not a good choice.

3. Data Shape: Structured, Semi-Structured, or Unstructured?

The first axis of storage design is data shape. This is the most intuitive factor, yet it is routinely ignored in favor of familiarity.

Structured data

Fixed schema, tabular, well-defined relationships between entities. Classic examples: users, orders, products, invoices, subscriptions.

CREATE TABLE users (
    id         UUID         NOT NULL PRIMARY KEY,
    email      VARCHAR(254) NOT NULL UNIQUE,
    created_at TIMESTAMPTZ  NOT NULL DEFAULT now(),
    plan_id    INT          REFERENCES plans(id)
);

CREATE TABLE orders (
    id          UUID         NOT NULL PRIMARY KEY,
    user_id     UUID         NOT NULL REFERENCES users(id),
    total_cents INT          NOT NULL,
    status      order_status NOT NULL DEFAULT 'pending'
);

This is the natural home of relational databases like PostgreSQL, MySQL, and SQL Server. The schema enforces integrity. Joins are efficient. Transactions are first class.

Semi-structured data

Variable schema, optional fields, nested hierarchies. A product catalog is a classic example - a running shoe has sizes, drop_mm, and lug_depth_mm, while an electronics product in the same catalog has voltage, wattage, and wifi_standard. A fixed relational schema would require either a massive nullable-column table or an EAV anti-pattern. A document store handles this naturally.

{
  "id": "prod_7x9k2",
  "name": "Trail Running Shoe",
  "category": "footwear",
  "attributes": {
    "sizes": [7, 8, 9, 10, 11, 12],
    "waterproof": true,
    "drop_mm": 6,
    "lug_depth_mm": 4.5
  }
}

MongoDB, CouchDB, and Firestore are the natural fit here. PostgreSQL's JSONB column type is excellent for hybrid cases where most of your data is structured but a few entities need flexibility.

Unstructured data

Raw bytes - images, videos, audio, documents, backups. These should almost never live in your application database. Your database stores only a pointer (URL or storage key). The blob store like AWS S3, Azure Blob Storage, or Google Cloud Storage handles redundancy, versioning, and CDN delivery.

Time-series data

Timestamped measurements at high ingestion rates - metrics, sensor readings, financial ticks, application logs. Relational databases handle time-series poorly at scale because they are not optimized for append-heavy workloads with time-range queries. TimescaleDB, InfluxDB, ClickHouse, and VictoriaMetrics are purpose-built for this pattern.

4. Access Patterns Are the Real Design Driver

Here is the principle most database textbooks bury in chapter twelve: design your storage around how data is read, not how it is written. Writes are a one-time cost. Reads are a recurring cost that compounds at scale.

Mapping access patterns to storage keys

Before defining any schema, build an access pattern matrix. Write down every operation your system must perform, what it takes as input, what it returns, how frequently it runs, and what latency it must meet.

#	Operation	Input	Output	Frequency	Latency SLA
1	Get user profile	`user_id`	Single user record	Very High	< 5ms
2	List orders by user	`user_id`, date range	Paginated order list	High	< 20ms
3	Full-text search products	Search query string	Ranked product list	Medium	< 100ms
4	Aggregate revenue by month	Date range	Aggregated totals	Low	< 2s
5	Get recent activity feed	`user_id`	Last 50 events	High	< 10ms
6	Find users by email	Email address	Single user record	High	< 5ms

Now examine what each row tells you. Operations 1 and 6 are primary key and unique index lookups - any database handles this trivially. Operation 2 needs a composite index on (user_id, created_at) in a relational store, or a DynamoDB partition key of user_id with a sort key of created_at. Operation 3 requires a search engine - Elasticsearch, Typesense, or Postgres full-text search for smaller datasets. Operation 4 is an OLAP query that will crush your OLTP database under load - it belongs in a read replica, a materialized view, or a dedicated analytics engine. Operation 5 is a feed: pre-computed feeds cached in Redis outperform on-demand SQL joins by orders of magnitude.

The access pattern matrix forces you to confront these separations before you have committed to a single schema.

The golden rule of storage design: every non-trivial query that runs more than once per second against more than a million rows deserves its own index, materialized view, cache, or dedicated storage engine.

5. Consistency vs. Availability: Making the CAP Trade-Off Explicit

The CAP theorem states that a distributed system can guarantee at most two of Consistency, Availability, and Partition Tolerance. Since network partitions are a physical reality in any distributed system, the practical choice is always between consistency and availability. This is not a theoretical concern - it is a product decision masquerading as a technical one.

When consistency is non-negotiable

Financial systems, inventory management, booking and reservation systems, and authentication require strong consistency. If two users simultaneously attempt to book the last seat on a flight, the system must guarantee that exactly one succeeds. Eventual consistency is not acceptable here.

-- PostgreSQL SERIALIZABLE isolation - the highest consistency guarantee
BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;

  SELECT available_seats FROM flights WHERE id = $1 FOR UPDATE;

  UPDATE flights
     SET available_seats = available_seats - 1
   WHERE id = $1
     AND available_seats > 0;

  INSERT INTO bookings (flight_id, user_id, seat) VALUES ($1, $2, $3);

COMMIT;
-- If two transactions race, one rolls back automatically. No double-booking possible.

PostgreSQL, CockroachDB, Google Spanner, and SQL Server are the right engines here.

When availability is more important

Social feeds, analytics dashboards, product recommendations, and notification systems can tolerate eventual consistency. A user seeing a like count that is two seconds out of date has no meaningful impact. Blocking a write to maintain perfect consistency in these cases wastes infrastructure and hurts user experience.

Write path:  User likes a post
             → Write to primary (DynamoDB / Cassandra)
             → Async fan-out to followers' feed caches
             → Eventual read consistency: ~1–3 seconds

Read path:   User reads their feed
             → Read from Redis cache
             → Cache miss: read from replica, populate cache
             → No blocking, no locking, no coordination overhead

DynamoDB, Cassandra, Couchbase, and Redis are well-suited to this tier.

Document the trade-off explicitly

Every team should have a written record of which parts of their system require strong consistency and why. This document prevents future engineers from "optimizing" a financial ledger by switching it to an eventually consistent store without understanding the implications.

6. Read/Write Ratio and the Architecture It Implies

The read-to-write ratio of your system predicts your scaling strategy more accurately than almost any other single metric.

Ratio	System type	Common examples	Recommended pattern
100:1+ reads	Read-heavy	News sites, product catalogs	Aggressive caching, CDN, read replicas
10:1 reads	Typical SaaS	CRM, project management	Primary + replica, Redis for hot data
1:1 balanced	Transactional	Banking, bookings, inventory	Optimize for write throughput and consistency
1:10 writes	Write-heavy	IoT telemetry, event sourcing	Append-only stores, time-series DB, Kafka
1:100+ writes	Extreme write	Financial ticks, high-frequency metrics	ClickHouse, InfluxDB, LSM-tree engines

CQRS: separating the write and read models

For systems with a lopsided read/write ratio, Command Query Responsibility Segregation is not just an academic pattern - it is a practical necessity. The write side maintains the source of truth in a transactional database. The read side maintains purpose-built projections in engines optimized for each specific read use case.

WRITE SIDE (Commands)
┌─────────────────────────────────┐
│  POST /orders                   │
│  → Validate command             │
│  → Write to PostgreSQL          │
│    (source of truth)            │
│  → Emit OrderCreated event      │
└──────────────┬──────────────────┘
               │ async event
               ▼
READ SIDE (Queries)
┌─────────────────────────────────┐
│  OrderCreated consumer          │
│  → Denormalize into             │
│    Elasticsearch (search)       │
│  → Populate Redis (feed cache)  │
│  → Update ClickHouse (analytics)│
└─────────────────────────────────┘

GET /orders?user=X  → Elasticsearch  (not PostgreSQL)
GET /dashboard      → ClickHouse     (not PostgreSQL)
GET /feed           → Redis          (not PostgreSQL)

This pattern keeps your transactional database lean and fast while giving each read use case an engine that is built exactly for it.

7. The Storage Taxonomy: Choosing the Right Engine

Relational databases

Use relational databases when your data has a fixed, well-understood schema, when relationships between entities matter, and when transactions across multiple tables are required. PostgreSQL is the right default for most greenfield projects in 2026 - it handles relational, document (JSONB), full-text search, and time-series (via TimescaleDB extension) workloads in a single engine. CockroachDB and Google Spanner are the right choice when you need globally distributed strong consistency.

Avoid relational databases when the schema changes every sprint, when write throughput exceeds roughly 50K rows per second on a single node, or when the data is fundamentally graph-shaped.

Document databases

Use document databases when schema varies across records, when data is naturally hierarchical, and when rapid iteration matters more than rigid integrity. MongoDB is the most full-featured option. PostgreSQL JSONB is the pragmatic hybrid choice - relational and document in one engine - that lets small teams avoid operational overhead without sacrificing flexibility.

Avoid document databases when you need heavy cross-document transactional integrity and when your team conflates "flexible schema" with "no schema." Document stores still require schema discipline - they just enforce it in application code rather than at the database level.

Key-value stores

Use key-value stores for sub-millisecond access to hot data by a known key: caching, session management, rate limiting counters, feature flags, and pub/sub messaging. Redis is the industry standard with its rich data structure support - sorted sets, streams, bitmaps, and hyperloglogs make it far more than a simple cache.

Avoid key-value stores when you need to query by anything other than the primary key or when data requires complex relationships.

Wide-column stores

Use wide-column stores when you need massive write throughput at scale, time-series-like access patterns, or geographically distributed writes. Apache Cassandra and ScyllaDB are the proven options. They are extraordinary at what they do and difficult to operate incorrectly, so ensure your team has Cassandra expertise or budget before choosing this path.

Search engines

Use a dedicated search engine whenever users need to search by arbitrary text, apply facets, or receive ranked results. Typesense is the right choice for most teams building in 2026 - it is simple to operate, fast, and has excellent developer ergonomics. Elasticsearch and OpenSearch offer more power for complex log analytics and enterprise-scale search. Algolia is the fastest path to production if you are on a tight timeline and have budget for a managed SaaS.

Never use a search engine as a primary database. Search indexes are derived stores that must be populated from an authoritative source and can be rebuilt from scratch if corrupted.

Graph databases

Use graph databases when your domain is fundamentally relational in the graph sense - social networks, knowledge graphs, recommendation engines, fraud detection, and dependency resolution. Neo4j and Amazon Neptune are the mature options. For fewer than a few hundred thousand nodes and edges, PostgreSQL recursive CTEs handle graph traversal efficiently without the operational overhead of a separate engine.

Time-series databases

Use time-series databases when data is append-only, timestamped, and queried by time range. TimescaleDB is the gentlest entry point - it is a PostgreSQL extension, so you get time-series performance without learning a new operational stack. ClickHouse is the right choice when you need OLAP analytics on top of the time-series data. InfluxDB and VictoriaMetrics are excellent when you need Prometheus-compatible scraping.

8. Designing for Growth: Partitioning and Sharding from Day One

You do not need to implement sharding on day one. But you need to design as if you will. The partition key you choose at the start determines whether your future horizontal scaling is straightforward or catastrophic.

The partition key is everything

A partition key is the field by which data is distributed across nodes. Choosing it incorrectly causes hotspots - one node drowning in traffic while others sit idle.

BAD partition key: created_at (date)
  All writes today go to today's partition.
  99% of traffic hits one shard. Classic hotspot.

BAD partition key: status ('pending', 'completed', 'failed')
  Only 3 possible values. All completed records on one node.

GOOD partition key: user_id (UUID)
  High cardinality. Millions of unique values.
  Writes distribute evenly. A user's data hits exactly one shard.

Design your primary key for partition-friendliness

Sequential integer primary keys are a write hotspot in distributed systems - all inserts go to the "latest" page of the B-tree index. UUID v4 solves the hotspot but makes keys non-sortable by time. UUID v7, which is time-ordered and random, gives you the best of both worlds: even distribution across shards and lexicographic sorting by creation time.

-- Anti-pattern: sequential integer - hotspot on the index leaf page
CREATE TABLE events (
    id      SERIAL PRIMARY KEY,
    user_id UUID NOT NULL,
    payload JSONB
);

-- Better: UUID v4 - random distribution, no hotspot
CREATE TABLE events (
    id      UUID DEFAULT gen_random_uuid() PRIMARY KEY,
    user_id UUID NOT NULL,
    payload JSONB
);

-- Best for distributed systems: UUIDv7 - time-ordered AND hotspot-free
CREATE TABLE events (
    id      UUID DEFAULT uuidv7() PRIMARY KEY,
    user_id UUID NOT NULL,
    payload JSONB
);

-- Multi-tenant systems: composite partition key
-- Partition by tenant, sort by time - perfect locality
CREATE TABLE events (
    tenant_id UUID NOT NULL,
    id        UUID DEFAULT uuidv7() NOT NULL,
    payload   JSONB,
    PRIMARY KEY (tenant_id, id)
) PARTITION BY HASH (tenant_id);

Write queries first, then define indexes

The most common schema design mistake is defining tables and then writing queries. Reverse the process. Write every query the system needs to execute, then add exactly the indexes those queries require.

-- Query: get a user's orders sorted newest first
CREATE INDEX idx_orders_user_created
    ON orders (user_id, created_at DESC)
    INCLUDE (status, total_cents);   -- covering index, no heap fetch needed

-- Query: admin dashboard filtered by status
CREATE INDEX idx_orders_status
    ON orders (status, created_at DESC)
    WHERE status IN ('pending', 'processing');  -- partial index, smaller and faster

9. The Polyglot Persistence Pattern

Modern systems almost never need just one storage engine. Using multiple purpose-specific databases within the same system is called polyglot persistence, and it is the architectural norm for any non-trivial product.

Here is how a mature SaaS application's storage layer typically looks:

┌──────────────────────────────────────────────────────────────────┐
│                          SaaS Platform                           │
├──────────────┬──────────────┬──────────────┬─────────────────────┤
│  Accounts &  │  Product     │  Search &    │  Analytics &        │
│  Billing     │  Catalog     │  Discovery   │  Reporting          │
│  PostgreSQL  │  MongoDB     │  Typesense   │  ClickHouse         │
│  ACID,       │  flexible    │  full-text,  │  columnar,          │
│  relations   │  schema      │  facets      │  aggregations       │
├──────────────┴──────────────┴──────────────┴─────────────────────┤
│  Sessions &     │  Media &        │  Events &       │  Cache      │
│  Auth tokens    │  File uploads   │  Audit logs     │  layer      │
│  Redis          │  S3 / Azure     │  TimescaleDB    │  Redis      │
│  sub-ms, TTL    │  Blob Storage   │  time-series    │  hot data   │
└─────────────────┴─────────────────┴─────────────────┴─────────────┘

Source of truth: PostgreSQL + Event stream (Kafka / SQS)
All other stores are derived projections, eventually consistent

The source of truth principle

In a polyglot architecture, the single most important rule is: every piece of data has exactly one authoritative source. All other copies are derived projections. If your search index and your relational database disagree on a product's price, you know which one is correct - the relational database. The search index is eventually consistent with it, and it can be rebuilt from scratch at any time.

This principle prevents the nightmare of split-brain systems where engineers are unsure which database contains the real data.

10. The Storage Design Document: A Template

Before any code is written, produce a Storage Design Document. It does not need to be long. It needs to be explicit.

# Storage Design Document

Project:  [Project Name]
Version:  1.0
Date:     [Date]
Authors:  [Names]
Status:   Draft | Reviewed | Approved

## 1. System Overview
[2–3 sentences describing what the system does and its scale expectations]

## 2. Data Inventory

| Entity          | Shape          | Size estimate   | Retention     |
|-----------------|----------------|-----------------|---------------|
| Users           | Structured     | ~1M rows/year   | Indefinite    |
| Orders          | Structured     | ~10M rows/year  | 7 years       |
| Product catalog | Semi-struct.   | ~500K docs      | Indefinite    |
| Audit events    | Time-series    | ~100M rows/year | 90 days hot   |
| Media uploads   | Unstructured   | ~5TB/year       | Indefinite    |

## 3. Access Pattern Matrix
[Full table of every read and write operation with frequency and latency SLA]

## 4. Consistency Requirements

| Domain          | Required consistency | Justification                |
|-----------------|----------------------|------------------------------|
| Payments        | Serializable         | Financial integrity           |
| Product prices  | Read committed       | Slight staleness acceptable   |
| Activity feed   | Eventual (~2s)       | UX only, no financial impact  |

## 5. Storage Engine Decisions

| Store           | Engine           | Justification                  |
|-----------------|------------------|--------------------------------|
| Primary store   | PostgreSQL 17    | ACID, relations, team expertise|
| Search          | Typesense        | Simple, fast, managed          |
| Cache           | Redis 8          | Sub-ms reads, TTL support      |
| Media           | AWS S3           | Durability, CDN integration    |
| Metrics         | TimescaleDB      | PostgreSQL extension, low ops  |

## 6. Partition Strategy
[Describe partition keys, sharding approach, and growth triggers]

## 7. Backup and Recovery
RPO (Recovery Point Objective): [e.g. 1 hour]
RTO (Recovery Time Objective): [e.g. 4 hours]
Backup strategy: [e.g. daily snapshots + WAL streaming]

## 8. Open Questions
[Decisions deferred for later, each with an owner and resolution deadline]

11. Common Anti-Patterns and How to Avoid Them

The God Table

Every entity lives in a single table with 80 columns, most of them NULL for most records. This usually results from "we'll add columns as we go" thinking during a fast-moving sprint zero. The table becomes unmaintainable and query performance degrades as the row size explodes.

The fix is to normalize correctly from the start. Use PostgreSQL table partitioning for large-volume entities and JSONB columns for genuinely variable attributes - that way you get schema discipline where you need it and flexibility where the domain demands it.

Using the Application Database for Everything

Using PostgreSQL for full-text search at scale, session storage, rate limiting counters, file storage, analytics aggregations, and event streaming simultaneously. The database becomes a bottleneck across every concern because it was never designed to be all of these things at once.

The fix is polyglot persistence. The application database owns transactional writes. Purpose-built engines own everything else. Each engine is sized and scaled independently.

The N+1 Schema Design

Designing a schema that makes the most natural query an N+1 - one query to fetch a list, then one query per row to fetch related data - and then adding caching to paper over the resulting performance problem. The cache masks the symptom without fixing the cause, and the latency spike returns the moment the cache is cold.

The fix is to design schemas and indexes so that common read operations are satisfiable in a single query. Joins, covering indexes, and materialized views all exist for this purpose. Run EXPLAIN ANALYZE on every query that touches more than a thousand rows before calling the schema done.

Premature Sharding

Implementing a sharded database cluster on day one for a product with 200 users because "we might need to scale." Sharding adds massive operational complexity - cross-shard transactions become coordination nightmares, and debugging a distributed write failure is orders of magnitude harder than debugging a single-node one.

The fix is to design your partition keys correctly from the start so that future sharding is a straightforward horizontal operation, but run on a single node until you have a measured, concrete reason to distribute. "It might be slow someday" is not a measured reason.

No Migration Strategy

Treating schema changes as a one-time ALTER TABLE executed manually on the production database by whoever has DBA access that day. This approach guarantees eventual disaster - a missed migration on a new environment, a rollback that left the schema in an inconsistent state, or a destructive change that had no approval process.

The fix is to treat every schema change as a versioned migration file checked into source control, executed by an automated tool like Flyway, Liquibase, EF Core Migrations, or Alembic, and tested against a production-like dataset before deployment.

Storing Secrets and PII Without Thought

Storing passwords in plaintext, API keys in a config table, or personally identifiable information in the same tables as operational data with no additional access controls. This is both a security vulnerability and, in most jurisdictions, a regulatory compliance failure.

The fix is to hash passwords with bcrypt or Argon2, store secrets in a secrets manager such as AWS Secrets Manager or HashiCorp Vault, encrypt PII at the column level, and isolate sensitive data in a dedicated store with strict RBAC policies and audit logging on every access.

12. A Real-World Walkthrough: Designing Storage for a SaaS Platform

Let us apply the entire framework to a concrete example: a B2B project management SaaS, think a lightweight Jira. Here is the process from scratch.

Step 1 - Answer the five questions

The data is mostly structured: workspaces, users, projects, tasks, and comments. Custom task fields per project template make one entity semi-structured. Access patterns include reading a user's task list, searching tasks by text, displaying a project activity feed, exporting project data, and aggregating team velocity metrics for reporting.

Consistency requirements split cleanly - task creation and assignment must be consistent since conflicts here would corrupt project state, while the activity feed can be eventually consistent. Scale targets are 500 paying teams at launch growing to 10,000 in 18 months, roughly 50 million tasks at scale and around 1 billion activity events per year.

The team is small - four engineers - so managed cloud services are strongly preferred and PostgreSQL expertise already exists on the team.

Step 2 - Select engines based on the access pattern matrix

Operation	Frequency	Latency SLA	Notes
List tasks in project	Very High	< 30ms	Filtered by status and assignee
Get task detail	Very High	< 10ms	With comments and attachments
Search tasks by text	High	< 200ms	Cross-project for enterprise tier
Get activity feed	High	< 50ms	Last 100 events per user
Export project to CSV	Low	< 10s	Async background job
Velocity report	Low	< 3s	Aggregate closed tasks by sprint

The access pattern matrix leads to the following engine decisions. PostgreSQL 17 on Supabase handles all structured data - workspaces, users, projects, tasks, and comments - as the source of truth. A JSONB column on the tasks table covers custom fields per project template without needing a separate document store at this scale. Typesense provides cross-project full-text task search, synced from PostgreSQL via a change-data-capture worker. Redis on Upstash stores pre-computed activity feeds per user (last 100 events) and session tokens. S3-compatible object storage holds task attachments with PostgreSQL storing only the key. Velocity reports are served by materialized views in PostgreSQL, refreshed nightly.

Step 3 - Design the schema for growth

-- Multi-tenant task table partitioned by workspace
CREATE TABLE tasks (
    id            UUID DEFAULT uuidv7() NOT NULL,
    workspace_id  UUID NOT NULL,
    project_id    UUID NOT NULL,
    title         TEXT NOT NULL,
    status        task_status NOT NULL DEFAULT 'todo',
    assignee_id   UUID,
    custom_fields JSONB,
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (workspace_id, id)
) PARTITION BY HASH (workspace_id);

-- 16 hash partitions - right-sized for expected tenant growth
CREATE TABLE tasks_p0  PARTITION OF tasks FOR VALUES WITH (modulus 16, remainder 0);
CREATE TABLE tasks_p1  PARTITION OF tasks FOR VALUES WITH (modulus 16, remainder 1);
-- tasks_p2 through tasks_p15 follow the same pattern

-- Composite index supports the most frequent read operation
CREATE INDEX idx_tasks_project_status
    ON tasks (workspace_id, project_id, status, created_at DESC);

-- Partial index for assignee queries - excludes unassigned tasks
CREATE INDEX idx_tasks_assignee
    ON tasks (workspace_id, assignee_id, status)
    WHERE assignee_id IS NOT NULL;

The workspace_id as the partition key ensures that one large enterprise customer's data is physically isolated and their heavy queries do not scan partitions belonging to other tenants.

Step 4 - Document and review

The final step is producing the Storage Design Document, getting it reviewed by at least one engineer who was not involved in writing it, and resolving any open questions before the first migration runs. A fresh pair of eyes catches access patterns you forgot and consistency requirements you underspecified.

13. The Decision Checklist

Use this before committing to any storage architecture.

Discovery phase: Have you answered the five questions and written down the answers? Is the access pattern matrix complete? Are consistency requirements mapped per domain? Have you calculated scale estimates for rows, bytes, and requests per second? Have you identified operational constraints including team skills, budget, and SLAs?

Design decisions: Has every data entity been assigned to a storage engine with a documented justification? Have you identified the source of truth for every entity? Have you designed partition and sharding keys even if you are not implementing sharding yet? Has an index strategy been defined for every access pattern? Have backup, RPO, and RTO been defined?

Anti-pattern checks: Are there any God Tables? Is the application database being asked to serve as a search engine, cache, or analytics platform? Is any sharding premature? Has schema migration tooling been selected and configured? Has PII and secrets handling been defined?

Review gate: Is the Storage Design Document written? Has it been reviewed by at least one team member not involved in the design? Have open questions been listed with owners and resolution deadlines? Has the decision been approved by the tech lead or architect?

Wrapping Up

Great storage design is not about picking the trendiest database. It is about asking disciplined questions before the excitement of writing code takes over.

The engineers and teams that avoid expensive storage migrations share a common discipline. They slow down before sprint one. They build an access pattern matrix. They make their consistency trade-offs explicit. They write a Storage Design Document that everyone can refer back to. They design for the partition key they will need in year three even if they do not implement sharding until year two. They embrace polyglot persistence instead of forcing every use case into a single engine.

The cost of this upfront discipline is a few hours. The cost of skipping it is months of painful migrations, performance emergencies, and architectural debt that compounds every quarter.

Design the storage first. Then write the code.

Found this useful? Share it with your team before your next greenfield project starts. Drop your own storage war stories in the comments - every anti-pattern you have survived is a lesson someone else needs to hear.

Supercharge Your APIs: ASP.NET Core + C# 14 Features You Must Know in 2026

Elvin Suleymanov — Fri, 27 Mar 2026 10:46:03 +0000

The .NET ecosystem is on a relentless upward trajectory, and 2026 is no exception. ASP.NET Core paired with C# 14 raises the bar once again - delivering sharper syntax, fearless performance, and first-class cloud-native primitives that make building modern APIs genuinely enjoyable.

In this article we'll cut straight to the features that matter most, with real, production-ready code you can adopt today. No fluff, no filler - just signal.

Who is this for? Mid-to-senior .NET developers who want to ship faster, leaner, and more maintainable APIs in 2026.

C# 14 - The Language Hits a New Gear
Implicit Span Conversions & Zero-Alloc Pipelines
Extension Everything - Methods, Properties, Indexers
Nullable-Improved Patterns and the ?[] Null-Conditional Index
ASP.NET Core 10 - What's New in the Pipeline
Minimal APIs: Typed Route Constraints + Streaming JSON
Blazor United Goes Full Stack
Native AOT + R2R Hybrid: The Best of Both Worlds
Built-in Rate Limiting - Smarter Policies
Real-World Benchmark: .NET 8 → .NET 10
Migration Checklist

1. C# 14 - The Language Hits a New Gear

C# 14 ships inside the .NET 10 SDK (GA: November 2026, Preview available now). The headline theme is reducing cognitive overhead - the language gets smarter so you can think about your domain, not boilerplate.

Key additions at a glance:

Feature	What it solves
Implicit span conversions	Zero-alloc string/array APIs without casting
Extension properties & indexers	Richer domain models without inheritance
`field` keyword (stable)	Validated auto-properties, no backing field
`params` on any collection (stable)	Stack-allocated variadics
Partial properties	Split property declarations across files
`nameof` in attributes	Compile-safe attribute arguments

2. Implicit Span Conversions & Zero-Alloc Pipelines

One of the most impactful C# 14 changes is implicit conversions between string, char[], and ReadOnlySpan<char>. This single change quietly eliminates dozens of .AsSpan() calls littered across hot paths.

// C# 13 - explicit, noisy
ReadOnlySpan<char> ParseSegment(string input)
    => input.AsSpan().Trim();  // .AsSpan() required

// C# 14 - implicit, clean
ReadOnlySpan<char> ParseSegment(string input)
    => ((ReadOnlySpan<char>)input).Trim();  // implicit now, cast optional

// Even cleaner when the target type is already known:
void Process(ReadOnlySpan<char> data) { /* ... */ }

Process("hello world");   // ✅ C# 14 - string implicitly converts
Process(myCharArray);     // ✅ C# 14 - char[] implicitly converts

Why does this matter in APIs?

JSON serialization, header parsing, and query-string processing all deal with spans internally. With C# 14, your custom middleware and filters can opt into span APIs without polluting call sites with casts:

// High-throughput header validator - zero allocation
public static bool TryValidateCorrelationId(
    IHeaderDictionary headers,
    out ReadOnlySpan<char> correlationId)
{
    if (!headers.TryGetValue("X-Correlation-ID", out var value))
    {
        correlationId = default;
        return false;
    }

    // C# 14: StringValues implicitly yields ReadOnlySpan<char>
    correlationId = ((string?)value)?.Trim() ?? default;
    return correlationId.Length == 36; // UUID length check
}

Pro tip: Pair implicit span conversions with [SkipLocalsInit] on hot-path methods to squeeze out the last few nanoseconds in your request pipeline.

3. Extension Everything - Methods, Properties, Indexers

C# 14 dramatically expands the extension member system. You can now write extension properties, extension indexers, and static extension members - not just methods. This is a game-changer for clean domain modeling without inheritance chains.

// Define extensions in a dedicated file - clean separation of concerns
public extension HttpContextExtensions for HttpContext
{
    // Extension property - no more helper method calls
    public string TraceId => this.TraceIdentifier;

    public bool IsAuthenticated => this.User?.Identity?.IsAuthenticated == true;

    // Extension indexer - treat headers like a dictionary
    public string? this[string headerName]
        => this.Request.Headers.TryGetValue(headerName, out var val)
            ? val.ToString()
            : null;

    // Static extension factory
    public static HttpContext CreateTestContext(string path = "/")
    {
        var ctx = new DefaultHttpContext();
        ctx.Request.Path = path;
        return ctx;
    }
}

// Usage - reads like first-class properties
app.Use(async (ctx, next) =>
{
    var traceId  = ctx.TraceId;           // extension property
    var authd    = ctx.IsAuthenticated;   // extension property
    var agent    = ctx["User-Agent"];     // extension indexer

    await next(ctx);
});

This eliminates the proliferation of static helper classes (HttpContextHelper, RequestExtensions, ClaimsPrincipalUtils) that clutter every enterprise codebase.

4. Nullable-Improved Patterns and the `?[]` Null-Conditional Index

C# 14 extends null-conditional syntax to indexers and collection expressions:

// Old - verbose null guards
var first = list != null && list.Count > 0 ? list[0] : null;

// C# 14 - null-conditional index
var first = list?[0];           // already existed
var matrix = grid?[row]?[col]; // now works for nested indexers too

// New: null-conditional with collection expressions
string[]? tags = GetTags();
var primary = tags?[0] ?? "untagged";

// Pattern matching improvements - and patterns now short-circuit
if (request is { Method: "POST", ContentLength: > 0 and < 10_000_000 })
{
    // safe to read body
}

// List patterns inside switch expressions
var category = items.Count switch
{
    0           => "empty",
    1           => "single",
    [.., > 100] => "large",   // list pattern - last element > 100
    _           => "normal"
};

In API middleware these patterns dramatically reduce guard clause noise, especially when processing nullable JSON payloads:

app.MapPost("/orders", (OrderRequest? req) =>
{
    // Exhaustive, readable pattern match
    return req switch
    {
        null                          => Results.BadRequest("Payload required"),
        { Items: [] }                 => Results.UnprocessableEntity("No items"),
        { Items: [.., { Qty: <= 0 }]} => Results.UnprocessableEntity("Invalid quantity"),
        _                             => Results.Accepted()
    };
});

5. ASP.NET Core 10 - What's New in the Pipeline

ASP.NET Core 10 (shipping with .NET 10, November 2026) focuses on three pillars: performance, observability, and developer ergonomics.

Automatic `ProblemDetails` for all errors

You no longer need to configure AddProblemDetails() manually. ASP.NET Core 10 returns RFC 9457-compliant ProblemDetails responses for all unhandled exceptions and status codes by default:

// .NET 9 - you had to wire this up
builder.Services.AddProblemDetails();
app.UseExceptionHandler();
app.UseStatusCodePages();

// .NET 10 - it just works out of the box
// The above three lines are now the default behavior.
// Customize only when you need to:
builder.Services.AddProblemDetails(opts =>
{
    opts.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Extensions["traceId"] =
            ctx.HttpContext.TraceIdentifier;

        ctx.ProblemDetails.Extensions["environment"] =
            ctx.HttpContext.RequestServices
               .GetRequiredService<IWebHostEnvironment>().EnvironmentName;
    };
});

OpenAPI 3.1 schema improvements

The built-in OpenAPI generator (introduced in .NET 9) now supports discriminators, polymorphic schemas, and $ref de-duplication out of the box:

// Register a polymorphic hierarchy automatically
builder.Services.AddOpenApi(opts =>
{
    opts.AddSchemaTransformer<PolymorphicSchemaTransformer>();
});

// The discriminator is inferred from [JsonDerivedType]
[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")]
[JsonDerivedType(typeof(CardPayment),   "card")]
[JsonDerivedType(typeof(CryptoPayment), "crypto")]
[JsonDerivedType(typeof(BankPayment),   "bank")]
public abstract record Payment(decimal Amount);

public record CardPayment(decimal Amount, string Last4)   : Payment(Amount);
public record CryptoPayment(decimal Amount, string Wallet): Payment(Amount);
public record BankPayment(decimal Amount, string Iban)    : Payment(Amount);

Keyed services in Minimal API parameters

Keyed DI (introduced in .NET 8) now works natively as Minimal API parameters:

builder.Services.AddKeyedSingleton<ICache, RedisCache>("distributed");
builder.Services.AddKeyedSingleton<ICache, MemoryCache>("local");

// Inject keyed service directly from route handler - no [FromServices] hack
app.MapGet("/data/{key}", async (
    string key,
    [FromKeyedServices("distributed")] ICache cache,
    CancellationToken ct) =>
{
    var value = await cache.GetAsync(key, ct);
    return value is null ? Results.NotFound() : Results.Ok(value);
});

6. Minimal APIs: Typed Route Constraints + Streaming JSON

Custom typed route constraints

// Register a reusable constraint
builder.Services.AddRouting(opts =>
    opts.ConstraintMap["sku"] = typeof(SkuRouteConstraint));

public sealed class SkuRouteConstraint : IRouteConstraint
{
    // SKU format: ABC-12345
    private static readonly Regex Pattern =
        new(@"^[A-Z]{3}-\d{5}$", RegexOptions.Compiled);

    public bool Match(HttpContext? ctx, IRouter? route,
                      string routeKey, RouteValueDictionary values,
                      RouteDirection direction)
        => values.TryGetValue(routeKey, out var raw)
           && Pattern.IsMatch(raw?.ToString() ?? "");
}

// Usage - clean, self-documenting routes
app.MapGet("/products/{sku:sku}", async (string sku, IProductService svc)
    => await svc.GetBySkuAsync(sku) is { } p
        ? TypedResults.Ok(p)
        : TypedResults.NotFound());

Streaming JSON responses with `IAsyncEnumerable`

app.MapGet("/feed/events", (IEventStore store, CancellationToken ct)
    => store.StreamEventsAsync(ct));  // Returns IAsyncEnumerable<Event>

// ASP.NET Core 10 automatically streams NDJSON (newline-delimited JSON)
// Each event is flushed as it arrives - perfect for dashboards & feeds

public interface IEventStore
{
    IAsyncEnumerable<Event> StreamEventsAsync(CancellationToken ct);
}

// Client-side (JS fetch API with streaming)
// const res = await fetch('/feed/events');
// for await (const chunk of res.body) { ... }

Pro tip: Streaming IAsyncEnumerable<T> is now the preferred pattern over SignalR for simple server-push scenarios. It requires no WebSocket infrastructure and works perfectly through HTTP/2.

7. Blazor United Goes Full Stack

Blazor's unified model (introduced in .NET 8, matured in .NET 9) reaches full stability in .NET 10. The render mode system is now effortless:

@* Pages/ProductDetail.razor *@
@page "/products/{Id:int}"
@attribute [StreamRendering]           @* Server-side streaming SSR *@
@rendermode InteractiveAuto            @* Upgrades to WASM after first load *@

<h1>@product?.Name</h1>

@if (product is null)
{
    <p>Loading...</p>
}
else
{
    <PriceWidget Price="@product.Price" @rendermode="InteractiveWebAssembly" />
    <ReviewList ProductId="@Id"         @rendermode="InteractiveServer" />
}

@code {
    [Parameter] public int Id { get; set; }
    private Product? product;

    protected override async Task OnInitializedAsync()
        => product = await ProductService.GetByIdAsync(Id);
}

With InteractiveAuto, Blazor renders on the server for instant first-paint, then silently hydrates to WebAssembly - giving you the speed of SSR and the interactivity of SPA, automatically.

8. Native AOT + R2R Hybrid: The Best of Both Worlds

Full Native AOT is great for microservices but requires significant trade-offs (no reflection, limited dynamic code). .NET 10 introduces a hybrid publishing model that combines ReadyToRun (R2R) pre-JIT with selective AOT for hot paths:

<!-- .csproj -->
<PropertyGroup>
  <!-- Hybrid: AOT hot paths, R2R everything else -->
  <PublishReadyToRun>true</PublishReadyToRun>
  <TieredPGO>true</TieredPGO>
  <EnableUnsafeBinaryFormatterSerialization>false</EnableUnsafeBinaryFormatterSerialization>
</PropertyGroup>

<ItemGroup>
  <!-- Mark specific assemblies for full AOT -->
  <TrimmerRootAssembly Include="MyApp.HotPath" />
</ItemGroup>

// Annotate methods for AOT compilation hints
[DynamicDependency(DynamicallyAccessedMemberTypes.All, typeof(OrderProcessor))]
public static void RegisterHandlers(IServiceCollection services)
{
    services.AddScoped<IOrderHandler, OrderProcessor>();
}

// Trim-safe source-generated serialization (required for full AOT paths)
[JsonSerializable(typeof(Order))]
[JsonSerializable(typeof(OrderResult))]
[JsonSerializable(typeof(ProblemDetails))]
internal partial class AppJsonContext : JsonSerializerContext { }

Performance profile (4-core container, 512MB RAM)

Mode	Startup	Memory	Throughput	Binary
.NET 8 JIT	210ms	78MB	1.9M req/s	180MB
.NET 10 JIT + PGO	155ms	65MB	2.8M req/s	178MB
.NET 10 R2R Hybrid	45ms	42MB	2.6M req/s	95MB
.NET 10 Full AOT	7ms	26MB	2.5M req/s	11MB

Choose wisely: Use Full AOT for stateless microservices and sidecar proxies. Use R2R Hybrid for complex apps with reflection-heavy libraries (EF Core, AutoMapper, etc.).

9. Built-in Rate Limiting - Smarter Policies

Rate limiting shipped in .NET 7. In .NET 10, it gains per-user token bucket policies, adaptive limits, and native integration with the OpenAPI spec:

builder.Services.AddRateLimiter(opts =>
{
    opts.RejectionStatusCode = StatusCodes.Status429TooManyRequests;

    // Sliding window per authenticated user
    opts.AddPolicy("per-user", ctx =>
    {
        var userId = ctx.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value
                     ?? ctx.Connection.RemoteIpAddress?.ToString()
                     ?? "anonymous";

        return RateLimitPartition.GetSlidingWindowLimiter(userId, _ =>
            new SlidingWindowRateLimiterOptions
            {
                PermitLimit          = 100,
                Window               = TimeSpan.FromMinutes(1),
                SegmentsPerWindow    = 6,      // 10-second buckets
                QueueProcessingOrder = QueueProcessingOrder.OldestFirst,
                QueueLimit           = 10
            });
    });

    // Generous policy for premium tier
    opts.AddPolicy("premium", ctx =>
        RateLimitPartition.GetTokenBucketLimiter(
            ctx.User!.FindFirstValue(ClaimTypes.NameIdentifier)!,
            _ => new TokenBucketRateLimiterOptions
            {
                TokenLimit          = 1000,
                ReplenishmentPeriod = TimeSpan.FromSeconds(10),
                TokensPerPeriod     = 100,
                AutoReplenishment   = true
            }));

    // Global concurrency limiter as a safety net
    opts.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(ctx =>
        RateLimitPartition.GetConcurrencyLimiter("global",
            _ => new ConcurrencyLimiterOptions { PermitLimit = 500 }));
});

app.UseRateLimiter();

// Apply per endpoint
app.MapPost("/api/checkout", CheckoutHandler)
   .RequireRateLimiting("per-user");

app.MapGet("/api/analytics/stream", AnalyticsHandler)
   .RequireRateLimiting("premium");

10. Real-World Benchmark: .NET 8 → .NET 10

Testing environment: Azure Container Apps, 2 vCPU, 4GB RAM, 500 concurrent users, 60-second run, Bombardier load tester.

Metric	.NET 8	.NET 9	.NET 10	Δ (8→10)
Startup time	210ms	175ms	45ms (R2R)	-79%
P50 latency	4.2ms	3.8ms	2.9ms	-31%
P99 latency	22ms	18ms	11ms	-50%
Throughput	1.9M req/s	2.2M req/s	2.8M req/s	+47%
Memory (idle)	78MB	68MB	42MB (R2R)	-46%
GC pause (P99)	8.2ms	6.1ms	3.4ms	-59%
Docker image	215MB	195MB	95MB (R2R)	-56%

These numbers reflect a real Minimal API service with EF Core (PostgreSQL), Redis caching, and structured logging via Serilog. Your mileage will vary, but the trend is unmistakable.

11. Migration Checklist

Use this as your upgrade checklist when moving an existing API to .NET 10 + C# 14:

UPGRADE CHECKLIST: .NET 10 + C# 14
====================================

Project setup
  [ ] Update TargetFramework to net10.0
  [ ] Set <LangVersion>14</LangVersion> (or preview)
  [ ] Update all NuGet packages
  [ ] Run dotnet-upgrade-assistant for automated fixes

C# 14 quick wins
  [ ] Replace .AsSpan() call sites with implicit conversions
  [ ] Migrate static helper classes to extension properties/indexers
  [ ] Adopt field keyword in validated auto-properties
  [ ] Convert null guard clauses to null-conditional index ?[]
  [ ] Simplify switch expressions with list patterns

ASP.NET Core 10
  [ ] Remove manual AddProblemDetails() - now default
  [ ] Remove Swashbuckle - use built-in OpenAPI generator
  [ ] Add Scalar.AspNetCore for API explorer UI
  [ ] Switch to [FromKeyedServices] for keyed DI in endpoints
  [ ] Enable IAsyncEnumerable streaming on collection endpoints

Performance
  [ ] Enable TieredPGO in csproj
  [ ] Profile with dotnet-trace before and after
  [ ] Evaluate Full AOT vs R2R Hybrid per service
  [ ] Add source-gen JSON contexts for hot serialization paths
  [ ] Run BenchmarkDotNet suite on critical paths

Observability
  [ ] Adopt OpenTelemetry .NET 2.0 SDK
  [ ] Add traceId to ProblemDetails extensions
  [ ] Enable metrics export to Prometheus / Azure Monitor

Wrapping Up

C# 14 and ASP.NET Core 10 together represent the most impactful .NET release since .NET 6 launched the modern unified platform. Whether you're building a high-traffic public API, an internal microservice, or a full-stack Blazor application, the improvements are broad and deep.

The key takeaways:

Implicit span conversions and extension properties make your codebase dramatically cleaner without sacrificing performance.
Native AOT + R2R Hybrid finally gives teams a practical path to sub-10ms cold starts without rewriting their entire app.
ASP.NET Core 10's zero-config ProblemDetails and OpenAPI dramatically reduce the framework ceremony tax.
Streaming IAsyncEnumerable<T> is the new standard for server-push patterns - simpler than SignalR, HTTP-native, and effortlessly scalable.

The .NET platform has never been faster, leaner, or more expressive. There's no better time to upgrade.

Found this useful? Share it with your team, drop your benchmark results in the comments, and follow me for more deep-dive .NET content.

Resources

RAG Architecture Patterns in .NET: From Naive to Production-Grade

Elvin Suleymanov — Thu, 26 Mar 2026 13:59:30 +0000

Your AI model is brilliant. It can write essays, analyze data, and hold conversations that feel human. But ask it about your company's internal documentation, last quarter's sales numbers, or the return policy you updated yesterday, and it fails. Not because it is stupid. Because it does not know.

Large language models only know what was in their training data. Your private documents, your proprietary databases, your recent updates: none of it exists in the model's world. Fine-tuning is expensive, slow, and inflexible. Every time your data changes, you would need to retrain.

Retrieval-Augmented Generation solves this. Instead of teaching the model your data, you fetch the relevant data at query time and hand it to the model alongside the question. The model generates a response grounded in real, current information from your systems.

RAG is not a framework. It is not a library. It is an architecture pattern. And the .NET ecosystem in 2026 has everything you need to implement it at production scale.

This article walks through the entire journey. We start with what RAG actually is. We build a naive implementation. Then we make it production-grade, covering chunking strategies, embedding generation, vector storage, hybrid search, and the architectural patterns that make RAG maintainable in enterprise .NET applications.

What RAG Actually Is

RAG has three letters and five stages. Here is what happens when a user asks a question:

1. The user asks a question. "What is our refund policy for digital products?"

2. The question gets embedded. An embedding model converts the question into a vector: a high-dimensional array of numbers that represents the meaning of the question.

3. Relevant documents are retrieved. The system searches a vector database for documents whose embeddings are similar to the question's embedding. It returns the top 5 or 10 most relevant chunks.

4. The context is injected into the prompt. The retrieved chunks are added to the prompt alongside the user's question. The model now has the original question plus the relevant context.

5. The model generates a grounded response. Instead of guessing or hallucinating, the model answers based on the retrieved context. It can cite sources, quote specific passages, and admit when the context does not contain the answer.

That is the entire pattern. Embed, retrieve, inject, generate. Everything else is optimization.

The Naive Implementation

Let us build the simplest possible RAG pipeline in .NET. No frameworks, no magic. Just the raw pattern.

// The simplest RAG pipeline you can write

var embedder = new OpenAIEmbeddingGenerator(
    "text-embedding-3-small", apiKey);
var chatClient = new OpenAIChatClient("gpt-4o", apiKey);

// 1. Your "database" of documents
var documents = new List<(string Text, float[] Vector)>();

// 2. Index a document
var docText = "Digital products are non-refundable after " +
    "download. Customers may request a refund within " +
    "24 hours of purchase if the product has not been " +
    "downloaded.";
var docVector = await embedder.GenerateVectorAsync(docText);
documents.Add((docText, docVector));

// 3. User asks a question
var question = "Can I get a refund on a digital purchase?";
var questionVector = await embedder
    .GenerateVectorAsync(question);

// 4. Find the most similar document (cosine similarity)
var bestMatch = documents
    .OrderBy(d => CosineDistance(questionVector, d.Vector))
    .First();

// 5. Build the prompt with context
var prompt = $"""
    Answer the question based on the context below.
    If the context does not contain the answer, say
    "I don't know."

    Context:
    {bestMatch.Text}

    Question: {question}
    """;

// 6. Generate response
var response = await chatClient.GetResponseAsync(prompt);
Console.WriteLine(response.Text);

This works. The model gets the refund policy document as context and answers accurately. But this naive approach has problems that become obvious at scale.

Problem 1: Documents are too big. A 50-page PDF does not fit in the model's context window. You need to split documents into smaller chunks.

Problem 2: In-memory storage. A list of tuples does not survive a restart, does not scale, and does not support metadata filtering.

Problem 3: No relevance threshold. The system always returns something, even when nothing is relevant.

Problem 4: Single embedding model. If the provider changes pricing or goes down, everything breaks.

Let us fix all of these.

Stage 1: Chunking — Splitting Documents Intelligently

Before you can embed documents, you need to split them into chunks that fit in the model's context window and are semantically coherent. This is the single most impactful decision in a RAG pipeline.

Chunking Strategies

Fixed-size chunking. Split every N tokens. Simple, predictable, but can break mid-sentence or mid-paragraph. A chunk about refund policy might end with "customers may request a" and the next chunk starts with "refund within 24 hours." Neither chunk is useful alone.

Paragraph-based chunking. Split on double newlines. Preserves natural semantic units, but paragraphs vary wildly in size. A one-sentence paragraph wastes embedding capacity. A five-page paragraph defeats the purpose.

Recursive chunking. Try to split on paragraphs first. If a paragraph is too big, split on sentences. If a sentence is too big, split on tokens. This is the best default for most use cases.

Semantic chunking. Use embedding similarity to detect topic boundaries. When the embedding of consecutive sentences diverges sharply, that is a chunk boundary. Produces the most coherent chunks but is computationally expensive.

Implementation with Semantic Kernel's TextChunker

using Microsoft.SemanticKernel.Text;

// Load your document
var documentText = await File.ReadAllTextAsync(
    "refund-policy.md");

// Recursive chunking: paragraphs first, then lines
var lines = TextChunker.SplitPlainTextLines(
    documentText, maxTokensPerLine: 128);

var chunks = TextChunker.SplitPlainTextParagraphs(
    lines,
    maxTokensPerParagraph: 256,
    overlapTokens: 32);

// Each chunk is now 128-256 tokens with 32-token
// overlap between consecutive chunks

The overlap parameter is important. A 32-token overlap means consecutive chunks share context at their boundaries, so information that spans a chunk boundary is not lost entirely. Typical overlap is 10-15% of the chunk size.

How Big Should Chunks Be

There is no universal answer, but here is what works in practice:

128-256 tokens for factual Q&A (support docs, FAQs, policies). Small chunks mean more precise retrieval.

256-512 tokens for analytical content (reports, articles, research). Larger chunks preserve more context for complex reasoning.

512-1024 tokens for code documentation and tutorials. Code blocks need surrounding explanation to make sense.

Start with 256 tokens and adjust based on retrieval quality.

Stage 2: Embedding — Converting Text to Vectors

Each chunk needs to be converted to a vector that captures its semantic meaning. The choice of embedding model determines the quality of your retrieval.

Using Microsoft.Extensions.AI

using Microsoft.Extensions.AI;

// Register in DI (provider-agnostic)
builder.Services.AddEmbeddingGenerator(
    new OpenAIClient(apiKey)
    .GetEmbeddingClient("text-embedding-3-small")
    .AsIEmbeddingGenerator());

The IEmbeddingGenerator<string, Embedding<float>> abstraction means you can switch providers without changing your RAG code.

Embedding Models Compared

OpenAI text-embedding-3-small. 1536 dimensions. Good quality, low cost. Best default for most .NET applications.

OpenAI text-embedding-3-large. 3072 dimensions. Higher quality, higher cost and storage. Use when precision matters more than cost.

Local models via Ollama (mxbai-embed-large). 1024 dimensions. Runs on your machine. Zero API cost. Good for development and privacy-sensitive deployments.

Azure OpenAI. Same models as OpenAI, but deployed in your Azure tenant. Best for enterprise compliance requirements.

Batch Embedding

Never embed one chunk at a time in production. Batch calls reduce latency and cost:

public async Task<List<(string Text, float[] Vector)>>
    EmbedChunksAsync(
        List<string> chunks,
        IEmbeddingGenerator<string,
            Embedding<float>> embedder)
{
    var results = new List<(string, float[])>();

    // Process in batches of 100
    foreach (var batch in chunks.Chunk(100))
    {
        var embeddings = await embedder
            .GenerateAsync(batch.ToList());

        for (int i = 0; i < batch.Length; i++)
        {
            results.Add((
                batch[i],
                embeddings[i].Vector.ToArray()));
        }
    }

    return results;
}

Stage 3: Storage — Where Your Vectors Live

You have three options in the .NET ecosystem, each with different trade-offs.

Option A: EF Core 10 with SQL Server 2025

If you already use SQL Server, this is the simplest path. No new infrastructure.

public class DocumentChunk
{
    public int Id { get; set; }
    public string Text { get; set; } = "";
    public string Source { get; set; } = "";
    public string Category { get; set; } = "";
    public DateTime IndexedAt { get; set; }

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

// Query
var results = await db.Chunks
    .Where(c => c.Category == "policies")
    .OrderBy(c => EF.Functions.VectorDistance(
        "cosine", c.Embedding, queryVector))
    .Take(5)
    .ToListAsync();

Best for: datasets under 10 million vectors, existing SQL Server infrastructure, applications that need joins and transactions alongside vector search.

Option B: Microsoft.Extensions.VectorData

A provider-agnostic abstraction that works with Azure AI Search, Qdrant, Cosmos DB, Redis, Weaviate, and an in-memory implementation for testing.

using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.InMemory;

// Define your record
public class DocChunk
{
    [VectorStoreRecordKey]
    public string Id { get; set; } = "";

    [VectorStoreRecordData]
    public string Text { get; set; } = "";

    [VectorStoreRecordData]
    public string Source { get; set; } = "";

    [VectorStoreRecordVector(1536)]
    public ReadOnlyMemory<float> Embedding { get; set; }
}

// Create a collection
var vectorStore = new InMemoryVectorStore();
var collection = vectorStore
    .GetCollection<string, DocChunk>("documents");
await collection.CreateCollectionIfNotExistsAsync();

// Upsert a record
await collection.UpsertAsync(new DocChunk
{
    Id = Guid.NewGuid().ToString(),
    Text = chunkText,
    Source = "refund-policy.md",
    Embedding = embeddingVector
});

// Search
var searchResults = await collection
    .VectorizedSearchAsync(queryVector,
        new VectorSearchOptions { Top = 5 });

await foreach (var result in searchResults.Results)
{
    Console.WriteLine(
        $"{result.Score}: {result.Record.Text}");
}

Best for: applications that may switch vector backends, teams using Semantic Kernel, multi-backend architectures.

Option C: Kernel Memory

Microsoft's out-of-the-box RAG solution. Handles the entire pipeline: document ingestion, chunking, embedding, storage, and retrieval through a single service.

using Microsoft.KernelMemory;

builder.Services.AddKernelMemory<MemoryServerless>(
    memoryBuilder =>
{
    memoryBuilder
        .WithPostgresMemoryDb(postgresConfig)
        .WithOpenAITextGeneration(openAiConfig)
        .WithOpenAITextEmbeddingGeneration(openAiConfig);
});

// Ingest a document (handles chunking + embedding)
await memory.ImportDocumentAsync(
    "refund-policy.pdf", documentId: "policy-001");

// Ask a question (handles retrieval + generation)
var answer = await memory.AskAsync(
    "What is the refund policy for digital products?");

Console.WriteLine(answer.Result);

Best for: rapid prototyping, applications where you want RAG with minimal custom code, teams that prefer convention over configuration.

Stage 4: Retrieval — Getting the Right Chunks

Retrieval quality determines RAG quality. If you retrieve irrelevant chunks, no amount of prompt engineering fixes the output.

Basic Vector Retrieval

var queryVector = await embedder
    .GenerateVectorAsync(userQuestion);

var chunks = await db.Chunks
    .OrderBy(c => EF.Functions.VectorDistance(
        "cosine", c.Embedding,
        new SqlVector<float>(queryVector)))
    .Take(5)
    .Select(c => new { c.Text, c.Source })
    .ToListAsync();

Filtered Retrieval

Always filter before searching when you can. It reduces the search space and improves relevance:

var chunks = await db.Chunks
    .Where(c => c.Category == "policies")
    .Where(c => c.IndexedAt >= DateTime.UtcNow
        .AddMonths(-3))
    .OrderBy(c => EF.Functions.VectorDistance(
        "cosine", c.Embedding,
        new SqlVector<float>(queryVector)))
    .Take(5)
    .ToListAsync();

Hybrid Retrieval

Combine vector similarity with keyword matching for the best results. On Cosmos DB, EF Core 10 provides native hybrid search:

var results = await db.Chunks
    .OrderBy(c => EF.Functions.Rrf(
        EF.Functions.FullTextScore(
            c.Text, "refund digital"),
        EF.Functions.VectorDistance(
            c.Embedding, queryVector)))
    .Take(5)
    .ToListAsync();

Relevance Thresholds

Not every query has a relevant answer in your database. Set a distance threshold to avoid returning garbage:

var results = await db.Chunks
    .Select(c => new
    {
        c.Text,
        c.Source,
        Distance = EF.Functions.VectorDistance(
            "cosine", c.Embedding,
            new SqlVector<float>(queryVector))
    })
    .Where(r => r.Distance < 0.35)
    .OrderBy(r => r.Distance)
    .Take(5)
    .ToListAsync();

if (!results.Any())
    return "I don't have information about that topic.";

A cosine distance below 0.35 typically indicates meaningful relevance. Above 0.5, the results are likely noise. Tune based on your data.

Stage 5: Generation — Building the Prompt

The prompt is where retrieval and generation meet. A well-structured prompt makes the difference between a useful answer and a hallucinated one.

The Basic RAG Prompt

public async Task<string> GenerateAnswerAsync(
    string question,
    List<RetrievedChunk> chunks,
    IChatClient chat)
{
    var context = string.Join("\n\n",
        chunks.Select((c, i) =>
            $"[Source {i + 1}: {c.Source}]\n{c.Text}"));

    var prompt = $"""
        You are a helpful assistant that answers
        questions based on the provided context.

        Rules:
        1. Only use information from the context below.
        2. If the context does not contain the answer,
           say "I don't have information about that."
        3. Cite your sources using [Source N] format.
        4. Be concise and direct.

        Context:
        {context}

        Question: {question}
        """;

    var response = await chat.GetResponseAsync(prompt);
    return response.Text;
}

Prompt Design Principles

Be explicit about grounding. Tell the model to only use the provided context. Without this instruction, models happily mix retrieved context with training knowledge, which defeats the purpose of RAG.

Include source attribution. By numbering sources and instructing the model to cite them, you get verifiable answers. Users can check the cited source to confirm accuracy.

Handle the "no answer" case. Explicitly instruct the model what to do when the context does not contain the answer. Without this, models confabulate convincing but incorrect responses.

Keep the system prompt short. The system message should establish behavior, not provide content. Put all retrieved context in the user message or a dedicated context section.

The Complete Production RAG Service

Here is everything combined into a clean, injectable service:

public class RagService
{
    private readonly AppDbContext _db;
    private readonly IEmbeddingGenerator<string,
        Embedding<float>> _embedder;
    private readonly IChatClient _chat;
    private readonly ILogger<RagService> _logger;

    public RagService(
        AppDbContext db,
        IEmbeddingGenerator<string,
            Embedding<float>> embedder,
        IChatClient chat,
        ILogger<RagService> logger)
    {
        _db = db;
        _embedder = embedder;
        _chat = chat;
        _logger = logger;
    }

    public async Task<RagResponse> AskAsync(
        string question,
        string? category = null,
        int topK = 5,
        double maxDistance = 0.35)
    {
        // 1. Embed the question
        var queryVector = new SqlVector<float>(
            await _embedder
                .GenerateVectorAsync(question));

        // 2. Retrieve relevant chunks
        var query = _db.Chunks.AsQueryable();

        if (category is not null)
            query = query
                .Where(c => c.Category == category);

        var chunks = await query
            .Select(c => new
            {
                c.Text,
                c.Source,
                Distance = EF.Functions.VectorDistance(
                    "cosine", c.Embedding, queryVector)
            })
            .Where(c => c.Distance < maxDistance)
            .OrderBy(c => c.Distance)
            .Take(topK)
            .ToListAsync();

        _logger.LogInformation(
            "Retrieved {Count} chunks for question: {Q}",
            chunks.Count, question);

        if (!chunks.Any())
        {
            return new RagResponse
            {
                Answer = "I don't have information " +
                    "about that topic in my knowledge base.",
                Sources = [],
                ChunksUsed = 0
            };
        }

        // 3. Build prompt with context
        var context = string.Join("\n\n",
            chunks.Select((c, i) =>
                $"[Source {i + 1}: {c.Source}]\n{c.Text}"));

        var prompt = $"""
            Answer the question based only on the
            context below. Cite sources using
            [Source N] format. If the context does not
            contain the answer, say so.

            Context:
            {context}

            Question: {question}
            """;

        // 4. Generate response
        var response = await _chat
            .GetResponseAsync(prompt);

        return new RagResponse
        {
            Answer = response.Text,
            Sources = chunks
                .Select(c => c.Source)
                .Distinct()
                .ToList(),
            ChunksUsed = chunks.Count
        };
    }
}

public class RagResponse
{
    public string Answer { get; set; } = "";
    public List<string> Sources { get; set; } = [];
    public int ChunksUsed { get; set; }
}

This service is provider-agnostic (IEmbeddingGenerator + IChatClient), supports category filtering, enforces relevance thresholds, includes source attribution, handles the "no answer" case gracefully, and logs retrieval metrics.

Where RAG Fits in Clean Architecture

RAG is not a separate system. It is a pattern within your application architecture.

Your Application
    Domain          → Entities, business rules
    Application     → RagService, IndexingService,
                      commands, queries
    Infrastructure  → EF Core (vector storage),
                      embedding providers,
                      LLM providers
    Presentation    → REST endpoints, MCP tools

The RagService lives in the Application layer. It depends on abstractions (IEmbeddingGenerator, IChatClient, DbContext) defined or referenced in that layer. Infrastructure provides the implementations. Presentation exposes the service through REST endpoints, MCP tools, or both.

This means your RAG pipeline follows the same architectural rules as the rest of your application. Testing is straightforward: mock the embedding generator and chat client, provide a test database, and verify retrieval quality in isolation.

RAG Through MCP

RAG and MCP complement each other naturally. An MCP server can expose RAG as a tool that any AI agent can call:

[McpToolType]
public class KnowledgeBaseTools
{
    private readonly RagService _rag;

    public KnowledgeBaseTools(RagService rag)
        => _rag = rag;

    [McpTool("search_knowledge_base")]
    [Description(
        "Search the company knowledge base using " +
        "semantic search. Returns relevant documents " +
        "with source citations. Use when the user " +
        "asks about company policies, procedures, " +
        "products, or internal documentation.")]
    public async Task<ToolResult> SearchKnowledgeBase(
        [Description("The user's question")]
        string question,
        [Description("Category filter (optional)")]
        string? category = null)
    {
        var response = await _rag.AskAsync(
            question, category);

        var result = $"{response.Answer}\n\n" +
            $"Sources: {string.Join(", ", response.Sources)}\n" +
            $"Chunks used: {response.ChunksUsed}";

        return ToolResult.Success(result);
    }
}

Now any MCP-compatible AI client, Claude, Copilot, Semantic Kernel agents, can search your knowledge base through a standardized protocol. The RAG pipeline is an implementation detail behind the tool. The AI agent does not need to know about embeddings, vectors, or chunking. It just calls a tool and gets grounded answers.

Common Pitfalls and How to Avoid Them

Chunks too large (over 512 tokens). Wastes context window space and dilutes relevance. The retrieved chunk contains the answer somewhere in 500 tokens of surrounding text. The model has to find the needle.

Chunks too small (under 64 tokens). Loses context. A 50-token chunk rarely contains enough information to be useful on its own. "The refund period is 24 hours" without knowing what product or under what conditions is incomplete.

No metadata filtering. Vector similarity alone retrieves the most semantically similar chunks, but "similar" is not always "relevant." A question about refund policies might retrieve chunks about return shipping procedures because they are semantically close. Category and date filters narrow the search space.

Embedding the wrong text. If your documents have titles, embed "Title: Refund Policy. Content: Digital products are non-refundable..." not just the content. The title carries significant semantic signal.

Ignoring the "no answer" case. Without a relevance threshold, RAG returns the "least irrelevant" chunk for every question, and the model generates a convincing answer from irrelevant context. Always set a distance threshold and handle the case where nothing is relevant.

Not measuring retrieval quality. You can have a perfect LLM and a perfect prompt, but if retrieval returns wrong chunks, the output is wrong. Measure retrieval precision and recall separately from generation quality. Build a test set of questions with known relevant chunks and evaluate your retrieval pipeline against it.

Performance Tips

Cache embeddings for common queries. If users frequently ask similar questions, cache the query embedding and retrieval results. A semantic cache (search cached queries by vector similarity) can serve repeated questions without hitting the embedding API.

Pre-compute embeddings during ingestion. Never compute embeddings at query time for documents. All document embeddings should be generated during the indexing phase and stored alongside the text.

Use appropriate dimensions. OpenAI's text-embedding-3-small supports dimension reduction. If 1536 dimensions is too expensive for storage, you can generate 512-dimension embeddings with modest accuracy loss. Test with your data to find the sweet spot.

Index your vectors. For datasets over 100,000 rows, vector search without an index is a full table scan. Use DiskANN indexes on SQL Server 2025 or HNSW indexes on dedicated vector databases.

Batch everything. Batch embedding generation during indexing. Batch retrieval if handling multiple queries. Batch database operations when ingesting large document sets.

Conclusion

RAG is not complicated. It is five stages: chunk, embed, store, retrieve, generate. The .NET ecosystem provides production-ready tools for every stage. Semantic Kernel's TextChunker handles splitting. Microsoft.Extensions.AI provides embedding abstractions. EF Core 10 or Microsoft.Extensions.VectorData handles storage and retrieval. IChatClient handles generation.

The architecture is clean. The RagService lives in the Application layer. Infrastructure provides the implementations. Presentation exposes it through REST or MCP. Testing is straightforward. Provider switching is a configuration change.

The difference between a naive RAG implementation and a production-grade one is not the pattern. It is the details. Chunk size. Overlap. Metadata filters. Relevance thresholds. Prompt structure. Source attribution. Error handling for the "no answer" case.

Get those details right and RAG transforms your .NET application from a system that can only answer questions about public knowledge into one that can answer questions about your data. Your policies. Your products. Your documentation. Your knowledge.

That is the whole point.

MCP in .NET: The Protocol That Changes How Your Code Talks to AI

Elvin Suleymanov — Sun, 22 Mar 2026 16:04:30 +0000

Everything you need to know about Model Context Protocol in .NET. What it is, why it exists, how it works, and how to build your first MCP server from scratch with a real-world OpenWeatherMap example.

MCP in .NET: The Protocol That Changes How Your Code Talks to AI

There is a moment every developer hits when building AI features. You have your application. You have an AI model. And now you need them to talk to each other. So you write an adapter. Then another. Then another. And before you know it, you are maintaining a pile of brittle glue code that breaks every time someone at OpenAI, Anthropic, or Google ships an update.

This is not a .NET problem. This is not a Python problem. This is an industry problem. And in 2026, it finally has a real solution.

Model Context Protocol. MCP.

If you write software that touches AI in any way, this article is for you. If you are a .NET developer, this article is especially for you, because the C# SDK just hit v1.0 and the ecosystem is moving fast. But even if you have never written a line of C# in your life, the ideas here will change how you think about connecting software to AI.

Let us start from the beginning.

The Problem Nobody Wanted to Talk About

Here is a story that will sound familiar.

A team builds a customer support application. They integrate OpenAI so the chatbot can answer questions. It works. Then the product manager asks: "Can it also look up order status?" So the team writes a function-calling adapter using OpenAI's specific schema. It works. Then leadership says: "We are switching to Claude for cost reasons." So the team rewrites the adapter using Anthropic's tool-use specification, which has different schema conventions, different invocation patterns, and different error handling.

Six months later they add Copilot integration. Another adapter. Then Google Gemini for a different use case. Another adapter. Each one has its own authentication flow, its own discovery mechanism, its own way of describing what tools are available.

The application now has four separate integration layers doing fundamentally the same thing: letting an AI model call a function in the application. Each layer has its own bugs, its own test suite, and its own maintenance burden. Adding a new tool (say, "check inventory") means implementing it four times.

This is the integration tax. And until recently, every team paid it silently.

What MCP Actually Is

Model Context Protocol is an open standard that eliminates the integration tax. It defines a single, universal way for AI applications to discover and use tools provided by external software.

The analogy that works best: think about what happened with web APIs. Before REST became the dominant pattern, every web service had its own protocol. SOAP. XML-RPC. Custom binary formats. If you wanted to integrate with three services, you learned three different protocols. REST standardized the conversation. One pattern. Any client. Any server.

MCP does the same thing, but for AI-to-tool communication. You build one server that exposes your capabilities. Any MCP-compatible AI client can discover and use those capabilities without custom integration code. Claude, Copilot, Semantic Kernel, custom applications. It does not matter. The protocol is the contract.

MCP was originally created by Anthropic (the company behind Claude) and has since been contributed to the Linux Foundation for open governance. It is not a proprietary technology tied to one vendor. It is an open protocol with an open specification, open SDKs, and a growing ecosystem of implementations.

As of March 2026, the official C# SDK reached v1.0, built collaboratively by Microsoft and Anthropic. This is not a preview or a beta. It is production-ready infrastructure.

Why Should You Care (Even If You Are Not a .NET Developer)

MCP matters because it solves a coordination problem that transcends any single language or framework.

If you are a backend developer, MCP gives you a way to expose your existing APIs to AI agents without rewriting anything. Your database queries, your business logic, your internal services. All of it becomes AI-accessible through a thin protocol layer.

If you are a frontend developer, MCP means the AI features in your application can talk to any backend tool without you building custom bridges for each one.

If you are an architect, MCP is a new presentation layer concern that fits cleanly into existing patterns (Clean Architecture, CQRS, microservices) without disrupting what you have already built.

If you are a product manager, MCP means switching AI providers does not require an engineering sprint. The tools work with any compliant client.

If you are a student, MCP is one of the most important protocols to learn right now because it sits at the intersection of AI and software engineering, which is where the industry is heading at full speed.

The rest of this article focuses on .NET because that is where I live and because the C# SDK is exceptionally well-designed. But the concepts apply everywhere.

The Architecture: Three Roles, One Protocol

MCP uses a client-server model with three clearly defined roles.

Figure 1. A single host contains multiple MCP clients, each maintaining a 1:1 session with a separate server over JSON-RPC 2.0.

The Host is the application the user interacts with. It could be an IDE like Visual Studio 2026, a conversational interface like Claude Desktop, or a custom enterprise application your team built. The host is the outer shell that the human sees.

The Client lives inside the host. It implements the MCP protocol, handling the low-level details of connecting to servers, discovering their capabilities, and invoking tools. A single host can manage multiple clients, each connected to a different server. Think of the client as the diplomat that speaks the protocol language on behalf of the host.

The Server is where your code lives. It exposes capabilities through the protocol. When an AI model needs to check the weather, query a database, or cancel an order, the client sends a request to your server, your server executes the logic, and the result flows back through the client to the host.

The communication between client and server uses JSON-RPC 2.0, which provides structured request-response messaging with support for notifications. The protocol lifecycle begins with an initialization handshake where both sides declare their capabilities, so they can gracefully handle cases where one side supports features the other does not.

This architecture has an elegant property: your server does not know or care which AI model is on the other end. It exposes tools. Clients call them. The model is irrelevant. Today it might be Claude. Tomorrow it might be GPT-5. Next year it might be something that does not exist yet. Your server does not change.

The Three Primitives: What Your Server Can Expose

Every MCP server exposes capabilities through three types of primitives. Understanding them is the key to designing good MCP servers.

Figure 2. The three MCP primitives: Tools (actions), Resources (context), and Prompts (templates).

Tools: The Verbs

Tools are functions that AI agents can execute. They are the actions. When a model decides it needs to do something, like check inventory, send an email, run a calculation, or fetch weather data, it calls a tool.

Every tool has three components: a name, a description, and a parameter schema. The name is how the model identifies the tool. The description is how the model decides when to use it. The schema defines what inputs the tool expects.

Here is the critical insight that most people miss: the description is the most important part of a tool. The AI model reads the description to determine whether this tool is the right one for the user's request. A bad description leads to the model calling the wrong tool or not calling any tool at all. Writing descriptions is not documentation. It is engineering.

Resources: The Context

Resources are read-only data that gives the AI context about your domain. They answer the question: "What does the AI need to know before it starts calling tools?"

Imagine hiring a new developer on your team. You would not give them terminal access and say "go fix the bug." You would give them documentation first. Architecture diagrams. Database schemas. Team conventions. Resources serve the same purpose for AI agents.

Each resource has a URI, a name, and a MIME type. They can be static (like a database schema that rarely changes) or dynamic (like a list of active users that is generated on demand). When an AI agent connects to your server, it can read resources first to understand the domain, then make much smarter decisions about which tools to call and how.

Prompts: The Templates

Prompts are reusable message templates that structure how the AI interacts with your system. They are the recipes. A prompt might define a standard workflow for "generate a weekly sales report" by specifying which tools to call in what order and what format to use for the output.

Prompts are optional. Many servers work perfectly with just tools and resources. But for teams that want consistent AI behavior across different users and sessions, prompts are incredibly valuable.

MCP in .NET: The SDK

The MCP C# SDK ships as two NuGet packages.

ModelContextProtocol is the core library. It contains everything you need for both servers and clients: protocol primitives, transport handling, JSON-RPC communication, and schema generation.

ModelContextProtocol.AspNetCore adds HTTP hosting support. If you want your MCP server to run as a remote service (in the cloud, behind a load balancer, on Azure Container Apps), this package provides the middleware.

Both packages target netstandard2.0, which means they work on .NET 8, .NET 9, and .NET 10 without any compatibility issues.

The SDK was built collaboratively by Microsoft and Anthropic and is maintained on GitHub under the Model Context Protocol organization. It reached v1.0 in March 2026, bringing production-ready features including OAuth authorization, structured output, elicitation (servers can ask users for clarification mid-execution), and long-running request support with progress reporting.

What makes the .NET SDK particularly well-designed is its integration with patterns .NET developers already know. Dependency injection works natively. Tool classes support constructor injection. The server registers through the standard IServiceCollection pipeline. If you know how to build an ASP.NET Core application, you already know 90% of what you need to build an MCP server.

Building a Real MCP Server: OpenWeatherMap from Scratch

Theory is useful. Code is better. Let us build something real.

We are going to create an MCP server that connects any AI agent to live weather data from OpenWeatherMap. When someone asks Claude "What is the weather in Tokyo?", Claude will call our server, our server will hit the OpenWeatherMap API, and Claude will respond with real, live data instead of a hallucinated guess.

You need three things before starting: .NET 8 or later, a free OpenWeatherMap API key (sign up at openweathermap.org), and a code editor.

Create the Project

mkdir WeatherMcp && cd WeatherMcp
dotnet new console -n WeatherMcp.Server
cd WeatherMcp.Server
dotnet add package ModelContextProtocol --prerelease
dotnet add package ModelContextProtocol.AspNetCore --prerelease
dotnet add package Microsoft.Extensions.Hosting
dotnet add package Microsoft.Extensions.Http

The Weather Service

First we need a service that talks to OpenWeatherMap. This is plain .NET. No MCP-specific code here at all.

// Services/OpenWeatherMapService.cs

using System.Text.Json;
using System.Text.Json.Serialization;

namespace WeatherMcp.Server.Services;

// DTOs matching OpenWeatherMap JSON
public class WeatherResponse
{
    [JsonPropertyName("name")]
    public string City { get; set; } = "";

    [JsonPropertyName("main")]
    public WeatherMain Main { get; set; } = new();

    [JsonPropertyName("weather")]
    public List<WeatherCondition> Weather { get; set; } = new();

    [JsonPropertyName("wind")]
    public WeatherWind Wind { get; set; } = new();

    [JsonPropertyName("visibility")]
    public int Visibility { get; set; }

    [JsonPropertyName("sys")]
    public WeatherSys Sys { get; set; } = new();

    [JsonPropertyName("coord")]
    public WeatherCoord Coord { get; set; } = new();
}

public class WeatherMain
{
    [JsonPropertyName("temp")] public double Temp { get; set; }
    [JsonPropertyName("feels_like")] public double FeelsLike { get; set; }
    [JsonPropertyName("humidity")] public int Humidity { get; set; }
    [JsonPropertyName("pressure")] public int Pressure { get; set; }
}

public class WeatherCondition
{
    [JsonPropertyName("main")] public string Main { get; set; } = "";
    [JsonPropertyName("description")] public string Description { get; set; } = "";
}

public class WeatherWind
{
    [JsonPropertyName("speed")] public double Speed { get; set; }
    [JsonPropertyName("deg")] public int Deg { get; set; }
}

public class WeatherSys
{
    [JsonPropertyName("country")] public string Country { get; set; } = "";
    [JsonPropertyName("sunrise")] public long Sunrise { get; set; }
    [JsonPropertyName("sunset")] public long Sunset { get; set; }
}

public class WeatherCoord
{
    [JsonPropertyName("lat")] public double Lat { get; set; }
    [JsonPropertyName("lon")] public double Lon { get; set; }
}

public class ForecastResponse
{
    [JsonPropertyName("city")] public ForecastCity City { get; set; } = new();
    [JsonPropertyName("list")] public List<ForecastItem> Items { get; set; } = new();
}

public class ForecastCity
{
    [JsonPropertyName("name")] public string Name { get; set; } = "";
    [JsonPropertyName("country")] public string Country { get; set; } = "";
}

public class ForecastItem
{
    [JsonPropertyName("dt")] public long Dt { get; set; }
    [JsonPropertyName("main")] public WeatherMain Main { get; set; } = new();
    [JsonPropertyName("weather")] public List<WeatherCondition> Weather { get; set; } = new();
    [JsonPropertyName("wind")] public WeatherWind Wind { get; set; } = new();
    [JsonPropertyName("dt_txt")] public string DateText { get; set; } = "";
}

// The service interface
public interface IWeatherService
{
    Task<WeatherResponse?> GetCurrentAsync(string city);
    Task<ForecastResponse?> GetForecastAsync(string city);
}

// The implementation
public class OpenWeatherMapService : IWeatherService
{
    private readonly HttpClient _http;
    private readonly string _apiKey;
    private readonly ILogger<OpenWeatherMapService> _logger;
    private const string Base = "https://api.openweathermap.org/data/2.5";

    public OpenWeatherMapService(
        HttpClient http,
        IConfiguration config,
        ILogger<OpenWeatherMapService> logger)
    {
        _http = http;
        _apiKey = config["OpenWeatherMap:ApiKey"]
            ?? throw new InvalidOperationException(
                "OpenWeatherMap:ApiKey not configured.");
        _logger = logger;
    }

    public async Task<WeatherResponse?> GetCurrentAsync(string city)
    {
        var url = $"{Base}/weather?q={Uri.EscapeDataString(city)}" +
                  $"&appid={_apiKey}&units=metric";
        _logger.LogInformation("Fetching weather for {City}", city);

        var res = await _http.GetAsync(url);
        if (!res.IsSuccessStatusCode) return null;

        return JsonSerializer.Deserialize<WeatherResponse>(
            await res.Content.ReadAsStringAsync());
    }

    public async Task<ForecastResponse?> GetForecastAsync(string city)
    {
        var url = $"{Base}/forecast?q={Uri.EscapeDataString(city)}" +
                  $"&appid={_apiKey}&units=metric&cnt=40";
        _logger.LogInformation("Fetching forecast for {City}", city);

        var res = await _http.GetAsync(url);
        if (!res.IsSuccessStatusCode) return null;

        return JsonSerializer.Deserialize<ForecastResponse>(
            await res.Content.ReadAsStringAsync());
    }
}

This is a standard .NET service. HttpClient with DI. Structured logging. Strongly-typed responses. Nothing here is MCP-specific. If you have ever written an API client in C#, this is exactly what you already know.

The MCP Tools

Now we wrap this service in MCP tools. This is the layer where your existing code becomes AI-accessible.

// Tools/WeatherTools.cs

using System.ComponentModel;
using System.Text;
using ModelContextProtocol;
using WeatherMcp.Server.Services;

namespace WeatherMcp.Server.Tools;

[McpToolType]
public class WeatherTools
{
    private readonly IWeatherService _weather;

    public WeatherTools(IWeatherService weather)
    {
        _weather = weather;
    }

    [McpTool("get_current_weather")]
    [Description(
        "Get current weather conditions for a city. " +
        "Returns temperature in Celsius, humidity, wind, " +
        "and sky conditions. Use when the user asks about " +
        "current or today's weather.")]
    public async Task<ToolResult> GetCurrentWeather(
        [Description("City name, e.g. 'London' or 'Tokyo,JP'")] string city)
    {
        var data = await _weather.GetCurrentAsync(city);

        if (data is null)
            return ToolResult.Error(
                $"City '{city}' not found. Try adding a country " +
                $"code, e.g. 'Springfield,US'.");

        var sb = new StringBuilder();
        sb.AppendLine($"Weather in {data.City}, {data.Sys.Country}:");
        sb.AppendLine($"  {data.Main.Temp}C (feels like {data.Main.FeelsLike}C)");
        sb.AppendLine($"  Humidity: {data.Main.Humidity}%");
        sb.AppendLine($"  Wind: {data.Wind.Speed} m/s");
        sb.AppendLine($"  Visibility: {data.Visibility / 1000.0} km");
        if (data.Weather.Count > 0)
            sb.AppendLine($"  Sky: {data.Weather[0].Description}");

        return ToolResult.Success(sb.ToString());
    }

    [McpTool("get_forecast")]
    [Description(
        "Get a 5-day weather forecast for a city. " +
        "Returns temperature and conditions every 3 hours. " +
        "Use when the user asks about tomorrow, this week, " +
        "or future weather.")]
    public async Task<ToolResult> GetForecast(
        [Description("City name, e.g. 'Berlin,DE'")] string city,
        [Description("Days ahead, 1 to 5, default 3")] int days = 3)
    {
        if (days < 1 || days > 5)
            return ToolResult.Error("Days must be between 1 and 5.");

        var data = await _weather.GetForecastAsync(city);
        if (data is null)
            return ToolResult.Error($"City '{city}' not found.");

        var sb = new StringBuilder();
        sb.AppendLine($"Forecast for {data.City.Name}, {data.City.Country}:");

        var cutoff = DateTime.UtcNow.AddDays(days);
        var grouped = data.Items
            .Where(i => DateTimeOffset.FromUnixTimeSeconds(i.Dt).UtcDateTime < cutoff)
            .GroupBy(i => DateTimeOffset.FromUnixTimeSeconds(i.Dt).ToString("yyyy-MM-dd"));

        foreach (var day in grouped)
        {
            sb.AppendLine($"\n  {day.Key}:");
            foreach (var item in day)
            {
                var time = DateTimeOffset.FromUnixTimeSeconds(item.Dt).ToString("HH:mm");
                var cond = item.Weather.Count > 0 ? item.Weather[0].Description : "N/A";
                sb.AppendLine($"    {time} - {item.Main.Temp}C, {cond}, wind {item.Wind.Speed} m/s");
            }
        }

        return ToolResult.Success(sb.ToString());
    }
}

Look at what is happening here. The [McpTool] attribute registers a method as a callable tool. The [Description] attributes tell the AI when and how to use it. The constructor receives IWeatherService through dependency injection, which means this tool uses the exact same service you would use in a REST controller.

The tool does not know which AI model is calling it. It does not care. It receives input, calls your service, formats a result, and returns it.

Wiring It Together

// Program.cs

using ModelContextProtocol;
using ModelContextProtocol.AspNetCore;
using WeatherMcp.Server.Services;
using WeatherMcp.Server.Tools;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient<IWeatherService, OpenWeatherMapService>();
builder.Services.AddMcpServer()
    .WithTools<WeatherTools>();

var app = builder.Build();
app.MapGet("/", () => "Weather MCP Server is running.");
app.MapMcpEndpoint("/mcp");
app.Run();

Add your API key to appsettings.json:

{
  "OpenWeatherMap": {
    "ApiKey": "YOUR_KEY_HERE"
  }
}

Run it with dotnet run. Your server is live.

Connecting to Claude Desktop

Add this to your Claude Desktop config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "weather": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/WeatherMcp.Server"]
    }
  }
}

Restart Claude. Ask: "What is the weather like in London right now?" Claude calls your server, gets live data, and gives a real answer. Ask "Should I bring an umbrella to Tokyo tomorrow?" and it calls the forecast tool, checks for rain in the forecast, and gives you practical advice based on actual data.

That is the magic. Your C# code is now accessible to an AI agent through a standardized protocol. No OpenAI-specific adapter. No Anthropic-specific plugin. Just MCP.

Transport: How Clients and Servers Communicate

MCP defines two transport mechanisms for different deployment scenarios.

Stdio: For Local Servers

Standard input/output. The host launches your server as a child process and talks to it through stdin/stdout pipes. This is how Claude Desktop and Visual Studio connect to local MCP servers. Zero network overhead. Lowest possible latency.

For a Stdio server, you do not need ASP.NET Core. A plain console app works:

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHttpClient<IWeatherService, OpenWeatherMapService>();
builder.Services.AddMcpServer()
    .WithStdioTransport()
    .WithTools<WeatherTools>();
await builder.Build().RunAsync();

HTTP: For Remote Servers

For cloud deployments, multi-tenant environments, and load-balanced architectures, you use HTTP with Server-Sent Events (SSE). This is the ModelContextProtocol.AspNetCore package. The MapMcpEndpoint() method handles all the HTTP plumbing.

Most teams start with Stdio during development (for quick testing with Claude Desktop or Copilot) and deploy with HTTP in production.

Where MCP Lives in Your Architecture

If you follow Clean Architecture, Onion Architecture, or any layered pattern, MCP fits as a presentation layer concern. It sits at the same level as your REST API controllers.

Your Application
  Domain Layer         → Entities, business rules
  Application Layer    → Use cases, commands, queries
  Infrastructure       → Database, external APIs
  Presentation Layer   → REST Controllers (existing)
                       → MCP Server (new)

Figure 3. MCP sits in the presentation layer alongside REST controllers. Both point inward to the application layer.

Your MCP tools should be thin. They accept input, call your application layer (or dispatch commands via MediatR if you use CQRS), and return results. They should contain zero business logic. All validation, authorization, and domain rules stay in the layers where they belong.

This means adding MCP to an existing application is not a rewrite. It is a new entry point into the same application logic. The same service that powers your REST endpoint can power your MCP tool. One codebase. Two interfaces. No duplication.

What v1.0 Brought to the Table

The March 2026 release was not just a version bump. It brought features that make MCP viable for serious production use.

Authorization. OAuth support with Protected Resource Metadata. Your MCP server can sit behind an identity provider and enforce the same role-based access control you use for REST endpoints.

Elicitation. Servers can ask users for clarification during tool execution. A deployment tool can pause and say "You asked me to deploy to production. Please confirm." The user responds through the client, and execution continues.

Structured Output. Instead of returning raw text that the AI has to interpret, tools can return explicitly typed content. The model knows exactly what each field means, which reduces errors and hallucination.

Progress Reporting. Long-running tools can send incremental status updates. "Collecting data... Processing... Generating report... Complete." The client displays these to the user so they know something is happening.

Icon Support. Tools, resources, and prompts can have icons for visual identification in client UIs.

The Ecosystem: What Works with MCP Today

Building an MCP server is an investment. The return on that investment depends on how many clients can use it. Here is what works today.

Figure 4. One MCP server works with every compatible AI client, present and future.

Claude Desktop. Full MCP support. Local Stdio and remote HTTP.

GitHub Copilot in Visual Studio 2026. MCP servers appear as tools in agent mode. Your weather tool, your database tool, your internal API tool. All discoverable in Copilot.

VS Code with Copilot Agent Mode. Same as Visual Studio but in VS Code.

Semantic Kernel. Microsoft's AI orchestration framework consumes MCP servers as plugins automatically. Your MCP tools become Semantic Kernel functions with zero extra code.

Microsoft Agent Framework. Introduced in .NET 10 at .NET Conf 2025. It uses MCP as its primary tool integration mechanism. Autonomous agents discover and invoke tools through the protocol.

Copilot Studio. Enterprise AI workflow integration for organizations using Microsoft 365.

One server. All of these clients. That is the power of implementing a protocol instead of coupling to a vendor.

The Description Engineering Principle

This deserves its own section because it is the single most impactful thing you can do to make your MCP server work well.

When an AI model decides which tool to call, it reads the [Description] attribute. That is it. That is the entire selection mechanism. If your description is vague, the model picks the wrong tool. If your description is incomplete, the model does not pick your tool at all. If your description is excellent, the model calls exactly the right tool with exactly the right parameters.

Bad description:

"Gets weather"

Good description:

"Get current weather conditions for a city. Returns
temperature in Celsius, humidity, wind speed, and sky
conditions. Use when the user asks about current or
today's weather in a specific location."

The good description tells the model three things: what the tool does, what it returns, and when to use it. This is not optional polish. This is functional engineering that directly affects how well your server works.

The same principle applies to parameter descriptions. Instead of "The city", write "City name, optionally with country code, e.g. 'London' or 'Tokyo,JP'". The model uses these to construct correct input.

Error Messages That AI Can Use

When a REST endpoint fails, you return an error for a developer to read. When an MCP tool fails, you return an error for an AI model to interpret and act on.

Bad error:

"Error: 404"

Good error:

"City 'Springfeld' not found. This may be a spelling error.
Try 'Springfield' or add a country code like 'Springfield,US'."

The good error gives the AI enough information to recover. It might correct the spelling and retry. It might ask the user for clarification. It might try a different approach entirely. But it can only do these things if your error message provides context.

This is a mindset shift. You are not writing errors for a developer reading logs at 2 AM. You are writing errors for an AI agent that needs to decide what to do next in real time.

What Makes MCP Different from Function Calling

If you have used OpenAI's function calling or Anthropic's tool use, you might wonder: how is MCP different?

Function calling is a feature of a specific AI provider's API. It lets you define functions that a specific model can call within a specific conversation. The function definitions live in your API request. The execution happens in your application code. It works, but it is tightly coupled to that provider's schema and conventions.

MCP is a protocol. It separates the tool definition from the AI provider entirely. Your tools live in a server that any client can connect to. Discovery is automatic. Schema generation is automatic. The protocol handles lifecycle management, capability negotiation, and communication. You do not embed tool definitions in API calls. You run a server and clients find it.

The practical difference: with function calling, you write tool definitions once per provider. With MCP, you write them once, period.

When Should You Build an MCP Server?

MCP is not the right solution for everything. Here is when it makes sense.

Build an MCP server when you have existing business logic that would be useful to AI agents. Order management. Inventory queries. Customer lookup. Report generation. Deployment automation. If you already have services that do these things, wrapping them in MCP tools is a small investment with a large payoff.

Build an MCP server when you want to decouple from AI providers. If you are tired of rewriting integrations every time you switch models, MCP gives you a stable interface that survives provider changes.

Build an MCP server when you want AI features in your IDE. If your team uses Visual Studio or VS Code with Copilot, an MCP server can expose your internal tools, APIs, and data directly in the developer's workflow.

Do not build an MCP server when you just need a one-off function call in a single API request. If your use case is simple and provider-specific, function calling might be simpler.

Do not build an MCP server when you do not have existing services to expose. MCP is a presentation layer. If there is no application logic behind it, there is nothing to expose.

Getting Started in 5 Minutes

If you want to try MCP right now with the absolute minimum code:

dotnet new console -n MyFirstMcp
cd MyFirstMcp
dotnet add package ModelContextProtocol --prerelease
dotnet add package Microsoft.Extensions.Hosting

using ModelContextProtocol;
using Microsoft.Extensions.Hosting;
using System.ComponentModel;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddMcpServer()
    .WithStdioTransport()
    .WithTools<MyTools>();
await builder.Build().RunAsync();

[McpToolType]
public class MyTools
{
    [McpTool("greet")]
    [Description("Generate a personalized greeting for someone.")]
    public Task<ToolResult> Greet(
        [Description("The person's name")] string name)
    {
        return Task.FromResult(
            ToolResult.Success($"Hello, {name}! Welcome."));
    }
}

That is a complete MCP server. Five minutes. One file. Connect it to Claude Desktop and you have an AI agent that can greet people by name using your code.

From here you add real services, real tools, real resources. The weather server we built earlier in this article. A database query tool. An order management tool. A deployment pipeline tool. Each one is just another class with [McpToolType] and [McpTool] attributes.

What Comes Next

MCP is early. The protocol is mature enough for production (v1.0 is stable), but the ecosystem is still expanding rapidly.

Multi-agent orchestration is the next frontier. The Microsoft Agent Framework already supports scenarios where multiple agents coordinate through MCP, each with their own tools, sharing context and delegating tasks. This is where the protocol's design really shines, because each agent is just another client connecting to servers.

Remote server hosting will become standardized. Today most MCP servers run locally. The HTTP transport makes remote hosting possible, and cloud providers are beginning to offer managed MCP hosting.

Security models will evolve. As MCP servers handle more sensitive operations, the community will need to develop patterns for fine-grained permission scoping, audit logging, and anomaly detection for AI-initiated operations.

Tool marketplaces are coming. Just as npm and NuGet transformed how developers share code, MCP server registries will transform how teams share AI-accessible capabilities.

Conclusion

MCP is not a framework. It is not a library. It is a protocol. And protocols change industries.

HTTP changed how computers talk to each other. REST changed how services talk to each other. MCP is changing how AI talks to software. The pattern is the same: standardize the conversation and everything else follows.

If you build software that touches AI in any way, MCP is worth understanding deeply. If you are a .NET developer, the C# SDK is production-ready and the ecosystem support from Microsoft is serious. If you are not a .NET developer, the concepts are identical across every SDK.

The code we wrote today, the weather server, is a starting point. The real value comes when you wrap your own business logic in MCP tools and suddenly every AI agent in your organization can use it.

Build the server. Expose your tools. Let the AI find them.

If this was useful, hit the reaction button and share it with someone who builds software that talks to AI. I write about .NET architecture and AI integration. Follow me for more.

Questions? Ideas for your own MCP server? Drop them in the comments.

DEV Community: Elvin Suleymanov

Modernizing .NET Architectures for AI-Native Workloads

Table of Contents

1. What AI-Native Actually Means

2. Why Traditional .NET Architectures Struggle with AI

3. The AI-Native Architecture Stack

4. Semantic Kernel as the AI Orchestration Layer

Plugins as domain capability exposure

5. Designing AI-Aware Domain Models

6. Vector Storage and Semantic Memory in .NET

Choosing your vector store

7. The Agent Pattern: Autonomous AI in Your Domain

The principle of least privilege for agents

8. Streaming AI Responses with ASP.NET Core

9. Observability for AI Workloads

The AI observability checklist

10. Guardrails: Safety, Cost Control, and Responsible AI

Token budget enforcement

Input and output validation

The human-in-the-loop pattern

11. Real-World Walkthrough: AI-Native CRM Feature

The feature requirements

The architecture

The output schema

12. Migration Path: Evolving an Existing .NET System

Phase 1 - Add the AI infrastructure (Week 1-2)

Phase 2 - Build the first plugin from an existing service (Week 2-3)

Phase 3 - Build a single AI endpoint with full observability (Week 3-4)

Phase 4 - Add semantic indexing to existing entities (Week 4-6)

Phase 5 - Expand plugins and agents gradually (Ongoing)

Wrapping Up

Modern Storage Design: How Engineers Should Think Before Writing a Single Line of Code

1. Why Storage Decisions Outlive Everything Else

2. The Five Questions You Must Answer Before Choosing Anything

3. Data Shape: Structured, Semi-Structured, or Unstructured?

Structured data

Semi-structured data

Unstructured data

Time-series data

4. Access Patterns Are the Real Design Driver

Mapping access patterns to storage keys

5. Consistency vs. Availability: Making the CAP Trade-Off Explicit

When consistency is non-negotiable

When availability is more important

Document the trade-off explicitly

6. Read/Write Ratio and the Architecture It Implies

CQRS: separating the write and read models

7. The Storage Taxonomy: Choosing the Right Engine

Relational databases

Document databases

Key-value stores

Wide-column stores

Search engines

Graph databases

Time-series databases

8. Designing for Growth: Partitioning and Sharding from Day One

The partition key is everything

Design your primary key for partition-friendliness

Write queries first, then define indexes

9. The Polyglot Persistence Pattern

The source of truth principle

10. The Storage Design Document: A Template

11. Common Anti-Patterns and How to Avoid Them

The God Table

Using the Application Database for Everything

The N+1 Schema Design

Premature Sharding

No Migration Strategy

Storing Secrets and PII Without Thought

12. A Real-World Walkthrough: Designing Storage for a SaaS Platform

Step 1 - Answer the five questions

Step 2 - Select engines based on the access pattern matrix

Step 3 - Design the schema for growth

Step 4 - Document and review

13. The Decision Checklist

Wrapping Up

Supercharge Your APIs: ASP.NET Core + C# 14 Features You Must Know in 2026

Table of Contents

1. C# 14 - The Language Hits a New Gear

2. Implicit Span Conversions & Zero-Alloc Pipelines

4. Nullable-Improved Patterns and the `?[]` Null-Conditional Index

Automatic `ProblemDetails` for all errors

Streaming JSON responses with `IAsyncEnumerable`