CoreDatabase 2025.7.24

CoreDatabase

Biblioteca de acceso a datos para SQL Server que proporciona una capa de abstracción robusta, segura y fácil de usar sobre ADO.NET, con soporte completo para operaciones síncronas y asíncronas.

Características

• Conexión segura a SQL Server con soporte para autenticación integrada y SQL
• Manejo de transacciones (commit/rollback)
• Ejecución de consultas SQL y procedimientos almacenados
• Soporte completo para parámetros SQL con tipado fuerte
• Manejo de errores robusto con mensajes descriptivos
• Operaciones asíncronas para mejor rendimiento
• Manejo automático de conexiones (abre/cierra según sea necesario)
• Integración con inyección de dependencias
• Binding automático de objetos a parámetros SQL
• Operaciones bulk para inserción masiva de datos
• Soporte para múltiples formatos de retorno (DataTable, List<T>, Diccionarios, objetos fuertemente tipados)
• Creación y eliminación dinámica de tablas
• Soporte para múltiples conjuntos de resultados

Instalación

El componente se puede instalar como un paquete NuGet:

dotnet add package DeveloperKit.CoreDatabase

Requisitos

• SQL Server 2012 o superior
• .NET 6.0 o superior (compatible con .NET Standard 2.1+)
• .NET Framework 4.8 (soporte heredado)
• Visual Studio 2022 o superior (recomendado)
• SQL Server Native Client o Microsoft.Data.SqlClient

Configuración

Configuración Inicial

// Configuración básica
services.AddScoped<IMSSqlRepository, MSSqlRepository>(provider =>
{
    var connectionString = Configuration.GetConnectionString("SqlServerConnection");
    return new MSSqlRepository(connectionString);
});

// Configuración con nombre de aplicación personalizado
services.AddScoped<IMSSqlRepository>(provider =>
{
    var connectionString = Configuration.GetConnectionString("SqlServerConnection");
    return new MSSqlRepository(connectionString, () => "MiAplicacion");
});

// Configuración con credenciales explícitas
services.AddScoped<IMSSqlRepository>(provider =>
{
    var config = provider.GetRequiredService<IConfiguration>();
    return new MSSqlRepository(
        serverName: config["Database:Server"],
        dataBaseName: config["Database:Name"],
        userName: config["Database:User"],
        password: config["Database:Password"]
    );
});

Uso

Ejemplos de Uso

Consultas Básicas

// Inyección del repositorio
private readonly IMSSqlRepository _sqlRepository;

public CustomerService(IMSSqlRepository sqlRepository)
{
    _sqlRepository = sqlRepository;
}

// Ejecutar consulta y obtener DataTable
public async Task<DataTable> GetActiveCustomersAsync()
{
    var query = "SELECT * FROM CUSTOMERS WHERE ACTIVE = @active";
    
    return await _sqlRepository.ExecuteQueryAsTableAsync(query, parameters =>
    {
        parameters.Add("active", SqlDbType.Bit, true);
    });
}

// Ejecutar consulta y mapear a objetos fuertemente tipados
public async Task<List<Customer>> GetCustomersAsync()
{
    var query = "SELECT CustomerId, Name, Email, CreatedDate FROM CUSTOMERS";
    
    return await _sqlRepository.ExecuteQueryAsListAsync(query, reader => new Customer
    {
        CustomerId = reader.GetInt32(0),
        Name = reader.GetString(1),
        Email = reader.IsDBNull(2) ? null : reader.GetString(2),
        CreatedDate = reader.GetDateTime(3)
    });
}

Procedimientos Almacenados

// Ejecutar procedimiento almacenado con parámetros
public async Task<Customer> GetCustomerByIdAsync(int customerId)
{
    var spName = "usp_GetCustomerById";
    
    return await _sqlRepository.ExecuteProcedureAsSingleAsync(spName, reader => new Customer
    {
        CustomerId = reader.GetInt32("CustomerId"),
        Name = reader.GetString("Name"),
        Email = reader.IsDBNull("Email") ? null : reader.GetString("Email"),
        CreatedDate = reader.GetDateTime("CreatedDate")
    }, parameters =>
    {
        parameters.Add("@CustomerId", SqlDbType.Int, customerId);
    });
}

