CoreDatabase 2025.6.11

CoreDatabase

Biblioteca de acceso a datos para SQL Server que proporciona una capa de abstracción robusta y fácil de usar sobre ADO.NET.

Características

• Conexión segura a SQL Server
• Manejo de transacciones
• Ejecución de consultas y procedimientos almacenados
• Soporte para parámetros SQL
• Manejo de errores robusto
• Soporte para operaciones asíncronas
• Manejo de conexiones temporales
• Integración con inyección de dependencias
• Binding automático de objetos
• Soporte para operaciones bulk

Instalación

El componente se puede instalar como un paquete NuGet:

dotnet add package DeveloperKit.CoreDatabase

Requisitos

• SQL Server 2012 o superior
• .NET Framework 4.8 o superior
• Visual Studio 2019 o superior
• SQL Server Native Client

Configuración

Configuración Inicial

// Configurar la conexión
services.AddScoped<IMSSqlRepository, MSSqlRepository>(provider =>
{
    var connectionString = Configuration.GetConnectionString("SqlServerConnection");
    return new MSSqlRepository(connectionString);
});

Uso

Ejemplos de Uso

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

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

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

// Ejecutar procedimiento almacenado
public async Task ExecuteStoredProcedure()
{
    var spName = "PKG_CUSTOMERS.GET_CUSTOMER";
    
    await _sqlRepository.ExecuteStoredProcedureAsync(spName, parameters =>
    {
        parameters.Add("p_customer_id", SqlDbType.Int, 123);
        parameters.Add("p_result", SqlDbType.Int, ParameterDirection.Output);
    });
}

// Binding automático de objetos
public class Customer
{
    public int CustomerId { get; set; }
    public string Name { get; set; }
    public DateTime CreatedDate { get; set; }
}

public async Task InsertCustomer(Customer customer)
{
    var query = "INSERT INTO CUSTOMERS (CustomerId, Name, CreatedDate) VALUES (@CustomerId, @Name, @CreatedDate)";
    
    await _sqlRepository.ExecuteQueryAsync(query, parameters =>
    {
        parameters.BindFrom(customer);
    });
}

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 Bulk

public async Task BulkInsert(List<Customer> customers)
{
    await _sqlRepository.BulkInsertAsync("CUSTOMERS", customers, mapping =>
    {
        mapping.Column("CustomerId", x => x.CustomerId);
        mapping.Column("Name", x => x.Name);
        mapping.Column("CreatedDate", x => x.CreatedDate);
    });
}

Mejores Prácticas

1. Siempre usar parámetros en las consultas para evitar inyección SQL
2. Manejar transacciones para operaciones que afectan múltiples tablas
3. Usar conexiones asíncronas para operaciones largas
4. Implementar manejo de errores robusto
5. Usar procedimientos almacenados cuando sea posible
6. Implementar timeout adecuado para consultas
7. Usar pool de conexiones para mejor rendimiento
8. Validar datos antes de insertar/actualizar
9. Usar binding automático para objetos complejos
10. Implementar logging de consultas

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> parameter = null)
  Ejecuta una consulta SQL y devuelve un DataTable con los resultados.

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

• T GetItemFromQuery<T>(string query, Func<IDataReader, T> expression, Action<IDataParameterCollection> parameter = 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> parameter = null)
  Igual que el anterior, pero con procedimiento almacenado.

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

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

• ICollection<T> GetItemsFromStoredProcedure<T>(string procedimientoAlmacenado, Func<IDataReader, T> expression, Action<IDataParameterCollection> parameter = 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> parameter = 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> parameter = 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> parameter = 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> parameter = 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> parameter = 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> parameter = null)
  Ejecuta una consulta asíncrona y devuelve un DataTable con los resultados.

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

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

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

• Task<ICollection<T>> GetItemsFromQueryAsync<T>(string query, Func<IDataReader, T> expression, Action<IDataParameterCollection> parameter = 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> parameter = null)
  Igual que el anterior, pero con mapeo personalizado.

Comandos asíncronos

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

• Task ExecuteNonQueryAsync(string command, Action<IDataParameterCollection> parameter = 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);
}