DEV Community: Juan Gómez

Crea un servidor MCP en C#: escribe tus herramientas una vez y úsalas en cualquier Claude

Juan Gómez — Fri, 31 Jul 2026 19:58:43 +0000

Crea un servidor MCP en C#: escribe tus herramientas una vez y úsalas en cualquier Claude

La última vez construimos un agente de tool use con Claude en C#. Funcionaba — pero cada herramienta vivía dentro de esa única app de consola. Si querías la misma capacidad de "consultar un pedido" dentro de Claude Desktop, o de Claude Code, o del agente de un compañero, tocaba copiar y pegar la herramienta y toda su fontanería en cada sitio. Herramientas atrapadas en un solo proceso, reimplementadas por todas partes. Ese es justo el acoplamiento que MCP viene a romper.

El Model Context Protocol le da la vuelta a quién es dueño de la herramienta. La escribes una vez, como un servidor independiente, y la expones sobre un protocolo estándar. Entonces cualquier cliente MCP — Claude Desktop, Claude Code, tu propio agente, lo que salga el próximo trimestre — se conecta y obtiene tus herramientas gratis. En este post cogemos las mismas herramientas de Aurora Coffee Co. de la última vez y las liberamos como un servidor MCP real en .NET, para luego enchufarlo a Claude.

Qué es MCP en realidad

MCP es un pequeño protocolo cliente/servidor (JSON-RPC por debajo) para conectar clientes de IA con tus capacidades. Con tres ideas ya puedes arrancar:

Cliente y servidor son procesos separados. El cliente es la app de IA (Claude Desktop, Claude Code). El servidor es tu código. Se hablan por un transporte, no por una tabla de funciones compartida.
Los servidores exponen tres cosas: tools (acciones que el modelo puede invocar — nuestro foco), resources (datos legibles, como ficheros o filas) y prompts (plantillas de prompt reutilizables). Hoy todo son tools.
Dos transportes. stdio — el cliente lanza tu servidor como proceso hijo y hablan por la entrada/salida estándar; ideal para herramientas locales. HTTP — tu servidor corre en algún sitio y los clientes se conectan por red; para herramientas compartidas o remotas.

Si leíste el artículo anterior, este es el mismo bucle de tool use — declaras una herramienta, el modelo la invoca, tu código la ejecuta, devuelves un resultado — pero ahora la herramienta vive al otro lado de una frontera de proceso, reutilizable por cualquier cliente en lugar de cableada dentro de una sola app.

El servidor que vamos a construir

¿Te acuerdas de Aurora Coffee Co.? Sus dos herramientas respondían preguntas de soporte sobre unos datos en memoria:

get_order_status(order_id) — consulta un pedido.
check_stock(sku) — comprueba el inventario de un producto.

La última vez esas herramientas eran métodos enterrados en un bucle de agente. Ahora se convierten en un servidor MCP que cualquier Claude puede invocar. Arranca una app de consola y añade dos paquetes:

dotnet new console -o AuroraCoffee.Mcp
cd AuroraCoffee.Mcp
dotnet add package ModelContextProtocol
dotnet add package Microsoft.Extensions.Hosting

ModelContextProtocol es el SDK oficial de C# (1.0.0, mantenido en colaboración con Microsoft). Microsoft.Extensions.Hosting nos da el host genérico — la misma historia de DI y configuración que usarías en cualquier servicio .NET.

Los datos, como servicio inyectable

Guardamos la "base de datos" de Aurora en un singleton para que las herramientas la reciban por inyección en el constructor — igual que un repositorio de verdad:

public sealed class CoffeeShopData
{
    public Dictionary<string, Order> Orders { get; } = new()
    {
        ["A-1001"] = new("A-1001", "shipped", "2026-08-03"),
        ["A-1002"] = new("A-1002", "processing", "2026-08-06"),
    };

    public Dictionary<string, int> Stock { get; } = new()
    {
        ["ETH-250"] = 42,
        ["COL-1KG"] = 0,
    };
}

public sealed record Order(string Id, string Status, string Eta);

Las herramientas

Esta es la parte que sustituye al JSON Schema escrito a mano y al switch de la última vez. Una clase marcada con [McpServerToolType], métodos marcados con [McpServerTool], y [Description] tanto en el método como en sus parámetros. El SDK lee la firma de tu método y te genera el JSON Schema:

using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class CoffeeTools(CoffeeShopData data)
{
    [McpServerTool, Description("Consulta el estado y la fecha estimada de entrega de un pedido por su id.")]
    public string GetOrderStatus(
        [Description("Id del pedido, p. ej. A-1001")] string orderId) =>
        data.Orders.TryGetValue(orderId, out var order)
            ? $"Pedido {order.Id}: {order.Status}, ETA {order.Eta}."
            : "No hay ningún pedido con ese id.";

    [McpServerTool, Description("Comprueba cuántas unidades de un SKU de producto hay en stock ahora mismo.")]
    public string CheckStock(
        [Description("SKU del producto, p. ej. ETH-250")] string sku) =>
        data.Stock.TryGetValue(sku, out var quantity)
            ? $"SKU {sku}: {quantity} unidades en stock."
            : "SKU desconocido.";
}

Esos atributos [Description] no son adorno — son los mismos docstrings con peso del artículo anterior, solo que escritos en un sitio más bonito. El del método le dice a Claude cuándo llamar a la herramienta; los de los parámetros, qué pasarle. Descripciones vagas aquí son la razón número uno de que un modelo ignore una herramienta perfectamente buena.

Fíjate en lo que desapareció: ni objeto input_schema, ni array required, ni parseo manual de argumentos. orderId es un parámetro string tipado, así que el SDK sabe que es un string obligatorio y te entrega el valor ya parseado. La fontanería del Enfoque 1 de la última vez ahora es trabajo del framework.

Uniéndolo todo

El host builder registra los datos, el servidor MCP, el transporte stdio y descubre automáticamente todos los [McpServerToolType] del ensamblado:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder(args);

// stdout es el canal del protocolo — los logs DEBEN ir a stderr o corromperás el stream.
builder.Logging.AddConsole(options =>
    options.LogToStandardErrorThreshold = LogLevel.Trace);

builder.Services.AddSingleton<CoffeeShopData>();
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();

await builder.Build().RunAsync();

Ese es el servidor entero. Lee otra vez la línea del logging, porque ahí está la trampa más común del MCP por stdio: stdout transporta los mensajes JSON-RPC. Un solo Console.WriteLine despistado a stdout y Claude ve ruido donde esperaba JSON — el equivalente en protocolo a hablar con la boca llena. Manda todos los logs a stderr y no habrá problema.

Enchufándolo a Claude

Un servidor al que nadie se conecta no es más que una app de consola muy solitaria. Vamos a conectarlo a dos clientes.

Claude Desktop lee un fichero de configuración JSON (claude_desktop_config.json, en %APPDATA%\Claude\ en Windows o ~/Library/Application Support/Claude/ en macOS). Añade tu servidor bajo mcpServers:

{
  "mcpServers": {
    "aurora-coffee": {
      "command": "dotnet",
      "args": ["run", "--project", "C:/src/AuroraCoffee.Mcp"]
    }
  }
}

El cliente ejecuta ese comando, habla stdio con el proceso hijo y tus herramientas aparecen. Reinicia Claude Desktop y pregunta "¿El pedido A-1001 está enviado, y todavía te quedan ETH-250 en stock?" — llamará a ambas herramientas y responderá de verdad.

Claude Code es aún más corto — un comando de CLI, sin editar ficheros:

claude mcp add aurora-coffee -- dotnet run --project ./AuroraCoffee.Mcp

Mismo servidor, segundo cliente, cero cambios de código. Ese es justo el sentido de MCP: las herramientas no se movieron, pero ahora dos Claude distintos pueden alcanzarlas — y también el tercero que aún no has instalado.

Pruébalo sin cliente

Antes de tocar la config de ningún cliente, verifica el servidor con el MCP Inspector, una UI de navegador que habla el protocolo para que listes e invoques herramientas a mano:

npx @modelcontextprotocol/inspector dotnet run --project ./AuroraCoffee.Mcp

Lanza tu servidor, lista get_order_status y check_stock, y te deja disparar llamadas de prueba. Si una herramienta se porta mal, te enteras aquí — no tres capas dentro de un transcript de chat.

Llegando al mundo exterior: DI y HttpClient

Los diccionarios en memoria valen para una demo, pero las herramientas de verdad llaman a sistemas de verdad. Como el servidor es un host .NET normal, la inyección de dependencias funciona tal cual esperas — incluidos los HttpClient tipados. Considera que Aurora tiene una API de tostadero para notas de cata:

using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class RoastTools(HttpClient http)
{
    [McpServerTool, Description("Obtiene las notas de tueste de hoy para un origen de café.")]
    public async Task<string> GetRoastNotes(
        [Description("Nombre del origen, p. ej. Ethiopia")] string origin) =>
        await http.GetStringAsync(
            $"https://api.auroracoffee.example/roast-notes/{Uri.EscapeDataString(origin)}");
}

Regístralo como cliente tipado y listo — el SDK inyecta el HttpClient en el constructor de la herramienta:

builder.Services.AddHttpClient<RoastTools>();

Dos cosas a subrayar. Primera, las herramientas pueden ser async y devolver Task<string> — sin ceremonia, solo await. Segunda, usa AddHttpClient<T> (o IHttpClientFactory) en vez de instanciar un HttpClient por llamada; la factory reutiliza conexiones para que no agotes sockets bajo carga. Aplica la higiene de siempre en .NET — MCP no cambia nada de eso.

Pasando al modo remoto: el transporte HTTP

stdio es genial cuando el cliente puede lanzar tu servidor en local. Pero si quieres un servidor compartido por un equipo, o corriendo en un contenedor, quieres HTTP. Cambia el paquete de transporte y dos líneas:

dotnet add package ModelContextProtocol.AspNetCore

using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<CoffeeShopData>();
builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();

var app = builder.Build();
app.MapMcp();
app.Run();

Los mismos CoffeeTools, los mismos atributos, el mismo descubrimiento — solo cambiaron el transporte y el host. Ahora los clientes se conectan por URL en vez de lanzar un proceso, y obtienes todo lo que ASP.NET Core ya te da: middleware de auth, HTTPS, hosting, escalado. Tus herramientas ni se enteraron.

Cuándo construir un servidor MCP — y cuándo no

Tira de MCP cuando las herramientas necesiten ser compartidas o reutilizadas: la misma capacidad en Claude Desktop y en Claude Code, un servidor al que apunte todo tu equipo, o herramientas que quieras desacopladas de cualquier app y libres de evolucionar a su propio ritmo de releases. La frontera de proceso es una ventaja — es lo que permite que un servidor sirva a muchos clientes, en cualquier lenguaje.

Sáltatelo cuando exactamente una app vaya a usar las herramientas y sea esa app la que hace las llamadas al modelo. Entonces el bucle de tool use dentro de la app del artículo anterior es más simple y rápido — sin transporte, sin segundo proceso. Un servidor cuyo único cliente es él mismo no es más que una llamada a función disfrazada de protocolo.

Regla general: tool use dentro de la app cuando una app es dueña del modelo y de las herramientas; un servidor MCP en el momento en que más de un cliente necesita las mismas herramientas.

Puntos Clave

MCP desacopla las herramientas de los clientes — escribe una herramienta una vez como servidor y cualquier cliente MCP (Claude Desktop, Claude Code, tu propio agente) puede usarla, en vez de reimplementarla en cada app.
El SDK va por atributos — [McpServerToolType] en la clase, [McpServerTool] en el método, y el JSON Schema se genera a partir de tu firma. Sin schema a mano, sin parseo manual de argumentos.
Las descripciones siguen teniendo peso — [Description] en el método y en cada parámetro es como Claude decide cuándo llamar a una herramienta y qué pasarle. Escríbelas como docstrings.
Cuida stdout — en modo stdio el protocolo es stdout. Manda los logs a stderr o corromperás el stream con tu propia salida de debug.
Mismas herramientas, cambia el transporte — stdio para herramientas locales por proceso hijo, HTTP (ModelContextProtocol.AspNetCore) para compartidas o remotas. El código de la herramienta no cambia.

Build an MCP Server in C#: Write Your Tools Once, Use Them in Every Claude

Juan Gómez — Fri, 31 Jul 2026 19:58:32 +0000

Build an MCP Server in C#: Write Your Tools Once, Use Them in Every Claude

Last time we built a Claude tool-use agent in C#. It worked — but every tool lived inside that one console app. If you wanted the same "look up an order" ability inside Claude Desktop, or Claude Code, or a teammate's agent, you'd copy-paste the tool and its plumbing into each one. Tools trapped in a single process, re-implemented everywhere. That's the coupling MCP exists to break.

The Model Context Protocol flips the ownership around. You write a tool once, as a standalone server, and expose it over a standard protocol. Then any MCP client — Claude Desktop, Claude Code, your own agent, whatever ships next quarter — connects and gets your tools for free. In this post we'll take the exact same Aurora Coffee Co. tools from last time and set them loose as a real MCP server in .NET, then plug it into Claude.

What MCP actually is

MCP is a small client/server protocol (JSON-RPC under the hood) for connecting AI clients to your capabilities. Three ideas are all you need to start:

Client and server are separate processes. The client is the AI app (Claude Desktop, Claude Code). The server is your code. They talk over a transport, not a shared function table.
Servers expose three things: tools (actions the model can call — our focus), resources (readable data, like files or rows), and prompts (reusable prompt templates). Today it's all tools.
Two transports. stdio — the client launches your server as a child process and talks over standard in/out; perfect for local tools. HTTP — your server runs somewhere and clients connect over the network; for shared or remote tools.

If you read the previous article, this is the same tool-use loop — declare a tool, the model calls it, your code runs it, you return a result — but the tool now lives on the other side of a process boundary, reusable by any client instead of hardwired into one app.

The server we're building

Remember Aurora Coffee Co.? Its two tools answered support questions over some in-memory data:

get_order_status(order_id) — looks up an order.
check_stock(sku) — checks inventory for a product.

Last time those tools were methods buried in an agent loop. Now they become an MCP server that any Claude can call. Start a console app and add two packages:

dotnet new console -o AuroraCoffee.Mcp
cd AuroraCoffee.Mcp
dotnet add package ModelContextProtocol
dotnet add package Microsoft.Extensions.Hosting

ModelContextProtocol is the official C# SDK (1.0.0, maintained with Microsoft). Microsoft.Extensions.Hosting gives us the generic host — the same DI and configuration story you'd use in any .NET service.

The data, as an injectable service

We'll hold Aurora's "database" in a singleton so tools can take it via constructor injection — exactly like a real repository:

public sealed class CoffeeShopData
{
    public Dictionary<string, Order> Orders { get; } = new()
    {
        ["A-1001"] = new("A-1001", "shipped", "2026-08-03"),
        ["A-1002"] = new("A-1002", "processing", "2026-08-06"),
    };

    public Dictionary<string, int> Stock { get; } = new()
    {
        ["ETH-250"] = 42,
        ["COL-1KG"] = 0,
    };
}

public sealed record Order(string Id, string Status, string Eta);

The tools

Here's the part that replaces last time's hand-written JSON Schema and switch statement. A class marked [McpServerToolType], methods marked [McpServerTool], and [Description] on both the method and its parameters. The SDK reads your method signature and generates the JSON Schema for you:

using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class CoffeeTools(CoffeeShopData data)
{
    [McpServerTool, Description("Look up the status and ETA of a customer order by its id.")]
    public string GetOrderStatus(
        [Description("Order id, e.g. A-1001")] string orderId) =>
        data.Orders.TryGetValue(orderId, out var order)
            ? $"Order {order.Id}: {order.Status}, ETA {order.Eta}."
            : "No order found with that id.";

    [McpServerTool, Description("Check how many units of a product SKU are currently in stock.")]
    public string CheckStock(
        [Description("Product SKU, e.g. ETH-250")] string sku) =>
        data.Stock.TryGetValue(sku, out var quantity)
            ? $"SKU {sku}: {quantity} units in stock."
            : "Unknown SKU.";
}

Those [Description] attributes are not decoration — they're the same load-bearing docstrings from the last article, just written in a nicer place. The method one tells Claude when to call the tool; the parameter ones tell it what to pass. Vague descriptions here are the number-one reason a model ignores a perfectly good tool.

Notice what's gone: no input_schema object, no required array, no manual argument parsing. orderId is a typed string parameter, so the SDK knows it's a required string and hands you the parsed value. The plumbing from Approach 1 last time is now the framework's job.

Wiring it together

The host builder registers the data, the MCP server, the stdio transport, and auto-discovers every [McpServerToolType] in the assembly:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder(args);

// stdout is the protocol channel — logs MUST go to stderr or you corrupt the stream.
builder.Logging.AddConsole(options =>
    options.LogToStandardErrorThreshold = LogLevel.Trace);

builder.Services.AddSingleton<CoffeeShopData>();
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();

await builder.Build().RunAsync();

That's the whole server. Read that logging line again, because it's the single biggest footgun in stdio MCP: stdout carries the JSON-RPC messages. One stray Console.WriteLine to stdout and Claude sees line noise where it expected JSON — the protocol equivalent of talking with your mouth full. Route every log to stderr and you're fine.

Plugging it into Claude

A server nobody connects to is just a very lonely console app. Let's wire it into two clients.

Claude Desktop reads a JSON config file (claude_desktop_config.json, in %APPDATA%\Claude\ on Windows or ~/Library/Application Support/Claude/ on macOS). Add your server under mcpServers:

{
  "mcpServers": {
    "aurora-coffee": {
      "command": "dotnet",
      "args": ["run", "--project", "C:/src/AuroraCoffee.Mcp"]
    }
  }
}

The client runs that command, speaks stdio to the child process, and your tools show up. Restart Claude Desktop and ask "Is order A-1001 shipped, and do you still have ETH-250 in stock?" — it'll call both tools and answer for real.

Claude Code is even shorter — one CLI command, no file editing:

claude mcp add aurora-coffee -- dotnet run --project ./AuroraCoffee.Mcp

Same server, second client, zero code changes. That's the entire point of MCP: the tools didn't move, but now two different Claudes can reach them — and so can the third one you haven't installed yet.

Test it without a client

Before you touch any client config, sanity-check the server with the MCP Inspector, a browser UI that speaks the protocol so you can list and invoke tools by hand:

npx @modelcontextprotocol/inspector dotnet run --project ./AuroraCoffee.Mcp

It launches your server, lists get_order_status and check_stock, and lets you fire test calls. If a tool misbehaves, you find out here — not three layers deep inside a chat transcript.

Reaching the outside world: DI and HttpClient

In-memory dictionaries are fine for a demo, but real tools call real systems. Because the server is a normal .NET host, dependency injection works exactly as you'd expect — including typed HttpClients. Suppose Aurora has a roastery API for tasting notes:

using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class RoastTools(HttpClient http)
{
    [McpServerTool, Description("Fetch today's roast notes for a coffee origin.")]
    public async Task<string> GetRoastNotes(
        [Description("Origin name, e.g. Ethiopia")] string origin) =>
        await http.GetStringAsync(
            $"https://api.auroracoffee.example/roast-notes/{Uri.EscapeDataString(origin)}");
}

builder.Services.AddHttpClient<RoastTools>();

Two things worth calling out. First, tools can be async and return Task<string> — no ceremony, just await. Second, use AddHttpClient<T> (or IHttpClientFactory) rather than newing up an HttpClient per call; the factory pools connections so you don't exhaust sockets under load. Standard .NET hygiene applies — MCP doesn't change any of it.

