Forem: Isaac Ojeda

EF Core: tu query funciona, tus pruebas pasan… y estás leyendo 50,000 filas para devolver 3

Isaac Ojeda — Sat, 14 Mar 2026 22:44:46 +0000

El código lleva meses en producción. Nadie se ha quejado. Todas las pruebas pasan.

Luego llega un cliente grande, con años de historial acumulado, y esa pantalla que siempre cargó “bien” empieza a tardar varios segundos. A veces ni siquiera falla: simplemente se vuelve torpe, pesada, impredecible.

Empiezas a revisar y descubres algo incómodo: el problema siempre estuvo ahí. Solo necesitaba suficientes datos para hacerse visible.

Ese es uno de los patrones más traicioneros cuando trabajas con EF Core. No porque el código esté roto, sino porque funciona. Devuelve los datos correctos. Pasa QA. Sobrevive en producción durante meses. Y aun así, por debajo, puede estar ejecutando consultas mucho más caras de lo que parecen.

En este artículo quiero mostrar dos trampas comunes:

cuando materializas demasiado pronto con ToList() y el filtro termina ocurriendo en memoria;
cuando dejas lógica no traducible dentro de la proyección y la consulta deja de ser tan eficiente como parece.

La idea no es memorizar reglas raras de EF Core. La idea es desarrollar un reflejo: siempre revisar el SQL real que se genera.

Por qué casi nadie lo detecta a tiempo

Este problema rara vez aparece de golpe.

En local, todo corre sobre una base pequeña, con datos de prueba y una máquina rápida. Las consultas tardan milisegundos y nadie siente la necesidad de inspeccionar el SQL.

En QA o staging, la infraestructura puede parecerse a producción, pero el volumen de datos sigue sin representar el mundo real. El problema ya existe, solo que todavía no pesa.

En producción, con clientes pequeños, los tiempos siguen siendo aceptables. No hay alertas. No hay tickets. No hay razón aparente para abrir el capó.

Y entonces llega el cliente con años de historial, decenas de miles de registros y patrones reales de uso. Ahí, por primera vez, la consulta muestra su costo verdadero.

Lo más difícil de este escenario no es corregirlo. Lo más difícil es que cuando por fin se vuelve visible, el código ya lleva tanto tiempo vivo que nadie recuerda con claridad por qué se escribió así.

En EF Core, el peligro no siempre es que algo falle. A veces el peligro es que funcione… pero de la forma más cara posible.

Problema 1: el `ToList()` que mueve el filtro fuera de SQL

El origen: una excepción legítima

Todo empieza con algo bastante normal: quieres usar lógica de negocio propia dentro de un Where.

var pedidos = await context.Pedidos
    .Where(p => EsDelUltimoMes(p.FechaCreacion))
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total
    })
    .ToListAsync();

private static bool EsDelUltimoMes(DateTime fecha) =>
    fecha >= DateTime.Now.AddMonths(-1);

Ese código no es traducible tal como está. EsDelUltimoMes es un método local de C#, y EF Core no sabe convertirlo a SQL. En EF Core moderno, eso normalmente termina en una excepción de traducción.

Algo como esto:

InvalidOperationException: The LINQ expression could not be translated.
Either rewrite the query in a form that can be translated, or switch to
client evaluation explicitly by inserting a call to 'AsEnumerable',
'AsAsyncEnumerable', 'ToList', or 'ToListAsync'.

La excepción no miente. Pero es muy fácil leerla de forma peligrosa.

La “solución” que parece arreglar todo

Alguien ve que el mensaje menciona ToList(), lo agrega, y el problema desaparece:

var pedidos = context.Pedidos
    .ToList()
    .Where(p => EsDelUltimoMes(p.FechaCreacion))
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total
    })
    .ToList();

Y sí: ahora funciona. Compila, devuelve resultados correctos y pasa las pruebas.

Pero ya no estás filtrando en la base de datos. Estás trayendo todos los registros primero, y luego aplicando la lógica en memoria.

En otras palabras, el SQL que sale ya no se parece a la intención original. Se parece más a esto:

SELECT p.Id, p.ClienteId, p.Total, p.Activo, p.FechaCreacion, ...
FROM Pedidos

Sin WHERE. Sin proyección útil. Sin límite.

Si la tabla tiene 50,000 filas, esas 50,000 filas viajan completas desde la base de datos hasta tu aplicación. Solo después haces el filtro en C# para devolver quizá 3 resultados al usuario.

Ese es el tipo de problema que no se nota con 200 registros, pero sí con años de operación acumulada.

La forma correcta

La solución real es expresar el filtro usando operadores que EF Core sí conozca y pueda traducir.

var fechaLimite = DateTime.Now.AddMonths(-1);

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total
    })
    .ToListAsync();

Ahora sí el filtro vive donde debe vivir: en SQL.

SELECT c.Nombre, p.Total
FROM Pedidos p
LEFT JOIN Clientes c ON p.ClienteId = c.Id
WHERE p.FechaCreacion >= '2025-02-14'

La regla práctica aquí no es “nunca uses métodos”. Es esta: mientras la lógica se exprese con operadores y funciones que EF Core conoce, podrá empujarla a SQL. Cuando no pueda, corres el riesgo de que la evaluación ocurra fuera de la base de datos o de que EF directamente falle al traducir.

Si necesitas lógica de negocio más compleja, aplícala después de materializar, pero solo sobre un conjunto de datos que ya filtraste correctamente en la base.

Nota: en algunos escenarios complejos, usar Raw SQL es perfectamente válido. No es una derrota; es una herramienta más.

Problema 2: la proyección parece pequeña, pero la consulta deja de ser eficiente

El segundo problema es más silencioso.

Aquí el Where sí se traduce. La consulta sí filtra en la base de datos. Los resultados son correctos. El detalle está en la proyección.

El escenario

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        Estatus = ObtenerEtiqueta(p.Activo)
    })
    .ToListAsync();

private static string ObtenerEtiqueta(bool activo) =>
    activo ? "Activo" : "Inactivo";

A simple vista, parece una proyección pequeña. Solo quieres tres campos.

El problema es que ObtenerEtiqueta sigue siendo lógica local de C#. EF Core no puede traducir ese método directamente. En la proyección final, eso puede hacer que parte del trabajo termine resolviéndose del lado del cliente.

Y cuando eso pasa, la consulta puede traer más información de la necesaria para completar esa proyección en memoria.

La parte peligrosa no es solo “que funcione”. Es que desde el código parece una consulta mínima, cuando en realidad el SQL puede estar cargando más columnas de las que tú creías.

No siempre será literalmente un SELECT *, pero sí puede ocurrir que EF traiga suficiente información como para volver la proyección más costosa de lo que aparenta en C#.

La forma correcta

Si el formateo no necesita vivir en SQL, sepáralo de la consulta:

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        EsActivo = p.Activo
    })
    .ToListAsync();

// Dejar que la capa presentación muestre los datos
// o
// 👇🏼
foreach (var pedido in pedidos)
    pedido.Estatus = ObtenerEtiqueta(pedido.EsActivo);

Así la base de datos solo devuelve lo necesario, y el formateo ocurre después, en memoria, pero ya sobre un conjunto pequeño y bien proyectado.

Si la lógica sí puede expresarse con algo traducible, entonces mejor dejarla en la consulta:

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        Estatus = p.Activo ? "Activo" : "Inactivo"
    })
    .ToListAsync();

Una expresión ternaria simple como esa normalmente sí se traduce a CASE WHEN en SQL.

Cómo inspeccionar lo que EF Core realmente está haciendo

Si no ves el SQL, estás adivinando.

Y adivinar con consultas que hoy corren sobre 500 filas y mañana correrán sobre 5 millones suele salir caro.

Opción 1: logs en desarrollo

Puedes habilitar logs del contexto para ver el SQL ejecutado:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(connectionString)
           .LogTo(Console.WriteLine, LogLevel.Information)
           .EnableSensitiveDataLogging());

EnableSensitiveDataLogging() conviene dejarlo solo en desarrollo.

En la salida, busca entradas como esta:

Executed DbCommand (X ms) [Parameters=[...], CommandType='Text', CommandTimeout='30']

Ahí está la consulta real.

Opción 2: `ToQueryString()`

Cuando quieres revisar una consulta específica, esta suele ser la forma más directa:

var query = context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        Estatus = p.Activo ? "Activo" : "Inactivo"
    });

Console.WriteLine(query.ToQueryString());
var pedidos = await query.ToListAsync();

ToQueryString() funciona sobre cualquier IQueryable antes de materializarlo. Si tienes dudas sobre traducción, úsalo. Te ahorra suposiciones.

Un detalle extra en consultas de lectura

Si esa consulta solo existe para mostrar datos y no vas a modificar las entidades después, vale la pena considerar AsNoTracking():

var pedidos = await context.Pedidos
    .AsNoTracking()
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total
    })
    .ToListAsync();

No arregla problemas de traducción ni evita consultas mal diseñadas. Pero sí reduce trabajo del change tracker en escenarios de solo lectura, y eso puede sumar bastante cuando la pantalla consulta muchos registros.

Sobre asistentes de código y queries “que funcionan”

Los asistentes de código suelen optimizar para darte algo que compile, que se vea razonable y que devuelva el resultado esperado.

Eso está bien. Pero una consulta correcta funcionalmente no siempre es una consulta sana desde el punto de vista de traducción o performance.

El asistente no ve el volumen real de tu tabla. No está mirando el plan de ejecución. No sabe si ese query hoy devuelve 20 registros o si mañana va a inspeccionar medio millón para construir una pantalla.

Por eso esta revisión sigue siendo responsabilidad del developer: no basta con que la consulta compile y pase pruebas. Hay que confirmar qué SQL genera y dónde se está ejecutando realmente cada parte de la lógica.

Resumen

Situación	Qué ocurre	Cómo detectarlo
Método local no traducible dentro de `Where`	EF Core normalmente falla al traducir o te obliga a mover la evaluación fuera de SQL	Excepción de traducción
`ToList()` antes del filtro	La consulta se materializa completa y el filtrado ocurre en memoria	Revisando el código y el SQL generado
Lógica no traducible en la proyección final	Parte de la proyección puede resolverse en cliente y traer más datos de los necesarios	`ToQueryString()`, logs y revisión de columnas consultadas

La idea central de todo esto es simple: no confíes en que una query está bien solo porque funciona.

En EF Core, una consulta puede ser correcta en resultados y aun así ser innecesariamente cara. Y la forma más confiable de descubrirlo no es mirando el LINQ: es mirando el SQL.

¿Qué sigue?

Este es el primero de una serie sobre cosas que EF Core hace de forma poco obvia y que solo se vuelven dolorosas cuando los datos son reales.

El siguiente artículo va sobre el problema N+1: esa consulta que en desarrollo parece hacer unas pocas llamadas a la base, pero en producción termina haciendo cientos o miles.

Si alguna vez te pasó algo parecido, seguramente no fue porque el código estuviera “mal” en apariencia. Fue porque el costo real estaba escondido en un lugar que casi nadie revisa a tiempo.

Primeros pasos con Microsoft Agent Framework: construyendo un chatbot de soporte con C#

Isaac Ojeda — Tue, 24 Feb 2026 03:33:14 +0000

Introducción

Microsoft lleva años apostando por herramientas para construir aplicaciones con IA: primero llegó Semantic Kernel, después AutoGen, y ahora ambos convergen en su sucesor directo: Microsoft Agent Framework (MAF). Creado por los mismos equipos, MAF unifica lo mejor de ambos mundos — la estabilidad y características enterprise de Semantic Kernel con las abstracciones simples para agentes multi-turno de AutoGen — y agrega nuevas capacidades como workflows basados en grafos y un sistema robusto de manejo de estado.

Al momento de escribir este artículo, MAF está en public preview, disponible para .NET y Python bajo licencia MIT.

En este artículo vamos a aprender los conceptos fundamentales del framework y a construir algo concreto: una API con ASP.NET Core 10 que expone un chatbot de soporte técnico capaz de responder preguntas basándose en documentación Markdown interna, manteniendo el contexto de la conversación entre mensajes.

El código completo está disponible en GitHub.

Desarrollo

¿Qué es Microsoft Agent Framework?

MAF gira en torno a dos conceptos centrales que vale la pena entender antes de escribir código:

Agents son sistemas que usan un LLM para procesar entradas, tomar decisiones, llamar herramientas y generar respuestas. Son ideales cuando la tarea es dinámica y no puedes predecir de antemano exactamente qué pasos se van a necesitar — como una conversación de soporte donde el usuario puede preguntar cualquier cosa.

Workflows son secuencias de pasos definidas explícitamente, conectadas en un grafo. Son la elección correcta cuando el flujo es predecible y necesitas control determinista sobre la ejecución — como un pipeline de procesamiento de datos o un flujo de aprobaciones.

La documentación oficial tiene una regla de oro que me parece honesta y útil: "If you can write a function to handle the task, do that instead of using an AI agent." No todo necesita un agente. En este artículo construimos un agente porque la naturaleza conversacional e impredecible del soporte técnico es exactamente el caso de uso para el que están diseñados.

Los 5 conceptos clave

El tutorial oficial de Microsoft Learn organiza el aprendizaje en 5 pasos progresivos. Aquí los resumo en mis propias palabras antes de ver el código:

1. Tu primer agente. Un AIAgent se crea a partir de un cliente de chat (Azure OpenAI, OpenAI, etc.) con instrucciones y un nombre. Es stateless por diseño — el mismo agente puede atender múltiples conversaciones en paralelo. Correrlo es tan simple como await agent.RunAsync("pregunta").

2. Tools. Cualquier método C# decorado con [Description] se puede convertir en una herramienta que el agente puede llamar cuando lo necesite, usando AIFunctionFactory.Create(). El LLM decide autónomamente cuándo y con qué argumentos invocarla. Esto es lo que le da al agente la capacidad de actuar sobre el mundo real.

3. Multi-turn conversations. Como el agente es stateless, el historial de la conversación vive en un AgentSession. Se crea con agent.CreateSessionAsync() y se pasa en cada llamada. El agente recuerda todo lo que ocurrió en esa sesión.

4. Memory y Persistencia. La sesión es serializable a JsonElement. Esto permite guardarla en cualquier almacenamiento (memoria, base de datos, Redis) y reconstruirla después con agent.DeserializeSessionAsync(). Para un chat de soporte, esto significa que el usuario puede retomar una conversación donde la dejó, incluso si el servidor se reinició.

5. Workflows. Para orquestar múltiples agentes o pasos en secuencias definidas, se usa WorkflowBuilder. Se definen Executors (unidades de procesamiento) y se conectan con Edges. En este artículo no los implementamos porque no añaden valor real al caso de uso — pero al final menciono cuándo sí tendría sentido usarlos.

El ejemplo: SupportBot

El escenario es simple: una empresa tiene documentación interna en archivos .md — guías de usuario, FAQs, manuales de módulos. En lugar de que los empleados busquen manualmente en esos archivos, un chatbot lee la documentación y responde en lenguaje natural, manteniendo el hilo de la conversación.

Deliberadamente dejé fuera RAG y embeddings. La búsqueda por keywords en archivos planos es suficiente para demostrar cómo funciona MAF, y mantiene el ejemplo enfocado en el framework, no en infraestructura de búsqueda vectorial.

La estructura del proyecto es la siguiente:

SupportBot/
├── Program.cs
├── appsettings.json
├── Docs/
│   ├── accesos.md
│   ├── facturacion.md
│   └── reportes.md
├── Agents/
│   └── SupportAgentFactory.cs
├── Tools/
│   └── DocumentationTool.cs
├── Models/
│   ├── ChatRequest.cs
│   └── ChatResponse.cs
└── Sessions/
    └── InMemorySessionStore.cs

Instalación

dotnet new webapi -n SupportBot
cd SupportBot

dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI --prerelease
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
dotnet add package Microsoft.Extensions.AI --prerelease

Todos los paquetes de Microsoft.Agents.AI están en prerelease — el flag es necesario.

La Tool: DocumentationTool

Aquí está el corazón del ejemplo. DocumentationTool es la herramienta que el agente llamará cuando necesite buscar información para responder al usuario.

using System.ComponentModel;

namespace SupportBot.Tools;

public class DocumentationTool
{
    private readonly string _docsPath;

    public DocumentationTool(string docsPath)
    {
        _docsPath = docsPath;
    }

    [Description("Busca en la documentación interna del sistema información sobre un tema específico. Úsala siempre antes de responder una pregunta del usuario.")]
    public string GetDocumentation(
        [Description("El tema o concepto sobre el que buscar. Por ejemplo: 'accesos', 'facturación', 'reportes', 'contraseña', etc.")]
        string topic)
    {
        if (!Directory.Exists(_docsPath))
            return "No hay documentación disponible en este momento.";

        var files = Directory.GetFiles(_docsPath, "*.md");

        if (files.Length == 0)
            return "No hay documentación disponible en este momento.";

        var keywords = topic.ToLowerInvariant()
            .Split(' ', StringSplitOptions.RemoveEmptyEntries);

        var matchingFiles = files.Where(file =>
        {
            var fileName = Path.GetFileNameWithoutExtension(file).ToLowerInvariant();
            var content = File.ReadAllText(file).ToLowerInvariant();
            return keywords.Any(k => fileName.Contains(k) || content.Contains(k));
        }).ToList();

        var filesToRead = matchingFiles.Count > 0 ? matchingFiles : files.ToList();

        var builder = new System.Text.StringBuilder();
        foreach (var file in filesToRead)
        {
            var fileName = Path.GetFileNameWithoutExtension(file);
            var content = File.ReadAllText(file);
            builder.AppendLine($"=== {fileName.ToUpperInvariant()} ===");
            builder.AppendLine(content);
            builder.AppendLine();
        }

        return builder.ToString();
    }
}

Hay dos detalles importantes aquí. El primero es que los atributos [Description] no son decorativos — MAF los usa para construir el schema que el LLM recibe, y de su calidad depende que el modelo entienda bien cuándo y cómo llamar la herramienta. El segundo es la estrategia de fallback: si no encuentra archivos que hagan match con el tema, retorna todos los documentos. Es una decisión pragmática — preferimos que el agente tenga demasiado contexto a que se quede sin información para responder.

El Agente: SupportAgentFactory

using Azure.AI.OpenAI;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using SupportBot.Tools;

namespace SupportBot.Agents;

public class SupportAgentFactory
{
    private readonly AIAgent _agent;

    public SupportAgentFactory(IConfiguration configuration, IWebHostEnvironment env)
    {
        var endpoint = configuration["AzureOpenAI:Endpoint"]
            ?? throw new InvalidOperationException("AzureOpenAI:Endpoint no configurado");
        var deploymentName = configuration["AzureOpenAI:DeploymentName"] ?? "gpt-4o-mini";
        var apiKey = configuration["AzureOpenAI:ApiKey"]
            ?? throw new InvalidOperationException("AzureOpenAI:ApiKey no configurado");

        var docsPath = Path.Combine(env.ContentRootPath, "Docs");
        var docTool = new DocumentationTool(docsPath);

        var instructions = """
            Eres un asistente de soporte técnico interno. Tu única fuente de información
            es la documentación del sistema que puedes consultar con la herramienta GetDocumentation.

            Reglas:
            - SIEMPRE consulta la documentación antes de responder cualquier pregunta.
            - Responde de forma clara, concisa y en el mismo idioma que el usuario.
            - Si la documentación no contiene la respuesta, dilo claramente.
            - No inventes información que no esté en la documentación.
            - Si el usuario saluda o hace preguntas generales, responde amablemente y pregunta en qué puedes ayudar.
            - No respondas preguntas fuera del contexto del sistema.
            """;

        _agent = new AzureOpenAIClient(
                new Uri(endpoint),
                new System.ClientModel.ApiKeyCredential(apiKey))
            .GetChatClient(deploymentName)
            .AsIChatClient()
            .AsAIAgent(
                instructions: instructions,
                name: "SupportAgent",
                tools: [AIFunctionFactory.Create(docTool.GetDocumentation)]
            );
    }

    public AIAgent Agent => _agent;
}

El flujo de construcción es una cadena: AzureOpenAIClient → GetChatClient() → AsIChatClient() → AsAIAgent(). El último paso es donde se convierten las tools registradas y las instrucciones en la configuración que el agente usará en cada conversación.

Nótese que el agente se construye una sola vez y se registra como singleton. Como es stateless, puede atender todas las conversaciones concurrentes sin problema — el estado de cada conversación vive en su propia AgentSession.

Manejo de Sesiones: InMemorySessionStore

using System.Collections.Concurrent;
using System.Text.Json;

namespace SupportBot.Sessions;

public class InMemorySessionStore
{
    private readonly ConcurrentDictionary<string, JsonElement> _sessions = new();

    public bool TryGetSession(string sessionId, out JsonElement session)
        => _sessions.TryGetValue(sessionId, out session);

    public void SaveSession(string sessionId, JsonElement session)
        => _sessions[sessionId] = session;

    public bool DeleteSession(string sessionId)
        => _sessions.TryRemove(sessionId, out _);
}

El store guarda sesiones como JsonElement — el formato en que MAF las serializa nativamente. ConcurrentDictionary garantiza thread-safety sin necesidad de locks manuales. Para producción, esto se reemplazaría por Redis o una base de datos, pero la interfaz del store no cambiaría.

Los Endpoints: Program.cs

using System.Text.Json;
using Microsoft.Agents.AI;
using SupportBot.Agents;
using SupportBot.Models;
using SupportBot.Sessions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<SupportAgentFactory>();
builder.Services.AddSingleton<InMemorySessionStore>();

var app = builder.Build();

app.MapPost("/chat", async (
    ChatRequest request,
    SupportAgentFactory agentFactory,
    InMemorySessionStore sessionStore) =>
{
    if (string.IsNullOrWhiteSpace(request.SessionId))
        return Results.BadRequest("SessionId es requerido.");

    if (string.IsNullOrWhiteSpace(request.Message))
        return Results.BadRequest("Message es requerido.");

    var agent = agentFactory.Agent;

    AgentSession session;
    if (sessionStore.TryGetSession(request.SessionId, out var serializedSession))
    {
        session = await agent.DeserializeSessionAsync(serializedSession);
    }
    else
    {
        session = await agent.CreateSessionAsync();
    }

    var response = await agent.RunAsync(request.Message, session);

    var updatedSession = await agent.SerializeSessionAsync(session);
    sessionStore.SaveSession(request.SessionId, updatedSession);

    return Results.Ok(new ChatResponse(request.SessionId, response.Text));
});

app.MapDelete("/chat/{sessionId}", (
    string sessionId,
    InMemorySessionStore sessionStore) =>
{
    sessionStore.DeleteSession(sessionId);
    return Results.NoContent();
});

app.Run();

El endpoint POST /chat sigue un patrón claro: cargar o crear sesión → ejecutar el agente → serializar y guardar la sesión actualizada → retornar la respuesta. El sessionId lo genera el cliente (puede ser un GUID) y lo manda en cada request para mantener el hilo de la conversación.

Un detalle de la versión RC1: SerializeSessionAsync es async, a diferencia de lo que indica la documentación inicial del framework.

El agente en acción

Con la API corriendo, así se ve una conversación multi-turn real:

Primer mensaje:

POST /chat
{
  "sessionId": "usr-42",
  "message": "Hola, no puedo entrar al sistema, olvidé mi contraseña"
}

{
  "sessionId": "usr-42",
  "reply": "¡Hola! Para resetear tu contraseña sigue estos pasos: ve a la pantalla de login y haz clic en '¿Olvidaste tu contraseña?', ingresa tu correo corporativo y recibirás un enlace válido por 24 horas. Si no recibes el correo en 10 minutos, revisa tu carpeta de spam o contacta a TI."
}

Mensaje de seguimiento (mismo sessionId):

POST /chat
{
  "sessionId": "usr-42",
  "message": "¿Y si tampoco recuerdo mi correo corporativo?"
}

{
  "sessionId": "usr-42",
  "reply": "En ese caso, la cuenta puede quedar bloqueada tras 5 intentos fallidos. Te recomiendo contactar directamente al equipo de soporte en soporte@empresa.com o llamar al ext. 100 para que puedan verificar tu identidad y ayudarte a recuperar el acceso."
}

El agente recuerda que estamos hablando de un problema de acceso y responde en contexto, sin necesidad de que el usuario repita la situación.

¿Cuándo agregarías Workflows aquí?

En este ejemplo los Workflows no añaden valor — el flujo conversacional es impredecible por naturaleza y el agente lo maneja bien solo. Pero hay escenarios donde sí tendría sentido introducirlos:

Si quisieras clasificar automáticamente la intención antes de responder (¿es una pregunta de accesos, facturación o reportes?) y enrutar a agentes especializados según el tema, un Workflow con un executor de clasificación seguido de ejecutores especializados sería la arquitectura correcta.

Si quisieras escalar a un humano cuando el agente no encuentra respuesta, un Workflow con un paso de "human-in-the-loop" integrado en el grafo lo haría de forma limpia y auditable.

La regla es simple: si puedes predecir los pasos, usa un Workflow. Si la conversación es abierta e impredecible, deja que el agente decida.

Conclusión

