Adfines.Net.Ganesha - Gestor Multi-Base de Datos para .NET

📑 MENÚ DE NAVEGACIÓN

• 📋 Descripción
• 🚀 Características Principales
• 📦 Instalación
• 🔐 Encriptación
• 🗄️ Bases de Datos Soportadas
• 🔧 Configuración
• 🛠️ Inicialización
• 💻 Operaciones CRUD
• 📊 Tablas de Retornos
• 🔍 Metadatos
• 🐛 Manejo de Errores
• 🔍 Ejemplos Completos
• ❓ Preguntas Frecuentes
• 📝 Notas Importantes

📋 Descripción

Adfines.Net.Ganesha es un paquete NuGet diseñado para simplificar y optimizar la gestión de múltiples tipos de bases de datos en aplicaciones .NET 6+. Soporta MySQL, SQL Server, PostgreSQL y Oracle con una API unificada.

🚀 Características Principales

• ✅ Soporte multi-base de datos: MySQL, SQL Server, PostgreSQL, Oracle
• 🔒 Cifrado automático de credenciales (AfCrypt)
• 📊 API unificada para todas las bases de datos
• 🐛 Sistema de logging automático en base de datos
• ⚡ Configuración flexible con múltiples formas de inicialización
• 🔧 Manejo de parámetros para consultas parametrizadas
• 📝 Tipos de retorno múltiples (Dictionary, JObject, JArray)
• 🎯 Operaciones CRUD completas y optimizadas
• 🔍 Metadatos de bases de datos (esquemas, tablas, columnas)

📦 Instalación

dotnet add package Adfines.Net.Ganesha

🔐 Encriptación de Contraseñas

// Para encriptar contraseñas (cuando AfCrypt = true)
string passwordEncriptado = Adfines.Net.Ganesha.Xtra.Password.E("Hola mundo");
Console.WriteLine(passwordEncriptado);
// El valor retornado es el que se debe colocar en Password cuando AfCrypt es true

🗄️ BASES DE DATOS SOPORTADAS

MySQL / MariaDB

using Adfines.Net.Ganesha.Utils;

var mysql = new MySql(new Initializer()
{
    AfCrypt = true,
    Bdd = "onepiece",
    User = "root",
    Password = "SbBW2UXX83XHhG9Wr/tVQ9beTQ/W59hYTf2FMqL/K4A=",
    Ip = "localhost",
    Port = 3306,
    SslMode = "2"
});

SQL Server

var sqlServer = new SqlServer(new Initializer()
{
    AfCrypt = true,
    Bdd = "prod",
    User = "sa",
    Password = "SbBW2UXX83XHhG9Wr/tVQ13gAq5/rlkTkE22fgB/Nlw=",
    IntegratedSecurity = false,
    TrustCertificate = true
});

PostgreSQL

var postgresql = new PostgreSql(new Initializer()
{
    AfCrypt = true,
    Bdd = "postgres", 
    User = "odoo",
    Password = "SbBW2UXX83XHhG9Wr/tVQzBYlM7x4OaeU8ohdoTdWSg=",
    TrustCertificate = true
});

Oracle

var oracle = new Oracle(new Initializer()
{
    AfCrypt = true,
    Bdd = "XE",
    User = "system", 
    Password = "SbBW2UXX83XHhG9Wr/tVQzzsIpm04BOM7m2vZqvEAAk=",
    Protocol = "1"  // 1: TCP, 2: TCPS, 3: IPC, 4: NMP, 5: SDP
});

🔧 CONFIGURACIÓN DE CONEXIÓN

Parámetros Comunes

Parámetros Específicos

🛠️ FORMAS DE INICIALIZACIÓN

Forma 1: Configuración Directa

var msql = new MySql(new Initializer()
{
    AfCrypt = true,
    Bdd = "onepiece",
    User = "root",
    Password = "SbBW2UXX83XHhG9Wr/tVQ9beTQ/W59hYTf2FMqL/K4A="
});

Forma 2: Desde appsettings.json

var msql = new MySql("EjemploMysql");

appsettings.json:

{
  "AdfinesGaneshaNet": {
    "EjemploMysql": {
      "AfCrypt": true,
      "Bdd": "onepiece",
      "User": "root",
      "Password": "SbBW2UXX83XHhG9Wr/tVQ9beTQ/W59hYTf2FMqL/K4A="
    }
  }
}

Forma 3: Con Parámetros Directos

var msql = new MySql(new Initializer(
    afCrypt: true,
    bdd: "onepiece", 
    user: "root",
    password: "SbBW2UXX83XHhG9Wr/tVQ9beTQ/W59hYTf2FMqL/K4A=",
    ip: "localhost",
    port: 3306
));

Forma 4: Desde Archivo Externo

// JSON
var msql = new MySql(new Initializer("/ruta", "config", "json"));

// CSV  
var msql = new MySql(new Initializer("/ruta", "config", "csv"));

💻 OPERACIONES COMUNES A TODAS LAS BASES DE DATOS

