DEV Community: Ben Witt

Durable Workflows Are Great, and the Wrong Choice for Short Pipelines

Ben Witt — Wed, 29 Jul 2026 08:00:00 +0000

With the Microsoft Agent Framework and its Durable Task extension, durable execution is once again a major topic in the .NET world. The idea is tempting: define agents and workflows in ordinary code, then let the runtime handle persistence, crash recovery, state management, distributed scaling, and observability.

That is strong technology. At the time of writing, the Durable Task extension for Microsoft Agent Framework is still in preview, but the direction is already clear: durable execution is becoming easier to apply to agentic and workflow-based systems.

Precisely because it is powerful, it will also be used in places where it does not belong.

My thesis: for short, cheap, idempotent pipelines, durable workflows are usually the wrong abstraction. Not because the framework is bad, but because the nature of the problem is different.

Keep Two Concepts Separate

There is an important distinction that is easy to blur.

Microsoft Agent Framework workflows let you define a graph of executors and agents. That can be useful even without durability. A workflow graph can model a sequence, a branch, a fan-out, or a handoff.

Durable Task is a different decision: it adds persistence, recovery, replay semantics, and distributed coordination.

Those two things are related, but they are not the same. A workflow does not automatically need to be durable. A three-step graph can still be just a three-step graph.

That distinction matters because the cost of a workflow model and the cost of durable execution are not the same.

What Durable Workflows Are Built For

Durable execution solves a real and difficult problem: how do you keep a workflow alive when it runs for a long time, consists of several steps, waits for external events, and may fail along the way?

The runtime records progress in durable state. If the process crashes, the workflow can be reconstructed from history and resumed. Work that has already completed does not have to be blindly executed again. In serverless hosting models, a workflow can wait for a human approval or external event without consuming compute for the entire waiting period.

That is excellent engineering for workflows that actually have these properties:

long-running processes
human approvals
external events
distributed execution
visible business state
expensive intermediate steps
recovery requirements that span process restarts

This is where durable workflows shine. The extra machinery buys you something concrete: continuity, recovery, and visibility.

But durability is not magic. It does not remove the need to design side effects carefully. If a step sends an email, charges a card, writes to an external system, or publishes a message, you still need idempotency keys, deduplication, transactional boundaries, or an outbox pattern. Durable execution helps avoid repeating completed work, but it does not make the outside world exactly-once.

What a Short Pipeline Is

A short pipeline is not just a workflow that finishes quickly.

For this discussion, a short pipeline has four properties:

it runs in milliseconds or a few seconds
it has only a small number of steps
it does not wait for humans or external events
it is cheap and safe to repeat from the beginning

That last point is the decisive one.

A message comes in, gets transformed, validated, enriched, and forwarded. If the process dies halfway through, the simplest recovery strategy is often to run the whole pipeline again. If the pipeline is idempotent and the cost of repetition is tiny, replaying from durable history is solving a problem that the workload barely has.

For this kind of workload, durable execution can make you pay a price without giving you enough value in return.

The Costs You Add

Infrastructure overhead.

Durable execution depends on a persistent backend and a hosting environment that records workflow progress. For a process that finishes in milliseconds, that can be more machinery than the problem deserves.

Programming model constraints.

Replay-based orchestration requires discipline. You need clean step boundaries, deterministic orchestration logic, and careful handling of replay semantics. Those rules are worth their cost when you need recovery across time. If you do not, they become cognitive overhead.

Latency.

Every durable boundary has a cost. In a workflow that waits for 24 hours, that cost disappears in the noise. In a low-latency pipeline, it lands exactly where you care most.

Debugging distance.

You are no longer debugging simple control flow. You are debugging an orchestration with history, replay behavior, stored state, and runtime semantics. That is powerful for complex processes, but unnecessary distance from a three-step transformation.

Operational coupling.

The pipeline now depends on the durability store, the worker model, the hosting configuration, and the runtime's interpretation of history. That can be a good trade when you need the guarantees. It is a bad trade when a normal retry would have solved the failure.

The Actual Question

The question before choosing durable execution is not:

Would reliability be nice?

Reliability is always nice.

The useful question is:

What does it cost me to repeat the entire operation?

If the answer is "almost nothing, because the pipeline is short, cheap, and idempotent," you probably do not need durable execution.

If the answer is "a lot, because the workflow runs for hours, waits for external input, or contains expensive side effects," then the overhead may be worth every cent.

I would ask five questions before introducing a durable workflow:

Does the process outlive a single request or worker process?
Does it wait for humans, timers, or external events?
Is there meaningful intermediate state that someone needs to observe?
Is repeating the whole operation expensive or dangerous?
Are side effects isolated and designed for idempotency?

If most answers are no, durability is probably the wrong layer.

What I Would Use Instead

For a short pipeline, the honest architecture is usually boring:

a few methods or handlers called in sequence
validation at the boundary
retry only around transient I/O
idempotency keys for incoming messages
dead-letter handling for poison messages
tracing and metrics for observability
an outbox pattern if a database write and message publish must stay coordinated

That gives you reliability where it matters without turning ordinary control flow into orchestration.

The goal is not to avoid infrastructure at all costs. The goal is to put infrastructure at the correct boundary.

When I Would Use Durable Workflows

Durable workflows are the right choice as soon as at least one of these points applies:

The process runs for minutes, hours, or days.
There are waiting points for external events or human approvals.
The workflow state must be externally visible while it is running.
Completed steps are expensive to repeat.
Side effects need strict coordination and cannot be treated as a cheap retry.
The process needs distributed execution across workers or machines.
Auditability and replayable history are part of the requirement.

In those cases, the durable runtime earns its place. The workflow is no longer just a short transformation. It is a stateful business process.

Conclusion

The temptation with powerful frameworks is to use them everywhere because they are impressive. Durable workflows are impressive for good reasons.

But durability is not a free upgrade. It is a trade: persistence, replay semantics, storage dependency, latency, and a stricter programming model in exchange for recovery, continuity, and observability.

For short, cheap, idempotent pipelines, that trade is usually wrong. Repeating the whole operation is simpler than preserving every intermediate step.

Sometimes the right answer to "Should we make this durable?" is simply:

No. Make it repeatable.

RabbitMQ Dead Letter Queues in .NET: Why We Chose This Approach and Where It Hit Us

Ben Witt — Wed, 22 Jul 2026 08:00:00 +0000

In a message-based system, one of the first questions you have to answer is this:

What happens to a message that cannot be processed?

The naive answer is: catch the exception, log it, and move on.

That works until you realize what it really means: you are silently losing messages in production. No rollback, no second chance, no audit trail.

RabbitMQ's Dead Letter Exchange, DLX, is a good answer to this problem. But it is not magic, and it is not a complete failure-handling strategy by itself. It is one building block in a production setup that also needs retries, persistence, publisher confirms, monitoring, and a deliberate replay process.

This article explains why we used a DLX, what the setup looks like in .NET, and which mistakes caught us off guard.

The Problem

Our system processes messages from several queues through a plugin-based messaging framework. A consumer reads a message, processes it, and confirms it with BasicAck.

If processing fails, there are three basic options:

Requeue immediately.

BasicNack with requeue: true puts the message back on the queue. This is useful for some transient failures, but dangerous as a default. If the problem is permanent, the same message can loop forever and put unnecessary pressure on the broker and consumers.
Reject without requeue and without DLX.

BasicNack or BasicReject with requeue: false discards the message if no dead-lettering is configured. That means no second chance and no operational visibility.
Reject without requeue and use a DLX.

If the source queue is configured with a Dead Letter Exchange, RabbitMQ republishes the message to that exchange. From there, it can be routed to a Dead Letter Queue, where it can be inspected, repaired, replayed, or archived.

Option 3 was the only acceptable default for messages that failed permanently. Messages that cannot be processed should not simply disappear.

But there is an important distinction:

A DLQ is not an error handler. It is a place where failed messages wait for an error-handling decision.

How Dead Lettering Works

Dead-lettering can happen for several reasons:

a consumer rejects or nacks a message with requeue: false
a message expires because of TTL
a queue length limit is exceeded
a quorum queue delivery limit is exceeded

The common case in our system was explicit rejection from the consumer.

Conceptually, the flow looks like this:

Publisher
    |
[Exchange]
    |
[my.queue] -- nack(requeue:false) --> [my.dlx] --> [my.queue.dlq]

The DLQ is a normal queue. RabbitMQ adds dead-letter metadata to the message headers, including information such as the queue it came from, the reason it was dead-lettered, and death history through headers such as x-death, x-first-death-*, and x-last-death-*.

That metadata is useful, but it should not be your only source of truth. For production troubleshooting, log the message ID, correlation ID, queue name, exception type, and failure reason before you nack the message.

Prefer Policies Over Hardcoded Queue Arguments

There are two ways to configure dead-lettering for a queue:

using RabbitMQ policies
using queue declaration arguments such as x-dead-letter-exchange

RabbitMQ recommends policies for DLX configuration because policies can be updated without redeploying applications and without deleting and recreating queues. Queue declaration arguments are less flexible because they become part of the queue's declared properties.

A policy-based setup can look like this:

rabbitmqctl set_policy my-service-dlx "^my\.service\." \
  '{"dead-letter-exchange":"my.dlx"}' \
  --apply-to queues \
  --priority 7

If you need a specific dead-letter routing key, add it to the policy:

rabbitmqctl set_policy my-service-dlx "^my\.service\." \
  '{"dead-letter-exchange":"my.dlx","dead-letter-routing-key":"my.service.failed"}' \
  --apply-to queues \
  --priority 7

That is usually the cleaner production option.

There is still a place for queue arguments: if your application fully owns the topology and you want the topology definition to live with the application. In that case, configuration is better than hardcoding, but policies should be considered first.

Setup in CSharp

The exchange and DLQ are normal RabbitMQ entities:

await channel.ExchangeDeclareAsync(
    exchange: "my.dlx",
    type: ExchangeType.Direct,
    durable: true,
    autoDelete: false);

await channel.QueueDeclareAsync(
    queue: "my.queue.dlq",
    durable: true,
    exclusive: false,
    autoDelete: false,
    arguments: null);

await channel.QueueBindAsync(
    queue: "my.queue.dlq",
    exchange: "my.dlx",
    routingKey: "my-routing-key");

If the queue is configured through policy, the main queue declaration does not need DLX arguments:

await channel.QueueDeclareAsync(
    queue: "my.queue",
    durable: true,
    exclusive: false,
    autoDelete: false,
    arguments: null);

If you intentionally configure DLX through queue arguments, the declaration must include the exact arguments:

await channel.QueueDeclareAsync(
    queue: "my.queue",
    durable: true,
    exclusive: false,
    autoDelete: false,
    arguments: new Dictionary<string, object?>
    {
        ["x-dead-letter-exchange"] = "my.dlx",
        ["x-dead-letter-routing-key"] = "my-routing-key"
    });

The consumer rejects permanently failed messages with requeue: false:

var consumer = new AsyncEventingBasicConsumer(channel);

consumer.ReceivedAsync += async (_, ea) =>
{
    try
    {
        var body = ea.Body.ToArray();
        var message = Encoding.UTF8.GetString(body);

        await ProcessMessageAsync(message);
        await channel.BasicAckAsync(ea.DeliveryTag, multiple: false);
    }
    catch (TransientException ex)
    {
        _logger.LogWarning(ex, "Transient failure while processing message.");
        await channel.BasicNackAsync(ea.DeliveryTag, multiple: false, requeue: true);
    }
    catch (Exception ex)
    {
        _logger.LogError(
            ex,
            "Permanent processing failure. Message will be dead-lettered. DeliveryTag={DeliveryTag}",
            ea.DeliveryTag);

        await channel.BasicNackAsync(ea.DeliveryTag, multiple: false, requeue: false);
    }
};

await channel.BasicConsumeAsync(
    queue: "my.queue",
    autoAck: false,
    consumer: consumer);

The important part is not the exact exception hierarchy. The important part is the decision:

transient failures may be retried
permanent failures should be dead-lettered
every path should be observable

Where It Hit Us: PRECONDITION_FAILED 406

This was the part that cost us time.

After we configured dead-lettering in the broker, the next deployment failed during startup with:

AMQP operation QueueDeclare failed with code 406: PRECONDITION_FAILED

The cause was not the DLX itself. The cause was RabbitMQ's property equivalence check.

When a queue already exists, a later QueueDeclare call must match the existing queue properties. That includes durable, exclusive, auto-delete, queue type, and optional arguments. If the declaration differs, RabbitMQ closes the channel with PRECONDITION_FAILED.

