Alan Northam : Tutorial

Custom Profile Provider with NHibernate

anortham — Thu, 09 Aug 2007 13:29:00 GMT

I've updated the NHibernate blog example code to include a custom profile provider. This provider stores the profile information using the XML data type in SQL Server 2005. New profile properties can be added to the web.config file in same way as the Microsoft SqlProfileProvider. The included web.config contains examples showing how to add new properties and their types. If adding a custom type be sure to include the full type name (i.e. NHBlog.BusinessEntities.Security.Application.).

The example now includes custom NHibernate based providers for Membership, Roles, and Profiles.

Getting Started with NHibernate: Part IV

anortham — Thu, 26 Jul 2007 20:07:00 GMT

I've made some major changes to the blog application example. The users and roles now use custom membership and role providers that supports NHibernate. Session context is maintained with a custom implementation of ICurrentSessionContext (a new NHibernate 1.2 feature). The session and session factory management classes have also undergone some minor modifications. I've also included a very basic web user interface that uses Ajax for Asp.Net (previously Atlas). I'll cover some of these topics in more detail in upcoming posts.

The attached zip file contains the VS2005 solution and a SQL script to generate the database schema (SQL 2005 or SQL Express 2005 only).

Getting Started with NHibernate: Part III - Updated

anortham — Wed, 30 May 2007 19:49:00 GMT

I've updated the mapping files for Comment and BlogPost in Part III.

The changes are:

The named query GetCommentsByBlogPostID has been moved into the BlogPost.hbm.xml file, it just makes more sense for it to be there.
<loader query-ref="GetCommentsByBlogPostID"/> was added to the Comments collection mapping in the BlogPost.hbm.xml file, NHibernate will use this query when loading the collection.
cascade="delete", and inverse="true" attributes were added to the Comments collection mapping in the BlogPost.hbm.xml file, the combination of these two setting ensure that when a BlogPost is deleted all of the comments associated with it will also be deleted. It is unlikely that you would want to delete a BlogPost and all it's comments in a live blog application (although you might want to archive or hide them) but here it serves the purpose of demonstrating these attributes usage.
The Comment mapping file (Comment.hbm.xml) was updated to include a stored procedure call for loading comment entities by ID.

These changes will be covered in greater detail as the application progresses. Part IV is coming soon and will include all updates, source code, and SQL Express database.

Getting Started with NHibernate: Part III

anortham — Wed, 23 May 2007 18:11:00 GMT

When mapping objects to the database in NHibernate you can either use XML files or decorate your classes with mapping attributes (NHibernate.Mapping.Attributes). I've used both but I usually choose XML files simply as a matter of personal preference. Either method works well and both provide many options for defining the relationship between class and table and configuring it's function. I'll be using XML files in this tutorial but may work in some mapping attributes later in the process.

To get intellisense working with the mapping files you can copy the nhibernate-*.xsd files from the NHibernate source (NHibernate\src\NHibernate\) to C:\Program Files\Microsoft Visual Studio 8\Xml\Schemas (or wherever you installed VS). There are a few tools that can help by generating the mapping files based on an existing database schema, one that I've had the most success with is MyGeneration (try the template by lujan99).

As I go through each mapping I'll point out how certain features work but for detailed information on the available options check the official documentation here. Each of these mapping files will follow the naming convention classname.hbm.xml as this is what NHibernate expects to find when the SessionFactory is initialized (more on this in Part IV).

BlogPost mapping:

<?xml version="1.0" encoding="utf-8"?> <hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="NHBlog.Domain" namespace="NHBlog.Domain"> <class name="BlogPost" table="BlogPost"> <id name="ID" column="ID" type="int"> <generator class="native" /> </id> <property name="Title" column="Title" type="string" not-null="true"></property> <property name="Body" column="Body" type="string" not-null="true"></property> <property name="PublishedOn" column="PublishedOn" type="DateTime"></property> <many-to-one name="PublishedBy" column="PublishedByID" class="BlogUser" not-null="true" /> <bag name="Comments" cascade="delete" inverse="true" > <key column="BlogPostID" /> <one-to-many class="Comment" /> <loader query-ref="GetCommentsByBlogPostID"/> </bag> </class> <sql-query name="GetCommentsByBlogPostID"> <load-collection alias="Comments" role="BlogPost.Comments" /> exec GetCommentsByBlogPostID :blogPostID </sql-query> </hibernate-mapping>