Verificación de Conexión

if (mysql.Success) 
{
    Console.WriteLine("Conexión exitosa a la base de datos");
}

SELECT

var resultado = mysql.Select(
    "SELECT * FROM usuarios WHERE edad > @edad", 
    new() { ["edad"] = 18 },
    "Error al obtener usuarios"
);

INSERT

var insercion = mysql.Insert(
    "usuarios (nombre, email) VALUES (@nombre, @email)",
    new() { ["nombre"] = "Juan", ["email"] = "juan@ejemplo.com" },
    "Error al insertar usuario"
);

UPDATE

var actualizacion = mysql.Update(
    "usuarios SET activo = 1 WHERE id = @id",
    new() { ["id"] = 1 },
    "Error al actualizar usuario"
);

DELETE

var eliminacion = mysql.Delete(
    "usuarios WHERE id = @id", 
    new() { ["id"] = 1 },
    "Error al eliminar usuario"
);

RAW (Consultas Crudas)

var raw = mysql.Raw(@"
    INSERT INTO log (accion) VALUES ('inicio');
    UPDATE contador SET valor = valor + 1;
", "Error en consultas raw");

INSERTED (Inserción con Retorno de ID)

var inserted = mysql.Inserted(
    "usuarios (nombre) VALUES (@nombre)",
    new() { ["nombre"] = "Maria" },
    "Error al insertar"
);

📊 TABLAS DE ESTRUCTURAS DE RETORNO

Entity.Read (SELECT)

Entity.Insert / Update / Delete / Raw

Entity.Inserted

Entity.Err / Entity.Warning

Entity.Props

Estructura Column (Metadatos de Columnas)

🔍 OPERACIONES PROPS (METADATOS)

MySQL (Sin Esquemas)

// Listar todas las tablas
var tablas = mysql.Props();
foreach (var tabla in tablas.List)
{
    Console.WriteLine($"Tabla: {tabla}");
}

// Obtener columnas de una tabla
var columnas = mysql.Props("usuarios");
foreach (var columna in columnas.Column)
{
    Console.WriteLine($"Columna: {columna.Name}, Tipo: {columna.Type}, Nulo: {columna.Null}");
}

SQL Server, PostgreSQL, Oracle (Con Esquemas)

// Listar todos los esquemas
var esquemas = sqlServer.Props();
foreach (var esquema in esquemas.List)
{
    Console.WriteLine($"Esquema: {esquema}");
}

// Listar tablas de un esquema  
var tablas = sqlServer.Props("dbo");
foreach (var tabla in tablas.List)
{
    Console.WriteLine($"Tabla: {tabla}");
}

// Obtener columnas de una tabla en un esquema
var columnas = sqlServer.Props("dbo", "usuarios");
foreach (var columna in columnas.Column)
{
    Console.WriteLine($"Columna: {columna.Name}, Tipo: {columna.Type}");
}

🗃️ CONFIGURACIÓN DE TABLAS DE LOG

Tabla de Errores (error_table)

CREATE TABLE error_table(
    id INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
    creacion DATETIME NOT NULL,
    valor TEXT NOT NULL,
    codigo TEXT NOT NULL,
    descripcion TEXT NOT NULL
);

Tabla de Advertencias (warn_table)

CREATE TABLE warn_table(
    id INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
    creacion DATETIME NOT NULL,
    valor TEXT NOT NULL,
    codigo TEXT NOT NULL,
    descripcion TEXT NOT NULL
);

🐛 MANEJO DE ERRORES Y ADVERTENCIAS

Log Automático

Los errores en consultas SELECT, INSERT, UPDATE, DELETE se registran automáticamente cuando se proporciona el parámetro de descripción de error.

Log Manual

try
{
    // Operación riesgosa
    var numero = "hola mundo";
    var i = int.Parse(numero);
}
catch (Exception e)
{
    // Registrar error
    var error = mysql.Error(e, "Dio error al tratar de convertir un numero: " + numero);
    
    // Registrar advertencia  
    var warning = mysql.Warning(e, "No se pudo convertir el numero " + numero);
    
    // NOTA: Flag se invierte para consultas de error puras
    if (!error.Flag) // true = éxito, false = error al guardar
    {
        Console.WriteLine("Hubo un error al tratar guardar el error");
    }
    else
    {
        Console.WriteLine("id del error: " + error.Id);
    }
}

🔍 EJEMPLOS COMPLETOS

Ejemplo 1: Operación Completa con Manejo de Errores

var mysql = new MySql(new Initializer() { 
    AfCrypt = true,
    Bdd = "onepiece",
    User = "root",
    Password = "SbBW2UXX83XHhG9Wr/tVQ9beTQ/W59hYTf2FMqL/K4A=",
    Error = "error_table",
    Warning = "warn_table"
});

if (mysql.Success) 
{
    Console.WriteLine("Conexión exitosa a la base de datos");
    
    // SELECT con parámetros
    var usuarios = mysql.Select(
        "SELECT * FROM luffy WHERE id > @id AND nombre LIKE @nombre", 
        new() 
        {
            ["id"] = 0,
            ["nombre"] = "%lu%"
        },
        "Problemas al querer listar luffy"
    );
    
    if (usuarios.Err.Flag)
    {
        if (usuarios.Err.Id < 1)
        {
            Console.WriteLine("No se pudo guardar el error en la base de datos");
        }
        else
        {
            Console.WriteLine("Hubo un error. ID del error: " + usuarios.Err.Id);
        }
    }
    else
    {
        // Procesar resultados en diferentes formatos
        Dictionary<string, object?> primerRegistro = usuarios.First.Dic;
        JObject primerRegistroJson = usuarios.First.Obj;
        IList<Dictionary<string, object?>> todosRegistros = usuarios.Info.List;
        JArray todosRegistrosJson = usuarios.Info.Array;
        int totalRegistros = usuarios.Info.Count;
        
        Console.WriteLine($"Total de registros: {totalRegistros}");
        
        // Advertencia condicional
        if (totalRegistros > 100)
        {
            mysql.Warning(new ArgumentException(), "La tabla ya tiene mas de 100 registros");
        }
    }
}

Ejemplo 2: Inserción con Retorno de ID

var inserted = mysql.Inserted(
    @"luffy (nombre, creacion, edad, poder, activo) VALUES (@nombre, @creacion, @edad, @poder, @activo)",
    new()
    {
        ["nombre"] = "luis 3",
        ["creacion"] = "TIMESTAMP()",
        ["edad"] = 89,
        ["poder"] = 55.5,
        ["activo"] = null
    },
    "Hubo un error al querer insertar en luffy"
);

if (inserted.Error.Flag)
{
    if (inserted.Error.Id < 1)
    {
        Console.WriteLine("No se pudo insertar el id del error o no se pudo recuperar el id de la tabla error");
    }
    else
    {
        Console.WriteLine("id del error al insertar: " + inserted.Error.Id);
    }
}
else
{
    Console.WriteLine($"Inserción exitosa. ID: {inserted.Id}");
}

Ejemplo 3: Inserción Múltiple

var insercionMultiple = mysql.Inserts("luffy",
[
    new()
    {
        ["nombre"] = "luis 4",
        ["creacion"] = "TIMESTAMP()",
        ["edad"] = 89,
        ["poder"] = 55.5,
        ["activo"] = null
    },
    new()
    {
        ["nombre"] = "luis 5", 
        ["creacion"] = "TIMESTAMP()",
        ["edad"] = 90,
        ["poder"] = 60.0,
        ["activo"] = 1
    }
], "Hubo un error al querer insertar en luffy");

if (!insercionMultiple.Ok)
{
    Console.WriteLine("Error en inserción múltiple. ID error: " + insercionMultiple.Err);
}

Ejemplo 4: Consultas RAW Múltiples

var activoLuffyRaw = 1;
var consultasRaw = mysql.Raw(@"
    INSERT INTO luffy (nombre, creacion, edad, poder) VALUES ('luis 55', TIMESTAMP(), 80, 22.2);
    UPDATE luffy SET activo = {activoLuffyRaw} WHERE nombre = 'luis 55';
    DELETE FROM luffy WHERE edad > 100;
", "Hubo un error al ejecutar una consulta cruda");

if (!consultasRaw.Ok)
{
    Console.WriteLine("Error en consultas RAW. ID error: " + consultasRaw.Err);
}

❓ PREGUNTAS FRECUENTES (FAQ)

¿Cómo elijo entre las diferentes bases de datos?

Use la clase correspondiente:

• MySql para MySQL/MariaDB
• SqlServer para SQL Server
• PostgreSql para PostgreSQL
• Oracle para Oracle

¿Es obligatorio el WHERE en UPDATE/DELETE?

Sí, por razones de seguridad todas las bases de datos requieren WHERE en UPDATE/DELETE.

¿Qué significa el comportamiento invertido de Flag en Entity.Err?

En consultas de error puras (Error() y Warning()), Flag = true significa éxito y Flag = false significa error. Esto es diferente a otras operaciones.

¿Cómo obtengo el ID del registro insertado?

Use Inserted() en lugar de Insert() para obtener el ID del registro insertado.

¿Puedo ejecutar múltiples consultas en una sola operación?

Sí, use Raw() con consultas separadas por punto y coma.

📝 NOTAS IMPORTANTES

• Siempre incluya WHERE en UPDATE y DELETE por seguridad
• Use el parámetro de descripción de error en producción para mejor debugging
• Las tablas de log se pueden limpiar periódicamente para mantener el rendimiento
• AfCrypt añade seguridad pero requiere usar Password.E() para encriptar
• Verifique siempre la propiedad Success después de crear la instancia
• Los parámetros se convierten automáticamente al tipo apropiado
• Para bases de datos con esquemas, use las sobrecargas apropiadas de Props()