In our case, the queue already existed with x-dead-letter-exchange and x-dead-letter-routing-key. Our framework declared the same queue at startup, but did not pass those arguments. From RabbitMQ's perspective, that was a different queue declaration for the same queue name.

The broker was right to reject it.

The Fix

There are two clean ways to avoid this.

Option 1: Use policies

If dead-lettering is configured through RabbitMQ policies, the application does not have to provide DLX queue arguments during QueueDeclare.

This is usually the better operational model because broker-level routing behavior stays broker-level configuration.

Option 2: Make queue arguments explicit configuration

If the application owns queue declarations, then queue arguments must be part of the application configuration and passed consistently on every declaration.

Our QueueConfiguration needed a generic Arguments dictionary:

public class QueueConfiguration
{
    public string Name { get; set; } = string.Empty;
    public bool IsDurable { get; set; } = true;
    public bool IsAutoDelete { get; set; } = false;
    public bool AutoAck { get; set; } = false;
    public string ExchangeName { get; set; } = string.Empty;
    public string RoutingKey { get; set; } = string.Empty;
    public IDictionary<string, object?>? Arguments { get; set; }
}

The queue declaration then passes the dictionary directly:

await channel.QueueDeclareAsync(
    queue: queue.Name,
    durable: queue.IsDurable,
    exclusive: false,
    autoDelete: queue.IsAutoDelete,
    arguments: queue.Arguments);

In configuration:

{
  "Name": "my.service.queue",
  "IsDurable": true,
  "IsAutoDelete": false,
  "AutoAck": false,
  "ExchangeName": "my.exchange",
  "RoutingKey": "my.routing.key",
  "Arguments": {
    "x-dead-letter-exchange": "my.dlx",
    "x-dead-letter-routing-key": "my.service.failed"
  }
}

The second trap: if the broker queue has both x-dead-letter-exchange and x-dead-letter-routing-key, both must match. Setting only one is not enough.

You can inspect the current queue arguments in the RabbitMQ Management UI under the queue details.

Queue Arguments Are Not a Migration Mechanism

Queue arguments are not a good place for values you expect to change frequently.

Many queue properties are fixed at declaration time. If an existing queue was declared with different properties, you cannot simply redeclare it with new values. You either need a policy where supported, or you need a queue migration.

For queue arguments that cannot be changed in place, the operational process is:

Stop publishers and consumers, or drain traffic safely.
Make sure the queue is empty or move the messages intentionally.
Delete the queue.
Recreate it with the correct properties.
Restart consumers and publishers.

In production, that means planning. A queue declaration is not just code. It is part of the broker topology.

DLX Does Not Replace Retries

One mistake is sending every exception directly to the DLQ.

Some failures are permanent:

invalid schema
impossible state transition
missing required business data
unsupported message type

Those belong in a DLQ.

Other failures are transient:

database timeout
network interruption
temporary downstream outage
lock contention

Those usually need retries before dead-lettering.

The retry strategy depends on the system. Common patterns are:

limited in-process retry for very short transient failures
delayed retry queues with TTL and DLX
retry counters in headers
quorum queue delivery limits
final dead-lettering after max attempts

The important rule is this:

A DLQ should contain messages that need investigation, not messages that merely hit a temporary dependency failure once.

DLX Does Not Replace Message Durability

A durable queue does not automatically make every message durable.

For production systems, publishers still need to publish persistent messages where appropriate, and they should use publisher confirms if message loss is unacceptable. Otherwise, a message can be lost before it ever reaches the consumer or before the broker has safely accepted it.

Dead-lettering itself is also a form of publishing. In some scenarios, especially clustered setups, dead-letter forwarding can fail if the target exchange or queue is unavailable or unroutable. Quorum queues offer stronger options for at-least-once dead-lettering, but the broader point remains:

A DLX is part of reliability. It is not the whole reliability story.

Operating a DLQ

Creating a DLQ is easy. Operating one is the real work.

At minimum, we need:

alerts when DLQ depth grows
dashboards for dead-letter rate and age
a way to inspect payload and headers safely
retention rules so DLQs do not grow forever
a replay process with idempotency protection
a way to quarantine messages that fail again after replay
clear ownership: who looks at the DLQ and when

Without that, the DLQ becomes a message graveyard. It prevents immediate loss, but it does not create recovery.

What We Learned

These are the points I would consider from the beginning in the next project:

1. Prefer RabbitMQ policies for DLX configuration.

Policies are easier to update and avoid baking broker behavior into application declarations.

2. If you use queue arguments, make them explicit configuration.

Hardcoded x-arguments are painful because they cannot be changed casually after the queue exists.

3. Queue declarations must match broker state.

PRECONDITION_FAILED 406 during QueueDeclare usually means a property equivalence mismatch. Check durable, auto-delete, exclusive, queue type, and optional arguments.

4. Separate transient and permanent failures.

Do not send every exception directly to the DLQ. Retry transient failures, dead-letter permanent ones.

5. Use message durability and publisher confirms where loss matters.

DLX handles consumer-side failure. It does not protect the whole publish-consume path by itself.

6. Monitor and operate the DLQ.

A DLQ without alerts, retention, ownership, and replay tooling is just delayed message loss.

7. Be deliberate with routing keys.

Separate dead-letter routing keys per queue are often useful because they make routing and replay easier. They are not mandatory, but they are a good default when multiple queues share one DLX.

Conclusion

The DLX approach requires more setup than the naive exception-based solution. In return, you stop silently discarding failed messages and gain a place to inspect, repair, replay, or archive them.

But the important lesson is not "add a DLQ and you are safe."

The lesson is:

Treat failed messages as part of your production workflow.

That means policies or consistent queue arguments, deliberate retries, persistent messages, publisher confirms where needed, monitoring, and a replay process.

Once you understand that, the PRECONDITION_FAILED error becomes less mysterious. It is RabbitMQ telling you that your code and broker topology disagree.

Fix that disagreement early. Then make sure your DLQ is not just a place where messages go to be forgotten.

MCP Design Patterns: 6 Architectures for Your AI Tools

Ben Witt — Wed, 15 Jul 2026 08:00:00 +0000

The Model Context Protocol is everywhere right now. Everyone is building MCP servers, connecting tools to agents, and exposing internal systems to AI clients.

What gets less attention is the architecture behind those servers.

An MCP server is not just a template you set up once and forget. Depending on the use case, the right structure can be completely different. A thin wrapper around an API, a local resource server, and an orchestration layer for long-running jobs all expose capabilities through MCP, but they should not be designed the same way.

I have seen six patterns emerge in practice. This is not an academic classification. It is a decision aid:

Which MCP server shape fits the problem?

What Is an MCP Server?

The Model Context Protocol is an open protocol for connecting AI applications to external context and capabilities.

An MCP server can expose three main kinds of primitives:

Tools: callable actions, usually with parameters and structured results.
Resources: readable context such as files, documents, database records, or generated views.
Prompts: reusable prompt templates or interaction patterns.

In practice, most people start with tools because they are the most visible part of MCP. But a good MCP server is not just a bag of functions. It is a boundary between an AI client and a system that has data, behavior, permissions, and risk.

The important question is not only:

What can the agent call?

It is also:

What should the client expose, in what shape, with what permissions, and at what level of abstraction?

Pattern 1: Direct API Wrapper

This is the simplest and most common pattern. One MCP tool maps closely to one existing API endpoint. The server is mostly a thin adapter between the MCP client and an existing service.

AI Client
  |
MCP Tool: get_user(id)
  |
REST API: GET /users/{id}

When it fits:

The API is stable, well documented, and already close to what the model needs. You want quick integration without adding much domain logic to the MCP server.

When it does not fit:

The API exposes low-level data that the model still has to join, filter, interpret, or clean up. Then the complexity moves into the prompt and the model has to act like an API integration layer. That is fragile.

Typical examples:

GitHub issue lookup
Jira ticket retrieval
internal REST services
simple CRM queries

Main risk:

Tool bloat. If every endpoint becomes a tool, the model has too many similar options and too much raw API detail to reason about.

Design rule:

Use direct wrappers for small, obvious, low-risk API operations. Move to task-level tools when the agent has to combine or interpret several raw endpoints.

Pattern 2: Composite Service

A composite MCP server hides multiple backend calls behind one task-level tool. The agent asks for the result it actually needs, and the server performs the aggregation.

AI Client
  |
MCP Tool: get_order_summary(order_id)
  |
  +-- REST API: GET /orders/{id}
  +-- REST API: GET /customers/{customer_id}
  +-- REST API: GET /products/{product_id}

When it fits:

The agent repeatedly needs the same combination of data for one task. Without this pattern, it would make several tool calls and assemble the result itself.

When it does not fit:

The required combination changes constantly. If every task needs a different shape, a fixed composite tool can become too rigid.

Typical example:

A customer service agent that needs order data, customer profile, delivery status, and product information together.

Main risk:

The composite tool can become a hidden mini-application. If it starts making too many assumptions, the agent loses flexibility.

Design rule:

Return task-ready context, not a full backend dump. The output should be smaller, clearer, and safer than the raw data sources.

Pattern 3: Resource-Oriented MCP

Not every capability should be a tool. Sometimes the best MCP server exposes structured resources that the client can read and inject as context.

AI Client
  |
MCP Resource: file://project/README.md
MCP Resource: db://customer/123/profile
MCP Resource: config://service/payment
  |
Local or remote data source

When it fits:

The agent needs context more than action. The data is read-only or should be treated as reference material.

When it does not fit:

The model needs to execute a parameterized operation, mutate state, trigger a workflow, or perform a search that has meaningful side effects or cost.

Typical examples:

code repositories
documentation collections
local knowledge bases
generated system state snapshots
configuration views

Main risk:

Overexposure. Raw resource access can accidentally reveal too much. A filesystem server, for example, should not expose the entire machine by default.

Design rule:

Expose curated resources with clear roots, metadata, and permission boundaries. Prefer readable views over unrestricted raw access.

Pattern 4: Agent-Backed Tool

In this pattern, the MCP tool does not call a normal API. It delegates to another AI agent, model, or specialized reasoning component.

Main AI Client
  |
MCP Tool: analyze_code(snippet)
  |
Specialized Analysis Agent

When it fits:

A subtask benefits from a different model, narrower context, specialized tools, or a controlled reasoning workflow.

When it does not fit:

The task is simple enough for the main model. Additional agent hops add latency, cost, and debugging complexity.

Typical examples:

code security review
policy compliance analysis
domain-specific document classification
test generation with a specialized context

Main risk:

Loss of traceability. Once one agent calls another, failures become harder to explain. The main model sees a result, but not necessarily the reasoning quality behind it.

Design rule:

Use agent-backed tools when the subagent produces a bounded, verifiable result. Return evidence, confidence, and limitations where possible.

Pattern 5: Event-Driven Control Surface

Some work should not happen inside a synchronous MCP tool call. The operation may take minutes, involve queues, or run in a background service.

In this pattern, the MCP server exposes a control surface over asynchronous infrastructure.

AI Client
  |
MCP Tool: start_report_generation(params)
  |
Event Queue / Job Scheduler
  |
Report Service
  |
MCP Tool: get_report_status(job_id)
MCP Resource: report://jobs/{job_id}/result

When it fits:

The operation is too slow or too expensive for a normal request-response call. The agent should start the job, receive a job ID, and check status later.

When it does not fit:

The operation is fast and deterministic. Adding a queue for a 200 ms call is unnecessary overhead.

Typical examples:

report generation
long-running data processing
batch imports
document conversion
asynchronous approval workflows

Main risk:

Ambiguous state. If the agent cannot tell whether a job is queued, running, failed, completed, or expired, the workflow becomes unreliable.

Design rule:

Make job state explicit. Provide status, progress, failure reason, result location, cancellation, and retry semantics.

Pattern 6: Gateway or Federated MCP

In larger systems, one MCP server may act as a gateway in front of several domain-specific servers or services. This is not a special MCP primitive. It is an architectural pattern.

Many clients can connect to multiple MCP servers directly. A gateway is useful when you need shared concerns in one place.

AI Client
  |
MCP Gateway: Auth, Routing, Logging, Policy
  |
  +-- Inventory MCP Server
  +-- Order MCP Server
  +-- Customer MCP Server

When it fits:

The system has many domains, teams, or permission boundaries. You need central authentication, routing, audit logging, tool filtering, or rate limiting.

When it does not fit:

The system is small. A gateway then becomes an unnecessary layer between the client and a few simple tools.

Typical examples:

enterprise AI platforms
multi-team internal tool ecosystems
regulated environments
shared company-wide assistant infrastructure

Main risk:

The gateway becomes a bottleneck or a second platform. If every domain change requires gateway changes, team independence disappears.

Design rule:

Use a gateway for cross-cutting policy, not for domain logic. Domain ownership should stay with the domain servers.

A Note on Local Access

Local resource access is often treated as its own category because it feels different from API integration. A local MCP server may read files, inspect repositories, query a local database, or expose an Obsidian vault.

Architecturally, local access usually belongs to one of two patterns:

Resource-Oriented MCP for read-only local context.
Direct or Composite Tools for controlled local actions such as search, indexing, transformation, or file generation.

The key issue is permission scope. Local access can be extremely powerful. A good local MCP server should restrict roots, filter results, avoid leaking secrets, and make dangerous actions explicit.

The Decision Logic

These questions help choose the right pattern:

Question	Best fit
Do I have a simple existing API operation to expose?	Direct API Wrapper
Does the model need one task-level result from several sources?	Composite Service
Is the capability mostly read-only context?	Resource-Oriented MCP
Does the task need another model or specialized reasoning context?	Agent-Backed Tool
Does the operation run asynchronously or take too long for one call?	Event-Driven Control Surface
Do many teams or domains need one shared policy boundary?	Gateway or Federated MCP

The patterns are not mutually exclusive. A production system often combines them:

Gateway MCP
  |
  +-- Composite tools for customer support
  +-- Resource-oriented server for documentation
  +-- Event-driven tools for report generation
  +-- Agent-backed tools for specialized analysis

The more important decision is where complexity should live:

in the MCP server
in the client
in the model prompt
in backend services
in a gateway layer

As a rule, complexity that is deterministic, security-sensitive, or repetitive should live outside the prompt.

Security Questions Every Pattern Needs

Before exposing a capability through MCP, ask:

Is it read-only or can it change state?
Does it require user confirmation?
What is the smallest permission scope that works?
Can the tool leak secrets through raw output?
Is the result structured enough for the model to use safely?
Is the action logged with user, time, input, and result?
Can the operation be replayed safely?
What happens if the model calls the tool with malformed or hostile input?

MCP makes integration easier. It does not make trust boundaries disappear.

Conclusion

Building an MCP server is easy. Building the right MCP server requires a conscious decision about shape, abstraction level, and risk.

Start with the simplest pattern that satisfies the requirement:

direct wrappers for simple API operations
composite tools for repeated multi-source tasks
resources for readable context
agent-backed tools for bounded specialist work
event-driven control surfaces for long-running jobs
gateways only when cross-domain policy really matters

The best MCP server does not expose everything the backend can do. It exposes the smallest stable capability that helps the model complete the task without giving it unnecessary power or unnecessary raw data.

That is the real architecture decision.

References

Official MCP specification and documentation: https://modelcontextprotocol.io/specification/latest
MCP server concepts: https://modelcontextprotocol.io/docs/learn/server-concepts
Official MCP GitHub repository: https://github.com/modelcontextprotocol/modelcontextprotocol

Local AI Pipeline: Why Certain Workloads Never Leave the Machine

Ben Witt — Wed, 08 Jul 2026 08:00:00 +0000

The default assumption is still this: AI means cloud API. You send your text, your audio, or your document to an endpoint, pay per token, and get a result back.

For many tasks, that is perfectly valid.

For a specific class of tasks, it is the wrong default. In my setup, those tasks run locally, on my own hardware, inside my own network. No document or transcript content is sent to an external AI endpoint.

This is not a religious argument about local versus cloud. It is a decision logic. Here is how I think about it, including the real costs.

The Three Reasons, in the Right Order

1. Privacy, and in the DACH region this is not a side issue.

When I transcribe a dictation, tag an invoice, or make private documents searchable, the content is exactly that: private. As soon as this content is sent to an external endpoint, data processing happens outside my own environment, with all the questions that come with it: Where is the data stored, who has access to it, what happens to it after processing, and which legal basis applies?

In Germany, Austria, and Switzerland, this quickly touches topics such as GDPR obligations, data processing agreements, data residency, professional secrecy, and confidential business or financial documents.

Local processing changes the risk profile. It does not magically make a system secure. I still need access control, encrypted backups, patching, and sane container permissions. But it removes one entire class of risk: external AI processing of the content.

That is the clean part. What never goes to an external AI endpoint does not have to be governed, audited, or trusted there.

2. Costs that do not scale per token.

Cloud APIs charge by usage. For rare, large tasks, that is usually acceptable. For frequent, small tasks, every voice note, every scanned document, every small cleanup step, it adds up to a recurring cost that grows with usage.

Local models have the opposite profile: higher upfront cost, mostly the hardware, and then marginal costs that are very low. Not zero, because electricity, storage, time, and maintenance still exist. But the economics change when a workflow runs many times per day.

The break-even point depends less on one spectacular job and more on repetition. Hundreds of small tasks per month can change the calculation faster than one large task per quarter.

3. Latency and independence.

No network round trip. No rate limits. No API outage in the middle of a workflow. No external model deprecation that breaks an automation overnight.

Local does not mean maintenance-free. Docker updates, GPU drivers, CUDA versions, operating system changes, and model updates can still break things. But the failure mode is different. The dependency boundary moves closer to me, into infrastructure I can inspect, pin, and control.

For small interactive workflows, that matters. A push-to-talk transcription tool should feel instant. A document tagging pipeline should not depend on whether an external endpoint is reachable at that exact moment.

What This Looks Like in Practice

My setup is intentionally unspectacular:

Ollama in Docker, with GPU passthrough to an RTX 4070. A quantized mistral:7b model serves as the workhorse for text tasks such as cleaning up transcripts and light classification.
faster-whisper for transcription, integrated into a small push-to-talk tool: hold a key, speak, release it, and the cleaned-up text lands in the clipboard.
Paperless-ngx inside my local network for document management. Paperless runs on the NAS, while AI-assisted tagging is handled by a local model endpoint inside the network.

The pattern is always the same: small, frequent, data-sensitive tasks that do not need peak intelligence, but reliability, privacy, and low friction.

The Honest Part: What It Costs

Local AI has real limits.

Throughput.

In my setup, a quantized 7B model is fast enough for short cleanup and classification tasks. It is not something I would use for long-form heavy reasoning or large unattended batches. The exact speed depends on the model, quantization, backend, context length, GPU, and CPU offloading.

Quality ceiling.

A local 7B model is not a frontier model from the cloud. For cleanup, classification, tagging, and simple transformations, it can be fully sufficient. For demanding reasoning tasks, it is not the right choice.

The important rule is this: the easier the output is to verify, the better the task fits local models. Spelling cleanup, tagging, formatting, and transcript polishing are good candidates. Legal, medical, financial, or strategic reasoning is a different category.

Hardware and maintenance.

The GPU costs money upfront. Docker, drivers, GPU passthrough, model updates, storage, backups, and monitoring become your responsibility. If you do not want to operate that infrastructure, you pay for someone else to operate it as an API fee.

Local security.

Local AI reduces external exposure, but it does not remove operational security. The local machine becomes the trust boundary. If the device is compromised, the NAS is misconfigured, backups are unencrypted, or containers have excessive permissions, the privacy story weakens quickly.

Local is not automatically secure. It is only more controllable.

The Actual Decision

The useful question is not: local or cloud?

The useful question is: what does this specific task need?

Use a cloud API when the task is:

rare
large
complex
dependent on maximum model quality
based on non-sensitive data
not required to work offline

Keep it local when the task is:

frequent
small
data-sensitive
easy to verify
part of a stable workflow
dependent on offline reliability or independence

That is the actual split.

Cloud is excellent when I need the strongest model and the data can leave my environment. Local is excellent when the task repeats often, touches private material, and does not require frontier-level reasoning.

In my case, a surprising number of tasks fall into the second category. Transcription, document management, cleanup steps, tagging, formatting: these are exactly the tasks where I am glad every day that the content stays inside my own environment.

Conclusion

Local AI is not better than cloud AI. It does not have to be.

The interesting question is which tasks should be in the cloud at all. For data-sensitive, frequent, small, and easy-to-verify workflows, my answer is increasingly: none of them.

Local AI changes the default question.

Not: which API should I send this to?

But: why should this leave my machine at all?

A Generic Table API with Dapper in 80 Lines of C#

Ben Witt — Wed, 01 Jul 2026 08:00:00 +0000

Sometimes you quickly need a read-only API on top of a PostgreSQL database.

No Entity Framework setup.

No code generation.

No endpoint per table.

Just query a known table and return the result.

The tempting version is fully dynamic:

GET /api/{table}

That is useful for demos, but dangerous if it means every table in the database suddenly becomes reachable from HTTP.

The safer version is still generic, but not unlimited:

one endpoint, known tables, allowed columns, bounded pagination, read-only database permissions.

That is the version I would use as a practical template.

The Goal

GET /api/transport_orders?$top=50&$skip=0&$orderby=created_at desc
GET /api/business_orders?$top=100
GET /api/handling_units?$top=25&$skip=25

Each call returns a normalized JSON object:

{
  "totalCount": 127,
  "items": []
}

Columns come from PostgreSQL as snake_case and are returned to the client as camelCase. JSON columns can be deserialized so the frontend does not have to parse JSON strings manually.

Setup

NuGet packages:

dotnet add package Dapper
dotnet add package Npgsql

That is it. No ORM, no migrations, no scaffolding.

The Important Boundary: Known Tables Only

The endpoint is generic, but the database surface is not.

Instead of accepting every table name that matches a regex, define the tables and columns the API is allowed to expose:

var tables = new Dictionary<string, TableDefinition>(StringComparer.OrdinalIgnoreCase)
{
    ["transport_orders"] = new(
        Schema: "public",
        Name: "transport_orders",
        Columns: new HashSet<string>(StringComparer.OrdinalIgnoreCase)
        {
            "id",
            "hu_id",
            "state",
            "source_node_name",
            "target_node_name",
            "created_at",
            "is_active",
            "route_nodes"
        }),

    ["business_orders"] = new(
        Schema: "public",
        Name: "business_orders",
        Columns: new HashSet<string>(StringComparer.OrdinalIgnoreCase)
        {
            "id",
            "order_number",
            "state",
            "created_at"
        })
};

This is the difference between a useful internal helper and an accidental database browser.

The Endpoint

Here is a complete minimal API example:

using System.Text.Json;
using System.Text.RegularExpressions;
using Dapper;
using Npgsql;

var builder = WebApplication.CreateBuilder(args);

var rawConnectionString =
    Environment.GetEnvironmentVariable("DATABASE_URL")
    ?? builder.Configuration.GetConnectionString("PostgreSQL")
    ?? throw new InvalidOperationException("No connection string found.");

var connectionString = NormalizeConnectionString(rawConnectionString);

builder.Services.AddSingleton(_ => NpgsqlDataSource.Create(connectionString));

builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(policy =>
        policy
            .WithOrigins("http://localhost:5173")
            .AllowAnyMethod()
            .AllowAnyHeader());
});

var tables = new Dictionary<string, TableDefinition>(StringComparer.OrdinalIgnoreCase)
{
    ["transport_orders"] = new(
        Schema: "public",
        Name: "transport_orders",
        Columns: new HashSet<string>(StringComparer.OrdinalIgnoreCase)
        {
            "id",
            "hu_id",
            "state",
            "source_node_name",
            "target_node_name",
            "created_at",
            "is_active",
            "route_nodes"
        }),

    ["business_orders"] = new(
        Schema: "public",
        Name: "business_orders",
        Columns: new HashSet<string>(StringComparer.OrdinalIgnoreCase)
        {
            "id",
            "order_number",
            "state",
            "created_at"
        })
};

var app = builder.Build();
app.UseCors();

