nh-tool 1.2.0

nh-tool

CLI tool that scaffolds NHibernate Mapping-by-Code entities and mappings from your database schema. Think dotnet ef dbcontext scaffold, but for NHibernate 5+.

Install

dotnet tool install --global nh-tool

Usage

nh-tool nh-scaffold <connection-string> <provider> [options]

Quick Examples

# SQL Server - all tables
nh-tool nh-scaffold "Server=.;Database=MyDb;Trusted_Connection=true;TrustServerCertificate=true" sqlserver \
  -o ./Generated -n MyApp.Data

# Oracle - specific tables only
nh-tool nh-scaffold "Data Source=myhost:1521/ORCL;User Id=HR;Password=hr123;" oracle \
  -t EMPLOYEES,DEPARTMENTS -o ./Generated -n HrModule.Data -s HR

# Exclude tables + force overwrite
nh-tool nh-scaffold "Server=.;Database=MyDb;..." sqlserver \
  -x AUDIT_LOG,TEMP_DATA --force -o ./Generated -n MyApp.Data

# Preview without writing files
nh-tool nh-scaffold "Server=.;Database=MyDb;..." sqlserver --dry-run

Options

What Gets Generated

Generated/
  Entities/
    User.cs           # POCO with virtual properties + navigation
    Order.cs
    OrderItem.cs
  Mappings/
    UserMap.cs         # ClassMapping<T> with ManyToOne/Bag
    OrderMap.cs
    OrderItemMap.cs
  NHibernateHelper.cs  # Thread-safe ISessionFactory configuration

Entity with Navigation Properties

public class Order
{
    public virtual int Id { get; set; }
    public virtual DateTime OrderDate { get; set; }
    public virtual decimal TotalAmount { get; set; }

    public virtual Customer Customer { get; set; }                              // ManyToOne
    public virtual IList<OrderItem> OrderItems { get; set; } = new List<OrderItem>();  // OneToMany
}

Mapping with FK + Identity Support

public class OrderMap : ClassMapping<Order>
{
    public OrderMap()
    {
        Schema("dbo");
        Table("ORDERS");

        Id(x => x.Id, m =>
        {
            m.Column("ID");
            m.Generator(Generators.Identity);  // Auto-detected from SQL Server IDENTITY
        });

        Property(x => x.OrderDate, m =>
        {
            m.Column("ORDER_DATE");
            m.NotNullable(true);
        });

        ManyToOne(x => x.Customer, m =>
        {
            m.Column("CUSTOMER_ID");
            m.NotNullable(true);
        });

        Bag(x => x.OrderItems, c =>
        {
            c.Key(k => k.Column("ORDER_ID"));
            c.Inverse(true);
            c.Lazy(CollectionLazy.Lazy);
        }, r => r.OneToMany());
    }
}

SessionFactory Helper

var factory = NHibernateHelper.BuildSessionFactory("Server=.;Database=MyDb;...");
using var session = factory.OpenSession();

// Optional cleanup APIs:
NHibernateHelper.DisposeSessionFactory("Server=.;Database=MyDb;...");
NHibernateHelper.DisposeAllSessionFactories();

Supported Databases

Key Features

• Foreign Keys - Auto-detected ManyToOne + OneToMany navigation properties
• Composite FK handling - Keeps scalar FK columns and warns that composite navigations require manual mapping
• Shared-PK safety - Skips auto ManyToOne when FK column is part of PK to avoid repeated column mapping
• IDENTITY / Sequence - SQL Server IDENTITY and Oracle sequences auto-detected
• Mapping-by-Code nativo - No FluentNHibernate, uses NHibernate 5+ ClassMapping<T>
• Smart naming - USERS → User, CUSTOMER_ID → Customer navigation (Humanizer)
• Composite PKs - Detected and mapped with ComposedId
• PK strategy - Identity, Sequence, Native, or Assigned based on column metadata
• Thread-safe session factory cache - Generated NHibernateHelper uses ConcurrentDictionary<string, Lazy<ISessionFactory>>
• Table filtering - --tables to include, --exclude-tables to exclude
• Dry run - Preview generated files and composite-FK warnings before writing
• Force overwrite - --force to overwrite existing files
• Legacy mode - --use-legacy-style for .NET Framework / C# 7.3 compatibility

Requirements

• .NET 8.0+

License

MIT