NHibernate blog : NHibernate Documentation

NHibernate 3 Beginners Guide published

gabriel.schenker — Mon, 29 Aug 2011 20:27:00 GMT

Note: This post has been cross posted from my own blog at Los Techies.

I am very pleased to announce that my book NHibernate 3 Beginners Guide has finally been published. It is a wonderful feeling to finally have a book in my hands that cost me a couple of months of intense work. But I think the result is well worth it.

If you are interested in the book then there is also a free chapter available for download.

I was lucky to have Fabio Maulo and José F. Romaniello as my reviewer, the former being the lead of the NHibernate project and the latter an active contributor to the the project.

My goal for this book has been to provide an easy to follow introduction to NHibernate 3.x. The text covers NHibernate up to version 3.1 GA and even references some of the new features of NHibernate 3.2 GA. It was very important to me to not use a data centric approach but rather choose a model first approach.

In this regard this book is NOT just an updated version of NHibernate 2 Beginners Guide but rather a complete rewrite.

I also have paid attention to cover all foundational topics in a clear and concise way. In no way did I want to abandon the reader in the dust of uncertainty.

Let me provide you the list of chapters found in the book with a short introduction about the respective content of each chapter.

Chapter 1, First Look… explains what NHibernate is and why we would use it in an application that needs to access data in a relational database. The chapter also briefly presents what is new in NHibernate 3.x compared to the version 2.x and discusses how one can get this framework. Links to various sources providing documentation and help are presented.

Chapter 2, A First Complete Sample…walks through a simple yet complete sample where the core concepts of NHibernate and its usage are introduced.

Chapter 3, Creating a Model… discusses what a domain model is and what building blocks constitute such a model. In an exercise the reader creates a domain model for a simple ordering system.

Chapter 4, Defining the Database Schema…explains what a database schema is and describes in details the individual parts comprising such a schema. A schema for the ordering system is created in an exercise.

Chapter 5, Mapping the Model to the Database…teaches how to bridge the gap between the domain model and the database schema with the aid of some wiring. This chapter presents four distinct techniques how the model can be mapped to the underlying database or vice versa. It is also shown how we can use NHibernate to automatically create the database schema by leveraging the meta-information contained in the domain model.

Chapter 6, Sessions and Transactions…teaches how to create NHibernate sessions to communicate with the database and how to use transactions to group multiple tasks into one consistent operation which succeeds or fails as a whole.

Chapter 7, Testing, Profiling, Monitoring and Logging…introduces how to test and profile our system during development to make sure we deliver a reliable, robust and maintainable application. It also shows how an application can be monitored in a productive environment and how it can log any unexpected or faulty behavior.

Chapter 8, Configuration… explains how we can tell NHibernate which database to use, as well as provide it the necessary credentials to get access to the stored data. In addition to that many more settings for NHibernate to tweak and optimize the database access are explained in this chapter.

Chapter 9, Writing Queries… discusses the various means how we can easily and efficiently query data from the database to create meaningful reports on screen or on paper.

Chapter 10, Validating the data to persist…discusses why data collected by an application needs to be correct, complete and consistent. It shows how we can instrument NHibernate to achieve this goal through various validation techniques.

Chapter 11, Common Pitfalls – Things to avoid… as the last chapter of this book presents the most common errors developers can make when using NHibernate to write or read data to and from the database. Each such pitfall is discussed in details and possible solutions to overcome the problems are shown.

Welcome NH2.1.0

Fabio Maulo — Sun, 19 Jul 2009 13:27:00 GMT

NHibernate 2.1.0GA was released today.

Download it!

After download it please take a look to releasenotes.txt file.

Note: The series NH2.1.x is the last whose target is .NET2.0

The reference manual is available for download.

We can’t release the API doc because its size. To compile API documentation you need to download sources and call : nant api.

Architecture Diagram Rework

Stefan Steinegger — Thu, 04 Jun 2009 13:34:00 GMT

While working on the NHibernate Documentation, I’m drawing some pretty pictures. I actually never liked the architecture diagrams much, because I never knew what exactly they are trying to show.

The original architecture diagram looks like this:

I never found this diagram very helpful. (When I started learning NH, Transient Objects and Persistent Objects were very confusing to me. Are this different classes?)

So I decided to rework it. I ended up with something that is not very different from the existing diagrams so:

I shouldn’t cover all the little details of the NHibernate’s internal design, just the concepts that are visible to the user.

What do you think: is this kind of useful?

Documentation Project Launch

Stefan Steinegger — Tue, 02 Jun 2009 16:52:00 GMT

I started to restructure and enhance the NHibernate documentation. I want to move from a "Reference Documentation" to a "Programmers Manual". The difference is, that when you read a reference documentation you already know the concepts and only need to know details like xml elements or HQL syntax. A manual should explain the concepts in detail and you should be able to understand it even if you are new to NHibernate.

The current documentation is explaining quite a lot - it is not only a reference. Most of the documentation is already there. But in my opinion it is sometimes on the wrong place.

Let me demonstrate this with some randomly picked examples:

Chapter 2.3 "Contextual Sessions": We don't even know, what a session actually is at this point and what it is used for.
Chapter 3.3 "User Provided ADO.NET connection": It is the first chapter about how to optain a connection and it appears to be the easiest and recommended way. This chapter should be last option and there should be a hint that some things won't work with user provided connections (eg. Hi-Lo identities afaik).
Chapter 3.5 "Optional configuration properties": There is a list of all optional properties. This is a "reference" kind of documentation. For instance, all the hibernate.cache.* parameters should be explained in a chapter about NH second level caches, unless the reader can't do anything with the information.
By the way, the possible values for each parameter is documented as "eg: ...". It should be a complete list.

And so on.

The new structure how I propose it is available as draft in the wiki. Please read it and comment to it if you think it should be different. Now it is still easy to change.

It will be quite a bit of work, and I will need some help. Now stop moving the mouse towards the "return" or "close tab" button and keep reading. Thanks. You can even help if you don't have much time and if you are not the Great Master of NHibernate. This is how you can help:

Give me some feedback to my plans, on this blog and on the structure proposal. This is important to me.
Tell me what you miss in the documentation, or what you would like be changed. Also tell me what you like and should be kept as it is.
I will ask specific questions in further blogs. So please keep reading them :-)

Later, I will need some people to:

review the docs. For instance, a native English speaker to turn my (and probably others) Pidgin English into real English. Or a NH developer who checks if it is actually true.
develop the tools. We are using DocBook, if you know about XSL:FO or how to configure HTML output, your help will be much appreciated.
develop examples and diagrams. But before we start writing such things, we need to know what has to be demonstrated with it.