app.MapGet("/api/{table}", async Task<IResult> (
    string table,
    HttpRequest request,
    NpgsqlDataSource dataSource,
    CancellationToken cancellationToken) =>
{
    if (!tables.TryGetValue(table, out var tableDefinition))
        return Results.NotFound($"Table '{table}' is not exposed by this API.");

    var top = ParseBoundedInt(request.Query["$top"], defaultValue: 100, min: 1, max: 500);
    var skip = ParseBoundedInt(request.Query["$skip"], defaultValue: 0, min: 0, max: 100_000);

    if (!TryBuildOrderBy(
            request.Query["$orderby"].FirstOrDefault(),
            tableDefinition,
            out var orderByClause,
            out var orderByError))
    {
        return Results.BadRequest(orderByError);
    }

    var qualifiedTable = QualifiedTableName(tableDefinition);
    var columnList = string.Join(", ", tableDefinition.Columns.Select(QuoteIdentifier));

    var countSql = $"SELECT COUNT(*) FROM {qualifiedTable}";
    var dataSql = $"""
        SELECT {columnList}
        FROM {qualifiedTable}
        {orderByClause}
        LIMIT @top OFFSET @skip
        """;

    await using var db = await dataSource.OpenConnectionAsync(cancellationToken);

    var totalCount = await db.ExecuteScalarAsync<long>(
        new CommandDefinition(countSql, cancellationToken: cancellationToken));

    var rows = await db.QueryAsync(
        new CommandDefinition(dataSql, new { top, skip }, cancellationToken: cancellationToken));

    return Results.Ok(new
    {
        totalCount,
        items = ToCamelCaseKeys(rows)
    });
});

app.MapGet("/health", () => Results.Ok(new { status = "ok" }));

app.Run();

record TableDefinition(
    string Schema,
    string Name,
    IReadOnlySet<string> Columns);

Helper Functions

Normalize the connection string

Many cloud providers expose PostgreSQL connection strings as URLs:

postgresql://user:password@host:5432/database

Npgsql primarily documents key-value connection strings:

Host=...;Port=...;Database=...;Username=...;Password=...

This helper handles the common URL shape. If your provider includes important query parameters such as SSL settings, preserve them explicitly or use the key-value connection string directly.

static string NormalizeConnectionString(string value)
{
    if (!Uri.TryCreate(value, UriKind.Absolute, out var uri))
        return value;

    if (uri.Scheme is not ("postgres" or "postgresql"))
        return value;

    var userInfo = uri.UserInfo.Split(':', 2);

    var builder = new NpgsqlConnectionStringBuilder
    {
        Host = uri.Host,
        Port = uri.Port > 0 ? uri.Port : 5432,
        Database = Uri.UnescapeDataString(uri.AbsolutePath.TrimStart('/'))
    };

    if (userInfo.Length > 0)
        builder.Username = Uri.UnescapeDataString(userInfo[0]);

    if (userInfo.Length > 1)
        builder.Password = Uri.UnescapeDataString(userInfo[1]);

    return builder.ConnectionString;
}

Bound pagination

Never let the client decide unlimited page sizes.

static int ParseBoundedInt(
    string? value,
    int defaultValue,
    int min,
    int max)
{
    if (!int.TryParse(value, out var parsed))
        return defaultValue;

    return Math.Clamp(parsed, min, max);
}

Quote identifiers

Identifiers cannot be passed as SQL parameters. That is why the allow-list is the real protection. Quoting is still useful because it avoids problems with reserved words or unusual casing.

static string QuoteIdentifier(string identifier) =>
    "\"" + identifier.Replace("\"", "\"\"") + "\"";

static string QualifiedTableName(TableDefinition table) =>
    $"{QuoteIdentifier(table.Schema)}.{QuoteIdentifier(table.Name)}";

Validate `$orderby`

The $orderby parameter is not free-form SQL. It is a small language:

created_at desc
created_at desc, id asc

Every column must exist in the table allow-list.

static bool TryBuildOrderBy(
    string? orderBy,
    TableDefinition table,
    out string clause,
    out string? error)
{
    clause = string.Empty;
    error = null;

    if (string.IsNullOrWhiteSpace(orderBy))
        return true;

    var parts = orderBy.Split(
        ',',
        StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries);

    var fragments = new List<string>();

    foreach (var part in parts)
    {
        var match = Regex.Match(
            part,
            @"^(?<column>[a-zA-Z_][a-zA-Z0-9_]*)(\s+(?<direction>asc|desc))?$",
            RegexOptions.IgnoreCase);

        if (!match.Success)
        {
            error = "Invalid $orderby syntax.";
            return false;
        }

        var column = match.Groups["column"].Value;

        if (!table.Columns.Contains(column))
        {
            error = $"Column '{column}' is not allowed in $orderby.";
            return false;
        }

        var direction = match.Groups["direction"].Success
            ? match.Groups["direction"].Value.ToUpperInvariant()
            : "ASC";

        fragments.Add($"{QuoteIdentifier(column)} {direction}");
    }

    clause = fragments.Count > 0
        ? "ORDER BY " + string.Join(", ", fragments)
        : string.Empty;

    return true;
}

Convert `snake_case` keys to `camelCase`

Dapper returns column names as they come from the database. The API can normalize them for frontend use.

static string ToCamelCase(string value)
{
    if (string.IsNullOrWhiteSpace(value))
        return value;

    var parts = value.Split('_', StringSplitOptions.RemoveEmptyEntries);

    if (parts.Length == 0)
        return value;

    return parts[0].ToLowerInvariant()
           + string.Concat(parts.Skip(1).Select(part =>
               char.ToUpperInvariant(part[0]) + part[1..].ToLowerInvariant()));
}

static IEnumerable<Dictionary<string, object?>> ToCamelCaseKeys(IEnumerable<dynamic> rows) =>
    rows.Select(row => ((IDictionary<string, object?>)row)
        .ToDictionary(
            pair => ToCamelCase(pair.Key),
            pair => TryParseJson(pair.Value)));

Parse JSON strings carefully

If you query dynamically with Dapper, JSONB values may arrive as strings. This helper parses strings that look like JSON objects or arrays.

This is a convenience heuristic, not a perfect type system. If you know the schema, prefer type-aware JSON mapping.

static object? TryParseJson(object? value)
{
    if (value is not string text)
        return value;

    var trimmed = text.TrimStart();

    if (trimmed.Length == 0 || (trimmed[0] is not ('{' or '[')))
        return value;

    try
    {
        using var document = JsonDocument.Parse(text);
        return document.RootElement.Clone();
    }
    catch (JsonException)
    {
        return value;
    }
}

Security: What This Protects

This version protects against the most important mistakes in a dynamic read endpoint:

unknown tables are rejected
unknown columns are not selected
$orderby can only use allowed columns
identifiers are quoted
$top and $skip are bounded
SQL values still use parameters
CORS is restricted to a known frontend origin

But this is still not a full production data access layer.

For production, also use:

a dedicated read-only PostgreSQL user
authentication and authorization at the API boundary
row-level or tenant-level filtering if needed
explicit decisions about sensitive columns
logging and rate limiting
optional total counts for large tables

The most important point:

A generic endpoint should not mean generic database access.

The Result

GET /api/transport_orders?$top=5&$orderby=created_at desc

{
  "totalCount": 127,
  "items": [
    {
      "id": "c720153c-3d9f-4764-8d5a-87bd5ed1594a",
      "huId": "341994",
      "state": "Failed",
      "sourceNodeName": "IP01",
      "targetNodeName": "A01-L-001-02-1",
      "createdAt": "2026-03-26T13:41:38.966Z",
      "isActive": false,
      "routeNodes": ["IP01", "A01-L-001-02-1"]
    }
  ]
}

snake_case from PostgreSQL arrives at the client as camelCase. JSON arrays such as routeNodes can be returned as JSON arrays instead of strings.

When This Makes Sense

This approach fits when:

you need a quick read-only API over existing tables
the exposed tables are known and stable
you want direct SQL without ORM setup
the API is for an internal tool, demo, or prototype
the shape is simple: list rows, page rows, sort rows

It does not fit when:

complex joins or aggregations are required
business logic belongs in the API layer
fine-grained access control is required
rows must be filtered per tenant or user
the database contains sensitive columns you cannot safely expose

Conclusion

Dapper is a good fit for this kind of endpoint: small surface, direct SQL, minimal ceremony.

But the naive version is too open. A regex around the table name is not enough. The safer pattern is:

one generic endpoint
explicit table allow-list
explicit column allow-list
bounded pagination
validated sorting
read-only database credentials

That keeps the useful part of the idea without turning the API into an accidental database browser.

References

Npgsql connection string parameters: https://www.npgsql.org/doc/connection-string-parameters.html
Npgsql JSON mapping: https://www.npgsql.org/doc/types/json.html

Semantic Search with PostgreSQL: Pragmatism Beats Hype - Most of the Time

Ben Witt — Wed, 24 Jun 2026 08:00:00 +0000

When you start adding semantic search to an application, the obvious options are often Pinecone, Weaviate, Qdrant, Milvus, or another dedicated vector database.

That can be the right choice.

But many applications already have a PostgreSQL database running. And for a large class of semantic search use cases, that database can do the job directly.

The key is pgvector, an open-source PostgreSQL extension that adds vector types and vector similarity search to Postgres. It lets you store embeddings next to your relational data and query them with SQL.

The advantage is not only fewer moving parts. It is also architectural:

No separate sync pipeline, no second source of truth, and no extra infrastructure until you actually need it.

Semantic Search in One Sentence

Classic search compares words. Semantic search compares meaning.

The query "How do I get over the pass?" can find a text about a mountain pass rather than a school hallway because both the query and the documents are represented as numerical vectors, also called embeddings.

The basic flow is:

Convert text into an embedding vector.
Store that vector in PostgreSQL.
Convert the search query into the same vector space.
Find the stored vectors closest to the query vector.

The phrase "same vector space" matters. You cannot freely mix embeddings from different models.

The Most Important Design Decision: The Embedding Model

Before creating the database schema, choose the embedding model.

That choice determines:

vector dimension
embedding quality
cost
latency
privacy profile
whether text leaves your environment

For example, if you use OpenAI text-embedding-3-small, a vector(1536) column is a common fit. If you use another model, including a local model through Ollama, the dimension may be different.

This is not a detail. PostgreSQL will reject vectors with the wrong number of dimensions.

If you later change the embedding model, plan to:

add a new vector column or table
re-embed all documents
rebuild the vector index
avoid comparing old and new embeddings directly

Embedding model changes are data migrations.

Installing pgvector

Enable the extension once in the database:

CREATE EXTENSION IF NOT EXISTS vector;

With managed PostgreSQL providers, check whether pgvector is available on your plan and PostgreSQL version. Many providers support it, but you should verify this before designing around it.

Schema: Store Chunks, Not Just Documents

For small records, one vector per row is fine.

For real documents, it is usually better to embed chunks. A long document may cover several topics. One vector for the entire document often becomes too blurry.

A practical schema:

CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    title       TEXT NOT NULL,
    source      TEXT,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE document_chunks (
    id           BIGSERIAL PRIMARY KEY,
    document_id  BIGINT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
    chunk_index  INTEGER NOT NULL,
    content      TEXT NOT NULL,
    embedding    vector(1536) NOT NULL,
    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (document_id, chunk_index)
);

Use vector(1536) only if your embedding model actually returns 1536-dimensional vectors. Otherwise, change the dimension to match the model.

Integration in .NET with Npgsql

Install the packages:

dotnet add package Npgsql
dotnet add package Pgvector

If you use Dapper, also add:

dotnet add package Pgvector.Dapper

For raw Npgsql, configure the data source with UseVector():

using Npgsql;
using Pgvector;

var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.UseVector();

await using var dataSource = dataSourceBuilder.Build();

In production, create the extension and tables through migrations or database provisioning. If you create the extension at runtime, reload PostgreSQL types on the connection before using the new type.

Generating Embeddings with OpenAI

With the OpenAI .NET SDK:

using OpenAI.Embeddings;

var embeddingClient = new EmbeddingClient("text-embedding-3-small", apiKey);

async Task<float[]> GetEmbeddingAsync(string text)
{
    var result = await embeddingClient.GenerateEmbeddingAsync(text);
    return result.Value.ToFloats().ToArray();
}

For local embeddings, use a local embedding model through your preferred provider. The important rule is the same:

The model used for indexing and the model used for querying must be the same, or at least intentionally compatible.

Do not index documents with one model and query them with another.

Storing a Document Chunk

async Task InsertChunkAsync(
    long documentId,
    int chunkIndex,
    string content,
    CancellationToken cancellationToken = default)
{
    var embedding = await GetEmbeddingAsync(content);
    var vector = new Vector(embedding);

    await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);
    await using var cmd = new NpgsqlCommand("""
        INSERT INTO document_chunks (document_id, chunk_index, content, embedding)
        VALUES (@documentId, @chunkIndex, @content, @embedding)
        ON CONFLICT (document_id, chunk_index)
        DO UPDATE SET
            content = EXCLUDED.content,
            embedding = EXCLUDED.embedding
        """, conn);

    cmd.Parameters.AddWithValue("documentId", documentId);
    cmd.Parameters.AddWithValue("chunkIndex", chunkIndex);
    cmd.Parameters.AddWithValue("content", content);
    cmd.Parameters.AddWithValue("embedding", vector);

    await cmd.ExecuteNonQueryAsync(cancellationToken);
}