Microsoft Agent Framework simplifica genuinamente la construcción de agentes conversacionales en .NET. La abstracción de AIAgent, el manejo de sesiones serializable y el sistema de tools via atributos [Description] permiten tener algo funcional con muy poco código de infraestructura — lo que queda es lógica de negocio real.

El hecho de que aún esté en preview se nota en algunos detalles: la API cambia entre versiones (como el caso de SerializeSessionAsync que en RC1 es async), y la documentación a veces no refleja el estado actual del código. Dicho esto, para proyectos nuevos donde el timeline lo permite, ya vale la pena apostar por él en lugar de Semantic Kernel — es el camino hacia adelante según el propio equipo de Microsoft.

Los siguientes pasos naturales para este proyecto serían reemplazar el InMemorySessionStore por Redis o SQL Server para persistencia real, agregar autenticación al endpoint, e integrar un frontend — pero eso es material para otro artículo.

Referencias

Microsoft Agent Framework Overview — Microsoft Learn
Get Started: Steps 1–5 — Microsoft Learn
Repositorio oficial con samples — GitHub
Anuncio oficial: Semantic Kernel y Microsoft Agent Framework — Microsoft Dev Blog
Migration Guide from Semantic Kernel — Microsoft Learn

Sistema de Control de Jobs en Tiempo Real con Channels y Background Services en .NET

Isaac Ojeda — Sat, 01 Nov 2025 22:42:58 +0000

Introducción

En el desarrollo moderno de aplicaciones, es común necesitar ejecutar procesos en segundo plano que se comuniquen con nuestra API de forma eficiente y segura. Tradicionalmente, esto se resolvía con implementaciones complejas usando locks, colas manuales o infraestructura externa como RabbitMQ. Sin embargo, .NET ofrece una solución simple pero elegante: System.Threading.Channels.

En este artículo, exploraremos cómo construir un sistema de control de jobs en tiempo real utilizando:

🔧 Channels para comunicación thread-safe entre componentes
🔄 Background Services para tareas recurrentes
🚀 Minimal APIs para endpoints modernos y limpios
⚡ TaskCompletionSource para comunicación bidireccional

Al finalizar, tendrás un proyecto funcional que puedes adaptar para casos de uso reales como procesamiento de emails, análisis de imágenes, generación de reportes, y más.

Nota: El código fuente siempre lo encontrarás en mi github -> DevToPosts/ApiBackgroundChannels at main · isaacOjeda/DevToPosts

¿Qué son los Channels?

Los Channels en .NET son estructuras de datos thread-safe diseñadas para escenarios productor-consumidor. Piensa en ellos como una "tubería" donde un lado escribe datos y el otro los lee, sin preocuparte por locks o sincronización manual.

¿Por qué usarlos?

✅ Thread-safe por diseño
✅ Alta performance con bajo overhead
✅ Backpressure integrado (control de flujo)
✅ Ideal para comunicación entre hilos/tareas
✅ Alternativa simple a colas externas (RabbitMQ, Redis) para escenarios internos
✅ Optimizado para async/await (usa ValueTask internamente)

Arquitectura del Proyecto

Este proyecto demuestra cómo controlar un Background Job desde una API usando Channels para comunicación bidireccional:

┌──────────────┐         ┌─────────┐         ┌──────────────────┐
│  API Request │ ──────> │ Channel │ ──────> │ Background Job   │
│  (Productor) │         │ (Cola)  │         │ (Consumidor)     │
└──────────────┘         └─────────┘         └──────────────────┘
      ↑                                             │
      └────── TaskCompletionSource ─────────────────┘
                     (Respuesta)

Paso 1: Definir el Modelo de Comunicación

Primero, necesitamos estructuras para enviar comandos y recibir respuestas:

public enum CommandType { Start, Stop, GetStatus }

public class JobCommand
{
    public CommandType Type { get; set; }
    public TaskCompletionSource<JobStatus>? ResponseTask { get; set; }
}

public class JobStatus
{
    public bool IsRunning { get; set; }
    public int ExecutionCount { get; set; }
    public DateTime? LastExecutionTime { get; set; }
    public string Message { get; set; } = string.Empty;
}

💡 Clave: TaskCompletionSource nos permite crear una Task que completaremos manualmente cuando tengamos la respuesta, haciendo posible la comunicación bidireccional.

Paso 2: Crear el Background Service (Consumidor)

public class JobProcessor : BackgroundService
{
    private readonly Channel<JobCommand> _channel;
    private bool _isJobRunning = false;
    private int _executionCount = 0;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("JobProcessor iniciado. Esperando comandos...");

        // ✅ Patrón recomendado por Microsoft: WaitToReadAsync + TryRead
        // Más eficiente que ReadAllAsync para alta concurrencia
        while (await _channel.Reader.WaitToReadAsync(stoppingToken))
        {
            while (_channel.Reader.TryRead(out var command))
            {
                try
                {
                    await ProcessCommandAsync(command, stoppingToken);
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, "Error procesando comando");
                    // ✅ Notificar errores al productor
                    command.ResponseTask?.TrySetException(ex);
                }
            }
        }
    }

    private async Task ProcessCommandAsync(JobCommand command, CancellationToken token)
    {
        switch (command.Type)
        {
            case CommandType.Start:
                _isJobRunning = true;
                _ = Task.Run(async () => await RunRecurringJobAsync(token));

                // Enviar respuesta al productor
                command.ResponseTask?.SetResult(new JobStatus 
                { 
                    IsRunning = true, 
                    Message = "Job iniciado" 
                });
                break;

            case CommandType.Stop:
                _isJobRunning = false;
                command.ResponseTask?.SetResult(new JobStatus 
                { 
                    IsRunning = false, 
                    Message = "Job detenido" 
                });
                break;

            case CommandType.GetStatus:
                command.ResponseTask?.SetResult(new JobStatus
                {
                    IsRunning = _isJobRunning,
                    ExecutionCount = _executionCount
                });
                break;
        }
    }
}

WaitToReadAsync() + TryRead(): Patrón recomendado por Microsoft para mejor performance
TrySetException(): Propaga errores al productor de forma segura
Bucle anidado: Procesa múltiples comandos en batch cuando están disponibles

Paso 3: Configurar el Channel y el Servicio

En Program.cs:

// ✅ Bounded Channel con opciones optimizadas (recomendado por Microsoft)
builder.Services.AddSingleton(Channel.CreateBounded<JobCommand>(
    new BoundedChannelOptions(100)
    {
        FullMode = BoundedChannelFullMode.Wait, // Backpressure automático
        SingleWriter = false, // Múltiples endpoints pueden escribir
        SingleReader = true   // Solo un BackgroundService consume
    }));

// Registrar el Background Service
builder.Services.AddHostedService<JobProcessor>();

💡 ¿Bounded vs Unbounded?

Característica	Unbounded	Bounded
Capacidad	Ilimitada	Limitada (configurable)
Memoria	Puede crecer sin control	Controlada
Backpressure	No	Sí (automático)
Uso recomendado	Productores lentos	Productores rápidos
Performance	Writes síncronos	Writes pueden ser async

Modos de Bounded Channel (FullMode):

Wait (recomendado): Espera hasta que haya espacio (backpressure)
DropWrite: Descarta el nuevo elemento
DropOldest: Descarta el elemento más antiguo
DropNewest: Descarta el elemento más reciente

Opciones de optimización:

SingleWriter: true = mejor performance si solo un productor escribe
SingleReader: true = mejor performance si solo un consumidor lee
AllowSynchronousContinuations: false (default) para evitar bloqueos

Paso 4: Crear los Endpoints (Productores)

public static IEndpointRouteBuilder MapJobEndpoints(this IEndpointRouteBuilder app)
{
    var jobGroup = app.MapGroup("api/job");

    jobGroup.MapPost("start", async (Channel<JobCommand> channel) =>
    {
        // Crear TaskCompletionSource para esperar la respuesta
        var tcs = new TaskCompletionSource<JobStatus>();

        var command = new JobCommand
        {
            Type = CommandType.Start,
            ResponseTask = tcs
        };

        // ✅ WriteAsync maneja backpressure automáticamente
        await channel.Writer.WriteAsync(command);

        // Esperar respuesta del consumidor
        var status = await tcs.Task;
        return Results.Ok(status);
    });

    // Endpoints similares para stop y status...

    return app;
}

💡 Flujo:

API recibe request → Crea TaskCompletionSource
Escribe comando en el Channel con WriteAsync() (maneja backpressure)
Espera que el consumidor complete la Task
Retorna la respuesta al cliente

¿Por qué este patrón?

Sin Channels:

// ❌ Locks manuales, propenso a errores
private static readonly object _lock = new();
private static Queue<Command> _queue = new();

public void AddCommand(Command cmd)
{
    lock(_lock) { _queue.Enqueue(cmd); }
}

Con Channels:

// ✅ Thread-safe automático, limpio, con backpressure
await channel.Writer.WriteAsync(command);

Casos de Uso Reales con Channels

1. Cola de Emails/Notificaciones

// Microsoft recomienda Bounded para prevenir OutOfMemory
var emailChannel = Channel.CreateBounded<EmailMessage>(
    new BoundedChannelOptions(1000)
    {
        FullMode = BoundedChannelFullMode.Wait
    });
// API recibe requests → Encola en Channel → Background envía emails en lotes

2. Procesamiento de Imágenes

Channel<ImageProcessingJob> imageChannel;
// Upload de imágenes → Channel → Worker redimensiona/optimiza en background

3. Logs Centralizados

// DropOldest para logs: si está lleno, descarta los más antiguos
var logChannel = Channel.CreateBounded<LogEntry>(
    new BoundedChannelOptions(5000)
    {
        FullMode = BoundedChannelFullMode.DropOldest
    });

4. Rate Limiting / Throttling

var boundedChannel = Channel.CreateBounded<Request>(100);
// Limita a 100 requests concurrentes, el resto espera (backpressure)

5. Event Sourcing Interno

Channel<DomainEvent> eventChannel;
// Eventos de dominio → Channel → Múltiples handlers procesan en paralelo

6. Pipeline de Datos (ejemplo oficial de Microsoft)

// Patrón de processing pipeline con múltiples stages
Channel<RawData> inputChannel;
Channel<ProcessedData> outputChannel;
// Stage 1: Raw → Validated → Stage 2: Validated → Enriched

Usa Channels cuando:

✅ Comunicación dentro de la misma aplicación
✅ Necesitas alta performance y bajo latency
✅ Quieres simplicidad sin infraestructura externa
✅ Trabajas con async/await
✅ Necesitas backpressure automático

Usa Queue externo (RabbitMQ/Azure Service Bus) cuando:

❌ Necesitas comunicación entre múltiples aplicaciones/servicios
❌ Requieres persistencia de mensajes
❌ Necesitas escalabilidad horizontal
❌ Requieres garantías de entrega (at-least-once, exactly-once)

¿Por qué usar Channels?

A lo largo de este tutorial, hemos visto cómo Channels ofrece ventajas significativas:

Simplicidad: No necesitas infraestructura externa para empezar
Performance: Diseñados desde cero para async/await con ValueTask
Seguridad: Thread-safe por diseño, sin preocupaciones por race conditions
Control: Backpressure automático previene sobrecarga del sistema
Flexibilidad: Configuración granular según tus necesidades específicas

Impacto en tu arquitectura

Este patrón es especialmente valioso cuando:

Estás construyendo aplicaciones monolíticas modernas que necesitan procesamiento asíncrono
Quieres reducir costos de infraestructura eliminando dependencias de message brokers
Necesitas optimizar performance con procesamiento en memoria
Buscas simplicidad operacional sin sacrificar escalabilidad vertical

Los Channels de .NET demuestran que no siempre necesitas herramientas complejas para resolver problemas complejos. A veces, la solución más elegante es la que viene incorporada en tu framework.

Próximos Pasos

¿Listo para llevar este conocimiento al siguiente nivel? Aquí tienes algunas ideas para expandir este proyecto:

1. Implementar Múltiples Consumidores

// Escalar procesamiento con múltiples workers
builder.Services.AddHostedService<JobProcessor>(); // Worker 1
builder.Services.AddHostedService<JobProcessor>(); // Worker 2
builder.Services.AddHostedService<JobProcessor>(); // Worker 3

Aprenderás: Paralelización, distribución de carga, sincronización entre workers

2. Integrar Observabilidad

// Métricas con System.Diagnostics.Metrics
var meter = new Meter("BackgroundJobs");
var jobsProcessed = meter.CreateCounter<long>("jobs_processed");
var queueDepth = meter.CreateObservableGauge("queue_depth", 
    () => channel.Reader.Count);

Aprenderás: OpenTelemetry, métricas personalizadas, dashboards con Grafana/Prometheus

3. Implementar Persistencia

// Guardar estado en caso de restart
public class PersistentJobProcessor : BackgroundService
{
    private readonly IJobStateRepository _repository;

    protected override async Task ExecuteAsync(CancellationToken token)
    {
        // Recuperar jobs pendientes al iniciar
        await _repository.RestorePendingJobsAsync(token);
        // ... continuar procesamiento normal
    }
}

Aprenderás: State management, recovery strategies, durabilidad

4. Agregar Pipeline de Procesamiento

// Pipeline multi-etapa
var rawChannel = Channel.CreateBounded<RawData>(100);
var validatedChannel = Channel.CreateBounded<ValidatedData>(100);
var enrichedChannel = Channel.CreateBounded<EnrichedData>(100);

// Stage 1: Validación
builder.Services.AddHostedService<ValidationProcessor>();
// Stage 2: Enriquecimiento
builder.Services.AddHostedService<EnrichmentProcessor>();
// Stage 3: Persistencia
builder.Services.AddHostedService<PersistenceProcessor>();

Aprenderás: Pipeline pattern, ETL processes, data transformation

5. Implementar Rate Limiting Avanzado

// Rate limiter con ventanas deslizantes
public class RateLimitedJobProcessor : BackgroundService
{
    private readonly RateLimiter _rateLimiter;

    protected override async Task ExecuteAsync(CancellationToken token)
    {
        while (await _channel.Reader.WaitToReadAsync(token))
        {
            using var lease = await _rateLimiter.AcquireAsync(1, token);
            if (lease.IsAcquired)
            {
                // Procesar job
            }
        }
    }
}

Aprenderás: Rate limiting patterns, token bucket, leaky bucket

6. Crear Dashboard de Monitoreo

// SignalR para updates en tiempo real
builder.Services.AddSignalR();

// Notificar estado a clientes conectados
await _hubContext.Clients.All.SendAsync("JobStatusUpdate", new {
    QueueDepth = channel.Reader.Count,
    ProcessingRate = jobsPerSecond,
    ActiveJobs = activeJobCount
});

Aprenderás: Real-time updates, SignalR, live dashboards

7. Añadir Resiliencia

// Polly para retry policies
var retryPolicy = Policy
    .Handle<Exception>()
    .WaitAndRetryAsync(3, retryAttempt => 
        TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));

await retryPolicy.ExecuteAsync(async () => 
{
    await ProcessJobAsync(command);
});

Aprenderás: Retry patterns, circuit breakers, fallback strategies

8. Implementar Health Checks

// Health check para el channel
builder.Services.AddHealthChecks()
    .AddCheck<ChannelHealthCheck>("channel_health")
    .AddCheck<JobProcessorHealthCheck>("job_processor_health");

public class ChannelHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync()
    {
        var queueDepth = _channel.Reader.Count;
        return queueDepth < 1000 
            ? HealthCheckResult.Healthy() 
            : HealthCheckResult.Degraded("Queue depth high");
    }
}

Aprenderás: Health monitoring, readiness/liveness probes, Kubernetes integration

9. Migrar a Arquitectura Distribuida

// Cuando crezcas más allá de un solo servidor
// Considera migrar a:
// - Azure Service Bus para messaging distribuido
// - Azure Queue Storage para simplicidad y bajo costo
// - RabbitMQ para control total
// - Redis Streams para alta performance

// Mantén la misma interfaz, cambia la implementación
public interface IJobQueue
{
    Task EnqueueAsync(JobCommand command);
    Task<JobCommand> DequeueAsync(CancellationToken token);
}

// Implementación con Channels (actual)
public class InMemoryJobQueue : IJobQueue { }

// Implementación con Azure Service Bus (futuro)
public class ServiceBusJobQueue : IJobQueue { }

Aprenderás: Estrategias de migración, abstracciones, arquitectura evolutiva

Recursos para Continuar Aprendiendo

Documentación Oficial:

Artículos Avanzados:

[Parte 4] Construyendo un Agente Conversacional con el Agent Framework de Semantic Kernel

Isaac Ojeda — Sat, 19 Jul 2025 18:56:35 +0000

🧠 Crea tu propio agente conversacional con Semantic Kernel

¿Te imaginas construir un asistente conversacional que entienda lenguaje natural y, además, sea capaz de ejecutar funciones reales de tu sistema? Con el Agent Framework de Semantic Kernel, eso ya no es solo posible, sino sorprendentemente sencillo.

En este tutorial te voy a mostrar cómo crear un agente inteligente especializado en gestión de facturas, diseñado para ayudar a abogados en una notaría pública. Este agente no solo entiende lo que le pides, sino que también puede:

Consultar el estado de una factura.
Crear prefacturas automáticamente.
Ver facturas vencidas.
Marcar facturas como pagadas.
Obtener información detallada de un cliente.

Todo esto lo logra invocando funciones reales en C#, conectadas a una base de datos real y expuestas mediante un plugin personalizado.

Durante el artículo veremos paso a paso:

Cómo configurar Semantic Kernel con Azure OpenAI.
Cómo definir tus propias funciones con [KernelFunction].
Cómo crear un ChatCompletionAgent con instrucciones personalizadas.
Cómo ejecutar al agente dentro de una API HTTP.
Y cómo mantener conversaciones con historial persistente.

Además, el proyecto incluye un cliente web de ejemplo (tipo chat) para que puedas probarlo todo en vivo y adaptar la solución a tus propios casos de uso.

🔗 Todo el código está disponible en este repositorio:

github.com/isaacOjeda/DevToPosts/tree/main/SemanticKernelSeries/SemanticKernelLearning04

🧠 ¿Qué es el Agent Framework en Semantic Kernel?

El Agent Framework es una de las capacidades más potentes introducidas en las versiones recientes de Semantic Kernel: un sistema que permite crear agentes conversacionales inteligentes con la capacidad de razonar, planificar e invocar funciones definidas por el desarrollador para lograr un objetivo.

A diferencia de un chatbot tradicional basado en reglas, un agente en Semantic Kernel:

Comprende instrucciones en lenguaje natural.
Decide qué acciones tomar en base al contexto disponible.
Invoca funciones (también llamadas “skills” o “plugins”) que tú defines en código.
Puede encadenar múltiples pasos de razonamiento para llegar a un resultado.

Este modelo es ideal para construir asistentes especializados con conocimientos de negocio y herramientas personalizadas.

🎯 Caso de uso: un asistente de facturación

En este tutorial vamos a construir un ejemplo real usando el Agent Framework: un asistente conversacional para abogados en una notaría pública, cuya función es gestionar facturas mediante lenguaje natural.

El asistente será capaz de:

Verificar si una factura está pagada o vencida.
Crear prefacturas para clientes nuevos.
Consultar el listado de facturas pendientes de pago.
Marcar una factura como pagada.
Obtener información detallada de un cliente y su historial de facturación.

Todo esto será posible gracias a una capa de funciones en C# expuestas al agente mediante anotaciones [KernelFunction], y alimentadas por un servicio de backend que accede a la base de datos.

🧬 ¿Por qué usar agentes en lugar de comandos o controladores tradicionales?

Con el Agent Framework:

El usuario no necesita conocer los comandos disponibles.
El agente elige por sí mismo la función que debe usar.
Puedes cambiar o extender el comportamiento del sistema sin modificar el frontend.
La experiencia es más natural, fluida y adaptable a distintos usuarios.

Esto hace que construir asistentes LLM especializados con Semantic Kernel sea una excelente opción para interfaces inteligentes sobre sistemas de negocio existentes, especialmente en entornos con operaciones rutinarias, como la gestión de facturas.

⚙️ Requisitos previos y setup del entorno

Antes de construir nuestro asistente de facturación, necesitamos preparar nuestro proyecto con las dependencias necesarias y configurar el acceso a un modelo de lenguaje compatible (en este caso, Azure OpenAI).

Este ejemplo está construido sobre .NET 9, con soporte para SQLite como base de datos local, y aprovecha la integración entre Semantic Kernel y Azure OpenAI.

🗂️ Puedes consultar el código completo y funcional de este proyecto en el repositorio:

🔗 github.com/isaacOjeda/DevToPosts/tree/main/SemanticKernelSeries/SemanticKernelLearning04

Allí encontrarás todos los archivos de configuración, modelos, servicios y ejemplos necesarios para correr este asistente de forma local o integrarlo en tu aplicación.

📦 Paquetes necesarios

El Agent Framework se encuentra dentro del paquete Microsoft.SemanticKernel.Agents.Core, por lo que debes incluir explícitamente las dependencias en tu archivo .csproj.

<ItemGroup>
  <PackageReference Include="Microsoft.SemanticKernel" Version="1.60.0" />
  <PackageReference Include="Microsoft.SemanticKernel.Agents.Core" Version="1.60.0" />
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.7" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="9.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.0" />
  <PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.22.1" />
</ItemGroup>

Esto nos da acceso al núcleo de Semantic Kernel, las capacidades de agentes, así como herramientas necesarias para la persistencia y desarrollo web.

🧪 Configurando el Kernel

El kernel es el núcleo que conecta el modelo de lenguaje con tus plugins. En este ejemplo, usamos Azure OpenAI para procesar instrucciones en lenguaje natural. A continuación se muestra cómo configurar el kernel con los valores de appsettings.json:

public static IServiceCollection AddSemanticKernel(this IServiceCollection services, IConfiguration configuration)
{
    var azureOpenAIConfig = configuration.GetSection("AzureOpenAI");

    services.AddAzureOpenAIChatCompletion(
        deploymentName: azureOpenAIConfig["DeploymentName"]!,
        apiKey: azureOpenAIConfig["ApiKey"]!,
        endpoint: azureOpenAIConfig["Endpoint"]!,
        modelId: azureOpenAIConfig["ModelId"]!
    );

    services.AddTransient(serviceProvider => new Kernel(serviceProvider));

    return services;
}

La configuración en appsettings.json se vería algo así:

"AzureOpenAI": {
  "DeploymentName": "notaria-assistant",
  "ApiKey": "TU_API_KEY",
  "Endpoint": "https://tuservicio.openai.azure.com/",
  "ModelId": "gpt-35-turbo"
}

Con esto, el Kernel queda disponible vía inyección de dependencias y listo para clonar, personalizar o conectar a nuestros agentes.

🧱 Servicios base y modelos de dominio

Nuestro agente necesita acceder a datos del mundo real, por lo que construimos un servicio InvoiceService con métodos como:

GetInvoiceByNumberAsync
CreateInvoiceAsync
MarkInvoiceAsPaidAsync
GetUnpaidInvoicesAsync
GetCustomerByEmailAsync

Este servicio será inyectado en el plugin que veremos en la próxima sección, y expone la lógica de negocio que el agente puede usar para resolver instrucciones. Si ya tienes una capa de servicios en tu aplicación, puedes integrarla directamente.

🧩 Definir tus funciones (skills/plugins)

Una de las capacidades más poderosas del Agent Framework es permitir que tus agentes ejecuten funciones reales escritas en C#. Estas funciones se registran como "plugins" usando decoradores especiales, y luego el agente las puede invocar cuando detecta que son necesarias para cumplir una instrucción del usuario.

En este caso, hemos creado un plugin llamado InvoicesPlugin, que expone cinco funciones relacionadas con facturación. Cada una está decorada con el atributo [KernelFunction], lo que la hace visible para Semantic Kernel.

🧠 ¿Qué es un plugin?

Un plugin en Semantic Kernel es simplemente una clase con métodos públicos asincrónicos decorados con [KernelFunction]. Además, puedes usar [Description] en los parámetros y métodos para mejorar la comprensión del agente sobre lo que hace cada función.

🗂️ El código completo del plugin puede consultarse en el repositorio:

Ver InvoicesPlugin.cs en GitHub

🧾 Ejemplo 1: Verificar el estado de una factura

[KernelFunction]
[Description("Verifica el estado de pago de una factura específica usando su número de factura.")]
public async Task<string> VerifyPaymentAsync(
    [Description("Número de la factura a verificar (ej: INV-202412-0001)")] string numeroFactura)
{
    var invoice = await invoiceService.GetInvoiceByNumberAsync(numeroFactura);

    if (invoice == null)
        return $"❌ No se encontró ninguna factura con el número: {numeroFactura}";

    var result = new StringBuilder();
    result.AppendLine($"📋 **Factura: {invoice.InvoiceNumber}**");
    result.AppendLine($"🔸 Estado: {GetStatusText(invoice.Status)}");
    // ...otros campos visuales

    return result.ToString();
}

💡 Nota:

En este ejemplo, todas las funciones del plugin reciben y retornan datos en formato string, ya que el enfoque está en mantener el ejemplo simple y fácil de seguir.