Going remote: the HTTP transport

stdio is great when the client can launch your server locally. But if you want one server shared across a team, or running in a container, you want HTTP. Swap the transport package and two lines:

dotnet add package ModelContextProtocol.AspNetCore

using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<CoffeeShopData>();
builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();

var app = builder.Build();
app.MapMcp();
app.Run();

Same CoffeeTools, same attributes, same discovery — only the transport and host changed. Now clients connect by URL instead of launching a process, and you get everything ASP.NET Core already gives you: auth middleware, HTTPS, hosting, scaling. Your tools didn't even notice.

When to build an MCP server — and when not to

Reach for MCP when tools need to be shared or reused: the same capability across Claude Desktop and Claude Code, a server your whole team points at, or tools you want decoupled from any single app and free to evolve on their own release cadence. The process boundary is a feature — it's what lets one server serve many clients, in any language.

Skip it when exactly one app will ever use the tools and it's the app doing the model calls. Then the in-app tool-use loop from the previous article is simpler and faster — no transport, no second process. A server whose only client is itself is just a function call wearing a lanyard.

Rule of thumb: in-app tool use when one app owns the model and the tools; an MCP server the moment more than one client needs the same tools.

Key Takeaways

MCP decouples tools from clients — write a tool once as a server and every MCP client (Claude Desktop, Claude Code, your own agent) can use it, instead of re-implementing it in each app.
The SDK is attribute-driven — [McpServerToolType] on the class, [McpServerTool] on the method, and the JSON Schema is generated from your signature. No hand-written schema, no manual argument parsing.
Descriptions are still load-bearing — [Description] on the method and each parameter is how Claude decides when to call a tool and what to pass. Write them like docstrings.
Guard stdout — in stdio mode the protocol is stdout. Send logs to stderr or you'll corrupt the stream with your own debug output.
Same tools, swap the transport — stdio for local child-process tools, HTTP (ModelContextProtocol.AspNetCore) for shared or remote ones. The tool code doesn't change.

Build a Claude Tool-Use Agent in C#: Not a Chatbot on Steroids

Juan Gómez — Fri, 24 Jul 2026 20:09:23 +0000

Build a Claude Tool-Use Agent in C#: Not a Chatbot on Steroids

Everyone ships "AI agents" now. Peek under the hood of most of them and you'll find a chatbot with a personality prompt and a hopeful // TODO: make it do things. It can talk about your orders. It cannot actually look one up.

A real agent closes that gap. You hand the model a set of tools — plain methods in your codebase — and it decides, mid-conversation, to call one. Your code runs the real work, hands back the result, and the model keeps going until it can answer for real. That loop is the whole trick, and you can build it in C# in about sixty lines. We'll do it twice: once by hand with HttpClient so you can see the wire protocol, and once with the official Anthropic .NET SDK for the short version you'd actually ship.

What "tool use" actually is

Tool use (a.k.a. function calling) is a small, strict loop:

You declare tools. Each is a name, a description, and a JSON Schema for its inputs. That's it — no code is sent to Claude, just the shape.
Claude replies with a tool_use block instead of text. It's saying "please run check_stock with { "sku": "ETH-250" } and tell me what you get."
Your code runs it. This is the part people miss: Claude never executes anything. It requests; your harness executes. The security boundary stays on your side of the fence.
You send the answer back as a tool_result block, tied to the request by id.
Claude continues — maybe calling more tools, maybe answering. You loop until it stops asking.

Think of Claude as a very fast senior colleague who can read your API but isn't allowed to touch production: it tells you exactly which button to press, you press it, you report back. The judgment is the model's; the hands are yours.

The agent we're building

Meet Aurora Coffee Co., a fictional shop with a support agent that answers questions like "Is my order shipped, and do you still have the Ethiopia beans?" It has two tools over some in-memory data, so the whole thing runs with zero external setup:

get_order_status(order_id) — looks up an order.
check_stock(sku) — checks inventory for a product.

Here's the shared part — the data and the tool executor. Both approaches below reuse this exact method; only the Claude plumbing changes.

using System.Text.Json;

// Aurora Coffee Co.'s "database" — in memory, so this runs with zero setup.
var orders = new Dictionary<string, Order>
{
    ["A-1001"] = new("A-1001", "shipped", "2026-07-26"),
    ["A-1002"] = new("A-1002", "processing", "2026-07-29"),
};
var stock = new Dictionary<string, int> { ["ETH-250"] = 42, ["COL-1KG"] = 0 };

// Your tools are ordinary C#. Claude never runs this — it only asks you to.
string RunTool(string name, IReadOnlyDictionary<string, JsonElement> args) => name switch
{
    "get_order_status" =>
        orders.TryGetValue(args["order_id"].GetString()!, out var o)
            ? $"Order {o.Id}: {o.Status}, ETA {o.Eta}."
            : "No order found with that id.",
    "check_stock" =>
        stock.TryGetValue(args["sku"].GetString()!, out var qty)
            ? $"SKU {args["sku"].GetString()}: {qty} units in stock."
            : "Unknown SKU.",
    _ => $"Unknown tool: {name}",
};

sealed record Order(string Id, string Status, string Eta);

Notice RunTool takes the tool inputs as a dictionary of JsonElement. We parse them — we never string-match the raw JSON Claude sends. That matters, and we'll come back to it.

Approach 1 — Raw HttpClient (see the protocol)

No SDK, no dependencies — just HttpClient and System.Net.Http.Json. This is the version that teaches you what's really going on the wire.

First, describe the tools as JSON Schema. This is the exact array that ships in the request:

var tools = new object[]
{
    new
    {
        name = "get_order_status",
        description = "Look up the status and ETA of a customer order by its id.",
        input_schema = new
        {
            type = "object",
            properties = new
            {
                order_id = new { type = "string", description = "Order id, e.g. A-1001" },
            },
            required = new[] { "order_id" },
        },
    },
    new
    {
        name = "check_stock",
        description = "Check how many units of a product SKU are currently in stock.",
        input_schema = new
        {
            type = "object",
            properties = new
            {
                sku = new { type = "string", description = "Product SKU, e.g. ETH-250" },
            },
            required = new[] { "sku" },
        },
    },
};

The description fields are load-bearing — they're how Claude decides when to reach for each tool. Write them like you'd write a docstring for a junior dev, not like a variable name.

Now the client and the agent loop. We keep a growing list of messages and keep calling until Claude stops asking for tools:

using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.anthropic.com") };
http.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY"));
http.DefaultRequestHeaders.Add("anthropic-version", "2023-06-01");

var json = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// The conversation grows as we go. Start with the user's question.
var messages = new List<object>
{
    new { role = "user", content = "Is order A-1001 shipped, and do you still have ETH-250 in stock?" },
};

while (true)
{
    var request = new { model = "claude-opus-4-8", max_tokens = 1024, tools, messages };

    var response = await http.PostAsJsonAsync("/v1/messages", request, json);
    response.EnsureSuccessStatusCode();
    var reply = await response.Content.ReadFromJsonAsync<JsonElement>();

    var stopReason = reply.GetProperty("stop_reason").GetString();
    var content = reply.GetProperty("content");

    // Echo Claude's whole turn back — tool_use blocks included — or the next
    // request won't line up with the tool_result we're about to send.
    messages.Add(new { role = "assistant", content });

    if (stopReason != "tool_use")
    {
        foreach (var block in content.EnumerateArray())
            if (block.GetProperty("type").GetString() == "text")
                Console.WriteLine(block.GetProperty("text").GetString());
        break;
    }

    // Claude asked for one or more tools. Run them all; collect every result.
    var results = new List<object>();
    foreach (var block in content.EnumerateArray())
    {
        if (block.GetProperty("type").GetString() != "tool_use") continue;

        var name = block.GetProperty("name").GetString()!;
        var toolInput = block.GetProperty("input").Deserialize<Dictionary<string, JsonElement>>(json)!;

        results.Add(new
        {
            type = "tool_result",
            tool_use_id = block.GetProperty("id").GetString(),
            content = RunTool(name, toolInput),
        });
    }

    // All the tool_results go back in ONE user message.
    messages.Add(new { role = "user", content = results });
}

Three details that will bite you if you skip them:

Echo the assistant turn back verbatim, tool_use blocks and all. The follow-up request must contain the original tool_use for every tool_result, matched by tool_use_id.
Return every result in a single user message. If Claude asks for two tools and you split the answers across two messages, it quietly learns to stop asking for tools in parallel.
Name your loop variable something other than args. Top-level statements already define an implicit args, and the compiler will not be shy about it. Ask me how I know.

That's a complete agent in one file — and you can see every byte that crosses the wire. Hand-rolling the JSON gets old fast, though, which is exactly why the SDK exists.

Approach 2 — The Anthropic .NET SDK (the short version)

Same agent, far less plumbing. Add the package:

dotnet add package Anthropic

Tool definitions become typed objects. InputSchema.Type is set to "object" for you — don't set it yourself:

using Anthropic;
using Anthropic.Models.Messages;
using System.Text.Json;

AnthropicClient client = new(); // reads ANTHROPIC_API_KEY

List<ToolUnion> tools =
[
    new Tool
    {
        Name = "get_order_status",
        Description = "Look up the status and ETA of a customer order by its id.",
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                ["order_id"] = JsonSerializer.SerializeToElement(
                    new { type = "string", description = "Order id, e.g. A-1001" }),
            },
            Required = ["order_id"],
        },
    },
    new Tool
    {
        Name = "check_stock",
        Description = "Check how many units of a product SKU are currently in stock.",
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                ["sku"] = JsonSerializer.SerializeToElement(
                    new { type = "string", description = "Product SKU, e.g. ETH-250" }),
            },
            Required = ["sku"],
        },
    },
];

The loop is the same idea, now with typed blocks. One quirk worth knowing: the SDK gives you response blocks (TextBlock, ToolUseBlock) but the request wants param blocks (TextBlockParam, ToolUseBlockParam), and there's no .ToParam() shortcut — you rebuild them. It's a few lines, and it keeps the type system honest:

List<MessageParam> messages =
[
    new() { Role = Role.User, Content = "Is order A-1001 shipped, and do you still have ETH-250 in stock?" },
];

while (true)
{
    var response = await client.Messages.Create(new MessageCreateParams
    {
        Model = Model.ClaudeOpus4_8,
        MaxTokens = 1024,
        Tools = tools,
        Messages = messages,
    });

    List<ContentBlockParam> assistant = [];
    List<ContentBlockParam> results = [];

    foreach (var block in response.Content)
    {
        if (block.TryPickText(out TextBlock? text))
        {
            assistant.Add(new TextBlockParam { Text = text.Text });
        }
        else if (block.TryPickToolUse(out ToolUseBlock? call))
        {
            assistant.Add(new ToolUseBlockParam { ID = call.ID, Name = call.Name, Input = call.Input });
            results.Add(new ToolResultBlockParam { ToolUseID = call.ID, Content = RunTool(call.Name, call.Input) });
        }
    }

    messages.Add(new() { Role = Role.Assistant, Content = assistant });

    if (response.StopReason != "tool_use")
    {
        foreach (var t in response.Content.Select(b => b.Value).OfType<TextBlock>())
            Console.WriteLine(t.Text);
        break;
    }

    messages.Add(new() { Role = Role.User, Content = results });
}

Notice RunTool didn't change at all — ToolUseBlock.Input is already an IReadOnlyDictionary<string, JsonElement>, so our executor drops right in.

Let the SDK drive the loop

If you don't want to write the loop yourself, the SDK ships a beta tool runner. You give each tool its schema and the code that runs it (a Run callback), and the runner handles the whole call-execute-continue cycle for you:

using Anthropic;
using Anthropic.Helpers.Beta;
using Anthropic.Models.Beta.Messages;
using System.Text.Json;

// Bundle each tool's schema with the code that answers it.
BetaRunnableTool MakeTool(string name, string description, string prop, string hint) => new()
{
    Name = name,
    Definition = new BetaTool
    {
        Name = name,
        Description = description,
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                [prop] = JsonSerializer.SerializeToElement(new { type = "string", description = hint }),
            },
            Required = [prop],
        },
    },
    Run = (call, ct) => Task.FromResult<BetaToolResultBlockParamContent>(RunTool(call.Name, call.Input)),
};

List<IBetaRunnableTool> runnable =
[
    MakeTool("get_order_status", "Look up the status and ETA of an order by id.", "order_id", "e.g. A-1001"),
    MakeTool("check_stock", "Check units in stock for a product SKU.", "sku", "e.g. ETH-250"),
];

var runner = client.Beta.Messages.ToolRunner(
    new MessageCreateParams
    {
        Model = "claude-opus-4-8",
        MaxTokens = 1024,
        Messages = [new() { Role = Role.User, Content = "Is A-1001 shipped, and is ETH-250 in stock?" }],
    },
    runnable);

await foreach (BetaMessage message in runner)
    foreach (var block in message.Content)
        if (block.TryPickText(out var text))
            Console.WriteLine(text.Text);

No manual loop, no block reconstruction — the runner calls your Run callbacks and keeps the conversation going until Claude is done. Whichever version you run, the output is the same:

> Is order A-1001 shipped, and do you still have ETH-250 in stock?
Order A-1001 has shipped and is on track to arrive 2026-07-26. And yes — the
Ethiopia beans (ETH-250) are in stock, with 42 units available.

Two tools, one question, and Claude figured out on its own that it needed to call both.

When to use tool use — and when not to

Tool use is the right call when the model needs something it can't have from text alone: live or private data (your database, an internal API, the filesystem) or the ability to take an action (send an email, create a ticket, refund an order). If the answer is genuinely locked inside your systems, tool use is how the model gets to it.

It's the wrong call when a single prompt would do. If you just need JSON out of a blob of text, reach for structured outputs, not a tool loop — you'll skip the extra round trips. Not every problem is an agent; some are just a well-shaped prompt.

Between the two implementations: go raw HttpClient when you're learning the protocol, want zero dependencies, or need total control over the loop — approval gates before a tool fires, custom logging, human-in-the-loop review. Go SDK for everything you'd actually ship: typed models, less boilerplate, and the tool runner when you just want the loop handled. And if cost matters more than raw capability, swap claude-opus-4-8 for claude-sonnet-5 — same code, cheaper runs.

Rule of thumb: prompt first, tool use when the model needs to reach into your world, an agent loop only when it needs to reach in more than once.

Key Takeaways

The loop is the whole trick, not magic — declare tools, Claude requests one, you run it, you return the result, repeat until it answers. Everything else is plumbing.
You own execution, and that's the point — Claude only asks to run a tool; your code decides whether and how. The security boundary never leaves your side.
Parse tool inputs, never string-match them — read the JSON into typed values (JsonElement / a dictionary). Matching against the raw serialized string is a bug waiting for a Unicode escape.
Native teaches the protocol, the SDK ships it — HttpClient shows every byte and gives you full control; the Anthropic SDK gives you typed blocks and a tool runner that drives the loop.
Start simple — a plain prompt beats an agent for most tasks. Add tool use when the model needs live data or has to do something, and an agent loop only when one tool call isn't enough.

Crea un agente con Tool Use de Claude en C#: no es un chatbot con esteroides

Juan Gómez — Fri, 24 Jul 2026 20:09:21 +0000

Crea un agente con Tool Use de Claude en C#: no es un chatbot con esteroides

Hoy todo el mundo lanza "agentes de IA". Levanta el capó de la mayoría y encontrarás un chatbot con un prompt de personalidad y un esperanzado // TODO: que haga algo. Puede hablar de tus pedidos. Lo que no puede es consultar uno de verdad.

Un agente real cierra esa brecha. Le das al modelo un conjunto de herramientas —métodos normales de tu código— y él decide, a mitad de la conversación, llamar a una. Tu código ejecuta el trabajo real, le devuelve el resultado, y el modelo sigue hasta que puede responder de verdad. Ese bucle es todo el truco, y lo puedes montar en C# en unas sesenta líneas. Lo haremos dos veces: primero a mano con HttpClient para que veas el protocolo tal cual viaja, y luego con el SDK oficial de Anthropic para .NET, que es la versión corta que de verdad pondrías en producción.

Qué es realmente "tool use"

Tool use (o function calling) es un bucle pequeño y estricto:

Declaras herramientas. Cada una es un name, una description y un JSON Schema para sus parámetros. Nada más — no le envías código a Claude, solo la forma.
Claude responde con un bloque tool_use en lugar de texto. Te está diciendo: "por favor ejecuta check_stock con { "sku": "ETH-250" } y dime qué obtienes".
Tu código lo ejecuta. Aquí está la parte que se le escapa a mucha gente: Claude nunca ejecuta nada. Él pide; tu harness ejecuta. La frontera de seguridad se queda de tu lado de la valla.
Le devuelves la respuesta como un bloque tool_result, atado a la petición por su id.
Claude continúa — quizá llamando a más herramientas, quizá respondiendo. Repites el bucle hasta que deja de pedir.

Piensa en Claude como un colega senior muy rápido que puede leer tu API pero no tiene permiso para tocar producción: te dice exactamente qué botón pulsar, tú lo pulsas y le reportas. El criterio es del modelo; las manos son tuyas.

El agente que vamos a construir

Te presento a Aurora Coffee Co., una tienda ficticia con un agente de soporte que responde preguntas como "¿Ya salió mi pedido y todavía tienen los granos de Etiopía?". Tiene dos herramientas sobre datos en memoria, así que todo corre sin ninguna configuración externa:

get_order_status(order_id) — consulta un pedido.
check_stock(sku) — revisa el inventario de un producto.

Esta es la parte compartida: los datos y el ejecutor de herramientas. Los dos enfoques de abajo reutilizan este mismo método; lo único que cambia es la fontanería de Claude.

using System.Text.Json;

// La "base de datos" de Aurora Coffee Co. — en memoria, para que corra sin setup.
var orders = new Dictionary<string, Order>
{
    ["A-1001"] = new("A-1001", "shipped", "2026-07-26"),
    ["A-1002"] = new("A-1002", "processing", "2026-07-29"),
};
var stock = new Dictionary<string, int> { ["ETH-250"] = 42, ["COL-1KG"] = 0 };

// Tus herramientas son C# normal. Claude nunca ejecuta esto — solo te pide que lo hagas.
string RunTool(string name, IReadOnlyDictionary<string, JsonElement> args) => name switch
{
    "get_order_status" =>
        orders.TryGetValue(args["order_id"].GetString()!, out var o)
            ? $"Pedido {o.Id}: {o.Status}, ETA {o.Eta}."
            : "No hay ningún pedido con ese id.",
    "check_stock" =>
        stock.TryGetValue(args["sku"].GetString()!, out var qty)
            ? $"SKU {args["sku"].GetString()}: {qty} unidades en stock."
            : "SKU desconocido.",
    _ => $"Herramienta desconocida: {name}",
};

sealed record Order(string Id, string Status, string Eta);

Fíjate en que RunTool recibe los parámetros como un diccionario de JsonElement. Los parseamos — nunca comparamos como texto el JSON crudo que manda Claude. Eso importa, y volveremos a ello.

Enfoque 1 — HttpClient a pelo (ver el protocolo)

Sin SDK, sin dependencias — solo HttpClient y System.Net.Http.Json. Esta es la versión que te enseña qué está pasando de verdad en el cable.

Primero, describe las herramientas como JSON Schema. Este es el array exacto que viaja en la petición:

var tools = new object[]
{
    new
    {
        name = "get_order_status",
        description = "Consulta el estado y la ETA de un pedido por su id.",
        input_schema = new
        {
            type = "object",
            properties = new
            {
                order_id = new { type = "string", description = "Id del pedido, p. ej. A-1001" },
            },
            required = new[] { "order_id" },
        },
    },
    new
    {
        name = "check_stock",
        description = "Consulta cuántas unidades de un SKU hay en stock ahora mismo.",
        input_schema = new
        {
            type = "object",
            properties = new
            {
                sku = new { type = "string", description = "SKU del producto, p. ej. ETH-250" },
            },
            required = new[] { "sku" },
        },
    },
};

Los campos description cargan con todo el peso — son la forma en que Claude decide cuándo echar mano de cada herramienta. Escríbelos como escribirías un docstring para alguien junior, no como el nombre de una variable.

Ahora el cliente y el bucle del agente. Mantenemos una lista de mensajes que va creciendo y seguimos llamando hasta que Claude deja de pedir herramientas:

using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.anthropic.com") };
http.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY"));
http.DefaultRequestHeaders.Add("anthropic-version", "2023-06-01");

var json = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// La conversación crece a medida que avanzamos. Empezamos con la pregunta del usuario.
var messages = new List<object>
{
    new { role = "user", content = "¿El pedido A-1001 ya salió, y todavía tienen ETH-250 en stock?" },
};

while (true)
{
    var request = new { model = "claude-opus-4-8", max_tokens = 1024, tools, messages };

    var response = await http.PostAsJsonAsync("/v1/messages", request, json);
    response.EnsureSuccessStatusCode();
    var reply = await response.Content.ReadFromJsonAsync<JsonElement>();

    var stopReason = reply.GetProperty("stop_reason").GetString();
    var content = reply.GetProperty("content");

    // Devuelve el turno completo de Claude — con sus bloques tool_use incluidos — o la
    // siguiente petición no cuadrará con el tool_result que estamos a punto de enviar.
    messages.Add(new { role = "assistant", content });

    if (stopReason != "tool_use")
    {
        foreach (var block in content.EnumerateArray())
            if (block.GetProperty("type").GetString() == "text")
                Console.WriteLine(block.GetProperty("text").GetString());
        break;
    }

    // Claude pidió una o más herramientas. Ejecútalas todas; recoge cada resultado.
    var results = new List<object>();
    foreach (var block in content.EnumerateArray())
    {
        if (block.GetProperty("type").GetString() != "tool_use") continue;

        var name = block.GetProperty("name").GetString()!;
        var toolInput = block.GetProperty("input").Deserialize<Dictionary<string, JsonElement>>(json)!;

        results.Add(new
        {
            type = "tool_result",
            tool_use_id = block.GetProperty("id").GetString(),
            content = RunTool(name, toolInput),
        });
    }

    // Todos los tool_results vuelven en UN SOLO mensaje de usuario.
    messages.Add(new { role = "user", content = results });
}

Tres detalles que te van a morder si los saltas:

Devuelve el turno del asistente tal cual, con bloques tool_use y todo. La petición de continuación debe contener el tool_use original para cada tool_result, emparejados por tool_use_id.
Devuelve todos los resultados en un único mensaje de usuario. Si Claude pide dos herramientas y repartes las respuestas en dos mensajes, aprende calladito a dejar de pedir herramientas en paralelo.
No llames args a tu variable del bucle. Los top-level statements ya definen un args implícito, y el compilador no se va a andar con timideces. No preguntes cómo lo sé.

Eso es un agente completo en un solo archivo — y puedes ver cada byte que cruza el cable. Escribir el JSON a mano cansa rápido, claro, que es justo para lo que existe el SDK.

Enfoque 2 — El SDK de Anthropic para .NET (la versión corta)

El mismo agente, con muchísima menos fontanería. Añade el paquete:

dotnet add package Anthropic

Las definiciones de herramientas pasan a ser objetos tipados. InputSchema.Type se pone en "object" por ti — no lo asignes a mano:

using Anthropic;
using Anthropic.Models.Messages;
using System.Text.Json;

AnthropicClient client = new(); // lee ANTHROPIC_API_KEY

List<ToolUnion> tools =
[
    new Tool
    {
        Name = "get_order_status",
        Description = "Consulta el estado y la ETA de un pedido por su id.",
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                ["order_id"] = JsonSerializer.SerializeToElement(
                    new { type = "string", description = "Id del pedido, p. ej. A-1001" }),
            },
            Required = ["order_id"],
        },
    },
    new Tool
    {
        Name = "check_stock",
        Description = "Consulta cuántas unidades de un SKU hay en stock ahora mismo.",
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                ["sku"] = JsonSerializer.SerializeToElement(
                    new { type = "string", description = "SKU del producto, p. ej. ETH-250" }),
            },
            Required = ["sku"],
        },
    },
];

El bucle es la misma idea, ahora con bloques tipados. Un detalle que conviene saber: el SDK te da bloques de respuesta (TextBlock, ToolUseBlock) pero la petición quiere bloques de parámetro (TextBlockParam, ToolUseBlockParam), y no hay atajo .ToParam() — los reconstruyes. Son unas pocas líneas, y mantienen honesto al sistema de tipos:

List<MessageParam> messages =
[
    new() { Role = Role.User, Content = "¿El pedido A-1001 ya salió, y todavía tienen ETH-250 en stock?" },
];

while (true)
{
    var response = await client.Messages.Create(new MessageCreateParams
    {
        Model = Model.ClaudeOpus4_8,
        MaxTokens = 1024,
        Tools = tools,
        Messages = messages,
    });

    List<ContentBlockParam> assistant = [];
    List<ContentBlockParam> results = [];

    foreach (var block in response.Content)
    {
        if (block.TryPickText(out TextBlock? text))
        {
            assistant.Add(new TextBlockParam { Text = text.Text });
        }
        else if (block.TryPickToolUse(out ToolUseBlock? call))
        {
            assistant.Add(new ToolUseBlockParam { ID = call.ID, Name = call.Name, Input = call.Input });
            results.Add(new ToolResultBlockParam { ToolUseID = call.ID, Content = RunTool(call.Name, call.Input) });
        }
    }

    messages.Add(new() { Role = Role.Assistant, Content = assistant });

    if (response.StopReason != "tool_use")
    {
        foreach (var t in response.Content.Select(b => b.Value).OfType<TextBlock>())
            Console.WriteLine(t.Text);
        break;
    }

    messages.Add(new() { Role = Role.User, Content = results });
}

Fíjate en que RunTool no cambió en absoluto — ToolUseBlock.Input ya es un IReadOnlyDictionary<string, JsonElement>, así que nuestro ejecutor encaja tal cual.

Deja que el SDK maneje el bucle

Si no quieres escribir el bucle tú, el SDK trae un tool runner (en beta). A cada herramienta le das su esquema y el código que la ejecuta (un callback Run), y el runner se encarga de todo el ciclo llamar-ejecutar-continuar:

using Anthropic;
using Anthropic.Helpers.Beta;
using Anthropic.Models.Beta.Messages;
using System.Text.Json;

// Empaqueta el esquema de cada herramienta junto con el código que la responde.
BetaRunnableTool MakeTool(string name, string description, string prop, string hint) => new()
{
    Name = name,
    Definition = new BetaTool
    {
        Name = name,
        Description = description,
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                [prop] = JsonSerializer.SerializeToElement(new { type = "string", description = hint }),
            },
            Required = [prop],
        },
    },
    Run = (call, ct) => Task.FromResult<BetaToolResultBlockParamContent>(RunTool(call.Name, call.Input)),
};

List<IBetaRunnableTool> runnable =
[
    MakeTool("get_order_status", "Consulta el estado y la ETA de un pedido por id.", "order_id", "p. ej. A-1001"),
    MakeTool("check_stock", "Consulta las unidades en stock de un SKU.", "sku", "p. ej. ETH-250"),
];

var runner = client.Beta.Messages.ToolRunner(
    new MessageCreateParams
    {
        Model = "claude-opus-4-8",
        MaxTokens = 1024,
        Messages = [new() { Role = Role.User, Content = "¿A-1001 ya salió, y ETH-250 está en stock?" }],
    },
    runnable);

await foreach (BetaMessage message in runner)
    foreach (var block in message.Content)
        if (block.TryPickText(out var text))
            Console.WriteLine(text.Text);

Sin bucle manual, sin reconstruir bloques — el runner llama a tus callbacks Run y mantiene la conversación viva hasta que Claude termina. Corras la versión que corras, la salida es la misma:

> ¿El pedido A-1001 ya salió, y todavía tienen ETH-250 en stock?
El pedido A-1001 ya salió y está previsto que llegue el 2026-07-26. Y sí — los
granos de Etiopía (ETH-250) están en stock, con 42 unidades disponibles.

Dos herramientas, una pregunta, y Claude dedujo por su cuenta que necesitaba llamar a ambas.

Cuándo usar tool use — y cuándo no

Tool use es la opción correcta cuando el modelo necesita algo que no puede sacar solo del texto: datos en vivo o privados (tu base de datos, una API interna, el sistema de archivos) o la capacidad de realizar una acción (mandar un correo, crear un ticket, reembolsar un pedido). Si la respuesta está de verdad encerrada dentro de tus sistemas, tool use es cómo el modelo llega a ella.

Es la opción equivocada cuando bastaría con un solo prompt. Si solo necesitas JSON a partir de un texto, tira de structured outputs, no de un bucle de herramientas — te ahorras los viajes de ida y vuelta. No todo problema es un agente; algunos son solo un prompt bien formado.

Entre las dos implementaciones: ve con HttpClient a pelo cuando estés aprendiendo el protocolo, quieras cero dependencias o necesites control total del bucle — puertas de aprobación antes de que dispare una herramienta, logging a medida, revisión con humano en el circuito. Ve con el SDK para todo lo que de verdad pondrías en producción: modelos tipados, menos boilerplate y el tool runner cuando solo quieres que se ocupe del bucle. Y si te pesa más el coste que la capacidad bruta, cambia claude-opus-4-8 por claude-sonnet-5 — mismo código, ejecuciones más baratas.

Regla de oro: primero el prompt, tool use cuando el modelo necesite meter la mano en tu mundo, y un bucle de agente solo cuando necesite meterla más de una vez.

Ideas clave

El bucle es todo el truco, no hay magia — declaras herramientas, Claude pide una, tú la ejecutas, devuelves el resultado, repites hasta que responde. Todo lo demás es fontanería.
La ejecución es tuya, y ese es el punto — Claude solo pide ejecutar una herramienta; tu código decide si lo hace y cómo. La frontera de seguridad nunca sale de tu lado.
Parsea los parámetros, no los compares como texto — lee el JSON a valores tipados (JsonElement / un diccionario). Comparar contra la cadena serializada cruda es un bug esperando a un escape Unicode.
El nativo enseña el protocolo, el SDK lo pone en producción — HttpClient muestra cada byte y te da control total; el SDK de Anthropic te da bloques tipados y un tool runner que maneja el bucle.
Empieza simple — un prompt normal le gana a un agente en la mayoría de tareas. Añade tool use cuando el modelo necesite datos en vivo o tenga que hacer algo, y un bucle de agente solo cuando una llamada no baste.

Stop Squinting at .NET Stack Traces: Debug Them With Claude Inside Visual Studio

Juan Gómez — Fri, 17 Jul 2026 13:35:22 +0000

Stop Squinting at .NET Stack Traces: Debug Them With Claude Inside Visual Studio

An unhandled exception fires, and Visual Studio drops forty lines of stack trace into your lap. Thirty-eight of them live in Microsoft.EntityFrameworkCore.* or System.Private.CoreLib, one is an async state-machine frame with a name like <<Main>$>b__0_0, and exactly one points at code you wrote. Your job is to find that one line, understand why it blew up, and fix the actual cause — not the symptom.

We've all pasted a trace into a search engine and gotten back a single Stack Overflow question from 2015, zero answers, one comment that just says "did you ever solve this?". There's a better way, and it now lives right inside Visual Studio: hand the trace to Claude, get back a ranked diagnosis tied to your line, and a fix you can actually reason about.

Why .NET Stack Traces Are Hard to Read

Stack traces aren't hard because they're long. They're hard because modern .NET code rarely runs in a straight line, and the trace reflects the machinery, not your intent.

Async unwinding. await compiles into a state machine. When an exception crosses an await, the frames you see are MoveNext() calls and ExecutionContext.Run, not the tidy call chain you wrote. The method name shows up as <SomethingAsync>d__4, and the line that logically threw might be three awaits up.
Inner exceptions. The message on top is often the least useful one. The real cause is nested — a DbUpdateException wrapping a SqliteException, or a TargetInvocationException wrapping the thing you actually care about. If you only read the first line, you're debugging the wrapper.
AggregateException. Anything involving Task.WhenAll or parallelism can bundle several failures into one. The outer message says "One or more errors occurred" — thanks, very helpful.
Inlined and framework frames. The JIT inlines small methods, so frames disappear. And the frames that remain are mostly library internals you can't change and don't need to read.

An LLM is genuinely good at this specific chore. It has seen these exception shapes thousands of times, it can tell the framework noise from the signal, and — this is the part that matters — when it runs inside your IDE, it can correlate the trace with the actual source file and line.

Two Ways to Put Claude Inside Visual Studio

You don't need to leave the IDE or paste anything into a browser. There are two solid paths, and they suit different moments.

1. Copilot Chat with a Claude model (in-IDE, conversational)

Visual Studio 2022 (17.14+) ships GitHub Copilot with a model picker. Click the Copilot badge, open the model dropdown in the chat prompt box, and pick a Claude model — Sonnet for fast everyday diagnosis, Opus when the bug is genuinely nasty. From then on, every Copilot Chat reply is generated by Claude.

Two things make this path shine for debugging:

When an unhandled exception pops the Exception Helper while debugging, there's an inline Ask Copilot link right on that dialog. With Claude selected as your model, that one-click analysis runs on Claude.
In the chat box you can pull real context in with # references — #Program.cs, #solution, or a highlighted selection — so Claude reads your actual code, not a paraphrase.

If you'd rather bring your own Anthropic key instead of using Copilot's models, the same picker has Manage Models → add Anthropic → paste your API key. Handy if you're already paying for API access.

2. Claude Code in the integrated terminal (agentic)

There's no official Claude Code extension for the full Visual Studio yet, but you don't need one — Claude Code runs in any terminal, including View → Terminal (Ctrl + backtick) inside VS. Run claude, paste the trace, and because Claude Code can read the whole repository, it will open the offending file itself, trace the call path, and propose the fix as a diff you approve or reject.

The trade-off is simple: Copilot Chat is faster for a quick "what does this mean?", while Claude Code is better when the fix touches several files or you want it to reproduce and verify. Use whichever the bug deserves.

A Real Example: The EF Core Trace That Blames the Wrong Thing

Let's debug something concrete. Here's a .NET 10 minimal API endpoint that returns an order summary. It looks reasonable, and it compiles cleanly:

// Program.cs — .NET 10 minimal API
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<ShopContext>(o => o.UseSqlite("Data Source=shop.db"));

var app = builder.Build();

app.MapGet("/orders/{customerId:int}/summary", async (int customerId, ShopContext db) =>
{
    // Fire both queries "in parallel" to be fast — right?
    var ordersTask = db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
    var totalTask  = db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

    await Task.WhenAll(ordersTask, totalTask);

    return Results.Ok(new { Orders = ordersTask.Result, Total = totalTask.Result });
});

app.Run();

Hit the endpoint and it throws. Here's the trace Visual Studio shows (trimmed to the frames that appear):