At the beginning of the file I'm setting the assembly and namespace values. They aren't required, but if they are not set you will need to fully qualify any class names used including the assembly ( i.e., NHBlog.Domain.BlogPost, NHBlog.Domain). The class element tells NHibernate what the name of the class is and which table that class maps to, in this case both are named BlogPost. The id element defines the primary key of the table and which property in the class it maps to. It's also includes the type (.net data type) and which class is generating these values. NHibernate includes many different generator classes. In our example we are using the identity function in SQL Server so the generator is set to native.

Each BlogPost will also have a collection of Comments seen here mapped using the bag element. This mapping is a bit different than normal in that the<loader query-ref="GetCommentsByBlogPostID"/> attribute specifies which query to use to load the collection of comments, in this case a stored procedure. At the bottom of the file a sql-query is defined to execute the stored procedure GetCommentsByBlogPostID and pass in the value blogPostID. The load-collection element instructs NHibernate what type of entities to expect as the result of this query.

Why am I using a stored procedure here? I don't have to, I could load the collection like any other but doing it this way serves two purposes; to demonstrate the use of stored procedures (a new feature in NHibernate 1.2), and to assist in loading the comments in a threaded conversational manner (see the requirements in Part II). GetCommentsByBlogPost uses a feature in Sql Server 2005 (and Sql Express 2005) called Common Table Expressions. More information can be found here.

BlogUser mapping:

<?xml version="1.0" encoding="utf-8"?> <hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="NHBlog.Domain" namespace="NHBlog.Domain"> <class name="BlogUser" table="BlogUser"> <id name="ID" column="ID" type="int"> <generator class="native" /> </id> <property name="FirstName" column="FirstName" type="string" not-null="true"></property> <property name="LastName" column="LastName" type="string" not-null="true"></property> <property name="Alias" column="Alias" type="string"></property> <property name="EmailAddress" column="EmailAddress" type="string" not-null="true"></property> <property name="CreatedOn" column="CreatedOn" type="DateTime"></property> <bag name="BlogPosts"> <key column="PublishedByID" /> <one-to-many class="BlogPost" /> </bag> <bag name="Comments"> <key column="MadeByID" /> <one-to-many class="Comment" /> </bag> <bag name="BlogRoles" table="UserRole"> <key column="BlogUserID" /> <many-to-many class="BlogRole" column="BlogRoleID" /> </bag> </class> </hibernate-mapping>

In BlogUser we have three collections mapped; BlogPosts, Comments, and BlogRoles. The first two are one-to-many relationships meaning that a single BlogUser can have posted many BlogPosts and made many Comments. The last is a many-to-many relationship meaning that a BlogUser can belong to many BlogRoles and a BlogRole can contain many BlogUsers. The table UserRole defines this relationship in the database. The mapping instructs NHibernate what type of class makes up this collection, which table to use to look up the collection members and which column holds the key for each.

BlogRole mapping:

BlogRole has a collection of BlogUsers which represents the other side of the many-to-many relationship defined in BlogUser.

Comment mapping:

<?xml version="1.0" encoding="utf-8"?> <hibernate-mapping xmlns="urn:nhibernate-mapping-2.2" assembly="NHBlog.Domain" namespace="NHBlog.Domain"> <class name="Comment" table="Comment"> <id name="ID" column="ID" type="int"> <generator class="native" /> </id> <property name="Subject" column="Subject" type="string" not-null="true"></property> <property name="Body" column="Body" type="string" not-null="true"></property> <property name="MadeOn" column="MadeOn" type="DateTime"></property> <many-to-one name="MadeBy" column="MadeByID" class="BlogUser" not-null="true" /> <many-to-one name="InReplyTo" column="InReplyToID" class="Comment" /> <many-to-one name="BlogPost" column="BlogPostID" class="BlogPost" not-null="true" /> <bag name="Replies"> <key column="InReplyToID" /> <one-to-many class="Comment" /> </bag> <property name="IsVisible" column="IsVisible" type="Boolean"></property> <property name="Depth" column="Depth" type="int" insert="false" update="false"></property> <loader query-ref="GetCommentByID"/> </class> <sql-query name="GetCommentByID"> <return class="Comment"></return> exec GetCommentByID :id </sql-query> </hibernate-mapping>