Sin embargo, el Agent Framework de Semantic Kernel soporta objetos complejos como parámetros de entrada y salida. Puedes retornar clases personalizadas, listas u objetos anidados, y el agente será capaz de interpretarlos, formatearlos o incluso razonar sobre ellos en sus respuestas.

En un escenario real, podrías devolver una InvoiceDetail con propiedades estructuradas en lugar de una cadena formateada, lo que abre la puerta a integraciones más ricas o adaptadas al canal (por ejemplo, APIs, UIs o chatbots).

Este método se encarga de buscar una factura por número y devolver su estado, fecha de vencimiento, monto y otra información útil. Como puedes ver, el resultado se formatea para ser legible y amigable, incluyendo emojis para mejorar la experiencia.

✍️ Ejemplo 2: Crear una prefactura

[KernelFunction]
[Description("Realiza una prefactura para un cliente usando email, descripción, monto y días hasta el vencimiento.")]
public async Task<string> CreateInvoiceDraftAsync(
    string clienteEmail,
    string descripcion,
    decimal monto,
    int diasVencimiento = 30)
{
    var customer = await invoiceService.GetCustomerByEmailAsync(clienteEmail);
    if (customer == null)
        return $"❌ No se encontró ningún cliente con el email: {clienteEmail}";

    var dueDate = DateTime.UtcNow.AddDays(diasVencimiento);
    var invoice = await invoiceService.CreateInvoiceAsync(
        customer.Id, descripcion, monto, dueDate, "Factura generada automáticamente");

    return $"✅ Prefactura creada: {invoice.InvoiceNumber} para {customer.Name}";
}

Este método genera una factura en estado "borrador", útil para cuando un abogado quiere adelantar una facturación para un cliente específico.

🧠 ¿Por qué usar `[KernelFunction]`?

Al decorar tus funciones con este atributo, estás dando al agente la capacidad de:

Descubrir qué herramientas tiene disponibles.
Seleccionar de forma automática la función correcta en base a la intención del usuario.
Combinar funciones si es necesario (por ejemplo, buscar cliente → generar factura).

Gracias a esto, no necesitas escribir prompts complejos ni reglas condicionales. El agente decide qué hacer en tiempo de ejecución.

🤖 Crear un agente y asignarle objetivos

Una vez que tenemos definido nuestro plugin con las funciones necesarias, es hora de crear un agente que lo utilice. Un agente es una instancia del tipo ChatCompletionAgent que sabe cómo interactuar con un modelo de lenguaje, tiene acceso a un conjunto de funciones y puede operar con base en instrucciones personalizadas.

En este paso lo conectamos todo: el kernel, el plugin, y la intención del asistente.

🧠 ¿Qué es un `ChatCompletionAgent`?

El ChatCompletionAgent es una implementación del Agent Framework de Semantic Kernel que permite interactuar con modelos de lenguaje compatibles (como GPT-4 o GPT-3.5) de forma conversacional. Este tipo de agente:

Usa un kernel preconfigurado con modelos y funciones.
Puede tener instrucciones personalizadas (“persona” o “rol”).
Decide automáticamente qué función usar, si corresponde.
Mantiene un contexto conversacional.

🏗️ Registrando el agente con DI

En este ejemplo, configuramos el agente como un servicio usando la extensión AddAgents. Esto permite que el agente se cree con acceso al kernel y al InvoicesPlugin:

services.AddKeyedTransient<ChatCompletionAgent>("AssistantAgent", (sp, _) =>
{
    var kernel = sp.GetRequiredService<Kernel>();
    var agentKernel = kernel.Clone();

    // Registramos el plugin de facturas
    var invoiceService = sp.GetRequiredService<InvoiceService>();
    agentKernel.ImportPluginFromObject(new InvoicesPlugin(invoiceService));

    var agent = new ChatCompletionAgent()
    {
        Name = "Asistente",
        Instructions = """
            Eres un asistente de abogados en una notaría pública. 
            Tu tarea es ayudar a los abogados a gestionar y verificar el estado de las facturas.

            Funciones disponibles:
            - Verificar el estado de pago de facturas específicas
            - Crear prefacturas para clientes
            - Consultar facturas pendientes de pago
            - Marcar facturas como pagadas
            - Consultar información de clientes

            Siempre proporciona información clara y detallada sobre el estado de las facturas.
            Usa emojis para hacer las respuestas más visuales y fáciles de entender.
        """,
        Kernel = agentKernel,
        Arguments = new KernelArguments(
            new OpenAIPromptExecutionSettings()
            {
                FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
            })
    };

    return agent;
});

🧩 Este agente se construye a partir de un Kernel clonado. Así puedes tener múltiples agentes con diferentes plugins, instrucciones o configuraciones sin interferencias entre ellos.

🗣️ Instrucciones: cómo le decimos al agente quién es

La propiedad Instructions permite definir la personalidad, contexto y objetivos del agente. Aquí estamos usando un sistema de "prompt largo" al estilo system message:

Instructions = """
    Eres un asistente de abogados en una notaría pública. 
    Tu tarea es ayudar a los abogados a gestionar y verificar el estado de las facturas.
    ...
"""

Este mensaje guía al modelo para que entienda el contexto en el que opera, el lenguaje que debe usar y el tipo de resultados esperados.

⚙️ Control de funciones automáticas

El fragmento clave para habilitar la selección automática de funciones es:

Arguments = new KernelArguments(
    new OpenAIPromptExecutionSettings()
    {
        FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
    })

Esto permite que el modelo analice la intención del usuario y decida si debe invocar alguna función del plugin registrado. No es necesario indicarle explícitamente el nombre de la función: el agente elige por sí mismo en función del mensaje recibido.

Con este paso, ya tenemos un asistente especializado corriendo sobre Semantic Kernel, con acceso completo a las funciones del plugin de facturación y configurado para operar en el contexto de una notaría pública.

🚀 Ejecutar el agente y manejar conversaciones

Una vez que nuestro agente está registrado y conectado a sus funciones, llega el momento de ponerlo en acción. En este ejemplo, creamos una API HTTP que permite a cualquier cliente (como una app web o móvil) interactuar con el asistente de forma conversacional.

Todo el ciclo se orquesta desde un conjunto de endpoints dentro de AgentEndpoints.cs.

🌐 Endpoint para iniciar una conversación

El primer paso en cualquier interacción es crear un hilo de conversación. Esto permite almacenar el historial y mantener contexto entre múltiples mensajes.

group.MapPost("/start", async (ConversationService conversationService) =>
{
    var conversationId = await conversationService.CreateConversationAsync();
    return Results.Ok(new { ConversationId = conversationId });
});

Este endpoint genera un ConversationId único que luego será utilizado en cada mensaje posterior. La conversación se almacena en la base de datos con su historial asociado.

💬 Enviar una pregunta al agente

El segundo endpoint es el más importante: recibe un mensaje del usuario y devuelve la respuesta del agente. Lo interesante es que reconstruye el historial completo antes de invocar el modelo, lo que permite mantener coherencia y continuidad.

group.MapPost("/", async (AskQuestionRequest request,
    [FromKeyedServices("AssistantAgent")] ChatCompletionAgent agent,
    ConversationService conversationService) =>
{
    // ... Obtener historial desde base de datos
    // ... Agregar mensaje del usuario actual
    // ... Crear ChatHistoryAgentThread y lanzar la invocación
});

📜 Cómo se construye el historial

El historial de conversación se crea a partir de los mensajes previos almacenados en la base de datos:

var chatHistory = new ChatHistory();
foreach (var dbMessage in conversation.Messages)
{
    if (dbMessage.Role == "user")
        chatHistory.AddUserMessage(dbMessage.Content);
    else if (dbMessage.Role == "assistant")
        chatHistory.AddAssistantMessage(dbMessage.Content);
}

Después se añade el nuevo mensaje del usuario, y se encapsula todo en un ChatHistoryAgentThread, que es el tipo de contexto que entiende el agente:

chatHistory.AddUserMessage(request.Question);
var thread = new ChatHistoryAgentThread(chatHistory, request.ThreadId);

🧠 Ejecutar al agente y procesar respuestas

El agente se invoca de forma asíncrona usando InvokeAsync, lo que permite recibir múltiples respuestas si el modelo decide dividir su salida (especialmente útil cuando hay invocación de funciones):

var responses = agent.InvokeAsync(request.Question, thread);

var allResponses = new List<string>();
await foreach (var agentResponse in responses)
{
    var content = agentResponse.Message.Content ?? string.Empty;
    if (!string.IsNullOrWhiteSpace(content))
    {
        allResponses.Add(content);
    }
}

Luego se combinan todas las respuestas en un solo mensaje y se guarda nuevamente en la base de datos:

var finalResponse = string.Join("\n\n", allResponses);
await conversationService.AddMessageAsync(request.ThreadId, finalResponse, "assistant");

✅ Respuesta final

El resultado es una experiencia completamente conversacional, persistente y con funciones automatizadas. El cliente (por ejemplo, una SPA en Blazor o React) solo necesita enviar preguntas con un ConversationId y mostrar las respuestas generadas.

📌 ¿Por qué usar historial y contexto?

Esto es clave para que el agente pueda entender preguntas como:

“¿Y esa factura de Juan ya se pagó?”

Sin historial, el modelo no sabría a qué se refiere “esa factura”. Al mantener contexto, el agente puede hacer inferencias y ejecutar funciones con mayor precisión.

Con esto, tenemos todo lo necesario para una experiencia de agente conversacional real, persistente, funcional y extensible.

📁 Nota:

Recuerda que el código completo está disponible en el repositorio, incluyendo el contexto de la base de datos y la implementación completa de ConversationService, que se encarga de crear conversaciones, almacenar mensajes y reconstruir el historial.

🔗 Ver el proyecto en GitHub

🧰 Extras, buenas prácticas y posibles extensiones

Hasta este punto ya tienes un agente conversacional funcional, conectado a un modelo de lenguaje, con un plugin personalizado, y persistencia completa de las conversaciones. Sin embargo, el Agent Framework de Semantic Kernel ofrece muchas oportunidades para llevar tu solución al siguiente nivel.

A continuación, te comparto algunas ideas para extender o mejorar tu asistente.

🔗 Agentes con múltiples plugins

El Kernel puede importar múltiples plugins, no solo uno. Por ejemplo, podrías tener:

InvoicesPlugin: para gestión de facturas.
CalendarPlugin: para gestionar eventos o vencimientos.
EmailPlugin: para enviar notificaciones automáticas.

agentKernel.ImportPluginFromObject(new CalendarPlugin(...));
agentKernel.ImportPluginFromObject(new EmailPlugin(...));

Esto permite que el mismo agente decida qué herramienta usar dependiendo del mensaje del usuario, sin que tengas que escribir lógica adicional.

🧠 Agentes que planifican múltiples pasos

El Agent Framework incluye soporte experimental para planificación automática, donde el modelo puede decidir ejecutar múltiples funciones encadenadas para lograr un objetivo complejo.

Por ejemplo:

“Crea una prefactura para Carlos y márcala como pagada.”

Esto podría generar un plan con dos pasos: CreateInvoiceDraftAsync → MarkInvoiceAsPaidAsync.

El agente puede manejar estas secuencias si se configura con FunctionCalling en modo Auto() y si las funciones están bien descritas.

🧪 Testing y depuración

Cuando construyes agentes que llaman funciones reales, es importante:

Probar con mensajes ambiguos o incompletos para ver cómo reacciona el agente.
Monitorear los logs de funciones invocadas.
Verificar qué parámetros está eligiendo el modelo.
Utilizar FunctionResult para obtener metadata sobre las llamadas.

También puedes capturar los mensajes generados por el modelo para analizarlos más adelante, por ejemplo, almacenando las decisiones o planes generados en una tabla de auditoría.

⚠️ Cuida la experiencia conversacional

Algunos consejos prácticos para que el asistente se sienta más natural:

Usa emojis y lenguaje cercano si el público lo permite (como hicimos aquí).
Asegúrate de que las respuestas siempre incluyan lo esencial, incluso si no hay datos (ej: “no hay facturas vencidas”).
Controla el tamaño del historial para evitar prompts excesivamente largos.
Maneja errores con mensajes claros: si una factura no existe, si el email es inválido, etc.

🧩 Integración con interfaces visuales

Aunque este ejemplo se enfoca en la API HTTP y el backend del agente, la interacción no termina ahí. Puedes conectar este agente conversacional a diferentes interfaces gráficas según tu contexto:

Una aplicación web (por ejemplo, Blazor, React, Angular).
Un chatbot embebido en tu intranet o sitio público.
Clientes móviles nativos.
Canales como Microsoft Teams, Telegram o WhatsApp.

💬 Importante:

El repositorio del proyecto incluye un chat funcional ya implementado que se comunica con esta API y permite mantener conversaciones con el agente.

Este cliente está disponible como referencia y punto de exploración: puedes ver cómo se estructuran los hilos, cómo se muestra el historial y cómo se consume el endpoint /api/agent.

🔗 Ver el repositorio en GitHub

Este ejemplo es ideal para experimentar con el flujo completo: desde el frontend que envía preguntas, hasta el agente que responde y persiste el historial.

🌱 ¿Qué más podrías construir con este enfoque?

El Agent Framework es ideal para automatizar tareas repetitivas en sistemas internos. Algunos ejemplos reales donde este enfoque encaja:

Asistentes de soporte técnico interno (consultar errores, reiniciar servicios).
Asistentes legales que redactan contratos o extraen cláusulas.
Agentes que combinan datos de distintas fuentes (facturas + clientes + CRM).
Robots de backoffice que ayudan a generar informes o consolidar información.

📌 Consejo final:

Piensa en tu agente como un colega digital: cuantas más herramientas le des, más tareas podrá resolver sin que tú tengas que intervenir manualmente.

✅ Conclusión

El Agent Framework de Semantic Kernel abre una puerta poderosa para construir aplicaciones inteligentes que combinan lenguaje natural con lógica de negocio real. En este artículo, creamos un agente conversacional especializado en facturación, capaz de razonar sobre peticiones del usuario e invocar funciones de una aplicación en .NET.

Hemos visto cómo:

Configurar un Kernel con Azure OpenAI.
Exponer funciones reales como plugins usando [KernelFunction].
Construir y personalizar un agente con instrucciones específicas.
Mantener conversaciones persistentes con historial contextual.
Integrar todo en una API funcional, lista para usarse desde un cliente.

Este enfoque es aplicable a muchísimos casos reales: desde automatización interna hasta asistentes legales, técnicos o administrativos.

💡 Lo mejor de todo es que puedes extender esta base fácilmente: agregar nuevos plugins, integrar fuentes de datos adicionales, o escalar hacia canales como webchat, Teams o bots en producción.

Si te interesa explorar más sobre cómo usar Semantic Kernel en escenarios del mundo real, o quieres construir asistentes más sofisticados, este es apenas el comienzo.

🔗 Recuerda que el código completo está disponible aquí:

github.com/isaacOjeda/DevToPosts/tree/main/SemanticKernelSeries/SemanticKernelLearning04

📚 Referencias

Si quieres seguir explorando el Agent Framework de Semantic Kernel y todas sus posibilidades en C#, aquí tienes enlaces oficiales de documentación que complementan lo visto en este artículo:

Semantic Kernel – Parte 03: Embeddings y Retrieval-Augmented Generation (RAG)

Isaac Ojeda — Sun, 16 Feb 2025 17:00:31 +0000

Introducción

En esta tercera parte de nuestra serie sobre Semantic Kernel, nos adentramos en la integración de Embeddings y Retrieval-Augmented Generation (RAG) para mejorar la generación de contenido y la recuperación de información. Utilizando herramientas como Ollama para la creación de embeddings y Qdrant como vector store, podemos construir sistemas más inteligentes capaces de generar respuestas más precisas basadas en datos externos y actualizados, en lugar de depender únicamente de los datos con los que fue entrenado el modelo. A través de esta configuración, aprovechamos la sinergia entre el poder de los modelos de lenguaje y la capacidad de búsqueda semántica para proporcionar soluciones más efectivas a las consultas de los usuarios. En este artículo, exploraremos cómo implementar estas tecnologías en Semantic Kernel, con ejemplos prácticos para configurar los servicios y gestionar los embeddings de manera eficiente.

¿Qué son los Embeddings?

Los embeddings son representaciones numéricas de texto en un espacio vectorial de alta dimensión. Estas representaciones permiten medir la similitud semántica entre palabras, frases o documentos completos. En el contexto de Semantic Kernel, los embeddings se utilizan para mejorar la búsqueda de información y la generación de respuestas basadas en conocimiento almacenado.

Características clave de los Embeddings:

Capturan el significado semántico del texto.
Permiten encontrar contenido relacionado aunque no se utilicen exactamente las mismas palabras.
Se almacenan en bases de datos especializadas llamadas vector stores (como Qdrant).
Se generan con modelos de lenguaje avanzados, como los proporcionados por Ollama u Open AI.

¿Qué es RAG (Retrieval-Augmented Generation)?

Retrieval-Augmented Generation (RAG) es una técnica que combina la recuperación de información con la generación de respuestas mediante un modelo de lenguaje. En lugar de confiar solo en los datos con los que fue entrenado el modelo, RAG permite buscar información relevante en bases de conocimiento externas y utilizarla para generar respuestas más precisas y actualizadas.

Funcionamiento de RAG en Semantic Kernel:

Consulta del usuario: Un usuario hace una pregunta o solicitud.
Búsqueda semántica:
- Se generan embeddings de la consulta.
- Se comparan con los embeddings almacenados en el vector store (Qdrant) para recuperar información relevante.
Generación de respuesta:
- La información recuperada se pasa como contexto al modelo de lenguaje.
- Se genera una respuesta más precisa y fundamentada en los datos encontrados.

Beneficios de RAG en Semantic Kernel:

Mejor comprensión de consultas: Permite obtener respuestas relevantes incluso si el usuario no usa palabras exactas.
Conocimiento actualizado: Se pueden agregar nuevos datos al sistema sin necesidad de reentrenar el modelo de IA.
Optimización del procesamiento: Reduce el costo computacional al recuperar solo la información relevante en lugar de analizar todo el corpus de datos.

Configurando Semantic Kernel con Embeddings y un Vector Store

En esta sección, configuraremos Semantic Kernel para trabajar con Embeddings y un Vector Store, utilizando Aspire para orquestar los servicios.

Los servicios principales que vamos a configurar son:

llama3.2: Modelo generador de texto.
nomic-embed-text: Modelo generador de embeddings.
Qdrant: Almacenamiento y recuperación de embeddings.
Aspire: Orquestación y despliegue de los servicios.

Configuración de Aspire

Aspire nos permite definir y gestionar los servicios necesarios en un solo archivo de configuración. En este caso, configuramos Qdrant como nuestro vector store y llama3.2 y nomic-embed-text como proveedor de embeddings.

Nota 💡: Esto ya lo hemos visto en los otros posts, siempre usa como referencia el código fuente (DevToPosts/SemanticKernelSeries/SemanticKernelLearning03 at main · isaacOjeda/DevToPosts) para más información.

var builder = DistributedApplication.CreateBuilder(args);

// Configuración de Qdrant
var qdrant = builder.AddQdrant("qdrant")
    .WithLifetime(ContainerLifetime.Persistent);

// Configuración de Ollama
var ollama =
    builder.AddOllama("ollama")
        .WithDataVolume()
        .WithOpenWebUI();

// Modelos de Ollama
var llamaModel = ollama.AddModel("llama", "llama3.2");
var embedding = ollama.AddModel("embed-text", "nomic-embed-text");

// Configuración del API Service con referencias a los modelos y Qdrant
var apiService = builder.AddProject<Projects.SemanticKernelLearning03_ApiService>("apiservice")
    .WithReference(llamaModel)
    .WithReference(embedding)
    .WithReference(qdrant);

// Construcción y ejecución de Aspire
builder.Build().Run();

Qdrant se configura como un servicio persistente.
- Se hace de esta forma para que no sea tan lento de inicializar en cada inicio de Aspire.
Ollama se configura con almacenamiento de datos y una interfaz web.
- Se añaden los modelos "llama3.2" para generación de texto y "nomic-embed-text" para embeddings.
Por último se agrega nuestra API en ASP.NET Core.
Configuración de Semantic Kernel con Aspire

Aspire se encargará de inyectar las cadenas de conexión en la API, según los nombres definidos en la configuración.

Para hacer que Semantic Kernel utilice correctamente los servicios orquestados por Aspire, debemos procesar estas cadenas de conexión. Como lo hemos hecho en ejemplos anteriores, parsearemos la información recibida y estructuraremos mejor nuestra configuración.

Para lograr esto, separaremos la configuración de dependencias en un archivo específico, lo que nos permitirá mantener un código más limpio y modular.

Creando `DependencyConfig.cs` para gestionar las dependencias

En este archivo, crearemos el método de extensión AddSemanticKernel, el cual:

Obtiene las cadenas de conexión inyectadas por Aspire.
Extrae los detalles necesarios de Ollama (para generación de texto y embeddings).
Extrae la información de conexión a Qdrant (Vector Store).
Registra los servicios de Semantic Kernel con las dependencias configuradas.
Agrega un servicio de búsqueda semántica (ITextSearch) que permite realizar búsquedas en una colección de vectores, el cual usaremos más adelante.

Aquí está el código en DependencyConfig.cs:

public static class DependencyConfig
{
    public static void AddSemanticKernel(this WebApplicationBuilder builder)
    {
        var (endpoint, completionModel) =
            GetModelDetailsFromConnectionString(builder.Configuration.GetConnectionString("llama")!);
        var (_, embeddingModel) =
            GetModelDetailsFromConnectionString(builder.Configuration.GetConnectionString("embed-text")!);
        var (host, port, apiKey) =
            GetQdrantDetailsFromConnectionString(builder.Configuration.GetConnectionString("qdrant")!);

        builder.Services.AddKernel()
            .AddOllamaChatCompletion(completionModel, endpoint)
            .AddOllamaTextEmbeddingGeneration(embeddingModel, endpoint)
            .AddQdrantVectorStore(host: host, port: port, apiKey: apiKey);

        builder.Services.AddKeyedTransient<ITextSearch>(BlogPost.VectorName, (sp, _) =>
        {
            var vectorStore = sp.GetRequiredService<IVectorStore>();
            var embeddingGenerationService = sp.GetRequiredService<ITextEmbeddingGenerationService>();

            var blogposts = vectorStore.GetCollection<Guid, BlogPost>(BlogPost.VectorName);

            blogposts.CreateCollectionIfNotExistsAsync().ConfigureAwait(true);

            var textSearch = new VectorStoreTextSearch<BlogPost>(blogposts, embeddingGenerationService);

            return textSearch;
        });
    }
}

Explicación del código

Obtenemos los detalles de conexión
- GetModelDetailsFromConnectionString extrae el modelo y endpoint desde las cadenas de conexión de Ollama (chat y embeddings).
- GetQdrantDetailsFromConnectionString extrae el host, puerto y API key de Qdrant.
Registramos los servicios de Semantic Kernel
- AddOllamaChatCompletion para generación de texto con Ollama.
- AddOllamaTextEmbeddingGeneration para generación de embeddings.
- AddQdrantVectorStore para almacenar y recuperar datos desde Qdrant.
Configuramos un servicio de búsqueda semántica (ITextSearch)
- Se obtiene la colección de vectores asociada a BlogPost.
- Si la colección no existe, se crea automáticamente en Qdrant.
- Se inicializa un objeto VectorStoreTextSearch<BlogPost>, permitiendo realizar búsquedas semánticas en la colección.

Almacenando Embeddings en Qdrant

Para almacenar datos en Qdrant, primero debemos definir nuestro modelo de datos que será indexado en la base de datos vectorial.

En este ejemplo, queremos guardar una serie de posts y realizar búsquedas semánticas sobre su contenido.

Advertencia ⚠️: Las búsquedas vectoriales que estamos viendo aquí están en Preview (Alpha), por lo que podrían cambiar en el futuro. Actualmente, no se recomienda su uso en producción, a menos que estés dispuesto a evolucionar junto con el framework.
Anteriormente, se utilizaban los Memory de Semantic Kernel para búsquedas similares, pero estos están en proceso de ser considerados "Legacy", por lo que su uso a largo plazo podría no ser viable.

Definición del modelo `BlogPost`

El modelo BlogPost representará las entradas del blog en nuestra base de datos vectorial.

public class BlogPost
{
    public const string VectorName = "blogposts";

