Quantum.Data.SqlBuilder 1.0.2

Quantum.Data.SqlBuilder

Quantum.Data.SqlBuilder es una librería .NET ligera y potente para construir scripts SQL de forma fluida, segura y dinámica. Su objetivo es simplificar la creación de consultas complejas sin la complejidad de un ORM completo, previniendo ataques de inyección SQL mediante el uso exclusivo de consultas parametrizadas.

✨ Características Principales (v1.0.0)

• API Fluida e Intuitiva: Encadena métodos para construir consultas SELECT, INSERT, UPDATE, y DELETE.
• Seguridad por Diseño: Genera siempre consultas parametrizadas para evitar la inyección SQL.
• Mapeo de DTOs: Utiliza atributos ([ColumnName], [Ignore]) para mapear tus clases a la base de datos de forma sencilla.
• Soporte Avanzado de Consultas:
  • Cláusulas JOIN (INNER, LEFT, RIGHT).
  • Condiciones complejas con WHERE IN, OR y grupos con paréntesis (AndGroup/OrGroup).
  • Helpers para cláusulas dinámicas (WhereIf).
  • Agregaciones con GROUP BY y HAVING.
• Paginación Simplificada: Método .Page() para paginación automática con OFFSET/FETCH.
• Soporte Completo para Stored Procedures:
  • Parámetros nombrados, posicionales y de OUTPUT.
  • Parámetros con Valor de Tabla (TVPs) para inserciones masivas eficientes.
• Scripts Transaccionales: Genera scripts T-SQL completos y seguros con la clase UnitOfWork, capaz de manejar la captura de IDs y su reutilización en operaciones posteriores.

🚀 Instalación

Instala el paquete a través de la consola del Administrador de Paquetes NuGet:

Install-Package Quantum.Data.SqlBuilder -Version 1.0.0

O mediante la CLI de .NET:

dotnet add package Quantum.Data.SqlBuilder --version 1.0.0

💡 Ejemplos de Uso

Consulta SELECT Avanzada

var builder = new SqlBuilder();
var query = builder
    .Select("u.Nombre, o.Total, o.Fecha")
    .From("Usuarios u")
    .InnerJoin("Ordenes o", "u.IdUsuario = o.IdUsuario")
    .Where("u.Activo", "=", 1)
    .AndGroup(g => g // Agrega un grupo: AND ( ... )
        .Where("o.Total", ">", 50)
        .OrWhere("o.Estado", "=", "Urgente")
    )
    .OrderBy("o.Fecha", descending: true)
    .Page(1, 10) // Página 1, 10 resultados
    .Build();

// `query` contiene el CommandText y los Parameters listos para ejecutar.
// SELECT u.Nombre, o.Total, o.Fecha FROM Usuarios u INNER JOIN Ordenes o ON u.IdUsuario = o.IdUsuario WHERE u.Activo = @p0 AND (o.Total > @p1 OR o.Estado = @p2) ORDER BY o.Fecha DESC OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY

INSERT a partir de un DTO con Atributos

// Define tu DTO
public class ProductoDto
{
    [ColumnName("NombreProducto")]
    public string Nombre { get; set; }
    
    public decimal Precio { get; set; }

    [Ignore] // Esta propiedad será ignorada
    public int CantidadEnCarrito { get; set; }
}

var nuevoProducto = new ProductoDto 
{ 
    Nombre = "Teclado Quantum Pro", 
    Precio = 89.99m, 
    CantidadEnCarrito = 1 
};

var builder = new SqlBuilder();
var command = builder
    .InsertInto("Productos")
    .Values(nuevoProducto)
    .Build();

// SQL Generado:
// INSERT INTO Productos (NombreProducto, Precio) VALUES (@NombreProducto, @Precio)

Stored Procedure con Parámetros de Tabla (TVP)

Ideal para inserciones masivas.

// 1. DTO que coincide con el User-Defined Table Type de SQL Server
public class DetalleDto { public int ProductoId { get; set; } public int Cantidad { get; set; } }

// 2. Lista de detalles a insertar
var detalles = new List<DetalleDto>
{
    new() { ProductoId = 101, Cantidad = 2 },
    new() { ProductoId = 205, Cantidad = 1 }
};

var builder = new SqlBuilder();
var command = builder
    .StoredProcedure("sp_InsertarDetallesFactura")
    .WithParameter("@FacturaId", 12345)
    .WithTableValuedParameter("@Detalles", detalles, "dbo.TipoDetalleFactura") // <-- Magia aquí
    .Build();

// `command` está listo para ser ejecutado, enviando la tabla de detalles en una sola llamada.

Script Transaccional con UnitOfWork

Genera un script T-SQL para crear una factura y sus detalles, capturando el ID del encabezado y reutilizándolo.

var uow = new UnitOfWork();

// 1. Define una variable para el ID de la nueva factura
var facturaIdVar = new ScriptVariable("@NuevaFacturaID", "INT");

// 2. Agrega el comando para insertar el encabezado y captura el nuevo ID
uow.AddAndCaptureIdentity(facturaIdVar, builder =>
    builder.InsertInto("Facturas")
           .Values(new { ClienteId = 42, Fecha = DateTime.UtcNow })
           .Build());

// 3. Itera sobre los detalles y usa la variable del ID de la factura
foreach (var detalle in detalles) // 'detalles' es una lista de objetos
{
    uow.Add(builder =>
        builder.InsertInto("DetallesFactura")
               .Values(detalle)
               .WithParameter("@FacturaID", facturaIdVar) // Reutiliza el ID capturado
               .Build());
}

// 4. Genera el script final
string transactionalScript = uow.BuildTransactionalScript();

/*
El script generado contendrá la estructura completa BEGIN/COMMIT/ROLLBACK TRANSACTION,
declarando la variable @NuevaFacturaID, ejecutando el primer INSERT, capturando
el ID con SCOPE_IDENTITY(), y luego usándolo en los siguientes INSERTs.
*/

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT. Siéntete libre de usarlo en tus proyectos personales y comerciales. Ver el archivo LICENSE para más detalles.