// Procedimiento con múltiples conjuntos de resultados
public async Task<(List<Customer> Customers, List<Order> Orders)> GetCustomerWithOrdersAsync(int customerId)
{
    var spName = "usp_GetCustomerWithOrders";
    
    var result = await _sqlRepository.ExecuteQueryAsListDictionaryAsync(
        "EXEC " + spName + " @CustomerId",
        parameters =>
        {
            parameters.Add("@CustomerId", SqlDbType.Int, customerId);
        });

    var customers = result[0].Select(dict => new Customer
    {
        CustomerId = (int)dict["CustomerId"],
        Name = (string)dict["Name"]
    }).ToList();

    var orders = result[1].Select(dict => new Order
    {
        OrderId = (int)dict["OrderId"],
        OrderDate = (DateTime)dict["OrderDate"],
        TotalAmount = (decimal)dict["TotalAmount"]
    }).ToList();

    return (customers, orders);
}

Operaciones CRUD

// Insertar un solo registro
public async Task<int> InsertCustomerAsync(Customer customer)
{
    var query = @"
        INSERT INTO Customers (Name, Email, CreatedDate)
        OUTPUT INSERTED.CustomerId
        VALUES (@Name, @Email, @CreatedDate)";
    
    return await _sqlRepository.ExecuteQueryAsSingleAsync<int>(query, reader => reader.GetInt32(0),
        parameters =>
        {
            parameters.Add("@Name", SqlDbType.NVarChar, 100, customer.Name);
            parameters.Add("@Email", SqlDbType.NVarChar, 100, (object)customer.Email ?? DBNull.Value);
            parameters.Add("@CreatedDate", SqlDbType.DateTime2, DateTime.UtcNow);
        });
}

// Insertar múltiples registros (bulk insert)
public async Task BulkInsertCustomersAsync(IEnumerable<Customer> customers)
{
    await _sqlRepository.ExecuteBulkCopyAsync("Customers", customers, mapping =>
    {
        mapping.Column("Name", c => c.Name);
        mapping.Column("Email", c => c.Email);
        mapping.Column("CreatedDate", c => c.CreatedDate);
    });
}

// Actualizar un registro
public async Task<bool> UpdateCustomerAsync(Customer customer)
{
    var query = @"
        UPDATE Customers 
        SET Name = @Name, 
            Email = @Email,
            ModifiedDate = @ModifiedDate
        WHERE CustomerId = @CustomerId";
    
    int rowsAffected = await _sqlRepository.ExecuteNonQueryAsync(query, parameters =>
    {
        parameters.Add("@CustomerId", SqlDbType.Int, customer.CustomerId);
        parameters.Add("@Name", SqlDbType.NVarChar, 100, customer.Name);
        parameters.Add("@Email", SqlDbType.NVarChar, 100, (object)customer.Email ?? DBNull.Value);
        parameters.Add("@ModifiedDate", SqlDbType.DateTime2, DateTime.UtcNow);
    });
    
    return rowsAffected > 0;
}

Operaciones con Transacciones

public async Task<bool> ProcessOrderAsync(Order order, List<OrderItem> items)
{
    try
    {
        _sqlRepository.BeginTransaction();
        
        // Insertar orden
        var orderId = await _sqlRepository.ExecuteQueryAsSingleAsync<int>(
            "INSERT INTO Orders (...) OUTPUT INSERTED.OrderId VALUES (...)",
            reader => reader.GetInt32(0));
        
        // Insertar ítems
        foreach (var item in items)
        {
            item.OrderId = orderId;
            await _sqlRepository.ExecuteInsertAsync("OrderItems", item);
        }
        
        // Actualizar inventario
        foreach (var item in items)
        {
            await _sqlRepository.ExecuteNonQueryAsync(
                "UPDATE Products SET Stock = Stock - @Quantity WHERE ProductId = @ProductId",
                parameters =>
                {
                    parameters.Add("@ProductId", SqlDbType.Int, item.ProductId);
                    parameters.Add("@Quantity", SqlDbType.Int, item.Quantity);
                });
        }
        
        _sqlRepository.CommitTransaction();
        return true;
    }
    catch (Exception ex)
    {
        _sqlRepository.RollbackTransaction();
        _logger.LogError(ex, "Error al procesar la orden");
        return false;
    }
}

Manejo de Transacciones

public async Task ExecuteWithTransaction()
{
    try
    {
        // Iniciar transacción
        _sqlRepository.BeginTransaction();
        
        // Ejecutar operaciones
        await _sqlRepository.ExecuteQueryAsync("INSERT INTO CUSTOMERS (...) VALUES (...)"));
        await _sqlRepository.ExecuteQueryAsync("UPDATE CUSTOMERS SET (...) WHERE (...)"));
        
        // Confirmar transacción
        _sqlRepository.CommitTransaction();
    }
    catch (Exception ex)
    {
        // Revertir transacción en caso de error
        _sqlRepository.RollbackTransaction();
        throw;
    }
}

Manejo de Parámetros