The important part is the update path. If the content changes, the embedding must change too.

Semantic Search

The <=> operator calculates cosine distance. A smaller value means higher similarity. ORDER BY ... ASC returns the nearest vectors first.

public sealed record SearchResult(
    long DocumentId,
    long ChunkId,
    string Title,
    string Content,
    double Distance);

async Task<List<SearchResult>> SearchAsync(
    string query,
    int limit = 5,
    CancellationToken cancellationToken = default)
{
    var queryEmbedding = await GetEmbeddingAsync(query);
    var queryVector = new Vector(queryEmbedding);

    await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);
    await using var cmd = new NpgsqlCommand("""
        SELECT d.id,
               c.id,
               d.title,
               c.content,
               c.embedding <=> @queryVector AS distance
        FROM document_chunks c
        JOIN documents d ON d.id = c.document_id
        ORDER BY c.embedding <=> @queryVector
        LIMIT @limit
        """, conn);

    cmd.Parameters.AddWithValue("queryVector", queryVector);
    cmd.Parameters.AddWithValue("limit", limit);

    var results = new List<SearchResult>();

    await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);
    while (await reader.ReadAsync(cancellationToken))
    {
        results.Add(new SearchResult(
            DocumentId: reader.GetInt64(0),
            ChunkId: reader.GetInt64(1),
            Title: reader.GetString(2),
            Content: reader.GetString(3),
            Distance: reader.GetDouble(4)));
    }

    return results;
}

Notice that the query orders by the distance expression directly. With pgvector indexes, the ORDER BY embedding <=> @query LIMIT n shape is important.

Distance Operators

pgvector supports several distance operators:

Operator	Meaning	Typical use
`<=>`	cosine distance	text embeddings and semantic search
`<->`	L2 / Euclidean distance	general vector distance, images, spatial-like embeddings
`<#>`	negative inner product	inner-product search; multiply by `-1` for the actual value
`<+>`	L1 distance	absolute-distance use cases
`<~>`	Hamming distance	binary vectors
`<%>`	Jaccard distance	binary vectors

For most text embedding use cases, cosine distance is a good default.

Creating an Index with HNSW

Without an index, PostgreSQL scans the table for every vector search. That is exact and simple, but it becomes slow as the number of vectors grows.

HNSW is often the best starting index for application search:

CREATE INDEX document_chunks_embedding_hnsw_idx
ON document_chunks
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

The parameters:

m: maximum number of connections per layer; default is 16
ef_construction: candidate list size during index construction; default is 64

Higher values can improve recall, but increase memory usage and build time.

You can tune search recall per query:

SET hnsw.ef_search = 100;

or for one transaction:

BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;

Important: HNSW is approximate. It trades perfect recall for speed.

IVFFlat as an Alternative

IVFFlat can use less memory and build faster than HNSW, but usually has a weaker speed-recall trade-off.

CREATE INDEX document_chunks_embedding_ivfflat_idx
ON document_chunks
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

Do not create an IVFFlat index on an empty table. It needs data to form the lists.

A practical starting point for lists:

rows / 1000 for up to 1M rows
sqrt(rows) for over 1M rows

For 10,000 vectors, start around 10 lists, not 100.

At query time, tune probes:

SET ivfflat.probes = 10;

Higher probes improve recall and reduce speed.

Filtering and Hybrid Search

One of the strongest reasons to use pgvector is that vectors live next to relational data.

You can filter before searching:

SELECT d.id, d.title, c.content, c.embedding <=> @queryVector AS distance
FROM document_chunks c
JOIN documents d ON d.id = c.document_id
WHERE d.created_at > NOW() - INTERVAL '30 days'
  AND d.source = 'documentation'
ORDER BY c.embedding <=> @queryVector
LIMIT 10;

For true hybrid search, do not just calculate keyword rank and then ignore it. Combine semantic and keyword ranks.

One practical pattern is Reciprocal Rank Fusion-style scoring:

WITH semantic AS (
    SELECT c.id,
           row_number() OVER (ORDER BY c.embedding <=> @queryVector) AS semantic_rank
    FROM document_chunks c
    LIMIT 100
),
keyword AS (
    SELECT c.id,
           row_number() OVER (
               ORDER BY ts_rank_cd(
                   to_tsvector('english', c.content),
                   plainto_tsquery('english', @query)
               ) DESC
           ) AS keyword_rank
    FROM document_chunks c
    WHERE to_tsvector('english', c.content) @@ plainto_tsquery('english', @query)
    LIMIT 100
)
SELECT d.id AS document_id,
       c.id AS chunk_id,
       d.title,
       c.content,
       COALESCE(1.0 / (60 + semantic.semantic_rank), 0) +
       COALESCE(1.0 / (60 + keyword.keyword_rank), 0) AS score
FROM semantic
FULL OUTER JOIN keyword ON keyword.id = semantic.id
JOIN document_chunks c ON c.id = COALESCE(semantic.id, keyword.id)
JOIN documents d ON d.id = c.document_id
ORDER BY score DESC
LIMIT 10;

This is not the only way to do hybrid search, but it makes the ranking logic explicit.

When pgvector Is the Right Choice

pgvector is a strong choice when:

PostgreSQL is already your primary database
vectors need to join naturally with relational data
transactional consistency matters
your team already knows PostgreSQL operations
the dataset is small to medium sized
you want to avoid another service and sync pipeline

It is especially good for internal search, product search, support tools, documentation search, and RAG systems where the relational database is already the source of truth.

When a Dedicated Vector Store May Be Better

A dedicated vector database is worth considering when:

vector count grows into tens of millions or more
query volume is very high and latency budgets are strict
you need specialized managed operations around vector search
you need advanced built-in hybrid search, reranking, or filtering behavior
your team does not operate PostgreSQL deeply
multi-tenant isolation and scaling are central requirements

The decision is not ideology. It is operational fit.

Complete ASP.NET Core Example

app.MapGet("/search", async (
    string q,
    NpgsqlDataSource db,
    CancellationToken cancellationToken) =>
{
    var queryEmbedding = await GetEmbeddingAsync(q);
    var queryVector = new Vector(queryEmbedding);

    await using var conn = await db.OpenConnectionAsync(cancellationToken);
    await using var cmd = new NpgsqlCommand("""
        SELECT d.id,
               c.id,
               d.title,
               c.content,
               c.embedding <=> @v AS distance
        FROM document_chunks c
        JOIN documents d ON d.id = c.document_id
        ORDER BY c.embedding <=> @v
        LIMIT 5
        """, conn);

    cmd.Parameters.AddWithValue("v", queryVector);

    var results = new List<object>();

    await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);
    while (await reader.ReadAsync(cancellationToken))
    {
        results.Add(new
        {
            documentId = reader.GetInt64(0),
            chunkId = reader.GetInt64(1),
            title = reader.GetString(2),
            content = reader.GetString(3),
            distance = reader.GetDouble(4)
        });
    }

    return Results.Ok(results);
});

Conclusion

Semantic search does not always require a separate vector database.

If PostgreSQL is already your source of truth, pgvector lets you store embeddings next to relational data, query them with SQL, filter with normal PostgreSQL conditions, and keep transactions in one system.

But the clean version has a few rules:

choose the embedding model before choosing the vector dimension
do not mix embeddings from different models
chunk documents when they are long or multi-topic
index only when the table is large enough to need it
remember that HNSW and IVFFlat are approximate
treat model changes as data migrations

For many production applications, pgvector is enough for a long time. Not because dedicated vector databases are unnecessary, but because the simplest reliable architecture is often the one that keeps the data where it already lives.

References

pgvector README: https://github.com/pgvector/pgvector
pgvector .NET support: https://github.com/pgvector/pgvector-dotnet
OpenAI .NET SDK: https://github.com/openai/openai-dotnet
OpenAI embeddings guide: https://platform.openai.com/docs/guides/embeddings
Microsoft.Extensions.AI: https://learn.microsoft.com/en-us/dotnet/ai/microsoft-extensions-ai

Stop Loading Your Entire Instruction System Into Every Session

Ben Witt — Wed, 17 Jun 2026 08:00:00 +0000

Most people talk about better prompts. Hardly anyone talks about what happens before every prompt: the instructions the assistant loads into the context before the actual work begins.

Depending on the system, you pay for that in different ways: input tokens, latency, reduced available context, or simply more noise in the assistant's active instructions. Even if the financial cost is partly reduced through prompt caching, the cognitive cost remains: the assistant still has to operate inside a larger instruction environment.

At some point, my setup had become one single, constantly growing instruction file. System structure, assistant personality, workflows, session rules, special cases: everything was in one file. And everything was loaded into the context on every interaction, no matter whether I was solving a complex task or just asking a quick question.

That is roughly like starting every phone call by reading the entire employee handbook before getting to the actual topic.

The Actual Problem

A monolithic instruction file has two costs that become unpleasant when combined:

The baseline gets expensive.

Most of the file is irrelevant to the concrete task. Still, it sits in the active context. Depending on the system, that means token cost, latency, less room for the real task, or all of them at once.
The signal-to-noise ratio drops.

The more rules and special cases you add, the more the currently relevant part gets diluted. More context does not automatically mean more competence.

Both scale in the wrong direction: the more mature your setup becomes, the heavier and less precise it gets, as long as everything lives in one file.

The Insight

Not all instructions are needed all the time.

I always need the assistant's personality and basic operating principles. I only need the exact structure of my project system when I actually navigate through it. I only need the session-end rules at the end of a session, and never before that.

A writing task does not need filesystem navigation rules.

A quick reasoning task does not need session-close workflows.

A debugging session does not need publishing guidelines.

If that is true, it makes no sense to keep everything loaded permanently.

The Architecture

I split the one large file into a lean entry point plus specialized modules:

.config/
├── instructions.md   -> compact entry point, always loaded
├── persona.md        -> personality, tone, behavior
├── structure.md      -> system structure, only relevant for navigation
└── workflows.md      -> session workflows, only relevant when needed

The main instruction file is now intentionally small. It contains the minimum that really has to be present in every session, plus clear references: which module is responsible for what, and when it should be loaded.

The detail modules are not active by default. They are accessible, but they only become part of the context when the task requires them.

That distinction matters. The full instruction set is not magically present for free. It is only available if the assistant knows that a module exists, recognizes that it is relevant, and loads it at the right moment.

So modularization does not mean: same context, lower cost.

It means: smaller baseline, with more responsibility placed on routing and loading.

How Loading Works

In my setup, the entry point acts as a router. It does not contain all detailed rules. It contains short loading rules such as:

If the task involves navigating the project system,
load structure.md before answering.

If the task involves ending or reviewing a session,
load workflows.md before making recommendations.

If the task is a quick standalone question,
do not load additional modules unless needed.

This is simple, but it is also the fragile part of the system. If the entry point is vague, the assistant may fail to load the right module. If it is too broad, it loads too much again and the benefit disappears.

The quality of the entry point determines the quality of the whole architecture.

The Result

In my setup, the baseline token load per session dropped by around 60-80%.

I measured this by comparing the files that were previously loaded unconditionally at session start with the files that are now loaded unconditionally. The important number is not the total size of all available instructions. It is the size of the always-loaded baseline.

Before modularization:

Always loaded:
instructions.md
persona.md
structure.md
workflows.md

Baseline load:
~4,800 tokens

After modularization:

Always loaded:
instructions.md
persona.md

Baseline load:
~1,450 tokens

Reduction:
69.8%

The full instruction set still exists, but it is no longer active by default. It becomes active only when needed.

Why This Works

The trick is not compressing individual instructions. The trick is separating baseline load from on-demand load.

Baseline load: what is loaded in every session. This is where the savings matter most, because this cost is paid repeatedly.
On-demand load: what is only relevant in specific situations. This can be large and detailed, as long as it is loaded only when it actually matters.

So you are not optimizing the total size of your instructions. You are optimizing which part of them must always be present. And that is surprisingly little.

Prompt caching can reduce the financial cost of repeated baseline instructions in some systems. But it does not remove the context-budget cost, the latency implications in every environment, or the signal-to-noise problem. A cached irrelevant instruction is still an irrelevant instruction in the active instruction set.

What It Costs

This is not a free lunch.

