Need Advice: Teach NHibernate with Fluent NHibernate or Without?

I’m in the process of writing an upcoming article for CoDe Magazine about getting started with NHibernate.

I’ve spoken with several people about my approach and the majority of them seem to agree that I should use Fluent NHibernate for the mappings instead of the HBM XML.  Of course, I will mention the HBM XML since Fluent NHibernate isn’t a complete solution (yet) for mappings, but for the day-to-day stuff, Fluent NHibernate is like buttah and will, I think, ease the learning process.

Unfortunately, at this time, Fluent NHibernate doesn’t have any sort of binary release (even a 0.1 release).  So this means I’ll have to tell the readers to use SVN to pull the trunk and do a build.  My instincts tell me that this is too much to ask and too heavy a burden for a “getting started” article.

Thus, a conundrum.  The best answer would be for me to do a build and place the binaries online somewhere for them to download.  Of course there are problems with this approach as well licensing issues perhaps, bandwidth, etc.  Perhaps I could get the FNH folks to cut a 0.1 binary release? *poke poke*  Barring that, what recourse do I have left?

I need the wisdom of the inter-clouds here to assist me in my dilemma. What say you?

About Chad Myers

Chad Myers is the Director of Development for Dovetail Software, in Austin, TX, where he leads a premiere software team building complex enterprise software products. Chad is a .NET software developer specializing in enterprise software designs and architectures. He has over 12 years of software development experience and a proven track record of Agile, test-driven project leadership using both Microsoft and open source tools. He is a community leader who speaks at the Austin .NET User's Group, the ADNUG Code Camp, and participates in various development communities and open source projects.
This entry was posted in Advice, CoDe Magazine, Fluent NHibernate, NHibernate. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • A while ago I suggested to the FNH Mailing list that perhaps the project should get hooked up with the new CodeBetter/IdeaVine TeamCity server. And once we’ve got that rolling, enable archiving of build artifacts so folks could pull nightly builds.

    Oh, and while we’re at it… maybe get StructureMap and NHibernate proper to start archiving nightly builds as well! :)

  • Zach Shewmaker

    I love FluentNHibernate. You probably do too.

    I’d *mention* it in the article (to do the right thing), but teach with the HBM. You mentioned one obvious reason… lack of binaries. But, let’s face it… some companies have strong resistance to third party(and/or open source) libraries… NHibernate alone is much easier to sell than NHibernate+FluentNHibernate (or linq2nhibernate, etc).

  • Hi,
    My opinion is that: when you start learning something new you should minimize number of dependencies on other tools, libs.. etc… that are built on the stuff that you are trying to learn. The main reason is, when something is not working is very hard to guess where really the problem is.
    Maybe that is not the case :)
    But in general, that is the idea

  • As much as I love FNH and use it, irrelevant of the binary dependency, I would teach NH w/o it and then gradually move on to it. It also helps them appreciate both FNH and NH more when that day comes.

  • Definitely use Fluent NHibernate as I believe this will make the learning curve 10 times smaller. I am sure that you can learn the xml easily, but when you make a mistake in there you end up getting weird error messages, while 90% of these mistakes will be catched by the compiler when using Fluent NHibernate. I done a talk about it for NNUG and I am pretty sure that 80% didn’t have any experience with it before, if I would have shown them all the xml needed I guess they would all be screaming and running away. Were as I showed them the nice type safety stuff and easiness of it and hey all sat down for an extra 25 minutes.

    If Paul doesn’t get a 0.1 release before the article is done, I am sure pointing your readers to “a latest build that this article is based on” as a separate download would be a very nice thing.

  • Fluent NHibernate is great, but I belive it’ll be better appreciated when one understands “classic” NHibernate.

  • If it’s a getting started with NHibernate, I’d stick with classic. NHibernate already has a huge learning curve. If you throw another product on there that doesn’t even has a 1.0 release, you increase the curve and cause friction with new people. Sad fact is if you mention you have to pull code down from SVN, have ruby, build with rake, do this do that, etc. … it will probably turn off people.

    Give readers a taste and use Fluent NHibernate as a suggestion once they get comfortable with it as an alternative to setup your mappings.

  • If binaries are what you need, binaries you shall receive. I’ll try to address this tonight.

    joey: What would be in a 1.0 release that isn’t already available?

  • Dirk

    I’m going to get flamed for this, but I never seriously looked at NHibernate, exactly because of the lack of a decent mapping solution
    You know the RegEx joke …
    So I wouldn’t even read you article if it doesn’t have Fluent NHibernate :-)

  • I’d say it eases the learning curve a bit. I’m preparing a lunch & learn on NHibernate and I’m going to integrated fluent-nhibernate and nhibernate.linq.

    Maybe your article can help “bully” the project into at least a 0.1 release? I mean why not?

  • Well, it has already been pointed out by you and others, but I agree a few important points are:
    - lack of binaries
    - they are still translated to xml under the hood, so it might be important to know that well because,
    - it’s a young product

    All in all, the important question is, Is it easier to “get” NHibernate with FNH? Has the product reached the point/maturity where you don’t need to know about the mapping files at all?

  • David McClelland

    I’d suggest teaching straight-up NHibernate through examples in your article, and then in a final paragraph show how you could accomplish the exact same mapping in just XX lines of code using Fluent NHibernate.

    As Derik Whittaker discovered, debugging problems with Fluent NHibernate involves looking at the underlying HBM XML sometimes:

    … so while Fluent NHibernate is still young it’s good to have a grasp of what’s going on under the covers.

  • I also love Fluent NHibernate. So much cleaner, more elegant, more versatile (in the long run), but…
    You should probably stick with the hbm approach. :(

    If someone is coming into an existing NHibernate project for the first time, more than likely they will be using the hbm approach.

    Also, it really helps a persons understanding fluent if they know the hbm.

  • I’m liking Fluent NHibernate, but allow me to echo: stick with the hbm approach.

  • While not a direct response to your question, I’d like to see an NHibernate introduction that starts with the domain model and creates the mapping and database as artifacts. Almost every NHibernate tutorial that I have seen to date, starts with a data model and creates the mappings and/or classes or starts with the mappings and works its way out to the classes and database.

  • Chad,

    I’d recommend using the XML mappings anyway. Main reason being that all of the documentation on the web references the .hmb files. All mapping is done in XML> You want users to walk away from your class/artcle and continue to use NHibernate, right?

    When they do, they are invariably going to run up against a wall on something; there’s going to be some mapping that they don’t know how to accomplish, and they’ll have to hit Google and the web docs to figure it out. And it’s all going to be in .hbm terms.

    Allow folks to make the progression themselves. I just started using NHibernate myself on a project. All documentation is in XML terms. Someday in the future I’d like to look at Fluent NHibernate and see how it works. But right now, being productive is more important, and all the documentation that helps me get through the mappings is in XML examples.

  • @Weston: For this audience (CoDe Magazine), I seriously doubt many of them are green field, and so I don’t think it would be appropriate to get into DDD or any of that stuff (as much as I’d love to). This is all about making their current problems a little easier. We can talk about that separately, if you want some advice or something?

    @Everyone: Sounds like the “XML”‘s have it. I still will plug Fluent NHibernate heavily and maybe even show examples along with the XML. But it seems clear, given your advice, that I should not ignore the HBM XML and, instead, make it the primary mapping example format.


  • cisco

    why not have the article be w/o Fluent NHibernate but write the very same artcile in Fluent NHibernate with a link within the CoDe magazing article. It will really push the effort forward

    yes it may be more work but i’m not writing it ;)

  • cowgaR

    my take is different than the majority here…

    what is the point of starting to teach NHibernate in the year 2009? there are (let me count) ok…there are _zillions_ of guides already avaiable not only on the net.

    what the community miss is Fluent NHibernate + NHibernate tutorial and probably some alpha 2.1 LINQ stuff…that would digg deeply. With FNH your chapter 3 can look on generic repository pattern, whereas w/o it your chapter 25 will still only be entitles “and now, mapping our product entity with xml files and inspecting more config options” ;-)
    e.g. more to the point guide, and btw, there are many HBML generators out there making teaching HBML deeply pointless…

    if it is meant for “learning” you don’t need advanced stuff anyway

  • What about using just Auto Mappings?

    Just show off. Writing the model, then show how to map the whole lot in 2 lines of code with Auto Mappings :)

    You could finish by demonstrating something that goes beyond Auto Mapping capabilities. Do that using both .hbm AND Fluent, which would show they can be used side-by-side.

  • @cowgaR, Tobin:

    Keep in mind, the audience here is likely people who are still rolling their own ADO.NET adapters for stored procedures and have no concept of ORM, let alone any idea to even LOOK for NHibernate in the first place.

    This is a gradual introduction into the concept of, “No, you don’t have to write your own ADO.NET layer every project you’re on”

    I need to gently coax them into letting go of their datareaders and datasets, etc. Automapping would likely blow their mind.

    Starting with Automapping is likely showing someone the “COS” button on a calculator without having taught them basic trigonometry first.

  • While I love FNH’s attempts to provide default ‘convention-mapping’ as well as better support for refactoring tools, I feel strongly that teaching anyone anything about NH when the premise is that the audience is “too stupid to read or compose XML files” is a HUGE error.

    If the concern is that a dev in the audience cannot grok XML then this is a class of dev that I would strongly argue is NOT a candidate for using NH at all — with or without FNH. If the dev is in this class, then the very next set of problems they will face are challenges with efficient query composition, the n+1 lazy loading issues, improper understanding of either the 1st or 2nd level caches, how UoW behaves, and more.

    I am NOT debating the value of FNH (which I think is HIGH), but if its intent was “to make NH approachable for the class of dev that cannot navigate XML” then I think its largely doomed to short-term gain but long-term failure in that you will be able to attract a whole new class of user that will quickly conclude “that NH performs terribly” due to their lack of ability to understand how to configure and implement it efficiently.

    Its not clear to me at all that there is a class of dev out there that is both a) frightened to death of XML and b) able to effectively use NH in a production app “if only we could get the XML out of the process”. It may be that your experience in this regard is different from mine, but I haven’t met these people in my own travels :) As such, I think you should carefully consider the skills your audience has and from there determine if they are even candidates for using NH at all (with or without XML or FNH).

  • @Steve:

    I have never said that they’re too stupid to do XML. I just think FNH has a less steep learning curve at first blush. It’s a complicated problem and it’s not quite that simple, but I do think that FNH is more approachable and involves less hassle than the XML.

    Already, now that I’ve proceeded down the XML path, I’m realizing what a pain it is and how many gotchas there are (i.e. “oops, forgot about marking it as ‘embedded resource’! — oops, I misspelled the file — “.hmb.xml”, etc, etc, etc). Not having the compiler kick you when you make a mistake can be a real drag when you’re troubleshooting a stupid error like a typo in the file name.

    That was my primary concern — easing the transition. I don’t assume anyone is “stupid” except myself.

  • Well, I will admit that ‘stupid’ was perhaps too strong a word and I hereby retract it but I guess where I was coming from is that if your target audience isn’t able to grok XML then they are quite likely IME to bump into the 1000 other things in NH that represent challenges to the level of dev that wouldn’t be able handle the XML.

    Not that there aren’t bunches and bunches of these people out there, but I think that all I’m really saying is much the same as some of the other commenters here: FNH is an abstraction over the behavior of NH mapping that the XML makes clear but that FNH can too easily IMHO make look like ‘magic’ and if you don’t take the time to understand what the abstraction is actually DOING for you, you will very quickly bump into its limitations.

    I guess as with all abstractions it comes down to this: “is the abstraction so leaky that most people using it will find themselves having to deal with the thing under the abstraction?” and in the case of FNH it seems to me that pretty quickly its early-state limitations will come bubbling out at anyone trying to do ‘real’ work with NH using JUST the FNH approach and they won’t be properly equipped to deal with it because they will lack the foundational knowledge to know what’s going on because they’ve only been introduced to the abstraction.

    I’m guessing that with time FNH may indeed reach a maturity level where it can indeed be a whole-hog replacement for any use of XML mapping files (and I for one will rejoice on that day, even as someone who DOES understand the XML and appreciates its power and flexibility) but IMO that day just isn’t here (yet).

  • @chad,

    Gotcha, didn’t realize who your target audience was.

    Hmmm… I’ve just left a shop that is moving from ADO.NET + Sprocs to NHibernate. Surprisingly I didn’t really have to sell them NHibernate directly, I just used it on a project and it got them curious.

    There were four things, I believe, that convinced them NHibernate was seriously worth considering.

    1) It has community respect. When they read around, they see influential people praising NHibernate (mostly!). It’s generally respected, trusted and widely used.

    2) They noticed that I as adding DAL-related capabilities to our solution in very little time. Things like full text search, caching and switching to a different database platform were possible in minutes. They had just recently spent many man weeks adding these features manually to their code bases.

    3) At a big customer sales meeting, it turned out a competitor was leveraging the goodness of _H_ibernate in their enterprise product. This re-enforced the notion that NHibernate *might* be good for their solutions too.

    4) They had recently chosen to adopt Target Process for project managment, and realized that this great tool was built on NHibernate. They could see NHibernate being used successfully in the wild (after all, they paid good money for TP).

    Unfortunately only one of these factors is really code-related, so I don’t know how useful that is to you.

    Back to mappings. I believe the devs grasp the concept of POCO -> XML -> Database quite well, it’s a safe choice.

  • MIke

    I’d eliminate unnecessary dependencies. XML is easier to visually grasp how a single object is mapped than Expressions anyways IMO.

  • I’ve used NHibernate for years. NHibernate with .hbm.xml has a steep learning curve and Fluent NHibernate has a relatively small learning curve and it much easier to understand. I don’t see a point in teaching the .hbm.xml way other than mentioning that it’s how to do NHibernate the “old way” and that under the hood it’s using XML mapping files.

    If you’re trying to teach someone the .hbm.xml way, you would have to cover all kinds of things, like what all the mappings are, that the files have to be embedded resources, that assembly names have to be fully qualified, that you have to specify your unsaved value, how to generate Guid PKs, etc. — all stuff that you don’t have to address in an intro to Fluent NHibernate.

  • Kerry

    Somewhat belated, sorry. I’m finally starting to learn the basics of nHibernate in the hopes that we’ll be using it here in the near future. Since I don’t know where the company’s decision will be, my choice is to learn NHibernate, then add Fluent NHibernate to it. This way I’ll have a better understanding of the underpinnings, regardless of the implementation the company ultimately uses.

    Unless Fluent NHibernate is going to replace NHibernate, my vote is for at least a basic grounding in NHibernate, and a mention of the differences between the two.