System.InvalidOperationException: A second operation was started on this context
instance before a previous operation completed. This is usually caused by different
threads concurrently using the same instance of DbContext. For more information on
how to avoid threading issues with DbContext, see https://go.microsoft.com/fwlink/?linkid=2097913.
   at Microsoft.EntityFrameworkCore.Internal.ConcurrencyDetector.EnterCriticalSection()
   at Microsoft.EntityFrameworkCore.Query.Internal.QueryCompiler.ExecuteAsync[TResult](Expression query, CancellationToken ct)
   at Microsoft.EntityFrameworkCore.Query.Internal.EntityQueryProvider.ExecuteAsync[TResult](Expression expression, CancellationToken ct)
   at Microsoft.EntityFrameworkCore.EntityFrameworkQueryableExtensions.ToListAsync[TSource](IQueryable`1 source, CancellationToken ct)
   at Program.<>c.<<Main>$>b__0_0(Int32 customerId, ShopContext db) in C:\src\Shop.Api\Program.cs:line 12

Four of those five frames are EF Core internals. The one that's yours — Program.cs:line 12 — is the ToListAsync() call, which makes it look like ToListAsync is the villain. It isn't.

Feeding it to Claude the right way

The quality of the answer depends entirely on what you paste. A one-line message gets you a one-line guess. Give Claude the whole picture:

.NET 10, EF Core 10, SQLite. This endpoint throws on every request under normal load
(not just concurrency). Full exception and the endpoint code below — what's the root
cause, and what's the idiomatic fix?

[paste the FULL exception via ex.ToString() — message + all inner exceptions + trace]

[paste the MapGet handler]

Three things make that prompt good:

The full exception, not the headline. ex.ToString() includes every inner exception and the complete trace. In Copilot Chat, #Program.cs pulls the source in for you.
The first frame that's yours. Point Claude at Program.cs:line 12 and the code around it. The framework frames are context; your frame is the crime scene.
The conditions. "Every request" vs "only under load" vs "intermittent" changes the diagnosis completely. Say what you observed.

What Claude tells you

Instead of "line 12 failed", you get the actual mechanism: EF Core's DbContext is not thread-safe and does not allow two operations on the same instance at once. Task.WhenAll starts the second query before the first finishes, both on the same injected db, and EF's ConcurrencyDetector throws. The line number was a red herring — the bug is the pattern, not the call.

And it gives you both fixes, with the trade-off:

// Fix A — simplest: run them sequentially. One context, one operation at a time.
var orders = await db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
var total  = await db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);
return Results.Ok(new { Orders = orders, Total = total });

// Fix B — real parallelism: give each query its OWN context via a factory.
builder.Services.AddDbContextFactory<ShopContext>(o => o.UseSqlite("Data Source=shop.db"));

app.MapGet("/orders/{customerId:int}/summary",
    async (int customerId, IDbContextFactory<ShopContext> factory) =>
{
    await using var ordersDb = await factory.CreateDbContextAsync();
    await using var totalDb  = await factory.CreateDbContextAsync();

    var ordersTask = ordersDb.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
    var totalTask  = totalDb.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

    await Task.WhenAll(ordersTask, totalTask);
    return Results.Ok(new { Orders = await ordersTask, Total = await totalTask });
});

Fix A is what you want 90% of the time — two SQLite queries are fast, and the parallelism was never worth the bug. Fix B is the answer when the queries are genuinely slow and independent, because IDbContextFactory<T> hands you a fresh, short-lived context per operation. That distinction — not the line number — is the thing you were actually missing, and it's the kind of judgment a good explanation gives you and a search result doesn't.

A .NET async stack trace has two kinds of frames: the forty that belong to the runtime, and the one that's your fault. Claude's job is to skip the forty and explain the one.

Verify — Don't Trust Blindly

Claude is a very fast senior colleague who is occasionally, confidently wrong. Treat its diagnosis as a strong hypothesis, not a verdict:

Reproduce and confirm. Apply the fix, re-run, and check the exception is actually gone — ideally under the same conditions that triggered it. In Visual Studio, set a breakpoint on the fixed line and watch the state.
Ask why, not just what. "Explain why this fixes it" surfaces a wrong root cause fast. If the reasoning doesn't hold, the fix probably doesn't either.
Watch for plausible-but-wrong causes. For intermittent bugs especially, Claude may propose a cause that fits the trace but isn't yours. Make it rank candidates and tell you how to distinguish them.

The debugger still owns state. Claude owns meaning. When you need to know the actual value of a variable at the moment of the crash, that's a watch window and a breakpoint, not a chat prompt.

When to Reach for Claude — and When Not To

Reach for it when:

The exception type or message is unfamiliar, or the trace is mostly framework internals.
The real cause is buried in inner exceptions or an AggregateException.
You're staring at async frames and can't tell which of your lines is the origin.
You want the idiomatic fix and the trade-offs, not just a patch that makes the red go away.

Don't bother when:

You already know the cause — a NullReferenceException on a line you just wrote doesn't need an LLM.
You need the runtime value of something — use the debugger.
The trace contains secrets or customer data. Connection strings, tokens, and PII live in exception messages and payloads more often than you'd like. Scrub before you paste, especially with a cloud model.

The rule of thumb: if you'd otherwise open a browser to search the exception, ask Claude instead — it's in the IDE, it can read your code, and it won't send you to a dead 2015 forum thread.

Key Takeaways

The trace shows machinery, not intent — async state machines, inner exceptions, and framework frames bury the one line that's yours. Reading traces is pattern recognition, which is exactly where an LLM helps.
Claude lives in Visual Studio two ways — pick it in Copilot Chat's model picker for quick, conversational diagnosis; run Claude Code in the integrated terminal when the fix is agentic and spans files.
Context is the whole game — paste the full ex.ToString(), point at the first frame that's yours, and describe when it happens. A headline message gets a headline guess.
The line number is often a red herring — the EF Core example throws at ToListAsync, but the bug is sharing one DbContext across parallel queries. The value is the explanation, not the location.
Verify, then trust — reproduce the fix, ask why it works, and never paste secrets. The debugger owns state; Claude owns meaning.

Deja de Entrecerrar los Ojos con los Stack Traces de .NET: Depúralos con Claude en Visual Studio

Juan Gómez — Fri, 17 Jul 2026 13:23:04 +0000

Deja de Entrecerrar los Ojos con los Stack Traces de .NET: Depúralos con Claude en Visual Studio

Salta una excepción no controlada y Visual Studio te suelta cuarenta líneas de stack trace en el regazo. Treinta y ocho viven en Microsoft.EntityFrameworkCore.* o en System.Private.CoreLib, una es un frame de máquina de estados asíncrona con un nombre tipo <<Main>$>b__0_0, y exactamente una apunta a código que escribiste tú. Tu trabajo es encontrar esa línea, entender por qué explotó y arreglar la causa real — no el síntoma.

Todos hemos pegado un trace en el buscador y recibido a cambio una sola pregunta de Stack Overflow de 2015, cero respuestas, y un único comentario que dice "¿al final lo resolviste?". Hay una forma mejor, y ahora vive dentro de Visual Studio: le pasas el trace a Claude y recibes un diagnóstico ordenado por probabilidad, atado a tu línea, con un arreglo que de verdad puedes razonar.

Por Qué Cuesta Tanto Leer un Stack Trace de .NET

Los stack traces no son difíciles por ser largos. Son difíciles porque el código moderno de .NET casi nunca corre en línea recta, y el trace refleja la maquinaria, no tu intención.

Desenrollado asíncrono. Un await compila a una máquina de estados. Cuando una excepción cruza un await, los frames que ves son llamadas a MoveNext() y ExecutionContext.Run, no la cadena de llamadas ordenada que escribiste. El método aparece como <AlgoAsync>d__4, y la línea que lógicamente lanzó puede estar tres await más arriba.
Excepciones internas (inner exceptions). El mensaje de arriba suele ser el menos útil. La causa real está anidada — un DbUpdateException envolviendo un SqliteException, o un TargetInvocationException envolviendo lo que de verdad importa. Si solo lees la primera línea, estás depurando el envoltorio.
AggregateException. Cualquier cosa con Task.WhenAll o paralelismo puede empaquetar varios fallos en uno. El mensaje externo dice "Se produjeron uno o más errores" — gracias, utilísimo.
Frames inlineados y de framework. El JIT hace inline de métodos pequeños, así que hay frames que desaparecen. Y los que quedan son en su mayoría internos de librerías que no puedes cambiar ni necesitas leer.

Un LLM es genuinamente bueno para esta tarea concreta. Ha visto estas formas de excepción miles de veces, sabe separar el ruido del framework de la señal y — esto es lo clave — cuando corre dentro de tu IDE, puede correlacionar el trace con el archivo y la línea reales.

Dos Formas de Meter a Claude Dentro de Visual Studio

No necesitas salir del IDE ni pegar nada en un navegador. Hay dos caminos sólidos, y cada uno sirve para un momento distinto.

1. Copilot Chat con un modelo Claude (dentro del IDE, conversacional)

Visual Studio 2022 (17.14+) trae GitHub Copilot con un selector de modelo. Haz clic en el badge de Copilot, abre el desplegable de modelos en la caja del chat y elige un modelo Claude — Sonnet para el diagnóstico rápido del día a día, Opus cuando el bug es realmente feo. A partir de ahí, cada respuesta de Copilot Chat la genera Claude.

Dos cosas hacen que este camino brille para depurar:

Cuando una excepción no controlada abre el Asistente de excepciones durante el debug, hay un enlace Preguntar a Copilot justo en ese diálogo. Con Claude seleccionado como modelo, ese análisis de un clic corre sobre Claude.
En la caja del chat puedes traer contexto real con referencias # — #Program.cs, #solution, o una selección resaltada — para que Claude lea tu código de verdad, no una paráfrasis.

Si prefieres usar tu propia clave de Anthropic en vez de los modelos de Copilot, el mismo selector tiene Manage Models → agregar Anthropic → pegar tu API key. Cómodo si ya pagas por acceso a la API.

2. Claude Code en la terminal integrada (agéntico)

Todavía no hay una extensión oficial de Claude Code para el Visual Studio completo, pero no la necesitas — Claude Code corre en cualquier terminal, incluida Ver → Terminal (Ctrl + backtick) dentro de VS. Ejecuta claude, pega el trace y, como Claude Code puede leer todo el repositorio, abrirá él mismo el archivo culpable, seguirá la ruta de llamadas y propondrá el arreglo como un diff que apruebas o rechazas.

El intercambio es simple: Copilot Chat es más rápido para un "¿qué significa esto?", mientras que Claude Code es mejor cuando el arreglo toca varios archivos o quieres que reproduzca y verifique. Usa el que el bug se merezca.

Un Ejemplo Real: El Trace de EF Core Que Culpa a Quien No Es

Depuremos algo concreto. Este es un endpoint de minimal API en .NET 10 que devuelve el resumen de pedidos de un cliente. Se ve razonable, y compila sin quejas:

// Program.cs — minimal API en .NET 10
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<ShopContext>(o => o.UseSqlite("Data Source=shop.db"));

var app = builder.Build();

app.MapGet("/orders/{customerId:int}/summary", async (int customerId, ShopContext db) =>
{
    // Disparamos ambas consultas "en paralelo" para ir rápido — ¿verdad?
    var ordersTask = db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
    var totalTask  = db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

    await Task.WhenAll(ordersTask, totalTask);

    return Results.Ok(new { Orders = ordersTask.Result, Total = totalTask.Result });
});

app.Run();

Llamas al endpoint y lanza. Este es el trace que muestra Visual Studio (recortado a los frames que aparecen):

System.InvalidOperationException: A second operation was started on this context
instance before a previous operation completed. This is usually caused by different
threads concurrently using the same instance of DbContext. For more information on
how to avoid threading issues with DbContext, see https://go.microsoft.com/fwlink/?linkid=2097913.
   at Microsoft.EntityFrameworkCore.Internal.ConcurrencyDetector.EnterCriticalSection()
   at Microsoft.EntityFrameworkCore.Query.Internal.QueryCompiler.ExecuteAsync[TResult](Expression query, CancellationToken ct)
   at Microsoft.EntityFrameworkCore.Query.Internal.EntityQueryProvider.ExecuteAsync[TResult](Expression expression, CancellationToken ct)
   at Microsoft.EntityFrameworkCore.EntityFrameworkQueryableExtensions.ToListAsync[TSource](IQueryable`1 source, CancellationToken ct)
   at Program.<>c.<<Main>$>b__0_0(Int32 customerId, ShopContext db) in C:\src\Shop.Api\Program.cs:line 12

Cuatro de esos cinco frames son internos de EF Core. El único que es tuyo — Program.cs:line 12 — es la llamada a ToListAsync(), lo que hace parecer que ToListAsync es el villano. No lo es.

Cómo pasárselo a Claude bien

La calidad de la respuesta depende por completo de lo que pegues. Un mensaje de una línea te da una conjetura de una línea. Dale a Claude el panorama completo:

.NET 10, EF Core 10, SQLite. Este endpoint lanza en cada request con carga normal
(no solo con concurrencia). Abajo van la excepción completa y el código del endpoint —
¿cuál es la causa raíz y cuál es el arreglo idiomático?

[pega la excepción COMPLETA con ex.ToString() — mensaje + todas las inner exceptions + trace]

[pega el handler del MapGet]

Tres cosas hacen que ese prompt sea bueno:

La excepción completa, no el titular. ex.ToString() incluye cada inner exception y el trace entero. En Copilot Chat, #Program.cs te trae el código solo.
El primer frame que es tuyo. Apunta a Claude a Program.cs:line 12 y al código a su alrededor. Los frames de framework son contexto; tu frame es la escena del crimen.
Las condiciones. "En cada request" vs "solo bajo carga" vs "intermitente" cambia el diagnóstico por completo. Di lo que observaste.

Lo que Claude te responde

En vez de "la línea 12 falló", obtienes el mecanismo real: el DbContext de EF Core no es thread-safe y no permite dos operaciones sobre la misma instancia a la vez. Task.WhenAll arranca la segunda consulta antes de que termine la primera, ambas sobre el mismo db inyectado, y el ConcurrencyDetector de EF lanza. El número de línea era una pista falsa — el bug es el patrón, no la llamada.

Y te da los dos arreglos, con el intercambio incluido:

// Arreglo A — el más simple: ejecútalas en secuencia. Un contexto, una operación a la vez.
var orders = await db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
var total  = await db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);
return Results.Ok(new { Orders = orders, Total = total });

// Arreglo B — paralelismo real: dale a cada consulta su PROPIO contexto vía factory.
builder.Services.AddDbContextFactory<ShopContext>(o => o.UseSqlite("Data Source=shop.db"));

app.MapGet("/orders/{customerId:int}/summary",
    async (int customerId, IDbContextFactory<ShopContext> factory) =>
{
    await using var ordersDb = await factory.CreateDbContextAsync();
    await using var totalDb  = await factory.CreateDbContextAsync();

    var ordersTask = ordersDb.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
    var totalTask  = totalDb.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

    await Task.WhenAll(ordersTask, totalTask);
    return Results.Ok(new { Orders = await ordersTask, Total = await totalTask });
});

El Arreglo A es lo que quieres el 90% de las veces — dos consultas a SQLite son rápidas, y el paralelismo nunca valió el bug. El Arreglo B es la respuesta cuando las consultas son genuinamente lentas e independientes, porque IDbContextFactory<T> te entrega un contexto fresco y de vida corta por operación. Esa distinción — no el número de línea — es lo que de verdad te faltaba, y es el tipo de criterio que te da una buena explicación y no un resultado de búsqueda.

Un stack trace asíncrono de .NET tiene dos tipos de frames: los cuarenta que le pertenecen al runtime, y el que es culpa tuya. El trabajo de Claude es saltarse los cuarenta y explicarte el uno.

Verifica — No Confíes a Ciegas

Claude es un colega senior muy rápido que de vez en cuando se equivoca con toda seguridad. Trata su diagnóstico como una hipótesis fuerte, no como un veredicto:

Reproduce y confirma. Aplica el arreglo, vuelve a correr y comprueba que la excepción de verdad desapareció — idealmente bajo las mismas condiciones que la dispararon. En Visual Studio, pon un breakpoint en la línea corregida y observa el estado.
Pregunta el por qué, no solo el qué. "Explica por qué esto lo arregla" saca a la luz una causa raíz equivocada rapidísimo. Si el razonamiento no se sostiene, el arreglo probablemente tampoco.
Ojo con las causas plausibles pero falsas. Sobre todo con bugs intermitentes, Claude puede proponer una causa que encaja con el trace pero que no es la tuya. Haz que ordene los candidatos y te diga cómo distinguirlos.

El debugger sigue siendo el dueño del estado. Claude es dueño del significado. Cuando necesitas saber el valor real de una variable en el momento del crash, eso es una ventana de inspección y un breakpoint, no un prompt de chat.

Cuándo Recurrir a Claude — y Cuándo No

Recurre a él cuando:

El tipo o el mensaje de la excepción te resulta desconocido, o el trace es casi todo internos de framework.
La causa real está enterrada en inner exceptions o en un AggregateException.
Estás mirando frames asíncronos y no logras saber cuál de tus líneas es el origen.
Quieres el arreglo idiomático y sus intercambios, no solo un parche que quite el rojo.

No te molestes cuando:

Ya sabes la causa — un NullReferenceException en una línea que acabas de escribir no necesita un LLM.
Necesitas el valor en runtime de algo — usa el debugger.
El trace contiene secretos o datos de clientes. Las cadenas de conexión, los tokens y los datos personales aparecen en mensajes de excepción y payloads más seguido de lo que te gustaría. Límpialos antes de pegar, especialmente con un modelo en la nube.

La regla de oro: si de otro modo abrirías el navegador para buscar la excepción, mejor pregúntale a Claude — está en el IDE, puede leer tu código, y no te mandará a un hilo de foro muerto de 2015.

Puntos Clave

El trace muestra maquinaria, no intención — máquinas de estados asíncronas, inner exceptions y frames de framework entierran la única línea que es tuya. Leer traces es reconocimiento de patrones, que es justo donde ayuda un LLM.
Claude vive en Visual Studio de dos formas — elígelo en el selector de modelo de Copilot Chat para diagnóstico rápido y conversacional; corre Claude Code en la terminal integrada cuando el arreglo es agéntico y abarca varios archivos.
El contexto lo es todo — pega el ex.ToString() completo, apunta al primer frame que es tuyo y describe cuándo pasa. Un mensaje titular recibe una conjetura titular.
El número de línea suele ser una pista falsa — el ejemplo de EF Core lanza en ToListAsync, pero el bug es compartir un DbContext entre consultas paralelas. El valor está en la explicación, no en la ubicación.
Verifica, luego confía — reproduce el arreglo, pregunta por qué funciona y nunca pegues secretos. El debugger es dueño del estado; Claude, del significado.

RAG local en .NET: Chatea con tu Documentación (sin nube, sin API keys)

Juan Gómez — Fri, 10 Jul 2026 20:47:29 +0000

RAG local en .NET: Chatea con tu Documentación (sin nube, sin API keys)

Pregúntale a un modelo de lenguaje sobre la documentación de tu producto y míralo improvisar. Nunca leyó tus docs internas de la API, así que rellena los huecos con respuestas seguras, plausibles y completamente inventadas. Eso es una alucinación, y no es que el modelo sea tonto: es que le pediste algo para lo que jamás le diste el material.

RAG lo arregla. En vez de rezar para que el modelo memorizara tus docs, le entregas las páginas relevantes en el momento de la pregunta — como dejar que un estudiante haga un examen a libro abierto. En este tutorial construimos un pequeño sistema RAG en .NET 10 que responde preguntas sobre la documentación de un producto, y lo hacemos 100% local: sin nube, sin API keys, sin factura a fin de mes.

¿Qué es RAG, sin humo?

RAG significa Retrieval-Augmented Generation (Generación Aumentada por Recuperación). Quítale las siglas y quedan tres ideas simples:

Retrieval (recuperar) — encontrar los pedazos de tus docs que se relacionan con la pregunta.
Augmented (aumentar) — pegar esos pedazos al prompt.
Generation (generar) — dejar que el modelo escriba la respuesta usándolos.

Eso es todo. Lo ingenioso está en el primer paso: ¿cómo encuentras los pedazos relevantes? No basta con buscar palabras iguales, porque alguien puede preguntar "¿cómo inicio sesión?" mientras tu doc dice "autenticación". Palabras distintas, mismo significado.

El truco son los embeddings. Un embedding es simplemente una lista de números (un vector) que captura el significado de un texto. Los textos que significan cosas parecidas obtienen números parecidos — así "iniciar sesión" y "autenticación" quedan cerca, aunque no compartan ni una letra. Encuentra los vectores más cercanos al vector de la pregunta y habrás encontrado los docs relevantes. No es magia, es geometría.

Los tres pasos de RAG

Este es el pipeline completo, de principio a fin:

Ingesta (una sola vez, al inicio): parte los docs en trozos pequeños, convierte cada trozo en un embedding y guárdalos.
Recuperación (por cada pregunta): convierte la pregunta en un embedding y busca los trozos cuyos embeddings estén más cerca.
Aumento y generación (por cada pregunta): mete esos trozos en el prompt y pide al modelo que responda usándolos.

Los pasos 2 y 3 corren cada vez que alguien pregunta algo. El paso 1 corre una vez y se reutiliza para siempre (o hasta que cambien tus docs).

Lo que vamos a construir + Setup

Armaremos una app de consola que ingiere la documentación de un producto y luego responde preguntas sobre ella desde la terminal. Tres herramientas hacen el trabajo pesado:

Ollama corre los modelos de IA en tu máquina — uno para crear embeddings, otro para escribir respuestas.
SQLite guarda todo en un único archivo.
sqlite-vec, una extensión de SQLite, hace por nosotros la búsqueda de "los vectores más cercanos".

Tu laptop está a punto de tener un segundo empleo como mini data center de IA. El único costo es un ventilador un poco más caliente.

# 1. Crea el proyecto
dotnet new console -n OrbitDocsRag
cd OrbitDocsRag
dotnet add package Microsoft.Data.Sqlite

# 2. Instala Ollama desde https://ollama.com y descarga los dos modelos
ollama pull nomic-embed-text   # convierte texto en vectores de 768 números
ollama pull llama3.2           # escribe la respuesta final

# 3. Coloca la librería nativa de sqlite-vec junto a tu app.
#    Descarga vec0.dll (Windows) / vec0.so (Linux) / vec0.dylib (macOS)
#    desde https://github.com/asg017/sqlite-vec/releases y ponla en la
#    carpeta del proyecto para que aterrice en bin/ al compilar.

Ollama expone una API REST sencilla en http://localhost:11434. Hablaremos con ella usando un HttpClient pelado — sin SDK — para que veas que no hay nada escondido detrás de un wrapper. De verdad son solo un par de POST por HTTP.

Paso 1 — Partir los docs en trozos (chunking)

No puedes convertir un manual de 50 páginas en un solo vector — sería un promedio borroso de todo, inútil para cualquier cosa. Así que partimos cada documento en ventanas pequeñas y solapadas. Los trozos pequeños dan coincidencias precisas; el solapamiento evita que una idea que cae justo en el borde quede cortada por la mitad.

sealed record DocChunk(string Source, string Text);

static class Chunker
{
    public static IEnumerable<DocChunk> Split(
        string source, string text, int maxWords = 120, int overlap = 20)
    {
        var words = text.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries);

