On the "new user" experience.... (it's not good 😬)

[space-alien]

I have never used NHibernate, but I have experienced enough frustration with EF Core (and the odd article extolling the superiority of NHibernate) that I very much wanted to give it a try for a new project. I expect there are many more in the same situation as me.

I wanted to share - in a purely constructive spirit - my experience as I approached NHibernate for the very first time. These points reflect the two most important factors:

1. The ease of getting started with the library as a new user, which obviously needs to be as frictionless as possible, and
2. the perception of the state of the project, which influences the decision whether to make the commitment of adopting it...

So, without further ado:

• The getting started tutorial "Your first NHibernate based application" was last updated in 2011 and is hopelessly outdated.
• As someone coming from EF, the Fluent API and convention-based mapping is pretty much baked into the mindset:
  • But NHibernate's "Mapping By Code" or "By Convention" features don't appear to be documented anywhere (Add documentation for Mapping by Code and By Convention #1571, NH-3730 - Document Mapping By Code #888). It's impossible to find any decent guidance or blog posts on fluent mappings.
  • There's no obvious guidance as to how or whether the FluentNHibernate relates to these features. In any case, the FluentNHibernate project looks pretty much dead.
• The number of open issues in this repo may only be half that of EF Core, but the vast majority were migrated over from the previous tracker and have not been touched since. I found some dating back to 2011. Only around 70 have had any activity in the last 12 months.
• The NHibernate website appears outdated (both content and cosmetics):
  • There aren't any books for v5, so the links to the (aging) books for v4 on the NHibernate website home page are not appealing. The final book link is broken entirely.
  • The blog has not been updated in years (not even a 5.2 announcement).
  • The wiki link points to a completely empty wiki created in 2014.
  • The last tweet on the Twitter feed (linked on the website), was in 2011.

Now, I do of course fully appreciate the time and priority constraints of maintaining an open source project, and none of this is meant in any way to be taken as negative criticism. However, I expect that my experience is probably replicated many times over, and is probably hurting adoption of NHibernate amongst a generation of potential new users who would be interested in a better .NET Core ORM.

Some of the above problems above are low hanging fruit (e.g. tidying up dead links or reducing the prominence of abandoned content).

But I think that what is needed more than anything, is just one freshly-written "getting started" tutorial. Because there really is nothing decent out there.

• In the same vein as those guides that EF Core newbies will find on MS Docs or all over the web
• Ideally targeting a simple ASP.NET Core 3.1 web project - although even a console app would be something at this point.
• Obviously making use of whatever modern / code-first / convention-based POCO mappings are now available in NHibernate.

On that last point, I'm afraid I can't be more specific, because sadly I reached the conclusion (rightly or wrongly) that it would require too much time and effort to overcome the documentation issues, and that was a great pity for me!

I hope this insight is helpful in some way!

[fredericDelaporte]

We are lacking contributors for documentation, that is a sure fact. And yes, this can only hurt adoption.

Now the old content is not hopelessly outdated from my viewpoint. NHibernate is mature and stable since a long time, it does not have disruptive changes between major versions.

v5 is an update to .Net Framework 4.6.1 featuring async support. The v5.1 added .Net Core support.
Many smaller features, improvements or bug fixes are also done in those versions.
But basic principles of NHibernate have not changed.

The most updated documentation is the reference documentation. It looks raw, but that is the one which is most frequently updated. The other Web content is indeed not really maintained. Announcements are done on SourceForge and on the groups.

There is also a minimal example project in the sources, demonstrating both .Net Framework and .Net Core use of NHibernate.

About #888, as I am quite used to xml mappings, and I have never used By Code, I am unlikely to document it myself.

Convention based mapping is also available but I have myself discovered it only by reading the book "NHibernate Cookbook" (v3 or v4, both cover it).

FluentNHibernate is an independent project which provides another way to map entities with NHibernate. The NHibernate organization does neither manage nor support FluentNHibernate.

And there is a fourth way of mapping, attributes. This one is documented in the reference as contrib extension, which it is, even if host and maintained by the NHibernate organization.

All of these are available since "ages" indeed.

There may be another pain point for newcomers: NHibernate gives a lot of choices. (Out of the box, three ways of mapping (XML, By Code, Convention) and a fourth as an extension (Attributes) ; four querying APIs (HQL, Criteria, QueryOver, Linq, and also plain SQL), ...)
And we do not give much guidance about which one to choose, because that is as always a matter of selecting the most appropriate tool for the task to be done. (Well, QueryOver can be considered as an update of Criteria, so better select QueryOver than Criteria. But for choosing between HQL, QueryOver or Linq, it depends on the needs.)

I had myself an easy start with NHibernate, because I was given a working Web site to start with, already in production since a few years, using NHibernate 0.9 at that time. So I had already quite a good starting point. (And I was not tempted to switch for a Microsoft backed alternative such as EF, since it was not existing at that time. So I have learned it, and now I will surely not switch a NHibernate project to EF. I have also handled projects with EF for a few years, but I would rather consider switching from EF to NHibernate, or Dapper if I conclude a full ORM is overkill for the project.)

[bahusoid]

I totally agree it's not user friendly for newcomers at all. NHibernate is like an old religion - it's quite settled with existing userbase and not fighting for newcomers. And no NHibernate evangelists nowadays (at least willing to contribute) - so there is no up to date "noob" tutorials.

[gliljas]

Thanks for your constructive criticism, @space-alien! NHibernate is an old beast, which, if you count its Java ancestor, has concepts and code harking back almost 18 years. That is both its strength and its weakness. The strengths comes as customisability, being able to deal with legacy systems, and an API that is not making it impossible for old systems to upgrade. The weakness is that some parts can feel outdated, but in terms of actual API and code, but also the documentation and the coolness that inspires community produced tutorials etc.

The last few years, in no small respect thanks to the guys above (and others), the project has been given renewed energy, and I'm sure that it is possible to take a path where the strengths are kept (in a mostly backwards compatible way), while modernising both code and documentation. At least, as a full-time NHibernate user (I would say I am) and a "some times" contributor, that's what I hope.

[fairking]

I would like to add few more links to help @space-alien with getting started with NH.

• Map-By-Code (https://notherdev.blogspot.com/2012/02/nhibernates-mapping-by-code-summary.html) everything you need.
• My SimpleMapping project (https://gitlab.com/fairking/nhibernate.simplemapping) for those who don't like complicated things.

[vocko]

I have to agree with what was said above. I was using Entity Framework (and EF Core) up until today and wanted to try NHibernate more out of curiosity than any need for a change. But the lack of documentation and beginner guides makes it a nightmare for newbies. I.e., the only fluent mapping tutorial is far from perfect and mainly 8 years old (and 2 major versions behind) so I'm not even sure if it is still valid or whether things changed significantly. And even google doesn't help as any related sources are very scarce.

I'm really close to give up now as my productivity was very low and everything takes too much time to figure out. Not saying that it will cost me another extra time to bring other people on the project up to speed.

I'm not saying it is a bad product, my decision was based on some blog posts where the feedback was overall positive, however, good documentation should be a cornerstone of any software otherwise it is doomed to die.