Indirection:
The assistant sometimes has to take an extra step to load the right module. That is slightly slower and creates the risk that the right module is not loaded.
Routing errors:
If the assistant does not recognize that a task requires a module, it may answer with incomplete instructions. This is the main operational risk.
Maintenance:
More files mean more places that can drift apart. If the entry point promises something that no longer exists in a module, you have a silent consistency problem.
Rule conflicts:
Modules can contradict each other or the entry point. You need a precedence rule: general instructions define the default, specialized modules override them only within their domain, and explicit user instructions still have to be handled according to the system's hierarchy.
Onboarding:
An outsider first has to understand the loading logic before the system becomes readable. A single file is trivial to understand.

The real trade-off is this:

You reduce baseline cost, but you give up permanent availability. You move complexity from runtime context into structure, routing, and maintenance.

When It Is Worth It

It is worth it if:

your instruction set is large and has grown over time
you start sessions frequently and baseline cost is noticeable
clearly separable situations exist, such as navigation, session-end handling, publishing, coding, or special workflows
your environment allows the assistant to load additional instruction files reliably

It is not worth it if your entire setup fits into a few hundred tokens anyway. In that case, modularization is premature optimization: you trade real simplicity for imagined efficiency.

It is also not worth it if the assistant cannot reliably access the modules when needed. A small always-loaded file plus inaccessible detail files is not an architecture. It is missing context with extra steps.

Conclusion

The biggest lever for instruction cost is rarely a better prompt. It is the question of what you force the assistant to carry into every interaction, and what it should only load when needed.

Separate baseline load from on-demand load. Keep the entry point small and turn it into a precise router. Leave the details where they only create cost when they are actually needed.

In my case, that meant 60-80% less baseline load. But the important part is not just the savings. It is the trade-off: less permanent context, more deliberate loading.

That is the architecture I actually want. Not less instruction, but less unnecessary instruction in the room at the wrong time.

The Most Dangerous Bias of Your AI Assistant Is That It Agrees With You

Ben Witt — Wed, 10 Jun 2026 08:00:00 +0000

We talk a lot about hallucinations. But there is another failure mode we should take just as seriously: AI assistants are optimized to be helpful, polite, and cooperative. Over a longer session, that can quietly turn into agreeableness.

In a system that is supposed to help you think, this is not a cosmetic problem. It is the core problem. An assistant that agrees with you simply because you are the one asking is worthless as a sparring partner. It confirms your bad ideas just as readily as your good ones.

I call this sycophancy drift, and I have added a reflective layer to my knowledge system to detect it.

What Sycophancy Drift Is

At the beginning of a session, the assistant still pushes back. You make a suggestion, and it gives you three reasons against it. Good.

Twenty messages later, the tone is different. You suggest something, and suddenly everything is “a good point,” “absolutely reasonable,” or “a strong idea.” Not because your ideas have necessarily become better, but because the conversation context has increasingly conditioned the assistant toward agreement.

To be precise: the model is not learning in the training sense. Its weights are not changing during the session. But the transcript becomes part of the active context, and that context can reward a pattern. If agreement keeps the conversation moving, the assistant may drift toward more agreement.

That is the drift: a gradual shift from honest evaluation to confirmation.

This is not speculation. Anthropic’s own research (Perez et al. 2022; Sharma et al. 2023) shows that RLHF training systematically rewards agreement: both human raters and preference models prefer convincingly written sycophantic answers over correct ones a non-negligible fraction of the time. The disposition is built in at training time. A long conversation does not create it - it amplifies it.

Why You Do Not Notice It

Because it feels good. That is the whole trick.

Hallucinations stand out because they are wrong. Sycophancy does not stand out because it is pleasant. You feel confirmed, you move forward, the session feels productive, and nobody tells you that the quality of disagreement has quietly dropped.

Message 5:
Assistant:
"I see three major risks."

Message 35:
Assistant:
"That's a very strong idea."

Drift warning:
Criticism frequency dropped from 4 objections
per proposal to 0.8 objections per proposal.

(Schematic illustration; the actual reports are qualitative)

This is exactly why the assistant cannot reliably correct this in real time by itself. It is inside the same conversational pressure. You need an outside view, or at least a retrospective one.

The Idea: A Reflective Layer at the End of the Session

In my setup, the assistant does not rewrite its own rules automatically. Instead, I use a dedicated reflective layer after a session has ended.

The process is intentionally simple:

At the end of a session, the analysis layer is explicitly triggered.
It reads the transcript of the entire session.
It compares the session against an explicit, versioned rule set.
It writes a structured proposal with four sections:

New rules: what this session produced as lessons.
Confirmed rules: what proved useful again.
Drift warnings: where the assistant agreed too much or weakened its criticism.
Recommendation: what should be added to the rule set.

The decisive point is this: it is only a proposal. It is written for human review. Not a single rule changes automatically.

What the Layer Actually Flags

The layer does not look for politeness. Politeness is not the problem.

It looks for disappearing resistance:

fewer objections over time
softer risk language
repeated validation phrases
missing alternative paths
ignored counterarguments
praise replacing evaluation
earlier rules being quietly weakened
decisions accepted without checking trade-offs

The goal is not to make the assistant negative. The goal is to preserve useful friction.

A good thinking partner should not disagree for sport. But it should notice when the session has become too smooth.

Three Design Decisions That Make the Difference

1. Human in the loop, not out of caution, but out of logic.

It would be tempting to let the analysis layer write its findings directly into the rule set. That would be the mistake. You would let a system that is prone to conversational drift rewrite its own anti-drift rules.

Separating proposal from adoption is not a comfort feature. It is the safety mechanism that makes the whole concept meaningful.

There is also a simple technical reality in my setup: the assistant has no autonomous background process and no unchecked memory update across sessions. Every change is conscious, triggered, and reviewable. This is not a limitation I want to bypass. It is the property that keeps the system honest.

2. Importance and frequency are two different axes.

Every rule has two independent dimensions: an importance value and a frequency counter.

A rule can occur rarely and still be critical. If I mix both dimensions together, the rare but important rule will eventually disappear because it looks statistically insignificant. That is why critical rules are protected from being archived, no matter how rarely they are triggered.

3. A maximum of five new rules per session.

Without a limit, the system overfits to a single conversation. One intense session could flood the rule set with special cases that may never matter again.

The upper limit forces selection: what was truly a lesson, and what was just noise?

Five is not a magic number. It is calibrated to my review capacity: a proposal I cannot review in five minutes is a proposal I will eventually stop reading and an unreviewed proposal pipeline is worse than none.

The Honest Part: The Recursion Problem

The obvious weakness is this: I am using the same kind of model that drifted to detect its own drift. Can an assistant that tends to agree really expose its own agreement reliably?

The honest answer is: not perfectly.

A retrospective layer can itself become performative. It may learn to produce the kind of criticism the user expects, without actually identifying meaningful drift. It may become another agreeable ritual: “Here are your drift warnings,” even when the analysis is shallow.

But the approach is still useful for two reasons.

First, checking a finished transcript against an explicit checklist is a narrower task than generating helpful answers in the middle of a live conversation. Evaluation is not the same as participation.

Second, the result is not trusted blindly. A human reviews it. The layer does not have to detect drift perfectly. It only has to make the pattern visible enough to question.

Additional costs:

No real-time feedback. Drift during the current session is detected afterwards, for the next run.
Review effort. Reading proposals and deciding what to adopt is work.
False confidence. A reflective layer can look more objective than it really is.

That last point matters. The layer is not a guarantee. It is a mirror.

The industry attacks the same problem one level deeper: Anthropic’s persona-vector research identifies activation patterns associated with sycophancy and steers models away from them during training. That is the right fix at the model level. But it cannot reach the workflow level — no lab can review whether your assistant pushed back on your architecture decision yesterday. That layer is yours to build.

When It Is Worth It

If you use the assistant as a thinking tool, where honest disagreement is part of the value, then drift detection is not a nice extra. It is one of the conditions under which the tool works at all.

If you only use the assistant for clearly defined execution tasks, where agreement does not matter much, you probably do not need this.

But if the assistant helps shape your decisions, your architecture, your writing, your strategy, or your beliefs, then you should care about how much resistance disappears over time.

Conclusion

The labs are working on this at the training level, evals, steering, character training. What is largely missing is the workflow level: per-user, per-session drift detection that you control.

The most pleasant bias may also be the most dangerous one: an assistant that agrees with you feels like a good assistant while it slowly stops being useful as a thinking partner.

The solution is not simply a better model version. It is a layer that looks back after the work is done, names the drift, and leaves the decision with you.

The assistant should not only help you move faster. It should also preserve the friction that keeps your thinking honesty.

Part II will follow later

Transitive Dependency – Challenges and Approaches in .NET

Ben Witt — Wed, 12 Feb 2025 09:00:00 +0000

Imagine you are developing a .NET application that runs perfectly at first. Suddenly, however, unexpected runtime errors occur—even though your main project does not explicitly include any additional packages. How can this phenomenon be explained? Often, the cause is a transitive dependency: a library such as Entity Framework Core is silently included in your project via another NuGet package. In complex application scenarios, this issue can lead to version conflicts or even hard-to-diagnose runtime errors like the MissingMethodException. Without targeted management of these dependencies, the effort required for error resolution can become significant.

1. Basics and Problem Statement

1.1 Transitive References vs. Transitive Dependencies

Transitive References:

In a multi-layered solution structure, for example, Project A directly references Project B, which in turn uses Project C. In this way, Project A has an indirect (transitive) reference to Project C—even if it is not explicitly listed in the .csproj file.
Transitive Dependencies:

With external NuGet packages, the problem appears when they are brought in by a referenced package and do not show up in the main project’s .csproj file. For instance, if Project A uses a package (e.g., PackageX) that internally references EF Core in a specific version, then EF Core is included transitively—even though Project A never explicitly added it.

Isn’t it remarkable how quickly such subtle dependency chains can emerge in large projects without being noticed?

1.2 A Typical Scenario in .NET

In many .NET applications, Entity Framework Core (EF Core) is used as the data access library. Even if the main project does not directly reference EF Core, it can be silently included as a transitive dependency via another utility or data access package. Initially, everything seems to work smoothly—EF Core provides a stable API. However, when updating the .NET framework or integrating new features, version conflicts may occur that eventually lead to hard-to-diagnose runtime errors.

2. Detailed Solution Approaches

To prevent the unwanted propagation of packages, two main approaches are available: the targeted restriction of individual packages using PrivateAssets="all" or the complete deactivation of transitive project references with <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>. Both approaches are critically examined below.

2.1 `PrivateAssets="all"`

By adding the attribute PrivateAssets="all" in the PackageReference, you prevent the respective library from being passed on to other projects in the dependency hierarchy. This way, the package—and its transitive dependencies—remain available only within the current project.

Advantages:

Granularity: You decide on a package-by-package basis whether a dependency should be inherited.
Avoidance of Side Effects: Problematic libraries are not automatically transferred to subordinate projects.

Disadvantages:

Increased Configuration Effort: If another project needs the same library, it must be explicitly referenced again.

Example:

<ItemGroup>
  <PackageReference Include="SomeDataAccessPackage" Version="1.2.3" PrivateAssets="all" />
</ItemGroup>

Could it be that in complex environments the administrative effort for such package-specific configuration outweighs the benefits?

2.2 DisableTransitiveProjectReferences

With the global setting true in the .csproj file, you prevent the automatic propagation of all transitive project references. Every project must then explicitly list all the required packages.

Advantages:
• Increased Transparency: All dependencies are explicitly visible and controllable.
• Prevention of Unintended Inclusions: No “hidden” libraries are automatically added to the project.

Disadvantages:
• Higher Maintenance Effort: Explicitly listing all dependencies can create a significant administrative overhead, especially in larger projects.
• Risk of Omissions: Essential dependencies might accidentally be overlooked, leading to compile-time or runtime errors.

Example:


<PropertyGroup>
  <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>

Given the additional effort, is it really practical to explicitly declare all dependencies?

2.3 Comparison of Both Approaches

Criterion	PrivateAssets="all"	DisableTransitiveProjectReferences
Granularity	Package-specific control	Global deactivation – all dependencies must be explicitly referenced
Maintenance Effort	Requires individual adjustments per project	Higher maintenance effort due to separate management of all references
Clarity	Can lead to opaque dependency chains in complex structures	Clear separation, but increases the risk of overlooking essential packages
Flexibility	High flexibility in isolated control of individual packages	Strict control, but less adaptability

3. Practical Example: Abstraction and Interface Encapsulation

Consider a specific application: a .NET Standard library named Common encapsulates various helper methods and tools and internally includes a data access package that brings EF Core as a transitive dependency. In this case, it is advisable not to expose EF Core-specific classes in the public API; instead, these should be abstracted through interfaces.