        for (var start = 0; start < words.Length; start += maxWords - overlap)
        {
            var end = Math.Min(start + maxWords, words.Length);
            yield return new DocChunk(source, string.Join(' ', words[start..end]));
            if (end == words.Length) break;
        }
    }
}

Cada trozo recuerda su Source (el archivo del que vino) para poder citarlo después. Desliza una ventana de 120 palabras avanzando de 100 en 100, y obtienes trozos solapados que conservan su contexto.

Paso 2 — Convertir texto en vectores (embeddings)

Aquí Ollama se gana el sueldo. Hacemos POST de un texto a /api/embed y recibimos un arreglo de 768 floats — el embedding.

using System.Net.Http.Json;
using System.Text.Json;

sealed class OllamaClient
{
    private static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web);
    private readonly HttpClient _http = new() { BaseAddress = new Uri("http://localhost:11434") };

    public async Task<float[]> EmbedAsync(string text)
    {
        var request = new { model = "nomic-embed-text", input = text };
        var response = await _http.PostAsJsonAsync("/api/embed", request, Json);
        response.EnsureSuccessStatusCode();

        var body = await response.Content.ReadFromJsonAsync<EmbedResponse>(Json);
        return body!.Embeddings[0];
    }

    private sealed record EmbedResponse(float[][] Embeddings);
}

Esa es toda la parte de "IA" de los embeddings — una llamada HTTP. El modelo lee tu texto y devuelve su significado como 768 números. Dos trozos sobre autenticación regresarán con dos arreglos muy parecidos.

Paso 3 — Guardar los vectores en SQLite

Ahora guardamos cada trozo y su embedding. sqlite-vec nos da una tabla virtual especial que sabe buscar vectores de forma nativa. Le decimos que los vectores son 768 floats y que queremos distancia coseno (ya llegamos a eso). Las columnas +source y +chunk viajan como texto plano para poder recuperar el texto original tras una búsqueda.

using Microsoft.Data.Sqlite;
using System.Text.Json;

sealed class VectorStore(string path) : IDisposable
{
    private readonly SqliteConnection _connection = new($"Data Source={path}");

    public void Initialize()
    {
        _connection.Open();
        _connection.LoadExtension("vec0"); // carga la librería nativa de sqlite-vec

        using var command = _connection.CreateCommand();
        command.CommandText = """
            CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(
                embedding float[768] distance_metric=cosine,
                +source text,
                +chunk text
            );
            """;
        command.ExecuteNonQuery();
    }

    public void Add(DocChunk chunk, float[] embedding)
    {
        using var command = _connection.CreateCommand();
        command.CommandText = """
            INSERT INTO vec_chunks(embedding, source, chunk)
            VALUES ($embedding, $source, $chunk);
            """;
        command.Parameters.AddWithValue("$embedding", JsonSerializer.Serialize(embedding));
        command.Parameters.AddWithValue("$source", chunk.Source);
        command.Parameters.AddWithValue("$chunk", chunk.Text);
        command.ExecuteNonQuery();
    }

    public void Dispose() => _connection.Dispose();
}

Guardamos el embedding como un string JSON tipo [0.12, -0.04, ...] — sqlite-vec lo interpreta sin problema.

¿Cómo funciona eso de "el más cercano"?

sqlite-vec hace la búsqueda en código nativo rápido, pero no hay ningún misterio adentro. "¿Qué tan parecidos son dos vectores?" se responde con similitud coseno, que son un puñado de líneas de C# plano:

static double CosineSimilarity(float[] a, float[] b)
{
    double dot = 0, magA = 0, magB = 0;
    for (var i = 0; i < a.Length; i++)
    {
        dot  += a[i] * b[i];
        magA += a[i] * a[i];
        magB += b[i] * b[i];
    }
    return dot / (Math.Sqrt(magA) * Math.Sqrt(magB));
}

El resultado va de 1.0 (significado idéntico) hasta 0 (sin relación). sqlite-vec reporta la distancia — básicamente 1 - similitud — así que más pequeño es más cercano. Por eso cada consulta de abajo termina en ORDER BY distance. Eso es toda la "búsqueda vectorial" de la que todos hablan: un producto punto y una raíz cuadrada.

Paso 4 — Recuperar los trozos relevantes

Por cada pregunta, convertimos la pregunta en embedding exactamente igual, y luego le pedimos a sqlite-vec los k trozos más cercanos. La palabra clave MATCH es la señal de sqlite-vec para ejecutar una búsqueda por vecinos más cercanos.

sealed record SearchHit(string Source, string Chunk, double Distance);

// (agrega este método a VectorStore)
public List<SearchHit> Search(float[] queryEmbedding, int k)
{
    using var command = _connection.CreateCommand();
    command.CommandText = """
        SELECT source, chunk, distance
        FROM vec_chunks
        WHERE embedding MATCH $query
        ORDER BY distance
        LIMIT $k;
        """;
    command.Parameters.AddWithValue("$query", JsonSerializer.Serialize(queryEmbedding));
    command.Parameters.AddWithValue("$k", k);

    var hits = new List<SearchHit>();
    using var reader = command.ExecuteReader();
    while (reader.Read())
        hits.Add(new SearchHit(reader.GetString(0), reader.GetString(1), reader.GetDouble(2)));

    return hits;
}

Le das el vector de la pregunta y recibes los tres trozos con mayor probabilidad de contener la respuesta — ordenados del más cercano al más lejano.

Paso 5 — Armar el prompt y generar la respuesta

El último paso es la recompensa. Cosemos los trozos recuperados dentro de un prompt con una instrucción estricta: responde solo con este contexto. Luego lo enviamos al modelo de chat vía /api/chat.

// (agrega este método a OllamaClient)
public async Task<string> ChatAsync(string prompt)
{
    var request = new
    {
        model = "llama3.2",
        messages = new[] { new { role = "user", content = prompt } },
        stream = false
    };
    var response = await _http.PostAsJsonAsync("/api/chat", request, Json);
    response.EnsureSuccessStatusCode();

    var body = await response.Content.ReadFromJsonAsync<ChatResponse>(Json);
    return body!.Message.Content;
}

// records anidados dentro de OllamaClient
private sealed record ChatResponse(ChatMessage Message);
private sealed record ChatMessage(string Role, string Content);

Y el prompt que lo une todo:

var context = string.Join("\n\n", hits.Select(h => $"[{h.Source}] {h.Chunk}"));

var prompt = $"""
    Answer the question using ONLY the context below.
    If the answer is not in the context, say "I don't know based on the docs."

    Context:
    {context}

    Question: {question}
    """;

Esa única instrucción — solo con este contexto — es lo que mata las alucinaciones. Sin nada en qué apoyarse, el modelo no inventará una respuesta con seguridad; admitirá que no sabe. Es la diferencia entre un estudiante que estudió y uno que improvisa frente a la clase. Y como cada trozo lleva su etiqueta [source.md], puedes mostrarle al usuario exactamente de dónde salió la respuesta.

El ejemplo completo

Este es el Program.cs de nivel superior. Trae tres "docs" diminutas embebidas para que puedas correrlo sin ningún archivo, pero cambia SampleDocs.All por una carpeta de .md reales y no cambia nada más. Mantén los tipos OllamaClient, VectorStore, Chunker, DocChunk y SearchHit de los pasos anteriores en el mismo proyecto (debajo del código de nivel superior, o en sus propios archivos) y compila tal cual.

using System.Net.Http.Json;
using System.Text.Json;
using Microsoft.Data.Sqlite;

var ollama = new OllamaClient();
using var store = new VectorStore("orbit-docs.db");
store.Initialize();

// --- Paso 1 + 2 + 3: ingesta de los docs (trocear -> embeber -> guardar) ---
foreach (var (source, text) in SampleDocs.All)
    foreach (var chunk in Chunker.Split(source, text))
    {
        var embedding = await ollama.EmbedAsync(chunk.Text);
        store.Add(chunk, embedding);
    }

Console.Write("Pregunta sobre la API de Orbit: ");
var question = Console.ReadLine() is { Length: > 0 } input ? input : "¿Cómo me autentico?";

// --- Paso 4: recuperar ---
var questionEmbedding = await ollama.EmbedAsync(question);
var hits = store.Search(questionEmbedding, k: 3);

// --- Paso 5: aumentar + generar ---
var context = string.Join("\n\n", hits.Select(h => $"[{h.Source}] {h.Chunk}"));
var prompt = $"""
    Answer the question using ONLY the context below.
    If the answer is not in the context, say "I don't know based on the docs."

    Context:
    {context}

    Question: {question}
    """;

var answer = await ollama.ChatAsync(prompt);

Console.WriteLine($"\n{answer}\n");
Console.WriteLine($"Fuentes: {string.Join(", ", hits.Select(h => h.Source).Distinct())}");

static class SampleDocs
{
    public static readonly Dictionary<string, string> All = new()
    {
        ["auth.md"] = """
            Authentication. The Orbit API uses API keys. Send your key in the
            Authorization header as 'Bearer <key>'. Keys never expire but can be
            revoked from the dashboard. Rate limits are 100 requests per minute.
            """,
        ["webhooks.md"] = """
            Webhooks. Orbit pushes events to your endpoint. Register a webhook URL
            in the dashboard. Every payload is signed with HMAC-SHA256; verify the
            X-Orbit-Signature header before trusting the body. Failed deliveries
            retry 5 times with exponential backoff.
            """,
        ["errors.md"] = """
            Error codes. Orbit returns standard HTTP status codes. A 429 means you
            hit the rate limit, so back off and retry. A 401 means your API key is
            missing or invalid. A 422 means the request body failed validation.
            """
    };
}

Córrelo, pregunta "¿cómo inicio sesión?" y, aunque esas palabras exactas no aparecen en ningún lado de los docs, el embedding de tu pregunta aterriza junto al trozo de autenticación — y el modelo responde con las instrucciones de la API key, citando auth.md. Eso es RAG funcionando.

Cuándo usar RAG — y cuándo no

RAG es la herramienta correcta cuando tu conocimiento es grande, privado o cambiante:

Usa RAG para docs de empresa, manuales de producto, tickets de soporte, una base de conocimiento — cualquier cosa que el modelo base nunca vio y que se actualiza seguido. ¿Docs nuevos? Solo los embebes. Sin reentrenar.
Sáltate RAG y pega todo en el prompt cuando el conocimiento completo cabe cómodamente en la ventana de contexto. Si son dos párrafos, la recuperación es matar moscas a cañonazos.
Recurre a fine-tuning cuando necesitas cambiar el estilo, tono o formato del modelo — no sus hechos. El fine-tuning enseña comportamiento; RAG aporta conocimiento. Resuelven problemas distintos, y muchos sistemas reales usan ambos.

Algunas limitaciones honestas a tener en cuenta: tus respuestas son tan buenas como tus trozos, así que un mal chunking significa mala recuperación. Las tablas y los números se embeben mal (su significado vive en la estructura, no en la prosa). Y si la respuesta simplemente no está en los docs, un sistema RAG bien instruido debería decirlo — lo cual es una virtud, no un defecto.

La regla de oro: si tendrías que copiar y pegar un documento en el chat para obtener una buena respuesta, ese es trabajo para RAG.

Puntos clave

RAG son tres pasos, no magia — recuperar los trozos relevantes, aumentar el prompt, generar la respuesta. Todo lo demás es detalle.
Los embeddings convierten significado en geometría — un texto parecido se vuelve un vector parecido, así encuentras docs relevantes aunque las palabras no coincidan.
La "búsqueda vectorial" es solo similitud coseno — un producto punto y una raíz cuadrada; sqlite-vec solo lo hace rápido, no misterioso.
Anclar al contexto mata las alucinaciones — decirle al modelo que responda solo con el contexto recuperado convierte el disparate seguro en un honesto "no sé", y te deja citar fuentes.
No necesitas la nube — Ollama más SQLite corren un pipeline RAG completo en tu laptop, con cero API keys y cero costo por token.

Build a Local RAG in .NET: Chat With Your Docs (No Cloud, No API Keys)

Juan Gómez — Fri, 10 Jul 2026 20:47:26 +0000

Build a Local RAG in .NET: Chat With Your Docs (No Cloud, No API Keys)

Ask a language model about your product's documentation and watch it improvise. It has never read your internal API docs, so it fills the gaps with confident, plausible, completely made-up answers. That is hallucination, and it is not the model being dumb — it is the model being asked a question it was never given the material to answer.

RAG fixes this. Instead of hoping the model memorized your docs, you hand it the relevant pages at question time — like letting a student take an open-book exam. In this tutorial we build a small RAG system in .NET 10 that answers questions about a product's documentation, and we do it 100% locally: no cloud, no API keys, no invoice at the end of the month.

What Is RAG, Without the Hype?

RAG stands for Retrieval-Augmented Generation. Strip away the acronym and it is three plain-English words:

Retrieval — find the pieces of your docs that relate to the question.
Augmented — glue those pieces onto the prompt.
Generation — let the model write the answer using them.

That's it. The clever part is step one: how do you find the relevant pieces? You can't just search for matching keywords, because someone might ask "how do I log in?" while your docs say "authentication." Different words, same meaning.

The trick is embeddings. An embedding is just a list of numbers (a vector) that captures the meaning of a piece of text. Texts that mean similar things get similar numbers — so "log in" and "authentication" land close together, even though they share no letters. Find the closest vectors to the question's vector, and you've found the relevant docs. No magic, just geometry.

The Three Steps of RAG

Here is the entire pipeline, start to finish:

Ingest (done once, up front): chop the docs into small chunks, turn each chunk into an embedding, and store them.
Retrieve (done per question): turn the question into an embedding, then find the chunks whose embeddings are closest to it.
Augment & generate (done per question): drop those chunks into the prompt and ask the model to answer using them.

Steps 2 and 3 run every time someone asks something. Step 1 runs once and gets reused forever (or until your docs change).

What We're Building + Setup

We'll build a console app that ingests a product's docs and then answers questions about them from the terminal. Three tools do the heavy lifting:

Ollama runs the AI models on your machine — one to create embeddings, one to write answers.
SQLite stores everything in a single file.
sqlite-vec, a SQLite extension, does the "find the closest vectors" search for us.

Your laptop is about to moonlight as a tiny AI data center. The only cost is a slightly warmer fan.

# 1. Create the project
dotnet new console -n OrbitDocsRag
cd OrbitDocsRag
dotnet add package Microsoft.Data.Sqlite

# 2. Install Ollama from https://ollama.com, then pull the two models
ollama pull nomic-embed-text   # turns text into 768-number vectors
ollama pull llama3.2           # writes the final answer

# 3. Drop the sqlite-vec native library next to your app.
#    Grab vec0.dll (Windows) / vec0.so (Linux) / vec0.dylib (macOS)
#    from https://github.com/asg017/sqlite-vec/releases and place it
#    in the project folder so it lands in bin/ at build time.

Ollama exposes a plain REST API at http://localhost:11434. We'll talk to it with a bare HttpClient — no SDK — so you can see there is nothing hiding behind a wrapper. It really is just a couple of HTTP POSTs.

Step 1 — Chop the Docs Into Chunks

You can't embed a whole 50-page manual as one vector — it would be a blurry average of everything, useful for nothing. So we split each document into small, overlapping windows. Small chunks give precise matches; the overlap makes sure an idea that straddles a boundary isn't cut in half.

sealed record DocChunk(string Source, string Text);

static class Chunker
{
    public static IEnumerable<DocChunk> Split(
        string source, string text, int maxWords = 120, int overlap = 20)
    {
        var words = text.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries);

        for (var start = 0; start < words.Length; start += maxWords - overlap)
        {
            var end = Math.Min(start + maxWords, words.Length);
            yield return new DocChunk(source, string.Join(' ', words[start..end]));
            if (end == words.Length) break;
        }
    }
}

Each chunk remembers its Source (the file it came from) so we can cite it later. Slide a 120-word window forward 100 words at a time, and you get overlapping chunks that keep their context.

Step 2 — Turn Text Into Vectors (Embeddings)

This is where Ollama earns its keep. We POST a string to /api/embed and get back an array of 768 floats — the embedding.

using System.Net.Http.Json;
using System.Text.Json;

sealed class OllamaClient
{
    private static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web);
    private readonly HttpClient _http = new() { BaseAddress = new Uri("http://localhost:11434") };

    public async Task<float[]> EmbedAsync(string text)
    {
        var request = new { model = "nomic-embed-text", input = text };
        var response = await _http.PostAsJsonAsync("/api/embed", request, Json);
        response.EnsureSuccessStatusCode();

        var body = await response.Content.ReadFromJsonAsync<EmbedResponse>(Json);
        return body!.Embeddings[0];
    }

    private sealed record EmbedResponse(float[][] Embeddings);
}

That's the whole "AI" part of embeddings — one HTTP call. The model reads your text and returns its meaning as 768 numbers. Two chunks about authentication will come back with two very similar arrays.

Step 3 — Store the Vectors in SQLite

Now we save each chunk and its embedding. sqlite-vec gives us a special virtual table that can search vectors natively. We tell it the vectors are 768 floats and that we want cosine distance (more on that in a second). The +source and +chunk columns ride along as plain text so we can read the original text back after a search.

using Microsoft.Data.Sqlite;
using System.Text.Json;

sealed class VectorStore(string path) : IDisposable
{
    private readonly SqliteConnection _connection = new($"Data Source={path}");

    public void Initialize()
    {
        _connection.Open();
        _connection.LoadExtension("vec0"); // loads the sqlite-vec native library

        using var command = _connection.CreateCommand();
        command.CommandText = """
            CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(
                embedding float[768] distance_metric=cosine,
                +source text,
                +chunk text
            );
            """;
        command.ExecuteNonQuery();
    }

    public void Add(DocChunk chunk, float[] embedding)
    {
        using var command = _connection.CreateCommand();
        command.CommandText = """
            INSERT INTO vec_chunks(embedding, source, chunk)
            VALUES ($embedding, $source, $chunk);
            """;
        command.Parameters.AddWithValue("$embedding", JsonSerializer.Serialize(embedding));
        command.Parameters.AddWithValue("$source", chunk.Source);
        command.Parameters.AddWithValue("$chunk", chunk.Text);
        command.ExecuteNonQuery();
    }

    public void Dispose() => _connection.Dispose();
}

We store the embedding as a JSON string like [0.12, -0.04, ...] — sqlite-vec happily parses that.

How does "closest" actually work?

sqlite-vec does the search in fast native code, but there's no mystery inside. "How similar are two vectors?" is answered by cosine similarity, which is a handful of lines of plain C#:

static double CosineSimilarity(float[] a, float[] b)
{
    double dot = 0, magA = 0, magB = 0;
    for (var i = 0; i < a.Length; i++)
    {
        dot  += a[i] * b[i];
        magA += a[i] * a[i];
        magB += b[i] * b[i];
    }
    return dot / (Math.Sqrt(magA) * Math.Sqrt(magB));
}

The result runs from 1.0 (identical meaning) down to 0 (unrelated). sqlite-vec reports the distance — basically 1 - similarity — so smaller is closer. That's why every query below ends with ORDER BY distance. That's the whole "vector search" everyone talks about: a dot product and a square root.

Step 4 — Retrieve the Relevant Chunks

Per question, we embed the question the exact same way, then ask sqlite-vec for the k nearest chunks. The MATCH keyword is sqlite-vec's signal to run a nearest-neighbor search.

sealed record SearchHit(string Source, string Chunk, double Distance);