    [VectorStoreRecordKey]
    [TextSearchResultLink]
    public Guid BlogPostId { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    [TextSearchResultName]
    public string Title { get; set; }

    [VectorStoreRecordData(IsFullTextSearchable = true)]
    [TextSearchResultValue]
    public string Description { get; set; }

    [VectorStoreRecordVector(768, DistanceFunction.DotProductSimilarity, IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    public string[] Tags { get; set; }
}

Atributos de BlogPost:

BlogPostId: Identificador único del post. Se marca como clave primaria con [VectorStoreRecordKey] y como enlace de resultados de búsqueda con [TextSearchResultLink].
Title: Almacena el título del post. Usado como filtro con [VectorStoreRecordData(IsFilterable = true)] y como nombre principal en los resultados de búsqueda con [TextSearchResultName].
Description: Contiene el contenido del post. Es indexado para búsquedas de texto completo con [VectorStoreRecordData(IsFullTextSearchable = true)] y su valor es mostrado en los resultados con [TextSearchResultValue].
DescriptionEmbedding: Representación vectorial de Description. Almacenado como un vector de 768 dimensiones usando [VectorStoreRecordVector], con DotProductSimilarity como función de distancia y Hnsw para indexación eficiente.
Tags: Etiquetas relacionadas con el post. Pueden ser usadas como filtros en consultas con [VectorStoreRecordData(IsFilterable = true)]. ### Creando un endpoint para almacenar BlogPost en Qdrant

Para guardar nuevos BlogPost, crearemos un endpoint que recibirá los datos del post, generará su embedding y lo almacenará en la base de datos vectorial.

Nuestro servicio ya tiene configurados ITextEmbeddingGenerationService (para generar embeddings) e IVectorStore (para interactuar con Qdrant).

public static class CreateBlogPost
{
    public record Request(string Title, string Description, string[] Tags);

    public record Response(Guid BlogPostId);

    public class Handler
    {
        private readonly ITextEmbeddingGenerationService _embeddingService;
        private readonly IVectorStore _vectorStore;

        public Handler(ITextEmbeddingGenerationService embeddingService, IVectorStore vectorStore)
        {
            _embeddingService = embeddingService;
            _vectorStore = vectorStore;
        }

        public async Task<Response> Handle(Request request, CancellationToken ct)
        {
            var blogposts = _vectorStore.GetCollection<Guid, BlogPost>(BlogPost.VectorName);

            await blogposts.CreateCollectionIfNotExistsAsync(ct);

            var embeddingContents =
                await _embeddingService.GenerateEmbeddingAsync(request.Description, cancellationToken: ct);

            var newBlogPost = new BlogPost
            {
                BlogPostId = Guid.NewGuid(),
                Title = request.Title,
                Description = request.Description,
                DescriptionEmbedding = embeddingContents,
                Tags = request.Tags
            };

            await blogposts.UpsertAsync(newBlogPost, cancellationToken: ct);

            return new Response(newBlogPost.BlogPostId);
        }
    }
}

Explicación del código

Manejador (Handler)
- Recibe los servicios ITextEmbeddingGenerationService y IVectorStore a través del constructor.
Lógica del método Handle
- Obtiene la colección blogposts de Qdrant.
- Si la colección no existe, la crea con CreateCollectionIfNotExistsAsync().
- Genera el embedding del Description usando _embeddingService.GenerateEmbeddingAsync().
- Crea un BlogPost con los datos proporcionados y el embedding generado.
- Guarda el post en Qdrant con UpsertAsync(), que inserta o actualiza el registro.

Nota 💡: Para ver cómo este handler se integra con Minimal APIs, revisa el código fuente del proyecto. Para mantener este artículo conciso, omitiremos detalles específicos.

Probando el endpoint con `api.http`

Para poblar la base de datos vectorial, podemos hacer una solicitud HTTP de prueba.

Ejemplo en SemanticKernelLearning03.ApiService.http:

@SemanticKernelLearning03.ApiService_HostAddress = https://localhost:7391

POST {{SemanticKernelLearning03.ApiService_HostAddress}}/api/blog-posts
Content-Type: application/json

{
  "Title": "Introducción a ASP.NET Core",
  "Description": "Una guía completa sobre cómo comenzar con ASP.NET Core y sus características principales.",
  "Tags": ["ASP.NET Core", "C#", "Web Development"]
}

Verificando los datos en Qdrant

Si ejecutamos nuestra solución con Aspire y realizamos la solicitud anterior, podemos inspeccionar los datos en el dashboard de Qdrant y verificar que la colección y los registros existen.

Consideraciones sobre el tamaño de los vectores

Este ejemplo usa nomic-embed-text, que genera vectores de 768 dimensiones.
Qdrant debe estar configurado para aceptar este tamaño de vector.
Si usas modelos de OpenAI u otros proveedores, verifica el tamaño del vector antes de insertarlo en Qdrant.

Recuperando Información desde Qdrant

Para demostrar cómo realizar búsquedas semánticas en los vectores almacenados en Qdrant, podemos hacerlo de distintas maneras: usando el vector directamente o utilizando una abstracción que Semantic Kernel nos proporciona, llamada ITextSearch.

ITextSearch tiene distintas implementaciones, como BingTextSearch (que realiza búsquedas en Bing), pero en nuestro caso usaremos VectorStoreTextSearch, que está diseñado específicamente para realizar búsquedas en bases de datos vectoriales.

Esta clase necesita conocer:

El modelo de embeddings que estamos usando.
El nombre de la colección en Qdrant donde haremos la búsqueda.

El proceso realmente es sencillo y podríamos hacerlo manualmente construyendo consultas directamente contra la base de datos vectorial. Sin embargo, en este caso, aprovecharemos ITextSearch para simplificar el proceso.

Nota 💡: Para más información sobre búsquedas vectoriales en Semantic Kernel, consulta la documentación oficial de Microsoft:

Vector search using Semantic Kernel Vector Store connectors (Preview) | Microsoft Learn

Implementación del Endpoint `SearchBlogPost`

Para realizar la búsqueda semántica, crearemos un nuevo endpoint llamado SearchBlogPost, que permitirá encontrar los posts más relevantes basados en una consulta en lenguaje natural.

public static class SearchBlogPost
{
    public record Request(string Query);

    public record Response(Guid BlogPostId, string Title, string Description);

    public class Handler([FromKeyedServices(BlogPost.VectorName)] ITextSearch textSearch)
    {
        public async Task<List<Response>> Handle(Request request, CancellationToken ct)
        {
            KernelSearchResults<TextSearchResult> textResults =
                await textSearch.GetTextSearchResultsAsync(request.Query, new()
                {
                    Top = 2,
                    Skip = 0,
                }, ct);

            List<Response> responses = new();
            await foreach (TextSearchResult result in textResults.Results.WithCancellation(ct))
            {
                responses.Add(new(
                    Guid.Parse(result.Link),
                    result.Name,
                    result.Value));
            }

            return responses;
        }
    }
}

Explicación del Código

Uso de ITextSearch
- Lo recibimos en el constructor con [FromKeyedServices(BlogPost.VectorName)]. Esto asegura que estamos inyectando la instancia correcta configurada para nuestra colección de blog posts en Qdrant.
  - Esto lo hemos configurado en DependencyConfig anteriormente.
Realizamos la búsqueda semántica
- Llamamos a GetTextSearchResultsAsync(...);, donde:
  - request.Query es el término de búsqueda ingresado.
  - Top = 2 indica que queremos los dos resultados más relevantes.
  - Skip = 0 significa que no saltaremos ningún resultado.
Procesamos los resultados
- Iteramos sobre textResults.Results para extraer:
  - result.Link: Contiene el BlogPostId almacenado como string, lo convertimos a Guid.
  - result.Name: Corresponde al título del blog post.
  - result.Value: Contiene la descripción del blog post.
Devolvemos la lista de resultados
- Cada Response representa un blog post relevante basado en la búsqueda semántica.

Una vez que el endpoint SearchBlogPost está registrado, podemos comenzar a realizar búsquedas semánticas para encontrar los posts más relevantes según el texto ingresado.

Ejemplo de Consulta

Podemos hacer una búsqueda con la siguiente solicitud:

### Busquedas Semanticas
@Query=arquitectura de software
GET {{SemanticKernelLearning03.ApiService_HostAddress}}/api/blog-posts?Query={{Query}}

Respuesta Esperada

Si hay blog posts relevantes en la base de datos, la API devolverá un listado de los más coincidentes. Un ejemplo de respuesta podría ser:

[
  {
    "blogPostId": "949b7164-2021-4fcc-b58e-9887fdd00d0e",
    "title": "Clean Architecture: Diseño de Software Modular y Escalable",
    "description": "Clean Architecture es un enfoque de diseño de software ..."
  },
  {
    "blogPostId": "2340f1ac-e810-4067-90f5-a71899c6d42a",
    "title": "Principios SOLID en el Desarrollo de Software",
    "description": "Los principios SOLID son un conjunto de cinco principios de..."
  }
]

Si revisamos el repositorio, podemos notar que hay posts de distintos temas (por ejemplo, Machine Learning, Bases de Datos, DevOps), pero la búsqueda regresó los más relevantes según el texto ingresado. Esto demuestra que el motor de búsqueda semántico está funcionando correctamente.

Personalizando la Búsqueda

Podemos ajustar la consulta cambiando:

La cantidad de resultados (Top): Actualmente devuelve dos posts, pero podríamos aumentar este valor si queremos más opciones.
El modelo de embeddings: Si cambiamos el modelo de embeddings usado para almacenar los vectores, los resultados pueden variar en precisión y relevancia.

Integración con RAG (Retrieval-Augmented Generation)

En esta sección, vamos a implementar un nuevo endpoint que va más allá de una búsqueda semántica. En lugar de solo buscar contenido relevante, vamos a generar texto de manera dinámica a partir de una consulta proporcionada por el usuario. Lo interesante aquí es que el contexto para la generación de la respuesta será el contenido de los Posts del Blog que coincidan con la consulta del usuario.

¿Cómo funciona?

Si el usuario hace una pregunta como:

cuál es el objetivo principal de clean architecture?

En lugar de simplemente devolver una lista de posts relacionados, el modelo de Semantic Kernel buscará los posts más relevantes relacionados con la consulta, y usará esos resultados como contexto para generar una respuesta detallada. El modelo no solo devolverá contenido estático, sino que también incorporará la información más relevante y actualizada disponible en los posts, permitiendo una respuesta más precisa y contextualizada.

Esta técnica es útil porque, por lo general, los modelos de lenguaje (LLMs) se entrenan con datos estáticos que no contienen información actualizada o específica del dominio. Al integrar la Recuperación de Información (RAG), aprovechamos los datos disponibles en tiempo real para mejorar la relevancia y exactitud de las respuestas generadas.

¿Cómo lo implementamos?

En el post anterior, vimos cómo crear Plugins o Funciones Semánticas, y cómo Semantic Kernel se encarga de invocar automáticamente esos plugins cuando es necesario. Ahora, vamos a utilizar un plugin de búsqueda vectorial para recuperar los posts relevantes y luego construir un prompt personalizado que permita al modelo generar una respuesta coherente utilizando esos posts como contexto.

El Endpoint y el Código

El endpoint que vamos a implementar es el siguiente:

public static class QuestionsBlogPost
{
    public record Request(string Query);

    public record Response(string Content);

    public class Handler(Kernel kernel, [FromKeyedServices(BlogPost.VectorName)] ITextSearch textSearch)
    {
        public async Task<Response> Handle(Request request, CancellationToken ct)
        {
            var searchPlugin = textSearch.CreateWithGetTextSearchResults("SearchPlugin");
            kernel.Plugins.Add(searchPlugin);

            string promptTemplate = """
                                    Utiliza solamente los siguientes contenidos para contestar las preguntas realizadas. 
                                    Si no sabes la respuesta, hazle saber al usuario que no se encontró información relevante.

                                    Al final de tu respuesta, incluye el nombre del contenido utilizado como referencia.

                                    {{#with (SearchPlugin-GetTextSearchResults query)}}  
                                        {{#each this}}  
                                        Name: {{Name}}
                                        Value: {{Value}}
                                        -----------------
                                        {{/each}}  
                                    {{/with}}  

                                    Pregunta:

                                    {{query}}
                                    """;

            KernelArguments arguments = new() { { "query", request.Query } };

            HandlebarsPromptTemplateFactory promptTemplateFactory = new();
            var response = await kernel.InvokePromptAsync(
                promptTemplate,
                arguments,
                templateFormat: HandlebarsPromptTemplateFactory.HandlebarsTemplateFormat,
                promptTemplateFactory: promptTemplateFactory,
                cancellationToken: ct);

            return new Response(response.ToString());
        }
    }
}

Explicación del Código

Handler: Esta clase maneja la lógica de la consulta, invoca el plugin de búsqueda, crea el prompt con el contexto adecuado y genera la respuesta. Recibe un objeto Kernel y una instancia de ITextSearch que se utiliza para realizar la búsqueda de contenido relevante en los posts del blog.
searchPlugin: Este es el plugin de búsqueda que se crea utilizando el método CreateWithGetTextSearchResults. Este plugin se encarga de realizar la búsqueda semántica en los posts y recuperar los resultados más relevantes. El plugin se añade al Kernel para que pueda ser invocado cuando sea necesario.
promptTemplate: Es el template que se utilizará para generar el texto. En este caso, se utiliza Handlebars para permitir la inserción de los resultados de la búsqueda dentro del prompt. La idea es que el modelo genere una respuesta usando solamente los contenidos encontrados en la búsqueda. El template también incluye instrucciones para que el modelo devuelva el nombre y el valor de los posts utilizados como referencia.

{{#with (SearchPlugin-GetTextSearchResults query)}}  
    {{#each this}}  
    Name: {{Name}}  
    Value: {{Value}}  
    -----------------
    {{/each}}  
{{/with}}

Al final, se agrega la pregunta del usuario para que el modelo la utilice como parte de la respuesta:

Pregunta:
{{query}}

KernelArguments: Este objeto contiene los argumentos que se pasan al modelo, en este caso, la consulta realizada por el usuario.
InvokePromptAsync: Este método invoca el modelo utilizando el template y los argumentos proporcionados, lo que genera una respuesta basada en los contenidos recuperados.

Flujo Completo

El usuario hace una consulta (por ejemplo, "¿Qué es Clean Architecture?").
El Kernel busca los posts relevantes utilizando el plugin de búsqueda vectorial.
El prompt personalizado es generado e incluye los resultados de la búsqueda.
El modelo LLM genera una respuesta utilizando los posts recuperados como contexto.
La respuesta generada se devuelve al usuario, incluyendo la referencia a los contenidos utilizados.

Este enfoque permite mejorar la calidad de las respuestas generadas por el modelo, ya que se aprovecha la información más actualizada y relevante disponible en el dominio. Además, al usar el contenido de los posts, el modelo tiene un contexto más específico y adaptado a las necesidades del usuario, lo que mejora la relevancia y precisión de la respuesta.

Probando el Endpoint

Una vez que hemos configurado y creado nuestro endpoint, es hora de probarlo. Para ello, podemos hacer una solicitud HTTP como la siguiente, que ilustrará cómo interactuar con el servicio de generación de texto mediante la integración de RAG.

Ejemplo de solicitud HTTP:

###
@Question=cuál es el objetivo principal de clean architecture?
GET {{SemanticKernelLearning03.ApiService_HostAddress}}/api/blog-posts/qa?Query={{Question}}

Cuando se ejecuta esta solicitud, obtendremos una respuesta estructurada que incluye no solo la respuesta generada por el modelo, sino también la referencia al contenido utilizado para generar esa respuesta.

Respuesta esperada:

El objetivo principal de Clean Architecture es promover la separación de preocupaciones y la modularidad en el diseño de software, lo que permite a las aplicaciones ser más mantenibles y escalables a lo largo del tiempo.

Reference: Clean Architecture: Diseño de Software Modular y Escalable.

En este caso, la respuesta del endpoint es completamente dinámica y se genera utilizando los resultados de búsqueda obtenidos de los posts del blog relacionados con la pregunta. Como puedes observar, no solo obtenemos un resultado que responde a la consulta, sino que también proporcionamos el nombre del contenido utilizado como referencia, lo cual permite al usuario conocer la fuente de la información generada.

En el ejemplo, configuramos el promptTemplate para que el modelo de lenguaje solo utilizara los contenidos relevantes encontrados a través de la búsqueda de texto vectorial. De esta forma, garantizamos que la generación del modelo sea específica y relevante para el contexto proporcionado por los posts del blog.

Este template establece claramente la regla para que el modelo solo use los resultados de búsqueda como contexto, lo cual optimiza la relevancia de las respuestas generadas.

Escalabilidad y Flexibilidad del Prompt

El prompt puede ser adaptado para ser más específico y mejorar la calidad de las respuestas generadas, por ejemplo, agregando instrucciones más detalladas sobre el formato de la respuesta o proporcionando una estructura más precisa para guiar al modelo. La flexibilidad del sistema permite ajustar el nivel de detalle según la necesidad del caso de uso.

Ejemplo de otro Prompt:

Enlista los puntos más importantes al querer optimizar consultas SQL

Resultado generado:

¡Claro! A continuación, te presento los puntos más importantes para optimizar consultas SQL:

1. **Índices**: Los índices ayudan a acelerar la búsqueda de datos en una base de datos. Deben ser creados en las columnas que se utilizan en la cláusula WHERE o en la cláusula ORDER BY.
2. **Normalización y desnormalización de datos**: La normalización ayuda a reducir la cantidad de datos duplicados en una base de datos, mientras que la desnormalización puede mejorar el rendimiento en ciertas situaciones.
.
.
.

Referencia: Optimización de Consultas SQL en Aplicaciones .NET

Como vemos, el modelo genera una lista de los puntos más importantes y proporciona la referencia adecuada para la información. Este tipo de integración con Semantic Kernel y RAG hace que sea posible tener respuestas altamente relevantes y específicas basadas en contenido actual y relacionado.

Conclusión

A lo largo de este post, hemos aprendido a configurar y utilizar Semantic Kernel para aprovechar el poder de los embeddings y la técnica de Retrieval-Augmented Generation (RAG). Desde la generación y almacenamiento de vectores en Qdrant, hasta la realización de búsquedas semánticas y la generación de respuestas contextualizadas mediante prompts personalizados, hemos visto cómo combinar distintas tecnologías para crear soluciones de IA avanzadas y especializadas.

Esta integración no solo mejora la precisión y relevancia de las respuestas, sino que también demuestra el potencial de unir funciones semánticas, RAG y bases de datos vectoriales para abordar desafíos reales en el manejo de información. Con estas herramientas, podrás desarrollar aplicaciones que se adaptan al contexto de tus datos, ofreciendo respuestas dinámicas y actualizadas.

¡El camino hacia aplicaciones inteligentes y contextualmente precisas está abierto! Sigue experimentando y optimizando estas técnicas para llevar tus proyectos al siguiente nivel.

Referencias

Extendiendo Semantic Kernel: Creando Plugins para Consultas Dinámicas

Isaac Ojeda — Thu, 16 Jan 2025 17:34:53 +0000

1. Introducción

En el tutorial anterior, exploramos cómo configurar y utilizar Semantic Kernel junto con Aspire y Ollama para crear un API básico que generaba resúmenes de texto. Ahora, vamos a dar un paso más y enfocarnos en una de las características más potentes de Semantic Kernel: los plugins.

En este tutorial, aprenderás a crear y utilizar plugins en Semantic Kernel. Los plugins son clases o componentes que encapsulan funciones específicas, permitiendo extender las capacidades del kernel con nuevas habilidades personalizadas.

Para ejemplificarlo, desarrollaremos dos plugins:

Un plugin que retorna la hora actual en formato UTC.
Un plugin que utiliza datos de geolocalización y clima para proporcionar información meteorológica de una ciudad específica.

Los plugins en Semantic Kernel permiten agregar habilidades modulares y reutilizables. Esto no solo facilita la escalabilidad del proyecto, sino que también abre las puertas para integrar servicios externos o lógica personalizada de manera sencilla y eficiente.

Nota 💡: Aquí podrás encontrar el código fuente de este tutorial: DevToPosts/SemanticKernelSeries/SemanticKernelLearning02 at main · isaacOjeda/DevToPosts

2. Qué son los Plugins en Semantic Kernel

¿Qué es un Plugin en Semantic Kernel?

Un plugin en Semantic Kernel es una clase que contiene métodos decorados con atributos especiales, como [KernelFunction], para exponer su funcionalidad al kernel. Esto permite que esas funciones sean llamadas por el kernel como si fueran partes integradas de su sistema.

¿Por qué usar Plugins?

Modularidad: Los plugins encapsulan lógica específica, lo que los hace fáciles de mantener y reutilizar.
Flexibilidad: Puedes crear plugins para realizar tareas como interactuar con APIs externas, procesar datos o realizar cálculos.
Integración sencilla: Los plugins se registran fácilmente en el kernel, haciéndolos disponibles para su uso en el API o dentro de flujos más complejos.

Componentes clave de un Plugin

Métodos decorados con [KernelFunction]: Esto marca las funciones que el kernel puede invocar.
Descripción: Los métodos pueden incluir descripciones para documentar su propósito, facilitando su descubrimiento.
Dependencias externas: Los plugins pueden interactuar con servicios externos, como APIs, utilizando patrones conocidos como IHttpClientFactory.

Plugins que construiremos en este tutorial

TimeInformationService: Un plugin que proporciona la hora actual en UTC.
WeatherInformationService: Un plugin que utiliza una API externa para obtener información de geolocalización y clima.

Ambos plugins serán integrados en nuestro kernel y expuestos a través del API que desarrollamos en el tutorial anterior.

¿Cómo funcionan los Plugins en Semantic Kernel?

Los plugins registrados en el kernel pueden ser invocados en tiempo de ejecución mediante prompts o directamente desde el código. El kernel gestiona automáticamente la ejecución de estos métodos, permitiendo integrarlos en flujos de procesamiento complejos.

3. Desarrollo del Ejemplo

Ahora que entendemos qué son los plugins en Semantic Kernel, vamos a desarrollar e integrar dos plugins personalizados en nuestro proyecto:

TimeInformationService: Un plugin simple que devuelve la hora actual en UTC.
WeatherInformationService: Un plugin más avanzado que utiliza una API externa para obtener información sobre el clima en una ciudad.

Paso 1: Crear los Plugins

TimeInformationService

El siguiente plugin proporciona la hora actual en formato UTC. Es un ejemplo sencillo para entender cómo funcionan los plugins básicos en Semantic Kernel.

/// <summary>
/// A plugin that returns the current time.
/// </summary>
public class TimeInformationService
{
    [KernelFunction]
    [Description("Retrieves the current time in UTC.")]
    public string GetCurrentUtcTime() => DateTime.UtcNow.ToString("R");
}

Aquí destacamos:

El atributo [KernelFunction] expone el método al kernel.
El método devuelve la hora en formato "R" (RFC1123), que es legible y estándar.

WeatherInformationService

Este plugin es más complejo. Obtiene información sobre una ciudad (coordenadas, país, etc.) y también el clima actual utilizando servicios externos.

public class WeatherInformationService(IHttpClientFactory httpClientFactory)
{
    [KernelFunction]
    [Description("Get weather information for a city.")]
    public async Task<WeatherInfo> GetWeatherByCity(string cityName)
    {
        if (string.IsNullOrWhiteSpace(cityName))
            throw new ArgumentException("City name cannot be null or empty.", nameof(cityName));

        // Step 1: Get city coordinates
        var city = await GetCityCoordinatesAsync(cityName);

        // Step 2: Get weather data
        var weatherResult = await GetWeatherDataAsync(city.Latitude, city.Longitude);

        return new WeatherInfo
        {
            City = city.Name,
            Country = city.Country,
            Temperature = weatherResult.CurrentWeather.Temperature,
            WindSpeed = weatherResult.CurrentWeather.Windspeed,
            WeatherCode = weatherResult.CurrentWeather.Weathercode
        };
    }

    private async Task<GeocodingResult> GetCityCoordinatesAsync(string cityName)
    {
        // ...For more info, check the source code
    }

    private async Task<WeatherApiResponse> GetWeatherDataAsync(double latitude, double longitude)
    {
        // ...For more info, check the source code
    }
}

Puntos clave:

Este plugin utiliza IHttpClientFactory para realizar llamadas HTTP a APIs externas.
- Como puedes ver, la inyección de dependencias funciona sin problema, por lo que aquí podríamos inyectar lo que se necesite que el plugin realice
El Kernel utiliza los nombres de los métodos y los parámetros para darles significado y así usarlo según el prompt solicitado.

Paso 2: Registrar los Plugins en el Kernel

Para que el kernel pueda usar estos plugins, debemos registrarlos en la configuración del servicio:

var kernel = builder.Services.AddKernel();

// Registrar el servicio de hora
kernel.ImportPlugin<TimeInformationService>();

// Registrar el servicio de clima
kernel.ImportPlugin<WeatherInformationService>();

Paso 3: Exponer los Plugins Utilizando el Kernel

En lugar de llamar directamente a los métodos de los servicios, utilizaremos el Kernel de Semantic Kernel para invocar los plugins mediante prompts. Esto nos permitirá combinar capacidades y hacer el uso más dinámico de los plugins.

Haremos la prueba con un simple endpoint que invoque el prompt

app.MapPost("/api/chat", async (ChatRequest request, Kernel kernel) =>
{
    var settings = new OpenAIPromptExecutionSettings()
    {
        FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
    };

    // Aquí podríamos hacer un Prompt más explícito para el modelo si nuestra intención fuera
    // solo contestar preguntas sobre el clima.

    var response = await kernel.InvokePromptAsync(request.Question, new(settings));

    return Results.Ok(new
    {
        Result = response.ToString()
    });
});

Explicación del Código

Uso del Kernel:
- El método InvokePromptAsync utiliza el kernel para procesar el prompt y determinar qué función de los plugins debe ejecutarse.
- En este caso, el Kernel automáticamente seleccionará el método correcto (GetCurrentUtcTime o GetWeatherByCity) basado en el texto del prompt.
Integración Flexible:
- La estructura permite enviar cualquier pregunta o texto, dejando que el Kernel interprete y seleccione el método adecuado.
  - También podemos hacer prompts donde seamos explícitos de que Plugin queremos que el modelo utilice, pero por ahora lo dejamos en automático y que el modelo decida.

4. Probar los Endpoints

Con los endpoints configurados y los plugins integrados en el Kernel, es momento de validarlos y observar cómo funcionan.

Ejemplo 1: Consultar el Clima

Utilizando Postman, envía la siguiente solicitud al endpoint configurado:

{
  "question": "Cuál es el clima actual en Londres"
}

Al depurar la aplicación, notarás que el modelo entiende la intención del prompt, lo asocia con nuestro plugin y determina que queremos el clima actual de Londres. Esto sucede porque hemos registrado una función específica que devuelve esta información:

La respuesta sería algo similar a:

{
    "result": "El clima actual en Londres es frío y nublado, con una temperatura de 8.6°C y un viento que sopla a 6.8 km/h. La codificación del tiempo es 3, lo que indica condiciones climáticas mezcladas, con algunas nubes y posibles lluvias."
}

Ejemplo 2: Consultar Información de una Ciudad

Ahora, realiza una consulta diferente, como esta:

{
  "question": "Cuál es la población actual de Madrid?"
}

En este caso, el modelo invocará automáticamente otra función registrada en el plugin que se encarga de obtener información sobre una ciudad:

La respuesta será algo como:

{
    "result": "La población actual de Madrid es de aproximadamente 3,255,594 personas, según la información proporcionada por el servicio de información geográfica."
}

¿Notas el poder detrás de esta integración? Con esta configuración, el Kernel puede realizar tareas que antes requerían múltiples servicios separados. Todo se reduce a cómo estructuramos los prompts y las funciones de nuestros plugins.

¡Y esto es solo el principio! Aún no hemos explorado características avanzadas como memoria semántica y RAG (Retrieval-Augmented Generation), pero con lo que ya tenemos, podemos construir soluciones extremadamente flexibles y personalizadas para cualquier dominio o industria.

Con prompts más específicos, puedes resolver problemas complejos y automatizar procesos avanzados. La única limitación es tu creatividad y las necesidades de tu proyecto.

5. Extender Funcionalidades y Consideraciones Finales

Ahora que hemos visto cómo registrar plugins y probarlos con el Kernel, reflexionemos sobre cómo podemos extender estas funcionalidades para adaptarlas a necesidades más complejas. Aquí algunas ideas y recomendaciones para el siguiente nivel:

Incorporar Más Plugins

La flexibilidad de Semantic Kernel nos permite agregar más funciones a nuestros plugins o crear nuevos plugins para cubrir otras áreas de interés, como:

Análisis de texto: Procesar grandes volúmenes de datos textuales para obtener resúmenes, extraer palabras clave o identificar entidades.
Integraciones externas: Conectar con APIs de terceros para realizar tareas como manejo de correos electrónicos, acceso a sistemas empresariales o realizar transacciones.
Procesamiento de imágenes: Usar servicios como OCR para reconocer texto en imágenes o realizar análisis visual.

Usar Memoria Semántica

La memoria semántica de Semantic Kernel puede almacenar y recuperar información contextualmente relevante. Por ejemplo:

Recordar interacciones previas para mejorar la experiencia del usuario.
Contextualizar consultas complejas basándose en datos históricos.
Implementar personalización profunda en aplicaciones que requieran un historial de acciones o preferencias.

Optimización de Prompts

Un diseño adecuado de prompts es clave para mejorar la precisión de los resultados. Algunas recomendaciones:

Sea específico: Prompts detallados producen resultados más enfocados.
Use ejemplos: Proporcionar ejemplos en el prompt puede ayudar al modelo a entender la intención de manera más clara.
Evalúe y ajuste: Experimente con diferentes configuraciones para obtener mejores resultados en diferentes escenarios.

Escalabilidad y Producción

Si bien en estos ejemplos usamos Ollama localmente para evitar problemas de infraestructura, en un entorno de producción puedes cambiar sin modificar tu código base y usar servicios como OpenAI o Azure OpenAI para aprovechar su escalabilidad y confiabilidad. Esto implica:

Definir claves API para entornos seguros.
Configurar políticas de acceso según las necesidades de tu organización.
Monitorear el uso y los costos para optimizar el rendimiento.

Casos de Uso Empresariales

Con los elementos ya implementados, podemos visualizar algunos casos prácticos donde estas capacidades sean útiles:

Asistentes de soporte: Resolver consultas comunes en tiempo real con información siempre actualizada.
Automatización de tareas repetitivas: Por ejemplo, generar reportes basados en datos o notificaciones programadas.
Sistemas personalizados: Aplicaciones inteligentes que se adapten dinámicamente a las necesidades de los usuarios, como dashboards interactivos o chatbots avanzados. ### Conclusión

Con Semantic Kernel, hemos transformado lo que tradicionalmente sería una combinación de servicios aislados en una solución unificada y potente. Desde entender intenciones en lenguaje natural hasta ejecutar acciones basadas en plugins específicos, el Kernel nos proporciona una plataforma flexible y extensible para la creación de aplicaciones inteligentes.

La verdadera ventaja de esta tecnología radica en su capacidad de evolución. Puedes comenzar con casos de uso simples, como los ejemplos de este tutorial, y escalar hacia soluciones más complejas que integren múltiples fuentes de datos, memoria semántica y funcionalidades avanzadas.

Tu creatividad y las necesidades de tu proyecto dictarán el camino. Ahora que tienes las bases, ¿qué construirás con Semantic Kernel?

Semantic Kernel: Crea un API para Generación de Texto con Ollama y Aspire

Isaac Ojeda — Tue, 14 Jan 2025 20:18:42 +0000

1. Introducción

En este tutorial, aprenderás cómo usar Semantic Kernel para integrar Large Language Models (LLM) y construir un servicio REST que resuma texto. Utilizaremos Ollama como motor local de modelos de lenguaje, lo que nos permitirá evitar el uso de servicios en la nube en esta fase de desarrollo.

El objetivo principal es configurar un entorno de trabajo funcional en C# que permita a los desarrolladores:

Conectar un modelo de lenguaje local (llama3.2).
Crear un kernel para manejar tareas personalizadas.
Exponer la funcionalidad como un endpoint REST en una API ASP.NET Core.

Al finalizar, tendrás un servicio de API que podrá recibir texto como entrada y devolver un resumen en una sola oración. Esto no solo te ayudará a entender cómo usar Semantic Kernel, sino que también te dará una base sólida para construir aplicaciones prácticas basadas en IA generativa.

2. Introducción a Semantic Kernel

2.1. ¿Qué es Semantic Kernel?

Semantic Kernel es un SDK de código abierto que permite a los desarrolladores crear sus propios agentes personalizados de inteligencia artificial (IA). Al combinar modelos de lenguaje de gran escala (LLMs) con código nativo, los desarrolladores pueden crear agentes de IA que entiendan y respondan a solicitudes en lenguaje natural para realizar una variedad de tareas.

2.2 ¿Qué es un agente de IA?

Un agente de IA es un programa diseñado para alcanzar objetivos predeterminados. Los agentes de IA están impulsados por modelos de lenguaje de gran escala (LLMs) entrenados con cantidades masivas de datos. Estos agentes pueden completar una amplia variedad de tareas con mínima o ninguna intervención humana. Algunos ejemplos de lo que pueden hacer los agentes de IA incluyen:

Escribir código.
Redactar correos electrónicos.
Resumir reuniones.
Proporcionar recomendaciones.
¡Y mucho más!

Semantic Kernel integra modelos de lenguaje como OpenAI, Azure OpenAI y Hugging Face con lenguajes de programación convencionales como C#, Python y Java. Los desarrolladores pueden crear "plugins" para interactuar con los LLMs y realizar diversas tareas. Además, el SDK de Semantic Kernel incluye plugins predefinidos que pueden mejorar rápidamente una aplicación. Esto permite que los desarrolladores utilicen LLMs en sus propias aplicaciones sin necesidad de aprender los detalles específicos de la API del modelo.

2.3 Componentes clave del SDK de Semantic Kernel

Capa de orquestación de IA

El núcleo del stack de Semantic Kernel es una capa de orquestación de IA que permite la integración fluida de modelos de IA y plugins. Esta capa combina estos componentes para crear interacciones innovadoras con los usuarios.

Conectores

El SDK ofrece un conjunto de conectores que permiten a los desarrolladores integrar LLMs en sus aplicaciones existentes. Estos conectores actúan como un puente entre el código de la aplicación y los modelos de IA.

Plugins

El SDK opera con plugins, que funcionan como el "cuerpo" de la aplicación de IA. Los plugins incluyen solicitudes (prompts) que el modelo de IA debe responder y funciones para realizar tareas especializadas. Los desarrolladores pueden usar plugins predefinidos o crear los suyos propios.

3. Desarrollo del Ejemplo

En esta sección, construiremos un API REST que utiliza Semantic Kernel y el modelo de lenguaje llama3.2 de Ollama para resumir texto en una sola oración. El objetivo es entender cómo configurar el entorno y crear una habilidad básica que pueda ser utilizada desde cualquier aplicación a través de un endpoint.

3.1. Configuración con Aspire

Antes de entrar en los detalles del API, configuramos el entorno utilizando Aspire. Este framework facilita la construcción de aplicaciones distribuidas, simplificando la gestión de dependencias y servicios.

Lo que he hecho para simplificar la configuración, es utilizar Visual Studio para crear la solución ejemplo de Aspire con .NET 9:

Esta plantilla, también incluye un proyecto de Blazor, en este tutorial no lo utilizaremos, pero al finalizar, puedes utilizar ese proyecto para consumir los endpoints realizados y ya tener una aplicación funcional.

El código de Aspire tiene los siguientes propósitos:

Configurar Ollama: Define el modelo llama3.2 como el motor de lenguaje. Esto nos permite trabajar con un modelo local, eliminando la necesidad de infraestructura compleja en desarrollo.
Modularidad: Cada proyecto (como SemanticKernelLearning01_ApiService) se configura como un módulo independiente, permitiendo una estructura clara y extensible.

Nota: Usar Ollama local es ideal para pruebas y desarrollo, ya que no requiere configurar una infraestructura en la nube. Sin embargo, en producción puedes cambiar a OpenAI o Azure OpenAI sin modificar el código, aprovechando la flexibilidad de Semantic Kernel.

Código de Aspire:

Primero necesitamos los siguientes paquetes:

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
    <PackageReference Include="CommunityToolkit.Aspire.Hosting.Ollama" Version="9.1.0" />
  </ItemGroup>

var builder = DistributedApplication.CreateBuilder(args);

var ollama =
    builder
        .AddOllama("ollama")// <-- Utilizará docker para usar ollama y sus modelos 
        .WithDataVolume()   // <-- Volumen de Docker para persistir modelos descargados
        .WithOpenWebUI();   // <-- UI Estilo ChatGPT

// Descarga el modelo llama3.2 con nombre "llama"
var llamaModel = ollama.AddModel("llama", "llama3.2");

// Nuestra API depende de Ollama, por lo que se referencia y espera a que esté listo
builder.AddProject<Projects.SemanticKernelLearning01_ApiService>("apiservice")
    .WithReference(llamaModel)
    .WaitFor(llamaModel);

builder.Build().Run();

Aquí configuramos Ollama como motor de generación de texto y vinculamos el modelo llama3.2. También iniciamos el servicio API como un módulo dentro del proyecto.

3.2. Configuración del API REST

En el siguiente bloque de código, configuramos un API REST utilizando ASP.NET Core y Semantic Kernel. Aquí se define un endpoint que acepta texto como entrada y devuelve su resumen generado por el modelo de lenguaje.

Puntos clave del código:

Kernel y Ollama: Se inicializa el kernel de Semantic Kernel y se conecta con Ollama usando la configuración definida en Aspire.
Habilidad de Resumen: La lógica para resumir texto se encapsula en un prompt que el modelo interpreta para generar respuestas.
Exposición del Endpoint: Se define un endpoint /api/summarizer que recibe un objeto JSON con el texto a resumir y devuelve el resultado.

Código del API REST:

Paquetes necesarios:

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.0" />
    <PackageReference Include="Microsoft.SemanticKernel" Version="1.33.0" />
    <PackageReference Include="Microsoft.SemanticKernel.Connectors.Ollama" Version="1.33.0-alpha" />
  </ItemGroup>

Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();
builder.Services.AddProblemDetails();
builder.Services.AddOpenApi();

var kernel = builder.Services.AddKernel();

var (endpoint, modelId) = GetOllamaConnectionString();

#pragma warning disable SKEXP0070
kernel.AddOllamaTextGeneration(modelId, endpoint); // Está en alpha, puede cambiar.
#pragma warning restore SKEXP0070

var app = builder.Build();

app.UseExceptionHandler();

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

app.MapDefaultEndpoints();

app.MapPost("/api/summarizer", async (
    TextCompletionRequest request,
    ITextGenerationService textGenerationService) =>
{
    var prompt = $"""
                 Summarize the following text in one sentence:  

                 {request.Text}
                 """;

    var response = await textGenerationService.GetTextContentsAsync(prompt);

    return response;
});

app.Run();

3.3. Explicación General del Flujo

Creación del Kernel: Se configura el kernel para usar Ollama como motor de generación de texto con el modelo llama3.2.
Definición del Endpoint: El endpoint /api/summarizer recibe un JSON con una propiedad Text.
Generación del Resumen: El texto recibido se envía al modelo junto con un prompt que instruye al modelo para resumirlo en una oración.
Devolución del Resultado: El resumen generado se devuelve como respuesta al cliente que llamó al API.

Código restante:

(Uri endpoint, string modelId) GetOllamaConnectionString()
{
    // Este ConnectionString es establecida por Aspire
    var connectionString = builder.Configuration.GetConnectionString("llama");

    var connectionBuilder = new DbConnectionStringBuilder
    {
        ConnectionString = connectionString
    };

    Uri endpoint = new Uri(connectionBuilder["Endpoint"].ToString());
    string modelId = connectionBuilder["Model"].ToString();

    return (endpoint, modelId);
}

// Simple DTO
public record TextCompletionRequest(string Text);

Nota 💡: Recuerda que siempre puedes descargar el código desde desde este Repositorio

3.4 Probando la solución

Si corremos el proyecto de Aspire, automáticamente orquestará lo necesario para que la API pueda comunicarse con ollama:

Su primera ejecución será lenta, ya que tendrá que descargar el modelo llama3.2.

Existen muchos modelos que podemos ejecutar, tanto para Text Generation y para Embeddings (revisado en próxmos post), puedes revisar más aquí: Ollama.

Probemos el endpoint (utilizando Visual Studio y un archivo .http):

@host = https://localhost:7384

### Text Generation
POST {{host}}/api/summarizer
Content-Type: application/json

{
    "text": "Mariana found an ancient book in her grandfather’s library, with a bookmark pointing to a page that read, “Recite these words and your destiny will change.” Intrigued, she read it out loud, and in an instant, she found herself in a bustling market in a medieval town. \rNo one seemed surprised by her modern clothing; in fact, one merchant greeted her as if he knew her. As she searched for answers, an old man explained that she was the heir to a lost legacy and had to make a choice: stay and lead a kingdom on the brink of chaos, or return to her everyday life. \rWith the book in her hands, Mariana took a deep breath and closed her eyes, choosing the challenge she had secretly always wanted."
}

Respuesta:

[
  {
    "text": "Mariana discovers an ancient book that transports her to a medieval town, where she learns she is the heir to a lost legacy and must make a choice between returning to her ordinary life or leading a kingdom on the brink of chaos.",
    "modelId": "llama3.2"
  }
]

La ejecución de modelos con ollama claro que suele ser más lento, para acelerar su ejecución debemos de contar con una GPU y de preferencia Nvidia.

Para operaciones sencillas, me ha funcionado bien y como vemos, la respuesta ha funcionado, todo ejecutandose en nuestra computadora.

4. Conclusión

En este tutorial, exploramos los fundamentos de Semantic Kernel y cómo integrarlo con Ollama para construir un servicio funcional capaz de generar resúmenes de texto. A través de este ejercicio:

Aprendiste a configurar un entorno básico utilizando Aspire, simplificando la administración de servicios distribuidos.
Descubriste cómo conectar Semantic Kernel con un motor de lenguaje local, como llama3.2 de Ollama, para evitar complicaciones de infraestructura en desarrollo.
Implementaste un API REST con un endpoint práctico que utiliza generación de texto como una habilidad central.

Este ejercicio muestra lo versátil que puede ser Semantic Kernel para crear aplicaciones inteligentes que aprovechan los modelos de lenguaje. Además, la flexibilidad de la arquitectura permite cambiar fácilmente entre diferentes proveedores de modelos, como OpenAI o Azure, sin necesidad de modificar el código base.

Este tutorial es solo el inicio. A partir de aquí, puedes explorar y agregar nuevas habilidades, integrar bases de datos vectoriales para contextualizar las respuestas o expandir el API con capacidades adicionales.

5. Próximos Pasos

Ahora que ya tienes una base sólida para trabajar con Semantic Kernel y Ollama, considera avanzar con los siguientes temas para expandir tus conocimientos:

Ampliar tus habilidades en Semantic Kernel:
- Aprende a crear habilidades más complejas con múltiples pasos y dependencias.
- Explora cómo usar conectores para integrar datos externos, como archivos, APIs, o bases de datos.
Incorporar contexto mediante bases de datos vectoriales:
- Experimenta con herramientas como Qdrant o Pinecone para agregar contexto a las respuestas basadas en vectores.
- Usa embeddings para conectar preguntas con datos relevantes en tiempo real.
Migrar a un entorno de producción:
- Configura la misma API para usar OpenAI o Azure OpenAI como motores de generación de texto.
- Aprende a manejar credenciales y seguridad en aplicaciones en producción.
Construir una interfaz gráfica:
- Usa Blazor para crear una interfaz interactiva donde los usuarios puedan interactuar con tus habilidades de Semantic Kernel.
Desarrollar tutoriales más avanzados:
- Enseña a otros cómo resolver problemas reales, como análisis de sentimientos, clasificación de texto o generación de contenido adaptado al contexto.

Integration Tests en .NET con TestContainers: Pruebas de Base de Datos Aisladas

Isaac Ojeda — Thu, 07 Nov 2024 21:23:19 +0000

Introducción a las Pruebas de Integración

En el desarrollo de software, las pruebas de integración son esenciales para verificar que los distintos módulos de una aplicación trabajen correctamente en conjunto. A diferencia de las pruebas unitarias, que se centran en unidades individuales de código, las pruebas de integración se enfocan en asegurarse de que los componentes del sistema interactúan adecuadamente entre sí y, en muchos casos, dependen de servicios externos, como bases de datos, servicios de autenticación o APIs de terceros.

En este artículo, vamos a trabajar con una Web API de ejemplo que utiliza SQL Server como base de datos. La idea es configurar un entorno de pruebas de integración utilizando TestContainers, una librería que permite levantar contenedores Docker de forma programática y en tiempo de ejecución, facilitando así la creación de entornos de prueba aislados y controlados.

Para ejecutar nuestras pruebas, usaremos xUnit como framework de testing y Respawn para resetear la base de datos entre pruebas, lo que ayuda a garantizar que cada prueba comience con un estado limpio y consistente. Gracias a TestContainers, podemos levantar un contenedor de SQL Server específicamente para nuestras pruebas, eliminando la dependencia de una base de datos local o compartida y asegurando que el entorno sea reproducible en cualquier máquina.

El código fuente completo de esta configuración y las pruebas está disponible en este repositorio de GitHub. Si quieres seguir este tutorial, puedes clonar el repositorio y ajustar los pasos según sea necesario para tu propio proyecto.

Herramientas y Librerías Utilizadas

Para implementar pruebas de integración con un entorno aislado y controlado, usaremos las siguientes librerías:

xUnit: Un framework de pruebas en .NET, ideal para organizar y ejecutar nuestras pruebas de integración.
Testcontainers.MsSql: Permite levantar un contenedor de SQL Server en Docker exclusivamente para nuestras pruebas, evitando dependencias locales y asegurando un entorno consistente.
Respawn: Resetea la base de datos entre pruebas, manteniendo un estado limpio y libre de datos residuales para cada ejecución.
FluentAssertions: Simplifica la escritura de aserciones, haciéndolas más legibles y expresivas.
Microsoft.AspNetCore.Mvc.Testing: Utilizada para crear un servidor web en memoria para poder exponer los endpoints y poder ejecutar las pruebas de inicio a fin.

Creación de un Contenedor SQL Server con TestContainers

En esta sección, configuraremos un contenedor de SQL Server para nuestras pruebas de integración usando TestContainers y un ICollectionFixture en xUnit. Esto permitirá que todas las pruebas dentro de una misma colección compartan una instancia de contenedor SQL Server, evitando configuraciones repetitivas y asegurando un entorno consistente.

Uso de ICollectionFixture y CollectionDefinition en xUnit

xUnit proporciona el concepto de ICollectionFixture para compartir configuraciones entre pruebas en una misma colección. Con ICollectionFixture, podemos crear una configuración compartida que solo se inicializa una vez y está disponible para todas las pruebas que pertenecen a una colección específica. Esto es ideal cuando tenemos configuraciones costosas o que queremos evitar inicializar en cada prueba, como en este caso, un contenedor Docker para SQL Server.

La configuración se organiza en dos partes:

ICollectionFixture: Define una clase de configuración compartida, en este caso SqlServerContainerFixture, que contiene toda la lógica para levantar y detener el contenedor SQL Server.
CollectionDefinition: Agrupa las pruebas que comparten la misma configuración. Asociamos las pruebas a esta colección usando el nombre de la colección (en este caso, "SqlServerContainerFixture").

Creación del Contenedor SQL Server

A continuación, se muestra el código de SqlServerContainerFixture, que configura y administra el ciclo de vida de un contenedor SQL Server. Este fixture implementa IAsyncLifetime, que permite ejecutar lógica de inicialización y limpieza de recursos de forma asincrónica.

public class SqlServerContainerFixture : IAsyncLifetime
{
    public const string FixtureName = "SqlServerContainerFixture";
    public MsSqlContainer SqlServerContainer { get; private set; }
    public string ConnectionString => SqlServerContainer.GetConnectionString();

    public SqlServerContainerFixture()
    {
        // Configuramos el contenedor SQL Server usando TestContainers
        SqlServerContainer = new MsSqlBuilder()
            .WithImage("mcr.microsoft.com/mssql/server:2022-latest") // Imagen de SQL Server
            .WithPassword("Passw0rd!") // Contraseña obligatoria para SQL Server
            .Build();
    }

    // Inicializa el contenedor de forma asincrónica antes de que las pruebas comiencen a ejecutarse
    public async Task InitializeAsync()
    {
        await SqlServerContainer.StartAsync();
    }

    // Detiene y limpia el contenedor después de que todas las pruebas hayan finalizado
    public async Task DisposeAsync()
    {
        await SqlServerContainer.StopAsync();
    }
}

Propiedades y Constructor:
- SqlServerContainer: Es el contenedor de SQL Server configurado a través de la clase MsSqlBuilder de TestContainers, donde especificamos la imagen docker, la contraseña y el puerto para el contenedor.
- ConnectionString: Proporciona una cadena de conexión a SQL Server, obtenida directamente del contenedor para que las pruebas puedan conectarse a esta base de datos.
Async Lifecycle con IAsyncLifetime:
- InitializeAsync(): Este método se ejecuta antes de que cualquier prueba en la colección se ejecute. Llama a StartAsync() para levantar el contenedor de SQL Server.
- DisposeAsync(): Este método se ejecuta una vez que todas las pruebas de la colección han finalizado, liberando recursos al detener el contenedor con StopAsync().

Definición de la Colección de Pruebas

A continuación, definimos la colección de pruebas asociada al fixture SqlServerContainerFixture. Esto se hace con [CollectionDefinition], que simplemente establece un nombre para la colección y vincula el fixture a todas las pruebas de la misma colección:

[CollectionDefinition(SqlServerContainerFixture.FixtureName)]
public class DatabaseCollection : ICollectionFixture<SqlServerContainerFixture>
{
    // Esta clase no necesita código. Su único propósito es asociar
    // el CollectionDefinition con ICollectionFixture.
}

[CollectionDefinition]: Asocia un nombre de colección, en este caso "SqlServerContainerFixture", con el fixture SqlServerContainerFixture.
ICollectionFixture<SqlServerContainerFixture>: Define la dependencia del fixture en todas las pruebas que pertenezcan a la colección.

Al agrupar nuestras pruebas en esta colección, cada una podrá acceder al contenedor de SQL Server compartido, eliminando la necesidad de inicializar un nuevo contenedor para cada prueba individualmente. Esto hace que las pruebas sean más eficientes y garantiza un entorno de datos consistente.

Configuración de Reseteo de Base de Datos con Respawn y WebApplicationFactory

Uso de `WebApplicationFactory`

WebApplicationFactory es una clase proporcionada por Microsoft que permite crear un servidor de pruebas en memoria basado en la configuración de la aplicación real. Esto es útil cuando necesitas probar la integración de tu Web API, ya que te permite simular el comportamiento de la aplicación sin necesidad de un servidor físico o configuración externa.

En este caso, estamos creando un WebApplicationFixture que extiende WebApplicationFactory<Program>. Esta clase personalizada actúa como un "wrapper" para iniciar la aplicación en un entorno de pruebas, y también maneja la configuración de la base de datos y su reseteo entre pruebas utilizando Respawn.

Configuración de Respawn para el Reseteo de la Base de Datos

Respawn es una librería que facilita el reseteo rápido y eficiente de la base de datos, lo cual es especialmente útil en pruebas de integración. Lo que hace Respawn es eliminar los datos de las tablas entre pruebas, asegurando que cada prueba tenga un entorno limpio y consistente sin la necesidad de restaurar toda la base de datos.

En nuestro WebApplicationFixture, estamos utilizando IAsyncLifetime para manejar la inicialización y limpieza asincrónica de los recursos antes y después de que se ejecuten las pruebas. En particular, se usa para la configuración de Respawn:

public class WebApplicationFixture(SqlServerContainerFixture sqlServerContainerFixture)
    : WebApplicationFactory<Program>, IAsyncLifetime
{
    private Respawner? _respawner;

    // Inicialización de Respawn y base de datos
    async Task IAsyncLifetime.InitializeAsync()
    {
        using var scope = Services.CreateScope();
        var dbSeed = scope.ServiceProvider.GetRequiredService<AppDbContextSeed>();

        // Inicializar Respawn
        _respawner = await Respawner.CreateAsync(sqlServerContainerFixture.ConnectionString, new RespawnerOptions
        {
            TablesToIgnore = ["__EFMigrationsHistory"]
        });

        // Asegurar que la base de datos esté creada y con datos de prueba
        await dbSeed.EnsureCreatedAsync();
        await dbSeed.SeedAsync();
    }

    // Reseteo de la base de datos después de las pruebas
    async Task IAsyncLifetime.DisposeAsync()
    {
        if (_respawner is null)
        {
            return;
        }

        // Reseteamos la base de datos a su estado inicial
        await _respawner.ResetAsync(sqlServerContainerFixture.ConnectionString);
    }
}

InitializeAsync():
- Respawner.CreateAsync(): Configuramos Respawn con la cadena de conexión del contenedor SQL Server para reiniciar las tablas relevantes antes de cada clase de pruebas. Las tablas especificadas en TablesToIgnore no se resetean.
- dbSeed.EnsureCreatedAsync() y dbSeed.SeedAsync(): Aseguran que la base de datos esté creada y se tengan datos iniciales para las pruebas.
DisposeAsync():
- Cuando las pruebas de una clase han finalizado, DisposeAsync() es responsable de ejecutar el método ResetAsync() de Respawn, que limpia la base de datos, dejando las tablas listas para la siguiente clase de pruebas.

Configuración de la Base de Datos con `ConfigureWebHost`

Dentro de la clase WebApplicationFixture, también estamos utilizando el método ConfigureWebHost para ajustar la configuración de la aplicación de pruebas, especialmente la conexión a la base de datos. Esto es necesario porque la aplicación por defecto podría estar configurada para usar una base de datos local o un entorno diferente, por lo que tenemos que "reconfigurar" la cadena de conexión para que apunte al contenedor SQL Server levantado con TestContainers:

protected override void ConfigureWebHost(IWebHostBuilder builder)
{
    builder.UseEnvironment("IntegrationTests");
    builder.ConfigureTestServices(services =>
    {
        // Eliminar configuraciones anteriores de la base de datos
        var descriptor = services.SingleOrDefault(
            d => d.ServiceType == typeof(DbContextOptions<AppDbContext>));

        services.Remove(descriptor!);

        var descriptorAppDbContext = services.SingleOrDefault(
            d => d.ServiceType == typeof(AppDbContext));

        services.Remove(descriptorAppDbContext!);

        // Configurar la base de datos para que utilice el contenedor SQL Server
        services.AddDbContext<AppDbContext>(options =>
        {
            options.UseSqlServer(sqlServerContainerFixture.ConnectionString);
        });
    });
}

UseEnvironment("IntegrationTests"): Establece el entorno de pruebas para que la aplicación cargue las configuraciones específicas para pruebas de integración (de ser necesario, podríamos tener un appsettings.IntegrationTests.json).
ConfigureTestServices(): Reconfigura los servicios de la aplicación para que la conexión de la base de datos apunte al contenedor SQL Server. Primero, eliminamos cualquier configuración previa de DbContext y luego agregamos la nueva configuración que utiliza la cadena de conexión proporcionada por el contenedor.

Con esta configuración, WebApplicationFixture:

Levanta la aplicación en memoria utilizando WebApplicationFactory para simular el servidor real.
Utiliza Respawn para reiniciar la base de datos antes de cada clase de pruebas, asegurando un entorno limpio.
Configura la conexión a la base de datos para que apunte al contenedor SQL Server levantado con TestContainers.

Escribir una Prueba de Integración Básica

Las pruebas de integración en este contexto validan la comunicación entre nuestra aplicación y la base de datos SQL Server. Usando WebApplicationFixture y SqlServerContainerFixture, simulamos el entorno de la aplicación y reiniciamos el estado de la base de datos para cada clase de pruebas, asegurando que cada prueba comience desde un estado limpio.

Estructura de la Clase de Prueba `CreateProductTests`

La clase CreateProductTests contiene dos pruebas básicas para el endpoint de creación de productos:

Una prueba para validar que la creación de un producto es exitosa.
Una prueba para verificar el comportamiento cuando se intenta crear un producto con una categoría inexistente.

namespace TestContainers.Integration.Tests.Endpoints.ProductTests;

[Collection(SqlServerContainerFixture.FixtureName)]
public class CreateProductTests : IClassFixture<WebApplicationFixture>
{
    private readonly WebApplicationFixture _factory;
    private readonly AppDbContext _dbContext;
    private readonly HttpClient _client;

    public CreateProductTests(WebApplicationFixture factory)
    {
        _factory = factory;
        _dbContext = factory.DbContext;
        _client = factory.HttpClient;
    }

[Collection]: Esta anotación asegura que SqlServerContainerFixture se utilice para todas las pruebas dentro de esta clase, compartiendo la misma configuración de base de datos.
IClassFixture<WebApplicationFixture>: WebApplicationFixture proporciona acceso a un cliente HTTP en memoria (HttpClient) para simular llamadas HTTP y a AppDbContext para realizar operaciones directas en la base de datos durante la configuración de pruebas.

Primera Prueba: Creación Exitosa de un Producto

La prueba CreateProduct_ReturnsProduct verifica que la creación de un producto con una categoría válida sea exitosa y que los datos devueltos sean correctos.

[Fact]
public async Task CreateProduct_ReturnsProduct()
{
    // Arrange
    var category = await GetFirstCategory();
    var product = new Product
    {
        Name = "Test Product",
        Description = "Test Description",
        Price = 10.0m,
        CategoryId = category.Id
    };

    // Act
    var response = await _client.PostAsJsonAsync("/products", product);

    // Assert
    response.EnsureSuccessStatusCode();

    var createdProduct = await response.Content.ReadFromJsonAsync<Product>();

    createdProduct.ShouldNotBeNull();
    createdProduct.Name.ShouldBeEqualTo(product.Name);
    createdProduct.Price.ShouldBeEqualTo(product.Price);
}

Arrange: Se obtiene una categoría válida desde la base de datos (GetFirstCategory) y se crea un objeto Product con propiedades válidas.
Act: Se envía una solicitud HTTP POST al endpoint /products con los datos del producto. Esto simula una creación de producto en el sistema.
Assert: Se verifica que la respuesta sea exitosa y que los datos del producto creado coincidan con los esperados.

Segunda Prueba: Creación Fallida de un Producto con Categoría Inexistente

La prueba CreateProduct_Fails_WhenCategoryDoesNotExist verifica que la creación de un producto falle cuando se especifica una categoría inválida.

[Fact]
public async Task CreateProduct_Fails_WhenCategoryDoesNotExist()
{
    // Arrange
    var product = new Product
    {
        Name = "Test Product",
        Description = "Test Description",
        Price = 10.0m,
        CategoryId = 0 // Categoría inválida
    };

    // Act
    var response = await _client.PostAsJsonAsync("/products", product);

    // Assert
    response.StatusCode.ShouldBeEqualTo(HttpStatusCode.BadRequest);
}

Arrange: Se crea un objeto Product con una categoría inexistente (CategoryId = 0).
Act: Se envía una solicitud HTTP POST al endpoint /products con el producto, esperando un fallo.
Assert: Se verifica que el servidor responde con un estado BadRequest (400), indicando que la categoría especificada no existe.

Método Auxiliar `GetFirstCategory`

El método GetFirstCategory es una función auxiliar que facilita la recuperación de la primera categoría disponible en la base de datos. Este método permite a las pruebas obtener un CategoryId válido para productos.

private async Task<Category> GetFirstCategory()
{
    return await _dbContext.Categories.FirstAsync();
}

Este enfoque de pruebas ayuda a mantener las pruebas de integración eficientes y confiables, verificando los comportamientos principales del endpoint de creación de productos y manejando casos tanto exitosos como de error.

Cuando Usar Integration Tests o Unit Tests

Las pruebas de software se dividen principalmente en pruebas unitarias e integración, y cada tipo tiene su propósito y contexto de uso. La elección entre uno u otro depende del objetivo de la prueba y del nivel de aislamiento necesario. A continuación, te explicamos cuándo es adecuado utilizar cada tipo de prueba.

Unit Tests: Aislando el Comportamiento de una Funcionalidad Específica

Las pruebas unitarias son el tipo más básico de pruebas. Están diseñadas para verificar el comportamiento de una unidad de código de manera aislada, sin depender de recursos externos como bases de datos, servicios web o sistemas de archivos. Este tipo de pruebas se centran en una pequeña parte del sistema, como un método o función individual, asegurando que se ejecute correctamente bajo diferentes condiciones.

Cuándo usar Unit Tests:

Cuando deseas comprobar el comportamiento de una función o método específico en aislamiento.
Cuando necesitas verificar que una lógica de negocio interna funciona correctamente.
Para asegurar que el código cumple con los requisitos del comportamiento esperado.
Cuando los cambios realizados no deberían afectar otras partes del sistema (por ejemplo, al refactorizar código o agregar nuevas características pequeñas).

Ventajas:

Rápidos de ejecutar: debido a que son pequeños y no requieren recursos externos.
Aislamiento: puedes asegurarte de que las dependencias externas no interfieran.
Fáciles de automatizar: las pruebas unitarias suelen ser fáciles de configurar y ejecutar en una suite de pruebas automatizadas.

Integration Tests: Validando la Interacción entre Componentes

Las pruebas de integración van un paso más allá, probando cómo diferentes unidades de código interactúan entre sí y con sistemas externos, como bases de datos, API, o sistemas de mensajería. Se aseguran de que los componentes del sistema funcionen juntos de la forma esperada.

Cuándo usar Integration Tests:

Cuando necesitas verificar cómo los módulos o servicios interactúan entre sí.
Si deseas probar la integración con sistemas externos como bases de datos, servicios web, o colas de mensajes.
Para validar que los cambios no afecten negativamente la interacción de diferentes capas del sistema.
Para garantizar que la configuración de infraestructura y las dependencias externas (como bases de datos) estén correctamente conectadas y funcionando.

Ventajas:

Cobertura completa de flujo: Validan el flujo real de datos a través de los diferentes componentes del sistema, lo que aumenta la confianza en la funcionalidad de alto nivel.
Identificación de problemas de integración: Detectan problemas en la forma en que los componentes interactúan entre sí, lo cual no se podría verificar con pruebas unitarias.
Reducción de errores en producción: Aseguran que el sistema se comporte correctamente en un entorno más cercano al real.

¿Unit Tests o Integration Tests? ¿Cuándo usar cada uno?

A menudo, la clave está en la combinación adecuada de ambos tipos de pruebas:

Unit Tests: Son el primer paso en el ciclo de vida del desarrollo, permitiendo detectar errores rápidamente y de forma aislada.
Integration Tests: Deben complementarse con las pruebas unitarias para garantizar que todos los componentes funcionen correctamente cuando se ensamblen.

Es decir:

Si estás desarrollando una pequeña funcionalidad que no interactúa con sistemas externos, prioriza las pruebas unitarias.
Si estás trabajando con interacción entre sistemas, bases de datos o servicios externos, añade pruebas de integración para validar estos comportamientos más complejos.

Ambos tipos de pruebas son fundamentales para una estrategia de pruebas completa, y saber cuándo usar cada uno te ayudará a mantener una buena cobertura de pruebas y mejorar la calidad de tu software.

Consideraciones para Escenarios Complejos

Cuando trabajamos con escenarios más allá de las simples operaciones CRUD, es crucial que nuestras pruebas de integración sean flexibles y realistas. A continuación, algunos puntos a considerar:

Datos de Configuración Inicial (Seed Data)

En escenarios complejos, es probable que necesites un conjunto de datos predefinido para representar un estado inicial específico de la base de datos. Utilizar datos de configuración inicial (o "seed data") permite que las pruebas se ejecuten en condiciones que simulan situaciones de negocio más avanzadas.

Estrategia de Configuración: Puedes agregar datos de configuración en la fase de inicialización del WebApplicationFixture. Esto permite que los datos de prueba específicos estén listos cada vez que se ejecuten las pruebas.
Uso de Factories o Builders: Para configurar datos complejos, considera el uso de patrones como Factory o Builder que ayuden a crear objetos con propiedades adecuadas para el escenario, manteniendo el código de prueba más limpio y reutilizable.

Simulación de Estados de la Aplicación

Algunas pruebas pueden requerir que la aplicación esté en un estado específico antes de ejecutar el test (como el "estado de procesamiento" o "finalizado" de una orden). Para simular estos estados:

Configuración de Estados con Estados Mock o Flags: Configura los estados directamente en las entidades de prueba, o utiliza servicios mock (como mocks de notificaciones, correos electrónicos o servicios externos) para simular estados sin requerir que la aplicación ejecute todos los pasos.
Test Doubles: Para escenarios que dependen de servicios externos, considera el uso de "doubles" (dummies, mocks, etc.) que representen estos servicios sin necesidad de hacer llamadas reales. Esto ayuda a centrar la prueba en la lógica de negocio sin complicaciones adicionales.

Verificación de Efectos Colaterales

Cuando las pruebas de integración implican actualizaciones de datos o envío de eventos a otros sistemas, es importante verificar que los efectos colaterales ocurren como se espera.

Simulación de Eventos: Para los sistemas basados en eventos, puedes verificar que los eventos se envíen correctamente o incluso simular la recepción de eventos que la aplicación debe procesar.
Validación de Estados Finales: Después de realizar una operación, verifica que las tablas relevantes y los estados de las entidades reflejen los cambios esperados.

Los escenarios complejos pueden agregar valor significativo a las pruebas de integración, ayudando a identificar problemas difíciles de reproducir en condiciones normales. Aplicar una configuración cuidadosa, incluyendo datos de configuración inicial, control de transacciones, y mocks de estados y dependencias, permitirá manejar estos escenarios de forma efectiva y aumentar la robustez de las pruebas de integración.

Conclusión

Las pruebas de integración son esenciales para garantizar que los componentes de una aplicación funcionen de manera coherente y sin problemas cuando se combinan. A lo largo de este tutorial, hemos visto cómo configurar un entorno de pruebas sólido y flexible utilizando herramientas como xUnit, Testcontainers, Respawn, y WebApplicationFactory en .NET, permitiendo realizar pruebas con una base de datos SQL Server en contenedor y manteniendo un servidor de pruebas en memoria.

Al seguir las prácticas descritas, desde el uso de contenedores hasta la optimización de la infraestructura de pruebas, puedes asegurar que tu aplicación se mantenga estable a lo largo del ciclo de desarrollo. Este enfoque no solo minimiza errores que solo podrían detectarse en producción, sino que también facilita la identificación y resolución de problemas antes de que escalen.

Recuerda que, aunque estas pruebas pueden ser más costosas en términos de tiempo de ejecución y configuración que las pruebas unitarias, la inversión en pruebas de integración robustas proporciona un valor significativo. Estas pruebas ayudan a prevenir fallos graves y aseguran una experiencia de usuario final consistente. Adoptar buenas prácticas de optimización y aprovechar herramientas modernas para la gestión de entornos de prueba te permitirá mantener una suite de pruebas rápida y eficiente, fortaleciendo la confiabilidad de tus aplicaciones en el tiempo.

Referencias

Flexibilidad y Escalabilidad: Usando Strategy y Factory Patterns

Isaac Ojeda — Sat, 26 Oct 2024 18:18:52 +0000

Introducción

En el desarrollo de software, construir aplicaciones modulares y flexibles es esencial para poder adaptarse a cambios de requerimientos y tecnologías. Los patrones de diseño como Strategy y Factory son herramientas poderosas que nos permiten crear soluciones robustas, facilitando la extensión y el mantenimiento del código. Estos patrones nos ayudan a diseñar componentes intercambiables, permitiendo que la lógica central (Core) de la aplicación permanezca independiente de los detalles específicos de cada implementación. En este artículo, exploraremos cómo emplear ambos patrones para gestionar diferentes proveedores de notificaciones de forma dinámica y escalable.

Implementaremos un sistema de notificaciones en el que INotificationsStrategy actúa como la interfaz central que define el contrato para enviar notificaciones, mientras que el Factory Pattern se encarga de construir la estrategia de notificación adecuada según el proveedor configurado. Además, utilizaremos el patrón Decorator para simplificar la inyección de dependencias, inspirándonos en la arquitectura de ASP.NET Core. Veremos cómo esta combinación de patrones nos permite intercambiar servicios de notificación de manera sencilla, hacerlos configurables y extender nuestro sistema sin modificar el Core de la aplicación.

Código Fuente: DevToPosts/StrategyFactoryPattern at main · isaacOjeda/DevToPosts · GitHub

Strategy Pattern

El Strategy Pattern es un patrón de diseño de comportamiento que permite definir una familia de algoritmos, encapsular cada uno y hacerlos intercambiables. Este patrón permite que el algoritmo varíe independientemente del cliente que lo utiliza.

Utilizando el Strategy Pattern, podemos aplicar diferentes estrategias de ejecución para un mismo comportamiento en función de configuraciones o condiciones externas. Este patrón es ideal cuando necesitamos flexibilidad en la lógica de negocio que se aplicará según diferentes condiciones sin modificar el código principal.

Factory Pattern

El Factory Pattern es un patrón de diseño creacional que abstrae el proceso de creación de objetos, permitiendo a las clases delegar la responsabilidad de instanciar sus dependencias. La fábrica selecciona y devuelve la instancia correcta según las necesidades del cliente.

El factory elimina la necesidad de conocer detalles de las clases concretas en el código del cliente, centralizando la creación de objetos y reduciendo el acoplamiento. Este patrón es fundamental cuando el tipo de instancia a crear depende de configuraciones externas o de los datos en tiempo de ejecución.

Al combinar el Strategy Pattern con el Factory Pattern, se logra una arquitectura flexible y escalable, ideal para aplicaciones que deben manejar múltiples implementaciones de un servicio (por ejemplo, múltiples proveedores de notificaciones). La fábrica es responsable de crear la estrategia apropiada en tiempo de ejecución, permitiendo al cliente utilizar la estrategia correcta sin necesidad de lógica adicional.

Ventajas, Desventajas y Consideraciones de Uso

Ventajas

Flexibilidad y Extensibilidad: Implementar patrones como Strategy y Factory permite integrar fácilmente distintas estrategias o servicios sin afectar el Core de la aplicación. Esto minimiza el riesgo de errores al realizar cambios y facilita la expansión de funcionalidades.
Separación de Responsabilidades: Estos patrones promueven principios como el de Responsabilidad Única y la Inversión de Dependencias, lo que resulta en un código más organizado y fácil de mantener.
Facilidad para Pruebas: Al estar desacopladas las implementaciones, resulta sencillo realizar pruebas unitarias y de integración mediante mocks o stubs de las interfaces.
Escalabilidad: A medida que la aplicación crece, puedes añadir nuevas estrategias o servicios sin modificar la lógica del Core, lo cual facilita la evolución del sistema.

Desventajas

Complejidad Añadida: En proyectos pequeños o con lógica sencilla, la implementación de estos patrones puede resultar en una complejidad innecesaria, generando más trabajo del que realmente aporta.
Impacto en el Rendimiento: La abstracción adicional puede ralentizar levemente la ejecución. En aplicaciones de alto rendimiento, es fundamental medir si el costo es justificable.
Curva de Aprendizaje: Para desarrolladores sin experiencia en patrones de diseño, esta estructura puede ser difícil de comprender y mantener.

Consideraciones para su uso

Cuándo utilizar estos patrones:

Si el sistema interactúa con múltiples proveedores o servicios que podrían cambiar, o si el sistema debe ser flexible y fácil de extender, estos patrones son ideales.
Cuando se usa una arquitectura modular (como Hexagonal o Clean Architecture) y se necesita proteger el Core de la aplicación de los detalles de implementación.

Cuándo no utilizarlos:

En sistemas con una sola implementación fija que no necesita cambiarse.
En aplicaciones simples, donde la abstracción adicional puede considerarse sobreingeniería.

Implementando Strategy Pattern Con Factory

En este ejemplo, implementamos una infraestructura de notificaciones utilizando Strategy para definir varias maneras de enviar notificaciones (a través de SendGrid o SMTP) y Factory para decidir cuál estrategia utilizar en función de la configuración.

Application Layer

No entraremos en detalle sobre la organización específica del código, pero estas estrategias suelen emplearse en arquitecturas como Hexagonal o Clean Architecture. Aunque no nos centraremos en cómo estructurar el código, sí es esencial entender qué elementos forman parte del "Core" de la aplicación y cuáles corresponden a detalles externos de los que queremos aislarnos.

Definir un contrato en el Core es fundamental. Este contrato determina las entradas y salidas esperadas sin depender de detalles de implementación específicos. De esta forma, el Core actúa como una "caja negra": no le interesa cómo se implementa cada detalle, solo que se cumpla el contrato definido. Esta flexibilidad hace que el código sea altamente intercambiable, y aquí es donde los patrones Strategy y Factory se vuelven especialmente útiles.

Nota 💡: He implementado estas estrategias en diversos escenarios (almacenamiento, pasarelas de pago, procesamiento de documentos, etc.), y este vídeo me inspiró a escribir este artículo, ya que es una técnica valiosa en muchos de mis proyectos.

Notifications > INotificationsStrategy

Definimos una interfaz INotificationsStrategy, que actúa como contrato para las distintas estrategias de notificación. Cada implementación de esta interfaz representará un proveedor de notificaciones distinto (por ejemplo, SendGrid y SMTP).

public interface INotificationsStrategy
{
    Task<SendNotificationResponse> SendNotification(SendNotificationRequest request);
}

La interfaz asegura que cualquier servicio de notificación que implementemos tendrá el mismo método SendNotification. Esto permite que los clientes (la aplicación) usen cualquier servicio de notificación de manera intercambiable, asegurando consistencia en la estructura del código.

Es fundamental que SendNotificationRequest y SendNotificationResponse permanezcan en el Core de la aplicación y estén completamente desvinculadas de los detalles específicos de cada proveedor de notificaciones. Estas clases son las piezas de información que el Core necesita para realizar una notificación, y al definirlas de forma abstracta, nos aseguramos de que el Core pueda operar independientemente de los detalles específicos de cada implementación.

Dentro de SendNotificationRequest, podríamos incluir datos como el correo electrónico, número de teléfono u otros detalles del usuario que son comunes en las notificaciones, sin que estos datos dependan de un proveedor específico. Cada implementación puede necesitar configuraciones únicas, pero el Core debería mantenerse lo más aislado posible de estas particularidades.

Por ejemplo, una implementación podría requerir una API Key para acceder a su servicio, mientras que otra podría exigir autenticación mediante un usuario y clave secreta para obtener un token. Aunque estas diferencias pueden ser significativas, el Core no debe preocuparse por estos detalles de autenticación y configuración. Los patrones Strategy y Factory nos ayudan a gestionar estas variaciones, permitiéndonos abstraer esas diferencias y mantener el Core limpio y centrado en su función principal.

Notifications > INotificationsFactory

La INotificationsFactory es la interfaz del factory. Define métodos para crear instancias de servicios de notificación basándose en el proveedor configurado.

public interface INotificationsFactory
{
    INotificationsStrategy CreateNotificationService();
}

La fábrica encapsula la lógica de selección de proveedores. Esto significa que cualquier cambio en el método de selección no afectará a los consumidores de los servicios de notificación.

Notifications > NotificationsConfig

NotificationsConfig es una clase de configuración que contiene las configuraciones de los distintos proveedores de notificaciones.

public class NotificationsConfig
{
    public NotificationProvider Provider { get; set; }
    public SendGridConfig? SendGrid { get; set; }
    public SmtpConfig? Smtp { get; set; }
}

public class SendGridConfig
{
    //...
}

public class SmtpConfig
{
    //...
}

La propiedad Provider en NotificationsConfig define el proveedor predeterminado configurado en nuestra aplicación. Este proveedor se establece a través de appsettings.json, lo que facilita configurar y ajustar el servicio de notificaciones sin necesidad de modificar el código.

Si bien en este ejemplo usamos appsettings.json, el propósito del Strategy Pattern es permitir la intercambiabilidad de estrategias en tiempo de ejecución. Esto significa que, además de ser configurable en el archivo de configuración, la estrategia de notificación podría adaptarse dinámicamente según las preferencias del usuario, del tenant o cualquier otra lógica específica de la aplicación. Este enfoque añade flexibilidad al sistema y ayuda a personalizar el servicio para distintos contextos o necesidades en tiempo real.

Infrastructure Layer

Notifications > SendGrid

Implementamos SendGridNotificationService, que utiliza el proveedor de SendGrid para enviar notificaciones. Esta clase es una implementación concreta de INotificationsStrategy.

public class SendGridNotificationService : INotificationsStrategy
{
    private readonly ILogger<SendGridNotificationService> _logger;

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

    public async Task<SendNotificationResponse> SendNotification(SendNotificationRequest request)
    {
        _logger.LogInformation("Using SendGrid to send notification");

        // SendGrid logic here
        await Task.Delay(0);

        return new SendNotificationResponse(true, "Notification sent successfully");
    }
}

Notifications > Smtp

SmtpNotificationsService es otra implementación de INotificationsStrategy, que envía notificaciones utilizando un servidor SMTP.

public class SmtpNotificationsService : INotificationsStrategy
{
    private readonly ILogger<SmtpNotificationsService> _logger;

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

    public async Task<SendNotificationResponse> SendNotification(SendNotificationRequest request)
    {
        _logger.LogInformation("Using SMTP to send notification");

        // Smtp logic here
        await Task.Delay(0);

        return new SendNotificationResponse(true, "Notification sent successfully");
    }
}

Cada clase implementa su propia lógica de envío de notificaciones, pero siguen el mismo contrato INotificationsStrategy. Esto asegura que el código cliente puede cambiar entre distintas implementaciones sin conocer detalles de su funcionamiento interno.

NotificationsService y NotificationsFactory

En NotificationsFactory, creamos las instancias de los servicios de notificación basándonos en el proveedor configurado.

public class NotificationsFactory(
    ILogger<NotificationsFactory> logger,
    IServiceProvider serviceProvider,
    IOptions<NotificationsConfig> notificationsConfig) : INotificationsFactory
{
    public INotificationsStrategy CreateNotificationService()
    {
        var provider = notificationsConfig.Value.Provider;

        logger.LogInformation("Creating notification service for provider {Provider}", provider);

        return provider switch
        {
            NotificationProvider.SendGrid => serviceProvider.GetRequiredService<SendGridNotificationService>(),
            NotificationProvider.Smtp => serviceProvider.GetRequiredService<SmtpNotificationsService>(),
            _ => throw new NotImplementedException($"Notification provider {provider} is not implemented")
        };
    }

    public INotificationsStrategy CreateNotificationService(NotificationProvider provider)
    {
        //...
    }
}

NotificationsFactory centraliza la creación de objetos. Dependiendo del proveedor especificado, crea una instancia del servicio correspondiente sin que el cliente necesite saber cómo se instancia.

Ejemplo de appsettings.json:

  "Notifications": {
    "Provider": "Smtp",
    "SendGrid": {
      "ApiKey": "SG.1234567890"
    },
    "Smtp": {
      "Server": "smtp.server.com",
      "Port": 587,
      "Username": "username",
      "Password": "password"
    }
  }

Aunque en este punto podemos utilizar el Factory directamente en cualquier parte de nuestro código, podemos aplicar el patrón Decorator para simplificar aún más el uso de INotificationsStrategy y hacer que la creación de instancias sea más transparente. Para ello, crearemos la clase NotificationService, que será el punto de acceso principal cuando solicitemos la dependencia INotificationsStrategy. Esto significa que nuestro código usará NotificationService, mientras que NotificationService se encargará internamente de invocar al Factory para crear la instancia de la estrategia correcta.

Nota 💡: Este método de creación de objetos está inspirado en la implementación de IStringLocalizer y IStringLocalizerFactory en ASP.NET Core. Al usar IStringLocalizer, el framework invoca internamente el Factory para crear las instancias requeridas en función de la configuración establecida.
Más información: aspnetcore/src/Localization/Abstractions/src/StringLocalizerOfT.cs at main · dotnet/aspnetcore

Nota 2💡: Explorar el código fuente puede ser de gran ayuda. Revisar, leer y ejecutar el código no solo profundiza el conocimiento de estos conceptos, sino que también puede ayudarte a ver cómo los patrones se aplican en la práctica.

public class NotificationService(INotificationsFactory notificationsFactory) : INotificationsStrategy
{
    private INotificationsStrategy notificationsStrategy = notificationsFactory.CreateNotificationService();

    public async Task<SendNotificationResponse> SendNotification(SendNotificationRequest request)
    {
        return await notificationsStrategy.SendNotification(request);
    }
}

Program.cs

En el archivo Program.cs, configuramos la inyección de dependencias. Aquí registramos INotificationsFactory, INotificationsStrategy y las implementaciones específicas de cada proveedor.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddScoped<INotificationsStrategy, NotificationService>();
builder.Services.AddScoped<INotificationsFactory, NotificationsFactory>();
builder.Services.AddScoped<SendGridNotificationService>();
builder.Services.AddScoped<SmtpNotificationsService>();

builder.Services.Configure<NotificationsConfig>(builder.Configuration.GetSection("Notifications"));

var app = builder.Build();

app.MapPost("/send", async (SendNotificationRequest request, INotificationsStrategy notificationService) =>
{
    var response = await notificationService.SendNotification(request);

    return response.IsSuccess ? Results.Ok(response) : Results.BadRequest(response);
});

app.Run();

Conclusión

Al combinar los patrones Strategy y Factory, hemos creado un sistema de notificaciones flexible y fácil de extender, en el que distintas implementaciones de notificación pueden integrarse sin afectar la lógica central de la aplicación. Esta estructura modular permite que el código sea adaptable y escalable, lo que es fundamental en entornos en los que los requisitos y las tecnologías cambian constantemente. La incorporación de un patrón Decorator adicional facilita la inyección de dependencias, manteniendo el uso de las notificaciones simple y organizado.

Estos patrones aportan claridad y robustez a la arquitectura del sistema, permitiendo que el Core de la aplicación se mantenga desacoplado de los detalles de implementación específicos de cada proveedor de notificaciones. Este enfoque también fomenta la reutilización y facilita el mantenimiento a largo plazo, ya que se pueden agregar o modificar servicios sin necesidad de realizar cambios significativos. La implementación de patrones de diseño bien aplicados no solo mejora la estructura del código, sino que también enriquece el proceso de desarrollo, proporcionando una base sólida para futuros requerimientos y funcionalidades.

Estrategias para Encapsular Dependencias Externas: Creación componentes personalizados en Angular

Isaac Ojeda — Wed, 14 Aug 2024 18:00:53 +0000

Introducción

En el desarrollo de aplicaciones web modernas, la reutilización y la mantenibilidad del código son cruciales para garantizar el éxito a largo plazo. Una de las formas de lograrlo es mediante la creación de componentes personalizados, que no solo encapsulan funcionalidad específica, sino que también sirven como una capa de abstracción sobre las bibliotecas externas. Este enfoque permite minimizar la dependencia directa de terceros, reduciendo el impacto de futuros cambios en estas bibliotecas.

En este artículo, exploraremos cómo crear un componente personalizado en Angular que actúe como una abstracción sobre un componente de Kendo UI. También abordaremos la importancia de la abstracción en sistemas de largo plazo y cómo las dependencias externas pueden convertirse en un problema en sistemas grandes.

Creación de Componentes Personalizados

Creación del Date Picker

Imaginemos que estás utilizando Kendo UI en tu proyecto Angular para manejar componentes UI como el Date Picker. Sin embargo, has notado que cualquier actualización en Kendo UI podría forzarte a cambiar decenas o incluso cientos de archivos en tu código base. Para mitigar este riesgo, puedes crear un componente personalizado que encapsule la lógica del Date Picker, permitiéndote modificar la implementación subyacente sin afectar el resto de tu aplicación.

Aquí te mostramos cómo hacerlo:

import { Component, EventEmitter, forwardRef, Input, Output } from '@angular/core';
import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';

@Component({
  selector: 'custom-date-input',
  template: `
    <kendo-datepicker [format]="format" [value]="value" (valueChange)="onValueChange($event)" [disabled]="disabled">
    </kendo-datepicker>
  `,
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: forwardRef(() => DateInputComponent),
      multi: true,
    }
  ]
})
export class DateInputComponent implements ControlValueAccessor {
  @Input()
  public value: Date | null = null;

  @Input()
  public format: string = 'dd/MM/yyyy';

  @Output()
  public valueChange: EventEmitter<Date> = new EventEmitter<Date>();

  public disabled: boolean = false;

  private onChange = (value: any) => { };
  private onTouched = () => { };

  writeValue(value: any): void {
    this.value = value;
  }

  registerOnChange(fn: any): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: any): void {
    this.onTouched = fn;
  }

  setDisabledState?(isDisabled: boolean): void {
    this.disabled = isDisabled;
  }

  onValueChange(value: Date): void {
    this.value = value;
    this.onChange(value);
    this.onTouched();
    this.valueChange.emit(value);
  }
}

Este componente personalizado DateInputComponent actúa como una abstracción sobre el componente kendo-datepicker, permitiendo el binding bidireccional de su valor y emitiendo eventos cuando el valor cambia. Esto permite que tu aplicación utilice un Date Picker sin estar acoplada directamente a la implementación de Kendo.

Explicación del Código del `DateInputComponent`

El DateInputComponent es un componente Angular personalizado que encapsula un kendo-datepicker, proporcionando una interfaz consistente y reutilizable para manejar entradas de fecha en tu aplicación. A continuación, desglosamos cada parte clave del componente:

import { Component, EventEmitter, forwardRef, Input, Output } from '@angular/core';
import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';

Importaciones y Configuración Inicial

Angular Core Imports: Importamos las funcionalidades principales de Angular como Component, Input, Output, y EventEmitter.
ControlValueAccessor: Esta interfaz permite que nuestro componente actúe como un puente entre el valor de un formulario y la vista del componente, permitiendo la integración con formularios reactivos y basados en plantillas.
NG_VALUE_ACCESSOR: Utilizamos este token para registrar nuestro componente como un proveedor de ControlValueAccessor, lo que permite que Angular lo reconozca como un input de formulario.

Decorador @Component

@Component({
  selector: 'darwin-date-input',
  template: `
    <kendo-datepicker [format]="format" [value]="value" (valueChange)="onValueChange($event)" [disabled]="disabled">
    </kendo-datepicker>
  `,
  styleUrls: ['./date-input.component.css'],
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: forwardRef(() => DateInputComponent),
      multi: true,
    }
  ]
})

selector: Define el nombre del elemento HTML que representará este componente en la aplicación.
template: El componente encapsula un kendo-datepicker, pasando las propiedades como format, value, y disabled. También maneja el evento valueChange para actualizar el valor del componente.
providers: Registra el componente como un ControlValueAccessor, permitiendo que funcione en formularios de Angular.

Propiedades y Constructor

export class DateInputComponent implements BaseInput<Date>, ControlValueAccessor {
  @Input()
  public value: Date | null;
  @Input()
  public format: string = 'dd/MM/yyyy';

  @Output()
  public valueChange: EventEmitter<Date>;
  public disabled: boolean = false;

  private onChange = (value: any) => { };
  private onTouched = () => { };

  constructor() {
    this.value = null;
    this.valueChange = new EventEmitter<Date>();
  }

@Input() value: Este es el valor del kendo-datepicker, que se enlaza bidireccionalmente con el formulario.
@Input() format: Permite configurar el formato de fecha desde el exterior del componente. Si no se proporciona un formato, utiliza uno por defecto.
@Output() valueChange: Este evento se emite cuando el valor de la fecha cambia, permitiendo a otros componentes reaccionar a los cambios de valor.
disabled: Controla si el input de fecha está habilitado o deshabilitado.
onChange y onTouched: Estas funciones son definidas para cumplir con la interfaz ControlValueAccessor, permitiendo que Angular controle el estado y los cambios del input.

Métodos Implementados

writeValue(obj: any): void {
  this.value = obj;
}

registerOnChange(fn: any): void {
  this.onChange = fn;
}

registerOnTouched(fn: any): void {
  this.onTouched = fn;
}

setDisabledState?(isDisabled: boolean): void {
  this.disabled = isDisabled;
}

onValueChange(value: Date): void {
  this.value = value;
  this.onChange(value);
  this.onTouched();
}

writeValue(obj: any): Este método se invoca cuando Angular necesita actualizar el valor del componente desde el formulario. Simplemente asigna el valor recibido a la propiedad value.
registerOnChange(fn: any) y registerOnTouched(fn: any): Angular pasa funciones a estos métodos para manejar los cambios en el componente y cuando el usuario interactúa con él. Guardamos estas funciones para llamarlas posteriormente.
setDisabledState(isDisabled: boolean): Permite a Angular habilitar o deshabilitar el componente según sea necesario.
onValueChange(value: Date): Este método se invoca cuando el usuario selecciona una fecha nueva. Actualiza el valor del componente y notifica a Angular sobre el cambio, garantizando que la vista y el modelo del formulario estén sincronizados.

Resumen

El DateInputComponent es un ejemplo de cómo encapsular la funcionalidad de componentes de terceros, como Kendo UI, dentro de tu propia interfaz abstracta. Este enfoque no solo te proporciona mayor flexibilidad y control sobre tu código, sino que también te protege contra cambios en las bibliotecas externas, minimizando el impacto en tu base de código cuando necesitas actualizar o reemplazar esas dependencias.

Unit Testing

Es fundamental garantizar que tu componente personalizado funcione correctamente en todas las situaciones posibles. Para ello, puedes crear pruebas unitarias que validen su comportamiento:

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { DateInputComponent } from './date-input.component';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { DateInputsModule } from '@progress/kendo-angular-dateinputs';

describe('DateInputComponent', () => {
  let component: DateInputComponent;
  let fixture: ComponentFixture<DateInputComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [DateInputComponent],
      imports: [FormsModule, ReactiveFormsModule, BrowserAnimationsModule, DateInputsModule]
    }).compileComponents();
  });

  beforeEach(() => {
    fixture = TestBed.createComponent(DateInputComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });

  it('should emit valueChange event when value changes', () => {
    spyOn(component.valueChange, 'emit');
    const newValue = new Date('2024-01-01');
    component.onValueChange(newValue);
    expect(component.valueChange.emit).toHaveBeenCalledWith(newValue);
  });

  it('should reflect the value in the template', () => {
    const newValue = new Date('2024-01-01');
    component.writeValue(newValue);
    fixture.detectChanges();
    const datePickerElement: HTMLElement = fixture.nativeElement.querySelector('kendo-datepicker');
    expect(datePickerElement.getAttribute('ng-reflect-value')).toBe('2024-01-01T00:00:00.000Z');
  });
});

Estas pruebas aseguran que el componente funcione correctamente en términos de creación, emisión de eventos, y sincronización del valor con la plantilla.

Uso del Componente Personalizado

Una vez que has creado tu componente DateInputComponent, puedes usarlo en formularios tanto reactivos como basados en plantillas. A continuación, se muestra cómo integrar este componente en ambos enfoques.

💡 Nota: Este componente no se encuentra en ningún módulo, será necesario que hagas tu módulo de componentes y luego utilizarlo en algún otro módulo o importar todos tus componentes directamente en el módulo donde lo necesites.

Uso con Reactive Forms

Los formularios reactivos en Angular son ideales para manejar formularios complejos, donde se necesita un mayor control sobre la validación y la lógica del formulario. Aquí te muestro cómo utilizar el componente DateInputComponent en un formulario reactivo:

import { Component, OnInit } from '@angular/core';
import { FormBuilder, FormGroup } from '@angular/forms';

@Component({
  selector: 'app-reactive-form-example',
  template: `
    <form [formGroup]="form">
      <label for="date">Select Date:</label>
      <custom-date-input formControlName="date" #dateInput></custom-date-input>
    </form>
    <p>Selected Date: {{dateInput.value | date: 'dd/MM/yyyy'}}</p>
  `
})
export class ReactiveFormExampleComponent implements OnInit {
  form!: FormGroup;