// Parámetros básicos
parameters.Add("p_input", SqlDbType.Varchar, "valor");

// Parámetros con tamaño
parameters.Add("p_text", SqlDbType.NVarChar, 100, "valor largo");

// Parámetros numéricos
parameters.Add("p_decimal", SqlDbType.Decimal, 18, 2, 123.45);

// Parámetros de salida
parameters.Add("p_output", SqlDbType.Int, ParameterDirection.Output);

// Parámetros de entrada/salida
parameters.Add("p_inout", SqlDbType.Int, 1, ParameterDirection.InputOutput);

Operaciones Avanzadas

Inserción Masiva (Bulk Insert)

// Inserción masiva desde DataTable
public async Task BulkInsertCustomersAsync(DataTable customersData)
{
    await _sqlRepository.ExecuteBulkCopyToTableAsync(customersData, "Customers");
}

// Inserción masiva desde colección de objetos
public async Task BulkInsertCustomersAsync(IEnumerable<Customer> customers)
{
    await _sqlRepository.ExecuteBulkCopyAsync("Customers", customers, mapping =>
    {
        mapping.Column("CustomerId", c => c.CustomerId);
        mapping.Column("Name", c => c.Name);
        mapping.Column("Email", c => c.Email);
        mapping.Column("CreatedDate", c => c.CreatedDate);
    });
}

Creación Dinámica de Tablas

// Crear tabla desde DataTable
public void CreateTableFromData(DataTable sourceData, string destinationTableName)
{
    _sqlRepository.CreateTable(sourceData, destinationTableName);
}

// Crear tabla desde IDataReader
public void CreateTableFromReader(IDataReader reader, string destinationTableName)
{
    _sqlRepository.CreateTable(reader, destinationTableName);
}

// Eliminar tabla
public void DropCustomerTable()
{
    _sqlRepository.DropTable("Customers");
}

Manejo de Tipos de Datos

La biblioteca soporta todos los tipos de datos de SQL Server, incluyendo tipos especiales como:

• Tipos numéricos: INT, BIGINT, DECIMAL, FLOAT, etc.
• Tipos de texto: VARCHAR, NVARCHAR, CHAR, NCHAR, TEXT, NTEXT
• Tipos de fecha: DATETIME, DATETIME2, DATE, TIME, DATETIMEOFFSET
• Tipos binarios: VARBINARY, IMAGE
• Tipos especiales: UNIQUEIDENTIFIER, XML, JSON, GEOMETRY, GEOGRAPHY

Manejo de Errores

try
{
    // Código que interactúa con la base de datos
}
catch (SqlException sqlEx) when (sqlEx.Number == 2627) // Violación de restricción única
{
    throw new DuplicateEntryException("Ya existe un registro con la misma clave", sqlEx);
}
catch (SqlException sqlEx) when (sqlEx.Number == 547) // Violación de clave foránea
{
    throw new InvalidOperationException("No se puede eliminar el registro porque tiene registros relacionados", sqlEx);
}
catch (SqlException sqlEx) when (sqlEx.Number == 1205) // Deadlock
{
    // Reintentar la operación
    await Task.Delay(500);
    await ExecuteOperationWithRetry();
}
catch (Exception ex)
{
    _logger.LogError(ex, "Error al acceder a la base de datos");
    throw new DatabaseOperationException("Error al procesar la operación", ex);
}

Mejores Prácticas

1. Seguridad

   • Siempre usar parámetros en las consultas para evitar inyección SQL
   • No concatenar valores directamente en las consultas SQL
   • Usar los permisos mínimos necesarios para la conexión a la base de datos
   • Validar y limpiar todos los datos de entrada

2. Rendimiento

   • Usar operaciones asíncronas para operaciones de E/S
   • Implementar paginación para consultas que devuelven grandes conjuntos de datos
   • Usar operaciones bulk para inserciones/actualizaciones masivas
   • Mantener las transacciones lo más cortas posibles

3. Mantenibilidad

   • Usar procedimientos almacenados para lógica de negocio compleja
   • Implementar un patrón de repositorio para centralizar el acceso a datos
   • Usar DTOs para transferir datos entre capas
   • Documentar consultas complejas

4. Manejo de Errores

   • Implementar un manejo de errores consistente
   • Registrar errores con suficiente contexto para diagnóstico
   • Proporcionar mensajes de error amigables al usuario final
   • Manejar adecuadamente las transacciones fallidas

5. Patrones de Diseño

   • Usar el patrón Unit of Work para operaciones atómicas
   • Implementar el patrón Repository para abstraer el acceso a datos
   • Usar el patrón Specification para construir consultas complejas
   • Aplicar el principio de responsabilidad única