// (add this method to VectorStore)
public List<SearchHit> Search(float[] queryEmbedding, int k)
{
    using var command = _connection.CreateCommand();
    command.CommandText = """
        SELECT source, chunk, distance
        FROM vec_chunks
        WHERE embedding MATCH $query
        ORDER BY distance
        LIMIT $k;
        """;
    command.Parameters.AddWithValue("$query", JsonSerializer.Serialize(queryEmbedding));
    command.Parameters.AddWithValue("$k", k);

    var hits = new List<SearchHit>();
    using var reader = command.ExecuteReader();
    while (reader.Read())
        hits.Add(new SearchHit(reader.GetString(0), reader.GetString(1), reader.GetDouble(2)));

    return hits;
}

Give it the question's vector, get back the three chunks most likely to contain the answer — ranked from closest to furthest.

Step 5 — Build the Prompt and Generate the Answer

The final step is the payoff. We stitch the retrieved chunks into a prompt with one strict instruction: answer only from this context. Then we send it to the chat model via /api/chat.

// (add this method to OllamaClient)
public async Task<string> ChatAsync(string prompt)
{
    var request = new
    {
        model = "llama3.2",
        messages = new[] { new { role = "user", content = prompt } },
        stream = false
    };
    var response = await _http.PostAsJsonAsync("/api/chat", request, Json);
    response.EnsureSuccessStatusCode();

    var body = await response.Content.ReadFromJsonAsync<ChatResponse>(Json);
    return body!.Message.Content;
}

// nested records inside OllamaClient
private sealed record ChatResponse(ChatMessage Message);
private sealed record ChatMessage(string Role, string Content);

And the prompt that ties it all together:

var context = string.Join("\n\n", hits.Select(h => $"[{h.Source}] {h.Chunk}"));

var prompt = $"""
    Answer the question using ONLY the context below.
    If the answer is not in the context, say "I don't know based on the docs."

    Context:
    {context}

    Question: {question}
    """;

That one instruction — only from this context — is what kills hallucinations. With nothing to lean on, the model won't confidently invent an answer; it'll admit it doesn't know. It's the difference between a student who studied and one improvising in front of the class. And because each chunk carries its [source.md] tag, you can show the user exactly where the answer came from.

The Full Example

Here's the top-level Program.cs. It ships with three tiny "docs" inline so you can run it without any files, but swap SampleDocs.All for a folder of real .md files and nothing else changes. Keep the OllamaClient, VectorStore, Chunker, DocChunk, and SearchHit types from the steps above in the same project (below the top-level code, or in their own files) and it compiles as-is.

using System.Net.Http.Json;
using System.Text.Json;
using Microsoft.Data.Sqlite;

var ollama = new OllamaClient();
using var store = new VectorStore("orbit-docs.db");
store.Initialize();

// --- Step 1 + 2 + 3: ingest the docs (chunk -> embed -> store) ---
foreach (var (source, text) in SampleDocs.All)
    foreach (var chunk in Chunker.Split(source, text))
    {
        var embedding = await ollama.EmbedAsync(chunk.Text);
        store.Add(chunk, embedding);
    }

Console.Write("Ask about the Orbit API: ");
var question = Console.ReadLine() is { Length: > 0 } input ? input : "How do I authenticate?";

// --- Step 4: retrieve ---
var questionEmbedding = await ollama.EmbedAsync(question);
var hits = store.Search(questionEmbedding, k: 3);

// --- Step 5: augment + generate ---
var context = string.Join("\n\n", hits.Select(h => $"[{h.Source}] {h.Chunk}"));
var prompt = $"""
    Answer the question using ONLY the context below.
    If the answer is not in the context, say "I don't know based on the docs."

    Context:
    {context}

    Question: {question}
    """;

var answer = await ollama.ChatAsync(prompt);

Console.WriteLine($"\n{answer}\n");
Console.WriteLine($"Sources: {string.Join(", ", hits.Select(h => h.Source).Distinct())}");

static class SampleDocs
{
    public static readonly Dictionary<string, string> All = new()
    {
        ["auth.md"] = """
            Authentication. The Orbit API uses API keys. Send your key in the
            Authorization header as 'Bearer <key>'. Keys never expire but can be
            revoked from the dashboard. Rate limits are 100 requests per minute.
            """,
        ["webhooks.md"] = """
            Webhooks. Orbit pushes events to your endpoint. Register a webhook URL
            in the dashboard. Every payload is signed with HMAC-SHA256; verify the
            X-Orbit-Signature header before trusting the body. Failed deliveries
            retry 5 times with exponential backoff.
            """,
        ["errors.md"] = """
            Error codes. Orbit returns standard HTTP status codes. A 429 means you
            hit the rate limit, so back off and retry. A 401 means your API key is
            missing or invalid. A 422 means the request body failed validation.
            """
    };
}

Run it, ask "how do I log in?", and even though those exact words appear nowhere in the docs, the embedding for your question lands next to the authentication chunk — and the model answers with the API-key instructions, citing auth.md. That's RAG working.

When to Use RAG — and When Not To

RAG is the right tool when your knowledge is large, private, or changing:

Use RAG for company docs, product manuals, support tickets, a knowledge base — anything the base model never saw and that updates often. New docs? Just embed them. No retraining.
Skip RAG and just paste it into the prompt when the whole knowledge fits comfortably in the context window. If it's two paragraphs, retrieval is overkill.
Reach for fine-tuning instead when you need to change the model's style, tone, or format — not its facts. Fine-tuning teaches behavior; RAG supplies knowledge. They solve different problems, and plenty of real systems use both.

A few honest limitations to keep in mind: your answers are only as good as your chunks, so bad chunking means bad retrieval. Tables and numbers embed poorly (their meaning lives in structure, not prose). And if the answer simply isn't in the docs, a well-instructed RAG system should say so — which is a feature, not a bug.

The rule of thumb: if you'd have to copy-paste a document into the chat to get a good answer, that's a job for RAG.

Key Takeaways

RAG is three steps, not magic — retrieve relevant chunks, augment the prompt, generate the answer. Everything else is detail.
Embeddings turn meaning into geometry — similar text becomes similar vectors, so you can find relevant docs even when the words don't match.
"Vector search" is just cosine similarity — a dot product and a square root; sqlite-vec only makes it fast, not mysterious.
Grounding kills hallucinations — telling the model to answer only from the retrieved context turns confident nonsense into honest "I don't know," and lets you cite sources.
You don't need the cloud — Ollama plus SQLite runs a complete RAG pipeline on your laptop, with zero API keys and zero per-token cost.

Claude Code for .NET Developers: From Zero to Productive in VS Code and Visual Studio

Juan Gómez — Mon, 15 Jun 2026 22:57:25 +0000

Claude Code for .NET Developers: From Zero to Productive in VS Code and Visual Studio

Here is the pattern that plays out constantly with AI coding tools: you try one, it blows your mind. You use it for a week, and it starts feeling random. Sometimes it's brilliant; sometimes it confidently suggests code from three framework versions ago. You stop trusting it, and it fades into the "cool but not practical" category.

The problem is not the model. The problem is that you are using a powerful tool without understanding how it works. Claude Code is different from a chat window, and once you understand its mechanics — how it discovers context, how you shape its behavior, how you extend it with custom commands — it becomes genuinely reliable for .NET work.

This article covers everything: installation, VS Code integration, the honest story about Visual Studio 2022 and 2026, CLAUDE.md (the most important file you are not writing yet), context management, Skills, and MCP. Whether you are new to AI tooling or already use it daily, there is something here for you.

What Is Claude Code, Exactly?

Claude Code is not a chatbot that happens to know about code. It is a CLI-first, agentic coding assistant built by Anthropic. The key distinction: it operates on your actual repository. It can read files, run commands, edit code, and chain multiple steps together without you narrating every move.

The mental model that helps most: Claude Code is a skilled contractor who just walked into your codebase. Give them the right context, and they can work independently. Give them nothing, and they will ask questions — or worse, make assumptions.

There are two surfaces you will use:

The CLI (claude) — runs in any terminal, works with any editor
The VS Code extension (anthropic.claude-code) — embeds the CLI experience directly into VS Code, with file awareness, selection sharing, and inline diffs

Both use the same model and the same context system. The extension is additive convenience on top of the CLI, not a separate product.

Installation and Setup

Prerequisites

You need Node.js 22 LTS or later. Check with:

node --version

Install Claude Code globally:

npm install -g @anthropic-ai/claude-code

Authenticate:

claude