  constructor(private fb: FormBuilder) {}

  ngOnInit(): void {
    this.form = this.fb.group({
      date: [new Date()]
    });
  }
}

En este ejemplo:

Se utiliza FormBuilder para crear un formulario reactivo con un control de fecha (date).
El componente DateInputComponent se integra con el formulario utilizando formControlName.
La fecha seleccionada se muestra debajo del formulario utilizando la propiedad value del control de fecha.

Uso con Template-Driven Forms

Los formularios basados en plantillas son más adecuados para formularios más simples, donde el control directo de la lógica y la validación del formulario no es tan crucial. Aquí se muestra cómo usar el componente DateInputComponent en un formulario basado en plantillas:

import { Component } from '@angular/core';

@Component({
  selector: 'app-template-driven-form-example',
  template: `
    <form #form="ngForm">
      <label for="date">Select Date:</label>
      <custom-date-input name="date" [(ngModel)]="date"></custom-date-input>
    </form>
    <p>Selected Date: {{ date | date }}</p>
  `
})
export class TemplateDrivenFormExampleComponent {
  date: Date = new Date();
}

En este ejemplo:

El componente DateInputComponent se utiliza dentro de un formulario basado en plantillas.
Se usa [(ngModel)] para crear un binding bidireccional entre el valor del componente y la propiedad date.
La fecha seleccionada se muestra debajo del formulario utilizando el valor de date.

Conclusión

La abstracción es una herramienta poderosa en el desarrollo de software, especialmente en proyectos de larga duración. Al encapsular componentes de bibliotecas externas en componentes personalizados, puedes proteger tu código de los cambios en estas dependencias, mejorando así la mantenibilidad y reduciendo el riesgo de errores en el futuro.

En sistemas grandes, la dependencia directa de bibliotecas externas puede llevar a problemas de actualización y mantenimiento, ya que los cambios en esas bibliotecas pueden requerir modificaciones extensivas en el código. Al crear una capa de abstracción, puedes aislar estas dependencias y asegurar que las futuras actualizaciones de las bibliotecas tengan un impacto mínimo en tu aplicación.

Este enfoque no solo facilita la gestión del código a largo plazo, sino que también mejora la flexibilidad y la capacidad de adaptación de tu aplicación a nuevas tecnologías y necesidades emergentes. La clave es encontrar un equilibrio entre reutilización y abstracción para mantener un código limpio, modular y fácil de mantener.

Localización en ASP.NET Core: Cómo Implementar Traducciones Dinámicas Usando una Base de Datos

Isaac Ojeda — Mon, 12 Aug 2024 13:07:38 +0000

Introducción

En aplicaciones modernas, la localización es un aspecto crucial para ofrecer una experiencia personalizada a los usuarios de diferentes culturas e idiomas. ASP.NET Core nos proporciona una manera sencilla de implementar la localización utilizando archivos de recursos, pero este enfoque puede no ser ideal para todos los escenarios. Los archivos de recursos (archivos XML), pueden volverse difíciles de gestionar a medida que crecen en tamaño y número, especialmente cuando se trata de aplicaciones que soportan múltiples idiomas y requieren actualizaciones frecuentes.

En este artículo, exploraremos cómo podemos ir más allá de las opciones predeterminadas y construir una solución de localización personalizada utilizando una base de datos como fuente de los textos localizados. Este enfoque nos ofrece una mayor flexibilidad y desacoplamiento del código, permitiendo agregar y modificar traducciones sin necesidad de redeploys ni cambios en el código fuente.

Veremos cómo implementar esta solución utilizando ASP.NET Core, Entity Framework Core, y el concepto de IStringLocalizer e IStringLocalizerFactory para crear una infraestructura que pueda adaptarse a las necesidades específicas de cualquier proyecto. Al final de este artículo, tendrás una base sólida para implementar localización basada en bases de datos, permitiendo a tus aplicaciones manejar traducciones de manera más eficiente y escalable.

Localización personalizada en ASP.NET Core

La implementación predeterminada de localización en ASP.NET Core se basa en archivos de recursos (resources files). Estos archivos son un arma de doble filo: puedes amarlos u odiarlos.

Cuando trabajas con múltiples idiomas y una gran cantidad de textos por traducir, los archivos XML pueden volverse difíciles de mantener y gestionar. A menos que estés usando Visual Studio, manejar estos archivos puede ser un verdadero dolor de cabeza.

Algunos frameworks, como ABP, ofrecen soluciones basadas en archivos JSON, lo cual es un avance. Sin embargo, lo que quiero demostrar en este artículo es que no estamos limitados a las opciones que otros nos ofrecen. Podemos implementar la localización de la manera que mejor se adapte a nuestras necesidades.

En la siguiente sección, exploraremos cómo implementar una solución de localización que no se base en archivos XML o JSON, sino en una base de datos.

Localización por Base de Datos

Implementar la localización utilizando una base de datos tiene sus ventajas y desventajas, que vamos a analizar en detalle.

Ventajas

Desacoplamiento del Proyecto: Una de las principales ventajas es que los recursos de localización no están embebidos en el código ni en el repositorio, lo que permite que las traducciones evolucionen sin necesidad de modificar el código ni realizar nuevos deployments. Esto facilita la gestión y reduce el tiempo de inactividad.
Facilidad de Expansión: Agregar nuevos idiomas es tan simple como insertar registros adicionales en la base de datos. No es necesario cambiar el código ni hacer nuevos despliegues, lo que permite una expansión rápida y menos propensa a errores.
Centralización y Mantenimiento: Al centralizar todas las traducciones en una base de datos, es más fácil mantener y auditar los recursos. Puedes aplicar reglas de negocio, implementar sistemas de validación y tener una vista centralizada de todos los textos traducidos.
Interfaz de Usuario para Edición: Puedes desarrollar una interfaz administrativa que permita a los usuarios no técnicos agregar o modificar traducciones directamente en la base de datos, sin necesidad de la intervención del equipo de desarrollo.

Desventajas

Rendimiento y Caché: Es crucial implementar un sistema de caché efectivo, ya que acceder a la base de datos para cada traducción podría impactar negativamente el rendimiento de la aplicación.
Complejidad de Gestión: Aunque esta solución es flexible, la gestión de las traducciones en la base de datos puede ser complicada, especialmente en sistemas con múltiples culturas e idiomas. Se requiere una estrategia clara para evitar duplicidades, inconsistencias y garantizar que las traducciones estén siempre actualizadas.
Dependencia de la Base de Datos: La localización depende de la disponibilidad y el rendimiento de la base de datos. Si la base de datos experimenta problemas, la localización podría verse afectada, impactando la experiencia del usuario final.
Sin Soporte Out-of-the-Box: A diferencia de los archivos de recursos predeterminados, esta solución requiere más configuración y personalización, lo que implica un mayor esfuerzo inicial en términos de desarrollo y pruebas.

LocalizationResource

Para implementar la localización en una base de datos, utilizaremos Entity Framework Core para manejar la persistencia. La clase LocalizationResource será la encargada de representar cada recurso localizado.

namespace CustomLocalization.Localization.Data;

public class LocalizationResource
{
    public int Id { get; set; }
    public string Culture { get; set; }
    public string Key { get; set; }
    public string Value { get; set; }
    public string AssemblyName { get; set; }
}

Las propiedades incluidas son:

Id: Identificador único del recurso.
Culture: La cultura del recurso (por ejemplo, es-MX, en-US).
Key: La clave utilizada para identificar el recurso.
Value: La cadena de texto traducida.
AssemblyName: El nombre del ensamblado donde se encuentra el recurso localizado (esto es útil cuando se localizan clases específicas).

LocalizationDbContext

El contexto de la base de datos también es bastante sencillo y sigue las convenciones estándar de Entity Framework Core:

using Microsoft.EntityFrameworkCore;

namespace CustomLocalization.Localization.Data;

public class LocalizationDbContext(DbContextOptions<LocalizationDbContext> options) : DbContext(options)
{
    public DbSet<LocalizationResource> LocalizationResources { get; set; }
}

DatabaseStringLocalizer

Aquí es donde comienza la parte interesante. Necesitaremos dos componentes clave: IStringLocalizer y IStringLocalizerFactory. Estos trabajan en conjunto, de manera similar a cómo ASP.NET Core utiliza archivos XML de recursos, para construir un IStringLocalizer<SomeClass> utilizando el Factory que vamos a definir.

La implementación de IStringLocalizer utilizando Entity Framework Core podría verse así:

using CustomLocalization.Localization.Data;
using Microsoft.Extensions.Localization;

namespace CustomLocalization.Localization;

public class DatabaseStringLocalizer : IStringLocalizer
{
    private readonly LocalizationDbContext _context;
    private readonly string _culture;
    private readonly string _assemblyName;
    private readonly List<LocalizationResource> _assemblyResources;
    public DatabaseStringLocalizer(LocalizationDbContext context, string culture, string assemblyName)
    {
        _context = context;
        _culture = culture;
        _assemblyName = assemblyName;

         // TODO: Guardar en caché es un MUST
        _assemblyResources = _context.LocalizationResources
            .Where(r => r.Culture == _culture && r.AssemblyName == _assemblyName)
            .ToList();
    }

