JSolutionss.ORM.SqlServer 1.0.9

JSolutionss.ORM.SqlServer

JSolutionss.ORM.SqlServer es un ORM de alto rendimiento para .NET 8 y SQL Server. Diseñado para arquitecturas empresariales, combina la velocidad de Dapper para mapeo de objetos y la eficiencia de SqlBulkCopy con streaming para operaciones masivas.

Implementa un patrón de segregación de responsabilidades basado en roles de base de datos (Query, Transaction, Log), optimizando el manejo de sockets y el pool de conexiones.

🚀 Características Principales

• Alto Rendimiento: Mapeo rápido con Dapper y caché de consultas generadas.
• Bulk Insert Streaming: Inserción masiva de IEnumerable<T> sin cargar DataTable en memoria.
• Gestión Inteligente de Conexiones: Reuso eficiente del pool y control de sockets (await using).
• Roles de Base de Datos: Soporte nativo para separar lecturas (Replica), escrituras (Master) y logs.
• Logger con Failover: Guarda logs en BD (jss.AppLog) y hace fallback a archivo de texto automáticamente si la BD falla.
• Configuración Aislada: Utiliza su propio archivo de configuración JSON para no contaminar el appsettings.json.

📦 Instalación

Instala el paquete desde tu feed NuGet:

dotnet add package JSolutionss.ORM.SqlServer

⚙️ Configuración

Registra el servicio en el contenedor de .NET. El método buscará automáticamente el archivo jsolutionss.ormsettings.json.

var builder = WebApplication.CreateBuilder(args);

// ... otros servicios ...

// Registra el ORM
builder.Services.AddJSolutionssORM();

// Opcional: Si deseas usar un nombre de archivo diferente (ej. por ambiente)
// builder.Services.AddJSolutionssORM("jsolutionss.production.json");

var app = builder.Build();

💻 Definición de Modelos

Utiliza los atributos incluidos en el namespace Mapping para vincular tus clases con las tablas SQL.

using JSolutionss.ORM.SqlServer.Mapping;

[Table("dbo.Productos")] // Nombre real de la tabla en SQL
public class Producto
{
    [Key] // Indica la Llave Primaria (Identity) para Updates automáticos
    public int IdProducto { get; set; }

    public string Nombre { get; set; }
    public string CodigoBarras { get; set; }
    public decimal Precio { get; set; }
    public bool Activo { get; set; }
}

Guía de Uso

El ORM expone la interfaz principal IServicioOperacionesDB, que agrupa las capacidades de lectura y escritura.

1. Consultas (Query DB) Utiliza la conexión definida en stringConnectionQueryDB. Ideal para llenar Grids, Combos y Reportes.

public class ProductoService
{
    private readonly IServicioOperacionesDB _db;

    public ProductoService(IServicioOperacionesDB db)
    {
        _db = db;
    }

    public async Task<IEnumerable<Producto>> BuscarPorNombre(string nombre)
    {
        // Ejecuta Query directo o Stored Procedure.
        // Los parámetros anónimos se convierten automáticamente a @p_NombrePropiedad
        
        string sql = "SELECT * FROM dbo.Productos WHERE Nombre LIKE @p_Nombre AND Activo = 1";
        
        return await _db.ExecuteCollection<Producto>(
            spName: sql, 
            param: new { Nombre = $"%{nombre}%" }, 
            commandType: CommandType.Text
        );
    }
}

2. Transacciones y CRUD (Transact DB)

Utiliza la conexión definida en stringConnectionTransactDB.

public async Task<int> InsertarProducto(Producto nuevoProducto)
{
    // Inserta el producto y retorna el Id generado
    return await _db.InsertAsync(nuevoProducto);
}

3. Inserción Masiva (High Performance) Utiliza SqlBulkCopy con un IDataReader personalizado sobre tu lista, evitando cargar un DataTable en memoria.

public async Task ImportarExcel(List<Producto> listaMasiva)
{
    // Inserta miles de registros en segundos directamente a la tabla [Table]
    await _db.InsertListBulkCopy(listaMasiva);
}

4. Logging y Auditoría

• Inyecta ILogServiceDB para registrar eventos.
• Automático: Si la tabla jss.AppLog no existe, el servicio la crea la primera vez.
• Resiliente: Si la base de datos de logs cae, guarda el error en el archivo de texto configurado en jsolutionss.json.

public class LoggerService
{
    private readonly ILogServiceDB _logger;

    public LoggerService(ILogServiceDB logger)
    {
        _logger = logger;
    }

    public async Task RegistrarError(string mensaje, string stackTrace)
    {
        // Se requiere un modelo que coincida con la tabla de logs
        var log = new AppLogModel 
        { 
            Message = mensaje, 
            Level = "ERROR", 
            Exception = stackTrace,
            User = "System"
        };
        
        await _logger.Insert(log);
    }
}

📄 Convenciones Importantes

• Parámetros SQL: El ORM antepone automáticamente el prefijo @p_ a los nombres de las propiedades de los objetos de parámetros. C#: new { IdEmpresa = 1 } SQL Esperado en SP o Query: @p_IdEmpresa
• Mapeo: Es obligatorio usar el atributo [Table] en la clase.
• Identidad: Es obligatorio usar el atributo [Key] en la propiedad de identidad para que los métodos Update y Insert funcionen correctamente.