The first run opens a browser for OAuth with your Anthropic account. After that, your credentials are stored locally and the CLI works offline-first (the model calls still go to Anthropic's API, of course).

VS Code Integration

Install the extension from the marketplace. The ID is anthropic.claude-code. You need VS Code 1.98 or later.

Once installed, a Claude icon appears in the activity bar. Open it, sign in, and you have a chat panel that is deeply aware of your open files, your current selection, and your workspace structure. You can also invoke it inline with Ctrl+Shift+C (Windows/Linux) or Cmd+Shift+C (Mac) to open a quick input without leaving your editor flow.

The extension does something important automatically: when you highlight code and ask a question, it attaches that selection as context. You do not have to copy-paste. This alone saves significant friction on large codebases.

If you use JetBrains Rider, there is also full Claude Code integration available through the JetBrains Marketplace. The experience is comparable to VS Code. Rider users are covered — you can follow this entire article and apply it directly.

Visual Studio 2022 and 2026: The Honest Story

Visual Studio has been the king of .NET IDEs for decades — it just has not heard of Claude yet.

As of June 2026, there is no official Claude Code extension for Visual Studio 2022 or 2026. GitHub Copilot has deep VS integration; Claude Code does not. This is not a temporary oversight — the extension model for Visual Studio is substantially different from VS Code, and Anthropic has focused on the VS Code surface.

The workaround is simple and it works well: use the integrated terminal.

Open it with View > Terminal (or Ctrl + backtick). Then run:

claude

Claude Code starts in your repo's root directory. It reads everything — your .cs files, your .csproj, your appsettings.json, your CLAUDE.md. The terminal-based experience is the same CLI you would use anywhere. You lose the inline diff rendering and selection-sharing that the VS Code extension provides, but the model's capabilities are identical.

Practical tip: keep Visual Studio open for debugging, the designer, and refactoring tooling (where it is unmatched), and open VS Code or a terminal alongside it for Claude interactions. Many .NET developers already do this. It is not a compromise — it is using each tool for what it is best at.

CLAUDE.md — The Brain of the Operation

This is the most important section in the article.

Every time Claude Code starts in a directory, it performs a filesystem walk. It moves upward from the current working directory, looking for CLAUDE.md files. It also lazily loads CLAUDE.md files found in subdirectories as it encounters them during work. The result is a layered context system: a root CLAUDE.md for the whole repo, and optionally per-project or per-module files for specific concerns.

CLAUDE.md is not magic. It is just a Markdown file. But it is the file Claude reads before doing anything else. Think of it as your onboarding document for a contractor who starts fresh every session.

What Claude Does NOT Know Without CLAUDE.md

Without any instruction file, Claude Code will:

Guess your build system from file structure
Assume generic conventions
Ask clarifying questions repeatedly
Make mistakes that a three-minute onboarding would prevent

With a good CLAUDE.md, Claude knows your exact dotnet commands, your test runner, your architecture decisions, your naming conventions, and any constraints specific to your project. It stops guessing and starts working.

Discovery in Visual Studio: A Common Gotcha

CLAUDE.md lives at the root of your repository — the same directory as your .sln file. Visual Studio's Solution Explorer shows files based on what is referenced in .csproj or .sln files. Since CLAUDE.md is not referenced by either, it will not appear in Solution Explorer.

This trips people up. They create the file, it does not show up in VS, they assume something is wrong. Nothing is wrong. Claude loads it perfectly. Open it directly in VS Code or a plain text editor to edit it.

To verify what Claude has loaded, run:

/memory

This lists all context files currently active in the session. If CLAUDE.md is loaded, it appears here. This is your ground truth.

A Practical CLAUDE.md for a .NET Project

Here is an example for a realistic ASP.NET Core project:

# OrderService

ASP.NET Core 10 minimal API backed by PostgreSQL via EF Core 10.
Authentication: JWT with ASP.NET Core Identity.
Deployed to Azure Container Apps via GitHub Actions.

## Build

```bash
dotnet build OrderService.sln
```

## Tests

```bash
# Run all tests
dotnet test OrderService.sln

# Run only unit tests
dotnet test tests/OrderService.UnitTests/

# Run with coverage
dotnet test OrderService.sln --collect:"XPlat Code Coverage"
```

## Architecture

- `src/OrderService.Api/` — minimal API endpoints, no business logic here
- `src/OrderService.Domain/` — domain models, value objects, interfaces
- `src/OrderService.Application/` — CQRS handlers (MediatR), validators (FluentValidation)
- `src/OrderService.Infrastructure/` — EF Core, repositories, external HTTP clients
- `tests/OrderService.UnitTests/` — xUnit, Moq, domain and application layer only
- `tests/OrderService.IntegrationTests/` — xUnit, Testcontainers, full API stack

## Conventions

- Use `record` types for immutable domain models and DTOs
- Use C# 14 `field` keyword instead of explicit backing fields where applicable
- All nullable reference types enabled; annotate accordingly
- No `var` — use explicit types everywhere
- Async all the way down; no `.Result` or `.Wait()`
- Repository interfaces in Domain layer; implementations in Infrastructure
- Endpoint classes in `Features/` folders grouped by domain concept (vertical slice)

## EF Core

- Migrations in `src/OrderService.Infrastructure/Migrations/`
- Add migration: `dotnet ef migrations add <Name> --project src/OrderService.Infrastructure --startup-project src/OrderService.Api`
- Apply: `dotnet ef database update --project src/OrderService.Infrastructure --startup-project src/OrderService.Api`

## Do Not

- Do not add business logic to endpoint handlers
- Do not use `dynamic` or `object` as return types
- Do not skip FluentValidation for command/query inputs
- Do not add new NuGet packages without noting them here

This file takes about fifteen minutes to write and saves hours of back-and-forth over the lifetime of a project. The investment is obvious once you have it.

Generating a Starter CLAUDE.md

If you are not starting from scratch, Claude Code can inspect your repo and generate a first draft:

/init

This reads your solution structure, existing documentation, and common patterns, then writes a CLAUDE.md that reflects what it found. Treat the output as a starting point — review it, correct anything wrong, and add the domain knowledge Claude cannot infer (architecture decisions, team conventions, known pitfalls).

Giving Claude Context

Even with a great CLAUDE.md, you will often need to point Claude at specific files during a conversation. The @ mention syntax does this precisely.

File and Directory Mentions

@Program.cs

Attaches the full content of Program.cs to the current message.

@src/OrderService.Application/

Attaches a directory listing. Claude will then read specific files from it as needed, rather than loading everything upfront.

@appsettings.json#1-20

Attaches only lines 1 through 20. Useful when you care about a specific section of a large config file and do not want to burn context on the rest.

VS Code Selection Sharing

When you use the VS Code extension, any code you highlight in the editor is automatically shared when you open the Claude panel. You do not need @ mentions for your active selection — it is already there. This makes "explain this method" or "what does this LINQ query do" workflows completely frictionless.

Managing Long Contexts

Long sessions accumulate context. After several hours of work, Claude's context window fills with earlier conversation turns that are no longer relevant. When responses start feeling less sharp, run:

/compact

This summarizes the conversation history into a compressed form, freeing up context space without losing the thread of what you have been working on. Think of it as telling the contractor to forget the small talk and remember only the decisions.

Skills — Custom Commands for Your Workflow

Skills are reusable, invocable commands that extend Claude Code's default behavior. They live as Markdown files and you invoke them with a / prefix, just like built-in commands. There are two scopes:

Personal skills — stored in ~/.claude/skills/<skill-name>/SKILL.md. Available in every project on your machine.
Project skills — stored in .claude/skills/<skill-name>/SKILL.md in your repo root. Checked into source control, shared with the team.

A skill file is a Markdown document that tells Claude what to do when invoked. It can include steps, decision logic, expected outputs, and even inline prompts.

Here are three practical examples for .NET development.

Skill: `/dotnet-test`

File: .claude/skills/dotnet-test/SKILL.md

# dotnet-test

Run the test suite for this project and summarize the results.

## Steps

1. Run `dotnet test` using the command from CLAUDE.md (check the "Tests" section).
2. Parse the output for failed tests.
3. For each failure:
   - Show the test name
   - Show the failure message
   - Show the stack trace trimmed to the first 5 lines
4. If all tests pass, confirm with a short success message.
5. If build errors prevent tests from running, show the build errors instead.

## Output Format

Group failures by project. Keep the summary concise — one paragraph max,
followed by a numbered list of failures if any exist.

Invoke with /dotnet-test. Claude runs your test command, reads the output, and gives you a clean summary instead of a wall of terminal text.

Skill: `/csharp-review`

File: .claude/skills/csharp-review/SKILL.md

# csharp-review

Review the provided C# code for modern idiom usage and correctness.

## What to Check

- **Records**: Are mutable classes used where `record` or `record struct` would be more appropriate?
- **Init-only properties**: Are setters used where `init` would suffice?
- **Pattern matching**: Are `if`/`switch` chains that could use `switch` expressions or positional patterns?
- **Nullable annotations**: Are reference types properly annotated? Any `!` suppressors hiding problems?
- **Primary constructors**: Could a class use C# 12+ primary constructor syntax?
- **`field` keyword**: Are there explicit backing fields that C# 14's `field` keyword could eliminate?
- **Async**: Any `.Result`, `.Wait()`, or `async void` outside of event handlers?
- **LINQ**: Any imperative loops that would read more clearly as LINQ?

## Output Format

List each finding as:
- **[Category]** Description of the issue
- Suggested rewrite (code block, 10 lines max)

End with a one-sentence overall assessment.

Invoke with /csharp-review while a file is open (or with @filename if using the CLI). You get actionable, .NET-specific feedback rather than generic suggestions.

Skill: `/ef-migrate`

File: .claude/skills/ef-migrate/SKILL.md

# ef-migrate

Guide through EF Core migration management for this project.

## Steps

1. Run the `dotnet ef migrations list` command from CLAUDE.md to show existing migrations.
   Use the correct `--project` and `--startup-project` flags from CLAUDE.md.
2. Show the migration list, noting which have been applied (indicated by [applied]).
3. Ask the user: "Do you want to add a new migration, or apply pending ones?"
4. If adding a migration:
   - Ask for the migration name (PascalCase, descriptive, e.g., AddOrderStatusIndex)
   - Run `dotnet ef migrations add <Name>` with correct flags
   - Show which files were created
   - Ask if they want to review the generated migration before applying
5. If applying pending migrations:
   - Confirm the number of pending migrations
   - Run `dotnet ef database update` with correct flags
   - Report success or errors

## Safety Note

Always mention that migrations modify the database schema. Remind the user to review
generated migrations before applying to staging or production environments.

This skill turns what is normally a multi-step, flag-heavy CLI workflow into a guided conversation. It uses the migration commands already defined in your CLAUDE.md, so it adapts to each project automatically.

MCP — Connecting External Tools

Model Context Protocol (MCP) is a standard that lets Claude connect to external data sources and tools beyond your local filesystem. Where Skills extend what Claude does, MCP extends what Claude can see.

A few examples relevant to .NET teams:

GitHub MCP — Claude can read PR diffs, check CI status, and leave review comments directly, without you copy-pasting GitHub URLs into the chat
Azure DevOps MCP — Claude can read your current sprint, query work items, and understand the backlog when you ask it to help prioritize or plan
Database MCP — Claude can query your local or dev database schema to inform code generation, without you having to paste CREATE TABLE statements

MCP servers are configured in your Claude Code settings and are available across all sessions. For .NET teams working in Azure DevOps or GitHub, setting up the corresponding MCP server once pays dividends on every PR review and sprint planning task after that.

VS Code vs Visual Studio: An Honest Comparison

Both IDEs are legitimate for .NET work. Here is where each one stands with Claude Code:

Feature	VS Code + Claude Extension	Visual Studio 2022/2026 + Terminal
Claude Code integration	Native extension, inline diffs, selection sharing	Terminal only, CLI-based
Debugging experience	Good (but not VS-level)	Best in class for .NET
CLAUDE.md support	Full	Full (file not shown in Solution Explorer)
Skills / MCP	Full	Full (terminal invocation)
Designer tools (WinForms, WPF)	Limited	Full
Refactoring tools	Good	Excellent (ReSharper-level built-in)
Hot Reload / Edit and Continue	Good	Best in class
Extension ecosystem	Vast	.NET-focused, deep OS integration
Cost	Free	Community free; Pro/Enterprise paid

The pragmatic answer for most .NET developers: use both. VS Code for AI-assisted coding, exploration, and file editing; Visual Studio for debugging sessions, UI designers, and deep refactoring. They open the same project files and there is no conflict. Many developers keep both open simultaneously without issue.

If you have to pick one: pure backend services (ASP.NET Core APIs, worker services, console apps) work well with VS Code as your primary. Anything with Windows Forms, WPF, or complex debugger needs warrants Visual Studio as primary with Claude Code in the terminal.

Key Takeaways

CLAUDE.md is not optional — it is the difference between an AI that guesses and one that knows your codebase. Write it, commit it, keep it current. Run /init to generate a starting point from your existing repo.
Visual Studio is fully usable — the lack of a native extension is a real limitation, but View > Terminal and the claude CLI give you full Claude Code functionality. The file-awareness and Skills system work identically.
Context is everything — use @ mentions to target specific files, use line ranges to stay precise, and use /compact when sessions get long. Precision in context leads to precision in output.
Skills are multipliers — a fifteen-minute investment writing a project skill pays back immediately. Codify your team's review criteria, your test workflow, your migration process. Claude Code executes them consistently every time.
The model is not random — your context is — when Claude gives you a bad answer, the fix is almost always better context: a clearer CLAUDE.md, a more specific @ mention, or a well-written skill. Understanding the context system turns a frustrating tool into a reliable one.

The architecture is simple once you see it: CLAUDE.md tells Claude who you are and how your project works, @ mentions tell Claude what to look at right now, and Skills tell Claude how to handle your recurring tasks. Stack those three things on top of a capable model and the "random magic" feeling goes away entirely. What you get instead is a coding assistant that behaves like someone who has actually read the codebase.

Which, thanks to CLAUDE.md, it has.

Claude Code para desarrolladores .NET: De cero a productivo en VS Code y Visual Studio

Juan Gómez — Mon, 15 Jun 2026 22:57:12 +0000

Claude Code para desarrolladores .NET: De cero a productivo en VS Code y Visual Studio

Las herramientas de IA se sienten mágicas los primeros días. Le preguntas algo, te responde bien, y piensas: "esto va a cambiar todo". Luego pasan unas semanas, el contexto se confunde, las respuestas se vuelven genéricas, y empiezas a sentir que estás teniendo una conversación con alguien que tiene amnesia selectiva.

El problema no es la IA. El problema es que nadie te explicó cómo funciona realmente.

Este artículo desmitifica Claude Code para desarrolladores .NET. No es un tutorial de "mira qué cool es esto" — es una guía práctica de cómo funciona, por qué funciona así, y cómo sacarle el máximo provecho en proyectos C# reales, tanto en VS Code como en Visual Studio 2022/2026.

Qué es Claude Code (y qué no es)

Claude Code no es una ventana de chat glorificada. Es una CLI (interfaz de línea de comandos) que corre directamente en tu terminal y tiene acceso real a tu sistema de archivos, puede ejecutar comandos, leer y editar archivos, y mantener contexto sobre tu proyecto.

La diferencia con "preguntarle a Claude en el navegador" es enorme:

En el navegador, pegas código manualmente, pierdes contexto entre sesiones, y Claude no sabe nada de tu proyecto más allá de lo que tú le dices.
Con Claude Code, Claude vive en tu repositorio. Lee archivos, ejecuta dotnet build, corre tus tests, y entiende la arquitectura de tu solución.

Además de la CLI, existe una extensión para VS Code que integra Claude Code directamente en el editor — con contexto automático de lo que tienes abierto y seleccionado. Para Visual Studio, la historia es diferente (y la contaremos honestamente más adelante).

Instalación y setup

Prerrequisitos

Node.js 22 LTS o superior
Una cuenta en claude.ai con acceso a Claude Code

Instalar la CLI

npm install -g @anthropic-ai/claude-code

Verifica la instalación:

claude --version

Para iniciar una sesión interactiva en tu proyecto, navega al directorio raíz y ejecuta:

claude

VS Code — integración completa

Instala la extensión oficial desde el Marketplace:

Nombre: Claude Code
ID: anthropic.claude-code
Requiere VS Code 1.98 o superior

Una vez instalada, Claude Code aparece en la barra lateral. La integración es profunda: cuando tienes un archivo abierto o código seleccionado, Claude lo recibe automáticamente como contexto. No necesitas copiar y pegar nada.

JetBrains Rider también cuenta con integración completa a través de su plugin oficial — si tu equipo usa Rider, el workflow es muy similar al de VS Code.

Visual Studio 2022/2026 — la verdad sin rodeos

Visual Studio ha sido el rey del desarrollo .NET por décadas. Simplemente aún no se ha enterado de que existe Claude.

A junio de 2026, no existe una extensión oficial de Claude Code para Visual Studio. Punto. No hay workaround mágico que cambie eso.

Lo que sí funciona, y funciona bien, es usar la terminal integrada de Visual Studio:

Ve a Ver > Terminal (o Ctrl + backtick)
Navega al directorio raíz de tu solución (normalmente ya estás ahí)
Ejecuta claude

Claude lee tu repositorio exactamente igual que en VS Code. La diferencia es que no tienes el contexto visual automático — tendrás que mencionar archivos explícitamente con @ (lo veremos en detalle más adelante). Para muchas tareas de refactoring, generación de código y revisión de arquitectura, la terminal es más que suficiente.

Muchos desarrolladores .NET tienen ambos IDEs abiertos en paralelo: Visual Studio para debugging avanzado, diseñadores de formularios, y herramientas de profiling; VS Code para trabajar con Claude Code.

CLAUDE.md — el cerebro de la operación

Aquí está el insight más importante del artículo, así que léelo despacio.

Claude Code no funciona como un chatbot con memoria persistente. Cada vez que inicias una sesión, parte de cero. Entonces, ¿cómo "conoce" tu proyecto? A través de un archivo llamado CLAUDE.md.

Cómo Claude descubre CLAUDE.md

Cuando ejecutas claude desde un directorio, Claude realiza un recorrido del filesystem hacia arriba desde tu directorio de trabajo actual (CWD), buscando archivos CLAUDE.md. Además, carga CLAUDE.md de los subdirectorios de forma lazy a medida que accede a ellos.

Esto significa dos cosas importantes:

No está basado en archivos de proyecto — Claude no lee tu .csproj para descubrir CLAUDE.md. Lo descubre por ubicación en el filesystem. Si tu CLAUDE.md está en la raíz del repo y ejecutas claude desde ahí, se carga. Si lo ejecutas desde un subdirectorio, también lo cargará (porque sube hacia arriba).
En Visual Studio, CLAUDE.md no aparece en el Explorador de Soluciones — porque no está referenciado en ningún .csproj. Pero Claude sí lo carga. No necesitas agregarlo al proyecto. De hecho, es mejor que no lo hagas — es un archivo de contexto para la IA, no un recurso de tu aplicación.

Verificar qué está cargado

Puedes verificar en cualquier momento qué archivos CLAUDE.md tiene cargados Claude con el comando:

/memory

Esto muestra el contenido actual de memoria, incluyendo todos los CLAUDE.md activos en la sesión.

Generar un CLAUDE.md inicial

Si tu proyecto no tiene CLAUDE.md, Claude puede generarlo leyendo el repo:

/init

Esto analiza tu código, estructura de carpetas, y archivos de configuración, y produce un CLAUDE.md base que puedes refinar.

Ejemplo práctico: CLAUDE.md para un proyecto .NET

Aquí un ejemplo completo y realista para una API de e-commerce en .NET 10:

# ECommerceApi — Contexto para Claude Code

## Descripción del proyecto
API REST para gestión de catálogo y órdenes de compra.
Stack: .NET 10, C# 14, Entity Framework Core 9, PostgreSQL, MassTransit (RabbitMQ).
Arquitectura: Clean Architecture con CQRS via MediatR.

## Comandos esenciales

### Build y tests
dotnet build ECommerceApi.sln
dotnet test ECommerceApi.sln --logger "console;verbosity=normal"
dotnet test --filter "Category=Unit"
dotnet test --filter "Category=Integration"

### Migraciones EF Core
cd src/ECommerceApi.Infrastructure
dotnet ef migrations add <NombreMigracion> --startup-project ../ECommerceApi.Api
dotnet ef database update --startup-project ../ECommerceApi.Api

### Ejecución local
cd src/ECommerceApi.Api
dotnet run

## Estructura del proyecto
src/
  ECommerceApi.Api/           # Controllers, middleware, DI setup
  ECommerceApi.Application/   # Commands, queries, DTOs, validators
  ECommerceApi.Domain/        # Entities, value objects, domain events
  ECommerceApi.Infrastructure/ # EF Core, repositories, external services
tests/
  ECommerceApi.UnitTests/
  ECommerceApi.IntegrationTests/

## Convenciones de código
- Usa records para DTOs y value objects
- Usa init-only properties en domain entities cuando sea posible
- Pattern matching exhaustivo en switches sobre discriminated unions
- Nullable reference types habilitados — sin supresiones con !
- No uses var — tipado explícito siempre
- Nombres en inglés para código, comentarios pueden ser en español

## Decisiones de arquitectura importantes
- Los controllers SOLO llaman a MediatR.Send() — lógica cero en controllers
- Validaciones con FluentValidation en el pipeline de MediatR (no en controllers)
- Los domain events se despachan DESPUÉS de SaveChanges (outbox pattern)
- Los integration tests levantan PostgreSQL en Docker via Testcontainers

## Lo que NO hacer
- No agregar lógica de negocio en Infrastructure
- No inyectar DbContext directamente en Application — solo via repositorios
- No usar AutoMapper — mappings explícitos con métodos ToDto() / ToDomain()

Este archivo transforma a Claude de "asistente genérico de C#" a "colega que conoce tu proyecto". La diferencia en calidad de respuestas es notable.

Dando contexto a Claude

Tener un buen CLAUDE.md es el 50% del trabajo. El otro 50% es saber cómo dar contexto durante la sesión.

Menciones con @

La sintaxis @ te permite referenciar archivos y directorios específicos:

@Program.cs                    # Archivo completo
@src/Application/              # Directorio entero
@appsettings.json#1-20         # Líneas 1 a 20 del archivo
@src/Domain/Entities/Order.cs  # Archivo en ruta relativa

Ejemplos de uso en conversación:

Revisa @src/Application/Orders/Commands/CreateOrderCommand.cs
y dime si hay algo que mejorar con los nuevos features de C# 14.

Tengo un bug en @src/Infrastructure/Repositories/OrderRepository.cs#45-80.
El método GetPendingOrders() devuelve órdenes canceladas. ¿Ves el problema?

Contexto automático en VS Code

En VS Code con la extensión instalada, el archivo que tienes abierto en el editor activo se comparte automáticamente como contexto. Si seleccionas un bloque de código, solo ese bloque se incluye. Esto elimina mucho del trabajo manual de menciones @.

En Visual Studio (terminal), necesitas ser explícito con @ — lo cual en realidad te obliga a ser más preciso sobre qué quieres mostrarle a Claude, lo cual no es necesariamente malo.

Gestionar el contexto largo con /compact

Las sesiones largas tienen un límite de tokens. Cuando el contexto se alarga demasiado, Claude puede empezar a "olvidar" cosas del inicio de la conversación.

El comando /compact resume el historial de la sesión actual, preservando los puntos clave pero reduciendo el tamaño del contexto:

/compact

Úsalo proactivamente cuando llevas un rato en la misma sesión, antes de llegar al límite. Es como hacer un checkpoint.

Skills — comandos personalizados para tu flujo

Los Skills son la característica más poderosa de Claude Code para equipos y proyectos recurrentes. Un Skill es esencialmente un comando personalizado que encapsula un flujo de trabajo completo.

Dónde viven los Skills

Hay dos ubicaciones:

Ubicación	Alcance	Ruta
Personal	Solo tú, todos tus proyectos	`~/.claude/skills/<nombre>/SKILL.md`
Proyecto	Todo el equipo, este repo	`.claude/skills/<nombre>/SKILL.md`

Los Skills de proyecto se versiona junto al código — cuando alguien hace git clone, obtiene los Skills también. Ideal para workflows específicos del equipo.

Cómo invocar un Skill

Simplemente escribe /nombre-del-skill en Claude Code:

/dotnet-test
/csharp-review
/ef-migrate

Claude lee el archivo SKILL.md correspondiente y ejecuta el flujo definido en él.

Ejemplo 1: `/dotnet-test`

Crea el archivo .claude/skills/dotnet-test/SKILL.md:

# dotnet-test

Ejecuta la suite de tests del proyecto y presenta los resultados de forma clara.

## Pasos

1. Ejecuta `dotnet test ECommerceApi.sln --logger "console;verbosity=normal"`
2. Si hay fallos, muestra SOLO los tests fallidos con:
   - Nombre completo del test
   - El mensaje de error
   - La línea del código donde falló
3. Si todos pasan, confirma con un resumen: total de tests, tiempo de ejecución
4. Si hay errores de compilación, muéstralos primero antes de hablar de tests

## Notas
- No muestres los tests que pasaron a menos que el usuario lo pida
- Si el build falla, no intentes interpretar qué tests fallaron

Ejemplo 2: `/csharp-review`

Crea .claude/skills/csharp-review/SKILL.md:

# csharp-review

Revisa código C# buscando oportunidades de modernización con C# 14 / .NET 10.

## Qué revisar

### Records y tipos de valor
- ¿Se puede reemplazar una clase inmutable con un record?
- ¿Los DTOs usan record en vez de class?
- ¿Se usan init-only properties donde corresponde?

### Pattern matching
- ¿Hay cadenas de if/else que se pueden reemplazar con switch expressions?
- ¿Los switches son exhaustivos sobre discriminated unions?
- ¿Se usa list patterns donde aplica?

### Nullable reference types
- ¿Hay supresiones con ! sin justificación?
- ¿Los parámetros nullable están correctamente anotados?

### field keyword (C# 14)
- ¿Hay propiedades con backing fields explícitos que se pueden simplificar con field?

### Async/await
- ¿Hay .Result o .Wait() que deberían ser await?
- ¿Se usa ConfigureAwait correctamente en librerías?

## Formato de respuesta
Para cada issue encontrado:
- Código original
- Código mejorado
- Una línea explicando por qué es mejor

No reportes lo que ya está bien — solo oportunidades de mejora.

Ejemplo 3: `/ef-migrate`

Crea .claude/skills/ef-migrate/SKILL.md:

# ef-migrate

Guía para agregar una migración de Entity Framework Core al proyecto.

## Pasos

1. Ejecuta `dotnet ef migrations list --project src/ECommerceApi.Infrastructure --startup-project src/ECommerceApi.Api`
   para mostrar las migraciones existentes

2. Pregunta al usuario:
   - ¿Qué cambio hiciste en el modelo de dominio?
   - ¿Qué nombre quieres para la migración? (sugerencia: usa PascalCase descriptivo, ej: AddOrderShippingAddress)

3. Ejecuta:
   `dotnet ef migrations add <NombreMigracion> --project src/ECommerceApi.Infrastructure --startup-project src/ECommerceApi.Api`

4. Lee el archivo de migración generado y verifica:
   - Que el Up() tiene el cambio esperado
   - Que el Down() revierte correctamente
   - Que no hay columnas `nvarchar(max)` donde debería haber un tamaño específico

5. Si el usuario quiere aplicar la migración:
   `dotnet ef database update --project src/ECommerceApi.Infrastructure --startup-project src/ECommerceApi.Api`

## Notas
- Nunca ejecutes database update en producción desde aquí — solo desarrollo local
- Si hay conflictos de migración, muestra el error completo antes de sugerir soluciones

Estos tres Skills solos ya justifican el setup. Imagina tener un equipo de 10 personas donde todos invocan /csharp-review y obtienen el mismo estándar de revisión.

MCP — conectando herramientas externas

MCP (Model Context Protocol) es el mecanismo que permite a Claude Code conectarse con servicios externos como si fueran herramientas nativas.

En términos simples: un servidor MCP expone capacidades (leer PRs, consultar tickets, buscar documentación) y Claude puede usarlas durante la sesión.

Dos ejemplos relevantes para equipos .NET:

GitHub MCP — Claude puede leer los PRs abiertos del repo, ver los comentarios de revisión, y ayudarte a resolverlos sin que copies nada manualmente:

¿Qué cambios pendientes tengo en el PR #247?

Azure DevOps MCP — Claude puede ver el contexto del sprint actual, las user stories asignadas, y entender qué estás construyendo sin que tengas que explicarlo:

¿Cuáles son los criterios de aceptación de la historia US-1089?

Los servidores MCP se configuran en ~/.claude/mcp.json o .claude/mcp.json a nivel de proyecto. La documentación oficial de Claude Code tiene la lista de servidores MCP disponibles y cómo configurarlos.

Cuándo usar VS Code vs Visual Studio

La pregunta que todo desarrollador .NET acaba haciendo. La respuesta honesta:

Criterio	VS Code + Claude Code	Visual Studio 2022/2026
Integración con Claude Code	Completa — contexto automático, extensión nativa	Funcional — terminal integrada, sin extensión
Debugging de aplicaciones .NET	Bueno (con extensión C#)	Excelente — el mejor de la industria
IntelliSense y refactoring	Bueno	Excepcional — Roslyn completo
Diseñadores visuales (WinForms, WPF, MAUI)	No disponible	Completos
Profiling y diagnósticos	Limitado	Herramientas de clase mundial
Startup y rendimiento del IDE	Rápido	Lento en proyectos grandes
Desarrollo multiplataforma	Ideal	Limitado
Trabajo con soluciones grandes (50+ proyectos)	Puede ser lento	Optimizado
Skills y workflows de equipo	Integración nativa	Via terminal

Recomendación práctica: No elijas uno. Úsalos en paralelo.

Visual Studio sigue siendo insustituible para debugging pesado, profiling de memoria, y diseñadores de UI de escritorio. VS Code con Claude Code es donde vas a escribir código más rápido, refactorizar más limpio, y entender más fácil código ajeno.

Muchos equipos .NET han adoptado el siguiente flujo: VS Code para el día a día con Claude Code activo, Visual Studio cuando necesitan el debugger avanzado o las herramientas de diagnóstico. Los dos conviven perfectamente apuntando al mismo proyecto.

Puntos clave

CLAUDE.md es tu punto de partida — sin él, Claude no conoce tu proyecto. Con él, se convierte en un colaborador que entiende tu arquitectura, tus convenciones y tus decisiones técnicas. Ejecuta /init para generarlo y refínalo con el tiempo.
La integración de VS Code es completa; Visual Studio usa la terminal — en VS Code, la extensión anthropic.claude-code (requiere 1.98+) te da contexto automático. En Visual Studio, usa Ver > Terminal y corre claude ahí. Funciona igual de bien para la mayoría de tareas.
Las menciones @ son tu herramienta de precisión — @archivo.cs, @directorio/, y @archivo.cs#10-40 te permiten dar a Claude exactamente el contexto que necesita. En VS Code, el archivo activo se comparte automáticamente; en Visual Studio, sé explícito.
Los Skills son tu ventaja de equipo — crea Skills en .claude/skills/ y versiónalos junto al código. Un /csharp-review consistente para todo el equipo es más valioso que cualquier guideline de código que nadie lee.
Gestiona el contexto activamente — usa /compact antes de que se alargue demasiado la sesión, y usa /memory para verificar qué CLAUDE.md tiene cargado. Entender cómo Claude descubre el contexto (recorrido del filesystem, no archivos de proyecto) elimina mucha confusión.

Claude Code no reemplaza tu conocimiento de .NET — lo amplifica. La diferencia entre usarlo mediocremente y usarlo bien está en esas tres cosas: un buen CLAUDE.md, contexto preciso con @, y Skills que encapsulan tu flujo de trabajo. Con eso, la magia deja de parecer aleatoria.

C# 14: The `field` Keyword — Cleaner Properties, Zero Boilerplate

Juan Gómez — Wed, 10 Jun 2026 21:20:58 +0000

C# 14: The `field` Keyword — Cleaner Properties, Zero Boilerplate

Every C# developer has been there. You start with a clean auto-property, then requirements change and you need to add a tiny bit of validation. Suddenly that one-liner explodes into six lines of boilerplate — a private backing field, a getter that just returns it, a setter that assigns it. The logic is two words. The ceremony is everything else.

C# 14 fixes this with the field keyword: a contextual keyword that refers to the compiler-synthesized backing field of a property, letting you write custom accessor logic without ever declaring an explicit field.

The Problem: Boilerplate Tax on Simple Properties

Auto-properties are one of C#'s best quality-of-life features. This is clean:

public string Username { get; set; }

But the moment you need to trim whitespace on assignment, that cleanness evaporates:

private string _username = string.Empty;

public string Username
{
    get => _username;
    set => _username = value.Trim();
}

You now have six lines — and four of them exist only to hold the shape of the pattern together. The backing field _username is not carrying any meaningful design weight. Its only job is to be a storage slot that Username uses privately. You already know the compiler creates one for auto-properties. You are just forced to make it visible so you can reference it.

This is the boilerplate tax. You pay it every time you add even the smallest piece of logic to a property.

Why `field` Exists

The C# language team has discussed this friction for years. The challenge was finding syntax that is:

Unambiguous — no conflict with existing identifiers
Familiar — consistent with how value works in setters
Scoped — only meaningful inside a property accessor

The solution landed in C# 14: the contextual keyword field. Just like value refers to the incoming assignment in a setter, field refers to the hidden backing storage the compiler manages for the property.

It is contextual, which means it only acts as a keyword inside a property accessor. Everywhere else in your code, field is still a valid identifier name (with one gotcha covered later).

How It Works

Basic Syntax

Here is the same username property rewritten with field:

public string Username
{
    get;
    set => field = value.Trim();
}

The get accessor is still auto-implemented — it just returns field. The set accessor does its one job: trim the incoming value before storing it. The private backing field is gone. The compiler synthesizes it behind the scenes, and field lets you reach into it.

You can also go the other way — implement get and auto-implement set:

public string DisplayName
{
    get => field.ToUpperInvariant();
    set;
}

Or implement both sides:

public int Age
{
    get => field;
    set => field = value >= 0 ? value : throw new ArgumentOutOfRangeException(nameof(value), "Age cannot be negative.");
}

Works with `init` Too

init-only properties work exactly the same way:

public string Email
{
    get;
    init => field = value.Trim().ToLowerInvariant();
}

This is especially useful in immutable record-style classes where you want normalization on construction but no mutation afterwards.

Real-World Usage Patterns

1. Input Normalization

The most common use case. Trim strings, normalize casing, sanitize user input — all without a backing field:

namespace Blog.Models;

public sealed class UserProfile
{
    public string Username
    {
        get;
        set => field = value.Trim();
    }

    public string Email
    {
        get;
        set => field = value.Trim().ToLowerInvariant();
    }

    public string? DisplayName
    {
        get;
        set => field = string.IsNullOrWhiteSpace(value) ? null : value.Trim();
    }
}

All three properties look almost as clean as auto-properties, and each enforces its own invariant at the point of assignment.

2. Range Validation

Numeric properties that must stay within bounds are a perfect fit:

namespace Blog.Models;

public sealed class ProductListing
{
    private const decimal MaxPrice = 99_999.99m;

    public string Title
    {
        get;
        set => field = value.Trim();
    }

    public decimal Price
    {
        get;
        set
        {
            ArgumentOutOfRangeException.ThrowIfNegative(value);
            ArgumentOutOfRangeException.ThrowIfGreaterThan(value, MaxPrice);
            field = value;
        }
    }

    public int StockQuantity
    {
        get;
        set => field = int.Max(0, value); // Quietly clamp negatives — intentional product decision
    }
}

Notice ArgumentOutOfRangeException.ThrowIfNegative and ThrowIfGreaterThan — those are .NET 8+ helpers that are cleaner than manual if throws. Use the modern APIs.

3. Lazy Initialization

field shines for lazy-loaded properties. The classic pattern used to need a nullable backing field and a null-check dance:

// Before C# 14 — the old dance
private List<string>? _tags;
public List<string> Tags => _tags ??= [];

With field, you write the same logic right inside the property:

public List<string> Tags => field ??= [];

One line. The compiler owns the backing field. You own the logic.

4. Change Notification (INotifyPropertyChanged)

ViewModel properties in MVVM apps often look like this:

namespace Blog.ViewModels;

public sealed class OrderViewModel : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler? PropertyChanged;

    public string CustomerName
    {
        get;
        set
        {
            if (field == value) return;
            field = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(CustomerName)));
        }
    }

    public decimal Total
    {
        get;
        set
        {
            if (field == value) return;
            field = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Total)));
        }
    }
}