Manejo de Errores

try
{
    await _sqlRepository.ExecuteQueryAsync(query);
}
catch (SqlException ex)
{
    // Manejo específico de errores de SQL
    if (ex.Number == 2627) // Violación de restricción única
    {
        throw new DuplicateEntryException("Ya existe un registro con esta clave");
    }
    throw;
}

Optimización de Consultas

1. Usar parámetros en lugar de concatenación de strings
2. Implementar timeout razonable
3. Usar índices apropiados
4. Evitar SELECT * cuando no es necesario
5. Usar procedimientos almacenados para consultas complejas
6. Implementar paginación para listados grandes
7. Usar transacciones solo cuando sea necesario

Soporte

Para reportar errores o solicitar características, por favor abre un issue en el repositorio de GitHub.

Licencia

Este proyecto está bajo licencia MIT. Consulta el archivo LICENSE para más detalles.

• void CommitTransaction()
  Confirma la transacción activa y cierra la conexión.

• void RollbackTransaction()
  Revierte la transacción activa y cierra la conexión.

Consultas y ejecución

• DataTable GetTableFromQuery(string query, Action<IDataParameterCollection> parametros = null)
  Ejecuta una consulta SQL y devuelve un DataTable con los resultados.

• DataTable GetTableFromStoredProcedure(string procedimientoAlmacenado, Action<IDataParameterCollection> parametros = null)
  Ejecuta un procedimiento almacenado y devuelve un DataTable.

• T GetItemFromQuery<T>(string query, Func<IDataReader, T> expression, Action<IDataParameterCollection> parametros = null)
  Ejecuta una consulta y transforma la primera fila a un objeto del tipo T.

• T GetItemFromStoredProcedure<T>(string procedimientoAlmacenado, Func<IDataReader, T> expression, Action<IDataParameterCollection> parametros = null)
  Igual que el anterior, pero con procedimiento almacenado.

• ICollection<Dictionary<string, object>> GetDictionaryFromQuery(string query, Action<IDataParameterCollection> parametros = null)
  Obtiene resultados de consulta como una colección de diccionarios con nombre/valor.

• ICollection<Dictionary<string, object>> GetDictionaryFromStoredProcedure(string procedimientoAlmacenado, Action<IDataParameterCollection> parametros = null)
  Igual que el anterior, pero para procedimientos almacenados.

• ICollection<T> GetItemsFromStoredProcedure<T>(string procedimientoAlmacenado, Func<IDataReader, T> expression, Action<IDataParameterCollection> parametros = null)
  Obtiene una colección de objetos tipo T a partir de un procedimiento almacenado.

• ICollection<T> GetItemsFromQuery<T>(string query, Func<IDataReader, T> expression, Action<IDataParameterCollection> parametros = null)
  Obtiene una colección de objetos tipo T a partir de una consulta SQL.

Ejecución de comandos

• void ExecuteNonQuery(string command, Action<IDataParameterCollection> parametros = null)
  Ejecuta comandos SQL que no retornan datos (INSERT, UPDATE, DELETE, etc.).

• void ExecuteInsert<T>(string tableName, T entity) where T : class, new()
  Inserta un único objeto en la tabla especificada usando reflexión.

• void ExecuteInsert<T>(string tableName, ICollection<T> collection) where T : class, new()
  Inserta una colección de objetos en la tabla especificada.

• void ExecuteStoredProcedureCommand(string procedimientoAlmacenado, Action<IDataParameterCollection> parametros = null)
  Ejecuta un procedimiento almacenado que no devuelve resultados.

Operaciones Bulk Copy

• void ExecuteBulkCopyToTable(DataTable source, string destinationTable)
  Borra la tabla destino, la crea según la estructura de la tabla fuente y realiza la inserción masiva.

• void ExecuteBulkCopy(DataTable source, string destinationTable)
  Inserción masiva desde un DataTable.

• void ExecuteBulkCopy(IDataReader source, string destinationTable)
  Inserción masiva desde un IDataReader.

Otros métodos útiles

• DateTime GetCurrentDateTime()
  Obtiene la fecha y hora actual del servidor SQL.

• Métodos para crear parámetros SQL para consultas y procedimientos almacenados (AddParameter).

• Métodos para configurar la conexión (SetDatabaseLogon).

Métodos Asíncronos de IMSSqlRepository

La interfaz también define métodos asíncronos para mejorar el rendimiento y escalabilidad de las operaciones de base de datos.

Métodos asíncronos principales

• Task<T> GetItemFromQueryAsync<T>(string query, Func<IDataReader, T> expression, Action<IDataParameterCollection> parametros = null)
  Ejecuta una consulta SQL asíncrona y transforma la primera fila en un objeto T.

