NHibernate para C# (.NET): guía completa con ejemplos

¿Qué es NHibernate y para qué sirve?

NHibernate es una potente y madura biblioteca de mapeo objeto-relacional (ORM) para la plataforma .NET, escrita en C#. Es un puerto de la famosa biblioteca Java Hibernate. NHibernate resuelve el problema fundamental de la falta de coincidencia entre el modelo de datos orientado a objetos en su aplicación C# y el modelo de datos relacional en la base de datos (SQL Server, PostgreSQL, MySQL, Oracle, etc.).

La tarea principal de NHibernate es automatizar la conversión de datos entre objetos C# (POCO — Plain Old CLR Objects) y registros en tablas de base de datos. En lugar de escribir cientos de líneas de código SQL repetitivo para operaciones CRUD (Create, Read, Update, Delete), usted trabaja con objetos, y NHibernate se encarga de la generación y ejecución de consultas SQL.

¿Por qué usar NHibernate?

\n
• Aumento de la productividad en el desarrollo: Escribe menos código, especialmente código repetitivo (boilerplate) para trabajar con ADO.NET.
\n
• Reducción de errores: Las consultas SQL se generan automáticamente, lo que reduce el riesgo de errores de sintaxis e inyecciones SQL (si se usa correctamente).
\n
• Independencia de la base de datos: Puede cambiar de SGBD modificando solo la cadena de conexión y el dialecto de NHibernate, sin reescribir la lógica de negocio.
\n
• Gestión de caché: Los mecanismos integrados de caché de primer y segundo nivel aceleran significativamente el rendimiento de la aplicación.
\n
• Lazy Loading (Carga diferida): Los datos relacionados se cargan solo cuando realmente se necesitan, lo que ahorra recursos.
\n
• Potente lenguaje de consultas: HQL (Hibernate Query Language) y LINQ to NHibernate permiten escribir consultas con seguridad de tipos.
\n

Instalación de NHibernate

NHibernate se distribuye a través de NuGet, el gestor de paquetes para .NET. La instalación es muy sencilla.

A través de la consola del administrador de paquetes (Package Manager Console):

Install-Package NHibernate

A través de .NET CLI (para proyectos .NET Core / .NET 5+):

dotnet add package NHibernate

Paquetes adicionales (según sea necesario):

\n
• NHibernate.Caches.CoreMemoryCache — para caché de segundo nivel.
\n
• System.Data.SqlClient o Microsoft.Data.SqlClient — para trabajar con SQL Server.
\n
• Npgsql — para trabajar con PostgreSQL.
\n
• MySql.Data — para trabajar con MySQL.
\n

Después de la instalación, deberá configurar la configuración (generalmente en el archivo app.config, web.config o appsettings.json) o mediante la configuración Fluent en el código.

Inicio rápido con ejemplo de código

Consideremos un ejemplo muy simple de trabajo con NHibernate. Supongamos que tenemos una tabla Products en una base de datos SQL Server.

1. Creamos la clase de entidad (Entity):

public class Product\n{\n    public virtual int Id { get; set; }\n    public virtual string Name { get; set; }\n    public virtual decimal Price { get; set; }\n}

Importante: Todas las propiedades deben ser virtual — este es un requisito de NHibernate para implementar mecanismos de proxy (lazy loading, seguimiento de cambios).

2. Creamos el archivo de mapeo (Product.hbm.xml):

<?xml version="1.0" encoding="utf-8" ?>\n<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2"\n                   assembly="YourAssemblyName"\n                   namespace="YourNamespace">\n    <class name="Product" table="Products">\n        <id name="Id" column="ProductId">\n            <generator class="native" />\n        </id>\n        <property name="Name" column="Pro