No private fields. No name collision risks. The pattern is still verbose (that is just the nature of INotifyPropertyChanged), but field removes one moving part from it.

The `field` Gotcha: When Your Property Is Named `field`

Here is where things get interesting. Because field is a contextual keyword, a property actually named Field (or field in a case-sensitive context) can shadow the keyword. Consider this:

public sealed class DatabaseRecord
{
    // This property is named "field" — uncommon, but legal
    public string field
    {
        get;
        // Inside here, does "field" mean the keyword or the property itself?
        set => field = value.Trim(); // Ambiguous!
    }
}

The compiler will warn you about the ambiguity. The fix is the verbatim identifier @field, which forces C# to treat it as an identifier, not the keyword:

public sealed class DatabaseRecord
{
    public string @field
    {
        get;
        set => @field = value.Trim(); // Explicit: this is the identifier, not the keyword
    }
}

Realistically, naming a property field is unusual. But if you work with code that maps to external schemas or databases that use reserved names, now you know the escape hatch.

When to Use `field`

Use field whenever you need some logic in a property accessor but the property is still the sole owner of its value:

Normalization on assignment — trimming, casing, formatting
Validation on assignment — range checks, null guards, format checks
Lazy initialization — compute-on-first-access patterns
Simple change tracking — equality check before raising events
init-only normalization — immutable objects that need clean input

The rule of thumb: if you would previously have written a private backing field that nothing else in the class references, replace it with field.

When NOT to Use `field`

field is not a silver bullet. There are cases where an explicit backing field is still the right tool:

The constructor bypass problem

Suppose you have a property that raises an event when assigned. You want the constructor to set the initial value silently, without firing the event. With field, you cannot do that — the only way into the backing storage is through the property accessor.

public sealed class Sensor
{
    // The event fires on every set — we want to skip it in the constructor
    public double Temperature
    {
        get;
        set
        {
            field = value;
            ReadingChanged?.Invoke(this, EventArgs.Empty);
        }
    }

    public event EventHandler? ReadingChanged;

    public Sensor(double initialTemperature)
    {
        // This fires ReadingChanged during construction — probably not what you want
        Temperature = initialTemperature;
    }
}

If you need the constructor to bypass the property's logic, keep the explicit backing field and set it directly from the constructor.

Multiple properties sharing state

If two or more properties read from or write to the same underlying value — for example a Radius and a Diameter that are computed from each other — you need an explicit field that both properties reference. field is per-property; it cannot be shared.

Complex derived state

If the "backing storage" is not a simple value but involves multiple fields, caches, or objects, an explicit field with a descriptive name communicates intent far better than the anonymous field keyword.

When a name is important for debugging

Explicit backing fields appear in debuggers with their declared name. The compiler-synthesized backing field for field-based properties gets a generated name (like <Username>k__BackingField) that is less readable in memory dumps or diagnostic tools. For hot paths under heavy diagnostics, you might prefer the explicit field.

Key Takeaways

field is a contextual keyword in C# 14 that refers to the compiler-synthesized backing field of a property — the same one auto-properties already create.
It lets you add logic to one or both accessors without promoting the backing field to an explicit private member.
It works in get, set, and init accessors, and you can mix auto-implementation with field-based implementation in the same property.
The gotcha to remember: if a property is named field, use @field to disambiguate the identifier from the keyword.
Prefer an explicit backing field when: the constructor needs to bypass property logic, multiple properties share one storage slot, or the field name matters for diagnostics.

C# 14: La keyword `field` — Propiedades más limpias, cero boilerplate

Juan Gómez — Wed, 10 Jun 2026 21:18:31 +0000

C# 14: La keyword `field` — Propiedades más limpias, cero boilerplate

Todo desarrollador de C# lo ha vivido. Empiezas con una auto-propiedad limpia, llegan nuevos requerimientos y necesitas agregar una pequeña validación. De repente esa línea explota en seis líneas de boilerplate — un campo privado, un getter que solo lo retorna, un setter que lo asigna. La lógica son dos palabras. La ceremonia es todo lo demás.

C# 14 resuelve esto con la keyword field: una keyword contextual que hace referencia al backing field sintetizado por el compilador de una propiedad, permitiéndote escribir lógica personalizada en los accessors sin necesidad de declarar un campo explícito.

El problema: el impuesto del boilerplate

Las auto-propiedades son una de las mejores mejoras de calidad de vida en C#. Esto es limpio:

public string Username { get; set; }

Pero en el momento en que necesitas hacer un trim del espacio en blanco al asignar, esa limpieza desaparece:

private string _username = string.Empty;

public string Username
{
    get => _username;
    set => _username = value.Trim();
}

Ahora tienes seis líneas — y cuatro de ellas existen únicamente para mantener la forma del patrón. El campo privado _username no aporta ningún peso de diseño significativo. Su único trabajo es ser un slot de almacenamiento que Username usa de forma privada. Ya sabes que el compilador crea uno para las auto-propiedades. Solo estás obligado a hacerlo visible para poder referenciarlo.

Este es el impuesto del boilerplate. Lo pagas cada vez que agregas la más mínima lógica a una propiedad.

Por qué existe `field`

El equipo de C# ha discutido esta fricción durante años. El desafío era encontrar una sintaxis que fuera:

Inequívoca — sin conflicto con identificadores existentes
Familiar — consistente con cómo funciona value en los setters
Acotada — con significado solo dentro de un accessor de propiedad

La solución llegó en C# 14: la keyword contextual field. Igual que value hace referencia al valor entrante en un setter, field hace referencia al almacenamiento interno que el compilador administra para la propiedad.

Es contextual, lo que significa que solo actúa como keyword dentro de un accessor de propiedad. En el resto de tu código, field sigue siendo un nombre de identificador válido (con una trampa que veremos más adelante).

Cómo funciona

Sintaxis básica

La misma propiedad Username reescrita con field:

public string Username
{
    get;
    set => field = value.Trim();
}

El accessor get sigue siendo auto-implementado — simplemente retorna field. El accessor set hace su único trabajo: hacer trim al valor entrante antes de almacenarlo. El campo privado desapareció. El compilador lo sintetiza en segundo plano, y field te permite acceder a él.

También puedes hacerlo al revés — implementar get y auto-implementar set:

public string DisplayName
{
    get => field.ToUpperInvariant();
    set;
}

O implementar ambos lados:

public int Age
{
    get => field;
    set => field = value >= 0 ? value : throw new ArgumentOutOfRangeException(nameof(value), "La edad no puede ser negativa.");
}

También funciona con `init`

Las propiedades de solo inicialización funcionan exactamente igual:

public string Email
{
    get;
    init => field = value.Trim().ToLowerInvariant();
}

Esto es especialmente útil en clases inmutables estilo record donde quieres normalización al construir pero sin mutación posterior.

Patrones de uso en el mundo real

1. Normalización de entrada

El caso de uso más común. Trim de strings, normalización de mayúsculas, saneamiento de input del usuario — todo sin un backing field:

namespace Blog.Models;

public sealed class UserProfile
{
    public string Username
    {
        get;
        set => field = value.Trim();
    }

    public string Email
    {
        get;
        set => field = value.Trim().ToLowerInvariant();
    }

    public string? DisplayName
    {
        get;
        set => field = string.IsNullOrWhiteSpace(value) ? null : value.Trim();
    }
}

Las tres propiedades se ven casi tan limpias como auto-propiedades, y cada una aplica su propio invariante en el punto de asignación.

2. Validación de rango

Las propiedades numéricas que deben mantenerse dentro de límites son un caso perfecto:

namespace Blog.Models;

public sealed class ProductListing
{
    private const decimal MaxPrice = 99_999.99m;

    public string Title
    {
        get;
        set => field = value.Trim();
    }

    public decimal Price
    {
        get;
        set
        {
            ArgumentOutOfRangeException.ThrowIfNegative(value);
            ArgumentOutOfRangeException.ThrowIfGreaterThan(value, MaxPrice);
            field = value;
        }
    }

    public int StockQuantity
    {
        get;
        set => field = int.Max(0, value); // Clamp silencioso — decisión intencional de producto
    }
}

Nota ArgumentOutOfRangeException.ThrowIfNegative y ThrowIfGreaterThan — helpers de .NET 8+ que son más limpios que los if manuales con throw. Usa las APIs modernas.

3. Inicialización lazy

field brilla en propiedades de carga diferida. El patrón clásico requería un backing field nullable y una danza de null-check:

// Antes de C# 14 — el baile de siempre
private List<string>? _tags;
public List<string> Tags => _tags ??= [];

Con field, escribes la misma lógica directamente dentro de la propiedad:

public List<string> Tags => field ??= [];

Una línea. El compilador administra el backing field. Tú administras la lógica.

4. Notificación de cambios (INotifyPropertyChanged)

Las propiedades de ViewModel en aplicaciones MVVM suelen verse así:

namespace Blog.ViewModels;

public sealed class OrderViewModel : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler? PropertyChanged;

    public string CustomerName
    {
        get;
        set
        {
            if (field == value) return;
            field = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(CustomerName)));
        }
    }

    public decimal Total
    {
        get;
        set
        {
            if (field == value) return;
            field = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Total)));
        }
    }
}

Sin campos privados. Sin riesgo de colisión de nombres. El patrón sigue siendo verboso (esa es la naturaleza de INotifyPropertyChanged), pero field elimina una pieza móvil del rompecabezas.

La trampa de `field`: cuando tu propiedad se llama `field`

Aquí las cosas se ponen interesantes. Como field es una keyword contextual, una propiedad que se llame efectivamente field puede entrar en conflicto con la keyword. Considera esto:

public sealed class DatabaseRecord
{
    // Esta propiedad se llama "field" — inusual, pero legal
    public string field
    {
        get;
        // Dentro de aquí, ¿"field" es la keyword o la propiedad misma?
        set => field = value.Trim(); // ¡Ambiguo!
    }
}

El compilador te advertirá sobre la ambigüedad. La solución es el identificador verbatim @field, que le indica a C# que lo trate como un identificador y no como la keyword:

public sealed class DatabaseRecord
{
    public string @field
    {
        get;
        set => @field = value.Trim(); // Explícito: este es el identificador, no la keyword
    }
}

En la práctica, nombrar una propiedad field es inusual. Pero si trabajas con código que mapea a esquemas externos o bases de datos que usan nombres reservados, ahora conoces la salida de emergencia.

Cuándo usar `field`

Usa field cuando necesitas algo de lógica en un accessor pero la propiedad sigue siendo la única dueña de su valor:

Normalización en asignación — trim, mayúsculas, formato
Validación en asignación — rangos, null guards, formato
Inicialización lazy — patrones de cálculo en primer acceso
Change tracking simple — verificación de igualdad antes de disparar eventos
Normalización en init — objetos inmutables que necesitan entrada limpia

La regla de oro: si antes hubieras escrito un backing field privado al que nada más en la clase hace referencia, reemplázalo con field.

Cuándo NO usar `field`

field no es una bala de plata. Hay casos donde un backing field explícito sigue siendo la herramienta correcta:

El problema del bypass en el constructor

Supón que tienes una propiedad que dispara un evento al asignarse. Quieres que el constructor establezca el valor inicial silenciosamente, sin disparar el evento. Con field no puedes hacerlo — la única forma de acceder al almacenamiento interno es a través del accessor de la propiedad.

public sealed class Sensor
{
    // El evento se dispara en cada set — queremos saltarlo en el constructor
    public double Temperature
    {
        get;
        set
        {
            field = value;
            ReadingChanged?.Invoke(this, EventArgs.Empty);
        }
    }

    public event EventHandler? ReadingChanged;

    public Sensor(double initialTemperature)
    {
        // Esto dispara ReadingChanged durante la construcción — probablemente no es lo que quieres
        Temperature = initialTemperature;
    }
}

Si el constructor necesita saltarse la lógica de la propiedad, mantén el backing field explícito y asígnalo directamente desde el constructor.

Múltiples propiedades que comparten estado

Si dos o más propiedades leen o escriben el mismo valor subyacente — por ejemplo Radius y Diameter calculadas una a partir de la otra — necesitas un campo explícito al que ambas propiedades hagan referencia. field es por propiedad; no puede compartirse.

Estado derivado complejo

Si el "almacenamiento interno" no es un valor simple sino que involucra múltiples campos, cachés u objetos, un campo explícito con un nombre descriptivo comunica la intención mucho mejor que la keyword anónima field.

Cuando el nombre importa para el diagnóstico

Los backing fields explícitos aparecen en los debuggers con su nombre declarado. El backing field sintetizado por el compilador para propiedades basadas en field recibe un nombre generado (como <Username>k__BackingField) que es menos legible en memory dumps o herramientas de diagnóstico. Para rutas críticas bajo diagnósticos intensivos, puede que prefieras el campo explícito.

Puntos clave

field es una keyword contextual de C# 14 que hace referencia al backing field sintetizado por el compilador — el mismo que las auto-propiedades ya crean.
Permite agregar lógica a uno o ambos accessors sin promover el backing field a un miembro privado explícito.
Funciona en accessors get, set e init, y puedes mezclar auto-implementación con implementación basada en field en la misma propiedad.
La trampa a recordar: si una propiedad se llama field, usa @field para distinguir el identificador de la keyword.
Prefiere un backing field explícito cuando: el constructor necesita saltarse la lógica de la propiedad, múltiples propiedades comparten un slot de almacenamiento, o el nombre del campo importa para el diagnóstico.