• Task<T> GetItemFromStoredProcedureAsync<T>(string procedimientoAlmacenado) where T : new()
  Ejecuta un procedimiento almacenado de forma asíncrona y devuelve un objeto T por defecto.

• Task<T> GetItemFromStoredProcedureAsync<T>(string procedimientoAlmacenado, Func<IDataReader, T> expression, Action<IDataParameterCollection> parametros = null)
  Ejecuta un procedimiento almacenado de forma asíncrona y mapea la primera fila a un objeto T.

• Task<DataTable> GetTableFromQueryAsync(string query, Action<IDataParameterCollection> parametros = null)
  Ejecuta una consulta asíncrona y devuelve un DataTable con los resultados.

• Task<DataTable> GetTableFromStoredProcedureAsync(string procedimientoAlmacenado, Action<IDataParameterCollection> parametros = null)
  Ejecuta un procedimiento almacenado de forma asíncrona y devuelve un DataTable.

• Task<ICollection<Dictionary<string, object>>> GetDictionaryFromQueryAsync(string query, Action<IDataParameterCollection> parametros = null)
  Ejecuta una consulta asíncrona y devuelve una colección de diccionarios.

• Task<ICollection<Dictionary<string, object>>> GetDictionaryFromStoredProcedureAsync(string procedimientoAlmacenado, Action<IDataParameterCollection> parametros = null)
  Igual que el anterior, pero para procedimientos almacenados.

• Task<ICollection<T>> GetItemsFromQueryAsync<T>(string query, Func<IDataReader, T> expression, Action<IDataParameterCollection> parametros = null)
  Obtiene una colección de objetos T de una consulta asíncrona.

• Task<ICollection<T>> GetItemsFromStoredProcedureAsync<T>(string storedProcedure) where T : new()
  Obtiene una colección de objetos T de un procedimiento almacenado asíncrono.

• Task<ICollection<T>> GetItemsFromStoredProcedureAsync<T>(string storedProcedure, Func<IDataReader, T> expression, Action<IDataParameterCollection> parametros = null)
  Igual que el anterior, pero con mapeo personalizado.

Comandos asíncronos

• Task<int> ExecuteStoredProcedureCommandAsync(string storedProcedure, Action<IDataParameterCollection> parametros = null)
  Ejecuta un procedimiento almacenado asíncrono que devuelve el número de filas afectadas.

• Task ExecuteNonQueryAsync(string command, Action<IDataParameterCollection> parametros = null)
  Ejecuta un comando SQL que no retorna datos de forma asíncrona.

• Task ExecuteBulkCopyToTableAsync(DataTable sourceTable, string destinationTable)
  Realiza una inserción masiva asíncrona creando la tabla destino.

• Task ExecuteBulkCopyAsync(DataTable source, string destinationTable)
  Inserción masiva asíncrona desde un DataTable.

• Task ExecuteBulkCopyAsync(IDataReader source, string destinationTable)
  Inserción masiva asíncrona desde un IDataReader.

• Task ExecuteInsertAsync<T>(string tableName, T entity)
  Inserta un objeto de forma asíncrona en la tabla especificada.

• Task ExecuteInsertAsync<T>(string tableName, ICollection<T> collection)
  Inserta una colección de objetos de forma asíncrona.

• Task<DateTime> GetCurrentDateTimeAsync()
  Obtiene la fecha y hora actual del servidor SQL de forma asíncrona.

Métodos para manejo de tablas en IMSSqlRepository

Además de los métodos para manipulación de datos, la interfaz incluye operaciones para gestionar tablas directamente:

• void DropTable(string tableName)
  Elimina la tabla especificada de la base de datos.

• void CreateTable(DataTable sourceTable, string destinationTable)
  Crea una tabla en la base de datos a partir de la estructura de un DataTable.

• void CreateTable(IDataReader reader, string destinationTable)
  Crea una tabla en la base de datos basándose en la estructura del IDataReader.

Interfaz IServiceProviderKeyed

Esta interfaz proporciona un mecanismo para obtener servicios basados en una clave específica:

public interface IServiceProviderKeyed
{
    TService GetKeyedService<TService, TKeyed>(TKeyed key);
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMicrosoftSQL(provider =>
    {
        // Aquí configuras la instancia concreta de IMSSqlRepository
        IMSSqlRepository repo = new MSSqlRepository();
        repo.SetDatabaseLogon("Server=myServer;Database=myDB;User Id=myUser;Password=myPassword;");
        return repo;
    }, ServiceLifetime.Scoped);
}