    public LocalizedString this[string name]
    {
        get
        {
            var resource = _assemblyResources.FirstOrDefault(r => r.Key == name);
            if (resource == null)
            {
                return new LocalizedString(name, name, true);
            }

            return new LocalizedString(name, resource.Value, false);
        }
    }

    public LocalizedString this[string name, params object[] arguments]
    {
        get
        {
            var resource = _assemblyResources.FirstOrDefault(r => r.Key == name);
            if (resource == null)
            {
                return new LocalizedString(name, name, true);
            }

            return new LocalizedString(name, resource.Value, false);
        }
    }

    public IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures)
    {
        return _assemblyResources.Select(r => new LocalizedString(r.Key, r.Value, false));
    }
}

Explicación del Código

En la clase DatabaseStringLocalizer, estamos implementando la interfaz IStringLocalizer, que es esencial para manejar la localización en ASP.NET Core. Este StringLocalizer se conecta a la base de datos para buscar las cadenas de texto traducidas según la cultura actual y el ensamblado que se está utilizando.

Constructor: El constructor toma como parámetros el contexto de base de datos LocalizationDbContext, la cultura actual y el nombre del ensamblado. Luego, consulta la base de datos para obtener todos los recursos localizados que coincidan con la cultura y el ensamblado, almacenándolos en una lista.
Indexer: El indexador this[string name] se utiliza para obtener el texto traducido correspondiente a una clave. Si no se encuentra ninguna traducción, se devuelve la clave original, indicando que la cadena no ha sido localizada. ==Esto es útil para evitar errores en caso de que falten traducciones==.
GetAllStrings: Este método devuelve todas las cadenas localizadas disponibles para la cultura y ensamblado especificados. Es útil para casos donde se necesita mostrar una lista completa de traducciones, como en una interfaz de administración.

