NHibernate para C# (.NET): guia completo com exemplos

O que é NHibernate e para que serve?

NHibernate é uma biblioteca de mapeamento objeto-relacional (ORM) poderosa e madura para a plataforma .NET, escrita em C#. Ela é uma adaptação da famosa biblioteca Java Hibernate. O NHibernate resolve o problema fundamental de incompatibilidade entre o modelo de dados orientado a objetos em sua aplicação C# e o modelo relacional de dados no banco de dados (SQL Server, PostgreSQL, MySQL, Oracle e outros).

A principal função do NHibernate é automatizar a conversão de dados entre objetos C# (POCO — Plain Old CLR Objects) e registros em tabelas do banco de dados. Em vez de escrever centenas de linhas de código SQL repetitivo para operações CRUD (Create, Read, Update, Delete), você trabalha com objetos, e o NHibernate assume a geração e execução das consultas SQL.

Por que usar NHibernate?

\n
• Aumento da produtividade no desenvolvimento: Você escreve menos código, especialmente código boilerplate para trabalhar com ADO.NET.
\n
• Redução de erros: As consultas SQL são geradas automaticamente, reduzindo o risco de erros de sintaxe e injeção de SQL (quando usado corretamente).
\n
• Independência de banco de dados: Você pode trocar de SGBD alterando apenas a string de conexão e o dialeto do NHibernate, sem reescrever a lógica de negócios.
\n
• Gerenciamento de cache: Mecanismos de cache de primeiro e segundo nível integrados aceleram significativamente a aplicação.
\n
• Lazy Loading (Carregamento Tardio): Dados relacionados são carregados apenas quando realmente necessários, economizando recursos.
\n
• Linguagem de consulta poderosa: HQL (Hibernate Query Language) e LINQ to NHibernate permitem escrever consultas type-safe.
\n

Instalação do NHibernate

O NHibernate é distribuído via NuGet — o gerenciador de pacotes para .NET. A instalação é muito simples.

Através do Console do Gerenciador de Pacotes (Package Manager Console):

Install-Package NHibernate

Através do .NET CLI (para projetos .NET Core / .NET 5+):

dotnet add package NHibernate

Pacotes adicionais (conforme necessário):

\n
• NHibernate.Caches.CoreMemoryCache — para cache de segundo nível.
\n
• System.Data.SqlClient ou Microsoft.Data.SqlClient — para trabalhar com SQL Server.
\n
• Npgsql — para trabalhar com PostgreSQL.
\n
• MySql.Data — para trabalhar com MySQL.
\n

Após a instalação, você precisará configurar a configuração (geralmente no arquivo app.config, web.config ou appsettings.json) ou através de configuração Fluent no código.

Início rápido com exemplo de código

Vamos considerar um exemplo simples de trabalho com NHibernate. Suponha que temos uma tabela Products em um banco de dados SQL Server.

1. Criando a classe de entidade (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 as propriedades devem ser virtual — este é um requisito do NHibernate para implementar mecanismos de proxy (lazy loading, rastreamento de alterações).

2. Criando o arquivo de mapeamento (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