Example Implementation:


// In Common
public interface IDataService
{
    IEnumerable<string> GetData();
}

internal class EfDataService : IDataService
{
    public IEnumerable<string> GetData()
    {
        // Internal use of EF Core
        return new List<string> { "Data from EF Core" };
    }
}

public static class DataServiceFactory
{
    public static IDataService CreateService()
    {
        return new EfDataService();
    }
}

Configuration in Common.csproj:


<ItemGroup>
  <PackageReference Include="SomeDataAccessPackage" Version="1.2.3" PrivateAssets="all" />
</ItemGroup>

This approach ensures that EF Core remains exclusively available internally—the main application only interacts with the interface without needing to know the underlying implementation.

4. Advanced Strategies and Alternative Approaches

In addition to the configuration options discussed above, other strategies can help minimize version conflicts and the issues of transitive dependencies:
• Binding Redirects:
Especially in older .NET Framework applications, binding redirects can help resolve conflicts between different versions of the same library.
• Modular Architectures:
Separating the application into clearly defined modules allows for targeted isolation of dependencies. This makes it easier to control unwanted side effects.

Should we not always question whether a focus solely on .csproj configurations in highly complex systems is truly the optimal solution?

5. Summary and Outlook

Transitive dependencies represent a serious issue in complex .NET projects. Seemingly insignificant libraries like EF Core can—when included via other NuGet packages—lead to significant version conflicts and runtime errors. Consistent separation of dependencies and the targeted use of measures such as PrivateAssets="all" or offer practical solutions. It is essential to weigh whether the administrative effort is justified by the benefits and how long-term maintainability can be ensured.

By using abstractions, explicit references, and additional measures such as binding redirects, developers can not only create a more stable codebase but also reduce ongoing maintenance efforts. Regularly reviewing dependency hierarchies using tools like dotnet list package --include-transitive or NDepend is indispensable.

Is it not ultimately the task of every developer to continually question whether the current architecture still meets the growing demands of modern applications?

I think so….!

Efficient Debugging and Precise Logging in C#: Using Caller Attributes

Ben Witt — Wed, 29 Jan 2025 17:01:53 +0000

How often do you wish, while debugging a complex application, to instantly see where in the code an error was triggered? Often, you are left with basic error messages that lack valuable context or exact code lines. This is where the C# attributes [CallerMemberName], [CallerFilePath], and [CallerLineNumber] come into play.

These attributes automatically provide information about the calling method’s name, the physical file path, and the line number in the source code when a method is called. This enables precise error tracking and logging, which is useful both during debugging and in production logging. Especially when troubleshooting large codebases, they prove to be indispensable tools for quick and targeted analysis.

Basics of the Attributes

The attributes [CallerMemberName], [CallerFilePath], and [CallerLineNumber] are applied directly to method parameters. The compiler automatically replaces the arguments with the corresponding values from the call context without any extra effort from the developer:
• [CallerMemberName] provides the name of the calling method.
• [CallerFilePath] gives the full path to the file where the method call is located.
• [CallerLineNumber] provides the line number of the call within that file.

The syntax is straightforward. A classic example:

public void LogInfo(
    string message, 
    [CallerMemberName] string memberName = "",
    [CallerFilePath] string filePath = "", 
    [CallerLineNumber] int lineNumber = 0)
{
    Console.WriteLine($"[{memberName}] {message} (File: {filePath}, Line: {lineNumber})");
}

Here, the parameters must have default values (e.g., = "" or = 0) so that the compiler can insert the values automatically. When you call the method without specifying these optional parameters, they are substituted automatically.

Example Method for Capturing Call Stack Information


public void ProcessData([CallerMemberName] string caller = "",
                        [CallerFilePath] string path = "",
                        [CallerLineNumber] int line = 0)
{
    Console.WriteLine($"Called by: {caller}, File: {path}, Line: {line}");
    // Further data processing code...
}

In this simple scenario, you can already gain initial insights into the call context and source code position. This meta-information is extremely valuable both for debugging and for later evaluations in operation.

Code Examples for Practical Applications

a) Simple Examples

Imagine you are running a library or an API to manage borrowing processes. Everywhere important actions take place—such as registering a book, registering new users, or handling requests—you want to create log entries. You could use a helper class for this:

public static class Logger
{
    public static void LogOperation(
        string operation, 
        [CallerMemberName] string memberName = "",
        [CallerFilePath] string filePath = "",
        [CallerLineNumber] int lineNumber = 0)
    {
        // For example, log to a file or a database
        Console.WriteLine($"Operation: {operation} in {memberName}, File: {filePath}, Line: {lineNumber}");
    }
}

Every time you call Logger.LogOperation("BookBorrowed"), the log provides much more information than if you had to add it manually.

b) More Complex Example with a Base Class

In larger projects, it is advisable to centralize logging and error handling routines in an abstract base class. The following example shows an abstract BaseRepository that catches errors and automatically uses the attributes for meaningful error messages:


public abstract class BaseRepository
{
    protected void LogError(Exception ex, 
                            [CallerMemberName] string memberName = "",
                            [CallerFilePath] string filePath = "", 
                            [CallerLineNumber] int lineNumber = 0)
    {
        Console.WriteLine($"Error in {memberName} at {filePath} (Line {lineNumber}): {ex.Message}");
    }
}

public class BookRepository : BaseRepository
{
    public void AddBook(Book book)
    {
        try
        {
            // Simulated database operation
            throw new InvalidOperationException("Database error while adding a book.");
        }
        catch (Exception ex)
        {
            LogError(ex);
            throw;  // Re-throw the error to continue the stack
        }
    }
}

public class LibraryService
{
    private readonly BookRepository _repository = new BookRepository();

    public void Execute()
    {
        try
        {
            _repository.AddBook(new Book { Title = "C# Deep Dive" });
        }
        catch (Exception ex)
        {
            Console.WriteLine("Error in the service layer: " + ex.Message);
            throw;
        }
    }
}

// Application
var service = new LibraryService();
service.Execute();

This approach allows complete tracking of the call stack. When an error is triggered in BookRepository, the LogError method precisely logs the context: the member name (AddBook), the file path, and the line number. At the same time, the error is re-thrown so that the higher layer (LibraryService) can perform further actions, such as separate logging or sending an alert.

c) Tracking a Complete Stack

In complex multi-layered architectures—consisting of service layers, repository layers, and database connections—it is crucial to trace the source of an error without gaps. The above example demonstrates this flow:
1. The service layer calls AddBook in BookRepository.
2. The repository layer throws an exception due to a database error, logs details using the caller attributes, and re-throws the error.
3. The service layer catches the error and can handle it accordingly.

With this technique, precise logging of each relevant layer is achieved, ensuring that no information about the actual origin is lost.

Practical Application with a Library Management System

In library software, where daily borrowings, reservations, returns, or new registrations are logged, the caller attributes are used optimally:
1. Logging API Errors: If an HTTP request fails, the log immediately provides information about the error location in the code (method, file, line).
2. Logging Database Operations: In dynamic environments, faulty SQL queries or transaction conflicts can quickly lead to confusing errors. Thanks to the caller attributes, it is possible to determine exactly where these conflicts were triggered, whether in the repository or service layer.

Such practical insights into the system not only shorten debugging times but also improve the overall maintainability of the application.

Limitations and Best Practices

Although logging file and line details is very helpful during development, it is important to consider potential drawbacks:
• Performance Considerations: With frequent log calls, excessive capturing of caller information can quickly bloat logs and impact application performance. Therefore, in production environments, it should be carefully considered where detailed logs are truly necessary.
• Security Aspects: Revealing file paths may be undesirable in some cases, such as in security-critical applications or externally shared logs.
• Reusability: To keep maintenance effort low, it is recommended to encapsulate the attributes in base classes or utility methods, as shown in the example (BaseRepository). This avoids redundant code and ensures consistent error messages across the entire project.

With a sensible logging concept and thoughtful filtering mechanisms, the level of detail can be flexibly controlled depending on the environment (development, staging, production).

Conclusion

The attributes [CallerMemberName], [CallerFilePath], and [CallerLineNumber] offer significant benefits for debugging, logging, and error tracing in C# projects. Their versatile applications—from simple logs in the development environment to complex error tracking in multi-layered architectures—make them essential tools in modern application development.

So why not start implementing more precise error logging and more efficient debugging in your own projects right away? The implementation is straightforward, while the benefits are enormous—especially when errors in production systems need to be quickly isolated and resolved. With targeted use, thoughtful structuring, and a bit of pragmatism, a new level of transparency in error analysis is achieved, significantly easing the developer’s daily work.

A Critical Look at Cancellation Management in .NET Applications

Ben Witt — Wed, 29 Jan 2025 17:01:36 +0000

The CancellationToken and the related types provided in .NET offer a central and effective foundation for carefully canceling tasks, threads, or asynchronous processes. However, the question arises whether this concept truly provides sufficient flexibility and stability in all application scenarios. But how often is this feature actually used in practice, and what risks come with improper handling? This article explains how the CancellationToken works and offers concrete recommendations for its efficient use. Additionally, potential pitfalls are highlighted and critically examined.

Definition and Purpose of CancellationToken

The CancellationToken is a structure from the Task Parallel Library (TPL) that is used to signal an ongoing operation that a cancellation request has been made. In a software architecture increasingly based on asynchronous and parallel processes, the CancellationToken plays a central role: it allows computationally intensive processes or long-running tasks to be terminated early, conserving resources and ensuring an improved user experience.

Why is this construct indispensable? In a modern .NET application, numerous operations can run in parallel or asynchronously. Without coordinated cancellation and resource release, there is a risk that certain tasks continue running and block system resources, even though they are no longer needed.

How It Works and Basic Concepts

Cancellation control is managed by the CancellationTokenSource class. It acts as the central control unit and provides methods such as Cancel(), which sends a cancellation signal to all linked CancellationTokens.

Resource Management with IDisposable

A frequently underestimated aspect is that CancellationTokenSource implements the IDisposable interface. If this is not taken into account, it can easily lead to resource leaks—especially in scenarios where a large number of CancellationTokenSource objects are created in parallel. Why should one neglect implementing clean resource management?

The recommendation is to always use the using keyword to enforce automatic resource release:

using (var cts = new CancellationTokenSource())
{
    // Code to execute the operation
}

Failing to call the Dispose() method can leave unmanaged resources in memory, ultimately affecting the application’s stability.

Methods to Cancel an Operation

There are several approaches to sending a cancellation request to an ongoing operation:
1. Synchronous Cancellation
The cancellation request is triggered immediately. This means the current method actively checks the CancellationToken and reacts right away.
2. Asynchronous Cancellation
The request is performed in the background without immediately blocking the calling code’s flow.
3. Delayed Cancellation
A predefined time span is used after which the operation is automatically terminated. This is especially helpful when a user does not want to wait further, such as in network or I/O-intensive tasks.

A concrete example of this is setting a timeout:

var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));

After this time span elapses, a cancellation request is triggered, ensuring that an operation does not run beyond the set limits. But is it always sensible to set a rigid timeout without being able to flexibly respond to external events?

Monitoring Cancellation Requests

Polling

A common practice is to regularly check the CancellationToken:

while (!token.IsCancellationRequested)
{
    // Continue the operation
}

When such loops are implemented in computationally intensive areas, the frequency of checks can significantly affect performance. The question arises: How often should the check be performed to recognize a cancellation promptly without excessively burdening execution time?

Alternatively, the ThrowIfCancellationRequested() method can be used, which throws an OperationCanceledException if a cancellation request has been made:

token.ThrowIfCancellationRequested();

This approach is usually cleaner but can also lead to unexpected side effects if the exception is not caught appropriately.

Callback Registration

In scenarios where regular polling is impractical or resource-intensive, a callback can be registered to execute automatically when a cancellation request arrives. For example, if a user is downloading a large file and cancels the process, not only should the download threads stop, but any temporary files created should also be deleted to free up space and avoid inconsistencies.

token.Register(() => 
{
    Console.WriteLine("Operation canceled.");
    // Additional cleanup, e.g., deleting temporary files
});

This method has the advantage of calling cancellation actions specifically without the ongoing operation having to constantly check for the cancellation signal. However, callback registration can lead to messy code flow in complex scenarios when multiple cancellation cases and cleanup actions need to be considered.

Linking Multiple CancellationTokens

What happens when an application needs to meet several potential cancellation conditions at the same time? For example, an operation might need to respond to both a user event (like closing a window) and a timeout simultaneously. The CancellationTokenSource class provides the CreateLinkedTokenSource method for this purpose:

var linkedTokenSource = CancellationTokenSource.CreateLinkedTokenSource(token1, token2);

The created instance combines multiple CancellationTokens into a new token. Once any of the involved tokens is canceled, the combined token is also triggered. This simplifies the implementation of complex cancellation logic and improves readability. However, caution is necessary: incorrect linking can cause operations to be canceled too early or not at all if the relationships between tokens are not clearly defined.

Best Practices for Handling CancellationToken

To ensure smooth cancellation management, the following points should be considered:
1. Respect the Passed Token
Avoid ignoring the CancellationToken. In every relevant method, actively check it or use an appropriate mechanism (e.g., callback).
2. Properly Release Resources
Always call the Dispose() method on CancellationTokenSource, preferably using the using block to prevent memory leaks.
3. Avoid Unnecessary Sources
Only create a new CancellationTokenSource if passing an existing CancellationToken is insufficient. Otherwise, you risk an unclear codebase and unnecessary resource consumption.
4. Proper Error Handling
Catch the OperationCanceledException and handle it meaningfully. Silently swallowing the exception can lead to hard-to-trace error patterns, as cancellation operations behave “invisibly.”

Additional Aspects and Critical Consideration

Use Cases for Timeouts

While the use of a timeout has already been mentioned, in a highly connected world, variable external factors such as fluctuating network bandwidths or different devices can quickly render a rigid timeout obsolete. Wouldn’t it make sense to take a closer look at adaptive timeout management?

Consider scenarios where the system responds to environmental parameters and dynamically adjusts timeouts. For example, a microservice that reduces wait times for certain requests under high load or grants more generous timeouts with a good connection could significantly enhance user satisfaction. Load balancers and reverse proxies also play an important role here, as they can capture both the context and the load of the respective services.

In short, a purely time-based approach without context can lead to misjudgments and, at worst, prematurely cancel important operations. In the age of cloud computing and highly variable environments, it’s worthwhile to consider context-dependent timeout management with circuit breakers or retry mechanisms.

Depth of Example Implementations

Although the article uses concise code snippets (such as the using statement), a more in-depth presentation of more complex application examples would be helpful. Especially in microservice architectures or when accessing databases, the layered cancellation logic often becomes apparent in practice.

A realistic example could cover the following aspects:
• Multiple CancellationTokens originating from different sources (e.g., user inputs, timeouts, overload signals).
• A database-heavy operation accessing an external resource that, upon interruption, must not only reset local but also database transactions.
• Logical separation of cancellation handling at the service level and repository level to ensure a clear separation of concerns and minimize side effects.

Such comprehensive implementations would allow developers to recognize and avoid common pitfalls—such as forgetting to call Dispose() or improperly catching OperationCanceledException—in a realistic context.

More Comprehensive Error Handling

The article already emphasizes the importance of catching OperationCanceledException. But how specifically should the error situation be handled in complex systems where multiple components respond to the same token?

A possible scenario could look like this: A user-initiated cancellation request is recognized, but a downstream sub-component does not respond in time or blocks while requesting resources. Partial failures occur, which might only appear late in the logs and are difficult to attribute to a specific cause. In such cases, structured exception handling is needed, considering the following points:
• Targeted Logging: Every cancellation request should appear in the logs, ideally with context information (e.g., which sub-component responded, which actions were interrupted).
• Separation of Regular Exceptions and Cancellation Cases: An OperationCanceledException does not indicate a classic error state but a deliberate cancellation. However, the interplay of multiple CancellationTokens can create unforeseen side effects, making a consistent and well-documented error strategy essential.
• Fallback Mechanisms: In safety-critical or highly available environments, a cancellation should not lead to an unstable overall system but support orderly fallback procedures (e.g., graceful shutdown).

Especially in distributed architectures where multiple services and applications interact, a well-documented error handling and logging process is indispensable to make cancellation processes both traceable and controlled.

Conclusion

The CancellationToken is a central component in the development of modern, reactive, and resource-efficient .NET applications. However, its correct use requires a certain level of attention: underestimating the importance of clean resource management or ignoring cancellation signals in the code can lead to errors and performance problems almost by default.

Is it really acceptable to forgo this central cancellation mechanism or implement it only half-heartedly? Those who value scalability and user satisfaction will clearly answer no. Consistently following the described best practices leads to robust and controlled cancellation management, enhances application performance, and improves the user experience equally. At the same time, a critical look at advanced concepts such as adaptive timeout management, comprehensive implementation examples, and structured error handling is recommended to make the use of CancellationToken even more effective and secure.

Asynchronous HTTP Requests – Explained Simply

Ben Witt — Wed, 29 Jan 2025 17:01:17 +0000

Imagine a waiter taking your order and waiting in the kitchen until your food is ready. During this time, the waiter cannot serve other guests. This is how a synchronous HTTP request works – it blocks the process.

An asynchronous HTTP request, on the other hand, allows the waiter to serve other guests while your food is being prepared. Once your dish is ready, the waiter brings it to you without others being delayed. Sounds efficient, right?

Why Are Asynchronous Requests So Important?

In daily life, we encounter asynchronous HTTP requests all the time, for example:
• WhatsApp: Messages are loaded while you’re using other functions.
• Instagram: Images and videos are loaded in the background.
• Netflix: The next episode is preloaded while you’re still watching.
• Online Shopping: Products are filtered and sorted in the background.

What Does Idempotence Mean in This Context?

Idempotence is an essential concept in web development, particularly for HTTP requests. It describes the property of an operation that delivers the same result no matter how many times it is performed. This principle plays an important role in the reliability and repeatability of requests – especially with asynchronous HTTP requests, as they might be sent multiple times due to network failures or timeouts.

Examples of idempotent HTTP methods:
• GET: Repeatedly fetching the same resource always returns the same data (unless the resource changes).
• PUT: Overwriting a resource with the same data does not change the final state.
• DELETE: Deleting a resource has no effect if the resource has already been removed.

In contrast, POST is not idempotent because it often creates new resources or changes states, which can lead to inconsistent behavior when executed multiple times.

A Simple Introduction in C#

Here is an example of fetching weather data in C#, which also considers idempotence:

public class WetterService
{
    private readonly HttpClient _httpClient;

    public WetterService()
    {
        _httpClient = new HttpClient();
        _httpClient.BaseAddress = new Uri("https://api.wetter.de/");
    }

    public async Task<WetterDaten> HoleWetterAsync(string stadt)
    {
        try
        {
            var antwort = await _httpClient.GetAsync($"wetter/{stadt}");

            if (!antwort.IsSuccessStatusCode)
            {
                return new WetterDaten { Fehler = "Ups! Da ist etwas schiefgelaufen." };
            }

            var json = await antwort.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<WetterDaten>(json);
        }
        catch (Exception)
        {
            return new WetterDaten { Fehler = "Sorry, wir konnten das Wetter nicht abrufen." };
        }
    }
}

Note: The use of the HTTP-GET method ensures idempotence. Even with multiple requests, the server’s state remains unchanged.

Practical Example: Online Shop

A typical controller processing asynchronous and idempotent requests:

[ApiController]
[Route("api/produkte")]
public class ProduktController : ControllerBase
{
    private readonly IProduktService _produktService;

    public ProduktController(IProduktService produktService)
    {
        _produktService = produktService;
    }

    [HttpGet]
    public async Task<ActionResult<List<Produkt>>> HoleAlleProdukte()
    {
        var produkte = await _produktService.HoleAlleProdukteAsync();
        return Ok(produkte);
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<Produkt>> HoleProdukt(int id)
    {
        var produkt = await _produktService.HoleProduktAsync(id);

        if (produkt == null)
        {
            return NotFound("Produkt nicht gefunden");
        }

        return Ok(produkt);
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> LoescheProdukt(int id)
    {
        var erfolgreich = await _produktService.LoescheProduktAsync(id);

        if (!erfolgreich)
        {
            return NotFound("Produkt nicht gefunden oder bereits gelöscht.");
        }

        return NoContent();
    }
}

Idempotence in detail: Both GET and DELETE are idempotent here. Even with multiple executions, the results remain consistent, enhancing the system’s stability.

Benefits of Asynchronous and Idempotent HTTP Requests
1. Better User Experience: The app remains responsive and does not freeze.
2. More Efficient Resource Utilization: The server can handle other tasks during wait times.
3. Increased Reliability: Repeated requests do not lead to inconsistent behavior thanks to idempotence.
4. Scalability: Asynchronous processing reduces bottlenecks, especially with parallel requests.

Advanced Use Case: Parallel Loading

Sometimes it is necessary to load multiple resources simultaneously:

public class DashboardService
{
    private readonly IBenutzerService _benutzerService;
    private readonly IBestellungService _bestellungService;

    public async Task<DashboardDaten> HoleDashboardDatenAsync()
    {
        var benutzerTask = _benutzerService.HoleStatistikenAsync();
        var bestellungenTask = _bestellungService.HoleStatistikenAsync();

        await Task.WhenAll(benutzerTask, bestellungenTask);

        return new DashboardDaten
        {
            BenutzerStats = await benutzerTask,
            BestellungStats = await bestellungenTask
        };
    }
}

Common Pitfalls and Solutions
1. Forgotten await: Without await, the code remains blocking and loses its asynchronous behavior.
2. Neglecting Error Handling: Network issues are common, so plan for appropriate error handling.
3. Not Setting Timeouts: Avoid endless wait times by implementing timeout rules.
4. Ignoring Idempotence: Non-idempotent requests can lead to hard-to-trace errors.
5. Lack of Tests: Asynchronous code is prone to subtle bugs and should be thoroughly tested.

Conclusion

Asynchronous HTTP requests are the foundation of modern, responsive applications. By adhering to idempotence principles, repeated requests do not produce unexpected results. Together, they not only enhance the user experience but also create robust and scalable systems. However, their proper implementation requires careful planning and execution.

DEV Community: Ben Witt

Durable Workflows Are Great, and the Wrong Choice for Short Pipelines

Keep Two Concepts Separate

What Durable Workflows Are Built For

What a Short Pipeline Is

The Costs You Add

The Actual Question

What I Would Use Instead

When I Would Use Durable Workflows

Conclusion

RabbitMQ Dead Letter Queues in .NET: Why We Chose This Approach and Where It Hit Us

The Problem

How Dead Lettering Works

Prefer Policies Over Hardcoded Queue Arguments

Setup in CSharp

Where It Hit Us: PRECONDITION_FAILED 406

The Fix

Option 1: Use policies

Option 2: Make queue arguments explicit configuration

Queue Arguments Are Not a Migration Mechanism

DLX Does Not Replace Retries

DLX Does Not Replace Message Durability

Operating a DLQ

What We Learned

Conclusion

MCP Design Patterns: 6 Architectures for Your AI Tools

What Is an MCP Server?

Pattern 1: Direct API Wrapper

Pattern 2: Composite Service

Pattern 3: Resource-Oriented MCP

Pattern 4: Agent-Backed Tool

Pattern 5: Event-Driven Control Surface

Pattern 6: Gateway or Federated MCP

A Note on Local Access

The Decision Logic

Security Questions Every Pattern Needs

Conclusion

References

Local AI Pipeline: Why Certain Workloads Never Leave the Machine

The Three Reasons, in the Right Order

What This Looks Like in Practice

The Honest Part: What It Costs

The Actual Decision

Conclusion

A Generic Table API with Dapper in 80 Lines of C#

The Goal

Setup

The Important Boundary: Known Tables Only

The Endpoint

Helper Functions

Normalize the connection string

Bound pagination

Quote identifiers

Validate $orderby

Convert snake_case keys to camelCase

Parse JSON strings carefully

Security: What This Protects

The Result

When This Makes Sense

Conclusion

References

Semantic Search with PostgreSQL: Pragmatism Beats Hype - Most of the Time

Semantic Search in One Sentence

The Most Important Design Decision: The Embedding Model

Installing pgvector

Schema: Store Chunks, Not Just Documents

Integration in .NET with Npgsql

Generating Embeddings with OpenAI

Storing a Document Chunk

Semantic Search

Distance Operators

Creating an Index with HNSW

IVFFlat as an Alternative

Filtering and Hybrid Search

When pgvector Is the Right Choice

When a Dedicated Vector Store May Be Better

Complete ASP.NET Core Example

Conclusion

References

Stop Loading Your Entire Instruction System Into Every Session

Validate `$orderby`

Convert `snake_case` keys to `camelCase`

2.1 `PrivateAssets="all"`