StringLocalizationFactory

El StringLocalizationFactory es responsable de crear instancias de IStringLocalizer basadas en la cultura actual y el recurso solicitado. Este factory sigue el patrón de diseño Factory, delegando la creación de objetos a una clase especializada.

using CustomLocalization.Localization.Data;
using Microsoft.Extensions.Localization;
using System.Globalization;

namespace CustomLocalization.Localization;

public class StringLocalizationFactory(IServiceProvider serviceProvider) : IStringLocalizerFactory
{
    public IStringLocalizer Create(Type resourceSource)
    {
        var currentCulture = CultureInfo.CurrentCulture.Name;
        var assembly = resourceSource.FullName;
        using var scope = serviceProvider.CreateScope();
        var context = scope.ServiceProvider.GetRequiredService<LocalizationDbContext>();

        return new DatabaseStringLocalizer(context, currentCulture, assembly);
    }

    public IStringLocalizer Create(string baseName, string location)
    {
        var currentCulture = CultureInfo.CurrentCulture.Name;
        using var scope = serviceProvider.CreateScope();
        var context = scope.ServiceProvider.GetRequiredService<LocalizationDbContext>();

        return new DatabaseStringLocalizer(context, currentCulture, baseName);
    }
}

Explicación del Código

El StringLocalizationFactory facilita la creación de IStringLocalizer utilizando la cultura actual y el recurso solicitado. Es un factory singleton, lo que significa que crea instancias de localizadores según sea necesario, y utiliza un scope para manejar las dependencias.