A Comment has a reference to the BlogUser who made it (MadeBy), the Comment it is replying to (InReplyTo), if any, the BlogPost it is a comment on (BlogPost), and a collection of comments replying to it (Replies). Also, notice the "Depth" property doesn't allow inserting or updating of this value. That's because this value/column doesn't actually exist in the database, it's generated when loading a collection of comments. If you load an individual Comment this value will always be zero. This mapping is also using a stored procedure but in this case it will be used when loading a comment by id.

GetCommentsByBlogPostID stored procedure code:

CREATE PROCEDURE [dbo].[GetCommentsByBlogPostID] ( @blogPostID int = 0 ) AS SET NOCOUNT ON; WITH CommentList ( ID, [Subject], Body, MadeOn, MadeByID, InReplyToID, BlogPostID, IsVisible, Depth, sortcol) AS ( SELECT ID, [Subject], Body, MadeOn, MadeByID, InReplyToID, BlogPostID, IsVisible, 0, CAST(ID AS VARBINARY(900)) FROM Comment WHERE (InReplyToID IS NULL) AND (BlogPostID = @blogPostID) UNION ALL SELECT c.ID, c.Subject, c.Body, c.MadeOn, c.MadeByID, c.InReplyToID, c.BlogPostID, c.IsVisible, cl.depth + 1, CAST(cl.sortcol + CAST(c.ID AS BINARY(4)) AS VARBINARY(900)) FROM Comment AS c INNER JOIN CommentList AS cl ON c.InReplyToID = cl.ID) SELECT ID, [Subject], Body, MadeOn, MadeByID, InReplyToID, BlogPostID, IsVisible, Depth FROM CommentList ORDER BY sortcol RETURN

GetCommentByID stored procedure code:

CREATE PROCEDURE dbo.GetCommentByID( @id int ) AS SET NOCOUNT ON SELECT ID, Subject, Body, MadeOn, MadeByID, InReplyToID, BlogPostID, IsVisible, 0 as Depth FROM Comment WHERE ID = @id RETURN

In Part IV we will configure NHibernate and begin building the supporting framework needed to use what we have done so far.

Getting Started with NHibernate: Part II

anortham — Wed, 23 May 2007 01:26:00 GMT

While writing the code necessary for this installment, I found myself falling prey to feature-creep. So I've decided to keep it fairly simple in the beginning. However, once the basic components are working I'll start introducing more features. I thought this might be a good way to demonstrate what is and isn't required to add new functionality to a working NHibernate application.

The application's initial functionality will consist of blog users being able to post new blog posts, comment on posts, and reply to other comments. Only users with the correct role membership will be able to post, all users will be able to comment and reply to comments. Also, the comments should be threaded so conversations can be followed more easily.

The domain model has just 4 classes (for now):

The Sql Express 2005 database will have 5 tables persisting our 4 classes. The extra database table UserRole will persist the many-to-many relationship between BlogUser and BlogRole.

Also notice that the "Depth" property in the Comment class is not actually persisted, it is a read-only value that is generated when a collection of comments for a BlogPost is loaded and represents the level of the comment in the comment hierarchy (threaded convesations!). See the attachment for the database script.

In Part III we will create the mapping glue that binds the model and database together.

Getting Started with NHibernate: Part I

anortham — Sun, 20 May 2007 02:22:00 GMT

When I first started learning and using NHibernate, I read every tutorial, downloaded every example, and studied every code snippet I could get my hands on. There are some great resources available with one of the best being Billy McCafferty's NHibernate Best Practices.

In my opinion, the majority of the resources available fall into one of three categories:

Articles that expect and require some familiarity with NHibernate.
Articles or snippets/sample code that are written at such a low level, you're left wondering how the technique demonstrated would be implemented in real world code.
Open source code that dissecting and learning from would be a daunting and tedious task for users new to the concept of NHibernate.

Each of the resources I refer to provide a lot of useful information. However, I like to learn by doing and I think a tutorial that provides a step by step guide to implementing NHibernate in a real world application would be beneficial to a lot of prospective NHibernate users.

In an attempt to fill this void, this is the first article in a series of many. Each article will cover a bite-sized (byte-sized?) step in the process as we design and implement a blog. We will finish with an application that is simple enough that we don't get bogged down in unrelated topics but complex enough that in the end we will have a framework that can be used as the foundation for future projects.

In Part II we will build our domain classes.