Create(Type resourceSource): Este método toma como parámetro un tipo (Type) que representa la clase o ensamblado que solicita el IStringLocalizer. Utilizando la cultura actual y el nombre completo del ensamblado, crea un nuevo DatabaseStringLocalizer que obtiene las traducciones correspondientes de la base de datos.
Create(string baseName, string location): Este método es una sobrecarga del anterior y permite crear un IStringLocalizer utilizando un nombre base (baseName) y una ubicación (location). Es útil cuando se desea especificar manualmente el nombre y la ubicación de los recursos de localización.

HomeEndpoint

En el siguiente ejemplo, se demuestra cómo cualquier clase puede tener su propia localización, similar a cómo funciona en ASP.NET Core de forma predeterminada.

El endpoint que se presenta a continuación simplemente retorna la traducción del texto Hello, World!. Este enfoque sigue el mismo estilo de ASP.NET Core, permitiendo desarrollar aplicaciones sin preocuparse inicialmente por la localización. Los textos se proporcionan como claves en un idioma predeterminado, generalmente el inglés.

Este estilo es altamente flexible, ya que no es necesario realizar ninguna configuración adicional durante el desarrollo. Solo en producción se deben proporcionar las traducciones correspondientes. Si una traducción no existe, se devolverá la clave original, que representa el texto en el idioma predeterminado.

using Microsoft.Extensions.Localization;

namespace CustomLocalization.Endpoints;

public class HomeEndpoint
{
    public static IResult Index(IStringLocalizer<HomeEndpoint> localizer)
    {
        return Results.Ok(localizer["Hello, World!"]);
    }
}

IStringLocalizer se puede utilizar en cualquier parte de la aplicación, como en un Controller, una vista de Razor, Blazor Server, entre otros.

Program

En esta sección configuramos las dependencias necesarias.

Como podrás observar, no estamos agregando directamente el DatabaseStringLocalizer al contenedor de dependencias. En su lugar, estamos utilizando la implementación predeterminada de ASP.NET Core llamada StringLocalizer.

Esta clase utiliza internamente el IStringLocalizerFactory, que en nuestro caso es StringLocalizationFactory. Aunque este nombre podría cambiarse a algo más descriptivo que haga referencia a la base de datos 😅, lo que hace esta fábrica es crear instancias del DatabaseStringLocalizer, lo que sigue un patrón de fábrica (Factory Pattern). Este patrón permite una abstracción clara entre la lógica de creación de objetos y su uso.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// other services...

builder.Services.AddSingleton<IStringLocalizerFactory, StringLocalizationFactory>();
builder.Services.AddTransient(typeof(IStringLocalizer<>), typeof(StringLocalizer<>));

builder.Services.AddDbContext<LocalizationDbContext>(opts => opts
    .UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
    
// other services...

var app = builder.Build();

// Localización de cada Request va primero que todo
app.UseRequestLocalization(new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture("en-US"),
    SupportedCultures = new List<CultureInfo>
    {
        new("en-US"),
        new("es-MX"),
        new("de-DE")
    },
    SupportedUICultures = new List<CultureInfo>
    {
        new("en-US"),
        new("es-MX"),
        new("de-DE")
    }
});

// Configure the HTTP request pipeline.
// other middelwares...

app.MapGet("/api", HomeEndpoint.Index);

// stuff...

Explicación de `UseRequestLocalization`

El middleware UseRequestLocalization se encarga de configurar la localización para cada request. Aquí se define la cultura predeterminada (en-US) y las culturas que la aplicación soporta (en-US, es-MX y de-DE). Este middleware se ejecuta antes que cualquier otro, asegurando que la cultura esté correctamente establecida para el procesamiento de la solicitud.

Si en la base de datos existe la localización adecuada, la aplicación retornará el texto configurado según la cultura del sistema.

Al realizar una solicitud al endpoint y establecer el encabezado HTTP Accept-Language, obtendremos el siguiente resultado. Para más información, puedes consultar la documentación oficial.

Conclusión

La localización es una característica clave en el desarrollo de aplicaciones globales, y ASP.NET Core ofrece una solución incorporada que es suficiente para la mayoría de los proyectos. Sin embargo, en situaciones donde se requiere un mayor control o flexibilidad, como en el manejo de grandes volúmenes de traducciones o la necesidad de actualizar idiomas sin redeploys, una localización personalizada puede ser una excelente opción.

En este artículo, hemos explorado cómo implementar una solución de localización basada en bases de datos, utilizando IStringLocalizer y IStringLocalizerFactory personalizados con Entity Framework Core. Este enfoque permite desacoplar los recursos localizados del código fuente, facilitando la gestión de traducciones y la adición de nuevos idiomas de manera más dinámica.

Es importante destacar que este es solo un ejemplo de cómo se puede personalizar la localización en ASP.NET Core. Las posibilidades son prácticamente ilimitadas: podrías extender esta idea para almacenar traducciones en archivos JSON, consumirlas desde una API externa, o incluso combinar varios métodos según las necesidades específicas de tu proyecto.

Aunque la solución incorporada de ASP.NET Core es suficiente en muchos casos, tener la capacidad de personalizar y extender la localización abre la puerta a nuevas oportunidades para crear aplicaciones más flexibles y adaptables. Espero que este artículo te haya dado una perspectiva valiosa sobre cómo puedes llevar la localización en tus proyectos al siguiente nivel.

Mejorando la Observabilidad en ASP.NET Core con OpenTelemetry y Aspire

Isaac Ojeda — Mon, 01 Apr 2024 15:01:08 +0000

Introducción

En el ámbito del desarrollo de aplicaciones modernas, la observabilidad se ha vuelto crucial para garantizar el rendimiento y la fiabilidad de nuestros sistemas distribuidos. OpenTelemetry ha surgido como un estándar para recopilar datos de telemetría en tiempo real. En este artículo, exploraremos cómo integrar OpenTelemetry en una aplicación ASP.NET Core con Blazor, con un enfoque central en el uso de Aspire. Aspire ofrece un Dashboard potente que nos permite visualizar y analizar datos de telemetría, facilitando la monitorización y el diagnóstico del comportamiento de nuestras aplicaciones en tiempo real. Utilizaremos un ejemplo práctico para demostrar su implementación y cómo puede potenciar nuestra capacidad de observabilidad.

Dashboard standalone de Aspire

.NET Aspire está emergiendo como una herramienta sumamente poderosa para el desarrollo de aplicaciones cloud native en el ecosistema .NET, además de otras plataformas.

Es fascinante observar lo sencillo que resulta comenzar a desarrollar con Aspire, abordando muchos aspectos que suelen ser tediosos o complicados de manejar. Sin embargo, ¿qué sucede con las aplicaciones ya existentes? No siempre es viable cambiar por completo el enfoque y adoptar Aspire como orquestador en nuestro entorno de desarrollo. Sin embargo, resulta tentador aprovechar las características que ofrece su dashboard.

Es posible que en aplicaciones ya establecidas, ya sean distribuidas o no, ya hayamos resuelto la forma de ejecutarlas. No obstante, Aspire y su dashboard nos brindan una herramienta sumamente valiosa durante la fase de desarrollo.

Contar con un panel de control que nos proporcione logs, métricas y traces es de gran ayuda para comprender nuestra aplicación y cómo se comporta al interactuar con servicios, bases de datos u otros componentes.

Por eso, el hecho de que el dashboard pueda utilizarse con un receptor OTLP (OpenTelemetry Protocol) y visualizar todos estos datos de manera integrada fue lo que realmente me convenció para explorar su uso.

Para ejecutar el Dashboard de Aspire, podemos utilizar el siguiente comando de Docker:

docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard mcr.microsoft.com/dotnet/nightly/aspire-dashboard:8.0.0-preview.4

Este comando creará y ejecutará un contenedor Docker llamado aspire-dashboard, que aloja el Dashboard de Aspire. El Dashboard estará disponible en el puerto 18888, mientras que el puerto para el OTLP será el 4317.

Una vez que el contenedor esté en ejecución, puedes acceder al Dashboard navegando a http://localhost:18888/ en tu navegador web. Ten en cuenta que inicialmente el Dashboard no mostrará datos hasta que una aplicación comience a enviar información a través del protocolo OTLP.

El Dashboard de Aspire es una herramienta versátil que puede utilizarse con cualquier aplicación que exporte sus datos utilizando el protocolo OTLP. Esto significa que no importa la plataforma en la que estés desarrollando (ya sea .NET, Java, Python, Go, etc.), siempre y cuando puedas configurar tu aplicación para enviar datos mediante OTLP, podrás visualizar y analizar esa información en el Dashboard de Aspire.

Nota 💡: Como costumbre, el código fuente: DevToPosts/AspireDashboard/OpenTelemetryExample · isaacOjeda/DevToPosts (github.com)

Ejemplo de Aplicación Web

En este ejemplo, crearemos una aplicación web utilizando Blazor Server Side Rendering, utilizando la configuración por defecto que proporciona ASP.NET Core, incluyendo páginas de ejemplo y demás. Luego, agregaremos los siguientes paquetes necesarios para integrar OpenTelemetry:

<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.7.0" /> <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.7.0" /> <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.7.1" /> <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.7.1" /> <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.7.0" />

Es importante destacar que todo lo que exploraremos en este artículo es aplicable a cualquier tipo de aplicación desarrollada en ASP.NET Core.

Si deseas comprender primero cómo funciona OpenTelemetry, ya he escrito un artículo al respecto disponible en este enlace. Además, su documentación oficial es bastante detallada y útil para obtener una comprensión más profunda.

Consumiendo una API externa

Para ilustrar un ejemplo claro de traces, vamos a consumir una API pública y gratuita de Pokémon (¡yeei!).

El procedimiento es simple: crearemos un servicio llamado PokemonService para consultar todos los Pokémon disponibles utilizando paginación. Luego, utilizaremos este servicio para mostrar los datos consultados en un componente de Blazor.

using System.Diagnostics;

namespace OpenTelemetryExample;

public class PokemonService(ILogger<PokemonService> logger, HttpClient http)
{
    public const string ActivitySourceName = "DownloadPokemon";
    private static readonly ActivitySource ActivitySource = new(ActivitySourceName);

    public async Task<PokemonList> GetPokemonAsync(int pageSize, int currentPage)
    {
        using var activity = ActivitySource.StartActivity("GetPokemon", ActivityKind.Producer);

        var url = $"https://pokeapi.co/api/v2/pokemon?limit={pageSize}&offset={currentPage * pageSize}";
        var list = await http.GetFromJsonAsync<PokemonList>(url);

        return list ?? new PokemonList
        {
            Next = null,
            Previous = null,
            Results = []
        };
    }
}

public class Pokemon
{
    public required string Name { get; init; }
    public required string Url { get; init; }
}

public class PokemonList
{
    public int Count { get; init; }
    public required string? Next { get; init; }
    public required string? Previous { get; init; }
    public required List<Pokemon> Results { get; init; }
}

La clase ActivitySource se utiliza para generar actividades de traces, lo que nos permite registrar eventos relacionados con la descarga de datos de la API de Pokémon. Estos traces pueden ser útiles para entender el rendimiento de la aplicación y depurar posibles problemas.

Dentro del método GetPokemonAsync, iniciamos una actividad del trace llamada "GetPokemon" utilizando ActivitySource.StartActivity. Esto nos permite registrar el inicio y la finalización de la operación de obtención de datos. Luego, hacemos una solicitud HTTP a la API de Pokémon para obtener una lista de Pokémon, y devolvemos los resultados obtenidos.

Te invito a revisar el código fuente para explorar el componente de Blazor que utiliza el servicio PokemonService. Sin embargo, por cuestiones de relevancia para este post, he omitido incluirlo directamente.

Es importante destacar que este ejemplo es solo una muestra y puedes implementar cualquier funcionalidad para probar. Incluso un Endpoint de Minimal API podría ser suficiente para demostrar el funcionamiento del sistema. En este caso particular, el objetivo era demostrar la consulta a un servicio externo y cómo integrarlo en una aplicación Blazor.

Program.cs

Ahora que hemos configurado el servicio y la vista de ejemplo, el siguiente paso es ajustar el programa principal para configurar OpenTelemetry y todos los exportadores necesarios (de logs, métricas y traces).

Es importante destacar que en este punto no estamos limitados a utilizar exclusivamente Aspire. Dado que todo el sistema es agnóstico en cuanto a la implementación, podríamos optar por utilizar servicios compatibles con el Protocolo OpenTelemetry, como Application Insights o Datadog, según nuestras necesidades y preferencias.

El enfoque que seguiremos es utilizar Aspire en modo desarrollo y, en producción, cualquier opción que esté lista para producción. Esta flexibilidad es una de las características más destacadas, ya que nos permite adaptarnos a diferentes entornos sin estar ligados a una sola solución.

A continuación, presentamos cómo quedará configurado el archivo Program.cs:

var builder = WebApplication.CreateBuilder(args);

ConfigureOpenTelemetry(builder);

builder.Services.AddHttpClient<PokemonService>();
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

app.UseHttpsRedirection();

app.UseStaticFiles();
app.UseAntiforgery();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

El método ConfigureOpenTelemetry es el siguiente:

static void ConfigureOpenTelemetry(IHostApplicationBuilder builder)
{
    builder.Logging.AddOpenTelemetry(logging =>
    {
        logging.IncludeFormattedMessage = true;
        logging.IncludeScopes = true;
    });

    builder.Services.AddOpenTelemetry()
        .ConfigureResource(c => c.AddService("OpenTelemetryExample"))
        .WithMetrics(metrics =>
        {
            metrics.AddHttpClientInstrumentation()
                .AddRuntimeInstrumentation();
        })
        .WithTracing(tracing =>
        {
            if (builder.Environment.IsDevelopment())
            {
                // We want to view all traces in development
                tracing.SetSampler(new AlwaysOnSampler());
            }
            tracing.AddAspNetCoreInstrumentation();
            tracing.AddHttpClientInstrumentation();
            tracing.AddSource(PokemonService.ActivitySourceName);
        });

    // Use the OTLP exporter if the endpoint is configured.
    var useOtlpExporter = !string.IsNullOrWhiteSpace(builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]);
    if (useOtlpExporter)
    {
        builder.Services.Configure<OpenTelemetryLoggerOptions>(logging => logging.AddOtlpExporter());
        builder.Services.ConfigureOpenTelemetryMeterProvider(metrics => metrics.AddOtlpExporter());
        builder.Services.ConfigureOpenTelemetryTracerProvider(tracing => tracing.AddOtlpExporter());
    }
}

En este método, definimos cómo queremos gestionar los logs, traces y metrics utilizando las bibliotecas que hemos agregado previamente.

En primer lugar, configuramos los registros (logs) para incluir el mensaje formateado y los ámbitos. Esto nos permite capturar información detallada sobre el estado de la aplicación y los eventos ocurridos durante su ejecución.

Luego, configuramos el sistema de métricas para recopilar datos sobre el rendimiento de la aplicación, como el tiempo de respuesta de las solicitudes HTTP y el rendimiento del tiempo de ejecución. Esto nos ayuda a monitorear y diagnosticar el comportamiento de nuestra aplicación en tiempo real.

Para los traces, establecemos un muestreador que determina qué traces se deben capturar y enviar. En entornos de desarrollo, configuramos un muestreador que captura todas los traces para facilitar la depuración y el análisis. Además, agregamos instrumentación específica para HttpClient y para nuestra clase PokemonService, lo que nos permite rastrear las solicitudes HTTP y las operaciones realizadas en nuestro servicio.

Finalmente, configuramos los exportadores OTLP (OpenTelemetry Protocol) para enviar los datos recopilados a un destino específico. Si se ha configurado un endpoint OTLP, utilizamos los exportadores OTLP para enviar registros, métricas y traces. Esto nos proporciona la flexibilidad para dirigir los datos de OpenTelemetry a diferentes sistemas de análisis y monitoreo, como Prometheus, Zipkin o Loki, siguiendo el estándar OTLP.

En resumen, el método ConfigureOpenTelemetry establece la base para la instrumentación y observabilidad de nuestra aplicación, permitiéndonos recopilar datos valiosos sobre su rendimiento y comportamiento en tiempo real, y enviarlos a destinos de análisis externos según nuestras necesidades y preferencias.

Probando la Solución

Ya podemos correr la aplicación de Blazor y Aspire juntos, y empezaremos a ver los logs de la aplicación:

Nota 💡: Si revisas el código fuente, yo estoy utilizando docker-compose por medio de visual studio, es fácil de usar, pero por eso salen por default esos warnings y errores en el startup.

Utilicemos la aplicación para comenzar a generar métricas:

Veremos la consulta de los Pokemons, pero en Aspire nos vamos a los Traces y veremos en efecto el flujo de lo que acaba de suceder:

Ejemplo de las métricas:

Aquí otro ejemplo de como se vería con un endpoints de Minimal API:

Conclusión

En este artículo, hemos explorado cómo integrar OpenTelemetry en una aplicación ASP.NET Core utilizando Blazor, destacando el papel central de Aspire en nuestro sistema de observabilidad. Utilizando un enfoque práctico, demostramos cómo configurar OpenTelemetry, consumir una API externa y visualizar los datos recopilados en el potente Dashboard de Aspire. Esta plataforma nos ofrece una interfaz intuitiva para monitorear y analizar datos de telemetría en tiempo real, lo que nos permite identificar y resolver problemas de manera proactiva. Con la combinación de OpenTelemetry y Aspire, podemos mejorar significativamente la observabilidad de nuestras aplicaciones, optimizar su rendimiento y proporcionar una experiencia excepcional a los usuarios finales.

Forem: Isaac Ojeda

EF Core: tu query funciona, tus pruebas pasan… y estás leyendo 50,000 filas para devolver 3

Por qué casi nadie lo detecta a tiempo

Problema 1: el ToList() que mueve el filtro fuera de SQL

El origen: una excepción legítima

La “solución” que parece arreglar todo

La forma correcta

Problema 2: la proyección parece pequeña, pero la consulta deja de ser eficiente

El escenario

La forma correcta

Cómo inspeccionar lo que EF Core realmente está haciendo

Opción 1: logs en desarrollo

Opción 2: ToQueryString()

Un detalle extra en consultas de lectura

Sobre asistentes de código y queries “que funcionan”

Resumen

¿Qué sigue?

Primeros pasos con Microsoft Agent Framework: construyendo un chatbot de soporte con C#

Introducción

Desarrollo

¿Qué es Microsoft Agent Framework?

Los 5 conceptos clave

El ejemplo: SupportBot

Instalación

La Tool: DocumentationTool

El Agente: SupportAgentFactory

Manejo de Sesiones: InMemorySessionStore

Los Endpoints: Program.cs

El agente en acción

¿Cuándo agregarías Workflows aquí?

Conclusión

Referencias

Sistema de Control de Jobs en Tiempo Real con Channels y Background Services en .NET

Introducción

¿Qué son los Channels?

Arquitectura del Proyecto

Paso 1: Definir el Modelo de Comunicación

Paso 2: Crear el Background Service (Consumidor)

Paso 3: Configurar el Channel y el Servicio

Paso 4: Crear los Endpoints (Productores)

¿Por qué este patrón?

Sin Channels:

Con Channels:

Casos de Uso Reales con Channels

1. Cola de Emails/Notificaciones

2. Procesamiento de Imágenes

3. Logs Centralizados

4. Rate Limiting / Throttling

5. Event Sourcing Interno

6. Pipeline de Datos (ejemplo oficial de Microsoft)

¿Por qué usar Channels?

Impacto en tu arquitectura

Próximos Pasos

1. Implementar Múltiples Consumidores

2. Integrar Observabilidad

3. Implementar Persistencia

4. Agregar Pipeline de Procesamiento

5. Implementar Rate Limiting Avanzado

6. Crear Dashboard de Monitoreo

7. Añadir Resiliencia

8. Implementar Health Checks

9. Migrar a Arquitectura Distribuida

Recursos para Continuar Aprendiendo

[Parte 4] Construyendo un Agente Conversacional con el Agent Framework de Semantic Kernel

🧠 Crea tu propio agente conversacional con Semantic Kernel

🧠 ¿Qué es el Agent Framework en Semantic Kernel?

🎯 Caso de uso: un asistente de facturación

🧬 ¿Por qué usar agentes en lugar de comandos o controladores tradicionales?

⚙️ Requisitos previos y setup del entorno

📦 Paquetes necesarios

🧪 Configurando el Kernel

🧱 Servicios base y modelos de dominio

🧩 Definir tus funciones (skills/plugins)

🧠 ¿Qué es un plugin?

🧾 Ejemplo 1: Verificar el estado de una factura

✍️ Ejemplo 2: Crear una prefactura

🧠 ¿Por qué usar [KernelFunction]?

🤖 Crear un agente y asignarle objetivos

🧠 ¿Qué es un ChatCompletionAgent?

🏗️ Registrando el agente con DI

Problema 1: el `ToList()` que mueve el filtro fuera de SQL

Opción 2: `ToQueryString()`

🧠 ¿Por qué usar `[KernelFunction]`?

🧠 ¿Qué es un `ChatCompletionAgent`?

Creando `DependencyConfig.cs` para gestionar las dependencias

Definición del modelo `BlogPost`

Probando el endpoint con `api.http`

Implementación del Endpoint `SearchBlogPost`